This group provides functions for UV mapping.

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 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.

Remarks:: Applying mapping reduces performance, so use with care. The impact on performance depends on the engine in use. The software is quite optimized, but not as fast as OpenGL.

Map points

Rotation

A map consists of a set of points, currently only four are supported. Each of these points contains a set of canvas coordinates x and y that can be used to alter the geometry of the mapped object, and a z coordinate that indicates the depth of that point. This last coordinate does not normally affect the map, but it is 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.

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 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.

 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);

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.

As said before, the z coordinate is unused here so when setting points by hand, its value is of no importance.

In all three cases above, setting the map to be used by the object is the same.

 evas_object_map_set(o, m);
 evas_object_map_enable_set(o, EINA_TRUE);

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.

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:

 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);

which rotates the object around its center point in a 45 degree angle in the clockwise direction, taking it from this

to this

Objects may be rotated around any other point just by setting the last two parameters 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

 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);

produces something like

And the following

 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);

rotates the object around the center of the window

3D Maps

Maps can also be used to achieve the effect of 3-dimensionality. When doing this, the 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 each corner of the object with which it is identified within the map.

Rotating this map around the Y axis would leave the order of the points in a counter-clockwise fashion, as seen in the following image.

This way we can say that we are looking at the back face of the object. This has stronger implications later when we talk about lighting.

To know if a map is facing towards the user or not it is 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.

3D rotation and perspective

Much like evas_map_util_rotate(), there is 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 z coordinate too. The rotation can also be around any of the 3 axis.

Starting from this simple setup

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 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 Z one not appearing due to being orthogonal to the screen.

which does not 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:

Color and lighting

Each point in a map can be set to a color, which is 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 faces away from the user and thus become obscured, since no light would be reflecting from it.

Note:: Object facing the light source

Note:: Same object facing away from the user

mapping

Images need some special handling when mapped. Evas can easily take care of objects and do almost anything with them, but it is 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.

Once Evas knows how to handle the source image within the map, it transforms 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().

 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);

Maps can also be set to use part of an image only, or even map them inverted, and when combined with evas_object_image_source_set() it can be used to achieve more interesting results.

 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);

Functions
void	evas_object_map_enable_set (Evas_Object *obj, Eina_Bool enabled)
	Enables or disables the map that is set.
Eina_Bool	evas_object_map_enable_get (const Evas_Object *obj)
	Checks whether the map is enabled.
void	evas_object_map_set (Evas_Object obj, const Evas_Map map)
	Sets current object transformation map.
const Evas_Map *	evas_object_map_get (const Evas_Object *obj)
	Gets the current object transformation map.
void	evas_map_util_points_populate_from_object_full (Evas_Map m, const Evas_Object obj, Evas_Coord z)
	Populates source and destination map points to exactly match the object.
void	evas_map_util_points_populate_from_object (Evas_Map m, const Evas_Object obj)
	Populates the source and destination map points to exactly match the object.
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)
	Populates the source and destination map points to match the given geometry.
void	evas_map_util_points_color_set (Evas_Map *m, int r, int g, int b, int a)
	Sets the given color for all the points.
void	evas_map_util_rotate (Evas_Map *m, double degrees, Evas_Coord cx, Evas_Coord cy)
	Changes the map to apply the given rotation.
void	evas_map_util_zoom (Evas_Map *m, double zoomx, double zoomy, Evas_Coord cx, Evas_Coord cy)
	Changes the map to apply the given zooming.
void	evas_map_util_3d_rotate (Evas_Map *m, double dx, double dy, double dz, Evas_Coord cx, Evas_Coord cy, Evas_Coord cz)
	Rotates the map around 3 axes in 3D.
void	evas_map_util_quat_rotate (Evas_Map *m, double qx, double qy, double qz, double qw, double cx, double cy, double cz)
	Rotates the map in 3D using a unit quaternion.
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)
	Performs lighting calculations on the given map.
void	evas_map_util_3d_perspective (Evas_Map *m, Evas_Coord px, Evas_Coord py, Evas_Coord z0, Evas_Coord foc)
	Applies a perspective transform to the map.
