path: root/src/lib/evas/canvas/efl_gfx_map.eo

mixin Efl.Gfx.Map (Efl.Interface, Efl.Object)
{
   [[Texture UV mapping for all objects (rotation, perspective, 3d, ...).

     Evas allows different transformations to be applied to all kinds of
     objects. These are applied by means of UV mapping.

     With UV mapping, one maps points in the source object to a 3D space
     positioning at target. This allows rotation, perspective, scale and
     lots of other effects, depending on the map that is used.

     Each map point may carry a multiplier color. If properly calculated,
     these can do shading effects on the object, producing 3D effects.

     At the moment of writing, maps can only have 4 points (no more, no less).

     @since 1.20
   ]]
   methods {
      map_has {
         [[Read-only property indicating whether an object is mapped.

           This will be $true if any transformation is applied to this object.
         ]]
         return: bool; [[$true if the object is mapped.]]
      }
      map_reset {
         [[Resets the map transformation to its default state.

           This will reset all transformations to identity, meaning the points'
           colors, positions and UV coordinates will be reset to their default
           values. @.map_has will then return $false. This function will
           not modify the values of @.map_smooth or @.map_alpha.
         ]]
      }
      @property map_point_count {
         [[Number of points of a map.

            This sets the number of points of map.
            Currently, the number of points must be multiples of 4.
         ]]
         values {
            count: int; [[The number of points of map]]
         }
      }
      @property map_clockwise {
         [[Clockwise state of a map (read-only).

           This determines if the output points (X and Y. Z is not used) are
           clockwise or counter-clockwise. This can be used for "back-face
           culling". This is where you hide objects that "face away" from you.
           In this case objects that are not clockwise.
         ]]
         get {}
         values {
            cw: bool; [[$true if clockwise, $false if counter clockwise]]
         }
      }

      // FIXME: This needs modes such as "default", "smooth", "fast", "fastest"
      // In SW: default, fast and fastest are not smooth
      // In GL: All but fastest are smooth
      // Same remark for alpha - it's only for performance
      // Same remark for (MISSING) anti-aliasing

      @property map_smooth {
         [[Smoothing state for map rendering.

           This sets smoothing for map rendering. If the object is a type that has
           its own smoothing settings, then both the smooth settings for this object
           and the map must be turned off. By default smooth maps are enabled.
         ]]
         values {
            smooth: bool; [[$true by default.]]
         }
      }
      @property map_alpha {
         [[Alpha flag for map rendering.

           This sets alpha flag for map rendering. If the object is a type that
           has its own alpha settings, then this will take precedence. Only
           image objects support this currently (@Efl.Canvas.Image and its
           friends). Setting this to off stops alpha blending of the map area,
           and is useful if you know the object and/or all sub-objects is 100%
           solid.

           Note that this may conflict with @.map_smooth depending on which
           algorithm is used for anti-aliasing.
         ]]
         values {
            alpha: bool; [[$true by default.]]
         }
      }
      @property map_coord_absolute {
         [[A point's absolute coordinate on the canvas.

           This sets/gets the fixed point's coordinate in the map. Note that points
           describe the outline of a quadrangle and are ordered either clockwise
           or counter-clockwise. Try to keep your quadrangles concave and
           non-complex. Though these polygon modes may work, they may not render
           a desired set of output. The quadrangle will use points 0 and 1 , 1 and 2,
           2 and 3, and 3 and 0 to describe the edges of the quadrangle.

           The X and Y and Z coordinates are in canvas units. Z is optional and may
           or may not be honored in drawing. Z is a hint and does not affect the
           X and Y rendered coordinates. It may be used for calculating fills with
           perspective correct rendering.

           Remember all coordinates are canvas global ones as with move and resize
           in the canvas.

           This property can be read to get the 4 points positions on the
           canvas, or set to manually place them.
         ]]
         keys {
            idx: int; [[ID of the point, from 0 to 3 (included).]]
         }
         values {
            x: double; [[Point X coordinate in absolute pixel coordinates.]]
            y: double; [[Point Y coordinate in absolute pixel coordinates.]]
            z: double; [[Point Z coordinate hint (pre-perspective transform).]]
         }
      }
      @property map_uv {
         [[Map point's U and V texture source point.

           This sets/gets the U and V coordinates for the point. This determines
           which coordinate in the source image is mapped to the given point,
           much like OpenGL and textures. Valid values range from 0.0 to 1.0.

           By default the points are set in a clockwise order, as such:
           - 0: top-left, i.e. (0.0, 0.0),
           - 1: top-right, i.e. (1.0, 0.0),
           - 2: bottom-right, i.e. (1.0, 1.0),
           - 3: bottom-left, i.e. (0.0, 1.0).
         ]]
         keys {
            idx: int; [[ID of the point, from 0 to 3 (included).]]
         }
         values {
            u: double; [[Relative X coordinate within the image, from 0 to 1.]]
            v: double; [[Relative Y coordinate within the image, from 0 to 1.]]
         }
      }
      @property map_color {
         [[Color of a vertex in the map.

           This sets the color of the vertex in the map. Colors will be linearly
           interpolated between vertex points through the map. Color will multiply
           the "texture" pixels (like GL_MODULATE in OpenGL). The default color of
           a vertex in a map is white solid (255, 255, 255, 255) which means it will
           have no affect on modifying the texture pixels.

           The color values must be premultiplied (ie. $a >= {$r, $g, $b}).
         ]]
         keys {
            idx: int; [[ID of the point, from 0 to 3 (included).
                        -1 can be used to set the color for all points,
                        but it is invalid for get().]]
         }
         values {
            r: int; [[Red (0 - 255)]]
            g: int; [[Green (0 - 255)]]
            b: int; [[Blue (0 - 255)]]
            a: int; [[Alpha (0 - 255)]]
         }
      }
      translate {
         [[Apply a translation to the object using map.

           This does not change the real geometry of the object but will affect
           its visible position.
         ]]
         params {
            dx: double; [[Distance in pixels along the X axis.]]
            dy: double; [[Distance in pixels along the Y axis.]]
            dz: double; [[Distance in pixels along the Z axis.]]
         }
      }

      // Transformations with a relative coordinates pivot
      // FIXME: pivot & center need to be optional, but double(0.5) doesn't work!
      rotate {
         [[Apply a rotation to the object.

           This rotates the object clockwise by $degrees degrees, around the
           center specified by the relative position ($cx, $cy) in the $pivot
           object. If $pivot is $null then this object is used as its own pivot
           center. 360 degrees is a full rotation, equivalent to no rotation.
           Negative values for $degrees will rotate clockwise by that amount.

           The coordinates are set relative to the given $pivot object. If its
           geometry changes, then the absolute position of the rotation center
           will change accordingly.

           By default, the center is at (0.5, 0.5). 0.0 means left or top while
           1.0 means right or bottom of the $pivot object.
         ]]
         params {
            degrees: double; [[CCW rotation in degrees.]]
            pivot: const(Efl.Gfx.Entity); [[A pivot object for the center point, can be $null.]]
            cx: double; [[X relative coordinate of the center point.]]
            cy: double; [[y relative coordinate of the center point.]]
         }
      }
      rotate_3d {
         [[Rotate the object around 3 axes in 3D.

           This will rotate in 3D, not just around the "Z" axis as is the case
           with @.rotate. You can rotate around the X, Y and Z axes. The
           Z axis points "into" the screen with low values at the screen and
           higher values further away. The X axis runs from left to right on
           the screen and the Y axis from top to bottom.

           As with @.rotate, you provide a pivot and center point to rotate
           around (in 3D). The Z coordinate of this center point is an absolute
           value, and not a relative one like X and Y, as objects are flat in a
           2D space.
         ]]
         params {
            dx: double; [[Rotation in degrees around X axis (0 to 360).]]
            dy: double; [[Rotation in degrees around Y axis (0 to 360).]]
            dz: double; [[Rotation in degrees around Z axis (0 to 360).]]
            pivot: const(Efl.Gfx.Entity); [[A pivot object for the center point, can be $null.]]
            cx: double; [[X relative coordinate of the center point.]]
            cy: double; [[y relative coordinate of the center point.]]
            cz: double; [[Z absolute coordinate of the center point.]]
         }
      }
      rotate_quat {
         [[Rotate the object in 3D using a unit quaternion.

           This is similar to @.rotate_3d but uses a unit quaternion (also
           known as versor) rather than a direct angle-based rotation around a
           center point. Use this to avoid gimbal locks.

           As with @.rotate, you provide a pivot and center point to rotate
           around (in 3D). The Z coordinate of this center point is an absolute
           value, and not a relative one like X and Y, as objects are flat in a
           2D space.
         ]]
         params {
            qx: double; [[The x component of the imaginary part of the quaternion.]]
            qy: double; [[The y component of the imaginary part of the quaternion.]]
            qz: double; [[The z component of the imaginary part of the quaternion.]]
            qw: double; [[The w component of the real part of the quaternion.]]
            pivot: const(Efl.Gfx.Entity); [[A pivot object for the center point, can be $null.]]
            cx: double; [[X relative coordinate of the center point.]]
            cy: double; [[y relative coordinate of the center point.]]
            cz: double; [[Z absolute coordinate of the center point.]]
         }
      }
      zoom {
         [[Apply a zoom to the object.

           This zooms the points of the map from a center point. That center is
           defined by $cx and $cy. The $zoomx and $zoomy parameters specify how
           much to zoom in the X and Y direction respectively.
           A value of 1.0 means "don't zoom". 2.0 means "double the size". 0.5 is
           "half the size" etc.

           By default, the center is at (0.5, 0.5). 0.0 means left or top while
           1.0 means right or bottom.
         ]]
         params {
            zoomx: double; [[Zoom in X direction]]
            zoomy: double; [[Zoom in Y direction]]
            pivot: const(Efl.Gfx.Entity); [[A pivot object for the center point, can be $null.]]
            cx: double; [[X relative coordinate of the center point.]]
            cy: double; [[y relative coordinate of the center point.]]
         }
      }
      lightning_3d {
         [[Apply a lighting effect on the object.

           This is used to apply lighting calculations (from a single light
           source) to a given mapped object. The R, G and B values of each
           vertex will be modified to reflect the lighting based on the light
           point coordinates, the light color and the ambient color, and at
           what angle the map is facing the light source. A surface should have
           its points be declared in a clockwise fashion if the face is
           "facing" towards you (as opposed to away from you) as faces have a
           "logical" side for lighting.

           The coordinates are set relative to the given $pivot object. If its
           geometry changes, then the absolute position of the rotation center
           will change accordingly. The Z position is absolute. If the $pivot
           is $null then this object will be its own pivot.
         ]]
         params {
            pivot: const(Efl.Gfx.Entity); [[A pivot object for the light point, can be $null.]]
            lx: double; [[X relative coordinate in space of light point.]]
            ly: double; [[Y relative coordinate in space of light point.]]
            lz: double; [[Z absolute coordinate in space of light point.]]
            lr: int; [[Light red value (0 - 255).]]
            lg: int; [[Light green value (0 - 255).]]
            lb: int; [[Light blue value (0 - 255).]]
            ar: int; [[Ambient color red value (0 - 255).]]
            ag: int; [[Ambient color green value (0 - 255).]]
            ab: int; [[Ambient color blue value (0 - 255).]]
         }
      }
      perspective_3d {
         [[Apply a perspective transform to the map

           This applies a given perspective (3D) to the map coordinates. X, Y and Z
           values are used. The px and py points specify the "infinite distance" point
           in the 3D conversion (where all lines converge to like when artists draw
           3D by hand). The $z0 value specifies the z value at which there is a 1:1
           mapping between spatial coordinates and screen coordinates. Any points
           on this z value will not have their X and Y values modified in the transform.
           Those further away (Z value higher) will shrink into the distance, and
           those under this value will expand and become bigger. The $foc value
           determines the "focal length" of the camera. This is in reality the distance
           between the camera lens plane itself (at or closer than this rendering
           results are undefined) and the "z0" z value. This allows for some "depth"
           control and $foc must be greater than 0.

           The coordinates are set relative to the given $pivot object. If its
           geometry changes, then the absolute position of the rotation center
           will change accordingly. The Z position is absolute. If the $pivot
           is $null then this object will be its own pivot.
         ]]
         params {
            pivot: const(Efl.Gfx.Entity); [[A pivot object for the infinite point, can be $null.]]
            px: double; [[The perspective distance X relative coordinate.]]
            py: double; [[The perspective distance Y relative coordinate.]]
            z0: double; [[The "0" Z plane value.]]
            foc: double; [[The focal distance, must be greater than 0.]]
         }
      }

      // Transformations with an absolute center
      rotate_absolute {
         [[Apply a rotation to the object, using absolute coordinates.

           This rotates the object clockwise by $degrees degrees, around the
           center specified by the relative position ($cx, $cy) in the $pivot
           object. If $pivot is $null then this object is used as its own pivot
           center. 360 degrees is a full rotation, equivalent to no rotation.
           Negative values for $degrees will rotate clockwise by that amount.

           The given coordinates are absolute values in pixels. See also
           @.rotate for a relative coordinate version.
         ]]
         params {
            degrees: double; [[CCW rotation in degrees.]]
            cx: double; [[X absolute coordinate in pixels of the center point.]]
            cy: double; [[y absolute coordinate in pixels of the center point.]]
         }
      }
      rotate_3d_absolute {
         [[Rotate the object around 3 axes in 3D, using absolute coordinates.

           This will rotate in 3D and not just around the "Z" axis as the case
           with @.rotate. This will rotate around the X, Y and Z axes. The
           Z axis points "into" the screen with low values at the screen and
           higher values further away. The X axis runs from left to right on
           the screen and the Y axis from top to bottom.

           The coordinates of the center point are given in absolute canvas
           coordinates. See also @.rotate_3d for a pivot-based 3D rotation.
         ]]
         params {
            dx: double; [[Rotation in degrees around X axis (0 to 360).]]
            dy: double; [[Rotation in degrees around Y axis (0 to 360).]]
            dz: double; [[Rotation in degrees around Z axis (0 to 360).]]
            cx: double; [[X absolute coordinate in pixels of the center point.]]
            cy: double; [[y absolute coordinate in pixels of the center point.]]
            cz: double; [[Z absolute coordinate of the center point.]]
         }
      }
      rotate_quat_absolute {
         [[Rotate the object in 3D using a unit quaternion, using absolute
           coordinates.

           This is similar to @.rotate_3d but uses a unit quaternion (also
           known as versor) rather than a direct angle-based rotation around a
           center point. Use this to avoid gimbal locks.

           The coordinates of the center point are given in absolute canvas
           coordinates. See also @.rotate_quat for a pivot-based 3D rotation.
         ]]
         params {
            qx: double; [[The x component of the imaginary part of the quaternion.]]
            qy: double; [[The y component of the imaginary part of the quaternion.]]
            qz: double; [[The z component of the imaginary part of the quaternion.]]
            qw: double; [[The w component of the real part of the quaternion.]]
            cx: double; [[X absolute coordinate in pixels of the center point.]]
            cy: double; [[y absolute coordinate in pixels of the center point.]]
            cz: double; [[Z absolute coordinate of the center point.]]
         }
      }
      zoom_absolute {
         [[Apply a zoom to the object, using absolute coordinates.

           This zooms the points of the map from a center point. That center is
           defined by $cx and $cy. The $zoomx and $zoomy parameters specify how
           much to zoom in the X and Y direction respectively.
           A value of 1.0 means "don't zoom". 2.0 means "double the size". 0.5 is
           "half the size" etc.

           The coordinates of the center point are given in absolute canvas
           coordinates. See also @.zoom for a pivot-based zoom.
         ]]
         params {
            zoomx: double; [[Zoom in X direction]]
            zoomy: double; [[Zoom in Y direction]]
            cx: double; [[X absolute coordinate in pixels of the center point.]]
            cy: double; [[y absolute coordinate in pixels of the center point.]]
         }
      }
      lightning_3d_absolute {
         [[Apply a lighting effect to the object.

           This is used to apply lighting calculations (from a single light
           source) to a given mapped object. The RGB values of each
           vertex will be modified to reflect the lighting based on the light
           point coordinates, the light color, the ambient color and at
           what angle the map is facing the light source. A surface should have
           its points be declared in a clockwise fashion if the face is
           "facing" towards you (as opposed to away from you) as faces have a
           "logical" side for lighting.

           The coordinates of the center point are given in absolute canvas
           coordinates. See also @.lightning_3d for a pivot-based lightning
           effect.
         ]]
         params {
            lx: double; [[X absolute coordinate in pixels of the light point.]]
            ly: double; [[y absolute coordinate in pixels of the light point.]]
            lz: double; [[Z absolute coordinate in space of light point.]]
            lr: int; [[Light red value (0 - 255).]]
            lg: int; [[Light green value (0 - 255).]]
            lb: int; [[Light blue value (0 - 255).]]
            ar: int; [[Ambient color red value (0 - 255).]]
            ag: int; [[Ambient color green value (0 - 255).]]
            ab: int; [[Ambient color blue value (0 - 255).]]
         }
      }
      perspective_3d_absolute {
         [[Apply a perspective transform to the map

           This applies a given perspective (3D) to the map coordinates. X, Y and Z
           values are used. The px and py points specify the "infinite distance" point
           in the 3D conversion (where all lines converge to like when artists draw
           3D by hand). The $z0 value specifies the z value at which there is a 1:1
           mapping between spatial coordinates and screen coordinates. Any points
           on this z value will not have their X and Y values modified in the transform.
           Those further away (Z value higher) will shrink into the distance, and
           those less than this value will expand and become bigger. The $foc value
           determines the "focal length" of the camera. This is in reality the distance
           between the camera lens plane itself (at or closer than this rendering
           results are undefined) and the "z0" z value. This allows for some "depth"
           control and $foc must be greater than 0.

           The coordinates of the center point are given in absolute canvas
           coordinates. See also @.perspective_3d for a pivot-based perspective
           effect.
         ]]
         params {
            px: double; [[The perspective distance X relative coordinate.]]
            py: double; [[The perspective distance Y relative coordinate.]]
            z0: double; [[The "0" Z plane value.]]
            foc: double; [[The focal distance, must be greater than 0.]]
         }
      }
   }
   implements {
      Efl.Object.constructor;
      Efl.Object.destructor;
   }
}