jpeg pushed a commit to branch master. http://git.enlightenment.org/core/efl.git/commit/?id=a49bddd124ea819421dc832737cecc0e6a99b8ba
commit a49bddd124ea819421dc832737cecc0e6a99b8ba Author: Jean-Philippe Andre <[email protected]> Date: Tue Jun 28 14:21:58 2016 +0900 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 --- src/lib/evas/Evas_Common.h | 832 ------------------------------------ src/lib/evas/Evas_Legacy.h | 834 +++++++++++++++++++++++++++++++++++++ src/lib/evas/canvas/evas_types.eot | 6 - 3 files changed, 834 insertions(+), 838 deletions(-) diff --git a/src/lib/evas/Evas_Common.h b/src/lib/evas/Evas_Common.h index cb090d9..07b7517 100644 --- a/src/lib/evas/Evas_Common.h +++ b/src/lib/evas/Evas_Common.h @@ -1458,838 +1458,6 @@ EAPI const Evas_Device *evas_device_emulation_source_get(const Evas_Device *dev) */ /** - * @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 * * Objects may carry hints, so that another object that acts as a diff --git a/src/lib/evas/Evas_Legacy.h b/src/lib/evas/Evas_Legacy.h index 7c59c26..c3f5267 100644 --- a/src/lib/evas/Evas_Legacy.h +++ b/src/lib/evas/Evas_Legacy.h @@ -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. * diff --git a/src/lib/evas/canvas/evas_types.eot b/src/lib/evas/canvas/evas_types.eot index ee3cdcc..b545f69 100644 --- a/src/lib/evas/canvas/evas_types.eot +++ b/src/lib/evas/canvas/evas_types.eot @@ -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; --