Eina_Bool	evas_map_util_clockwise_get (Evas_Map *m)
	Gets the clockwise state of a map.
Evas_Map *	evas_map_new (int count)
	Creates a map of transformation points to be later used with an Evas object.
void	evas_map_smooth_set (Evas_Map *m, Eina_Bool enabled)
	Sets the smoothing for map rendering.
Eina_Bool	evas_map_smooth_get (const Evas_Map *m)
void	evas_map_alpha_set (Evas_Map *m, Eina_Bool enabled)
	Sets the alpha flag for map rendering.
Eina_Bool	evas_map_alpha_get (const Evas_Map *m)
	Gets the alpha flag for map rendering.
Evas_Map *	evas_map_dup (const Evas_Map *m)
	Copies a previously allocated map.
void	evas_map_free (Evas_Map *m)
	Frees a previously allocated map.
int	evas_map_count_get (const Evas_Map *m)
	Gets a maps size.
void	evas_map_point_coord_set (Evas_Map *m, int idx, Evas_Coord x, Evas_Coord y, Evas_Coord z)
	Changes the map point's coordinate.
void	evas_map_point_coord_get (const Evas_Map m, int idx, Evas_Coord x, Evas_Coord y, Evas_Coord z)
	Gets the map point's coordinate.
void	evas_map_point_image_uv_set (Evas_Map *m, int idx, double u, double v)
	Changes the map point's U and V texture source point.
void	evas_map_point_image_uv_get (const Evas_Map m, int idx, double u, double *v)
	Gets the map point's U and V texture source points.
void	evas_map_point_color_set (Evas_Map *m, int idx, int r, int g, int b, int a)
	Sets the color of a vertex in the map.
void	evas_map_point_color_get (const Evas_Map m, int idx, int r, int g, int b, int *a)
	Gets the color set on a vertex in the map.
Typedefs
typedef struct _Evas_Map	Evas_Map
	An opaque handle to map points.

Typedef Documentation

Evas_Map

An opaque handle to map points.

See also:: evas_map_new(); evas_map_free(); evas_map_dup()

Function Documentation

Eina_Bool evas_map_alpha_get ( const Evas_Map * m )

Gets the alpha flag for map rendering.

This gets the alpha flag for map rendering.

Since :: 2.3.1

Parameters:

[in] m The map to get the alpha from
This must not be NULL.

Returns:: The alpha flag

void evas_map_alpha_set	(	Evas_Map *	m,
		Eina_Bool	enabled
	)

Sets the alpha flag for map rendering.

This function sets alpha flag for map rendering. If the object is a type that has its own alpha settings, then this takes 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.

Since :: 2.3.1

Parameters:

[in]	m	The map to modify This must not be `NULL`.
[in]	enabled	Set EINA_TRUE to enable alpha map rendering, otheriwse set EINA_FALSE to disable alpha map rendering

int evas_map_count_get ( const Evas_Map * m )

Gets a maps size.

Since :: 2.3.1

Remarks:: This function returns the number of points in a map. It should be at least be 4.

Parameters:

[in] m The map to get the size

Returns:: The number of points in a map,
otherwise -1 on error

Evas_Map* evas_map_dup ( const Evas_Map * m )

Copies a previously allocated map.

This makes a duplicate of the m object and returns it.

Since :: 2.3.1

Parameters:

[in] m The map to copy
This must not be NULL.

Returns:: The newly allocated map with the same count and contents as m

void evas_map_free ( Evas_Map * m )

Frees a previously allocated map.

This function frees a given map m and all memory associated with it. You must NOT free a map returned by evas_object_map_get() as this is internal.

Since :: 2.3.1

Parameters:

[in] m The map to free

Evas_Map* evas_map_new ( int count )

Creates a map of transformation points to be later used with an Evas object.

This function creates a set of points (currently only 4 is supported and no other number for count works). That is empty and ready to be modified with evas_map calls.

Since :: 2.3.1

Parameters:

[in] count The number of points in the map

Returns:: The newly allocated map,
otherwise NULL on errors

