aboutsummaryrefslogtreecommitdiffstats
path: root/src/lib/evas/canvas/efl_gfx_map.eo
blob: 9dc5b3246abeb563e165736eff0a90be5d00add5 (plain) (blame)
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 requires 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 {
         [[Read-only 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 (read-only).

           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.
         ]]
         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) anti-aliasing

      @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 to off stops alpha blending of the map area,
           and is useful if you know the object and/or all sub-objects is 100%
           solid.

           Note that this may conflict with @.map_smooth depending on which
           algorithm is used for anti-aliasing.
         ]]
         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 counter-clockwise. Try 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 as 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 (pre-perspective 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: top-left, i.e. (0.0, 0.0),
           - 1: top-right, i.e. (1.0, 0.0),
           - 2: bottom-right, i.e. (1.0, 1.0),
           - 3: bottom-left, 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.Entity); [[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, not just around the "Z" axis as is the case
           with @.rotate. You can 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.Entity); [[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 angle-based 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.Entity); [[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.Entity); [[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 lighting 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.Entity); [[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 under 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.Entity); [[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 pivot-based 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 angle-based 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 pivot-based 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 pivot-based 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 lighting effect to the object.

           This is used to apply lighting calculations (from a single light
           source) to a given mapped object. The RGB values of each
           vertex will be modified to reflect the lighting based on the light
           point coordinates, the light color, 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 pivot-based 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 pivot-based 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;
   }
}