1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473

mixin Efl.Gfx.Map (Efl.Interface, Efl.Object)
{
[[Texture UV mapping for all objects (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.
At the moment of writing, maps can only have 4 points (no more, no less).
@since 1.20
]]
methods {
map_has {
[[Readonly property indicating whether an object is mapped.
This will be $true if any transformation is applied to this object.
]]
return: bool; [[$true if the object is mapped.]]
}
map_reset {
[[Resets the map transformation to its default state.
This will reset all transformations to identity, meaning the points'
colors, positions and UV coordinates will be reset to their default
values. @.map_has will then return $false. This function will
not modify the values of @.map_smooth or @.map_alpha.
]]
}
@property map_point_count {
[[Number of points of a map.
This sets the number of points of map.
Currently, the number of points must be multiples of 4.
]]
values {
count: int; [[The number of points of map]]
}
}
@property map_clockwise {
[[Clockwise state of a map (readonly).
This determines if the output points (X and Y. Z is not used) are
clockwise or counterclockwise. This can be used for "backface
culling". This is where you hide objects that "face away" from you.
In this case objects that are not clockwise.
]]
get {}
values {
cw: bool; [[$true if clockwise, $false if counter clockwise]]
}
}
// FIXME: This needs modes such as "default", "smooth", "fast", "fastest"
// In SW: default, fast and fastest are not smooth
// In GL: All but fastest are smooth
// Same remark for alpha  it's only for performance
// Same remark for (MISSING) antialiasing
@property map_smooth {
[[Smoothing state 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.
]]
values {
smooth: bool; [[$true by default.]]
}
}
@property map_alpha {
[[Alpha flag for map rendering.
This sets alpha flag for map rendering. If the object is a type that
has its own alpha settings, then this will take precedence. Only
image objects support this currently (@Efl.Canvas.Image and its
friends). Setting this off stops alpha blending of the map area,
and is useful if you know the object and/or all subobjects is 100%
solid.
Note that this may conflict with @.map_smooth depending on which
algorithm is used for antialiasing.
]]
values {
alpha: bool; [[$true by default.]]
}
}
@property map_coord_absolute {
[[A point's absolute coordinate on the canvas.
This sets/gets the fixed point's coordinate in the map. Note that points
describe the outline of a quadrangle and are ordered either clockwise
or counterclockwise. It is suggested to keep your quadrangles concave and
noncomplex, 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 the canvas.
This property can be read to get the 4 points positions on the
canvas, or set to manually place them.
]]
keys {
idx: int; [[ID of the point, from 0 to 3 (included).]]
}
values {
x: double; [[Point X coordinate in absolute pixel coordinates.]]
y: double; [[Point Y coordinate in absolute pixel coordinates.]]
z: double; [[Point Z coordinate hint (preperspective transform).]]
}
}
@property map_uv {
[[Map point's U and V texture source point.
This sets/gets the U and V coordinates for the point. This determines
which coordinate in the source image is mapped to the given point,
much like OpenGL and textures. Valid values range from 0.0 to 1.0.
By default the points are set in a clockwise order, as such:
 0: topleft, i.e. (0.0, 0.0),
 1: topright, i.e. (1.0, 0.0),
 2: bottomright, i.e. (1.0, 1.0),
 3: bottomleft, i.e. (0.0, 1.0).
]]
keys {
idx: int; [[ID of the point, from 0 to 3 (included).]]
}
values {
u: double; [[Relative X coordinate within the image, from 0 to 1.]]
v: double; [[Relative Y coordinate within the image, from 0 to 1.]]
}
}
@property map_color {
[[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.
The color values must be premultiplied (ie. $a >= {$r, $g, $b}).
]]
keys {
idx: int; [[ID of the point, from 0 to 3 (included).
1 can be used to set the color for all points,
but it is invalid for get().]]
}
values {
r: int; [[Red (0  255)]]
g: int; [[Green (0  255)]]
b: int; [[Blue (0  255)]]
a: int; [[Alpha (0  255)]]
}
}
translate {
[[Apply a translation to the object using map.
This does not change the real geometry of the object but will affect
its visible position.
]]
params {
dx: double; [[Distance in pixels along the X axis.]]
dy: double; [[Distance in pixels along the Y axis.]]
dz: double; [[Distance in pixels along the Z axis.]]
}
}
// Transformations with a relative coordinates pivot
// FIXME: pivot & center need to be optional, but double(0.5) doesn't work!
rotate {
[[Apply a rotation to the object.
This rotates the object clockwise by $degrees degrees, around the
center specified by the relative position ($cx, $cy) in the $pivot
object. If $pivot is $null then this object is used as its own pivot
center. 360 degrees is a full rotation, equivalent to no rotation.
Negative values for $degrees will rotate clockwise by that amount.
The coordinates are set relative to the given $pivot object. If its
geometry changes, then the absolute position of the rotation center
will change accordingly.
By default, the center is at (0.5, 0.5). 0.0 means left or top while
1.0 means right or bottom of the $pivot object.
]]
params {
degrees: double; [[CCW rotation in degrees.]]
pivot: const(Efl.Gfx); [[A pivot object for the center point, can be $null.]]
cx: double; [[X relative coordinate of the center point.]]
cy: double; [[y relative coordinate of the center point.]]
}
}
rotate_3d {
[[Rotate the object around 3 axes in 3D.
This will rotate in 3D and not just around the "Z" axis as the case
with @.rotate. This will rotate around the X, Y and Z axes. The
Z axis points "into" the screen with low values at the screen and
higher values further away. The X axis runs from left to right on
the screen and the Y axis from top to bottom.
As with @.rotate, you provide a pivot and center point to rotate
around (in 3D). The Z coordinate of this center point is an absolute
value, and not a relative one like X and Y, as objects are flat in a
2D space.
]]
params {
dx: double; [[Rotation in degrees around X axis (0 to 360).]]
dy: double; [[Rotation in degrees around Y axis (0 to 360).]]
dz: double; [[Rotation in degrees around Z axis (0 to 360).]]
pivot: const(Efl.Gfx); [[A pivot object for the center point, can be $null.]]
cx: double; [[X relative coordinate of the center point.]]
cy: double; [[y relative coordinate of the center point.]]
cz: double; [[Z absolute coordinate of the center point.]]
}
}
rotate_quat {
[[Rotate the object in 3D using a unit quaternion.
This is similar to @.rotate_3d but uses a unit quaternion (also
known as versor) rather than a direct anglebased rotation around a
center point. Use this to avoid gimbal locks.
As with @.rotate, you provide a pivot and center point to rotate
around (in 3D). The Z coordinate of this center point is an absolute
value, and not a relative one like X and Y, as objects are flat in a
2D space.
]]
params {
qx: double; [[The x component of the imaginary part of the quaternion.]]
qy: double; [[The y component of the imaginary part of the quaternion.]]
qz: double; [[The z component of the imaginary part of the quaternion.]]
qw: double; [[The w component of the real part of the quaternion.]]
pivot: const(Efl.Gfx); [[A pivot object for the center point, can be $null.]]
cx: double; [[X relative coordinate of the center point.]]
cy: double; [[y relative coordinate of the center point.]]
cz: double; [[Z absolute coordinate of the center point.]]
}
}
zoom {
[[Apply a zoom to the object.
This zooms the points of the map from a center point. That center is
defined by $cx and $cy. The $zoomx and $zoomy parameters specify how
much to zoom in the X and Y direction respectively.
A value of 1.0 means "don't zoom". 2.0 means "double the size". 0.5 is
"half the size" etc.
By default, the center is at (0.5, 0.5). 0.0 means left or top while
1.0 means right or bottom.
]]
params {
zoomx: double; [[Zoom in X direction]]
zoomy: double; [[Zoom in Y direction]]
pivot: const(Efl.Gfx); [[A pivot object for the center point, can be $null.]]
cx: double; [[X relative coordinate of the center point.]]
cy: double; [[y relative coordinate of the center point.]]
}
}
lightning_3d {
[[Apply a lightning effect on the object.
This is used to apply lighting calculations (from a single light
source) to a given mapped object. The R, G and B values of each
vertex will be modified to reflect the lighting based on the light
point coordinates, the light color and the ambient color, and at
what angle the map is facing the light source. A surface should have
its points be declared in a clockwise fashion if the face is
"facing" towards you (as opposed to away from you) as faces have a
"logical" side for lighting.
The coordinates are set relative to the given $pivot object. If its
geometry changes, then the absolute position of the rotation center
will change accordingly. The Z position is absolute. If the $pivot
is $null then this object will be its own pivot.
]]
params {
pivot: const(Efl.Gfx); [[A pivot object for the light point, can be $null.]]
lx: double; [[X relative coordinate in space of light point.]]
ly: double; [[Y relative coordinate in space of light point.]]
lz: double; [[Z absolute coordinate in space of light point.]]
lr: int; [[Light red value (0  255).]]
lg: int; [[Light green value (0  255).]]
lb: int; [[Light blue value (0  255).]]
ar: int; [[Ambient color red value (0  255).]]
ag: int; [[Ambient color green value (0  255).]]
ab: int; [[Ambient color blue value (0  255).]]
}
}
perspective_3d {
[[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. 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.
The coordinates are set relative to the given $pivot object. If its
geometry changes, then the absolute position of the rotation center
will change accordingly. The Z position is absolute. If the $pivot
is $null then this object will be its own pivot.
]]
params {
pivot: const(Efl.Gfx); [[A pivot object for the infinite point, can be $null.]]
px: double; [[The perspective distance X relative coordinate.]]
py: double; [[The perspective distance Y relative coordinate.]]
z0: double; [[The "0" Z plane value.]]
foc: double; [[The focal distance, must be greater than 0.]]
}
}
// Transformations with an absolute center
rotate_absolute {
[[Apply a rotation to the object, using absolute coordinates.
This rotates the object clockwise by $degrees degrees, around the
center specified by the relative position ($cx, $cy) in the $pivot
object. If $pivot is $null then this object is used as its own pivot
center. 360 degrees is a full rotation, equivalent to no rotation.
Negative values for $degrees will rotate clockwise by that amount.
The given coordinates are absolute values in pixels. See also
@.rotate for a relative coordinate version.
]]
params {
degrees: double; [[CCW rotation in degrees.]]
cx: double; [[X absolute coordinate in pixels of the center point.]]
cy: double; [[y absolute coordinate in pixels of the center point.]]
}
}
rotate_3d_absolute {
[[Rotate the object around 3 axes in 3D, using absolute coordinates.
This will rotate in 3D and not just around the "Z" axis as the case
with @.rotate. This will rotate around the X, Y and Z axes. The
Z axis points "into" the screen with low values at the screen and
higher values further away. The X axis runs from left to right on
the screen and the Y axis from top to bottom.
The coordinates of the center point are given in absolute canvas
coordinates. See also @.rotate_3d for a pivotbased 3D rotation.
]]
params {
dx: double; [[Rotation in degrees around X axis (0 to 360).]]
dy: double; [[Rotation in degrees around Y axis (0 to 360).]]
dz: double; [[Rotation in degrees around Z axis (0 to 360).]]
cx: double; [[X absolute coordinate in pixels of the center point.]]
cy: double; [[y absolute coordinate in pixels of the center point.]]
cz: double; [[Z absolute coordinate of the center point.]]
}
}
rotate_quat_absolute {
[[Rotate the object in 3D using a unit quaternion, using absolute
coordinates.
This is similar to @.rotate_3d but uses a unit quaternion (also
known as versor) rather than a direct anglebased rotation around a
center point. Use this to avoid gimbal locks.
The coordinates of the center point are given in absolute canvas
coordinates. See also @.rotate_quat for a pivotbased 3D rotation.
]]
params {
qx: double; [[The x component of the imaginary part of the quaternion.]]
qy: double; [[The y component of the imaginary part of the quaternion.]]
qz: double; [[The z component of the imaginary part of the quaternion.]]
qw: double; [[The w component of the real part of the quaternion.]]
cx: double; [[X absolute coordinate in pixels of the center point.]]
cy: double; [[y absolute coordinate in pixels of the center point.]]
cz: double; [[Z absolute coordinate of the center point.]]
}
}
zoom_absolute {
[[Apply a zoom to the object, using absolute coordinates.
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.
The coordinates of the center point are given in absolute canvas
coordinates. See also @.zoom for a pivotbased zoom.
]]
params {
zoomx: double; [[Zoom in X direction]]
zoomy: double; [[Zoom in Y direction]]
cx: double; [[X absolute coordinate in pixels of the center point.]]
cy: double; [[y absolute coordinate in pixels of the center point.]]
}
}
lightning_3d_absolute {
[[Apply a lightning effect on the object.
This is used to apply lighting calculations (from a single light
source) to a given mapped object. The R, G and B values of each
vertex will be modified to reflect the lighting based on the light
point coordinates, the light color and the ambient color, and at
what angle the map is facing the light source. A surface should have
its points be declared in a clockwise fashion if the face is
"facing" towards you (as opposed to away from you) as faces have a
"logical" side for lighting.
The coordinates of the center point are given in absolute canvas
coordinates. See also @.lightning_3d for a pivotbased lightning
effect.
]]
params {
lx: double; [[X absolute coordinate in pixels of the light point.]]
ly: double; [[y absolute coordinate in pixels of the light point.]]
lz: double; [[Z absolute coordinate in space of light point.]]
lr: int; [[Light red value (0  255).]]
lg: int; [[Light green value (0  255).]]
lb: int; [[Light blue value (0  255).]]
ar: int; [[Ambient color red value (0  255).]]
ag: int; [[Ambient color green value (0  255).]]
ab: int; [[Ambient color blue value (0  255).]]
}
}
perspective_3d_absolute {
[[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. 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.
The coordinates of the center point are given in absolute canvas
coordinates. See also @.perspective_3d for a pivotbased perspective
effect.
]]
params {
px: double; [[The perspective distance X relative coordinate.]]
py: double; [[The perspective distance Y relative coordinate.]]
z0: double; [[The "0" Z plane value.]]
foc: double; [[The focal distance, must be greater than 0.]]
}
}
}
implements {
Efl.Object.constructor;
Efl.Object.destructor;
}
}
