SDK 6.3/C++/Native API

From WowWiki
Revision as of 09:14, 26 July 2026 by WowBot (talk | contribs) (C++ (WASM) and Rust API reference for SDK 6.3 (WowBot))
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search
Official WOWCube SDK documentation. SDK 6.3, C++ (WebAssembly) API. Signatures are extracted from the canonical SDK headers shipped with the WOWCube Development Kit; the headers remain authoritative.

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 · C++ / Native API

The low-level C ABI available to C/C++ (and Rust) cubeapps, declared in native.h. These are the same engine functions as the PAWN API — descriptions of shared functions below are taken from the official SDK reference. On top of this layer the SDK provides the object-oriented Application framework and the GFX Engine.

Types and data structures

Defined in native.h / native_defines.h: 

typedef uint32_t u32_t;   typedef int32_t i32_t;
typedef int32_t soundID_t; typedef int32_t spriteID_t;
union AppVersion_t { uint32_t full; struct { uint16_t patch:16; uint8_t minor:4; uint8_t major:4; uint8_t reserved:8; }; };
struct TOPOLOGY_faceletInfo_t { int32_t module; int32_t screen; int32_t connected; };
struct TOPOLOGY_place_t      { int32_t face; int32_t position; };
struct TOPOLOGY_twistInfo_t  { int32_t screen; int32_t count; int32_t direction; };
struct LB_info_t   { int32_t boardCount; int32_t selfPosition; int32_t selfScore; int32_t wholeUserListCount; };
struct GFX_Particle_t { ttl, vx, vy, ax, ay, explosion, velocity, duration, frequency, max, loop, time };

Enumerations: TOPOLOGY_twist_t (LEFT/RIGHT/DOUBLE), TOPOLOGY_orientation_mode_t (MENU/GRAVITY/SPLASH), TOPOLOGY_orientation_t (UP/DOWN/FRONT/BACK/LEFT/RIGHT), TOPOLOGY_neighbor_t (SELF/LEFT/DIAGONAL/TOP/RIGHT/BOTTOM), text_align_t (9 values), GFX_mirror_t (BLANK/X/Y/XY), GFX_PixelFormat_t (RGB565/ARGB6666/ARGB8888), eventMask_t, LogLevel_t, uartID_t. Constant: NET_BROADCAST = 0xFF; global cubeN — the index of the module the code is running on.

Core

sendPacket

Syntax: 

i32_t sendPacket(u32_t type, uint8_t* pkt, u32_t size)

Description:

Send a packet to another module. Use NET_BROADCAST (0xFF) as the destination to reach all modules. Low-level counterpart of the PAWN broadcastPacket().

recvPacket

Syntax: 

i32_t recvPacket(u32_t size, uint32_t* type, uint8_t* pkt)

Description:

Read a pending inter-module packet into a buffer. Normally consumed by the AppManager event loop, which dispatches it to Application::on_Message().

getTime

Syntax: 

i32_t getTime()

Description:

Get time in milliseconds since the module start.

Return values:

Time in milliseconds since the module start.

getUserName

Syntax: 

i32_t getUserName(uint8_t* buffer, u32_t bufSize)

Description:

Get the name of a user who is logined on the cube.
Get the user name configured in the WOWCube mobile application to save
results for.

toggleDebugInfo

Syntax: 

i32_t toggleDebugInfo()

Description:

Toggle overlay with debug information. TBD - move to GFX

saveState

Syntax: 

i32_t saveState(void* data, u32_t size)

Description:

Request to save an application data
Save user settings and/or progress on the flash to restore next time. Each
save data has an incremental ID.

Return values:

True if save was successful.

History:

v5.0 - fixed a bug in which only part of a data saved on the flash

loadState

Syntax: 

i32_t loadState(u32_t* id, void* data, u32_t size)

Description:

Request to load an application save data from the flash.
Trigger state load event. It is asynchronous so access to flash memory will
not affect an application performance.

random