See also:: evas_map_free(); evas_map_dup(); evas_map_point_coord_set(); evas_map_point_image_uv_set(); evas_map_util_points_populate_from_object_full(); evas_map_util_points_populate_from_object(); evas_object_map_set()

void evas_map_point_color_get	(	const Evas_Map *	m,
		int	idx,
		int *	r,
		int *	g,
		int *	b,
		int *	a
	)

Gets the color set on a vertex in the map.

This function gets the color set by evas_map_point_color_set() on the given vertex of the map.

Since :: 2.3.1

Parameters:

[in]	m	The map to get the color of the vertex from
[in]	idx	The index of point get This must be smaller than the map size.
[out]	r	The pointer to red color
[out]	g	The pointer to green color
[out]	b	The pointer to blue color
[out]	a	The pointer to alpha color (0 - 255)

See also:: evas_map_point_coord_set(); evas_object_map_set()

void evas_map_point_color_set	(	Evas_Map *	m,
		int	idx,
		int	r,
		int	g,
		int	b,
		int	a
	)

Sets the color of a vertex in the map.

This sets the color of the vertex in the map. Colors are linearly interpolated between vertex points through the map. Color multiplies 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 has no affect on modifying the texture pixels.

Since :: 2.3.1

Parameters:

[in]	m	The map to change the color of
[in]	idx	The index of point to change This must be smaller than the map size.
[in]	r	The red color (0 - 255)
[in]	g	The green color (0 - 255)
[in]	b	The blue color (0 - 255)
[in]	a	The alpha color (0 - 255)

See also:: evas_map_util_points_color_set(); evas_map_point_coord_set(); evas_object_map_set()

void evas_map_point_coord_get	(	const Evas_Map *	m,
		int	idx,
		Evas_Coord *	x,
		Evas_Coord *	y,
		Evas_Coord *	z
	)

Gets the map point's coordinate.

This function returns the coordinates of the given point in the map.

Since :: 2.3.1

Parameters:

[in]	m	The map to query point
[in]	idx	The index of point to query This must be smaller than the map size.
[out]	x	The X coordinate
[out]	y	The Y coordinate
[out]	z	The Z coordinate

void evas_map_point_coord_set	(	Evas_Map *	m,
		int	idx,
		Evas_Coord	x,
		Evas_Coord	y,
		Evas_Coord	z
	)

Changes the map point's coordinate.

This function 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 uses points 0 and 1 , 1 and 2, 2 and 3, and 3 and 0 to describe the edges of the quadrangle.

Since :: 2.3.1

Remarks:: The X, 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.

Parameters:

[in]	m	The map to change point This must not be `NULL`.
[in]	idx	The index of point to change This must be smaller than map size.
[in]	x	The X coordinate
[in]	y	The Y coordinate
[in]	z	The Z coordinate hint (pre-perspective transform)

See also:: evas_map_util_rotate(); evas_map_util_zoom(); evas_map_util_points_populate_from_object_full(); evas_map_util_points_populate_from_object()

void evas_map_point_image_uv_get	(	const Evas_Map *	m,
		int	idx,
		double *	u,
		double *	v
	)

Gets the map point's U and V texture source points.

This function returns the texture points set by evas_map_point_image_uv_set().

Since :: 2.3.1

Parameters:

[in]	m	The map to query point
[in]	idx	The index of point to query This must be smaller than map size.
[out]	u	The X coordinate within the image or texture source
[out]	v	The Y coordinate within the image or texture source

void evas_map_point_image_uv_set	(	Evas_Map *	m,
		int	idx,
		double	u,
		double	v
	)

Changes 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. Note that these points do select the pixel, but are double floating point values to allow for accuracy and sub-pixel selection.

Since :: 2.3.1

Parameters:

[in]	m	The map to change the point of
[in]	idx	The index of point to change This must be smaller than map size.
[in]	u	The X coordinate within the image or texture source
[in]	v	The Y coordinate within the image or texture source

See also:: evas_map_point_coord_set(); evas_object_map_set(); evas_map_util_points_populate_from_object_full(); evas_map_util_points_populate_from_object()

