Getting Started

Preface

Traditionally, prgrammer's journey with any new langauge or device or SDK starts with something simple, something like Hello, World application. The history of this dates back to 1978, and seriously, is there a programmer who hasn't got at least one Hello World application witten ever? Doubtful.

So your familiarization with WOWCube SDK starts with a Hello, World (kind of) application too.

But wait a minute.

Before moving to actual coding, let's stop for a second and think of what do we call a computer device ? Most of us would instantly think of a Mac, or PC, or gaming console, or even of mobile phone. We all deal with computer devices daily and we so used to it we almost take for granted that computer has a monitor, it has CPU and memory and storage. Let's try to be a bit more precise: it typically has one CPU, one block of memory and one to three monotors.

Thing is, WOWCube is different.

It is one device, but many. It consists of 8 independent modules each with own CPU and own memory. It has 24 screens that can change relative to each other positions. The modules can talk between each other via internal network.

But hang on you may say, how do I write applications for such challenging environment? This must be too difficult!

Apparently, it is not.

Creation of WOWCube applications is based on several principles and techniques known to any progammer rather well. The SDK provides quite intuitive API for controlling of nearly everything that device can do. So it would not to be that difficult to create your first game for WOWCube.

And to prove the point, let's get started...

Cubeapps and the structure of WOWCube application

First of all, it is important to understand that every WOWCube application constits of eight independent programs, or CUBEAPPS, that run on each device module.

A module is a building block of WOWCube device: it has 3 screens, its own CPU and its own memory. WOWCube devce has 8 modules.

A cubeapp is an application executed on module which implements application logic, rendering, network communication and haptic input

Thus, every WOWCube application is actually a union of eight cubeapps connected via internal network.

During the life of the applicaton, all cubeapps stay in constant interaction. In any random moment of time each cubeapp "knows" position of an own module relatively to the other modules. One module can easily send the data to the others. Finally, when one module receives a haptic command to close an application, all other modules will follow it instantly.

But аll this is provided by the functionality of the CubiOS operating system and done automatically.

The only thing every application must do is to listen to the signals operating system sends.

How?

Via callbacks...

CubiOS callbacks

A callback function is a function passed into a cubeapp application by CubiOS, which is then invoked inside the cubeapp application to complete some kind of routine or action.

A lifecycle of each cubeapp consists of three stages:

• application startup
• execution of application logic
• application shutdown

Of course, the second stage is always divided into multiple smaller stages, such as

• execution of logic
• rendering
• handling of user input
• handling of network communication

CubiOS utilizes callback functions to inform cubeapp application of which stage is running and what is happening.

The following callbacks are supported:

