aboutsummaryrefslogtreecommitdiffstats
path: root/src/lib/evas/canvas/efl_gfx_map.eo
diff options
context:
space:
mode:
authorJean-Philippe Andre <jp.andre@samsung.com>2017-04-26 15:11:51 +0900
committerJean-Philippe Andre <jp.andre@samsung.com>2017-05-11 17:54:00 +0900
commit0a224da86fe1602a2045fac55cb6457c71d81b88 (patch)
tree46d5c3bab9a14f9849a3a323c5b349b288a8b930 /src/lib/evas/canvas/efl_gfx_map.eo
parentevas map: Replace EO APIs for populate with reset (diff)
downloadefl-0a224da86fe1602a2045fac55cb6457c71d81b88.tar.gz
evas map: Introduce new API for maps (Efl.Gfx.Map)
This implements an entirely new API model for Evas Map by relying on high-level transformations on the object rather than an external Evas_Map structure that needs to be constantly updated manually. The implementation relies on Evas_Map. To rotate an object all you need to do now is efl_gfx_map_rotate(obj, 45.0, NULL, 0.5, 0.5); Or with a C++ syntax: obj.rotate(45.0, NULL, 0.5, 0.5); Or even simply (with default arguments): obj.rotate(45.0); The map transformation functions are: - rotate - rotate_3d - rotate_quat - zoom - translate (new!) - perspective_3d - lightning_3d @feature
Diffstat (limited to 'src/lib/evas/canvas/efl_gfx_map.eo')
-rw-r--r--src/lib/evas/canvas/efl_gfx_map.eo294
1 files changed, 155 insertions, 139 deletions
diff --git a/src/lib/evas/canvas/efl_gfx_map.eo b/src/lib/evas/canvas/efl_gfx_map.eo
index 720a972875..15f7449c65 100644
--- a/src/lib/evas/canvas/efl_gfx_map.eo
+++ b/src/lib/evas/canvas/efl_gfx_map.eo
@@ -9,55 +9,37 @@ mixin Efl.Gfx.Map (Efl.Interface, Efl.Object)
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.
+ 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).
- Note: For now this mixin is only compatible with $Efl.Canvas.Object and
- shouldn't be used anywhere else.
+ @since 1.20
]]
- data: null;
methods {
- @property map_enable @pure_virtual {
- [[Whether map transformation is enabled on this object.
+ map_has {
+ [[Read-only property indicating whether an object is mapped.
- The default map enable state is off ($false). The other
- properties and methods in this class have no effect until
- this property is enabled.
+ This will be $true if any transformation is applied to this object.
]]
- set {
- [[Enable or disable the use of map for this object. On
- enable, the object geometry will be saved, and the new
- geometry will change (position and size) to reflect the
- map geometry set.
- ]]
- }
- get {
- legacy: evas_object_map_enable_get;
- }
- values {
- enabled: bool; [[Enabled state.]]
- }
+ 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. This does not reset the @.map_enable flag.
-
- @since 1.20
+ values. @.map_has will then return $false. This function will
+ not modify the values of @.map_smooth or @.map_alpha.
]]
}
@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.
+ 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 {
@@ -78,18 +60,22 @@ mixin Efl.Gfx.Map (Efl.Interface, Efl.Object)
@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
- have this currently ($Efl.Canvas.Image and its friends).
- Setting this off stops alpha blending of the map area, and is
- useful if you know the object and/or all sub-objects is 100% solid.
+ 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 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_point_coord {
- [[Map point's coordinate.
+ @property map_raw_coord {
+ [[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
@@ -105,31 +91,39 @@ mixin Efl.Gfx.Map (Efl.Interface, Efl.Object)
Remember all coordinates are canvas global ones like with move and resize
in the canvas.
+
+ This function should rarely be used as it overrides any other
+ transformation set. 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.]]
- y: double; [[Point Y Coordinate.]]
- z: double; [[Point Z Coordinate hint (pre-perspective transform).]]
+ 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_point_image_uv {
+ @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. Notes that these points do select the pixel, but
- are double floating point values to allow for accuracy and sub-pixel
- selection.
+ 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; [[X coordinate within the image/texture source.]]
- v: double; [[Y coordinate within the image/texture source.]]
+ 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 {
@@ -155,102 +149,131 @@ mixin Efl.Gfx.Map (Efl.Interface, Efl.Object)
a: int; [[Alpha (0 - 255)]]
}
}
- @property map_move_sync {
- [[Status of object move synchronization for map rendering.
+ // FIXME: pivot & center need to be optional, but double(0.5) doesn't work!
+ rotate {
+ [[Apply a rotation to the object.
- If the flag is set as enabled, the map will be moved as the object
- is moved.
- ]]
- values {
- enable: bool; [[$true by default.]]
- }
- }
- map_rotate {
- [[Change the map to apply the given rotation.
-
- This rotates the indicated map's coordinates around the center coordinate
- given by $cx and $cy as the rotation center. The points will have their
- X and Y coordinates rotated clockwise by $degrees degrees (360.0 is a
- full rotation). Negative values for degrees will rotate counter-clockwise
- by that amount. All coordinates are canvas global 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 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.]]
- cx: double; [[X coordinate of the rotation center.]]
- cy: double; [[Y coordinate of the rotation center.]]
+ pivot: Efl.Gfx; [[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.]]
}
- return: bool; [[$false in case of error.]]
}
- map_zoom {
- [[Change the map to apply the given zooming.
+ rotate_3d {
+ [[Rotate the object around 3 axes in 3D.
- Like evas_map_util_rotate(), 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. All coordinates are canvas global coordinates.
- ]]
- params {
- zoomx: double; [[Zoom in X direction]]
- zoomy: double; [[Zoom in Y direction]]
- cx: double; [[X coordinate of the center point.]]
- cy: double; [[Y coordinate of the center point.]]
- }
- return: bool; [[$false in case of error.]]
- }
- map_rotate_3d {
- [[Rotate the map around 3 axes in 3D
-
- This will rotate not just around the "Z" axis as in evas_map_util_rotate()
- (which is a convenience call for those only wanting 2D). 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. Like with
- evas_map_util_rotate() you provide a center point to rotate around (in 3D).
+ 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.
+
+ 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).]]
- cx: double; [[Rotation's center X position.]]
- cy: double; [[Rotation's center Y position.]]
- cz: double; [[Rotation's center Z position.]]
+ pivot: Efl.Gfx; [[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.]]
}
- return: bool; [[$false in case of error.]]
}
- map_quat_rotate {
- [[Rotate the map in 3D using a unit quaternion.
+ 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.
- This will rotate in 3D using a unit quaternion. Like with
- evas_map_util_3d_rotate() you provide a center point
- to rotate around (in 3D).
+ 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.]]
- cx: double; [[Rotation's center x.]]
- cy: double; [[Rotation's center y.]]
- cz: double; [[Rotation's center z.]]
+ pivot: Efl.Gfx; [[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.]]
}
- return: bool; [[$false in case of error.]]
}
- map_lightning_3d {
- [[Perform lighting calculations on the given Map
-
- This is used to apply lighting calculations (from a single light source)
- to a given map. 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.
+ 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: Efl.Gfx; [[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.]]
+ }
+ }
+ 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 {
- lx: double; [[X coordinate in space of light point.]]
- ly: double; [[Y coordinate in space of light point.]]
- lz: double; [[Z coordinate in space of light point.]]
+ 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.]]
+ }
+ }
+ lightning_3d {
+ [[Apply a lightning 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: Efl.Gfx; [[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).]]
@@ -258,9 +281,8 @@ mixin Efl.Gfx.Map (Efl.Interface, Efl.Object)
ag: int; [[Ambient color green value (0 - 255).]]
ab: int; [[Ambient color blue value (0 - 255).]]
}
- return: bool; [[$false in case of error.]]
}
- map_perspective_3d {
+ perspective_3d {
[[Apply a perspective transform to the map
This applies a given perspective (3D) to the map coordinates. X, Y and Z
@@ -275,29 +297,23 @@ mixin Efl.Gfx.Map (Efl.Interface, Efl.Object)
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 {
- px: double; [[The perspective distance X coordinate]]
- py: double; [[The perspective distance Y coordinate]]
- z0: double; [[The "0" z plane value]]
- foc: double; [[The focal distance]]
+ pivot: Efl.Gfx; [[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.]]
}
- return: bool; [[$false in case of error.]]
- }
- map_dup {
- [[Duplicate the map information from another object.]]
- params {
- other: const(Efl.Gfx.Map); [[Map object to duplicate]]
- }
- return: bool; [[$false in case of error.]]
}
}
implements {
+ Efl.Object.constructor;
+ Efl.Object.destructor;
}
}
-
-
-// Porting notes:
-
-// Skipped APIs:
-// evas_map_util_object_move_sync_{set,get}