Eina_Bool evas_map_smooth_get ( const Evas_Map * m )

Checks whether the smoothing for map rendering is enabled.

This gets smoothing for map rendering.

Since :: 2.3.1

Parameters:

[in] m The map for which to get the smoothing status
This must not be NULL.

Returns:: EINA_TRUE if smoothing for map rendering is enabled,
otherwise EINA_FALSE if smoothing for map rendering is not enabled

void evas_map_smooth_set	(	Evas_Map *	m,
		Eina_Bool	enabled
	)

Sets the smoothing for map rendering.

This function 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.

Since :: 2.3.1

Parameters:

[in]	m	The map to modify This must not be `NULL`.
[in]	enabled	Set EINA_TRUE to enable smooth map rendering, otherwise set EINA_FALSE not to enable smooth map rendering

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
	)

Performs lighting calculations on the given map.

This function is used to apply lighting calculations (from a single light source) to a given map. The R, G and B values of each vertex is modified to reflect the lighting based on the lixth 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 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.

Since :: 2.3.1

Remarks:: Grey object, no lighting used

Remarks:: Lights out! Every color set to 0

Remarks:: Ambient light to full black, red light coming from close at the bottom-left vertex.

Remarks:: Same light as before, but not the light is set to 0 and ambient light is cyan.

Remarks:: Both lights are on.

Remarks:: Both lights again, but this time both are the same color.

Parameters:

[in]	m	The map to change
[in]	lx	The X coordinate in space of light point
[in]	ly	The Y coordinate in space of light point
[in]	lz	The Z coordinate in space of light point
[in]	lr	The light red value (0 - 255)
[in]	lg	The light green value (0 - 255)
[in]	lb	The light blue value (0 - 255)
[in]	ar	The ambient color red value (0 - 255)
[in]	ag	The ambient color green value (0 - 255)
[in]	ab	The ambient color blue value (0 - 255)

void evas_map_util_3d_perspective	(	Evas_Map *	m,
		Evas_Coord	px,
		Evas_Coord	py,
		Evas_Coord	z0,
		Evas_Coord	foc
	)

Applies a perspective transform to the map.

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

Since :: 2.3.1

Parameters:

[in]	m	The map to change
[in]	px	The perspective distance X coordinate
[in]	py	The perspective distance Y coordinate
[in]	z0	The "0" z plane value
[in]	foc	The focal distance

void evas_map_util_3d_rotate	(	Evas_Map *	m,
		double	dx,
		double	dy,
		double	dz,
		Evas_Coord	cx,
		Evas_Coord	cy,
		Evas_Coord	cz
	)

Rotates the map around 3 axes in 3D.

This function rotates not just around the "Z" axis as in evas_map_util_rotate() (which is a convenience call for those only wanting 2D). This rotates 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).

Since :: 2.3.1

Parameters:

[in]	m	The map to change
[in]	dx	The amount of degrees from `0.0` to `360.0` to rotate around X axis
[in]	dy	The amount of degrees from `0.0` to `360.0` to rotate around Y axis
[in]	dz	The amount of degrees from `0.0` to `360.0` to rotate around Z axis
[in]	cx	The rotation's center horizontal position
[in]	cy	The rotation's center vertical position
[in]	cz	The rotation's center vertical position

Eina_Bool evas_map_util_clockwise_get ( Evas_Map * m )

Gets the clockwise state of a map.

This function 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, the objects that are not clockwise.

Since :: 2.3.1

Parameters:

[in] m The map to query

Returns:: EINA_TRUE if the output points are clockwise, otherwise EINA_FALSE if the output points are not clockwise

void evas_map_util_points_color_set	(	Evas_Map *	m,
		int	r,
		int	g,
		int	b,
		int	a
	)

Sets the given color for all the points.

This function is useful to reuse maps after they had 3D lightning or any other colorization applied before.

Since :: 2.3.1

Parameters:

[in]	m	The map to change the color of
[in]	r	The red color (0 - 255)
[in]	g	The green color (0 - 255)
[in]	b	The blue color (0 - 255)
[in]	a	The alpha color (0 - 255)

See also:: evas_map_point_color_set()

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
	)

