efl.evas.Map
Class¶
- class efl.evas.Map(int count)¶
Bases:
object
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.
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’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().
- alpha¶
The 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.
- Type
bool
- alpha_get()¶
- alpha_set(alpha)¶
- coords_get(x, y, grab)¶
Apply a map transformation on given coordinate.
- Parameters
x (double) – point x source coordinate
y (double) – point y source coordinate
grab (int) – unknown
- Returns
coordinates after transformation by map
- Return type
tuple of 2 doubles (mx, my)
- Raises
RuntimeError – when interpolation fail
New in version 1.20.
- count¶
Get a maps size.
Returns the number of points in a map. Should be at least 4.
- Type
int (-1 on error)
- count_get()¶
- delete()¶
delete the map object
- point_color_get(idx)¶
Get the color set on a vertex in the map
This gets the color set by point_color_set() on the given vertex of the map.
- Parameters
idx – index of point get. Must be smaller than map size.
- Returns
the tuple (r, g, b, a)
- Return type
tuple of int
- point_color_set(idx, r, g, b, a)¶
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.
- Parameters
idx – index of point to change. Must be smaller than map size.
r – red (0 - 255)
g – green (0 - 255)
b – blue (0 - 255)
a – alpha (0 - 255)
- point_coord_get(idx)¶
Get the map point’s coordinate.
This returns the coordinates of the given point in the map.
- Parameters
idx – index of point to query. Must be smaller than map size.
- Returns
the tuple (x, y, z)
- Return type
tuple of 3 int
- point_coord_set(idx, x, y, z)¶
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.
- Parameters
idx – index of point to change. Must be smaller than map size.
x – Point X Coordinate
y – Point Y Coordinate
z – Point Z Coordinate hint (pre-perspective transform)
- point_image_uv_get(idx)¶
Get the map point’s U and V texture source points
This returns the texture points set by evas_map_point_image_uv_set().
- Parameters
idx – index of point to query. Must be smaller than map size.
- Returns
the tuple (u, v)
- Return type
tuple of double
- point_image_uv_set(idx, u, v)¶
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.
- Parameters
idx – index of point to change. Must be smaller than map size.
u – the X coordinate within the image/texture source
v – the Y coordinate within the image/texture source
- smooth¶
The smoothing state 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.
- Type
bool
- smooth_get()¶
- smooth_set(smooth)¶
- util_3d_lighting(lx, ly, lz, lr, lg, lb, ar, ag, ab)¶
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 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 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.
- Parameters
lx – X coordinate in space of light point
ly – Y coordinate in space of light point
lz – Z coordinate in space of light point
lr – light red value (0 - 255)
lg – light green value (0 - 255)
lb – light blue value (0 - 255)
ar – ambient color red value (0 - 255)
ag – ambient color green value (0 - 255)
ab – ambient color blue value (0 - 255)
- util_3d_perspective(px, py, z0, foc)¶
Apply a perspective transform to the map
This applies a given perspective (3D) to the map coordinates. X, Y and Z values are used. The px and py points specify the “infinite distance” point in the 3D conversion (where all lines converge to like when artists draw 3D by hand). The
z0
value specifies the z value at which there is a 1:1 mapping between spatial coordinates and screen coordinates. Any points on this z value will not have their X and Y values modified in the transform. Those further away (Z value higher) will shrink into the distance, and those less than this value will expand and become bigger. Thefoc
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 andfoc
must be greater than 0.- Parameters
m – map to change.
px – The perspective distance X coordinate
py – The perspective distance Y coordinate
z0 – The “0” z plane value
foc – The focal distance
- util_3d_rotate(dx, dy, dz, cx, cy, cz)¶
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).
- Parameters
dx – amount of degrees from 0.0 to 360.0 to rotate around X axis.
dy – amount of degrees from 0.0 to 360.0 to rotate around Y axis.
dz – amount of degrees from 0.0 to 360.0 to rotate around Z axis.
cx – rotation’s center horizontal position.
cy – rotation’s center vertical position.
cz – rotation’s center vertical position.
- util_clockwise¶
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.
- Returns
1 if clockwise, 0 otherwise
- util_clockwise_get()¶
- util_object_move_sync¶
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 True, 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.
- Type
bool
New in version 1.13.
- util_object_move_sync_get()¶
- util_object_move_sync_set(enabled)¶
- util_points_color_set(r, g, b, a)¶
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.
- Parameters
r – red (0 - 255)
g – green (0 - 255)
b – blue (0 - 255)
a – alpha (0 - 255)
- util_points_populate_from_geometry(x, y, w, h, z)¶
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()).
- Parameters
x – Point X Coordinate
y – Point Y Coordinate
w – width to use to calculate second and third points.
h – height to use to calculate third and fourth points.
z – Point Z Coordinate hint (pre-perspective transform). This value will be used for all four points.
- util_points_populate_from_object(obj)¶
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).
- Parameters
obj – object to use unmapped geometry to populate map coordinates.
- util_points_populate_from_object_full(obj, 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.
- Parameters
obj – object to use unmapped geometry to populate map coordinates.
z – Point Z Coordinate hint (pre-perspective transform). This value will be used for all four points.
- util_quat_rotate(qx, qy, qz, qw, cx, cy, 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).
- Parameters
qx – the x component of the imaginary part of the quaternion.
qy – the y component of the imaginary part of the quaternion.
qz – the z component of the imaginary part of the quaternion.
qw – the w component of the real part of the quaternion.
cx – rotation’s center x.
cy – rotation’s center y.
cz – rotation’s center z.
Attention
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.
- util_rotate(degrees, cx, cy)¶
Change the map to apply the given rotation.
This rotates the indicated map’s coordinates around the center coordinate given by cx and cy as the rotation center. The points will have their X and Y coordinates rotated clockwise by degrees degrees (360.0 is a full rotation). Negative values for degrees will rotate counter-clockwise by that amount. All coordinates are canvas global coordinates.
- Parameters
degrees – amount of degrees from 0.0 to 360.0 to rotate.
cx – rotation’s center horizontal position.
cy – rotation’s center vertical position.
- util_zoom(zoomx, zoomy, cx, 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 cx and cy. The zoomx and zoomy parameters specify how much to zoom in the X and Y direction respectively. A value of 1.0 means “don’t zoom”. 2.0 means “double the size”. 0.5 is “half the size” etc. All coordinates are canvas global coordinates.
- Parameters
zoomx – horizontal zoom to use.
zoomy – vertical zoom to use.
cx – zooming center horizontal position.
cy – zooming center vertical position.