SDK 6.3/C++/GFX Engine

From WowWiki
Jump to navigation Jump to search
Official WOWCube SDK documentation. SDK 6.3, C++ (WebAssembly) API. Signatures are extracted from the canonical SDK headers; usage notes and examples come from the official sample projects 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++ / GFX Engine

The object-oriented retained layer of the C++ SDK (namespace Cubios): a scene graph with sprites, text, backgrounds, sounds and math primitives. It sits on top of the native ABI and is driven by the Application framework.

The canonical pattern

Every official sample follows the same lifecycle:

  1. Create objects once at startup and register them in the application's Scene under integer IDs (usually an enum).
  2. Render every frame: for each of the module's three Screens open a Begin()/End() block and Add() the scene objects you want on that screen, chaining setters.

Resource creation (from the official Network/Messaging2 sample): 

void Messaging2::InitializeResources()
{
    this->Scene.CreateObjectWithID(GfxObjects::idle, new Sprite("idle.png", Transform(120,120,0)));
    this->Scene[GfxObjects::idle]->Color.Set(0xFFFFFFFF);
    this->Scene.CreateObjectWithID(GfxObjects::background, new Sprite("background.png", Transform(120,120,0)));
    this->SetTimer(Timers::mainTimer, 30);
}

Per-frame rendering (from the official GFX Engine Sample 1 — Twinkle): 

void Twinkle::on_Render(std::array<Cubios::Screen, 3>& screens)
{
    Background* bkg = (Background*)this->Scene[Sprites::Clear];
    for(auto it = screens.begin(); it != screens.end(); ++it)
    {
        it->Begin(TOPOLOGY_orientation_mode_t::ORIENTATION_MODE_GRAVITY, true);
            it->Add(bkg->SetColor(0xFF000044));
            if(TOPOLOGY_isAssembled()==1)
            {
                switch(it->Position())   // screen's place on the cube face
                {
                    case 0: it->Add(this->Scene[Sprites::MyUfo])->SetPosition(pos.X-280, pos.Y-280); break;
                    case 1: it->Add(this->Scene[Sprites::MyUfo])->SetPosition(pos.X,     pos.Y-280); break;
                    case 2: it->Add(this->Scene[Sprites::MyUfo])->SetPosition(pos.X,     pos.Y);     break;
                }
            }
        it->End();
    }
}

Units and conventions (as used across all official samples): screens are 240×240 px; colors are packed 0xAARRGGBB (Math::Color); Transform rotation is in degrees, scale is in percent (100 = 1:1); all Set* methods return SceneObject*, so calls chain: screen.Add(obj)->SetPosition(x,y)->SetAf(0.5f). To make one logical object span several screens of a face, samples draw it on each screen with a ±280 px offset per screen position (as above).

Scene

The retained scene graph owned by every Application (field app.Scene). It is an ID-addressed registry of objects and sounds; it owns them and disposes them for you.

uint32_t CreateObject(SceneObject* obj);
Register an object; returns its auto-assigned ID. The scene takes ownership.
bool CreateObjectWithID(uint32_t id, SceneObject* obj);
Register under an explicit ID (usually an enum value). Fails (returns false) if the ID is taken. The most common way to build a scene in the official samples.
uint32_t CreateSound(Sound* obj); / bool CreateSoundWithID(uint32_t id, Sound* obj);
Same, for sounds.
SceneObject* operator[](uint32_t);
Look an object up by ID: this->Scene[Sprites::MyUfo].
bool DisposeObjectWithID(uint32_t id); / bool DisposeSoundWithID(uint32_t id); / void DisposeAllObjects();
Remove and delete objects/sounds.
void Play(uint32_t id, uint8_t volume);
Play a registered sound by ID.

SceneObject

Base class of every visual object. Holds a Math::Transform, a Math::Color and a Visible flag. All setters are chainable (return SceneObject*).

virtual void Render() = 0;
Implemented by each concrete object; called by the engine when the object was Add()-ed to a screen in the current frame.
SetPosition(float x, float y) / SetPosition(const Math::Vec2&) / SetTransform(const Math::Transform&)
Place the object (240×240 screen space). The most-used call in the official samples.
SetRotation(int r)
Rotation in degrees; normalized into 0–359 (negative values allowed).
SetScale(unsigned s) / SetScale(sx, sy) / SetXScale(s) / SetYScale(s)
Scale in percent (100 = original size).
SetMirroring(unsigned m)
Mirror mode (GFX_mirror_t: BLANK/X/Y/XY).
SetColor(uint32_t argb) / SetR/SetG/SetB(uint8_t) / SetA(uint8_t) / SetAf(float) / SetAfSafe(float)
Tint/opacity. SetAf takes 0.0–1.0; SetAfSafe clamps out-of-range values (added in SDK 5.1).
SetVisible(bool)
Hide without removing from the scene.
const Math::Vec2 ScreenPosition();
The object's position converted to physical-screen space, taking the screen's current rotation angle (0/90/180/270°) into account.
Move(float dx, float dy) / Move(const Math::Vec2&)
Screen-angle-aware relative move. Only valid inside a Screen::Begin()/End() block — otherwise it logs a warning and does nothing.

