forked from enlightenment/efl
evas: Move evas_map APIs from common to legacy header
+ define Evas_Map struct in Evas_Legacy.h (not eo) Otherwise, just a simple cut & paste
This commit is contained in:
Jean-Philippe Andre
parent
6b8228ffbd
commit
a49bddd124
|
|
@ -1457,838 +1457,6 @@ EAPI const Evas_Device *evas_device_emulation_source_get(const Evas_Device *dev)
|
|||
* @ingroup Evas_Object_Group
|
||||
*/
|
||||
|
||||
/**
|
||||
* @defgroup Evas_Object_Group_Map UV Mapping (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.
|
||||
*
|
||||
* As usual, Evas provides both the raw and easy to use methods. The
|
||||
* raw methods allow developers to create their maps somewhere else,
|
||||
* possibly loading them from some file format. The easy to use methods
|
||||
* calculate the points given some high-level parameters such as
|
||||
* rotation angle, ambient light, and so on.
|
||||
*
|
||||
* @note applying mapping will reduce performance, so use with
|
||||
* care. The impact on performance depends on engine in
|
||||
* use. Software is quite optimized, but not as fast as OpenGL.
|
||||
*
|
||||
* @section sec-map-points Map points
|
||||
* @subsection subsec-rotation Rotation
|
||||
*
|
||||
* A map consists of a set of points, currently only four are supported. Each
|
||||
* of these points contains a set of canvas coordinates @c x and @c y that
|
||||
* can be used to alter the geometry of the mapped object, and a @c z
|
||||
* coordinate that indicates the depth of that point. This last coordinate
|
||||
* does not normally affect the map, but it's used by several of the utility
|
||||
* functions to calculate the right position of the point given other
|
||||
* parameters.
|
||||
*
|
||||
* The coordinates for each point are set with evas_map_point_coord_set().
|
||||
* The following image shows a map set to match the geometry of an existing
|
||||
* object.
|
||||
*
|
||||
* @image html map-set-map-points-1.png
|
||||
* @image rtf map-set-map-points-1.png
|
||||
* @image latex map-set-map-points-1.eps
|
||||
*
|
||||
* This is a common practice, so there are a few functions that help make it
|
||||
* easier.
|
||||
*
|
||||
* evas_map_util_points_populate_from_geometry() sets the coordinates of each
|
||||
* point in the given map to match the rectangle defined by the function
|
||||
* parameters.
|
||||
*
|
||||
* evas_map_util_points_populate_from_object() and
|
||||
* evas_map_util_points_populate_from_object_full() both take an object and
|
||||
* set the map points to match its geometry. The difference between the two
|
||||
* is that the first function sets the @c z value of all points to 0, while
|
||||
* the latter receives the value to set in said coordinate as a parameter.
|
||||
*
|
||||
* The following lines of code all produce the same result as in the image
|
||||
* above.
|
||||
* @code
|
||||
* evas_map_util_points_populate_from_geometry(m, 100, 100, 200, 200, 0);
|
||||
* // Assuming o is our original object
|
||||
* evas_object_move(o, 100, 100);
|
||||
* evas_object_resize(o, 200, 200);
|
||||
* evas_map_util_points_populate_from_object(m, o);
|
||||
* evas_map_util_points_populate_from_object_full(m, o, 0);
|
||||
* @endcode
|
||||
*
|
||||
* Several effects can be applied to an object by simply setting each point
|
||||
* of the map to the right coordinates. For example, a simulated perspective
|
||||
* could be achieve as follows.
|
||||
*
|
||||
* @image html map-set-map-points-2.png
|
||||
* @image rtf map-set-map-points-2.png
|
||||
* @image latex map-set-map-points-2.eps
|
||||
*
|
||||
* As said before, the @c z coordinate is unused here so when setting points
|
||||
* by hand, its value is of no importance.
|
||||
*
|
||||
* @image html map-set-map-points-3.png
|
||||
* @image rtf map-set-map-points-3.png
|
||||
* @image latex map-set-map-points-3.eps
|
||||
*
|
||||
* In all three cases above, setting the map to be used by the object is the
|
||||
* same.
|
||||
* @code
|
||||
* evas_object_map_set(o, m);
|
||||
* evas_object_map_enable_set(o, EINA_TRUE);
|
||||
* @endcode
|
||||
*
|
||||
* Doing things this way, however, is a lot of work that can be avoided by
|
||||
* using the provided utility functions, as described in the next section.
|
||||
*
|
||||
* @section map-utils Utility functions
|
||||
*
|
||||
* Utility functions take an already set up map and alter it to produce a
|
||||
* specific effect. For example, to rotate an object around its own center
|
||||
* you would need to take the rotation angle, the coordinates of each corner
|
||||
* of the object and do all the math to get the new set of coordinates that
|
||||
* need to be set in the map.
|
||||
*
|
||||
* Or you can use this code:
|
||||
* @code
|
||||
* evas_object_geometry_get(o, &x, &y, &w, &h);
|
||||
* m = evas_map_new(4);
|
||||
* evas_map_util_points_populate_from_object(m, o);
|
||||
* evas_map_util_rotate(m, 45, x + (w / 2), y + (h / 2));
|
||||
* evas_object_map_set(o, m);
|
||||
* evas_object_map_enable_set(o, EINA_TRUE);
|
||||
* evas_map_free(m);
|
||||
* @endcode
|
||||
*
|
||||
* Which will rotate the object around its center point in a 45 degree angle
|
||||
* in the clockwise direction, taking it from this
|
||||
*
|
||||
* @image html map-rotation-2d-1.png
|
||||
* @image rtf map-rotation-2d-1.png
|
||||
* @image latex map-rotation-2d-1.eps
|
||||
*
|
||||
* to this
|
||||
*
|
||||
* @image html map-rotation-2d-2.png
|
||||
* @image rtf map-rotation-2d-2.png
|
||||
* @image latex map-rotation-2d-2.eps
|
||||
*
|
||||
* Objects may be rotated around any other point just by setting the last two
|
||||
* paramaters of the evas_map_util_rotate() function to the right values. A
|
||||
* circle of roughly the diameter of the object overlaid on each image shows
|
||||
* where the center of rotation is set for each example.
|
||||
*
|
||||
* For example, this code
|
||||
* @code
|
||||
* evas_object_geometry_get(o, &x, &y, &w, &h);
|
||||
* m = evas_map_new(4);
|
||||
* evas_map_util_points_populate_from_object(m, o);
|
||||
* evas_map_util_rotate(m, 45, x + w - 20, y + h - 20);
|
||||
* evas_object_map_set(o, m);
|
||||
* evas_object_map_enable_set(o, EINA_TRUE);
|
||||
* evas_map_free(m);
|
||||
* @endcode
|
||||
*
|
||||
* produces something like
|
||||
*
|
||||
* @image html map-rotation-2d-3.png
|
||||
* @image rtf map-rotation-2d-3.png
|
||||
* @image latex map-rotation-2d-3.eps
|
||||
*
|
||||
* And the following
|
||||
* @code
|
||||
* evas_output_size_get(evas, &w, &h);
|
||||
* m = evas_map_new(4);
|
||||
* evas_map_util_points_populate_from_object(m, o);
|
||||
* evas_map_util_rotate(m, 45, w, h);
|
||||
* evas_object_map_set(o, m);
|
||||
* evas_object_map_enable_set(o, EINA_TRUE);
|
||||
* evas_map_free(m);
|
||||
* @endcode
|
||||
*
|
||||
* rotates the object around the center of the window
|
||||
*
|
||||
* @image html map-rotation-2d-4.png
|
||||
* @image rtf map-rotation-2d-4.png
|
||||
* @image latex map-rotation-2d-4.eps
|
||||
*
|
||||
* @subsection subsec-3d 3D Maps
|
||||
*
|
||||
* Maps can also be used to achieve the effect of 3-dimensionality. When doing
|
||||
* this, the @c z coordinate of each point counts, with higher values meaning
|
||||
* the point is further into the screen, and smaller values (negative, usually)
|
||||
* meaning the point is closer towards the user.
|
||||
*
|
||||
* Thinking in 3D also introduces the concept of back-face of an object. An
|
||||
* object is said to be facing the user when all its points are placed in a
|
||||
* clockwise fashion. The next image shows this, with each point showing the
|
||||
* with which is identified within the map.
|
||||
*
|
||||
* @image html map-point-order-face.png
|
||||
* @image rtf map-point-order-face.png
|
||||
* @image latex map-point-order-face.eps
|
||||
*
|
||||
* Rotating this map around the @c Y axis would leave the order of the points
|
||||
* in a counter-clockwise fashion, as seen in the following image.
|
||||
*
|
||||
* @image html map-point-order-back.png
|
||||
* @image rtf map-point-order-back.png
|
||||
* @image latex map-point-order-back.eps
|
||||
*
|
||||
* This way we can say that we are looking at the back face of the object.
|
||||
* This will have stronger implications later when we talk about lighting.
|
||||
*
|
||||
* To know if a map is facing towards the user or not it's enough to use
|
||||
* the evas_map_util_clockwise_get() function, but this is normally done
|
||||
* after all the other operations are applied on the map.
|
||||
*
|
||||
* @subsection subsec-3d-rot 3D rotation and perspective
|
||||
*
|
||||
* Much like evas_map_util_rotate(), there's the function
|
||||
* evas_map_util_3d_rotate() that transforms the map to apply a 3D rotation
|
||||
* to an object. As in its 2D counterpart, the rotation can be applied around
|
||||
* any point in the canvas, this time with a @c z coordinate too. The rotation
|
||||
* can also be around any of the 3 axis.
|
||||
*
|
||||
* Starting from this simple setup
|
||||
*
|
||||
* @image html map-3d-basic-1.png
|
||||
* @image rtf map-3d-basic-1.png
|
||||
* @image latex map-3d-basic-1.eps
|
||||
*
|
||||
* and setting maps so that the blue square to rotate on all axis around a
|
||||
* sphere that uses the object as its center, and the red square to rotate
|
||||
* around the @c Y axis, we get the following. A simple overlay over the image
|
||||
* shows the original geometry of each object and the axis around which they
|
||||
* are being rotated, with the @c Z one not appearing due to being orthogonal
|
||||
* to the screen.
|
||||
*
|
||||
* @image html map-3d-basic-2.png
|
||||
* @image rtf map-3d-basic-2.png
|
||||
* @image latex map-3d-basic-2.eps
|
||||
*
|
||||
* which doesn't look very real. This can be helped by adding perspective
|
||||
* to the transformation, which can be simply done by calling
|
||||
* evas_map_util_3d_perspective() on the map after its position has been set.
|
||||
* The result in this case, making the vanishing point the center of each
|
||||
* object:
|
||||
*
|
||||
* @image html map-3d-basic-3.png
|
||||
* @image rtf map-3d-basic-3.png
|
||||
* @image latex map-3d-basic-3.eps
|
||||
*
|
||||
* @section sec-color Color and lighting
|
||||
*
|
||||
* Each point in a map can be set to a color, which will be multiplied with
|
||||
* the objects own color and linearly interpolated in between adjacent points.
|
||||
* This is done with evas_map_point_color_set() for each point of the map,
|
||||
* or evas_map_util_points_color_set() to set every point to the same color.
|
||||
*
|
||||
* When using 3D effects, colors can be used to improve the looks of them by
|
||||
* simulating a light source. The evas_map_util_3d_lighting() function makes
|
||||
* this task easier by taking the coordinates of the light source and its
|
||||
* color, along with the color of the ambient light. Evas then sets the color
|
||||
* of each point based on the distance to the light source, the angle with
|
||||
* which the object is facing the light and the ambient light. Here, the
|
||||
* orientation of each point as explained before, becomes more important.
|
||||
* If the map is defined counter-clockwise, the object will be facing away
|
||||
* from the user and thus become obscured, since no light would be reflecting
|
||||
* from it.
|
||||
*
|
||||
* @image html map-light.png
|
||||
* @image rtf map-light.png
|
||||
* @image latex map-light.eps
|
||||
* @note Object facing the light source
|
||||
*
|
||||
* @image html map-light2.png
|
||||
* @image rtf map-light2.png
|
||||
* @image latex map-light2.eps
|
||||
* @note Same object facing away from the user
|
||||
*
|
||||
* @section Image mapping
|
||||
*
|
||||
* @image html map-uv-mapping-1.png
|
||||
* @image rtf map-uv-mapping-1.png
|
||||
* @image latex map-uv-mapping-1.eps
|
||||
*
|
||||
* Images need some special handling when mapped. Evas can easily take care
|
||||
* of objects and do almost anything with them, but it's completely oblivious
|
||||
* to the content of images, so each point in the map needs to be told to what
|
||||
* pixel in the source image it belongs. Failing to do may sometimes result
|
||||
* in the expected behavior, or it may look like a partial work.
|
||||
*
|
||||
* The next image illustrates one possibility of a map being set to an image
|
||||
* object, without setting the right UV mapping for each point. The objects
|
||||
* themselves are mapped properly to their new geometry, but the image content
|
||||
* may not be displayed correctly within the mapped object.
|
||||
*
|
||||
* @image html map-uv-mapping-2.png
|
||||
* @image rtf map-uv-mapping-2.png
|
||||
* @image latex map-uv-mapping-2.eps
|
||||
*
|
||||
* Once Evas knows how to handle the source image within the map, it will
|
||||
* transform it as needed. This is done with evas_map_point_image_uv_set(),
|
||||
* which tells the map to which pixel in image it maps.
|
||||
*
|
||||
* To match our example images to the maps above all we need is the size of
|
||||
* each image, which can always be found with evas_object_image_size_get().
|
||||
*
|
||||
* @code
|
||||
* evas_map_point_image_uv_set(m, 0, 0, 0);
|
||||
* evas_map_point_image_uv_set(m, 1, 150, 0);
|
||||
* evas_map_point_image_uv_set(m, 2, 150, 200);
|
||||
* evas_map_point_image_uv_set(m, 3, 0, 200);
|
||||
* evas_object_map_set(o, m);
|
||||
* evas_object_map_enable_set(o, EINA_TRUE);
|
||||
*
|
||||
* evas_map_point_image_uv_set(m, 0, 0, 0);
|
||||
* evas_map_point_image_uv_set(m, 1, 120, 0);
|
||||
* evas_map_point_image_uv_set(m, 2, 120, 160);
|
||||
* evas_map_point_image_uv_set(m, 3, 0, 160);
|
||||
* evas_object_map_set(o2, m);
|
||||
* evas_object_map_enable_set(o2, EINA_TRUE);
|
||||
* @endcode
|
||||
*
|
||||
* To get
|
||||
*
|
||||
* @image html map-uv-mapping-3.png
|
||||
* @image rtf map-uv-mapping-3.png
|
||||
* @image latex map-uv-mapping-3.eps
|
||||
*
|
||||
* Maps can also be set to use part of an image only, or even map them inverted,
|
||||
* and combined with evas_object_image_source_set() it can be used to achieve
|
||||
* more interesting results.
|
||||
*
|
||||
* @code
|
||||
* evas_object_image_size_get(evas_object_image_source_get(o), &w, &h);
|
||||
* evas_map_point_image_uv_set(m, 0, 0, h);
|
||||
* evas_map_point_image_uv_set(m, 1, w, h);
|
||||
* evas_map_point_image_uv_set(m, 2, w, h / 3);
|
||||
* evas_map_point_image_uv_set(m, 3, 0, h / 3);
|
||||
* evas_object_map_set(o, m);
|
||||
* evas_object_map_enable_set(o, EINA_TRUE);
|
||||
* @endcode
|
||||
*
|
||||
* @image html map-uv-mapping-4.png
|
||||
* @image rtf map-uv-mapping-4.png
|
||||
* @image latex map-uv-mapping-4.eps
|
||||
*
|
||||
* Examples:
|
||||
* @li @ref Example_Evas_Map_Overview
|
||||
*
|
||||
* @ingroup Evas_Object_Group
|
||||
*
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* Populate source and destination map points to match exactly object.
|
||||
*
|
||||
* Usually one initialize map of an object to match it's original
|
||||
* position and size, then transform these with evas_map_util_*
|
||||
* functions, such as evas_map_util_rotate() or
|
||||
* evas_map_util_3d_rotate(). The original set is done by this
|
||||
* function, avoiding code duplication all around.
|
||||
*
|
||||
* @param m map to change all 4 points (must be of size 4).
|
||||
* @param obj object to use unmapped geometry to populate map coordinates.
|
||||
* @param z Point Z Coordinate hint (pre-perspective transform). This value
|
||||
* will be used for all four points.
|
||||
*
|
||||
* @see evas_map_util_points_populate_from_object()
|
||||
* @see evas_map_point_coord_set()
|
||||
* @see evas_map_point_image_uv_set()
|
||||
*/
|
||||
EAPI void evas_map_util_points_populate_from_object_full(Evas_Map *m, const Evas_Object *obj, Evas_Coord z);
|
||||
|
||||
/**
|
||||
* Populate source and destination map points to match exactly object.
|
||||
*
|
||||
* Usually one initialize map of an object to match it's original
|
||||
* position and size, then transform these with evas_map_util_*
|
||||
* functions, such as evas_map_util_rotate() or
|
||||
* evas_map_util_3d_rotate(). The original set is done by this
|
||||
* function, avoiding code duplication all around.
|
||||
*
|
||||
* Z Point coordinate is assumed as 0 (zero).
|
||||
*
|
||||
* @param m map to change all 4 points (must be of size 4).
|
||||
* @param obj object to use unmapped geometry to populate map coordinates.
|
||||
*
|
||||
* @see evas_map_util_points_populate_from_object_full()
|
||||
* @see evas_map_util_points_populate_from_geometry()
|
||||
* @see evas_map_point_coord_set()
|
||||
* @see evas_map_point_image_uv_set()
|
||||
*/
|
||||
EAPI void evas_map_util_points_populate_from_object(Evas_Map *m, const Evas_Object *obj);
|
||||
|
||||
/**
|
||||
* Populate source and destination map points to match given geometry.
|
||||
*
|
||||
* Similar to evas_map_util_points_populate_from_object_full(), this
|
||||
* call takes raw values instead of querying object's unmapped
|
||||
* geometry. The given width will be used to calculate destination
|
||||
* points (evas_map_point_coord_set()) and set the image uv
|
||||
* (evas_map_point_image_uv_set()).
|
||||
*
|
||||
* @param m map to change all 4 points (must be of size 4).
|
||||
* @param x Point X Coordinate
|
||||
* @param y Point Y Coordinate
|
||||
* @param w width to use to calculate second and third points.
|
||||
* @param h height to use to calculate third and fourth points.
|
||||
* @param z Point Z Coordinate hint (pre-perspective transform). This value
|
||||
* will be used for all four points.
|
||||
*
|
||||
* @see evas_map_util_points_populate_from_object()
|
||||
* @see evas_map_point_coord_set()
|
||||
* @see evas_map_point_image_uv_set()
|
||||
*/
|
||||
EAPI void evas_map_util_points_populate_from_geometry(Evas_Map *m, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h, Evas_Coord z);
|
||||
|
||||
/**
|
||||
* Set color of all points to given color.
|
||||
*
|
||||
* This call is useful to reuse maps after they had 3d lightning or
|
||||
* any other colorization applied before.
|
||||
*
|
||||
* @param m map to change the color of.
|
||||
* @param r red (0 - 255)
|
||||
* @param g green (0 - 255)
|
||||
* @param b blue (0 - 255)
|
||||
* @param a alpha (0 - 255)
|
||||
*
|
||||
* @see evas_map_point_color_set()
|
||||
*/
|
||||
EAPI void evas_map_util_points_color_set(Evas_Map *m, int r, int g, int b, int a);
|
||||
|
||||
/**
|
||||
* Change the map to apply the given rotation.
|
||||
*
|
||||
* This rotates the indicated map's coordinates around the center coordinate
|
||||
* given by @p cx and @p cy as the rotation center. The points will have their
|
||||
* X and Y coordinates rotated clockwise by @p 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.
|
||||
*
|
||||
* @param m map to change.
|
||||
* @param degrees amount of degrees from 0.0 to 360.0 to rotate.
|
||||
* @param cx rotation's center horizontal position.
|
||||
* @param cy rotation's center vertical position.
|
||||
*
|
||||
* @see evas_map_point_coord_set()
|
||||
* @see evas_map_util_zoom()
|
||||
*/
|
||||
EAPI void evas_map_util_rotate(Evas_Map *m, double degrees, Evas_Coord cx, Evas_Coord cy);
|
||||
|
||||
/**
|
||||
* Change the map to apply the given zooming.
|
||||
*
|
||||
* Like evas_map_util_rotate(), this zooms the points of the map from a center
|
||||
* point. That center is defined by @p cx and @p cy. The @p zoomx and @p 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.
|
||||
*
|
||||
* @param m map to change.
|
||||
* @param zoomx horizontal zoom to use.
|
||||
* @param zoomy vertical zoom to use.
|
||||
* @param cx zooming center horizontal position.
|
||||
* @param cy zooming center vertical position.
|
||||
*
|
||||
* @see evas_map_point_coord_set()
|
||||
* @see evas_map_util_rotate()
|
||||
*/
|
||||
EAPI void evas_map_util_zoom(Evas_Map *m, double zoomx, double zoomy, Evas_Coord cx, Evas_Coord cy);
|
||||
|
||||
/**
|
||||
* 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).
|
||||
*
|
||||
* @param m map to change.
|
||||
* @param dx amount of degrees from 0.0 to 360.0 to rotate around X axis.
|
||||
* @param dy amount of degrees from 0.0 to 360.0 to rotate around Y axis.
|
||||
* @param dz amount of degrees from 0.0 to 360.0 to rotate around Z axis.
|
||||
* @param cx rotation's center horizontal position.
|
||||
* @param cy rotation's center vertical position.
|
||||
* @param cz rotation's center vertical position.
|
||||
*/
|
||||
EAPI void evas_map_util_3d_rotate(Evas_Map *m, double dx, double dy, double dz, Evas_Coord cx, Evas_Coord cy, Evas_Coord cz);
|
||||
|
||||
/**
|
||||
* Rotate the map in 3D using a unit quaternion.
|
||||
*
|
||||
* 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).
|
||||
*
|
||||
* @param m map to change.
|
||||
* @param qx the x component of the imaginary part of the quaternion.
|
||||
* @param qy the y component of the imaginary part of the quaternion.
|
||||
* @param qz the z component of the imaginary part of the quaternion.
|
||||
* @param qw the w component of the real part of the quaternion.
|
||||
* @param cx rotation's center x.
|
||||
* @param cy rotation's center y.
|
||||
* @param cz rotation's center z.
|
||||
*
|
||||
* @warning Rotations can be done using a unit quaternion. Thus, this
|
||||
* function expects a unit quaternion (i.e. qx² + qy² + qz² + qw² == 1).
|
||||
* If this is not the case the behavior is undefined.
|
||||
*
|
||||
* @since 1.8
|
||||
*/
|
||||
EAPI void evas_map_util_quat_rotate(Evas_Map *m, double qx, double qy, double qz, double qw, double cx, double cy, double cz);
|
||||
|
||||
/**
|
||||
* 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.
|
||||
*
|
||||
* @image html map-light3.png
|
||||
* @image rtf map-light3.png
|
||||
* @image latex map-light3.eps
|
||||
* @note Grey object, no lighting used
|
||||
*
|
||||
* @image html map-light4.png
|
||||
* @image rtf map-light4.png
|
||||
* @image latex map-light4.eps
|
||||
* @note Lights out! Every color set to 0
|
||||
*
|
||||
* @image html map-light5.png
|
||||
* @image rtf map-light5.png
|
||||
* @image latex map-light5.eps
|
||||
* @note Ambient light to full black, red light coming from close at the
|
||||
* bottom-left vertex
|
||||
*
|
||||
* @image html map-light6.png
|
||||
* @image rtf map-light6.png
|
||||
* @image latex map-light6.eps
|
||||
* @note Same light as before, but not the light is set to 0 and ambient light
|
||||
* is cyan
|
||||
*
|
||||
* @image html map-light7.png
|
||||
* @image rtf map-light7.png
|
||||
* @image latex map-light7.eps
|
||||
* @note Both lights are on
|
||||
*
|
||||
* @image html map-light8.png
|
||||
* @image rtf map-light8.png
|
||||
* @image latex map-light8.eps
|
||||
* @note Both lights again, but this time both are the same color.
|
||||
*
|
||||
* @param m map to change.
|
||||
* @param lx X coordinate in space of light point
|
||||
* @param ly Y coordinate in space of light point
|
||||
* @param lz Z coordinate in space of light point
|
||||
* @param lr light red value (0 - 255)
|
||||
* @param lg light green value (0 - 255)
|
||||
* @param lb light blue value (0 - 255)
|
||||
* @param ar ambient color red value (0 - 255)
|
||||
* @param ag ambient color green value (0 - 255)
|
||||
* @param ab ambient color blue value (0 - 255)
|
||||
*/
|
||||
EAPI void evas_map_util_3d_lighting(Evas_Map *m, Evas_Coord lx, Evas_Coord ly, Evas_Coord lz, int lr, int lg, int lb, int ar, int ag, int ab);
|
||||
|
||||
/**
|
||||
* 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 @p 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 @p 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 @p foc must be greater than 0.
|
||||
*
|
||||
* @param m map to change.
|
||||
* @param px The perspective distance X coordinate
|
||||
* @param py The perspective distance Y coordinate
|
||||
* @param z0 The "0" z plane value
|
||||
* @param foc The focal distance
|
||||
*/
|
||||
EAPI void evas_map_util_3d_perspective(Evas_Map *m, Evas_Coord px, Evas_Coord py, Evas_Coord z0, Evas_Coord foc);
|
||||
|
||||
/**
|
||||
* Get the clockwise state of a map
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* @param m map to query.
|
||||
* @return 1 if clockwise, 0 otherwise
|
||||
*/
|
||||
EAPI Eina_Bool evas_map_util_clockwise_get(Evas_Map *m);
|
||||
|
||||
/**
|
||||
* Create map of transformation points to be later used with an Evas object.
|
||||
*
|
||||
* This creates a set of points (currently only 4 is supported. no other
|
||||
* number for @p count will work). That is empty and ready to be modified
|
||||
* with evas_map calls.
|
||||
*
|
||||
* @param count number of points in the map.
|
||||
* @return a newly allocated map or @c NULL on errors.
|
||||
*
|
||||
* @see evas_map_free()
|
||||
* @see evas_map_dup()
|
||||
* @see evas_map_point_coord_set()
|
||||
* @see evas_map_point_image_uv_set()
|
||||
* @see evas_map_util_points_populate_from_object_full()
|
||||
* @see evas_map_util_points_populate_from_object()
|
||||
*
|
||||
* @see evas_object_map_set()
|
||||
*/
|
||||
EAPI Evas_Map *evas_map_new(int count);
|
||||
|
||||
/**
|
||||
* Set the smoothing 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.
|
||||
*
|
||||
* @param m map to modify. Must not be NULL.
|
||||
* @param enabled enable or disable smooth map rendering
|
||||
*/
|
||||
EAPI void evas_map_smooth_set(Evas_Map *m, Eina_Bool enabled);
|
||||
|
||||
/**
|
||||
* Get the smoothing for map rendering
|
||||
*
|
||||
* This gets smoothing for map rendering.
|
||||
*
|
||||
* @param m map to get the smooth from. Must not be NULL.
|
||||
* @return @c EINA_TRUE if the smooth is enabled, @c EINA_FALSE otherwise.
|
||||
*/
|
||||
EAPI Eina_Bool evas_map_smooth_get(const Evas_Map *m);
|
||||
|
||||
/**
|
||||
* Set the 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.
|
||||
* 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.
|
||||
*
|
||||
* @param m map to modify. Must not be NULL.
|
||||
* @param enabled enable or disable alpha map rendering
|
||||
*/
|
||||
EAPI void evas_map_alpha_set(Evas_Map *m, Eina_Bool enabled);
|
||||
|
||||
/**
|
||||
* Get the alpha flag for map rendering
|
||||
*
|
||||
* This gets the alpha flag for map rendering.
|
||||
*
|
||||
* @param m map to get the alpha from. Must not be NULL.
|
||||
* @return EINA_FALSE if map is NULL EINA_TRUE otherwise.
|
||||
*/
|
||||
EAPI Eina_Bool evas_map_alpha_get(const Evas_Map *m);
|
||||
|
||||
/**
|
||||
* Set the flag of the object move synchronization for map rendering
|
||||
*
|
||||
* This sets the flag of the object move synchronization for map rendering.
|
||||
* If the flag is set as enabled, the map will be moved as the object of the map
|
||||
* is moved. By default, the flag of the object move synchronization is not
|
||||
* enabled.
|
||||
*
|
||||
* @param m map to modify. Must not be NULL.
|
||||
* @param enabled enable or disable the object move synchronization for map
|
||||
* rendering.
|
||||
* @since 1.13
|
||||
*/
|
||||
EAPI void evas_map_util_object_move_sync_set(Evas_Map *m, Eina_Bool enabled);
|
||||
|
||||
/**
|
||||
* Get the flag of the object move synchronization for map rendering
|
||||
*
|
||||
* This gets the flag of the object move synchronization for map rendering.
|
||||
*
|
||||
* @param m map to get the flag of the object move synchronization from. Must
|
||||
* not be NULL.
|
||||
* @return EINA_FALSE if map is NULL EINA_TRUE otherwise.
|
||||
* @since 1.13
|
||||
*/
|
||||
EAPI Eina_Bool evas_map_util_object_move_sync_get(const Evas_Map *m);
|
||||
|
||||
/**
|
||||
* Copy a previously allocated map.
|
||||
*
|
||||
* This makes a duplicate of the @p m object and returns it.
|
||||
*
|
||||
* @param m map to copy. Must not be NULL.
|
||||
* @return newly allocated map with the same count and contents as @p m.
|
||||
*/
|
||||
EAPI Evas_Map *evas_map_dup(const Evas_Map *m);
|
||||
|
||||
/**
|
||||
* Free a previously allocated map.
|
||||
*
|
||||
* This frees a given map @p m and all memory associated with it. You must NOT
|
||||
* free a map returned by evas_object_map_get() as this is internal.
|
||||
*
|
||||
* @param m map to free.
|
||||
*/
|
||||
EAPI void evas_map_free(Evas_Map *m);
|
||||
|
||||
/**
|
||||
* Get a maps size.
|
||||
*
|
||||
* Returns the number of points in a map. Should be at least 4.
|
||||
*
|
||||
* @param m map to get size.
|
||||
* @return -1 on error, points otherwise.
|
||||
*/
|
||||
EAPI int evas_map_count_get(const Evas_Map *m) EINA_CONST;
|
||||
|
||||
/**
|
||||
* Change the map point's coordinate.
|
||||
*
|
||||
* This sets 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. It is suggested 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 like with move and resize
|
||||
* in evas.
|
||||
*
|
||||
* @param m map to change point. Must not be @c NULL.
|
||||
* @param idx index of point to change. Must be smaller than map size.
|
||||
* @param x Point X Coordinate
|
||||
* @param y Point Y Coordinate
|
||||
* @param z Point Z Coordinate hint (pre-perspective transform)
|
||||
*
|
||||
* @see evas_map_util_rotate()
|
||||
* @see evas_map_util_zoom()
|
||||
* @see evas_map_util_points_populate_from_object_full()
|
||||
* @see evas_map_util_points_populate_from_object()
|
||||
*/
|
||||
EAPI void evas_map_point_coord_set(Evas_Map *m, int idx, Evas_Coord x, Evas_Coord y, Evas_Coord z);
|
||||
|
||||
/**
|
||||
* Get the map point's coordinate.
|
||||
*
|
||||
* This returns the coordinates of the given point in the map.
|
||||
*
|
||||
* @param m map to query point.
|
||||
* @param idx index of point to query. Must be smaller than map size.
|
||||
* @param x where to return the X coordinate.
|
||||
* @param y where to return the Y coordinate.
|
||||
* @param z where to return the Z coordinate.
|
||||
*/
|
||||
EAPI void evas_map_point_coord_get(const Evas_Map *m, int idx, Evas_Coord *x, Evas_Coord *y, Evas_Coord *z);
|
||||
|
||||
/**
|
||||
* Change the map point's U and V texture source point
|
||||
*
|
||||
* This sets 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.
|
||||
*
|
||||
* @param m map to change the point of.
|
||||
* @param idx index of point to change. Must be smaller than map size.
|
||||
* @param u the X coordinate within the image/texture source
|
||||
* @param v the Y coordinate within the image/texture source
|
||||
*
|
||||
* @see evas_map_point_coord_set()
|
||||
* @see evas_object_map_set()
|
||||
* @see evas_map_util_points_populate_from_object_full()
|
||||
* @see evas_map_util_points_populate_from_object()
|
||||
*/
|
||||
EAPI void evas_map_point_image_uv_set(Evas_Map *m, int idx, double u, double v);
|
||||
|
||||
/**
|
||||
* Get the map point's U and V texture source points
|
||||
*
|
||||
* This returns the texture points set by evas_map_point_image_uv_set().
|
||||
*
|
||||
* @param m map to query point.
|
||||
* @param idx index of point to query. Must be smaller than map size.
|
||||
* @param u where to write the X coordinate within the image/texture source
|
||||
* @param v where to write the Y coordinate within the image/texture source
|
||||
*/
|
||||
EAPI void evas_map_point_image_uv_get(const Evas_Map *m, int idx, double *u, double *v);
|
||||
|
||||
/**
|
||||
* Set the 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.
|
||||
*
|
||||
* @param m map to change the color of.
|
||||
* @param idx index of point to change. Must be smaller than map size.
|
||||
* @param r red (0 - 255)
|
||||
* @param g green (0 - 255)
|
||||
* @param b blue (0 - 255)
|
||||
* @param a alpha (0 - 255)
|
||||
*
|
||||
* @see evas_map_util_points_color_set()
|
||||
* @see evas_map_point_coord_set()
|
||||
* @see evas_object_map_set()
|
||||
*/
|
||||
EAPI void evas_map_point_color_set(Evas_Map *m, int idx, int r, int g, int b, int a);
|
||||
|
||||
/**
|
||||
* Get the color set on a vertex in the map
|
||||
*
|
||||
* This gets the color set by evas_map_point_color_set() on the given vertex
|
||||
* of the map.
|
||||
*
|
||||
* @param m map to get the color of the vertex from.
|
||||
* @param idx index of point get. Must be smaller than map size.
|
||||
* @param r pointer to red return
|
||||
* @param g pointer to green return
|
||||
* @param b pointer to blue return
|
||||
* @param a pointer to alpha return
|
||||
*
|
||||
* @see evas_map_point_coord_set()
|
||||
* @see evas_object_map_set()
|
||||
*/
|
||||
EAPI void evas_map_point_color_get(const Evas_Map *m, int idx, int *r, int *g, int *b, int *a);
|
||||
/**
|
||||
* @}
|
||||
*/
|
||||
|
||||
/**
|
||||
* @defgroup Evas_Object_Group_Size_Hints Size Hints
|
||||
*
|
||||
|
|
|
|||
|
|
@ -5719,6 +5719,840 @@ EAPI void evas_output_size_get(const Evas *e, int *w, int *h);
|
|||
|
||||
#include "canvas/evas_out.eo.legacy.h"
|
||||
|
||||
typedef struct _Evas_Map Evas_Map;
|
||||
|
||||
/**
|
||||
* @defgroup Evas_Object_Group_Map UV Mapping (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.
|
||||
*
|
||||
* As usual, Evas provides both the raw and easy to use methods. The
|
||||
* raw methods allow developers to create their maps somewhere else,
|
||||
* possibly loading them from some file format. The easy to use methods
|
||||
* calculate the points given some high-level parameters such as
|
||||
* rotation angle, ambient light, and so on.
|
||||
*
|
||||
* @note applying mapping will reduce performance, so use with
|
||||
* care. The impact on performance depends on engine in
|
||||
* use. Software is quite optimized, but not as fast as OpenGL.
|
||||
*
|
||||
* @section sec-map-points Map points
|
||||
* @subsection subsec-rotation Rotation
|
||||
*
|
||||
* A map consists of a set of points, currently only four are supported. Each
|
||||
* of these points contains a set of canvas coordinates @c x and @c y that
|
||||
* can be used to alter the geometry of the mapped object, and a @c z
|
||||
* coordinate that indicates the depth of that point. This last coordinate
|
||||
* does not normally affect the map, but it's used by several of the utility
|
||||
* functions to calculate the right position of the point given other
|
||||
* parameters.
|
||||
*
|
||||
* The coordinates for each point are set with evas_map_point_coord_set().
|
||||
* The following image shows a map set to match the geometry of an existing
|
||||
* object.
|
||||
*
|
||||
* @image html map-set-map-points-1.png
|
||||
* @image rtf map-set-map-points-1.png
|
||||
* @image latex map-set-map-points-1.eps
|
||||
*
|
||||
* This is a common practice, so there are a few functions that help make it
|
||||
* easier.
|
||||
*
|
||||
* evas_map_util_points_populate_from_geometry() sets the coordinates of each
|
||||
* point in the given map to match the rectangle defined by the function
|
||||
* parameters.
|
||||
*
|
||||
* evas_map_util_points_populate_from_object() and
|
||||
* evas_map_util_points_populate_from_object_full() both take an object and
|
||||
* set the map points to match its geometry. The difference between the two
|
||||
* is that the first function sets the @c z value of all points to 0, while
|
||||
* the latter receives the value to set in said coordinate as a parameter.
|
||||
*
|
||||
* The following lines of code all produce the same result as in the image
|
||||
* above.
|
||||
* @code
|
||||
* evas_map_util_points_populate_from_geometry(m, 100, 100, 200, 200, 0);
|
||||
* // Assuming o is our original object
|
||||
* evas_object_move(o, 100, 100);
|
||||
* evas_object_resize(o, 200, 200);
|
||||
* evas_map_util_points_populate_from_object(m, o);
|
||||
* evas_map_util_points_populate_from_object_full(m, o, 0);
|
||||
* @endcode
|
||||
*
|
||||
* Several effects can be applied to an object by simply setting each point
|
||||
* of the map to the right coordinates. For example, a simulated perspective
|
||||
* could be achieve as follows.
|
||||
*
|
||||
* @image html map-set-map-points-2.png
|
||||
* @image rtf map-set-map-points-2.png
|
||||
* @image latex map-set-map-points-2.eps
|
||||
*
|
||||
* As said before, the @c z coordinate is unused here so when setting points
|
||||
* by hand, its value is of no importance.
|
||||
*
|
||||
* @image html map-set-map-points-3.png
|
||||
* @image rtf map-set-map-points-3.png
|
||||
* @image latex map-set-map-points-3.eps
|
||||
*
|
||||
* In all three cases above, setting the map to be used by the object is the
|
||||
* same.
|
||||
* @code
|
||||
* evas_object_map_set(o, m);
|
||||
* evas_object_map_enable_set(o, EINA_TRUE);
|
||||
* @endcode
|
||||
*
|
||||
* Doing things this way, however, is a lot of work that can be avoided by
|
||||
* using the provided utility functions, as described in the next section.
|
||||
*
|
||||
* @section map-utils Utility functions
|
||||
*
|
||||
* Utility functions take an already set up map and alter it to produce a
|
||||
* specific effect. For example, to rotate an object around its own center
|
||||
* you would need to take the rotation angle, the coordinates of each corner
|
||||
* of the object and do all the math to get the new set of coordinates that
|
||||
* need to be set in the map.
|
||||
*
|
||||
* Or you can use this code:
|
||||
* @code
|
||||
* evas_object_geometry_get(o, &x, &y, &w, &h);
|
||||
* m = evas_map_new(4);
|
||||
* evas_map_util_points_populate_from_object(m, o);
|
||||
* evas_map_util_rotate(m, 45, x + (w / 2), y + (h / 2));
|
||||
* evas_object_map_set(o, m);
|
||||
* evas_object_map_enable_set(o, EINA_TRUE);
|
||||
* evas_map_free(m);
|
||||
* @endcode
|
||||
*
|
||||
* Which will rotate the object around its center point in a 45 degree angle
|
||||
* in the clockwise direction, taking it from this
|
||||
*
|
||||
* @image html map-rotation-2d-1.png
|
||||
* @image rtf map-rotation-2d-1.png
|
||||
* @image latex map-rotation-2d-1.eps
|
||||
*
|
||||
* to this
|
||||
*
|
||||
* @image html map-rotation-2d-2.png
|
||||
* @image rtf map-rotation-2d-2.png
|
||||
* @image latex map-rotation-2d-2.eps
|
||||
*
|
||||
* Objects may be rotated around any other point just by setting the last two
|
||||
* paramaters of the evas_map_util_rotate() function to the right values. A
|
||||
* circle of roughly the diameter of the object overlaid on each image shows
|
||||
* where the center of rotation is set for each example.
|
||||
*
|
||||
* For example, this code
|
||||
* @code
|
||||
* evas_object_geometry_get(o, &x, &y, &w, &h);
|
||||
* m = evas_map_new(4);
|
||||
* evas_map_util_points_populate_from_object(m, o);
|
||||
* evas_map_util_rotate(m, 45, x + w - 20, y + h - 20);
|
||||
* evas_object_map_set(o, m);
|
||||
* evas_object_map_enable_set(o, EINA_TRUE);
|
||||
* evas_map_free(m);
|
||||
* @endcode
|
||||
*
|
||||
* produces something like
|
||||
*
|
||||
* @image html map-rotation-2d-3.png
|
||||
* @image rtf map-rotation-2d-3.png
|
||||
* @image latex map-rotation-2d-3.eps
|
||||
*
|
||||
* And the following
|
||||
* @code
|
||||
* evas_output_size_get(evas, &w, &h);
|
||||
* m = evas_map_new(4);
|
||||
* evas_map_util_points_populate_from_object(m, o);
|
||||
* evas_map_util_rotate(m, 45, w, h);
|
||||
* evas_object_map_set(o, m);
|
||||
* evas_object_map_enable_set(o, EINA_TRUE);
|
||||
* evas_map_free(m);
|
||||
* @endcode
|
||||
*
|
||||
* rotates the object around the center of the window
|
||||
*
|
||||
* @image html map-rotation-2d-4.png
|
||||
* @image rtf map-rotation-2d-4.png
|
||||
* @image latex map-rotation-2d-4.eps
|
||||
*
|
||||
* @subsection subsec-3d 3D Maps
|
||||
*
|
||||
* Maps can also be used to achieve the effect of 3-dimensionality. When doing
|
||||
* this, the @c z coordinate of each point counts, with higher values meaning
|
||||
* the point is further into the screen, and smaller values (negative, usually)
|
||||
* meaning the point is closer towards the user.
|
||||
*
|
||||
* Thinking in 3D also introduces the concept of back-face of an object. An
|
||||
* object is said to be facing the user when all its points are placed in a
|
||||
* clockwise fashion. The next image shows this, with each point showing the
|
||||
* with which is identified within the map.
|
||||
*
|
||||
* @image html map-point-order-face.png
|
||||
* @image rtf map-point-order-face.png
|
||||
* @image latex map-point-order-face.eps
|
||||
*
|
||||
* Rotating this map around the @c Y axis would leave the order of the points
|
||||
* in a counter-clockwise fashion, as seen in the following image.
|
||||
*
|
||||
* @image html map-point-order-back.png
|
||||
* @image rtf map-point-order-back.png
|
||||
* @image latex map-point-order-back.eps
|
||||
*
|
||||
* This way we can say that we are looking at the back face of the object.
|
||||
* This will have stronger implications later when we talk about lighting.
|
||||
*
|
||||
* To know if a map is facing towards the user or not it's enough to use
|
||||
* the evas_map_util_clockwise_get() function, but this is normally done
|
||||
* after all the other operations are applied on the map.
|
||||
*
|
||||
* @subsection subsec-3d-rot 3D rotation and perspective
|
||||
*
|
||||
* Much like evas_map_util_rotate(), there's the function
|
||||
* evas_map_util_3d_rotate() that transforms the map to apply a 3D rotation
|
||||
* to an object. As in its 2D counterpart, the rotation can be applied around
|
||||
* any point in the canvas, this time with a @c z coordinate too. The rotation
|
||||
* can also be around any of the 3 axis.
|
||||
*
|
||||
* Starting from this simple setup
|
||||
*
|
||||
* @image html map-3d-basic-1.png
|
||||
* @image rtf map-3d-basic-1.png
|
||||
* @image latex map-3d-basic-1.eps
|
||||
*
|
||||
* and setting maps so that the blue square to rotate on all axis around a
|
||||
* sphere that uses the object as its center, and the red square to rotate
|
||||
* around the @c Y axis, we get the following. A simple overlay over the image
|
||||
* shows the original geometry of each object and the axis around which they
|
||||
* are being rotated, with the @c Z one not appearing due to being orthogonal
|
||||
* to the screen.
|
||||
*
|
||||
* @image html map-3d-basic-2.png
|
||||
* @image rtf map-3d-basic-2.png
|
||||
* @image latex map-3d-basic-2.eps
|
||||
*
|
||||
* which doesn't look very real. This can be helped by adding perspective
|
||||
* to the transformation, which can be simply done by calling
|
||||
* evas_map_util_3d_perspective() on the map after its position has been set.
|
||||
* The result in this case, making the vanishing point the center of each
|
||||
* object:
|
||||
*
|
||||
* @image html map-3d-basic-3.png
|
||||
* @image rtf map-3d-basic-3.png
|
||||
* @image latex map-3d-basic-3.eps
|
||||
*
|
||||
* @section sec-color Color and lighting
|
||||
*
|
||||
* Each point in a map can be set to a color, which will be multiplied with
|
||||
* the objects own color and linearly interpolated in between adjacent points.
|
||||
* This is done with evas_map_point_color_set() for each point of the map,
|
||||
* or evas_map_util_points_color_set() to set every point to the same color.
|
||||
*
|
||||
* When using 3D effects, colors can be used to improve the looks of them by
|
||||
* simulating a light source. The evas_map_util_3d_lighting() function makes
|
||||
* this task easier by taking the coordinates of the light source and its
|
||||
* color, along with the color of the ambient light. Evas then sets the color
|
||||
* of each point based on the distance to the light source, the angle with
|
||||
* which the object is facing the light and the ambient light. Here, the
|
||||
* orientation of each point as explained before, becomes more important.
|
||||
* If the map is defined counter-clockwise, the object will be facing away
|
||||
* from the user and thus become obscured, since no light would be reflecting
|
||||
* from it.
|
||||
*
|
||||
* @image html map-light.png
|
||||
* @image rtf map-light.png
|
||||
* @image latex map-light.eps
|
||||
* @note Object facing the light source
|
||||
*
|
||||
* @image html map-light2.png
|
||||
* @image rtf map-light2.png
|
||||
* @image latex map-light2.eps
|
||||
* @note Same object facing away from the user
|
||||
*
|
||||
* @section Image mapping
|
||||
*
|
||||
* @image html map-uv-mapping-1.png
|
||||
* @image rtf map-uv-mapping-1.png
|
||||
* @image latex map-uv-mapping-1.eps
|
||||
*
|
||||
* Images need some special handling when mapped. Evas can easily take care
|
||||
* of objects and do almost anything with them, but it's completely oblivious
|
||||
* to the content of images, so each point in the map needs to be told to what
|
||||
* pixel in the source image it belongs. Failing to do may sometimes result
|
||||
* in the expected behavior, or it may look like a partial work.
|
||||
*
|
||||
* The next image illustrates one possibility of a map being set to an image
|
||||
* object, without setting the right UV mapping for each point. The objects
|
||||
* themselves are mapped properly to their new geometry, but the image content
|
||||
* may not be displayed correctly within the mapped object.
|
||||
*
|
||||
* @image html map-uv-mapping-2.png
|
||||
* @image rtf map-uv-mapping-2.png
|
||||
* @image latex map-uv-mapping-2.eps
|
||||
*
|
||||
* Once Evas knows how to handle the source image within the map, it will
|
||||
* transform it as needed. This is done with evas_map_point_image_uv_set(),
|
||||
* which tells the map to which pixel in image it maps.
|
||||
*
|
||||
* To match our example images to the maps above all we need is the size of
|
||||
* each image, which can always be found with evas_object_image_size_get().
|
||||
*
|
||||
* @code
|
||||
* evas_map_point_image_uv_set(m, 0, 0, 0);
|
||||
* evas_map_point_image_uv_set(m, 1, 150, 0);
|
||||
* evas_map_point_image_uv_set(m, 2, 150, 200);
|
||||
* evas_map_point_image_uv_set(m, 3, 0, 200);
|
||||
* evas_object_map_set(o, m);
|
||||
* evas_object_map_enable_set(o, EINA_TRUE);
|
||||
*
|
||||
* evas_map_point_image_uv_set(m, 0, 0, 0);
|
||||
* evas_map_point_image_uv_set(m, 1, 120, 0);
|
||||
* evas_map_point_image_uv_set(m, 2, 120, 160);
|
||||
* evas_map_point_image_uv_set(m, 3, 0, 160);
|
||||
* evas_object_map_set(o2, m);
|
||||
* evas_object_map_enable_set(o2, EINA_TRUE);
|
||||
* @endcode
|
||||
*
|
||||
* To get
|
||||
*
|
||||
* @image html map-uv-mapping-3.png
|
||||
* @image rtf map-uv-mapping-3.png
|
||||
* @image latex map-uv-mapping-3.eps
|
||||
*
|
||||
* Maps can also be set to use part of an image only, or even map them inverted,
|
||||
* and combined with evas_object_image_source_set() it can be used to achieve
|
||||
* more interesting results.
|
||||
*
|
||||
* @code
|
||||
* evas_object_image_size_get(evas_object_image_source_get(o), &w, &h);
|
||||
* evas_map_point_image_uv_set(m, 0, 0, h);
|
||||
* evas_map_point_image_uv_set(m, 1, w, h);
|
||||
* evas_map_point_image_uv_set(m, 2, w, h / 3);
|
||||
* evas_map_point_image_uv_set(m, 3, 0, h / 3);
|
||||
* evas_object_map_set(o, m);
|
||||
* evas_object_map_enable_set(o, EINA_TRUE);
|
||||
* @endcode
|
||||
*
|
||||
* @image html map-uv-mapping-4.png
|
||||
* @image rtf map-uv-mapping-4.png
|
||||
* @image latex map-uv-mapping-4.eps
|
||||
*
|
||||
* Examples:
|
||||
* @li @ref Example_Evas_Map_Overview
|
||||
*
|
||||
* @ingroup Evas_Object_Group
|
||||
*
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* Populate source and destination map points to match exactly object.
|
||||
*
|
||||
* Usually one initialize map of an object to match it's original
|
||||
* position and size, then transform these with evas_map_util_*
|
||||
* functions, such as evas_map_util_rotate() or
|
||||
* evas_map_util_3d_rotate(). The original set is done by this
|
||||
* function, avoiding code duplication all around.
|
||||
*
|
||||
* @param m map to change all 4 points (must be of size 4).
|
||||
* @param obj object to use unmapped geometry to populate map coordinates.
|
||||
* @param z Point Z Coordinate hint (pre-perspective transform). This value
|
||||
* will be used for all four points.
|
||||
*
|
||||
* @see evas_map_util_points_populate_from_object()
|
||||
* @see evas_map_point_coord_set()
|
||||
* @see evas_map_point_image_uv_set()
|
||||
*/
|
||||
EAPI void evas_map_util_points_populate_from_object_full(Evas_Map *m, const Evas_Object *obj, Evas_Coord z);
|
||||
|
||||
/**
|
||||
* Populate source and destination map points to match exactly object.
|
||||
*
|
||||
* Usually one initialize map of an object to match it's original
|
||||
* position and size, then transform these with evas_map_util_*
|
||||
* functions, such as evas_map_util_rotate() or
|
||||
* evas_map_util_3d_rotate(). The original set is done by this
|
||||
* function, avoiding code duplication all around.
|
||||
*
|
||||
* Z Point coordinate is assumed as 0 (zero).
|
||||
*
|
||||
* @param m map to change all 4 points (must be of size 4).
|
||||
* @param obj object to use unmapped geometry to populate map coordinates.
|
||||
*
|
||||
* @see evas_map_util_points_populate_from_object_full()
|
||||
* @see evas_map_util_points_populate_from_geometry()
|
||||
* @see evas_map_point_coord_set()
|
||||
* @see evas_map_point_image_uv_set()
|
||||
*/
|
||||
EAPI void evas_map_util_points_populate_from_object(Evas_Map *m, const Evas_Object *obj);
|
||||
|
||||
/**
|
||||
* Populate source and destination map points to match given geometry.
|
||||
*
|
||||
* Similar to evas_map_util_points_populate_from_object_full(), this
|
||||
* call takes raw values instead of querying object's unmapped
|
||||
* geometry. The given width will be used to calculate destination
|
||||
* points (evas_map_point_coord_set()) and set the image uv
|
||||
* (evas_map_point_image_uv_set()).
|
||||
*
|
||||
* @param m map to change all 4 points (must be of size 4).
|
||||
* @param x Point X Coordinate
|
||||
* @param y Point Y Coordinate
|
||||
* @param w width to use to calculate second and third points.
|
||||
* @param h height to use to calculate third and fourth points.
|
||||
* @param z Point Z Coordinate hint (pre-perspective transform). This value
|
||||
* will be used for all four points.
|
||||
*
|
||||
* @see evas_map_util_points_populate_from_object()
|
||||
* @see evas_map_point_coord_set()
|
||||
* @see evas_map_point_image_uv_set()
|
||||
*/
|
||||
EAPI void evas_map_util_points_populate_from_geometry(Evas_Map *m, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h, Evas_Coord z);
|
||||
|
||||
/**
|
||||
* Set color of all points to given color.
|
||||
*
|
||||
* This call is useful to reuse maps after they had 3d lightning or
|
||||
* any other colorization applied before.
|
||||
*
|
||||
* @param m map to change the color of.
|
||||
* @param r red (0 - 255)
|
||||
* @param g green (0 - 255)
|
||||
* @param b blue (0 - 255)
|
||||
* @param a alpha (0 - 255)
|
||||
*
|
||||
* @see evas_map_point_color_set()
|
||||
*/
|
||||
EAPI void evas_map_util_points_color_set(Evas_Map *m, int r, int g, int b, int a);
|
||||
|
||||
/**
|
||||
* Change the map to apply the given rotation.
|
||||
*
|
||||
* This rotates the indicated map's coordinates around the center coordinate
|
||||
* given by @p cx and @p cy as the rotation center. The points will have their
|
||||
* X and Y coordinates rotated clockwise by @p 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.
|
||||
*
|
||||
* @param m map to change.
|
||||
* @param degrees amount of degrees from 0.0 to 360.0 to rotate.
|
||||
* @param cx rotation's center horizontal position.
|
||||
* @param cy rotation's center vertical position.
|
||||
*
|
||||
* @see evas_map_point_coord_set()
|
||||
* @see evas_map_util_zoom()
|
||||
*/
|
||||
EAPI void evas_map_util_rotate(Evas_Map *m, double degrees, Evas_Coord cx, Evas_Coord cy);
|
||||
|
||||
/**
|
||||
* Change the map to apply the given zooming.
|
||||
*
|
||||
* Like evas_map_util_rotate(), this zooms the points of the map from a center
|
||||
* point. That center is defined by @p cx and @p cy. The @p zoomx and @p 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.
|
||||
*
|
||||
* @param m map to change.
|
||||
* @param zoomx horizontal zoom to use.
|
||||
* @param zoomy vertical zoom to use.
|
||||
* @param cx zooming center horizontal position.
|
||||
* @param cy zooming center vertical position.
|
||||
*
|
||||
* @see evas_map_point_coord_set()
|
||||
* @see evas_map_util_rotate()
|
||||
*/
|
||||
EAPI void evas_map_util_zoom(Evas_Map *m, double zoomx, double zoomy, Evas_Coord cx, Evas_Coord cy);
|
||||
|
||||
/**
|
||||
* 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).
|
||||
*
|
||||
* @param m map to change.
|
||||
* @param dx amount of degrees from 0.0 to 360.0 to rotate around X axis.
|
||||
* @param dy amount of degrees from 0.0 to 360.0 to rotate around Y axis.
|
||||
* @param dz amount of degrees from 0.0 to 360.0 to rotate around Z axis.
|
||||
* @param cx rotation's center horizontal position.
|
||||
* @param cy rotation's center vertical position.
|
||||
* @param cz rotation's center vertical position.
|
||||
*/
|
||||
EAPI void evas_map_util_3d_rotate(Evas_Map *m, double dx, double dy, double dz, Evas_Coord cx, Evas_Coord cy, Evas_Coord cz);
|
||||
|
||||
/**
|
||||
* Rotate the map in 3D using a unit quaternion.
|
||||
*
|
||||
* 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).
|
||||
*
|
||||
* @param m map to change.
|
||||
* @param qx the x component of the imaginary part of the quaternion.
|
||||
* @param qy the y component of the imaginary part of the quaternion.
|
||||
* @param qz the z component of the imaginary part of the quaternion.
|
||||
* @param qw the w component of the real part of the quaternion.
|
||||
* @param cx rotation's center x.
|
||||
* @param cy rotation's center y.
|
||||
* @param cz rotation's center z.
|
||||
*
|
||||
* @warning Rotations can be done using a unit quaternion. Thus, this
|
||||
* function expects a unit quaternion (i.e. qx² + qy² + qz² + qw² == 1).
|
||||
* If this is not the case the behavior is undefined.
|
||||
*
|
||||
* @since 1.8
|
||||
*/
|
||||
EAPI void evas_map_util_quat_rotate(Evas_Map *m, double qx, double qy, double qz, double qw, double cx, double cy, double cz);
|
||||
|
||||
/**
|
||||
* 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.
|
||||
*
|
||||
* @image html map-light3.png
|
||||
* @image rtf map-light3.png
|
||||
* @image latex map-light3.eps
|
||||
* @note Grey object, no lighting used
|
||||
*
|
||||
* @image html map-light4.png
|
||||
* @image rtf map-light4.png
|
||||
* @image latex map-light4.eps
|
||||
* @note Lights out! Every color set to 0
|
||||
*
|
||||
* @image html map-light5.png
|
||||
* @image rtf map-light5.png
|
||||
* @image latex map-light5.eps
|
||||
* @note Ambient light to full black, red light coming from close at the
|
||||
* bottom-left vertex
|
||||
*
|
||||
* @image html map-light6.png
|
||||
* @image rtf map-light6.png
|
||||
* @image latex map-light6.eps
|
||||
* @note Same light as before, but not the light is set to 0 and ambient light
|
||||
* is cyan
|
||||
*
|
||||
* @image html map-light7.png
|
||||
* @image rtf map-light7.png
|
||||
* @image latex map-light7.eps
|
||||
* @note Both lights are on
|
||||
*
|
||||
* @image html map-light8.png
|
||||
* @image rtf map-light8.png
|
||||
* @image latex map-light8.eps
|
||||
* @note Both lights again, but this time both are the same color.
|
||||
*
|
||||
* @param m map to change.
|
||||
* @param lx X coordinate in space of light point
|
||||
* @param ly Y coordinate in space of light point
|
||||
* @param lz Z coordinate in space of light point
|
||||
* @param lr light red value (0 - 255)
|
||||
* @param lg light green value (0 - 255)
|
||||
* @param lb light blue value (0 - 255)
|
||||
* @param ar ambient color red value (0 - 255)
|
||||
* @param ag ambient color green value (0 - 255)
|
||||
* @param ab ambient color blue value (0 - 255)
|
||||
*/
|
||||
EAPI void evas_map_util_3d_lighting(Evas_Map *m, Evas_Coord lx, Evas_Coord ly, Evas_Coord lz, int lr, int lg, int lb, int ar, int ag, int ab);
|
||||
|
||||
/**
|
||||
* 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 @p 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 @p 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 @p foc must be greater than 0.
|
||||
*
|
||||
* @param m map to change.
|
||||
* @param px The perspective distance X coordinate
|
||||
* @param py The perspective distance Y coordinate
|
||||
* @param z0 The "0" z plane value
|
||||
* @param foc The focal distance
|
||||
*/
|
||||
EAPI void evas_map_util_3d_perspective(Evas_Map *m, Evas_Coord px, Evas_Coord py, Evas_Coord z0, Evas_Coord foc);
|
||||
|
||||
/**
|
||||
* Get the clockwise state of a map
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* @param m map to query.
|
||||
* @return 1 if clockwise, 0 otherwise
|
||||
*/
|
||||
EAPI Eina_Bool evas_map_util_clockwise_get(Evas_Map *m);
|
||||
|
||||
/**
|
||||
* Create map of transformation points to be later used with an Evas object.
|
||||
*
|
||||
* This creates a set of points (currently only 4 is supported. no other
|
||||
* number for @p count will work). That is empty and ready to be modified
|
||||
* with evas_map calls.
|
||||
*
|
||||
* @param count number of points in the map.
|
||||
* @return a newly allocated map or @c NULL on errors.
|
||||
*
|
||||
* @see evas_map_free()
|
||||
* @see evas_map_dup()
|
||||
* @see evas_map_point_coord_set()
|
||||
* @see evas_map_point_image_uv_set()
|
||||
* @see evas_map_util_points_populate_from_object_full()
|
||||
* @see evas_map_util_points_populate_from_object()
|
||||
*
|
||||
* @see evas_object_map_set()
|
||||
*/
|
||||
EAPI Evas_Map *evas_map_new(int count);
|
||||
|
||||
/**
|
||||
* Set the smoothing 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.
|
||||
*
|
||||
* @param m map to modify. Must not be NULL.
|
||||
* @param enabled enable or disable smooth map rendering
|
||||
*/
|
||||
EAPI void evas_map_smooth_set(Evas_Map *m, Eina_Bool enabled);
|
||||
|
||||
/**
|
||||
* Get the smoothing for map rendering
|
||||
*
|
||||
* This gets smoothing for map rendering.
|
||||
*
|
||||
* @param m map to get the smooth from. Must not be NULL.
|
||||
* @return @c EINA_TRUE if the smooth is enabled, @c EINA_FALSE otherwise.
|
||||
*/
|
||||
EAPI Eina_Bool evas_map_smooth_get(const Evas_Map *m);
|
||||
|
||||
/**
|
||||
* Set the 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.
|
||||
* 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.
|
||||
*
|
||||
* @param m map to modify. Must not be NULL.
|
||||
* @param enabled enable or disable alpha map rendering
|
||||
*/
|
||||
EAPI void evas_map_alpha_set(Evas_Map *m, Eina_Bool enabled);
|
||||
|
||||
/**
|
||||
* Get the alpha flag for map rendering
|
||||
*
|
||||
* This gets the alpha flag for map rendering.
|
||||
*
|
||||
* @param m map to get the alpha from. Must not be NULL.
|
||||
* @return EINA_FALSE if map is NULL EINA_TRUE otherwise.
|
||||
*/
|
||||
EAPI Eina_Bool evas_map_alpha_get(const Evas_Map *m);
|
||||
|
||||
/**
|
||||
* Set the flag of the object move synchronization for map rendering
|
||||
*
|
||||
* This sets the flag of the object move synchronization for map rendering.
|
||||
* If the flag is set as enabled, the map will be moved as the object of the map
|
||||
* is moved. By default, the flag of the object move synchronization is not
|
||||
* enabled.
|
||||
*
|
||||
* @param m map to modify. Must not be NULL.
|
||||
* @param enabled enable or disable the object move synchronization for map
|
||||
* rendering.
|
||||
* @since 1.13
|
||||
*/
|
||||
EAPI void evas_map_util_object_move_sync_set(Evas_Map *m, Eina_Bool enabled);
|
||||
|
||||
/**
|
||||
* Get the flag of the object move synchronization for map rendering
|
||||
*
|
||||
* This gets the flag of the object move synchronization for map rendering.
|
||||
*
|
||||
* @param m map to get the flag of the object move synchronization from. Must
|
||||
* not be NULL.
|
||||
* @return EINA_FALSE if map is NULL EINA_TRUE otherwise.
|
||||
* @since 1.13
|
||||
*/
|
||||
EAPI Eina_Bool evas_map_util_object_move_sync_get(const Evas_Map *m);
|
||||
|
||||
/**
|
||||
* Copy a previously allocated map.
|
||||
*
|
||||
* This makes a duplicate of the @p m object and returns it.
|
||||
*
|
||||
* @param m map to copy. Must not be NULL.
|
||||
* @return newly allocated map with the same count and contents as @p m.
|
||||
*/
|
||||
EAPI Evas_Map *evas_map_dup(const Evas_Map *m);
|
||||
|
||||
/**
|
||||
* Free a previously allocated map.
|
||||
*
|
||||
* This frees a given map @p m and all memory associated with it. You must NOT
|
||||
* free a map returned by evas_object_map_get() as this is internal.
|
||||
*
|
||||
* @param m map to free.
|
||||
*/
|
||||
EAPI void evas_map_free(Evas_Map *m);
|
||||
|
||||
/**
|
||||
* Get a maps size.
|
||||
*
|
||||
* Returns the number of points in a map. Should be at least 4.
|
||||
*
|
||||
* @param m map to get size.
|
||||
* @return -1 on error, points otherwise.
|
||||
*/
|
||||
EAPI int evas_map_count_get(const Evas_Map *m) EINA_CONST;
|
||||
|
||||
/**
|
||||
* Change the map point's coordinate.
|
||||
*
|
||||
* This sets 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. It is suggested 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 like with move and resize
|
||||
* in evas.
|
||||
*
|
||||
* @param m map to change point. Must not be @c NULL.
|
||||
* @param idx index of point to change. Must be smaller than map size.
|
||||
* @param x Point X Coordinate
|
||||
* @param y Point Y Coordinate
|
||||
* @param z Point Z Coordinate hint (pre-perspective transform)
|
||||
*
|
||||
* @see evas_map_util_rotate()
|
||||
* @see evas_map_util_zoom()
|
||||
* @see evas_map_util_points_populate_from_object_full()
|
||||
* @see evas_map_util_points_populate_from_object()
|
||||
*/
|
||||
EAPI void evas_map_point_coord_set(Evas_Map *m, int idx, Evas_Coord x, Evas_Coord y, Evas_Coord z);
|
||||
|
||||
/**
|
||||
* Get the map point's coordinate.
|
||||
*
|
||||
* This returns the coordinates of the given point in the map.
|
||||
*
|
||||
* @param m map to query point.
|
||||
* @param idx index of point to query. Must be smaller than map size.
|
||||
* @param x where to return the X coordinate.
|
||||
* @param y where to return the Y coordinate.
|
||||
* @param z where to return the Z coordinate.
|
||||
*/
|
||||
EAPI void evas_map_point_coord_get(const Evas_Map *m, int idx, Evas_Coord *x, Evas_Coord *y, Evas_Coord *z);
|
||||
|
||||
/**
|
||||
* Change the map point's U and V texture source point
|
||||
*
|
||||
* This sets 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.
|
||||
*
|
||||
* @param m map to change the point of.
|
||||
* @param idx index of point to change. Must be smaller than map size.
|
||||
* @param u the X coordinate within the image/texture source
|
||||
* @param v the Y coordinate within the image/texture source
|
||||
*
|
||||
* @see evas_map_point_coord_set()
|
||||
* @see evas_object_map_set()
|
||||
* @see evas_map_util_points_populate_from_object_full()
|
||||
* @see evas_map_util_points_populate_from_object()
|
||||
*/
|
||||
EAPI void evas_map_point_image_uv_set(Evas_Map *m, int idx, double u, double v);
|
||||
|
||||
/**
|
||||
* Get the map point's U and V texture source points
|
||||
*
|
||||
* This returns the texture points set by evas_map_point_image_uv_set().
|
||||
*
|
||||
* @param m map to query point.
|
||||
* @param idx index of point to query. Must be smaller than map size.
|
||||
* @param u where to write the X coordinate within the image/texture source
|
||||
* @param v where to write the Y coordinate within the image/texture source
|
||||
*/
|
||||
EAPI void evas_map_point_image_uv_get(const Evas_Map *m, int idx, double *u, double *v);
|
||||
|
||||
/**
|
||||
* Set the 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.
|
||||
*
|
||||
* @param m map to change the color of.
|
||||
* @param idx index of point to change. Must be smaller than map size.
|
||||
* @param r red (0 - 255)
|
||||
* @param g green (0 - 255)
|
||||
* @param b blue (0 - 255)
|
||||
* @param a alpha (0 - 255)
|
||||
*
|
||||
* @see evas_map_util_points_color_set()
|
||||
* @see evas_map_point_coord_set()
|
||||
* @see evas_object_map_set()
|
||||
*/
|
||||
EAPI void evas_map_point_color_set(Evas_Map *m, int idx, int r, int g, int b, int a);
|
||||
|
||||
/**
|
||||
* Get the color set on a vertex in the map
|
||||
*
|
||||
* This gets the color set by evas_map_point_color_set() on the given vertex
|
||||
* of the map.
|
||||
*
|
||||
* @param m map to get the color of the vertex from.
|
||||
* @param idx index of point get. Must be smaller than map size.
|
||||
* @param r pointer to red return
|
||||
* @param g pointer to green return
|
||||
* @param b pointer to blue return
|
||||
* @param a pointer to alpha return
|
||||
*
|
||||
* @see evas_map_point_coord_set()
|
||||
* @see evas_object_map_set()
|
||||
*/
|
||||
EAPI void evas_map_point_color_get(const Evas_Map *m, int idx, int *r, int *g, int *b, int *a);
|
||||
/**
|
||||
* @}
|
||||
*/
|
||||
|
||||
/**
|
||||
* @brief Set current object transformation map.
|
||||
*
|
||||
|
|
|
|||
|
|
@ -54,12 +54,6 @@ enum Evas.Font.Hinting_Flags {
|
|||
bytecode [[Bytecode font hinting]]
|
||||
}
|
||||
|
||||
struct Evas.Map; [[An opaque handle to map points
|
||||
|
||||
See \@ref evas_map_new, \@ref evas_map_free,
|
||||
\@ref evas_map_dup.
|
||||
]]
|
||||
|
||||
enum Evas.Touch_Point_State {
|
||||
[[State of Evas_Coord_Touch_Point]]
|
||||
legacy: Evas_Touch_Point;
|
||||
|
|
|
|||
Loading…
Reference in New Issue