microui  3.0.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.0.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 Draws a pixel at given position.
162  *
163  * @param[in] gc the MicroUI GraphicsContext target.
164  * @param[in] x the pixel X coordinate.
165  * @param[in] y the pixel Y coordinate.
166  *
167  * @return the drawing status.
168  */
169 DRAWING_Status UI_DRAWING_writePixel(MICROUI_GraphicsContext* gc, jint x, jint y);
170 
171 /*
172  * @brief Draws a line at between points startX,startY (included) and endX,endY (included).
173  * Note: startX may be higher than endX (and/or startY may be higher than endY).
174  *
175  * @param[in] gc the MicroUI GraphicsContext target.
176  * @param[in] startX the first pixel line X coordinate.
177  * @param[in] startY the first pixel line Y coordinate.
178  * @param[in] endX the last pixel line X coordinate.
179  * @param[in] endY the last pixel line Y coordinate.
180  *
181  * @return the drawing status.
182  */
183 DRAWING_Status UI_DRAWING_drawLine(MICROUI_GraphicsContext* gc, jint startX, jint startY, jint endX, jint endY);
184 
185 /*
186  * @brief Draws a horizontal line at between points x1,y (included) and x2,y (included).
187  * Caller ensures that x1 <= x2.
188  *
189  * @param[in] gc the MicroUI GraphicsContext target.
190  * @param[in] x1 the first pixel line X coordinate.
191  * @param[in] x2 the last pixel line X coordinate.
192  * @param[in] y the both pixels line Y coordinate.
193  *
194  * @return the drawing status.
195  */
196 DRAWING_Status UI_DRAWING_drawHorizontalLine(MICROUI_GraphicsContext* gc, jint x1, jint x2, jint y);
197 
198 /*
199  * @brief Draws a vertical line at between points x,y1 (included) and x,y2 (included).
200  * Caller ensures that y1 <= y2.
201  *
202  * @param[in] gc the MicroUI GraphicsContext target.
203  * @param[in] x the both pixels line X coordinate.
204  * @param[in] y1 the first pixel line Y coordinate.
205  * @param[in] y2 the last pixel line Y coordinate.
206  *
207  * @return the drawing status.
208  */
209 DRAWING_Status UI_DRAWING_drawVerticalLine(MICROUI_GraphicsContext* gc, jint x, jint y1, jint y2);
210 
211 /*
212  * @brief Draws an orthogonal rectangle at from top-left point x1,y1 (included) and bottom-right
213  * point x2,y2 (included).
214  * Caller ensures that x1 <= x2 and y1 <= y2.
215  *
216  * @param[in] gc the MicroUI GraphicsContext target.
217  * @param[in] x1 the top-left pixel X coordinate.
218  * @param[in] y1 the top-left pixel Y coordinate.
219  * @param[in] x2 the bottom-right pixel X coordinate.
220  * @param[in] y2 the top-right pixel Y coordinate.
221  *
222  * @return the drawing status.
223  */
224 DRAWING_Status UI_DRAWING_drawRectangle(MICROUI_GraphicsContext* gc, jint x1, jint y1, jint x2, jint y2);
225 
226 /*
227  * @brief Fills a rectangle at from top-left point x1,y1 (included) and bottom-right
228  * point x2,y2 (included).
229  * Caller ensures that x1 <= x2 and y1 <= y2.
230  *
231  * @param[in] gc the MicroUI GraphicsContext target.
232  * @param[in] x1 the top-left pixel X coordinate.
233  * @param[in] y1 the top-left pixel Y coordinate.
234  * @param[in] x2 the bottom-right pixel X coordinate.
235  * @param[in] y2 the top-right pixel Y coordinate.
236  *
237  * @return the drawing status.
238  */
239 DRAWING_Status UI_DRAWING_fillRectangle(MICROUI_GraphicsContext* gc, jint x1, jint y1, jint x2, jint y2);
240 
241 /*
242  * @brief Draws a rounded rectangle at from top-left point x,y (included) and bottom-right
243  * point x+width-1,y+height-1 (included).
244  *
245  * @param[in] gc the MicroUI GraphicsContext target.
246  * @param[in] x the top-left pixel X coordinate.
247  * @param[in] y the top-left pixel Y coordinate.
248  * @param[in] width the rectangle width.
249  * @param[in] height the rectangle height.
250  * @param[in] cornerEllipseWidth the horizontal diameter of the arc at the corners.
251  * @param[in] cornerEllipseHeight the vertical diameter of the arc at the corners.
252  *
253  * @return the drawing status.
254  */
255 DRAWING_Status UI_DRAWING_drawRoundedRectangle(MICROUI_GraphicsContext* gc, jint x, jint y, jint width, jint height, jint cornerEllipseWidth, jint cornerEllipseHeight);
256 
257 /*
258  * @brief Fills a rounded rectangle at from top-left point x,y (included) and bottom-right
259  * point x+width-1,y+height-1 (included).
260  *
261  * @param[in] gc the MicroUI GraphicsContext target.
262  * @param[in] x the top-left pixel X coordinate.
263  * @param[in] y the top-left pixel Y coordinate.
264  * @param[in] width the rectangle width.
265  * @param[in] height the rectangle height.
266  * @param[in] cornerEllipseWidth the horizontal diameter of the arc at the corners.
267  * @param[in] cornerEllipseHeight the vertical diameter of the arc at the corners.
268  *
269  * @return the drawing status.
270  */
271 DRAWING_Status UI_DRAWING_fillRoundedRectangle(MICROUI_GraphicsContext* gc, jint x, jint y, jint width, jint height, jint cornerEllipseWidth, jint cornerEllipseHeight);
272 
273 /*
274  * @brief Draws a circular arc covering the square defined by top-left point x,y (included)
275  * and bottom-right point x+diameter-1,y+diameter-1 (included).
276  *
277  * The arc is drawn from startAngle up to arcAngle degrees. The center of the arc is
278  * defined as the center of the square whose origin is at (x,y) (upper-left corner)
279  * and whose dimension is given by width and height.
280  *
281  * Angles are interpreted such that 0 degrees is at the 3 o'clock position. A positive
282  * value indicates a counter-clockwise rotation while a negative value indicates
283  * a clockwise rotation.
284  *
285  * If either the given diameter is negative or zero, or if arcAngle is zero,
286  * nothing is drawn.
287  *
288  * The angles are given relative to the square. For instance an angle of 45
289  * degrees is always defined by the line from the center of the square to the
290  * upper right corner of the square.
291  *
292  * @param[in] gc the MicroUI GraphicsContext target.
293  * @param[in] x the top-left pixel X coordinate.
294  * @param[in] y the top-left pixel Y coordinate.
295  * @param[in] square the diameter of the arc to draw.
296  * @param[in] startAngle the beginning angle of the arc to draw
297  * @param[in] arcAngle the angular extent of the arc from startAngle
298  *
299  * @return the drawing status.
300  */
301 DRAWING_Status UI_DRAWING_drawCircleArc(MICROUI_GraphicsContext* gc, jint x, jint y, jint diameter, jfloat startAngle, jfloat arcAngle);
302 
303 /*
304  * @brief Draws an elliptical arc covering the rectangle defined by top-left point x,y (included)
305  * and bottom-right point x+width-1,y+height-1 (included).
306  *
307  * The arc is drawn from startAngle up to arcAngle degrees. The center of the arc is
308  * defined as the center of the rectangle whose origin is at (x,y) (upper-left corner)
309  * and whose dimension is given by width and height.
310  *
311  * Angles are interpreted such that 0 degrees is at the 3 o'clock position. A positive
312  * value indicates a counter-clockwise rotation while a negative value indicates
313  * a clockwise rotation.
314  *
315  * If either the given width or height is negative or zero, or if arcAngle is zero,
316  * nothing is drawn.
317  *
318  * The angles are given relative to the rectangle. For instance an angle of 45
319  * degrees is always defined by the line from the center of the rectangle to the
320  * upper right corner of the rectangle. Thus for a non squared rectangle
321  * angles are skewed along either height or width.
322  *
323  * @param[in] gc the MicroUI GraphicsContext target.
324  * @param[in] x the top-left pixel X coordinate.
325  * @param[in] y the top-left pixel Y coordinate.
326  * @param[in] width the rectangle width.
327  * @param[in] height the rectangle height.
328  * @param[in] startAngle the beginning angle of the arc to draw
329  * @param[in] arcAngle the angular extent of the arc from startAngle
330  *
331  * @return the drawing status.
332  */
333 DRAWING_Status UI_DRAWING_drawEllipseArc(MICROUI_GraphicsContext* gc, jint x, jint y, jint width, jint height, jfloat startAngle, jfloat arcAngle);
334 
335 /*
336  * @brief Fills a circular arc covering the square defined by top-left point x,y (included)
337  * and bottom-right point x+diameter-1,y+diameter-1 (included).
338  *
339  * The arc is drawn from startAngle up to arcAngle degrees. The center of the arc is
340  * defined as the center of the rectangle whose origin is at (x,y) (upper-left corner)
341  * and whose dimension is given by width and height.
342  *
343  * Angles are interpreted such that 0 degrees is at the 3 o'clock position. A positive
344  * value indicates a counter-clockwise rotation while a negative value indicates
345  * a clockwise rotation.
346  *
347  * If either the given diameter is negative or zero, or if arcAngle is zero,
348  * nothing is drawn.
349  *
350  * The angles are given relative to the square. For instance an angle of 45
351  * degrees is always defined by the line from the center of the square to the
352  * upper right corner of the square.
353  *
354  * @param[in] gc the MicroUI GraphicsContext target.
355  * @param[in] x the top-left pixel X coordinate.
356  * @param[in] y the top-left pixel Y coordinate.
357  * @param[in] diameter the diameter of the arc to draw.
358  * @param[in] startAngle the beginning angle of the arc to draw
359  * @param[in] arcAngle the angular extent of the arc from startAngle
360  *
361  * @return the drawing status.
362  */
363 DRAWING_Status UI_DRAWING_fillCircleArc(MICROUI_GraphicsContext* gc, jint x, jint y, jint diameter, jfloat startAngle, jfloat arcAngle);
364 
365 /*
366  * @brief Fills an elliptical arc covering the rectangle defined by top-left point x,y (included)
367  * and bottom-right point x+width-1,y+height-1 (included).
368  *
369  * The arc is drawn from startAngle up to arcAngle degrees. The center of the arc is
370  * defined as the center of the rectangle whose origin is at (x,y) (upper-left corner)
371  * and whose dimension is given by width and height.
372  *
373  * Angles are interpreted such that 0 degrees is at the 3 o'clock position. A positive
374  * value indicates a counter-clockwise rotation while a negative value indicates
375  * a clockwise rotation.
376  *
377  * If either the given width or height is negative or zero, or if arcAngle is zero,
378  * nothing is drawn.
379  *
380  * The angles are given relative to the rectangle. For instance an angle of 45
381  * degrees is always defined by the line from the center of the rectangle to the
382  * upper right corner of the rectangle. Thus for a non squared rectangle
383  * angles are skewed along either height or width.
384  *
385  * @param[in] gc the MicroUI GraphicsContext target.
386  * @param[in] x the top-left pixel X coordinate.
387  * @param[in] y the top-left pixel Y coordinate.
388  * @param[in] width the rectangle width.
389  * @param[in] height the rectangle height.
390  * @param[in] startAngle the beginning angle of the arc to draw
391  * @param[in] arcAngle the angular extent of the arc from startAngle
392  *
393  * @return the drawing status.
394  */
395 DRAWING_Status UI_DRAWING_fillEllipseArc(MICROUI_GraphicsContext* gc, jint x, jint y, jint width, jint height, jfloat startAngle, jfloat arcAngle);
396 
397 /*
398  * @brief Draws an ellipse covering the rectangle defined by top-left point x,y (included)
399  * and bottom-right point x+width-1,y+height-1 (included). Ellipses which focal points are not
400  * on the same axis are not supported.
401  *
402  * If either the given width or height is negative or zero, nothing is drawn.
403  *
404  * @param[in] gc the MicroUI GraphicsContext target.
405  * @param[in] x the top-left pixel X coordinate.
406  * @param[in] y the top-left pixel Y coordinate.
407  * @param[in] width the ellipse width.
408  * @param[in] height the ellipse height.
409  *
410  * @return the drawing status.
411  */
412 DRAWING_Status UI_DRAWING_drawEllipse(MICROUI_GraphicsContext* gc, jint x, jint y, jint width, jint height);
413 
414 /*
415  * @brief Fills an ellipse covering the rectangle defined by top-left point x,y (included)
416  * and bottom-right point x+width-1,y+height-1 (included).
417  *
418  * If either the given width or height is negative or zero, nothing is drawn.
419  *
420  * @param[in] gc the MicroUI GraphicsContext target.
421  * @param[in] x the top-left pixel X coordinate.
422  * @param[in] y the top-left pixel Y coordinate.
423  * @param[in] width the ellipse width.
424  * @param[in] height the ellipse height.
425  *
426  * @return the drawing status.
427  */
428 DRAWING_Status UI_DRAWING_fillEllipse(MICROUI_GraphicsContext* gc, jint x, jint y, jint width, jint height);
429 
430 /*
431  * @brief Draws a circle covering the square defined by top-left point x,y (included)
432  * and bottom-right point x+diameter-1,y+diameter-1 (included).
433  *
434  * If the given diameter is negative or zero, nothing is drawn.
435  *
436  * @param[in] gc the MicroUI GraphicsContext target.
437  * @param[in] x the top-left pixel X coordinate.
438  * @param[in] y the top-left pixel Y coordinate.
439  * @param[in] diameter the circle square size.
440  *
441  * @return the drawing status.
442  */
443 DRAWING_Status UI_DRAWING_drawCircle(MICROUI_GraphicsContext* gc, jint x, jint y, jint diameter);
444 
445 /*
446  * @brief Fills a circle covering the square defined by top-left point x,y (included)
447  * and bottom-right point x+diameter-1,y+diameter-1 (included)
448  *
449  * If the given diameter is negative or zero, nothing is drawn.
450  *
451  * @param[in] gc the MicroUI GraphicsContext target.
452  * @param[in] x the top-left pixel X coordinate.
453  * @param[in] y the top-left pixel Y coordinate.
454  * @param[in] diameter the circle square size.
455  *
456  * @return the drawing status.
457  */
458 DRAWING_Status UI_DRAWING_fillCircle(MICROUI_GraphicsContext* gc, jint x, jint y, jint diameter);
459 
460 /*
461  * @brief Draws a region of an image.
462  *
463  * The image and the destination (MICROUI_GraphicsContext) never target the same image. See
464  * UI_DRAWING_copyImage() and UI_DRAWING_drawRegion().
465  *
466  * The region of the image to draw is given relative to the image (origin at the
467  * upper-left corner) as a rectangle.
468  *
469  * If the specified source region exceeds the image bounds, the copied region is
470  * limited to the image boundary. If the copied region goes out of the bounds of
471  * the graphics context area, pixels out of the range will not be drawn.
472  *
473  * A global opacity value is given. When this value is 0xff (255, opaque), that means the image
474  * is drawn on the graphics context without managing an extra opacity. Only the image transparent
475  * pixels must have been merged with destination. All image opaque pixels override destination.
476  *
477  * When this value is a value between 0 and 0xff, that means each pixel of the image must be merged
478  * with destination in addition with the image transparent pixels. An image opaque pixel becomes
479  * transparent (its opacity is the given alpha) and the opacity of an image transparent pixel becomes
480  * (alpha * alpha(pixel)) / 255.
481  *
482  * @param[in] gc the MicroUI GraphicsContext target.
483  * @param[in] img the MicroUI Image to draw.
484  * @param[in] regionX the x coordinate of the upper-left corner of the region to copy.
485  * @param[in] regionY the x coordinate of the upper-left corner of the region to copy.
486  * @param[in] width the width of the region to copy.
487  * @param[in] height the height of the region to copy.
488  * @param[in] x the x coordinate of the top-left point in the destination.
489  * @param[in] y the y coordinate of the top-left point in the destination.
490  * @param[in] alpha the opacity level to apply to the region.
491  *
492  * @return the drawing status.
493  */
494 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);
495 
496 /*
497  * @brief Copy a region of an image in another image with the same pixel format.
498  *
499  * Contrary to UI_DRAWING_drawImage(), the opacity is not an option. As the source and destination
500  * have the same pixel representation, this function has just to perform a "memory copy".
501  *
502  * The region of the image to draw is given relative to the image (origin at the
503  * upper-left corner) as a rectangle.
504  *
505  * If the specified source region exceeds the image bounds, the copied region is
506  * limited to the image boundary. If the copied region goes out of the bounds of
507  * the graphics context area, pixels out of the range will not be drawn.
508  *
509  * The image and the destination (MICROUI_GraphicsContext) may target the same image. By consequence,
510  * the implementation has to check the "overlap" use-case: the region to copy overlaps the destination
511  * region.
512  *
513  * @param[in] gc the MicroUI GraphicsContext target.
514  * @param[in] img the MicroUI Image to copy.
515  * @param[in] regionX the x coordinate of the upper-left corner of the region to copy.
516  * @param[in] regionY the x coordinate of the upper-left corner of the region to copy.
517  * @param[in] width the width of the region to copy.
518  * @param[in] height the height of the region to copy.
519  * @param[in] x the x coordinate of the top-left point in the destination.
520  * @param[in] y the y coordinate of the top-left point in the destination.
521  *
522  * @return the drawing status.
523  */
524 DRAWING_Status UI_DRAWING_copyImage(MICROUI_GraphicsContext* gc, MICROUI_Image* img, jint regionX, jint regionY, jint width, jint height, jint x, jint y);
525 
526 /*
527  * @brief Draw a region of an image in the same image.
528  *
529  * Contrary to UI_DRAWING_drawImage(), the implementation has to check the "overlap" use-case:
530  * the region to copy overlaps the destination region.
531  *
532  * The region of the image to draw is given relative to the image (origin at the
533  * upper-left corner) as a rectangle.
534  *
535  * If the specified source region exceeds the image bounds, the copied region is
536  * limited to the image boundary. If the copied region goes out of the bounds of
537  * the graphics context area, pixels out of the range will not be drawn.
538  *
539  * @param[in] gc the MicroUI GraphicsContext source and target.
540  * @param[in] regionX the x coordinate of the upper-left corner of the region to copy.
541  * @param[in] regionY the x coordinate of the upper-left corner of the region to copy.
542  * @param[in] width the width of the region to copy.
543  * @param[in] height the height of the region to copy.
544  * @param[in] x the x coordinate of the top-left point in the destination.
545  * @param[in] y the y coordinate of the top-left point in the destination.
546  * @param[in] alpha the opacity level to apply to the region.
547  *
548  * @return the drawing status.
549  */
550 DRAWING_Status UI_DRAWING_drawRegion(MICROUI_GraphicsContext* gc, jint regionX, jint regionY, jint width, jint height, jint x, jint y, jint alpha);
551 
552 /*
553  * @brief Draws a thick point with fade at given position.
554  *
555  * @param[in] gc the MicroUI GraphicsContext target.
556  * @param[in] x the point X coordinate.
557  * @param[in] y the point Y coordinate.
558  * @param[in] thickness the point thickness.
559  * @param[in] fade the fade to apply.
560  *
561  * @return the drawing status.
562  */
563 DRAWING_Status UI_DRAWING_drawThickFadedPoint(MICROUI_GraphicsContext* gc, jint x, jint y, jint thickness, jint fade);
564 
565 /*
566  * @brief Draws a thick line with fade between given points.
567  *
568  * @param[in] gc the MicroUI GraphicsContext target.
569  * @param[in] startX the x coordinate of the start of the line
570  * @param[in] startY the y coordinate of the start of the line
571  * @param[in] endX the x coordinate of the end of the line
572  * @param[in] endY the y coordinate of the end of the line
573  * @param[in] thickness the line thickness.
574  * @param[in] fade the fade to apply.
575  * @param[in] startCap cap representation of start of shape
576  * @param[in] endCap cap representation of end of shape
577  *
578  * @return the drawing status.
579  */
580 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);
581 
582 /*
583  * @brief Draws a thick circle with fade covering the square specified by its diameter.
584  *
585  * If diameter is negative or zero, nothing is drawn.
586  *
587  * @param[in] gc the MicroUI GraphicsContext target.
588  * @param[in] x the x coordinate of the upper-left corner of the square where the circle is drawn
589  * @param[in] y the y coordinate of the upper-left corner of the square where the circle is drawn
590  * @param[in] diameter the diameter of the circle to draw
591  * @param[in] thickness the circle thickness.
592  * @param[in] fade the fade to apply.
593  *
594  * @return the drawing status.
595  */
596 DRAWING_Status UI_DRAWING_drawThickFadedCircle(MICROUI_GraphicsContext* gc, jint x, jint y, jint diameter, jint thickness, jint fade);
597 
598 /*
599  * @brief Draws a thick circle with fade arc covering the specified square.
600  *
601  * The arc is drawn from startAngle up to arcAngle degrees. The center of the arc
602  * is defined as the center of the square whose origin is at (x,y) (upper-left
603  * corner) and whose dimension is given by diameter.
604  *
605  * Angles are interpreted such that 0 degrees is at the 3 o'clock position. A positive
606  * value indicates a counter-clockwise rotation while a negative value indicates
607  * a clockwise rotation.
608  *
609  * If diameter is negative or zero, nothing is drawn.
610  *
611  * The angles are given relative to the square. For instance an angle of 45 degrees
612  * is always defined by the line from the center of the square to the upper right
613  * corner of the square. Thus for a non squared square angles are skewed along
614  * either height or width.
615  *
616  * @param[in] gc the MicroUI GraphicsContext target.
617  * @param[in] x the x coordinate of the upper-left corner of the square where the arc is drawn
618  * @param[in] y the y coordinate of the upper-left corner of the square where the arc is drawn
619  * @param[in] diameter the diameter of the circle to draw
620  * @param[in] startAngle the beginning angle of the arc to draw
621  * @param[in] arcAngle the angular extent of the arc from startAngle
622  * @param[in] thickness the arc thickness.
623  * @param[in] fade the fade to apply.
624  * @param[in] start cap representation of start of shape
625  * @param[in] end cap representation of end of shape
626  *
627  * @return the drawing status.
628  */
629 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);
630 
631 /*
632  * @brief Draws a thick ellipse with fade covering the specified rectangle.
633  *
634  * The center of the ellipse is defined as the center of the rectangle whose origin
635  * is at (x,y) (upper-left corner) and whose dimension is given by width and height.
636  *
637  * If either width or height is negative or zero, nothing is drawn.
638  *
639  * @param[in] gc the MicroUI GraphicsContext target.
640  * @param[in] x the x coordinate of the upper-left corner of the rectangle where the ellipse is drawn
641  * @param[in] y the y coordinate of the upper-left corner of the rectangle where the ellipse is drawn
642  * @param[in] width the width of the ellipse to draw
643  * @param[in] height the height of the ellipse to draw
644  * @param[in] thickness the ellipse thickness.
645  * @param[in] fade the fade to apply.
646  *
647  * @return the drawing status.
648  */
649 DRAWING_Status UI_DRAWING_drawThickFadedEllipse(MICROUI_GraphicsContext* gc, jint x, jint y, jint width, jint height, jint thickness, jint fade);
650 
651 /*
652  * @brief Draws a thick line between given points.
653  *
654  * @param[in] gc the MicroUI GraphicsContext target.
655  * @param[in] startX the x coordinate of the start of the line
656  * @param[in] startY the y coordinate of the start of the line
657  * @param[in] endX the x coordinate of the end of the line
658  * @param[in] endY the y coordinate of the end of the line
659  * @param[in] thickness the line thickness.
660  *
661  * @return the drawing status.
662  */
663 DRAWING_Status UI_DRAWING_drawThickLine(MICROUI_GraphicsContext* gc, jint startX, jint startY, jint endX, jint endY, jint thickness);
664 
665 /*
666  * @brief Draws a thick circle covering the square specified by its diameter.
667  *
668  * If diameter is negative or zero, nothing is drawn.
669  *
670  * @param[in] gc the MicroUI GraphicsContext target.
671  * @param[in] x the x coordinate of the upper-left corner of the square where the circle is drawn
672  * @param[in] y the y coordinate of the upper-left corner of the square where the circle is drawn
673  * @param[in] diameter the diameter of the circle to draw
674  * @param[in] thickness the circle thickness.
675  *
676  * @return the drawing status.
677  */
678 DRAWING_Status UI_DRAWING_drawThickCircle(MICROUI_GraphicsContext* gc, jint x, jint y, jint diameter, jint thickness);
679 
680 /*
681  * @brief Draws a thick ellipse covering the specified rectangle.
682  *
683  * The center of the ellipse is defined as the center of the rectangle whose origin
684  * is at (x,y) (upper-left corner) and whose dimension is given by width and height.
685  *
686  * If either width or height is negative or zero, nothing is drawn.
687  *
688  * @param[in] gc the MicroUI GraphicsContext target.
689  * @param[in] x the x coordinate of the upper-left corner of the square where the circle is drawn
690  * @param[in] y the y coordinate of the upper-left corner of the square where the circle is drawn
691  * @param[in] width the width of the ellipse to draw
692  * @param[in] height the height of the ellipse to draw
693  * @param[in] thickness the circle thickness.
694  *
695  * @return the drawing status.
696  */
697 DRAWING_Status UI_DRAWING_drawThickEllipse(MICROUI_GraphicsContext* gc, jint x, jint y, jint width, jint height, jint thickness);
698 
699 /*
700  * @brief Draws a thick arc covering the square specified by its diameter.
701  *
702  * The arc is drawn from startAngle up to arcAngle degrees. The center of the arc is
703  * defined as the center of the square whose origin is at (x,y) (upper-left corner)
704  * and whose dimension is given by diameter.
705  *
706  * Angles are interpreted such that 0 degrees is at the 3 o'clock position. A positive
707  * value indicates a counter-clockwise rotation while a negative value indicates a
708  * clockwise rotation.
709  *
710  * If diameter is negative, nothing is drawn.
711  *
712  * @param[in] gc the MicroUI GraphicsContext target.
713  * @param[in] x the x coordinate of the upper-left corner of the square where the arc is drawn
714  * @param[in] y the y coordinate of the upper-left corner of the square where the arc is drawn
715  * @param[in] diameter the diameter of the circle to draw
716  * @param[in] startAngle the beginning angle of the arc to draw
717  * @param[in] arcAngle the angular extent of the arc from startAngle
718  * @param[in] thickness the arc thickness.
719  *
720  * @return the drawing status.
721  */
722 DRAWING_Status UI_DRAWING_drawThickCircleArc(MICROUI_GraphicsContext* gc, jint x, jint y, jint diameter, jfloat startAngle, jfloat arcAngle, jint thickness);
723 
724 /*
725  * @brief Draws an image applying a flip (0, 90, 180 or 270 degrees with or without
726  * mirror).
727  *
728  * @param[in] gc the MicroUI GraphicsContext target.
729  * @param[in] img the MicroUI Image to draw.
730  * @param[in] regionX the x coordinate of the upper-left corner of the region to draw.
731  * @param[in] regionY the x coordinate of the upper-left corner of the region to draw.
732  * @param[in] width the width of the region to copy.
733  * @param[in] height the height of the region to copy.
734  * @param[in] x the x coordinate of the top-left point in the destination.
735  * @param[in] y the y coordinate of the top-left point in the destination.
736  * @param[in] transformation the flip to apply.
737  * @param[in] alpha the opacity level to apply to the region.
738  *
739  * @return the drawing status.
740  */
741 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);
742 
743 /*
744  * @brief Draws an image applying a free rotation (0 to 360 degrees).
745  *
746  * The rotation is specified by the center and the angle. The reference point is
747  * the graphical object top-left corner. The rotation point is relative where the
748  * graphical object will be drawn.
749  *
750  * This method uses the nearest neighbor algorithm to render the content. This algorithm
751  * is faster than bilinear algorithm but its rendering is faster.
752  *
753  * @param[in] gc the MicroUI GraphicsContext target.
754  * @param[in] img the MicroUI Image to draw.
755  * @param[in] x the x coordinate of the image reference anchor top-left point.
756  * @param[in] y the y coordinate of the image reference anchor top-left point.
757  * @param[in] rotationX the x coordinate of the rotation center.
758  * @param[in] rotationY the y coordinate of the rotation center.
759  * @param[in] angle the rotation angle.
760  * @param[in] alpha the opacity level to apply to the region.
761  *
762  * @return the drawing status.
763  */
764 DRAWING_Status UI_DRAWING_drawRotatedImageNearestNeighbor(MICROUI_GraphicsContext* gc, MICROUI_Image* img, jint x, jint y, jint rotationX, jint rotationY, jfloat angle, jint alpha);
765 
766 /*
767  * @brief Draws an image applying a free rotation (0 to 360 degrees).
768  *
769  * The rotation is specified by the center and the angle. The reference point is
770  * the graphical object top-left corner. The rotation point is relative where the
771  * graphical object will be drawn.
772  *
773  * This method uses the bilinear algorithm to render the content. This algorithm
774  * performs better rendering than nearest neighbor algorithm but it is slower to
775  * apply.
776  *
777  * @param[in] gc the MicroUI GraphicsContext target.
778  * @param[in] img the MicroUI Image to draw.
779  * @param[in] x the x coordinate of the image reference anchor top-left point.
780  * @param[in] y the y coordinate of the image reference anchor top-left point.
781  * @param[in] rotationX the x coordinate of the rotation center.
782  * @param[in] rotationY the y coordinate of the rotation center.
783  * @param[in] angle the rotation angle.
784  * @param[in] alpha the opacity level to apply to the region.
785  *
786  * @return the drawing status.
787  */
788 DRAWING_Status UI_DRAWING_drawRotatedImageBilinear(MICROUI_GraphicsContext* gc, MICROUI_Image* img, jint x, jint y, jint rotationX, jint rotationY, jfloat angle, jint alpha);
789 
790 /*
791  * @brief Draws an image applying a scaling.
792  *
793  * This method uses the nearest neighbor algorithm to render the content. This algorithm
794  * is faster than bilinear algorithm but its rendering is faster.
795  *
796  * @param[in] gc the MicroUI GraphicsContext target.
797  * @param[in] img the MicroUI Image to draw.
798  * @param[in] x the x coordinate of the image reference anchor top-left point.
799  * @param[in] y the y coordinate of the image reference anchor top-left point.
800  * @param[in] factorX scaling X factor.
801  * @param[in] factorY scaling Y factor.
802  * @param[in] alpha the opacity level to apply to the region.
803  *
804  * @return the drawing status.
805  */
806 DRAWING_Status UI_DRAWING_drawScaledImageNearestNeighbor(MICROUI_GraphicsContext* gc, MICROUI_Image* img, jint x, jint y, jfloat factorX, jfloat factorY, jint alpha);
807 
808 /*
809  * @brief Draws an image applying a scaling.
810  *
811  * This method uses the bilinear algorithm to render the content. This algorithm
812  * performs better rendering than nearest neighbor algorithm but it is slower to
813  * apply.
814  *
815  * @param[in] gc the MicroUI GraphicsContext target.
816  * @param[in] img the MicroUI Image to draw.
817  * @param[in] x the x coordinate of the image reference anchor top-left point.
818  * @param[in] y the y coordinate of the image reference anchor top-left point.
819  * @param[in] factorX scaling X factor.
820  * @param[in] factorY scaling Y factor.
821  * @param[in] alpha the opacity level to apply to the region.
822  *
823  * @return the drawing status.
824  */
825 DRAWING_Status UI_DRAWING_drawScaledImageBilinear(MICROUI_GraphicsContext* gc, MICROUI_Image* img, jint x, jint y, jfloat factorX, jfloat factorY, jint alpha);
826 
827 // --------------------------------------------------------------------------------
828 // EOF
829 // --------------------------------------------------------------------------------
830 
831 #ifdef __cplusplus
832 }
833 #endif
834 #endif // UI_DRAWING_H