Public fields: Math::Transform Transform; Math::Color Color; bool Visible;

Screen

One of the three displays of the current module; an array std::array<Screen, 3> is passed to on_Render() / on_PhysicsTick().

void Begin(TOPOLOGY_orientation_mode_t mode = ORIENTATION_MODE_MENU, bool autorotation = false); / void End();
Open/close the frame block for this screen. mode selects the orientation reference (MENU / GRAVITY / SPLASH); with autorotation = true content is auto-rotated as the cube is turned (samples use ORIENTATION_MODE_GRAVITY, true).
SceneObject* Add(SceneObject* obj);
Queue a scene object for rendering on this screen this frame; returns the object for chaining.
SceneObject* AddCopy(SceneObject* obj);
Queue an independent copy — the standard way to draw the same object several times with different positions in one frame (heavily used in the samples).
uint8_t ID();
Physical display index — pass to native calls such as MS_getFaceAccelX(screen.ID()).
uint8_t Position();
The screen's place on its cube face (see the render sample above — used to compute cross-screen offsets).
uint8_t Face(); / uint8_t OppositeFace(); / TOPOLOGY_orientation_t Direction();
Topology of the screen: which face it belongs to, the opposite face, and the facing direction (UP/DOWN/FRONT/…).
void SetOrientation(TOPOLOGY_orientation_mode_t mode); / uint32_t Angle(); / bool IsAutorotation();
Orientation control and current rotation angle of the content.

Gfx::Sprite

