Handling Twists

Topology - Handling Twists

First of all, what is a twist ?

As per Oxford Dictionary, a twist is an act of rotating something around a stationary point.

So every time you play with your WOWCube and rotate its modules relatively to each other, you are actually twisting them around the common rotation center, i.e. a centre of the device.

What also happening when you twist your device is this: device topology gets changed.

The word topology means “The study of mappings”.

But what exactly do we call a topology ?

There are several different definitions of what topology really is. In mathematcis, topology is concerned with a shape of a geometric object and how various transformations affect it. In networking it is common to define topology as a way of arranging of multiple devices that are the elements of a communication network. And in ecology it is the study of patterns of interconnections in an eco-system, and specifically called ecological topology.

In WOWCube Development Kit topology is defined as

а mutual arrangement of device modules relative to each other

while in order to detect a change of topology,

1ON_Twist(twist[TOPOLOGY_TWIST_INFO])
2 

callback is used.

This callback is called every time you twist your WOWCube thus changing its topology. The twist parameter of TOPOLOGY_TWIST_INFO type is a structure that contains the following fields:

1#define TOPOLOGY_TWIST_INFO [ .screen, .count, .direction ]
2 
3Fields:
4 
5screen - an index of the screen around which a twist was performed
6count - a count of twists that have happened since the application started
7direction - a direction of a twist
8 

As a matter of fact, handling WOWCube twists is easy. Let's get to coding...

The example

To demonstrate how twists are handled, let's create a simple cubeapp that just detects a twist and shows its direction.

First of all, let's load some images in order to make our cubeapp a little prettier. This is done in the ON_Init() callback of course:

1public ON_Init(id, size, const pkt[])
2{
3    ...
4 
5    Icons.left = GFX_getAssetId("left.png");
6    Icons.right = GFX_getAssetId("right.png");
7    Icons.dbl = GFX_getAssetId("dbl.png");
8 
9    ...
10}
11 

Then let's define the ON_Twist callback as follows:

1public ON_Twist(twist[TOPOLOGY_TWIST_INFO]) 
2{    
3    Application.screen = twist.screen;
4    Application.direction = twist.direction;
5 
6    Application.animationOffset = 200;
7}
8 

This callback gets called every time the topology of WOWCube gets changed. So every time it happens we will register a screen index and a direction in which the screen has been twisted, i.e rotated.

And finally, we will use these values to play some neat animation.

1public ON_Render()
2{ 
3    for(new screenNumber = 0; screenNumber<3; screenNumber++)
4    {
5        GFX_setRenderTarget(screenNumber);
6        GFX_clear(Colors.black);
7 
8        if(screenNumber == Application.screen)
9        {
10            iconPos.x = 120+Application.animationOffset;
11            switch(Application.direction)
12            {
13                case TWIST_LEFT:  { iconPos.x = 120+Application.animationOffset; GFX_drawImage(iconPos, 0xFF, 0, 0, MIRROR_BLANK, Icons.left);  }
14                case TWIST_RIGHT:  { iconPos.x = 120-Application.animationOffset; GFX_drawImage(iconPos, 0xFF, 0, 0, MIRROR_BLANK, Icons.right); }
15                case TWIST_DOUBLE:  GFX_drawImage([120,120], 0xFF, 0, 0, MIRROR_BLANK, Icons.dbl);
16            }
17        }
18 
19        GFX_render();
20    }   
21}
22