Populates the source and destination map points to match the given geometry.

Since :: 2.3.1

Remarks:: 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 is used to calculate destination points (evas_map_point_coord_set()) and set the image uv (evas_map_point_image_uv_set()).

Parameters:

[in]	m	The map to change all 4 points (must be of size 4)
[in]	x	The X coordinate
[in]	y	The Y coordinate
[in]	w	The width to use to calculate second and third points
[in]	h	The height to use to calculate third and fourth points
[in]	z	The Z coordinate hint (pre-perspective transform) This value is used for all four points.

See also:: evas_map_util_points_populate_from_object(); evas_map_point_coord_set(); evas_map_point_image_uv_set()

void evas_map_util_points_populate_from_object	(	Evas_Map *	m,
		const Evas_Object *	obj
	)

Populates the source and destination map points to exactly match the object.

Since :: 2.3.1

Remarks:: You initialize map of an object to match its 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.; The Z point coordinate is assumed as 0 (zero).

Parameters:

[in]	m	The map to change all 4 points (must be of size 4)
[in]	obj	The object to use unmapped geometry to populate map coordinates

See also:: evas_map_util_points_populate_from_object_full(); evas_map_util_points_populate_from_geometry(); evas_map_point_coord_set(); evas_map_point_image_uv_set()

void evas_map_util_points_populate_from_object_full	(	Evas_Map *	m,
		const Evas_Object *	obj,
		Evas_Coord	z
	)

Populates source and destination map points to exactly match the object.

Since :: 2.3.1

Remarks:: You initialize the map of an object to match its 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.

Parameters:

[in]	m	The map to change all 4 points (must be of size 4)
[in]	obj	The object to use unmapped geometry to populate map coordinates
[in]	z	The point Z coordinate hint (pre-perspective transform) This value is used for all four points.

See also:: evas_map_util_points_populate_from_object(); evas_map_point_coord_set(); evas_map_point_image_uv_set()

void evas_map_util_quat_rotate	(	Evas_Map *	m,
		double	qx,
		double	qy,
		double	qz,
		double	qw,
		double	cx,
		double	cy,
		double	cz
	)

Rotates the map in 3D using a unit quaternion.

This function rotates in 3D using a unit quaternion. Like with evas_map_util_3d_rotate() you provide a center point to rotate around (in 3D).

Since (EFL) :: 1.8

Since :: 2.3.1

Remarks:: 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.

Parameters:

[in]	m	The map to change
[in]	qx	The x component of the imaginary part of the quaternion
[in]	qy	The y component of the imaginary part of the quaternion
[in]	qz	The z component of the imaginary part of the quaternion
[in]	qw	The w component of the real part of the quaternion
[in]	cx	The rotation's center x
[in]	cy	The rotation's center y
[in]	cz	The rotation's center z

void evas_map_util_rotate	(	Evas_Map *	m,
		double	degrees,
		Evas_Coord	cx,
		Evas_Coord	cy
	)

Changes the map to apply the given rotation.

This function rotates the indicated map's coordinates around the center coordinate given by cx and cy as the rotation center. The points have their X and Y coordinates rotated clockwise by degrees degrees (360.0 is a full rotation). Negative values for degrees rotate counter-clockwise by that amount. All coordinates are canvas global coordinates.

Since :: 2.3.1

Parameters:

[in]	m	The map to change
[in]	degrees	The amount of degrees from `0.0` to `360.0` to rotate
[in]	cx	The rotation's center horizontal position
[in]	cy	The rotation's center vertical position

See also:: evas_map_point_coord_set(); evas_map_util_zoom()

void evas_map_util_zoom	(	Evas_Map *	m,
		double	zoomx,
		double	zoomy,
		Evas_Coord	cx,
		Evas_Coord	cy
	)

Changes the map to apply the given zooming.

Since :: 2.3.1

Remarks:: Like evas_map_util_rotate(), this zooms the points of the map from a center point. That center is defined by cx and cy. The zoomx and zoomy parameters specify how much to zoom in the X and Y direction respectively. A value of 1.0 means "don't zoom", 2.0 means "double the size", 0.5 is "half the size", and so on. All coordinates are canvas global coordinates.

