PawnLibs/graphics

Description

TBD: explain basic principles and underlying hardware limitations

PawnLibs/graphics/GFX_EMISSION

Summary

Array with named fields with particles emission description.

Synopsis

1#define GFX_EMISSION [ .duration, .frequency, .max, bool:.loop ]
2 

Description

Fields:

• duration - how long particles emit in ms
• frequency - how frequently new particles emit in Hz
• max - how many particles can emit
• loop - keep emission TBD: check?

See also

• GFX_PARTICLE
• GFX_drawParticles()
• GFX_drawParticlesXY()

PawnLibs/graphics/GFX_PARTICLE

Summary

Array with named fields with a single particle description.

Synopsis

1#define GFX_PARTICLE [ .ttl, .vx, .vy, .ax, .ay, bool:.explosion, .velocity ]
2 

Description

Fields:

• ttl - a particles lifetime in ms
• vx, vy - an initial particles velocity in px/ms
• ax, ay - a particles acceleration in px/ms^2
• explosion - an explosion emulation flag
• velocity - an explosion velocity

See also

• GFX_EMISSION
• GFX_drawParticles()
• GFX_drawParticlesXY()

PawnLibs/graphics/GFX_POINT

Summary

Array with named fields which represents a point on a screen.

Synopsis

1#define GFX_POINT [ .x, .y ]
2 

Description

Fields:

• x, y - coordinates of the point

PawnLibs/graphics/GFX_RECTANGLE

Summary

Array with named fields which represents a rectangle.

Synopsis

1#define GFX_RECTANGLE [ .x, .y, .w, .h ]
2 

Description

Fields:

• x, y - top left coordinates of the rectangle
• w - width of the rectangle
• h - height of the rectangle

PawnLibs/graphics/GFX_format

Summary

Enumeration of a pixel color formats.

Synopsis

1const GFX_format: {
2  FORMAT_RGB565 = 0,
3  FORMAT_ARGB6666,
4  FORMAT_ARGB8888,
5};
6 

PawnLibs/graphics/GFX_mirror

Summary

Enumeration of an image mirror variants.

Synopsis

1const GFX_mirror: {
2  MIRROR_BLANK = 0,
3  MIRROR_X,
4  MIRROR_Y,
5  MIRROR_XY,
6};
7 

PawnLibs/graphics/GFX_text_align

Summary

Enumeration of a text align variants.

Synopsis

1const GFX_text_align: {
2  TEXT_ALIGN_CENTER = 0,
3  TEXT_ALIGN_TOP_CENTER,
4  TEXT_ALIGN_BOTTOM_CENTER,
5  TEXT_ALIGN_LEFT_CORNER,
6  TEXT_ALIGN_LEFT_TOP_CORNER,
7  TEXT_ALIGN_LEFT_BOTTOM_CORNER,
8  TEXT_ALIGN_RIGHT_CORNER,
9  TEXT_ALIGN_RIGHT_TOP_CORNER,
10  TEXT_ALIGN_RIGHT_BOTTOM_CORNER,
11};
12 

PawnLibs/graphics/ON_Render

Summary

Render handler.

Synopsis

1forward ON_Render();
2 

Description

Public function with such signature will be called at the end of an application loop. Useful to logically divide the application and rendering logic. There is no limitations to render entire scene in the ON_Tick() handler.

PawnLibs/graphics/GFX_bakeImage

Summary

Set an ID of a memory buffer to save next rendering result.

Synopsis

1native GFX_bakeImage(const id, const width, const height, const GFX_format: format, bool: overwrite = true);
2 

Description

Specifies the image that will be created by combining the group of graphical primitives used between GFX_bakeImage() and GFS_render() according their order and taking into account alpha channel in images. HW has a limitation and can combine no more than 4 layers simultaneously, so if there are more primitives then they will be combined in a cascade. Useful for creating complex images like backgrounds for later usage.

Inputs

• id - an ID of image to access later
• width, height - image dimensions
• format - color format of baked image
• overwrite - true to overwrite previously baked image, false to append on top of it

See also

• GFX_format
• GFX_render()
• GFX_removeBakedImage()

PawnLibs/graphics/GFX_cacheImages

Summary

Force platform to cache application images.

Synopsis

1native GFX_cacheImages(imageList[], size = sizeof(imageList));
2 

Description

Platform automatically reads and caches images from flash when the application draws an image. Flash operations are synchronous and may cause delays especially when reading large portions of data. To prevent the application from lags it is possible to cache image data in advance. However if application requests to draw a non-cached image and there is not enough memory then oldest accessed images will be removed from cache. Also there is a limit of 256 for a total number of cached images.

