microui  3.1.0
microui
ui_drawing.h
1 /*
2  * Copyright 2020-2023 MicroEJ Corp. All rights reserved.
3  * Use of this source code is governed by a BSD-style license that can be found with this software.
4  */
5 
6 #if !defined UI_DRAWING_H
7 #define UI_DRAWING_H
8 #ifdef __cplusplus
9 extern "C" {
10 #endif
11 
12 /*
13  * @brief Provides drawing functions called by MicroUI native drawing functions.
14  *
15  * Default MicroUI native drawing functions implementations manage the synchronization
16  * with the Graphics Engine and allow a third party drawer perform the drawings.
17  *
18  * This header file lists all drawing functions to implement. This cut between MicroUI
19  * native functions default implementation and this file allows to simplify the
20  * writing of drawing functions: a drawing function has just to consider the drawing
21  * itself and not the synchronization with the Graphics Engine.
22  *
23  * The drawer has the responsibility to check the graphics context (when not disabled
24  * by caller) and to update the new flush dirty area.
25  *
26  * This cut simplifies the MicroUI native function implementation, which becomes:
27  *
28  * void _drawing_native_xxx(MICROUI_GraphicsContext* gc, ...) {
29  * // tell to the Graphics Engine if drawing can be performed
30  * if (LLUI_DISPLAY_requestDrawing(gc, (SNI_callback)&_drawing_native_xxx)) {
31  * // perform the drawings and set drawing status
32  * LLUI_DISPLAY_setDrawingStatus(_drawing_xxx(gc, ...));
33  * }
34  * // else: refused drawing
35  * }
36  *
37  * When clip is checked very early, the native implementation becomes:
38  *
39  * void _drawing_native_xxx(MICROUI_GraphicsContext* gc, ...) {
40  * // tell to the Graphics Engine if drawing can be performed
41  * if (LLUI_DISPLAY_requestDrawing(gc, (SNI_callback)&_drawing_native_xxx)) {
42  * DRAWING_Status status;
43  *
44  * if (LLUI_DISPLAY_isInClip(gc, ...)) {
45  * // perform the drawings
46  * status = _drawing_xxx(gc, ...);
47  * }
48  * else {
49  * // drawing is out of clip: nothing to draw
50  * status = DRAWING_DONE;
51  * }
52  *
53  * // set drawing status
54  * LLUI_DISPLAY_setDrawingStatus(status);
55  * }
56  * // else: refused drawing
57  * }
58  *
59  * This cut allows to use a third party drawer like a dedicated CPU (hardware accelerator).
60  * However, all drawing functions are already implemented in ui_drawing.c as
61  * weak implementation. This allows to override one or several functions without
62  * the need to override all functions. Default ui_drawing.c implementation calls the
63  * Graphics Engine software algorithms.
64  *
65  * The Graphics Engine software algorithms are listed in ui_drawing_soft.h.
66  * This allows to the ui_drawing.h to test if it is able to perform a drawing and
67  * if not, to call the software algorithm instead. For instance a GPU may be able
68  * to draw an image applying a rotation but it can't apply this rotation and an opacity
69  * at the same time. In this case, the drawing implementation function has to check
70  * the parameter "alpha" and calls or not Graphics Engine software algorithm.
71  *
72  * The implementation of these drawings must respect the graphics context clip and
73  * the flush dirty area as explained in LLUI_PAINTER_impl.h.
74  *
75  * @author MicroEJ Developer Team
76  * @version 3.1.0
77  */
78 
79 // --------------------------------------------------------------------------------
80 // Includes
81 // --------------------------------------------------------------------------------
82 
83 #include <LLUI_PAINTER_impl.h>
84 #include <LLDW_PAINTER_impl.h>
85 
86 // --------------------------------------------------------------------------------
87 // Defines
88 // --------------------------------------------------------------------------------
89 
90 /*
91  * @brief Concat two defines
92  */
93 #ifndef CONCAT
94 #define CONCAT0(p,s) p ## s
95 #define CONCAT(p,s) CONCAT0(p,s)
96 #endif
97 
98 // --------------------------------------------------------------------------------
99 // API
100 // --------------------------------------------------------------------------------
101 
102 #if defined(LLUI_GC_SUPPORTED_FORMATS) && (LLUI_GC_SUPPORTED_FORMATS > 1)
103 
104 /*
105  * @brief Tells if drawer "1" matches the destination format. The VEE port must implement
106  * this function when it includes the support to target the destination format. It not, the
107  * default weak implementation in ui_drawing.c redirects all the drawings for this destination
108  * format in the stub implementation.
109  */
110 bool UI_DRAWING_is_drawer_1(jbyte image_format);
111 
112 #if (LLUI_GC_SUPPORTED_FORMATS > 2)
113 /*
114  * @brief Tells drawer "2" matches the destination format. See UI_DRAWING_is_drawer_1.
115  */
116 bool UI_DRAWING_is_drawer_2(jbyte image_format);
117 
118 #endif // #if (LLUI_GC_SUPPORTED_FORMATS > 2)
119 
120 #endif // #if defined(LLUI_GC_SUPPORTED_FORMATS) && (LLUI_GC_SUPPORTED_FORMATS > 1)
121 
122 /*
123  * @brief Returns the new image row stride in bytes.
124  *
125  * @param[in] image_format the new RAW image format. The format is one value from the
126  * MICROUI_ImageFormat enumeration.
127  * @param[in] image_width the new image width (in pixels).
128  * @param[in] image_height the new image height (in pixels).
129  * @param[in] default_stride the minimal row stride (in bytes)
130  *
131  * @return expected row stride (in bytes)
132  *
133  * @see LLUI_DISPLAY_IMPL_getNewImageStrideInBytes()
134  */
135 uint32_t UI_DRAWING_getNewImageStrideInBytes(jbyte image_format, uint32_t image_width, uint32_t image_height, uint32_t default_stride);
136 
137 /*
138  * @brief Adjusts the new image characteristics: data size and alignment.
139  *
140  * @param[in] image_format the new RAW image format. The format is one value from the
141  * MICROUI_ImageFormat enumeration.
142  * @param[in] width the new image width (in pixels).
143  * @param[in] height the new image height (in pixels).
144  * @param[in/out] data_size the minimal data size (in bytes).
145  * @param[in/out] data_alignment the minimal data alignment to respect (in bytes).
146  *
147  * @see LLUI_DISPLAY_IMPL_adjustNewImageCharacteristics()
148  */
149 void UI_DRAWING_adjustNewImageCharacteristics(jbyte image_format, uint32_t width, uint32_t height, uint32_t* data_size, uint32_t* data_alignment);
150 
151 /*
152  * @brief Initializes the image's buffer.
153  *
154  * @param[in] image the MicroUI Image to initialize.
155  *
156  * @see LLUI_DISPLAY_IMPL_initializeNewImage()
157  */
158 void UI_DRAWING_initializeNewImage(MICROUI_Image* image);
159 
160 /*
161  * @brief Frees the image's resources (if any). This function is called just before releasing
162  * the image buffer and closing the image.
163  *
164  * @param[in] image the MicroUI Image to close.
165  *
166  * @see LLUI_DISPLAY_IMPL_freeImageResources()
167  */
168 void UI_DRAWING_freeImageResources(MICROUI_Image* image);
169 
170 /*
171  * @brief Draws a pixel at given position.
172  *
173  * @param[in] gc the MicroUI GraphicsContext target.
174  * @param[in] x the pixel X coordinate.
175  * @param[in] y the pixel Y coordinate.
176  *
177  * @return the drawing status.
178  */
179 DRAWING_Status UI_DRAWING_writePixel(MICROUI_GraphicsContext* gc, jint x, jint y);
180 
181 /*
182  * @brief Draws a line at between points startX,startY (included) and endX,endY (included).
183  * Note: startX may be higher than endX (and/or startY may be higher than endY).
184  *
185  * @param[in] gc the MicroUI GraphicsContext target.
186  * @param[in] startX the first pixel line X coordinate.
187  * @param[in] startY the first pixel line Y coordinate.
188  * @param[in] endX the last pixel line X coordinate.
189  * @param[in] endY the last pixel line Y coordinate.
190  *
191  * @return the drawing status.
192  */
193 DRAWING_Status UI_DRAWING_drawLine(MICROUI_GraphicsContext* gc, jint startX, jint startY, jint endX, jint endY);
194 
195 /*
196  * @brief Draws a horizontal line at between points x1,y (included) and x2,y (included).
197  * Caller ensures that x1 <= x2.
198  *
199  * @param[in] gc the MicroUI GraphicsContext target.
200  * @param[in] x1 the first pixel line X coordinate.
201  * @param[in] x2 the last pixel line X coordinate.
202  * @param[in] y the both pixels line Y coordinate.
203  *
204  * @return the drawing status.
205  */
206 DRAWING_Status UI_DRAWING_drawHorizontalLine(MICROUI_GraphicsContext* gc, jint x1, jint x2, jint y);
207 
208 /*
209  * @brief Draws a vertical line at between points x,y1 (included) and x,y2 (included).
210  * Caller ensures that y1 <= y2.
211  *
212  * @param[in] gc the MicroUI GraphicsContext target.
213  * @param[in] x the both pixels line X coordinate.
214  * @param[in] y1 the first pixel line Y coordinate.
215  * @param[in] y2 the last pixel line Y coordinate.
216  *
217  * @return the drawing status.
218  */
219 DRAWING_Status UI_DRAWING_drawVerticalLine(MICROUI_GraphicsContext* gc, jint x, jint y1, jint y2);
220 
221 /*
222  * @brief Draws an orthogonal rectangle at from top-left point x1,y1 (included) and bottom-right
223  * point x2,y2 (included).
224  * Caller ensures that x1 <= x2 and y1 <= y2.
225  *
226  * @param[in] gc the MicroUI GraphicsContext target.
227  * @param[in] x1 the top-left pixel X coordinate.
228  * @param[in] y1 the top-left pixel Y coordinate.
229  * @param[in] x2 the bottom-right pixel X coordinate.
230  * @param[in] y2 the top-right pixel Y coordinate.
231  *
232  * @return the drawing status.
233  */
234 DRAWING_Status UI_DRAWING_drawRectangle(MICROUI_GraphicsContext* gc, jint x1, jint y1, jint x2, jint y2);
235 
236 /*
237  * @brief Fills a rectangle at from top-left point x1,y1 (included) and bottom-right
238  * point x2,y2 (included).
239  * Caller ensures that x1 <= x2 and y1 <= y2.
240  *
241  * @param[in] gc the MicroUI GraphicsContext target.
242  * @param[in] x1 the top-left pixel X coordinate.
243  * @param[in] y1 the top-left pixel Y coordinate.
244  * @param[in] x2 the bottom-right pixel X coordinate.
245  * @param[in] y2 the top-right pixel Y coordinate.
246  *
247  * @return the drawing status.
248  */
249 DRAWING_Status UI_DRAWING_fillRectangle(MICROUI_GraphicsContext* gc, jint x1, jint y1, jint x2, jint y2);
250 
251 /*
252  * @brief Draws a rounded rectangle at from top-left point x,y (included) and bottom-right
253  * point x+width-1,y+height-1 (included).
254  *
255  * @param[in] gc the MicroUI GraphicsContext target.
256  * @param[in] x the top-left pixel X coordinate.
257  * @param[in] y the top-left pixel Y coordinate.
258  * @param[in] width the rectangle width.
259  * @param[in] height the rectangle height.
260  * @param[in] cornerEllipseWidth the horizontal diameter of the arc at the corners.
261  * @param[in] cornerEllipseHeight the vertical diameter of the arc at the corners.
262  *
263  * @return the drawing status.
264  */
265 DRAWING_Status UI_DRAWING_drawRoundedRectangle(MICROUI_GraphicsContext* gc, jint x, jint y, jint width, jint height, jint cornerEllipseWidth, jint cornerEllipseHeight);
266 
267 /*
268  * @brief Fills a rounded rectangle at from top-left point x,y (included) and bottom-right
269  * point x+width-1,y+height-1 (included).
270  *
271  * @param[in] gc the MicroUI GraphicsContext target.
272  * @param[in] x the top-left pixel X coordinate.
273  * @param[in] y the top-left pixel Y coordinate.
274  * @param[in] width the rectangle width.
275  * @param[in] height the rectangle height.
276  * @param[in] cornerEllipseWidth the horizontal diameter of the arc at the corners.
277  * @param[in] cornerEllipseHeight the vertical diameter of the arc at the corners.
278  *
279  * @return the drawing status.
280  */
281 DRAWING_Status UI_DRAWING_fillRoundedRectangle(MICROUI_GraphicsContext* gc, jint x, jint y, jint width, jint height, jint cornerEllipseWidth, jint cornerEllipseHeight);
282 
283 /*
284  * @brief Draws a circular arc covering the square defined by top-left point x,y (included)
285  * and bottom-right point x+diameter-1,y+diameter-1 (included).
286  *
287  * The arc is drawn from startAngle up to arcAngle degrees. The center of the arc is
288  * defined as the center of the square whose origin is at (x,y) (upper-left corner)
289  * and whose dimension is given by width and height.
290  *
291  * Angles are interpreted such that 0 degrees is at the 3 o'clock position. A positive
292  * value indicates a counter-clockwise rotation while a negative value indicates
293  * a clockwise rotation.
294  *
295  * If either the given diameter is negative or zero, or if arcAngle is zero,
296  * nothing is drawn.
297  *
298  * The angles are given relative to the square. For instance an angle of 45
299  * degrees is always defined by the line from the center of the square to the
300  * upper right corner of the square.
301  *
302  * @param[in] gc the MicroUI GraphicsContext target.
303  * @param[in] x the top-left pixel X coordinate.
304  * @param[in] y the top-left pixel Y coordinate.
305  * @param[in] square the diameter of the arc to draw.
306  * @param[in] startAngle the beginning angle of the arc to draw
307  * @param[in] arcAngle the angular extent of the arc from startAngle
308  *
309  * @return the drawing status.
310  */
311 DRAWING_Status UI_DRAWING_drawCircleArc(MICROUI_GraphicsContext* gc, jint x, jint y, jint diameter, jfloat startAngle, jfloat arcAngle);
312 
313 /*
314  * @brief Draws an elliptical arc covering the rectangle defined by top-left point x,y (included)
315  * and bottom-right point x+width-1,y+height-1 (included).
316  *
317  * The arc is drawn from startAngle up to arcAngle degrees. The center of the arc is
318  * defined as the center of the rectangle whose origin is at (x,y) (upper-left corner)
319  * and whose dimension is given by width and height.
320  *
321  * Angles are interpreted such that 0 degrees is at the 3 o'clock position. A positive
322  * value indicates a counter-clockwise rotation while a negative value indicates
323  * a clockwise rotation.
324  *
325  * If either the given width or height is negative or zero, or if arcAngle is zero,
326  * nothing is drawn.
327  *
328  * The angles are given relative to the rectangle. For instance an angle of 45
329  * degrees is always defined by the line from the center of the rectangle to the
330  * upper right corner of the rectangle. Thus for a non squared rectangle
331  * angles are skewed along either height or width.
332  *
333  * @param[in] gc the MicroUI GraphicsContext target.
334  * @param[in] x the top-left pixel X coordinate.
335  * @param[in] y the top-left pixel Y coordinate.
336  * @param[in] width the rectangle width.
337  * @param[in] height the rectangle height.
338  * @param[in] startAngle the beginning angle of the arc to draw
339  * @param[in] arcAngle the angular extent of the arc from startAngle
340  *
341  * @return the drawing status.
342  */
343 DRAWING_Status UI_DRAWING_drawEllipseArc(MICROUI_GraphicsContext* gc, jint x, jint y, jint width, jint height, jfloat startAngle, jfloat arcAngle);
344 
345 /*
346  * @brief Fills a circular arc covering the square defined by top-left point x,y (included)
347  * and bottom-right point x+diameter-1,y+diameter-1 (included).
348  *
349  * The arc is drawn from startAngle up to arcAngle degrees. The center of the arc is
350  * defined as the center of the rectangle whose origin is at (x,y) (upper-left corner)
351  * and whose dimension is given by width and height.
352  *
353  * Angles are interpreted such that 0 degrees is at the 3 o'clock position. A positive
354  * value indicates a counter-clockwise rotation while a negative value indicates
355  * a clockwise rotation.
356  *
357  * If either the given diameter is negative or zero, or if arcAngle is zero,
358  * nothing is drawn.
359  *
360  * The angles are given relative to the square. For instance an angle of 45
361  * degrees is always defined by the line from the center of the square to the
362  * upper right corner of the square.
363  *
364  * @param[in] gc the MicroUI GraphicsContext target.
365  * @param[in] x the top-left pixel X coordinate.
366  * @param[in] y the top-left pixel Y coordinate.
367  * @param[in] diameter the diameter of the arc to draw.
368  * @param[in] startAngle the beginning angle of the arc to draw
369  * @param[in] arcAngle the angular extent of the arc from startAngle
370  *
371  * @return the drawing status.
372  */
373 DRAWING_Status UI_DRAWING_fillCircleArc(MICROUI_GraphicsContext* gc, jint x, jint y, jint diameter, jfloat startAngle, jfloat arcAngle);
374 
375 /*
376  * @brief Fills an elliptical arc covering the rectangle defined by top-left point x,y (included)
377  * and bottom-right point x+width-1,y+height-1 (included).
378  *
379  * The arc is drawn from startAngle up to arcAngle degrees. The center of the arc is
380  * defined as the center of the rectangle whose origin is at (x,y) (upper-left corner)
381  * and whose dimension is given by width and height.
382  *
383  * Angles are interpreted such that 0 degrees is at the 3 o'clock position. A positive
384  * value indicates a counter-clockwise rotation while a negative value indicates
385  * a clockwise rotation.
386  *
387  * If either the given width or height is negative or zero, or if arcAngle is zero,
388  * nothing is drawn.
389  *
390  * The angles are given relative to the rectangle. For instance an angle of 45
391  * degrees is always defined by the line from the center of the rectangle to the
392  * upper right corner of the rectangle. Thus for a non squared rectangle
393  * angles are skewed along either height or width.
394  *
395  * @param[in] gc the MicroUI GraphicsContext target.
396  * @param[in] x the top-left pixel X coordinate.
397  * @param[in] y the top-left pixel Y coordinate.
398  * @param[in] width the rectangle width.
399  * @param[in] height the rectangle height.
400  * @param[in] startAngle the beginning angle of the arc to draw
401  * @param[in] arcAngle the angular extent of the arc from startAngle
402  *
403  * @return the drawing status.
404  */
405 DRAWING_Status UI_DRAWING_fillEllipseArc(MICROUI_GraphicsContext* gc, jint x, jint y, jint width, jint height, jfloat startAngle, jfloat arcAngle);
406 
407 /*
408  * @brief Draws an ellipse covering the rectangle defined by top-left point x,y (included)
409  * and bottom-right point x+width-1,y+height-1 (included). Ellipses which focal points are not
410  * on the same axis are not supported.
411  *
412  * If either the given width or height is negative or zero, nothing is drawn.
413  *
414  * @param[in] gc the MicroUI GraphicsContext target.
415  * @param[in] x the top-left pixel X coordinate.
416  * @param[in] y the top-left pixel Y coordinate.
417  * @param[in] width the ellipse width.
418  * @param[in] height the ellipse height.
419  *
420  * @return the drawing status.
421  */
422 DRAWING_Status UI_DRAWING_drawEllipse(MICROUI_GraphicsContext* gc, jint x, jint y, jint width, jint height);
423 
424 /*
425  * @brief Fills an ellipse covering the rectangle defined by top-left point x,y (included)
426  * and bottom-right point x+width-1,y+height-1 (included).
427  *
428  * If either the given width or height is negative or zero, nothing is drawn.
429  *
430  * @param[in] gc the MicroUI GraphicsContext target.
431  * @param[in] x the top-left pixel X coordinate.
432  * @param[in] y the top-left pixel Y coordinate.
433  * @param[in] width the ellipse width.
434  * @param[in] height the ellipse height.
435  *
436  * @return the drawing status.
437  */
438 DRAWING_Status UI_DRAWING_fillEllipse(MICROUI_GraphicsContext* gc, jint x, jint y, jint width, jint height);
439 
440 /*
441  * @brief Draws a circle covering the square defined by top-left point x,y (included)
442  * and bottom-right point x+diameter-1,y+diameter-1 (included).
443  *
444  * If the given diameter is negative or zero, nothing is drawn.
445  *
446  * @param[in] gc the MicroUI GraphicsContext target.
447  * @param[in] x the top-left pixel X coordinate.
448  * @param[in] y the top-left pixel Y coordinate.
449  * @param[in] diameter the circle square size.
450  *
451  * @return the drawing status.
452  */
453 DRAWING_Status UI_DRAWING_drawCircle(MICROUI_GraphicsContext* gc, jint x, jint y, jint diameter);
454 
455 /*
456  * @brief Fills a circle covering the square defined by top-left point x,y (included)
457  * and bottom-right point x+diameter-1,y+diameter-1 (included)
458  *
459  * If the given diameter is negative or zero, nothing is drawn.
460  *
461  * @param[in] gc the MicroUI GraphicsContext target.
462  * @param[in] x the top-left pixel X coordinate.
463  * @param[in] y the top-left pixel Y coordinate.
464  * @param[in] diameter the circle square size.
465  *
466  * @return the drawing status.
467  */
468 DRAWING_Status UI_DRAWING_fillCircle(MICROUI_GraphicsContext* gc, jint x, jint y, jint diameter);
469 
470 /*
471  * @brief Draws a region of an image.
472  *
473  * The image and the destination (MICROUI_GraphicsContext) never target the same image. See
474  * UI_DRAWING_copyImage() and UI_DRAWING_drawRegion().
475  *
476  * The region of the image to draw is given relative to the image (origin at the
477  * upper-left corner) as a rectangle.
478  *
479  * If the specified source region exceeds the image bounds, the copied region is
480  * limited to the image boundary. If the copied region goes out of the bounds of
481  * the graphics context area, pixels out of the range will not be drawn.
482  *
483  * A global opacity value is given. When this value is 0xff (255, opaque), that means the image
484  * is drawn on the graphics context without managing an extra opacity. Only the image transparent
485  * pixels must have been merged with destination. All image opaque pixels override destination.
486  *
487  * When this value is a value between 0 and 0xff, that means each pixel of the image must be merged
488  * with destination in addition with the image transparent pixels. An image opaque pixel becomes
489  * transparent (its opacity is the given alpha) and the opacity of an image transparent pixel becomes
490  * (alpha * alpha(pixel)) / 255.
491  *
492  * @param[in] gc the MicroUI GraphicsContext target.
493  * @param[in] img the MicroUI Image to draw.
494  * @param[in] regionX the x coordinate of the upper-left corner of the region to copy.
495  * @param[in] regionY the y coordinate of the upper-left corner of the region to copy.
496  * @param[in] width the width of the region to copy.
497  * @param[in] height the height of the region to copy.
498  * @param[in] x the x coordinate of the top-left point in the destination.
499  * @param[in] y the y coordinate of the top-left point in the destination.
500  * @param[in] alpha the opacity level to apply to the region.
501  *
502  * @return the drawing status.
503  */
504 DRAWING_Status UI_DRAWING_drawImage(MICROUI_GraphicsContext* gc, MICROUI_Image* img, jint regionX, jint regionY, jint width, jint height, jint x, jint y, jint alpha);
505 
506 /*
507  * @brief Copy a region of an image in another image with the same pixel format.
508  *
509  * Contrary to UI_DRAWING_drawImage(), the opacity is not an option. As the source and destination
510  * have the same pixel representation, this function has just to perform a "memory copy".
511  *
512  * The region of the image to draw is given relative to the image (origin at the
513  * upper-left corner) as a rectangle.
514  *
515  * If the specified source region exceeds the image bounds, the copied region is
516  * limited to the image boundary. If the copied region goes out of the bounds of
517  * the graphics context area, pixels out of the range will not be drawn.
518  *
519  * The image and the destination (MICROUI_GraphicsContext) may target the same image. By consequence,
520  * the implementation has to check the "overlap" use-case: the region to copy overlaps the destination
521  * region.
522  *
523  * @param[in] gc the MicroUI GraphicsContext target.
524  * @param[in] img the MicroUI Image to copy.
525  * @param[in] regionX the x coordinate of the upper-left corner of the region to copy.
526  * @param[in] regionY the y coordinate of the upper-left corner of the region to copy.
527  * @param[in] width the width of the region to copy.
528  * @param[in] height the height of the region to copy.
529  * @param[in] x the x coordinate of the top-left point in the destination.
530  * @param[in] y the y coordinate of the top-left point in the destination.
531  *
532  * @return the drawing status.
533  */
534 DRAWING_Status UI_DRAWING_copyImage(MICROUI_GraphicsContext* gc, MICROUI_Image* img, jint regionX, jint regionY, jint width, jint height, jint x, jint y);
535 
536 /*
537  * @brief Draw a region of an image in the same image.
538  *
539  * Contrary to UI_DRAWING_drawImage(), the implementation has to check the "overlap" use-case:
540  * the region to copy overlaps the destination region.
541  *
542  * The region of the image to draw is given relative to the image (origin at the
543  * upper-left corner) as a rectangle.
544  *
545  * If the specified source region exceeds the image bounds, the copied region is
546  * limited to the image boundary. If the copied region goes out of the bounds of
547  * the graphics context area, pixels out of the range will not be drawn.
548  *
549  * @param[in] gc the MicroUI GraphicsContext source and target.
550  * @param[in] regionX the x coordinate of the upper-left corner of the region to copy.
551  * @param[in] regionY the y coordinate of the upper-left corner of the region to copy.
552  * @param[in] width the width of the region to copy.
553  * @param[in] height the height of the region to copy.
554  * @param[in] x the x coordinate of the top-left point in the destination.
555  * @param[in] y the y coordinate of the top-left point in the destination.
556  * @param[in] alpha the opacity level to apply to the region.
557  *
558  * @return the drawing status.
559  */
560 DRAWING_Status UI_DRAWING_drawRegion(MICROUI_GraphicsContext* gc, jint regionX, jint regionY, jint width, jint height, jint x, jint y, jint alpha);
561 
562 /*
563  * @brief Draws a thick point with fade at given position.
564  *
565  * @param[in] gc the MicroUI GraphicsContext target.
566  * @param[in] x the point X coordinate.
567  * @param[in] y the point Y coordinate.
568  * @param[in] thickness the point thickness.
569  * @param[in] fade the fade to apply.
570  *
571  * @return the drawing status.
572  */
573 DRAWING_Status UI_DRAWING_drawThickFadedPoint(MICROUI_GraphicsContext* gc, jint x, jint y, jint thickness, jint fade);
574 
575 /*
576  * @brief Draws a thick line with fade between given points.
577  *
578  * @param[in] gc the MicroUI GraphicsContext target.
579  * @param[in] startX the x coordinate of the start of the line
580  * @param[in] startY the y coordinate of the start of the line
581  * @param[in] endX the x coordinate of the end of the line
582  * @param[in] endY the y coordinate of the end of the line
583  * @param[in] thickness the line thickness.
584  * @param[in] fade the fade to apply.
585  * @param[in] startCap cap representation of start of shape
586  * @param[in] endCap cap representation of end of shape
587  *
588  * @return the drawing status.
589  */
590 DRAWING_Status UI_DRAWING_drawThickFadedLine(MICROUI_GraphicsContext* gc, jint startX, jint startY, jint endX, jint endY, jint thickness, jint fade, DRAWING_Cap startCap, DRAWING_Cap endCap);
591 
592 /*
593  * @brief Draws a thick circle with fade covering the square specified by its diameter.
594  *
595  * If diameter is negative or zero, nothing is drawn.
596  *
597  * @param[in] gc the MicroUI GraphicsContext target.
598  * @param[in] x the x coordinate of the upper-left corner of the square where the circle is drawn
599  * @param[in] y the y coordinate of the upper-left corner of the square where the circle is drawn
600  * @param[in] diameter the diameter of the circle to draw
601  * @param[in] thickness the circle thickness.
602  * @param[in] fade the fade to apply.
603  *
604  * @return the drawing status.
605  */
606 DRAWING_Status UI_DRAWING_drawThickFadedCircle(MICROUI_GraphicsContext* gc, jint x, jint y, jint diameter, jint thickness, jint fade);
607 
608 /*
609  * @brief Draws a thick circle with fade arc covering the specified square.
610  *
611  * The arc is drawn from startAngle up to arcAngle degrees. The center of the arc
612  * is defined as the center of the square whose origin is at (x,y) (upper-left
613  * corner) and whose dimension is given by diameter.
614  *
615  * Angles are interpreted such that 0 degrees is at the 3 o'clock position. A positive
616  * value indicates a counter-clockwise rotation while a negative value indicates
617  * a clockwise rotation.
618  *
619  * If diameter is negative or zero, nothing is drawn.
620  *
621  * The angles are given relative to the square. For instance an angle of 45 degrees
622  * is always defined by the line from the center of the square to the upper right
623  * corner of the square. Thus for a non squared square angles are skewed along
624  * either height or width.
625  *
626  * @param[in] gc the MicroUI GraphicsContext target.
627  * @param[in] x the x coordinate of the upper-left corner of the square where the arc is drawn
628  * @param[in] y the y coordinate of the upper-left corner of the square where the arc is drawn
629  * @param[in] diameter the diameter of the circle to draw
630  * @param[in] startAngle the beginning angle of the arc to draw
631  * @param[in] arcAngle the angular extent of the arc from startAngle
632  * @param[in] thickness the arc thickness.
633  * @param[in] fade the fade to apply.
634  * @param[in] start cap representation of start of shape
635  * @param[in] end cap representation of end of shape
636  *
637  * @return the drawing status.
638  */
639 DRAWING_Status UI_DRAWING_drawThickFadedCircleArc(MICROUI_GraphicsContext* gc, jint x, jint y, jint diameter, jfloat startAngle, jfloat arcAngle, jint thickness, jint fade, DRAWING_Cap start, DRAWING_Cap end);
640 
641 /*
642  * @brief Draws a thick ellipse with fade covering the specified rectangle.
643  *
644  * The center of the ellipse is defined as the center of the rectangle whose origin
645  * is at (x,y) (upper-left corner) and whose dimension is given by width and height.
646  *
647  * If either width or height is negative or zero, nothing is drawn.
648  *
649  * @param[in] gc the MicroUI GraphicsContext target.
650  * @param[in] x the x coordinate of the upper-left corner of the rectangle where the ellipse is drawn
651  * @param[in] y the y coordinate of the upper-left corner of the rectangle where the ellipse is drawn
652  * @param[in] width the width of the ellipse to draw
653  * @param[in] height the height of the ellipse to draw
654  * @param[in] thickness the ellipse thickness.
655  * @param[in] fade the fade to apply.
656  *
657  * @return the drawing status.
658  */
659 DRAWING_Status UI_DRAWING_drawThickFadedEllipse(MICROUI_GraphicsContext* gc, jint x, jint y, jint width, jint height, jint thickness, jint fade);
660 
661 /*
662  * @brief Draws a thick line between given points.
663  *
664  * @param[in] gc the MicroUI GraphicsContext target.
665  * @param[in] startX the x coordinate of the start of the line
666  * @param[in] startY the y coordinate of the start of the line
667  * @param[in] endX the x coordinate of the end of the line
668  * @param[in] endY the y coordinate of the end of the line
669  * @param[in] thickness the line thickness.
670  *
671  * @return the drawing status.
672  */
673 DRAWING_Status UI_DRAWING_drawThickLine(MICROUI_GraphicsContext* gc, jint startX, jint startY, jint endX, jint endY, jint thickness);
674 
675 /*
676  * @brief Draws a thick circle covering the square specified by its diameter.
677  *
678  * If diameter is negative or zero, nothing is drawn.
679  *
680  * @param[in] gc the MicroUI GraphicsContext target.
681  * @param[in] x the x coordinate of the upper-left corner of the square where the circle is drawn
682  * @param[in] y the y coordinate of the upper-left corner of the square where the circle is drawn
683  * @param[in] diameter the diameter of the circle to draw
684  * @param[in] thickness the circle thickness.
685  *
686  * @return the drawing status.
687  */
688 DRAWING_Status UI_DRAWING_drawThickCircle(MICROUI_GraphicsContext* gc, jint x, jint y, jint diameter, jint thickness);
689 
690 /*
691  * @brief Draws a thick ellipse covering the specified rectangle.
692  *
693  * The center of the ellipse is defined as the center of the rectangle whose origin
694  * is at (x,y) (upper-left corner) and whose dimension is given by width and height.
695  *
696  * If either width or height is negative or zero, nothing is drawn.
697  *
698  * @param[in] gc the MicroUI GraphicsContext target.
699  * @param[in] x the x coordinate of the upper-left corner of the square where the circle is drawn
700  * @param[in] y the y coordinate of the upper-left corner of the square where the circle is drawn
701  * @param[in] width the width of the ellipse to draw
702  * @param[in] height the height of the ellipse to draw
703  * @param[in] thickness the circle thickness.
704  *
705  * @return the drawing status.
706  */
707 DRAWING_Status UI_DRAWING_drawThickEllipse(MICROUI_GraphicsContext* gc, jint x, jint y, jint width, jint height, jint thickness);
708 
709 /*
710  * @brief Draws a thick arc covering the square specified by its diameter.
711  *
712  * The arc is drawn from startAngle up to arcAngle degrees. The center of the arc is
713  * defined as the center of the square whose origin is at (x,y) (upper-left corner)
714  * and whose dimension is given by diameter.
715  *
716  * Angles are interpreted such that 0 degrees is at the 3 o'clock position. A positive
717  * value indicates a counter-clockwise rotation while a negative value indicates a
718  * clockwise rotation.
719  *
720  * If diameter is negative, nothing is drawn.
721  *
722  * @param[in] gc the MicroUI GraphicsContext target.
723  * @param[in] x the x coordinate of the upper-left corner of the square where the arc is drawn
724  * @param[in] y the y coordinate of the upper-left corner of the square where the arc is drawn
725  * @param[in] diameter the diameter of the circle to draw
726  * @param[in] startAngle the beginning angle of the arc to draw
727  * @param[in] arcAngle the angular extent of the arc from startAngle
728  * @param[in] thickness the arc thickness.
729  *
730  * @return the drawing status.
731  */
732 DRAWING_Status UI_DRAWING_drawThickCircleArc(MICROUI_GraphicsContext* gc, jint x, jint y, jint diameter, jfloat startAngle, jfloat arcAngle, jint thickness);
733 
734 /*
735  * @brief Draws an image applying a flip (0, 90, 180 or 270 degrees with or without
736  * mirror).
737  *
738  * @param[in] gc the MicroUI GraphicsContext target.
739  * @param[in] img the MicroUI Image to draw.
740  * @param[in] regionX the x coordinate of the upper-left corner of the region to draw.
741  * @param[in] regionY the y coordinate of the upper-left corner of the region to draw.
742  * @param[in] width the width of the region to copy.
743  * @param[in] height the height of the region to copy.
744  * @param[in] x the x coordinate of the top-left point in the destination.
745  * @param[in] y the y coordinate of the top-left point in the destination.
746  * @param[in] transformation the flip to apply.
747  * @param[in] alpha the opacity level to apply to the region.
748  *
749  * @return the drawing status.
750  */
751 DRAWING_Status UI_DRAWING_drawFlippedImage(MICROUI_GraphicsContext* gc, MICROUI_Image* img, jint regionX, jint regionY, jint width, jint height, jint x, jint y, DRAWING_Flip transformation, jint alpha);
752 
753 /*
754  * @brief Draws an image applying a free rotation (0 to 360 degrees).
755  *
756  * The rotation is specified by the center and the angle. The reference point is
757  * the graphical object top-left corner. The rotation point is relative where the
758  * graphical object will be drawn.
759  *
760  * This method uses the nearest neighbor algorithm to render the content. This algorithm
761  * is faster than bilinear algorithm but its rendering is faster.
762  *
763  * @param[in] gc the MicroUI GraphicsContext target.
764  * @param[in] img the MicroUI Image to draw.
765  * @param[in] x the x coordinate of the image reference anchor top-left point.
766  * @param[in] y the y coordinate of the image reference anchor top-left point.
767  * @param[in] rotationX the x coordinate of the rotation center.
768  * @param[in] rotationY the y coordinate of the rotation center.
769  * @param[in] angle the rotation angle.
770  * @param[in] alpha the opacity level to apply to the region.
771  *
772  * @return the drawing status.
773  */
774 DRAWING_Status UI_DRAWING_drawRotatedImageNearestNeighbor(MICROUI_GraphicsContext* gc, MICROUI_Image* img, jint x, jint y, jint rotationX, jint rotationY, jfloat angle, jint alpha);
775 
776 /*
777  * @brief Draws an image applying a free rotation (0 to 360 degrees).
778  *
779  * The rotation is specified by the center and the angle. The reference point is
780  * the graphical object top-left corner. The rotation point is relative where the
781  * graphical object will be drawn.
782  *
783  * This method uses the bilinear algorithm to render the content. This algorithm
784  * performs better rendering than nearest neighbor algorithm but it is slower to
785  * apply.
786  *
787  * @param[in] gc the MicroUI GraphicsContext target.
788  * @param[in] img the MicroUI Image to draw.
789  * @param[in] x the x coordinate of the image reference anchor top-left point.
790  * @param[in] y the y coordinate of the image reference anchor top-left point.
791  * @param[in] rotationX the x coordinate of the rotation center.
792  * @param[in] rotationY the y coordinate of the rotation center.
793  * @param[in] angle the rotation angle.
794  * @param[in] alpha the opacity level to apply to the region.
795  *
796  * @return the drawing status.
797  */
798 DRAWING_Status UI_DRAWING_drawRotatedImageBilinear(MICROUI_GraphicsContext* gc, MICROUI_Image* img, jint x, jint y, jint rotationX, jint rotationY, jfloat angle, jint alpha);
799 
800 /*
801  * @brief Draws an image applying a scaling.
802  *
803  * This method uses the nearest neighbor algorithm to render the content. This algorithm
804  * is faster than bilinear algorithm but its rendering is faster.
805  *
806  * @param[in] gc the MicroUI GraphicsContext target.
807  * @param[in] img the MicroUI Image to draw.
808  * @param[in] x the x coordinate of the image reference anchor top-left point.
809  * @param[in] y the y coordinate of the image reference anchor top-left point.
810  * @param[in] factorX scaling X factor.
811  * @param[in] factorY scaling Y factor.
812  * @param[in] alpha the opacity level to apply to the region.
813  *
814  * @return the drawing status.
815  */
816 DRAWING_Status UI_DRAWING_drawScaledImageNearestNeighbor(MICROUI_GraphicsContext* gc, MICROUI_Image* img, jint x, jint y, jfloat factorX, jfloat factorY, jint alpha);
817 
818 /*
819  * @brief Draws an image applying a scaling.
820  *
821  * This method uses the bilinear algorithm to render the content. This algorithm
822  * performs better rendering than nearest neighbor algorithm but it is slower to
823  * apply.
824  *
825  * @param[in] gc the MicroUI GraphicsContext target.
826  * @param[in] img the MicroUI Image to draw.
827  * @param[in] x the x coordinate of the image reference anchor top-left point.
828  * @param[in] y the y coordinate of the image reference anchor top-left point.
829  * @param[in] factorX scaling X factor.
830  * @param[in] factorY scaling Y factor.
831  * @param[in] alpha the opacity level to apply to the region.
832  *
833  * @return the drawing status.
834  */
835 DRAWING_Status UI_DRAWING_drawScaledImageBilinear(MICROUI_GraphicsContext* gc, MICROUI_Image* img, jint x, jint y, jfloat factorX, jfloat factorY, jint alpha);
836 
837 // --------------------------------------------------------------------------------
838 // EOF
839 // --------------------------------------------------------------------------------
840 
841 #ifdef __cplusplus
842 }
843 #endif
844 #endif // UI_DRAWING_H