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