Inputs

• imageList - array with IDs of images to cache
• size - size of imageList array

Return value

Number of cached images or negative value if an error happened. Error codes:

• -1 invalid function arguments count
• -2 invalid imageList array

See also

• GFX_clearCache()

PawnLibs/graphics/GFX_clear

Summary

Clear a layer with a given color.

Synopsis

1native GFX_clear(const color);
2 

Inputs

• color - a color in RGB888 format to clear a layer with

PawnLibs/graphics/GFX_clearCache

Summary

Clear all cached images.

Synopsis

1native GFX_clearCache();
2 

Description

Oldest accessed image cache will be automatically freed if there is not enough memory to cache a new image. This function forces this process, e.g. when switch game levels.

See also

• GFX_cacheImages()
• GFX_removeBakedImage()

PawnLibs/graphics/GFX_drawArc

Summary

Draw an arc at the given point with given radius, line width, color and angles.

Synopsis

1native GFX_drawArc(const center[GFX_POINT], radius, width, from, to, color);
2native GFX_drawArcXY(x, y, radius, width, from, to, color);
3 

Inputs

• center or (x, y) - coordinates of the arc center
• radius - radius of the arc
• width - line width used to draw the arc
• from - starting angle of the arc TBD: in - ? from - ?
• to - ending angle of the arc TBD: in - ? from - ?
• color - a color in ARGB8888 format to draw arc with

See also

• GFX_POINT

PawnLibs/graphics/GFX_drawBakedImage

Summary

Draw a previously baked image at a specified position and with given transformations.

Synopsis

1native GFX_drawBakedImage(const center[GFX_POINT], opacity, colorKey, scaleX, scaleY, angle, GFX_mirror: mirror, id);
2native GFX_drawBakedImageXY(x, y, opacity, colorKey, scaleX, scaleY, angle, GFX_mirror: mirror, id);
3 

Inputs

• center or (x, y) - coordinates of the image center to draw
• opacity - opacity of the entire image, 0 is fully transparent
• colorKey - transparent background color, pixels of that color will not be used for rendering, it is useful for image with color format without alpha channel, e.g. RGB565
• (scaleX, scaleY) - scale in percent from 1 to 100 along the corresponding axis
• angle - clockwise rotation angle in degrees
• mirror - mirroring variants
• id - an ID of the baked image to draw

See also

• GFX_POINT
• GFX_mirror

PawnLibs/graphics/GFX_drawCircle

Summary

Draw a circle at the given point with given radius, color and line width.

Synopsis

1native GFX_drawCircle(const center[GFX_POINT], radius, width, color);
2native GFX_drawCircleXY(x, y, radius, width, color);
3 

Inputs

• center or (x, y) - coordinates of the circle center
• radius - radius of the circle
• width - line width used to draw the circle
• color - a color in ARGB8888 format to draw circle with

See also

• GFX_POINT

PawnLibs/graphics/GFX_drawImage

Summary

Draw an image from application assets at a specified position and with given transformations.

Synopsis

1native GFX_drawImage(const center[GFX_POINT], opacity, colorKey, scaleX, scaleY, angle, GFX_mirror: mirror, id);
2native GFX_drawImageXY(x, y, opacity, colorKey, scaleX, scaleY, angle, GFX_mirror: mirror, id);
3 

Inputs

• center or (x, y) - coordinates of the image center to draw
• opacity - opacity of the entire image, 0 is fully transparent
• colorKey - transparent background color, pixels of that color will not be used for rendering, it is useful for image with color format without alpha channel, e.g. RGB565
• (scaleX, scaleY) - scale in percent from 1 to 100 along the corresponding axis
• angle - clockwise rotation angle in degrees
• mirror - mirroring variant
• id - an ID of assets image to draw

See also

• GFX_POINT
• GFX_mirror
• GFX_cacheImages()

PawnLibs/graphics/GFX_drawLine

Summary

Draw a line with from a given point to another one and given width and color.

Synopsis

1native GFX_drawLine(const start[GFX_POINT], const end[GFX_POINT], width, color);
2native GFX_drawLineXY(xs, ys, xe, ye, width, color);
3 

Inputs

• start or (xs, ys) - coordinates of the line starting point
• end or (xe, ye) - coordinates of the line ending point
• width - line width to draw
• color - a color in ARGB8888 format to draw line with

See also

• GFX_POINT

PawnLibs/graphics/GFX_drawParticles

Summary

Draw particle system with given parameters.

Synopsis

