forked from enlightenment/efl
474 lines
22 KiB
Plaintext
474 lines
22 KiB
Plaintext
mixin Efl.Gfx.Mapping requires 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 {
|
|
mapping_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.]]
|
|
}
|
|
mapping_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. @.mapping_has will then return $false. This function will
|
|
not modify the values of @.mapping_smooth or @.mapping_alpha.
|
|
]]
|
|
}
|
|
@property mapping_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 mapping_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 mapping_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 mapping_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 @.mapping_smooth depending on which
|
|
algorithm is used for anti-aliasing.
|
|
]]
|
|
values {
|
|
alpha: bool; [[$true by default.]]
|
|
}
|
|
}
|
|
@property mapping_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 mapping_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 mapping_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.]]
|
|
}
|
|
}
|
|
lighting_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.]]
|
|
}
|
|
}
|
|
lighting_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 @.lighting_3d for a pivot-based lighting
|
|
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;
|
|
}
|
|
}
|