Syntax: 

i32_t random(u32_t min, u32_t max)

Description:

Generate random number in half-open range.
Random number generator is initialized before each application start. Seed
for initialization is generated by TRNG (True Random Number Generator).

Return values:

Pseudo random value from requested range.

History:

v5.0 - fixed a bug in which random does not generate numbers in a given
range.

getAppVersion

Syntax: 

i32_t getAppVersion(Cubios::AppVersion_t *version)

Description:

Get application version.
WOWCube applications follow semantic versioning scheme (see
https://semver.org). This interface allows to get version parts stored in
the cube application descriptor.
Outputs
  • version - structure describing application version

History:

v6.0 - added

LOG

Syntax: 

i32_t LOG(uint8_t level, const char* text)

Description:

Write a log line with the given level. Prefer the LOG_a/e/w/i/d/v printf-style macros (see LogLevel_t).

getTap

Syntax: 

i32_t getTap()

Description:

Get the pending tap event, if any. Normally consumed by the AppManager event loop (Application::on_Tap() / on_Pat()).

sendBleData

Syntax: 

i32_t sendBleData(u32_t type, uint8_t* pkt, u32_t size)

Description:

Send external data over BLE to the connected companion (WOWCube Connect) application.

recvBleData

Syntax: 

i32_t recvBleData(uint8_t* pkt, u32_t size)

Description:

Receive pending external BLE data; dispatched by AppManager to Application::on_ExternalMessage().

EVENT_getList

Syntax: 

i32_t EVENT_getList()

Description:

Get the pending event mask for this module (see eventMask_t).

Topology

TOPOLOGY_getAdjacentFacelet

Syntax: 

i32_t TOPOLOGY_getAdjacentFacelet(u32_t module, u32_t screen, u32_t direction, Cubios::TOPOLOGY_faceletInfo_t* result)

Description:

Get a facelet neighbor in the given direction.
Facelet can have neighbors on the same cube face or neighbors by module.
This function provide a neighbor of the given facelet in the given
direction. Connection status indicates if there is a connection between
modules on which given facelet and its neighbor are located.

Return values:

Neighbor facelet in a given direction with its connection status. The
module ID will be MODULES_MAX and the screen number will be SCREENS_MAX in
case of an error (e.g. incorrect arguments or the topology malfunction).

TOPOLOGY_getFacelet

Syntax: 

i32_t TOPOLOGY_getFacelet(u32_t face, u32_t position, Cubios::TOPOLOGY_orientation_mode_t mode, Cubios::TOPOLOGY_faceletInfo_t* result)

Description:

Get a facelet located in the given place.

Return values:

Facelet located in the given place, connection status indicates if there
any connection to the module on which this facelet resides. The module ID
will be MODULES_MAX and the screen screen will be SCREENS_MAX in case of an
error (e.g. incorrect arguments or the topology malfunction).

TOPOLOGY_getPlace

Syntax: 

i32_t TOPOLOGY_getPlace(u32_t module, u32_t screen, Cubios::TOPOLOGY_orientation_mode_t mode, Cubios::TOPOLOGY_place_t* result)

Description:

Get a place of the facelet.

Return values:

Place on cube surface where the given facelet located. Face will be
TOPOLOGY_FACES_MAX and position will be TOPOLOGY_POSITIONS_MAX in case of
an error (e.g. incorrect arguments or topology malfunction)

TOPOLOGY_getOppositeFacelet

Syntax: 

i32_t TOPOLOGY_getOppositeFacelet(u32_t module, u32_t screen, Cubios::TOPOLOGY_faceletInfo_t* result)

Description:

Get an opposite facelet located on a diagonal counterpart module.

Return values:

Diagonal opposite counterpart facelet. Connection status indicates if there
any connection to the module on which that facelet resides. The module ID
will be MODULES_MAX and the screen number will be SCREENS_MAX in case of an
error (e.g. incorrect arguments or topology malfunction).

TOPOLOGY_getAngle

Syntax: 

i32_t TOPOLOGY_getAngle(u32_t module, u32_t screen, Cubios::TOPOLOGY_orientation_mode_t mode)

Description:

Get an angle to align images on a face according to the orientation mode.
Display coordinates system is persistent on a module screen. Different
angles are needed to align images on all modules with screens on the same
face. This function returns the angle for the screen specified by the
facelet. The angle is relative to the position 0 on the same face where the
facelet is located in the given orientation mode.

Return values:

Angle to align images on the same face according to the orientation mode, 0
in case of an error (e.g. incorrect arguments or the topology malfunction).

TOPOLOGY_getFaceletOrientation

Syntax: 

i32_t TOPOLOGY_getFaceletOrientation(u32_t module, u32_t screen)

Description:

Get a face orientation on which the given facelet resides.

Return values:

Face orientation on which the given facelet resides, ORIENTATION_MAX in
case of an error (e.g. incorrect arguments or the topology malfunction).

History:

v5.0 - renamed from TOPOLOGY_getFaceletLocation() to the
TOPOLOGY_getFaceletOrientation()

TOPOLOGY_getPlaceOrientation

Syntax: 

i32_t TOPOLOGY_getPlaceOrientation(u32_t face, u32_t position)

Description:

Get a face orientation on which the given place resides.

Return values:

Face orientation on which the given place resides, ORIENTATION_MAX in case
of an error (e.g. incorrect arguments or the topology malfunction).

History:

v5.0 - renamed from TOPOLOGY_getPlaceLocation() to the
TOPOLOGY_getPlaceOrientation()

TOPOLOGY_getFace

Syntax: 

i32_t TOPOLOGY_getFace(u32_t orientation)

Description:

Get a face number which has the given orientation.

Return values:

Face number which has the given orientation, TOPOLOGY_FACES_MAX in case of
an error (e.g. incorrect arguments or the topology malfunction).

TOPOLOGY_isAssembled

Syntax: 

i32_t TOPOLOGY_isAssembled()

Description:

Check that all modules in a system are connected to each other.

Return values:

True if all modules in a system are connected to each other, false
otherwise.

TOPOLOGY_getTwist

Syntax: 

i32_t TOPOLOGY_getTwist(Cubios::TOPOLOGY_twistInfo_t* twist)

Description:

Read the pending twist event into a TOPOLOGY_twistInfo_t. Normally consumed by AppManager, which calls Application::on_Twist().

Leaderboard

LB_getInfo

Syntax: 

i32_t LB_getInfo(Cubios::LB_info_t* info)


LB_getScore

Syntax: 

i32_t LB_getScore(uint8_t* leadTableBin, u32_t bufSize)


Motion Sensors

MS_getFaceAccelX

Syntax: 

i32_t MS_getFaceAccelX(u32_t display)

Description:

Get accelerometer value along X axis of some display.

Return values:

Accelerometer value along X axis.

MS_getFaceAccelY

Syntax: 

i32_t MS_getFaceAccelY(u32_t display)

Description:

Get accelerometer value along Y axis of some display.

Return values:

Accelerometer value along Y axis.

MS_getFaceAccelZ

Syntax: 

i32_t MS_getFaceAccelZ(u32_t display)

Description:

Get accelerometer value along Z axis of some display.

Return values:

Accelerometer value along Z axis.

MS_getFaceGyroX

Syntax: 

i32_t MS_getFaceGyroX(u32_t display)

Description:

Get gyroscope value around X axis of some display.

Return values:

Gyroscope value around X axis.

MS_getFaceGyroY

Syntax: 

i32_t MS_getFaceGyroY(u32_t display)

Description:

Get gyroscope value around Y axis of some display.

Return values:

Gyroscope value around Y axis.

MS_getFaceGyroZ

Syntax: 

i32_t MS_getFaceGyroZ(u32_t display)

Description:

Get gyroscope value around Z axis of some display.

Return values:

Gyroscope value around Z axis.

Graphics

GFX_getAssetId

Syntax: 

i32_t GFX_getAssetId(const char* spriteName)

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.

Return values:

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

History:

v5.0 - renamed from GFX_getId() to GFX_getAssetId()
v6.0 - truncate asset name in WASM API

GFX_clear

Syntax: 

i32_t GFX_clear(u32_t color)

Description:

Clear a layer with a given color.

History:

v6.0 - changed color format

GFX_drawText

Syntax: 

i32_t GFX_drawText(i32_t x, i32_t y, u32_t scale, u32_t angle, u32_t align, u32_t color, const char* text)

Description:

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

History:

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

GFX_drawPoint

Syntax: 

i32_t GFX_drawPoint(i32_t x, i32_t y, u32_t color)

Description:

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

History:

v5.0 - added GFX_drawPointXY() alias

GFX_drawCircle

Syntax: 

i32_t GFX_drawCircle(u32_t x, u32_t y, u32_t radius, u32_t width, u32_t color)

Description:

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

History:

v5.0 - added GFX_drawCircleXY() alias

GFX_drawSolidCircle

Deprecated. use fill shader intead

Syntax: 

i32_t GFX_drawSolidCircle(u32_t x, u32_t y, u32_t radius, u32_t color)

Description:

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

History:

v5.0 - added GFX_drawSolidCircleXY() alias
v6.0 - DEPRECATED, use GFX_setFillShader() instead

GFX_drawArc

Syntax: 

i32_t GFX_drawArc(i32_t x, i32_t y, u32_t radius, u32_t width, u32_t angle0, u32_t angle1, u32_t color)

Description:

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

History:

v5.0 - added GFX_drawArcXY() alias

GFX_drawSector

Syntax: 

i32_t GFX_drawSector(i32_t x, i32_t y, u32_t radius, u32_t angle0, u32_t angle1, u32_t color)

Description:

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

History:

v5.1 - created

GFX_drawLine

Syntax: 

i32_t GFX_drawLine(i32_t x0, i32_t y0, i32_t x1, i32_t y1, u32_t thickness, u32_t color)

Description:

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

History:

v5.0 - added GFX_drawLineXY() alias

GFX_drawRectangle

Syntax: 

i32_t GFX_drawRectangle(i32_t x, i32_t y, i32_t w, i32_t h, u32_t color)

Description:

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

History:

v5.0 - added GFX_drawRectangleXY() alias

GFX_bakeImage

Syntax: 

i32_t GFX_bakeImage(spriteID_t id, u32_t width, u32_t height, GFX_PixelFormat_t format, u32_t overwrite)

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.

History:

v6.0 - added overwrite parameter

GFX_setRenderTarget

Syntax: 

i32_t GFX_setRenderTarget(u32_t display)

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.

History:

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

GFX_drawImage

Syntax: 

i32_t GFX_drawImage(spriteID_t id, i32_t x, i32_t y, u32_t opacity, u32_t colorKey, u32_t scale_x, u32_t scale_y, u32_t angle, u32_t mirror)

Description:

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

History:

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

GFX_drawBakedImage

Syntax: 

i32_t GFX_drawBakedImage(i32_t x, i32_t y, u32_t opacity, u32_t colorKey, u32_t scale_x, u32_t scale_y, u32_t angle, u32_t mirror, spriteID_t id)

Description:

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

History:

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

GFX_drawQrCode

Syntax: 

i32_t GFX_drawQRCode(i32_t x, i32_t y, u32_t size, u32_t color0, u32_t color1, u32_t angle, u32_t id, const char *text)

Description:

Generate and draw QR-code for a given text string.
Supported version 2 which is limited by 32 characters of input.

History:

v6.0 - added

GFX_render

Syntax: 

i32_t GFX_render()

Description:

Start rendering process.

GFX_clearCache

Syntax: 

i32_t 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.

GFX_removeBakedImage

Syntax: 

i32_t GFX_removeBakedImage(spriteID_t 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.

History:

v6.0 - added

GFX_cacheImages

Syntax: 

i32_t GFX_cacheImages(spriteID_t* spriteIDs, u32_t count)

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.

Return values:

Number of cached images or negative value if an error happened. Error
codes:
* -1 invalid function arguments count
* -2 invalid imageList array

History:

v5.0 - moved from appCtrl module to graphics

GFX_setFpsWindow

Syntax: 

i32_t GFX_setFpsWindow(u32_t size)

Description:

Set the averaging window (in frames) used by the on-screen FPS counter (see Application::ShowFPSCounter()).

GFX_getAssetsCount

Syntax: 

i32_t GFX_getAssetsCount()

Description:

Get the total count of graphic assets.

Return values:

Number of graphic assets.

History:

v6.0 - added

GFX_setFillShader

Syntax: 

i32_t GFX_setFillShader(u32_t color)

Description:

Fill next primitives with specified color.

History:

v6.0 - added primitives shading

GFX_setLinearGradientShader

Syntax: 

i32_t GFX_setLinearGradientShader(u32_t x0, u32_t y0, u32_t x1, u32_t y1, u32_t color0, u32_t color1)

Description:

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

History:

v6.0 - added primitives shading

GFX_setRadialGradientShader

Syntax: 

i32_t GFX_setRadialGradientShader(u32_t x0, u32_t y0, u32_t radius, u32_t color0, u32_t color1)

Description:

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

History:

v6.0 - added primitives shading

GFX_removeShader

Syntax: 

i32_t GFX_removeShader()

Description:

Do not use shading in next primitives.

History:

v6.0 - added primitives shading

GFX_drawSubImage

Syntax: 

i32_t GFX_drawSubImage(spriteID_t id,i32_t x,i32_t y,u32_t rect_x,u32_t rect_y,u32_t rect_w,u32_t rect_h,u32_t opacity,u32_t colorKey,u32_t scale_x, u32_t scale_y,u32_t angle, u32_t mirror)

Description:

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

History:

v6.2 - added

Sound

SND_getAssetId

Syntax: 

i32_t SND_getAssetId(const char* soundName)

Description:

Get a sound ID by the filename.

Return values:

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

History:

v5.0 - renamed from SND_getId() to SND_getAssetId()
v6.0 - truncate asset name in WASM API

SND_play

Syntax: 

i32_t SND_play(soundID_t soundID, u32_t volume)

Description:

Play sound by ID.
Play any sound by its ID. Platform does not support audio mixing, so
previously playing sound will be stopped if it has not yet finished.
Supported audio formats:
  • WAV
  • MP3
  • MIDI

SND_cacheSounds

Syntax: 

i32_t SND_cacheSounds(soundID_t* soundIDs, u32_t count)

Description:

Force platform to cache application sounds.
Platform automatically reads and caches sounds from flash when the
application plays a sound. 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 sound data in advance.
However if application requests to play a non-cached sound and there is not
enough memory then oldest accessed sounds will be removed from cache. Also
there is a limit of 256 for a total number of cached sounds.

Return values:

Number of cached sounds or negative value if an error happened. Error
codes:
* -1 invalid function arguments count
* -2 invalid soundList array

History:

v5.0 - moved from appCtrl module to sound

SND_isPlaying

Syntax: 

i32_t SND_isPlaying()

Description:

Check if audio is playing.

Return values:

True if audio is playing, false otherwise.

History:

v6.0 - added

SND_stop

Syntax: 

i32_t SND_stop()

Description:

Stop playing sound if any.

History:

v6.0 - added

SND_getAssetsCount

Syntax: 

i32_t SND_getAssetsCount()

Description:

Get the total count of sound assets.

Return values:

Number of sound assets.

History:

v6.0 - added
Retrieved from "https://wiki.wowcube.com/index.php?title=SDK_6.3/C%2B%2B/Native_API&oldid=16937"