1/****h* PawnLibs/graphics
2 * Description
3 *   TBD: explain basic principles and underlying hardware limitations
4 ******/
5 
6/****s* PawnLibs/graphics/GFX_POINT
7 * Summary
8 *   Array with named fields which represents a point on a screen.
9 * Synopsis
10 */
11#define GFX_POINT [ .x, .y ]
12/*
13 * Description
14 *   Fields:
15 *   * x, y - coordinates of the point
16 ******/
17 
18/****s* PawnLibs/graphics/GFX_RECTANGLE
19 * Summary
20 *   Array with named fields which represents a rectangle.
21 * Synopsis
22 */
23#define GFX_RECTANGLE [ .x, .y, .w, .h ]
24/*
25 * Description
26 *   Fields:
27 *   * x, y - top left coordinates of the rectangle
28 *   * w - width of the rectangle
29 *   * h - height of the rectangle
30 ******/
31 
32/****c* PawnLibs/graphics/GFX_text_align
33 * Summary
34 *   Enumeration of a text align variants.
35 * Synopsis
36 */
37const GFX_text_align: {
38  TEXT_ALIGN_CENTER = 0,
39  TEXT_ALIGN_TOP_CENTER,
40  TEXT_ALIGN_BOTTOM_CENTER,
41  TEXT_ALIGN_LEFT_CORNER,
42  TEXT_ALIGN_LEFT_TOP_CORNER,
43  TEXT_ALIGN_LEFT_BOTTOM_CORNER,
44  TEXT_ALIGN_RIGHT_CORNER,
45  TEXT_ALIGN_RIGHT_TOP_CORNER,
46  TEXT_ALIGN_RIGHT_BOTTOM_CORNER,
47};
48/******/
49 
50/****c* PawnLibs/graphics/GFX_mirror
51 * Summary
52 *   Enumeration of an image mirror variants.
53 * Synopsis
54 */
55const GFX_mirror: {
56  MIRROR_BLANK = 0,
57  MIRROR_X,
58  MIRROR_Y,
59  MIRROR_XY,
60};
61/******/
62 
63/****c* PawnLibs/graphics/GFX_format
64 * Summary
65 *   Enumeration of a pixel color formats.
66 * Synopsis
67 */
68const GFX_format: {
69  FORMAT_RGB565 = 0,
70  FORMAT_ARGB6666,
71  FORMAT_ARGB8888,
72};
73/******/
74 
75/****e* PawnLibs/graphics/ON_Render
76 * Summary
77 *   Render handler.
78 * Synopsis
79 */
80forward ON_Render();
81/*
82 * Description
83 *   Public function with such signature will be called at the end of an
84 *   application loop. Useful to logically divide the application and rendering
85 *   logic. There is no limitations to render entire scene in the ON_Tick()
86 *   handler.
87 ******/
88 
89/****n* PawnLibs/graphics/GFX_getAssetId
90 * Summary
91 *   Get an image ID by the filename.
92 * Synopsis
93 */
94native GFX_getAssetId(const name[]);
95/*
96 * Description
97 *   Usually an application uses image IDs to draw sprites and backgrounds. But
98 *   sometimes IDs are unknown, e.g. in common libraries, or they change rapidly
99 *   during development. This interface can be used to get an ID of the image by
100 *   its filename in the runtime. Maximum asset name length is 15 characters,
101 *   remaining symbols are truncated during lookup.
102 * Inputs
103 *   * name - an image filename for which ID is requested
104 * Return value
105 *   The ID of image with a given filename or -1 in case of error.
106 * See also
107 *   * ON_Init()
108 * History
109 *   * v5.0 - renamed from GFX_getId() to GFX_getAssetId()
110 *   * v6.0 - truncate asset name in WASM API
111 ******/
112 
113/****n* PawnLibs/graphics/GFX_clear
114 * Summary
115 *   Clear a layer with a given color.
116 * Synopsis
117 */
118native GFX_clear(const color);
119/*
120 * Inputs
121 *   * color - a color in RGB888 format to clear a layer with
122 * History
123 *   * v6.0 - changed color format
124 ******/
125 
126/****n* PawnLibs/graphics/GFX_drawPoint
127 * Summary
128 *   Draw a point specified by its coordinates with a given color.
129 * Synopsis
130 */
131native GFX_drawPoint(const point[GFX_POINT], color);
132native GFX_drawPointXY(x, y, color);
133/*
134 * Inputs
135 *   * point or (x, y) - coordinates of point to draw
136 *   * color - a color in ARGB8888 format to draw point with
137 * See also
138 *   * GFX_POINT
139 * History
140 *   * v5.0 - added GFX_drawPointXY() alias
141 ******/
142 
143/****n* PawnLibs/graphics/GFX_drawCircle
144 * Summary
145 *   Draw a circle at the given point with given radius, color and line width.
146 * Synopsis
147 */
148native GFX_drawCircle(const center[GFX_POINT], radius, width, color);
149native GFX_drawCircleXY(x, y, radius, width, color);
150/*
151 * Inputs
152 *   * center or (x, y) - coordinates of the circle center
153 *   * radius - radius of the circle
154 *   * width - line width used to draw the circle
155 *   * color - a color in ARGB8888 format to draw circle with
156 * See also
157 *   * GFX_POINT
158 * History
159 *   * v5.0 - added GFX_drawCircleXY() alias
160 ******/
161 
162/****o* PawnLibs/graphics/GFX_drawSolidCircle
163 * Summary
164 *   Draw a solid circle at the given point with given radius and color.
165 * Synopsis
166 */
167native GFX_drawSolidCircle(const center[GFX_POINT], radius, color);
168native GFX_drawSolidCircleXY(x, y, radius, color);
169/*
170 * Inputs
171 *   * center or (x, y) - coordinates of the circle center
172 *   * radius - radius of the circle
173 *   * color - a color in ARGB8888 format to draw circle with
174 * See also
175 *   * GFX_POINT
176 *   * GFX_setFillShader()
177 *   * GFX_setLinearGradientShader()
178 *   * GFX_setRadialGradientShader()
179 * History
180 *   * v5.0 - added GFX_drawSolidCircleXY() alias
181 *   * v6.0 - DEPRECATED, use GFX_setFillShader() instead
182 ******/
183 
184/****n* PawnLibs/graphics/GFX_drawArc
185 * Summary
186 *   Draw an arc at the given point with given radius, line width, color and
187 *   angles.
188 * Synopsis
189 */
190native GFX_drawArc(const center[GFX_POINT], radius, width, from, to, color);
191native GFX_drawArcXY(x, y, radius, width, from, to, color);
192/*
193 * Inputs
194 *   * center or (x, y) - coordinates of the arc center
195 *   * radius - radius of the arc
196 *   * width - line width used to draw the arc
197 *   * from - starting angle of the arc TBD: in - ? from - ?
198 *   * to - ending angle of the arc TBD: in - ? from - ?
199 *   * color - a color in ARGB8888 format to draw arc with
200 * See also
201 *   * GFX_POINT
202 * History
203 *   * v5.0 - added GFX_drawArcXY() alias
204 ******/
205 
206/****n* PawnLibs/graphics/GFX_drawSector
207 * Summary
208 *   Draw a filled circular sector, connecting the arc to the circle's center
209 *   like a piece of pie.
210 * Synopsis
211 */
212native GFX_drawSector(const center[GFX_POINT], radius, from, to, color);
213native GFX_drawSectorXY(x, y, radius, from, to, color);
214/*
215 * Inputs
216 *   * center or (x, y) - coordinates of the circle's center
217 *   * radius - radius of the circle
218 *   * from - starting angle of the sector TBD: in - ? from - ?
219 *   * to - ending angle of the sector TBD: in - ? from - ?
220 *   * color - a color in ARGB8888 format to draw arc with
221 * See also
222 *   * GFX_POINT
223 * History
224 *   * v5.1 - created
225 ******/
226 
227/****n* PawnLibs/graphics/GFX_drawLine
228 * Summary
229 *   Draw a line with from a given point to another one and given width and
230 *   color.
231 * Synopsis
232 */
233native GFX_drawLine(const start[GFX_POINT], const end[GFX_POINT], width, color);
234native GFX_drawLineXY(xs, ys, xe, ye, width, color);
235/*
236 * Inputs
237 *   * start or (xs, ys) - coordinates of the line starting point
238 *   * end or (xe, ye) - coordinates of the line ending point
239 *   * width - line width to draw
240 *   * color - a color in ARGB8888 format to draw line with
241 * See also
242 *   * GFX_POINT
243 * History
244 *   * v5.0 - added GFX_drawLineXY() alias
245 ******/
246 
247/****n* PawnLibs/graphics/GFX_drawRectangle
248 * Summary
249 *   Draw a solid rectangle at a given position with specified dimensions and a
250 *   color.
251 * Synopsis
252 */
253native GFX_drawRectangle(const rectangle[GFX_RECTANGLE], color);
254native GFX_drawRectangleXY(x, y, w, h, color);
255/*
256 * Inputs
257 *   * rectangle or (x, y, w, h) - top left corner coordinates and dimensions of
258 *     the rectangle to draw
259 *   * color - a color in ARGB8888 format to draw rectangle with
260 * See also
261 *   * GFX_RECTANGLE
262 * History
263 *   * v5.0 - added GFX_drawRectangleXY() alias
264 ******/
265 
266/****n* PawnLibs/graphics/GFX_drawText
267 * Summary
268 *   Draw a formatted text by the specified coordinates with a given color,
269 *   scale, text align and a rotation angle.
270 * Synopsis
271 */
272native GFX_drawText(const center[GFX_POINT], scale, angle, fontId, GFX_text_align: align, color, const format[], {Float,Fixed,_}:...);
273native GFX_drawTextXY(x, y, scale, angle, fontId, GFX_text_align: align, color, const format[], {Float,Fixed,_}:...);
274/*
275 * Inputs
276 *   * center or (x, y) - coordinates of the text center
277 *   * scale - percentage scale, max font size is 200x200px (100%)
278 *   * angle - clockwise rotation angle in degrees
279 *   * fontId - not applicable, reserved for future use
280 *   * align - text align (TBD: double check)
281 *   * color - a color in ARGB8888 format to draw text with
282 *   * format - format string, see log.inc for specification
283 *   * ... - variable values to insert in the resulting string
284 * See also
285 *   * GFX_POINT
286 *   * GFX_text_align
287 *   * PawnLibs/log
288 * History
289 *   * v5.0 - clarified documentation, added GFX_drawTextXY() alias
290 ******/
291 
292/****n* PawnLibs/graphics/GFX_bakeImage
293 * Summary
294 *   Set an ID of a memory buffer to save next rendering result.
295 * Synopsis
296 */
297native GFX_bakeImage(const id, const width, const height, const GFX_format: format, bool: overwrite = true);
298/*
299 * Description
300 *   Specifies the image that will be created by combining the group of
301 *   graphical primitives used between GFX_bakeImage() and GFS_render()
302 *   according their order and taking into account alpha channel in images. HW
303 *   has a limitation and can combine no more than 4 layers simultaneously, so
304 *   if there are more primitives then they will be combined in a cascade.
305 *   Useful for creating complex images like backgrounds for later usage.
306 * Inputs
307 *   * id - an ID of image to access later
308 *   * width, height - image dimensions
309 *   * format - color format of baked image
310 *   * overwrite - true to overwrite previously baked image, false to append on
311 *     top of it
312 * See also
313 *   * GFX_format
314 *   * GFX_render()
315 *   * GFX_removeBakedImage()
316 * History
317 *   * v6.0 - added overwrite parameter
318 ******/
319 
320/****n* PawnLibs/graphics/GFX_setRenderTarget
321 * Summary
322 *   Set a screen which will be used to display next rendering result.
323 * Synopsis
324 */
325native GFX_setRenderTarget(const screen);
326/*
327 * Description
328 *   Cube module is a special device which has 3 independent screens to display
329 *   graphics. GFX_setRenderTarget() specifies a screen number which will be
330 *   used to display a next rendering result. Graphics primitives used in
331 *   between GFX_setRenderTarget() and GFX_render() calls will be combined
332 *   together according their order and taking into account alpha channel in
333 *   images. Resulting image will be immediately flushed onto the given screen.
334 *   HW has a limitation and can combine no more than 4 layers simultaneously,
335 *   so if there are more primitives then they will be combined in a cascade. To
336 *   display anything on the screen GFX_setRenderTarget() has to be always
337 *   called.
338 * Inputs
339 *   * screen - a screen number to render the resulting image on
340 * See also
341 *   * GFX_render()
342 *   * GFX_bakeImage()
343 * History
344 *   * v5.0 - renamed from GFX_updateDisplay() to GFX_setRenderTarget()
345 ******/
346 
347/****n* PawnLibs/graphics/GFX_drawImage
348 * Summary
349 *   Draw an image from application assets at a specified position and with
350 *   given transformations.
351 * Synopsis
352 */
353native GFX_drawImage(const center[GFX_POINT], opacity, colorKey, scaleX, scaleY, angle, GFX_mirror: mirror, id);
354native GFX_drawImageXY(x, y, opacity, colorKey, scaleX, scaleY, angle, GFX_mirror: mirror, id);
355/*
356 * Inputs
357 *   * center or (x, y) - coordinates of the image center to draw
358 *   * opacity - opacity of the entire image, 0 is fully transparent
359 *   * colorKey - transparent background color, pixels of that color will not be
360 *     used for rendering, it is useful for image with color format without
361 *     alpha channel, e.g. RGB565
362 *   * (scaleX, scaleY) - scale in percent from 1 to 100 along the corresponding
363 *     axis
364 *   * angle - clockwise rotation angle in degrees
365 *   * mirror - mirroring variant
366 *   * id - an ID of assets image to draw
367 * See also
368 *   * GFX_POINT
369 *   * GFX_mirror
370 *   * GFX_cacheImages()
371 * History
372 *   * v5.0 - added GFX_drawImageXY() alias, color argument clarified
373 *   * v6.0 - added scale parameters
374 ******/
375 
376/****n* PawnLibs/graphics/GFX_drawSubImage
377 * Summary
378 *   Draw a sub window of an image from application assets at a specified
379 *   position and with given transformations.
380 * Synopsis
381 */
382native GFX_drawSubImage(const center[GFX_POINT], winX, winY, winW, winH, opacity, colorKey, scaleX, scaleY, angle, GFX_mirror: mirror, id);
383native GFX_drawSubImageXY(x, y, winX, winY, winW, winH, opacity, colorKey, scaleX, scaleY, angle, GFX_mirror: mirror, id);
384/*
385 * Inputs
386 *   * center or (x, y) - coordinates of the sub image center to draw
387 *   * (winX, winY, winW, winH) - coordinates of image sub window relative to
388 *     its top level corner
389 *   * opacity - opacity of the entire image, 0 is fully transparent
390 *   * colorKey - transparent background color, pixels of that color will not be
391 *     used for rendering, it is useful for image with color format without
392 *     alpha channel, e.g. RGB565
393 *   * (scaleX, scaleY) - scale in percent from 1 to 100 along the corresponding
394 *     axis
395 *   * angle - clockwise rotation angle in degrees
396 *   * mirror - mirroring variant
397 *   * id - an ID of assets image to draw sub window
398 * See also
399 *   * GFX_POINT
400 *   * GFX_mirror
401 *   * GFX_cacheImages()
402 * History
403 *   * v6.2 - added
404 ******/
405 
406/****n* PawnLibs/graphics/GFX_drawBakedImage
407 * Summary
408 *   Draw a previously baked image at a specified position and with given
409 *   transformations.
410 * Synopsis
411 */
412native GFX_drawBakedImage(const center[GFX_POINT], opacity, colorKey, scaleX, scaleY, angle, GFX_mirror: mirror, id);
413native GFX_drawBakedImageXY(x, y, opacity, colorKey, scaleX, scaleY, angle, GFX_mirror: mirror, id);
414/*
415 * Inputs
416 *   * center or (x, y) - coordinates of the image center to draw
417 *   * opacity - opacity of the entire image, 0 is fully transparent
418 *   * colorKey - transparent background color, pixels of that color will not be
419 *     used for rendering, it is useful for image with color format without
420 *     alpha channel, e.g. RGB565
421 *   * (scaleX, scaleY) - scale in percent from 1 to 100 along the corresponding
422 *     axis
423 *   * angle - clockwise rotation angle in degrees
424 *   * mirror - mirroring variants
425 *   * id - an ID of the baked image to draw
426 * See also
427 *   * GFX_POINT
428 *   * GFX_mirror
429 * History
430 *   * v5.0 - added GFX_drawBakedImageXY() alias, color argument clarified
431 *   * v6.0 - added scale parameters
432 ******/
433 
434/****n* PawnLibs/graphics/GFX_setFillShader
435 * Summary
436 *   Fill next primitives with specified color.
437 * Synopsis
438 */
439native GFX_setFillShader(color);
440/*
441 * Inputs
442 *   * color - a color in ARGB8888 format to fill with
443 * History
444 *   * v6.0 - added primitives shading
445 ******/
446 
447 /****n* PawnLibs/graphics/GFX_setLinearGradientShader
448 * Summary
449 *   Fill next primitives with linear gradient from a given point / color to
450 *   another one.
451 * Synopsis
452 */
453native GFX_setLinearGradientShader(const start[GFX_POINT], const end[GFX_POINT], color0, color1);
454native GFX_setLinearGradientShaderXY(x0, y0, x1, y1, color0, color1);
455/*
456 * Inputs
457 *   * start or (xs, ys) - coordinates of the fill starting point
458 *   * end or (xe, ye) - coordinates of the fill ending point
459 *   * color0 - a color in ARGB8888 format to start fill with
460 *   * color1 - a color in ARGB8888 format to end fill with
461 * History
462 *   * v6.0 - added primitives shading
463 ******/
464 
465  /****n* PawnLibs/graphics/GFX_setRadialGradientShader
466 * Summary
467 *   Fill next primitives with radial gradient from a given point with radius
468 *   and from a given color to another one.
469 * Synopsis
470 */
471native GFX_setRadialGradientShader(const center[GFX_POINT], radius, color0, color1);
472native GFX_setRadialGradientShaderXY(x, y, radius, color0, color1);
473/*
474 * Inputs
475 *   * center or (x, y) - coordinates of the fill center
476 *   * radius - radius of the fill
477 *   * color0 - a color in ARGB8888 format to start fill with
478 *   * color1 - a color in ARGB8888 format to end fill with
479 * History
480 *   * v6.0 - added primitives shading
481 ******/
482 
483/****n* PawnLibs/graphics/GFX_removeShader
484 * Summary
485 *   Do not use shading in next primitives.
486 * Synopsis
487 */
488native GFX_removeShader();
489/*
490 * Inputs
491 * History
492 *   * v6.0 - added primitives shading
493 ******/
494 
495/****n* PawnLibs/graphics/GFX_drawQrCode
496 * Summary
497 *   Generate and draw QR-code for a given text string.
498 * Synopsis
499 */
500native GFX_drawQrCode(const center[GFX_POINT], size, color0, color1, angle, id, const text[]);
501native GFX_drawQrCodeXY(x, y, size, color0, color1, angle, id, const text[]);
502/*
503 * Description
504 *   Supported version 2 which is limited by 32 characters of input.
505 * Inputs
506 *   * center or (x, y) - coordinates of the resulting image of the QR-code to
507 *     draw
508 *   * size - size of the individual square representing a single bit in the
509 *     encodeded text string
510 *   * color0 - color of squares representing zeroes in the ARGB8888 format
511 *   * color1 - color of squares representing ones in the ARGB8888 format
512 *   * angle - clockwise rotation angle in degrees
513 *   * id - an ID of resulting image to distinguish different codes on the same
514       scene, starts from 0
515 *   * text - text string to encode and draw, maximum size is 256 characters
516 * See also
517 *   * GFX_POINT
518 * History
519 *   * v6.0 - added
520 ******/
521 
522/****n* PawnLibs/graphics/GFX_render
523 * Summary
524 *   Start rendering process.
525 * Synopsis
526 */
527native GFX_render();
528/*
529 * See also
530 *   * GFX_setRenderTarget()
531 *   * GFX_bakeImage()
532 ******/
533 
534/****n* PawnLibs/graphics/GFX_cacheImages
535 * Summary
536 *   Force platform to cache application images.
537 * Synopsis
538 */
539native GFX_cacheImages(imageList[], size = sizeof(imageList));
540/*
541 * Description
542 *   Platform automatically reads and caches images from flash when the
543 *   application draws an image. Flash operations are synchronous and may cause
544 *   delays especially when reading large portions of data. To prevent the
545 *   application from lags it is possible to cache image data in advance.
546 *   However if application requests to draw a non-cached image and there is not
547 *   enough memory then oldest accessed images will be removed from cache. Also
548 *   there is a limit of 256 for a total number of cached images.
549 * Inputs
550 *   * imageList - array with IDs of images to cache
551 *   * size - size of imageList array
552 * Return value
553 *   Number of cached images or negative value if an error happened. Error
554 *   codes:
555 *   * -1 invalid function arguments count
556 *   * -2 invalid imageList array
557 * See also
558 *   * GFX_clearCache()
559 * History
560 *   * v5.0 - moved from appCtrl module to graphics
561 ******/
562 
563/****n* PawnLibs/graphics/GFX_clearCache
564 * Summary
565 *   Clear all cached images.
566 * Synopsis
567 */
568native GFX_clearCache();
569/*
570 * Description
571 *   Oldest accessed image cache will be automatically freed if there is not
572 *   enough memory to cache a new image. This function forces this process, e.g.
573 *   when switch game levels.
574 * See also
575 *   * GFX_cacheImages()
576 *   * GFX_removeBakedImage()
577 ******/
578 
579/****n* PawnLibs/graphics/GFX_removeBakedImage
580 * Summary
581 *   Remove specified baked image from cache.
582 * Synopsis
583 */
584native GFX_removeBakedImage(id);
585/*
586 * Description
587 *   Baked images do not automatically invalidate. This function allows to
588 *   remove any baked image from cache to save some space.
589 * Inputs
590 *   * id - an ID of the baked image to remove from cache
591 * See also
592 *   * GFX_clearCache()
593 *   * GFX_bakeImage()
594 * History
595 *   * v6.0 - added
596 ******/
597 
598/****n* PawnLibs/graphics/GFX_getAssetsCount
599 * Summary
600 *   Get the total count of graphic assets.
601 * Synopsis
602 */
603native GFX_getAssetsCount();
604/*
605 * Return value
606 *   Number of graphic assets.
607 * History
608 *   * v6.0 - added
609 ******/
610 
611/****f* PawnLibs/graphics/GFX_fromARGB8888
612 * Summary
613 *   Returns a hexadecimal value of a color constructed from the channel
614 *   components.
615 * Synopsis
616 */
617stock GFX_fromARGB8888(a, r, g, b)
618/*
619 * Inputs
620 *   * a - the alpha channel, valid values are 0 through 255
621 *   * r - the red channel, valid values are 0 through 255
622 *   * g - the green channel, valid values are 0 through 255
623 *   * b - the blue channel, valid values are 0 through 255
624 * Return value
625 *   The hexadecimal value of a color constructed from the channel components.
626 * See also
627 *   * GFX_toARGB8888()
628 * History
629 *   * v5.0 - created
630 * Source
631 */
632{
633    return (a & 0xFF) << 24 | (r & 0xFF) << 16 | (g & 0xFF) << 8 | (b & 0xFF);
634}
635/******/
636 
637/****f* PawnLibs/graphics/GFX_toARGB8888
638 * Summary
639 *   Returns channel values of a color in the hexadecimal format.
640 * Synopsis
641 */
642stock GFX_toARGB8888(value, &a, &r, &g, &b)
643/*
644 * Inputs
645 *   * value - the hexadecimal value of the color
646 * Outputs
647 *   * a - the alpha channel
648 *   * r - the red channel
649 *   * g - the green channel
650 *   * b - the blue channel
651 * See also
652 *   * GFX_fromARGB8888
653 * History
654 *   * v5.0 - created
655 * Source
656 */
657{
658    a = value & 0xFF000000;
659    r = value & 0x00FF0000;
660    g = value & 0x0000FF00;
661    b = value & 0x000000FF;
662}
663/******/
664 
665