1native GFX_drawParticles(const center[GFX_POINT], opacity, colorKey, angle, id, const particle[GFX_PARTICLE], const emission[GFX_EMISSION], time);
2native GFX_drawParticlesXY(x, y, opacity, colorKey, angle, id, const particle[GFX_PARTICLE], const emission[GFX_EMISSION], time);
3 

Description

TBD: create extended description how to use a particle system.

Inputs

• center or (x, y) - coordinates of the (TBD: clarify which center) center to draw
• opacity - opacity of the entire particle system, 0 is fully transparent
• colorKey - transparent background color, pixels of that color will not be used for rendering, it is useful for image with color format without alpha channel, e.g. RGB565
• angle - clockwise rotation angle in degrees
• id - an ID of the assets image to use as a particle
• particle - a particle parameters
• emission - a particle emission parameters
• time - TBD: check

See also

• GFX_POINT
• GFX_PARTICLE
• GFX_EMISSION

PawnLibs/graphics/GFX_drawPoint

Summary

Draw a point specified by its coordinates with a given color.

Synopsis

1native GFX_drawPoint(const point[GFX_POINT], color);
2native GFX_drawPointXY(x, y, color);
3 

Inputs

• point or (x, y) - coordinates of point to draw
• color - a color in ARGB8888 format to draw point with

See also

• GFX_POINT

PawnLibs/graphics/GFX_drawQrCode

Summary

Generate and draw QR-code for a given text string.

Synopsis

1native GFX_drawQrCode(const center[GFX_POINT], size, color0, color1, angle, id, const text[]);
2native GFX_drawQrCodeXY(x, y, size, color0, color1, angle, id, const text[]);
3 

Description

Supported version 2 which is limited by 32 characters of input.

Inputs

• center or (x, y) - coordinates of the resulting image of the QR-code to draw
• size - size of the individual square representing a single bit in the encodeded text string
• color0 - color of squares representing zeroes in the ARGB8888 format
• color1 - color of squares representing ones in the ARGB8888 format
• angle - clockwise rotation angle in degrees
• id - an ID of resulting image to distinguish different codes on the same
• text - text string to encode and draw, maximum size is 256 characters

See also

• GFX_POINT

PawnLibs/graphics/GFX_drawRectangle

Summary

Draw a solid rectangle at a given position with specified dimensions and a color.

Synopsis

1native GFX_drawRectangle(const rectangle[GFX_RECTANGLE], color);
2native GFX_drawRectangleXY(x, y, w, h, color);
3 

Inputs

• rectangle or (x, y, w, h) - top left corner coordinates and dimensions of the rectangle to draw
• color - a color in ARGB8888 format to draw rectangle with

See also

• GFX_RECTANGLE

PawnLibs/graphics/GFX_drawSector

Summary

Draw a filled circular sector, connecting the arc to the circle's center like a piece of pie.

Synopsis

1native GFX_drawSector(const center[GFX_POINT], radius, from, to, color);
2native GFX_drawSectorXY(x, y, radius, from, to, color);
3 

Inputs

• center or (x, y) - coordinates of the circle's center
• radius - radius of the circle
• from - starting angle of the sector TBD: in - ? from - ?
• to - ending angle of the sector TBD: in - ? from - ?
• color - a color in ARGB8888 format to draw arc with

See also

• GFX_POINT

PawnLibs/graphics/GFX_drawText

Summary

Draw a formatted text by the specified coordinates with a given color, scale, text align and a rotation angle.

Synopsis

1native GFX_drawText(const center[GFX_POINT], scale, angle, fontId, GFX_text_align: align, color, const format[], {Float,Fixed,_}:...);
2native GFX_drawTextXY(x, y, scale, angle, fontId, GFX_text_align: align, color, const format[], {Float,Fixed,_}:...);
3 

Inputs

• center or (x, y) - coordinates of the text center
• scale - percentage scale, max font size is 200x200px (100%)
• angle - clockwise rotation angle in degrees
• fontId - not applicable, reserved for future use
• align - text align (TBD: double check)
• color - a color in ARGB8888 format to draw text with
• format - format string, see log.inc for specification
• ... - variable values to insert in the resulting string

See also

• GFX_POINT
• GFX_text_align
• PawnLibs/log

PawnLibs/graphics/GFX_getAssetId

Summary

Get an image ID by the filename.

Synopsis

1native GFX_getAssetId(const name[]);
2 

Description

Usually an application uses image IDs to draw sprites and backgrounds. But sometimes IDs are unknown, e.g. in common libraries, or they change rapidly during development. This interface can be used to get an ID of the image by its filename in the runtime. Maximum asset name length is 15 characters, remaining symbols are truncated during lookup.

Inputs

• name - an image filename for which ID is requested

Return value

The ID of image with a given filename or -1 in case of error.

