View source for SDK 6.3/C++/GFX Engine

{{notice|'''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 nav}}

''← [[SDK 6.3]] · C++ / GFX Engine''

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

== The canonical pattern ==

Every official sample follows the same lifecycle:

# '''Create''' objects once at startup and register them in the application's <code>Scene</code> under integer IDs (usually an <code>enum</code>).
# '''Render''' every frame: for each of the module's three <code>Screen</code>s open a <code>Begin()/End()</code> block and <code>Add()</code> 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''' (<code>Math::Color</code>); <code>Transform</code> rotation is in degrees, scale is in percent (100 = 1:1); all <code>Set*</code> methods return <code>SceneObject*</code>, so calls chain: <code>screen.Add(obj)->SetPosition(x,y)->SetAf(0.5f)</code>. 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 <code>Application</code> (field <code>app.Scene</code>). It is an ID-addressed registry of objects and sounds; it owns them and disposes them for you.

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

== SceneObject ==

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

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

Public fields: <code>Math::Transform Transform; Math::Color Color; bool Visible;</code>

== Screen ==

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

; <code>void Begin(TOPOLOGY_orientation_mode_t mode = ORIENTATION_MODE_MENU, bool autorotation = false);</code> / <code>void End();</code>
: Open/close the frame block for this screen. <code>mode</code> selects the orientation reference (MENU / GRAVITY / SPLASH); with <code>autorotation = true</code> content is auto-rotated as the cube is turned (samples use <code>ORIENTATION_MODE_GRAVITY, true</code>).
; <code>SceneObject* Add(SceneObject* obj);</code>
: Queue a scene object for rendering on this screen this frame; returns the object for chaining.
; <code>SceneObject* AddCopy(SceneObject* obj);</code>
: 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).
; <code>uint8_t ID();</code>
: Physical display index — pass to native calls such as <code>MS_getFaceAccelX(screen.ID())</code>.
; <code>uint8_t Position();</code>
: The screen's place on its cube face (see the render sample above — used to compute cross-screen offsets).
; <code>uint8_t Face();</code> / <code>uint8_t OppositeFace();</code> / <code>TOPOLOGY_orientation_t Direction();</code>
: Topology of the screen: which face it belongs to, the opposite face, and the facing direction (UP/DOWN/FRONT/…).
; <code>void SetOrientation(TOPOLOGY_orientation_mode_t mode);</code> / <code>uint32_t Angle();</code> / <code>bool IsAutorotation();</code>
: 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 <code>assets/</code>).

 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: <code>new Sprite("idle.png", Transform(120,120,0))</code> — center of a 240×240 screen.

== Gfx::Background ==

Full-screen fill. <code>Background(uint32_t argb)</code> or <code>Background(R,G,B[,A])</code>; recolor at render time via <code>SetColor(...)</code> (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);

; <code>SetContent(std::string)</code> / <code>FormatContent(const char* fmt, ...)</code>
: Replace the text; <code>FormatContent</code> is printf-style — handy for scores/counters.
; <code>SetFontSize(uint32_t)</code>
: Change size. Alignment via the public <code>Alignment</code> field (<code>text_align_t</code>, 9 anchors).

== Gfx::AnimatedSprite ==

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

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

== Gfx::SpriteAtlas ==

A sprite sheet: one image asset cut into sub-rectangles, each rendered by a <code>SpriteAtlasElement</code> 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));

; <code>bool AddSprite(uint32_t id, const Math::Rect2& rc);</code>
: Create an element for sub-rectangle <code>rc</code> and register it in the scene under <code>id</code> (fails if the ID is taken).
; <code>T* Get(uint32_t)</code> / <code>T* operator[](uint32_t)</code> / <code>size_t Count()</code> / <code>ElementsInsertionOrder()</code>
: Element access. <code>SpriteAtlasElement</code> itself is a normal <code>SceneObject</code> (position/scale/color) plus <code>Rect()</code> and <code>Copy()</code>. An atlas can also feed an [[#Gfx::AnimatedSprite|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);

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

== Gfx::QRCode ==

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

== Sound and SoundCollection ==

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

== NetworkMessage and SaveMessage ==

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

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

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

== Scramble ==

Cube-scramble helper (SDK 6.0+), used by puzzle titles to generate and track a scrambled state (<code>Scramble.h</code>). Used across the official ''Topology'' samples.

== Splashscreen ==

Standard splash screen with leaderboard integration (<code>Splashscreen.h</code>; reworked in SDK 6.2). Shows the app title screen and player scores before the game starts.

== Math ==

; <code>Math::Vec2</code> / <code>Math::Vec2i</code>
: 2D float/int vectors with arithmetic.
; <code>Math::Transform</code>
: <code>{ Vec2 Position; int Rotation; unsigned ScaleX, ScaleY; unsigned Mirroring; }</code> — rotation in degrees (<code>SafeRotation()</code> normalizes), scale in percent (100 = 1:1). Constructors: <code>(x,y)</code>, <code>(x,y,angle)</code>, <code>(x,y,angle,sx,sy)</code>, <code>(x,y,angle,mirror)</code>, <code>(x,y,angle,sx,sy,mirror)</code>.
; <code>Math::Color</code>
: ARGB color; <code>Set(0xAARRGGBB)</code>, per-channel <code>SetA/R/G/B</code>, float alpha <code>SetAf</code>/<code>SetAfSafe</code>. Named constants in <code>Gfx/Colors.h</code> (<code>Colors::black</code>, <code>Colors::white</code>, …).
; <code>Math::Rect2</code>
: 2D rectangle — used for [[#Gfx::SpriteAtlas|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 [https://marketplace.visualstudio.com/items?itemName=cubios-inc.WOWCubeSDK WOWCube SDK extension for VS Code].

[[Category:SDK 6.3]]
[[Category:C++ API]]