Static image sprite bound to an image asset by file name (from the app's packed assets/). 

Sprite(std::string name);
Sprite(std::string name, float x, float y);
Sprite(std::string name, const Cubios::Math::Transform& t);
Sprite(const Sprite& sprite);
void Render() override;

Typical use: new Sprite("idle.png", Transform(120,120,0)) — center of a 240×240 screen.

Gfx::Background

Full-screen fill. Background(uint32_t argb) or Background(R,G,B[,A]); recolor at render time via SetColor(...) (see the Twinkle sample above — one shared background object recolored per screen).

Gfx::Text

Text object. 

Text(std::string text, float x, float y, uint32_t fontSize = 10);
Text(std::string text, float x, float y, uint32_t fontSize, const Math::Color& color);
Text(std::string text, const Math::Transform& t, uint32_t fontSize, const Math::Color& color,
     text_align_t al = TEXT_ALIGN_CENTER);
SetContent(std::string) / FormatContent(const char* fmt, ...)
Replace the text; FormatContent is printf-style — handy for scores/counters.
SetFontSize(uint32_t)
Change size. Alignment via the public Alignment field (text_align_t, 9 anchors).

Gfx::AnimatedSprite

Frame-animated sprite. Three ways to construct: an explicit list of asset names; a name pattern (name + frameNumber + extension) with a first/last frame range; or a SpriteAtlas.

int16_t Tick(uint32_t dt);
Advance the animation; call from on_Tick(time, dt) for every animated sprite. Returns the current frame.
SetPlaybackMode(playbackMode_t)
Loop (wrap around), Bounce (ping-pong), Set (manual frame control).
SetPlaybackSpeed(int16_t) / SetFrame(int16_t) / NextFrame() / PrevFrame()
Speed and manual frame stepping.

Gfx::SpriteAtlas

A sprite sheet: one image asset cut into sub-rectangles, each rendered by a SpriteAtlasElement registered in the scene. Added in SDK 6.2 — saves memory versus per-frame images. 

SpriteAtlas<SpriteAtlasElement> atlas("sheet.png", &this->Scene);
atlas.AddSprite(MyIds::run0, Math::Rect2(0,   0, 64, 64));
atlas.AddSprite(MyIds::run1, Math::Rect2(64,  0, 64, 64));
bool AddSprite(uint32_t id, const Math::Rect2& rc);
Create an element for sub-rectangle rc and register it in the scene under id (fails if the ID is taken).
T* Get(uint32_t) / T* operator[](uint32_t) / size_t Count() / ElementsInsertionOrder()
Element access. SpriteAtlasElement itself is a normal SceneObject (position/scale/color) plus Rect() and Copy(). An atlas can also feed an AnimatedSprite.

Gfx::OffscreenRenderTarget

Render-to-texture: draw objects into an offscreen buffer once, then use the result as a single scene object (a "baked image"). 

OffscreenRenderTarget(u32_t width, u32_t height, GFX_PixelFormat_t format);
void Begin(bool overwrite = false); / void End(); / Add() / AddCopy()
Same block pattern as Screen, but drawing goes into the buffer. overwrite=true re-bakes.
virtual void RenderLayer(renderLayerOrder_t)
Hook to inject drawing BeforeQueue/AfterQueue. Pixel formats: RGB565 / ARGB6666 / ARGB8888.

Gfx::QRCode

QR-code scene object (SDK 6.0+). QRCode(std::string data, x, y[, size]); SetData(), SetSize(), SetColor() / SetBackgroundColor() (fields ColorOnes/ColorZeros). Used by system apps to link the cube with the mobile app.

Sound and SoundCollection

Sound(const std::string& name); → void Play(uint8_t volume = 100);
One sound asset. static Stop() / static bool IsPlaying() control the playback channel.
SoundCollection(std::vector<std::string>&) or (std::vector<Sound*>&)
A set of sounds (SDK 6.2+):
bool PlayRandomSound(uint8_t volume = 100, bool stopCurrent = true);
Play a random one — the idiom behind varied game SFX.
bool RepeatRandomSounds(uint8_t volume, int delayMin, int delayMax, int deltaTime);
Keep playing random sounds with a random delay in [min,max]; call it periodically passing the tick delta.
Stop() / IsPlaying()

NetworkMessage and SaveMessage

Two identical bit-packing serializers with different buffers: NetworkMessage (max MESSAGE_SIZE_MAX) for inter-module packets, SaveMessage (max GAME_SAVE_SIZE) for persistent state (SDK 6.0+).

WriteInt(int value, int bits) / WriteSignedInt(int value, int bits) (signed added in 5.1) / WriteByte / WriteBool / WriteFloat
Append a value using exactly bits bits — pack a whole game state into one packet.
ReadInt(int bits) / ReadSignedInt / ReadByte / ReadBool / ReadFloat
Read back in the same order.
GetData(int& length) / SetData(uint8_t*, int) / Reset(bool zero = false)
Raw buffer access and cursor reset.

Canonical flow: master module packs → SendNetworkMessage(type, &msg) → other modules unpack in on_Message(). For saves: pack → SaveState(&msg); restore via LoadState(&id, &msg).

Scramble

Cube-scramble helper (SDK 6.0+) for puzzle titles: it performs a given number of virtual twists from the current topology and lets the game track how the mapping changes. Subclass it and implement the callbacks.

void StartScramble(uint8_t twistsCount);
Run a scramble of twistsCount random virtual twists.
void VirtualTwist(uint8_t screen, uint8_t direction);
Apply one virtual twist programmatically.
virtual void on_BeforeTwist() = 0;
Called before each scramble twist.
virtual void on_MappingChanged(uint8_t moduleTo, uint8_t screenTo, uint8_t moduleFrom, uint8_t screenFrom) = 0;
Called for every facelet remapped by the twist — move your game state accordingly.
virtual void on_Twist(const TOPOLOGY_twistInfo_t twist) = 0;
Called after the twist with its description. Used across the official Topology samples.

Splashscreen

Standard splash screen with leaderboard integration (SDK 6.0+, reworked in 6.2): title screen, personal best, points table and control hints, rendered from your own sprite assets.

Splashscreen(Application* app, SplsParms::e_LeadersDataType dataType);
Create for an app; dataType selects how values are displayed (number, time, …).
InitSplashScreenSprites(background, mainImage, gameName, QRcode, leaderboardIcon, resultsIcon, twistIcon_1, twistIcon_2, tapIcon_1, tapIcon_2, borderYou)
Bind your sprite IDs to the standard slots (pass −1 to skip a slot).
void Render(Screen* screen); / void Tick(uint32_t currentTime, uint32_t deltaTime);
Drive it from on_Render / on_Tick while the splash is active.
uint32_t GetPersonalBest(); / void SetRecord(uint32_t value);
Personal best score.
SetNamedValue(idx, name, value, type) / SetLabel(idx, text) / SetApplicationName(name) / SetSeparator(s)
Texts and values shown on the splash.
SetLeaderBoardTable(e_LeaderBoardType) / SetLeaderBoardTable(lbTable[FACES][POSITIONS])
Leaderboard source — built-in or your own table.
SetQRCodeLink(link) / SetColors(key, base) / SetPlaybackSpeed(idx, speed)
QR link, color theme, label animation speed.
virtual void RenderUserDefinedScreen(uint8_t type)
Override to add custom splash screens.

Math

Math::Vec2 / Math::Vec2i
2D float/int vectors with arithmetic.
Math::Transform
{ Vec2 Position; int Rotation; unsigned ScaleX, ScaleY; unsigned Mirroring; } — rotation in degrees (SafeRotation() normalizes), scale in percent (100 = 1:1). Constructors: (x,y), (x,y,angle), (x,y,angle,sx,sy), (x,y,angle,mirror), (x,y,angle,sx,sy,mirror).
Math::Color
ARGB color; Set(0xAARRGGBB), per-channel SetA/R/G/B, float alpha SetAf/SetAfSafe. Named constants in Gfx/Colors.h (Colors::black, Colors::white, …).
Math::Rect2
2D rectangle — used for atlas sub-rectangles.

Where to see it all together

The Development Kit ships complete buildable projects using every class above: Basics (1–4), Rendering, Topology, Network (messaging between modules), and GFX Engine Sample Projects (1–3: Twinkle, SnotFlow, …) — create them via the WOWCube SDK extension for VS Code.

Retrieved from "https://wiki.wowcube.com/index.php?title=SDK_6.3/C%2B%2B/GFX_Engine&oldid=16947"