SDK 6.3/PAWN/Graphics

Official WOWCube SDK documentation. SDK 6.3, PAWN API. Generated from the canonical SDK headers — do not edit by hand; regenerate from source.

Legacy track. The PAWN API is supported but no longer actively developed — the last PAWN additions shipped in SDK 6.2. New development uses the C++ (WebAssembly) API.

SDK 6.3 · PAWN API: Core · Graphics · Topology · Sound · Motion Sensor · Leaderboard · Splash Screen · Physics · Network · Save · Scramble · Logging
C++: Native API · Application · GFX Engine  ·  Rust: Rust API (experimental)  ·  Changelog

← SDK 6.3 · PAWN / Graphics

Enumerations

GFX_text_align

Syntax:

const GFX_text_align: {
  TEXT_ALIGN_CENTER = 0,
  TEXT_ALIGN_TOP_CENTER,
  TEXT_ALIGN_BOTTOM_CENTER,
  TEXT_ALIGN_LEFT_CORNER,
  TEXT_ALIGN_LEFT_TOP_CORNER,
  TEXT_ALIGN_LEFT_BOTTOM_CORNER,
  TEXT_ALIGN_RIGHT_CORNER,
  TEXT_ALIGN_RIGHT_TOP_CORNER,
  TEXT_ALIGN_RIGHT_BOTTOM_CORNER,
};

Description:

Enumeration of a text align variants.

GFX_mirror

Syntax:

const GFX_mirror: {
  MIRROR_BLANK = 0,
  MIRROR_X,
  MIRROR_Y,
  MIRROR_XY,
};

Description:

Enumeration of an image mirror variants.

GFX_format

Syntax:

const GFX_format: {
  FORMAT_RGB565 = 0,
  FORMAT_ARGB6666,
  FORMAT_ARGB8888,
};

Description:

Enumeration of a pixel color formats.

Data structures

GFX_POINT

Syntax:

#define GFX_POINT [ .x, .y ]

Description:

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

Fields:

• x, y - coordinates of the point

GFX_RECTANGLE

Syntax:

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

Description:

Array with named fields which represents a rectangle.

Fields:

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

Event handlers

ON_Render

Syntax:

forward ON_Render();

Description:

Render handler.

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.

Functions

GFX_getAssetId

Syntax:

native GFX_getAssetId(const name[]);

Description:

Get an image ID by the filename.

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.

Arguments:

name

an image filename for which ID is requested

Return values:

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

See also: ON_Init()

History:

v5.0 - renamed from GFX_getId() to GFX_getAssetId()

v6.0 - truncate asset name in WASM API

GFX_clear

Syntax:

native GFX_clear(const color);

Description:

Clear a layer with a given color.

Arguments:

color

a color in RGB888 format to clear a layer with

History:

v6.0 - changed color format

GFX_drawPoint

Syntax:

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

Description:

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

Arguments:

point or (x, y)

coordinates of point to draw

color

a color in ARGB8888 format to draw point with

See also: GFX_POINT

History:

v5.0 - added GFX_drawPointXY() alias

GFX_drawCircle

Syntax:

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

Description:

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

Arguments:

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

History:

v5.0 - added GFX_drawCircleXY() alias

GFX_drawArc

Syntax:

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

Description:

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

angles.

Arguments:

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

History:

v5.0 - added GFX_drawArcXY() alias

GFX_drawSector

Syntax:

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

Description:

Draw a filled circular sector, connecting the arc to the circle's center

like a piece of pie.

Arguments:

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

History:

v5.1 - created

GFX_drawLine

Syntax:

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

Description:

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

color.

Arguments:

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

History:

v5.0 - added GFX_drawLineXY() alias

GFX_drawRectangle

Syntax:

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

Description:

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

color.

Arguments:

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

History:

v5.0 - added GFX_drawRectangleXY() alias

GFX_drawText

Syntax:

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

Description:

Draw a formatted text by the specified coordinates with a given color,

scale, text align and a rotation angle.

Arguments:

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

History:

v5.0 - clarified documentation, added GFX_drawTextXY() alias

GFX_bakeImage

Syntax:

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

Description:

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

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.

Arguments:

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()

History:

v6.0 - added overwrite parameter

