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