1void OnInit(Cubios::AppManager& appMgr) 
2    Gets called upon successfull load and start of cubeapp application. 
3 
4on_Tick(uint32_t currentTime, uint32_t deltaTime)
5    Gets called on every tick of cubeapp application internal runloop. In other words, it gets called continuously during the whole lifetime of an application. The frequency of calls depends on multiple factors, such as time of execution of the code within the callback, and not guaranteed to be stable. 
6 
7on_Render(std::array<Cubios::Screen, 3>& screens)
8    Application rendering code must be called inside this callback function. It gets called immediately after on_Tick(). Despite that any rendering calls can also be executed from on_Tick() callback, it is not a recommended practice. We advise to separate application logic and rendering into different callbacks. 
9 
10on_PhysicsTick(const std::array<Cubios::Screen, 3>& screens)
11    Gets called recurrently with not less than 30 milliseconds of delay between the calls. Can be used as a time callback for implementation of in-game physics or visual effects.
12 
13on_Twist(const Cubios::TOPOLOGY_twistInfo_t& twist)
14    Gets called when device topology - а mutual arrangement of modules relative to each other - is changed. 
15 
16on_Message(uint32_t type, uint8_t* pkt, u32_t size
17    Gets called when application receives data from the other module over device internal network.
18 
19on_Pat(uint32_t count)
20    Gets called when device registers a pat on one of its screens.
21 
22on_Timer(uint8_t timerID)
23    Gets called on every tick of a programmable timer.
24 

Simple sequence of callback calls of any cubeapp application looks like this:

1application started
2|
3OnInit(Cubios::AppManager& appMgr)   <--- initialization code
4|
5- Application::on_Tick()    <--- application logic
6- Application::on_Render()  <--- rendering
7  ...
8- Application::on_Tick()
9- Application::on_Render()
10  ...
11|
12shake the device
13|
14application closed
15 

Your first applicaton

Ok, enough of theory, let's get coding!

First of all, create a cubeapp project. We wanted Hello World, right? So let's do it!

In order to create a project, click the CREATE EXAMPLE PROJECT button below, then choose a folder where you would like the project to be created.

You can also navigate through WOWCube SDK examples library using <<PREV and NEXT>> buttons.

Once project is created, you will find the following items in your project's folder:

But before moving to the actual code, let's take a quick peek at what is inside the project file. The project file isn't something you would need to modify often, but to do certain things being familiar with its structure may come in handy.

The project file has the follwing structure:

1{
2"name": "HelloWOWCube",
3"version": "1.0.0",
4"sdkVersion": "6.3",
5"appIcon": {
6    "path": "assets/icon.png"
7},
8"sourceFile": "src/HelloWOWCube.cpp",
9"scriptFile": "binary/HelloWOWCube.wasm",
10"imageAssets": [],
11"soundAssets": [],
12"appFlags": 0,
13"language": "cpp",
14"interpreter": "wasm",
15"projectOptions": {
16    "cpp": {
17    "defines": "DUMMY_DEFINE=1;DUMMY_DEFINE2=2",
18    "flags": "-std=c++11 -Oz -flto -fno-exceptions -mexec-model=reactor -z stack-size=10240",
19    "compilerSettings": ",--initial-memory=65536,--export=run,--export=on_init,--strip-all,--lto-O3",
20    "includeFolders": [
21        "",
22        "",
23        "",
24        "",
25        ""
26    ]
27    }
28}
29}
30 

It is used to declare three major things: application's name, locations of files and versioning info.

1name:
2    A name of an application as it is shown in the WOWCube's main menu. In other words, it is a label under application's icon
3 
4version:
5    Application version
6 
7sdkVersion:
8    A version of WOWCube SDK used to build the application
9 
10sourceFile:
11    The name and the path to the source 
12 
13scriptFile:
14    The name and the path to the compiled intermediary file that then gets converted into a cubeapp file
15 
16appIcon:
17    The name and the path to the application icon file
18 
19 soundAssetsDir:
20 imageAssetsDir:
21    Paths to image and sound resource folders
22 
23projectOptions:
24    Programming language-specific options 
25 

So our example's name is MyApp, but you can change it by putting a different name and building the cubeapp.

Finally, the source code.

As you can see, the application's class has been generated and the callback functions have been declared:

1class HelloWOWCube: public Cubios::Application 
2{
3public:
4    HelloWOWCube();
5    virtual ~HelloWOWCube();
6 
7    virtual void on_PhysicsTick(const std::array<Cubios::Screen, 3>& screens) override;
8    virtual void on_Twist(const Cubios::TOPOLOGY_twistInfo_t& twist) override;
9    virtual void on_Message(uint32_t type, uint8_t* pkt, u32_t size) override;
10    virtual void on_Pat(uint32_t count) override;
11    virtual void on_Render(std::array<Cubios::Screen, 3>& screens) override;
12    virtual void on_Tick(uint32_t currentTime, uint32_t deltaTime) override;
13    virtual void on_Timer(uint8_t timerID) override;
14};
15 

Such class would be a bare minimum you need to have in order to build a cubeapp. This is our first cubeapp, and it is very simple: it only implements just one callback - on_Render().

But how does the cubeapp work exactly?

Let's look at the code of on_Render callback:

1void HelloWOWCube::on_Render(std::array<Cubios::Screen, 3>& screens)
2{
3    //iterate through screens
4    for(auto it = screens.begin(); it != screens.end(); ++it)
5    { 
6        //set screen render target
7        GFX_setRenderTarget(it->ID());
8 
9        //fill the screen with black color
10        GFX_clear(Colors::black);
11 
12        //render text
13        GFX_drawText(120,100, TEXT_SIZE, 0, text_align_t::TEXT_ALIGN_CENTER, Colors::white, "HELLO");
14        GFX_drawText(120,140, TEXT_SIZE, 0, text_align_t::TEXT_ALIGN_CENTER, Colors::white, "WOWCUBE");
15 
16        GFX_render(); 
17    }
18}
19 

The general principle of drawing on module's screen is simple:

First, you push commands to the graphics pipleine, then you commit them to be rendered on the screen

Since each module has three screens, you would want to iterate throught them every time you draw something. But this is not a must, you can actually draw on only one or two screens if you wish.

So, back to the on_Render code, we take three simple steps for each screen:

• We instruct the application what screen to use for rendering (GFX_setRenderTarget)
• We clear the screen with RGB color (GFX_clear)
• We draw text at screen coordinates (GFX_drawText) and
• We commit this to be drawn on particular screen (GFX_render)

Repeat those three steps for all three screens - and voila, Hello World.

No,

HELLO WOWCUBE