See also

• ON_Init()

PawnLibs/graphics/GFX_getAssetsCount

Summary

Get the total count of graphic assets.

Synopsis

1native GFX_getAssetsCount();
2 

Return value

Number of graphic assets.

PawnLibs/graphics/GFX_removeBakedImage

Summary

Remove specified baked image from cache.

Synopsis

1native GFX_removeBakedImage(id);
2 

Description

Baked images do not automatically invalidate. This function allows to remove any baked image from cache to save some space.

Inputs

• id - an ID of the baked image to remove from cache

See also

• GFX_clearCache()
• GFX_bakeImage()

PawnLibs/graphics/GFX_removeShader

Summary

Do not use shading in next primitives.

Synopsis

1native GFX_removeShader();
2 

Inputs

PawnLibs/graphics/GFX_render

Summary

Start rendering process.

Synopsis

1native GFX_render();
2 

See also

• GFX_setRenderTarget()
• GFX_bakeImage()

PawnLibs/graphics/GFX_setFillShader

Summary

Fill next primitives with specified color.

Synopsis

1native GFX_setFillShader(color);
2 

Inputs

• color - a color in ARGB8888 format to fill with

PawnLibs/graphics/GFX_setLinearGradientShader

Summary

Fill next primitives with linear gradient from a given point / color to another one.

Synopsis

1native GFX_setLinearGradientShader(const start[GFX_POINT], const end[GFX_POINT], color0, color1);
2native GFX_setLinearGradientShaderXY(x0, y0, x1, y1, color0, color1);
3 

Inputs

• start or (xs, ys) - coordinates of the fill starting point
• end or (xe, ye) - coordinates of the fill ending point
• color0 - a color in ARGB8888 format to start fill with
• color1 - a color in ARGB8888 format to end fill with

PawnLibs/graphics/GFX_setRadialGradientShader

Summary

Fill next primitives with radial gradient from a given point with radius and from a given color to another one.

Synopsis

1native GFX_setRadialGradientShader(const center[GFX_POINT], radius, color0, color1);
2native GFX_setRadialGradientShaderXY(x, y, radius, color0, color1);
3 

Inputs

• center or (x, y) - coordinates of the fill center
• radius - radius of the fill
• color0 - a color in ARGB8888 format to start fill with
• color1 - a color in ARGB8888 format to end fill with

PawnLibs/graphics/GFX_setRenderTarget

Summary

Set a screen which will be used to display next rendering result.

Synopsis

1native GFX_setRenderTarget(const screen);
2 

Description

Cube module is a special device which has 3 independent screens to display graphics. GFX_setRenderTarget() specifies a screen number which will be used to display a next rendering result. Graphics primitives used in between GFX_setRenderTarget() and GFX_render() calls will be combined together according their order and taking into account alpha channel in images. Resulting image will be immediately flushed onto the given screen. HW has a limitation and can combine no more than 4 layers simultaneously, so if there are more primitives then they will be combined in a cascade. To display anything on the screen GFX_setRenderTarget() has to be always called.

Inputs

• screen - a screen number to render the resulting image on

See also

• GFX_render()
• GFX_bakeImage()

PawnLibs/graphics/GFX_fromARGB8888

Summary

Returns a hexadecimal value of a color constructed from the channel components.

Synopsis

1stock GFX_fromARGB8888(a, r, g, b)
2 

Inputs

• a - the alpha channel, valid values are 0 through 255
• r - the red channel, valid values are 0 through 255
• g - the green channel, valid values are 0 through 255
• b - the blue channel, valid values are 0 through 255

Return value

The hexadecimal value of a color constructed from the channel components.

See also

• GFX_toARGB8888()

PawnLibs/graphics/GFX_toARGB8888

Summary

Returns channel values of a color in the hexadecimal format.

Synopsis

1stock GFX_toARGB8888(value, &a, &r, &g, &b)
2 

Inputs

• value - the hexadecimal value of the color

Outputs

• a - the alpha channel
• r - the red channel
• g - the green channel
• b - the blue channel

See also

• GFX_fromARGB8888

PawnLibs/graphics/GFX_drawSolidCircle

Summary

Draw a solid circle at the given point with given radius and color.

Synopsis

1native GFX_drawSolidCircle(const center[GFX_POINT], radius, color);
2native GFX_drawSolidCircleXY(x, y, radius, color);
3 

Inputs

• center or (x, y) - coordinates of the circle center
• radius - radius of the circle
• color - a color in ARGB8888 format to draw circle with

See also

• GFX_POINT
• GFX_setFillShader()
• GFX_setLinearGradientShader()
• GFX_setRadialGradientShader()