GFX_setRenderTarget

Syntax:

native GFX_setRenderTarget(const screen);

Description:

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

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.

Arguments:

screen

a screen number to render the resulting image on

See also: GFX_render(), GFX_bakeImage()

History:

v5.0 - renamed from GFX_updateDisplay() to GFX_setRenderTarget()

GFX_drawImage

Syntax:

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

Description:

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

given transformations.

Arguments:

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()

History:

v5.0 - added GFX_drawImageXY() alias, color argument clarified

v6.0 - added scale parameters

GFX_drawSubImage

Syntax:

native GFX_drawSubImage(const center[GFX_POINT], winX, winY, winW, winH, opacity, colorKey, scaleX, scaleY, angle, GFX_mirror: mirror, id);
native GFX_drawSubImageXY(x, y, winX, winY, winW, winH, opacity, colorKey, scaleX, scaleY, angle, GFX_mirror: mirror, id);

Description:

Draw a sub window of an image from application assets at a specified

position and with given transformations.

Arguments:

center or (x, y)

coordinates of the sub image center to draw

(winX, winY, winW, winH)

coordinates of image sub window relative to

its top level corner

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 sub window

See also: GFX_POINT, GFX_mirror, GFX_cacheImages()

History:

v6.2 - added

GFX_drawBakedImage

Syntax:

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

Description:

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

transformations.

Arguments:

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

History:

v5.0 - added GFX_drawBakedImageXY() alias, color argument clarified

v6.0 - added scale parameters

GFX_setFillShader

Syntax:

native GFX_setFillShader(color);

Description:

Fill next primitives with specified color.

Arguments:

color

a color in ARGB8888 format to fill with

History:

v6.0 - added primitives shading

GFX_setLinearGradientShader

Syntax:

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

Description:

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

another one.

Arguments:

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

History:

v6.0 - added primitives shading

GFX_setRadialGradientShader

Syntax:

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

Description:

Fill next primitives with radial gradient from a given point with radius

and from a given color to another one.

Arguments:

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

History:

v6.0 - added primitives shading

GFX_removeShader

Syntax:

native GFX_removeShader();

Description:

Do not use shading in next primitives.

History:

v6.0 - added primitives shading

GFX_drawQrCode

Syntax:

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

Description:

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

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

Arguments:

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

scene, starts from 0

text

text string to encode and draw, maximum size is 256 characters

See also: GFX_POINT

History:

v6.0 - added

GFX_render

Syntax:

native GFX_render();

Description:

Start rendering process.

See also: GFX_setRenderTarget(), GFX_bakeImage()

GFX_cacheImages

Syntax:

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

Description:

Force platform to cache application images.

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.

Arguments:

imageList

array with IDs of images to cache

size

size of imageList array

Return values:

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()

History:

v5.0 - moved from appCtrl module to graphics

GFX_clearCache

Syntax:

native GFX_clearCache();

Description:

Clear all cached images.

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()

GFX_removeBakedImage

Syntax:

native GFX_removeBakedImage(id);

Description:

Remove specified baked image from cache.

Baked images do not automatically invalidate. This function allows to

remove any baked image from cache to save some space.

Arguments:

id

an ID of the baked image to remove from cache

See also: GFX_clearCache(), GFX_bakeImage()

History:

v6.0 - added

GFX_getAssetsCount

Syntax:

native GFX_getAssetsCount();

Description:

Get the total count of graphic assets.

Return values:

Number of graphic assets.

History:

v6.0 - added

GFX_fromARGB8888

Syntax:

stock GFX_fromARGB8888(a, r, g, b)

Description:

Returns a hexadecimal value of a color constructed from the channel

components.

Arguments:

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 values:

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

See also: GFX_toARGB8888()

History:

v5.0 - created

GFX_toARGB8888

Syntax:

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

Description:

Returns channel values of a color in the hexadecimal format.

Arguments:

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

History:

v5.0 - created

Deprecated

GFX_drawSolidCircle

Deprecated. See History below.

Syntax:

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

Description:

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

Arguments:

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()

History:

v5.0 - added GFX_drawSolidCircleXY() alias

v6.0 - DEPRECATED, use GFX_setFillShader() instead