Parameters:

[in]	m	The map to change
[in]	zoomx	The horizontal zoom to use
[in]	zoomy	The vertical zoom to use
[in]	cx	The zooming center horizontal position
[in]	cy	The zooming center vertical position

See also:: evas_map_point_coord_set(); evas_map_util_rotate()

Eina_Bool evas_object_map_enable_get ( const Evas_Object * obj )

Checks whether the map is enabled.

This function returns the currently enabled state of the map on the object indicated. The default map enable state is off. You can enable and disable it with evas_object_map_enable_set().

Since :: 2.3.1

Parameters:

[in] obj The object to get the map enabled state from

Returns:: EINA_TRUE of the map is enabled,
otherwise EINA_FALSE of the map is not enabled

void evas_object_map_enable_set	(	Evas_Object *	obj,
		Eina_Bool	enabled
	)

Enables or disables the map that is set.

This function enables or disables the use of map for the object obj. When enabled, the object geometry is saved, and the new geometry changes (position and size) to reflect the map geometry set.

Since :: 2.3.1

Remarks:: If the object does not have a map set (with evas_object_map_set()), the initial geometry is undefined. It is advised to always set a map to the object first, and then call this function to enable its use.

Parameters:

[in]	obj	The object to enable the map on
[in]	enabled	Set EINA_TRUE to enable the map, otherwise EINA_FALSE to not enable the map

const Evas_Map* evas_object_map_get ( const Evas_Object * obj )

Gets the current object transformation map.

This function returns the current internal map set on the indicated object. It is intended for read-only access and is only valid as long as the object is not deleted or the map on the object is not changed. If you wish to modify the map and set it back do the following:

Since :: 2.3.1

 const Evas_Map *m = evas_object_map_get(obj);
 Evas_Map *m2 = evas_map_dup(m);
 evas_map_util_rotate(m2, 30.0, 0, 0);
 evas_object_map_set(obj, m2);
 evas_map_free(m2);

Parameters:

[in] obj The object to query transformation map

Returns:: The map reference to the map in use
This is an internal data structure, so do not modify it.

See also:: evas_object_map_set()

void evas_object_map_set	(	Evas_Object *	obj,
		const Evas_Map *	map
	)

Sets current object transformation map.

This function sets the map on a given object. It is copied from the map pointer, so there is no need to keep the map object if you do not need it anymore.

Since :: 2.3.1

Remarks:: A map is a set of 4 points which have canvas x, y coordinates per point, with an optional z point value as a hint for perspective correction, if it is available. As well each point has u and v coordinates. These are like "texture coordinates" in OpenGL in that they define a point in the source image that is mapped to that map vertex or point. The u corresponds to the x coordinate of this mapped point and v, the y coordinate. Note that these coordinates describe a bounding region to sample. If you have a 200x100 source image and want to display it at 200x100 with proper pixel precision, then do the following:

 Evas_Map *m = evas_map_new(4);
 evas_map_point_coord_set(m, 0,   0,   0, 0);
 evas_map_point_coord_set(m, 1, 200,   0, 0);
 evas_map_point_coord_set(m, 2, 200, 100, 0);
 evas_map_point_coord_set(m, 3,   0, 100, 0);
 evas_map_point_image_uv_set(m, 0,   0,   0);
 evas_map_point_image_uv_set(m, 1, 200,   0);
 evas_map_point_image_uv_set(m, 2, 200, 100);
 evas_map_point_image_uv_set(m, 3,   0, 100);
 evas_object_map_set(obj, m);
 evas_map_free(m);

Remarks:: Note that the map points a uv coordinates that match the image geometry. If the map parameter is NULL, the stored map is freed and geometry prior to enabling/setting a map is restored.

Parameters:

[in]	obj	The object to change transformation map
[in]	map	The new map to use

See also:: evas_map_new()

Map points

Rotation

Utility functions

3D Maps

3D rotation and perspective

Color and lighting

mapping

Functions

Typedefs

Typedef Documentation

Function Documentation