PawnLibs/topology

Description

Topology provides a set of interfaces to detect how the modules are connected to each other and how a cube is oriented in the space.

Cube has 8 modules and 6 faces. Module is a piece of cube, which has 3 screens. Each cube face has 4 screens and a space orientation characteristic (up, front, left, etc). Thereby each screen in an entire cube system can be addressed in two ways: statically and dynamically (or in other words: physical and logical "coordinates").

TBD: figure of disassembled cube with labels should be embedded here

Facelet is a static address of the screen. It is a pair of the module ID and the screen number. Module ID determined during the cube startup and based on the module hardware ID and how big it is comparing with other modules in a system. Screen number corresponds to the order number of the display on a bus. Therefore facelet address represents physical "coordinates" of the particular screen and guarantee to be immutable for that particular hardware setup.

Place is a dynamic address of the screen. It is a pair of the face number and the screen position on that face. Faces are always have the same relationship one to each other. Basically their numbers always corresponds to the screen numbers of a master module (module with ID 0) and its diagonal counterpart. Positions on the face are always enumerated in the same order. Positions order based on the orientation mode, there are 3 of them:

• menu - default, position on the face enumerates counter clockwise from the master module or its diagonal counterpart
• splash - TBD: check
• gravity - position on side faces enumerates from a top left module, TBD: check

After each cube permutation places are recalculated for the entire system. One can think of a place as a logical "coordinates" on the cube surface.

Actually topology purpose is a function from the set of facelets to the set of places. Topology assigns each facelet to the exactly one place and vice versa. Several interfaces provided for convenient application development.

PawnLibs/topology/TOPOLOGY_FACES_MAX

Summary

How many faces the cube has.

Synopsis

1#define TOPOLOGY_FACES_MAX 6
2 

PawnLibs/topology/TOPOLOGY_POSITIONS_MAX

Summary

How many screens there are on a single cube face.

Synopsis

1#define TOPOLOGY_POSITIONS_MAX 4
2 

PawnLibs/topology/TOPOLOGY_FACELET

Summary

Array with named fields which represents a single facelet.

Synopsis

1#define TOPOLOGY_FACELET [ .module, .screen ]
2 

Description

Fields:

• module - an ID of the module on which facelet is located
• screen - a number of the module screen which corresponds to the facelet

See also

• TOPOLOGY_FACELET_INFO
• TOPOLOGY_getAdjacentFacelet()
• TOPOLOGY_getPlace()
• TOPOLOGY_getOppositeFacelet()
• TOPOLOGY_getAngle()
• TOPOLOGY_getFaceletOrientation()

PawnLibs/topology/TOPOLOGY_FACELET_INFO

Summary

Array with named fields with meta information about a single facelet.

Synopsis

1#define TOPOLOGY_FACELET_INFO [ TOPOLOGY_FACELET, .connected ]
2 

Description

Fields:

• module - an ID of the module on which the facelet is located
• screen - a number of the module screen which corresponds to the facelet
• connected - connection status, depends on the context

See also

• TOPOLOGY_FACELET
• TOPOLOGY_getFacelet()
• TOPOLOGY_getAdjacentFacelet()
• TOPOLOGY_getOppositeFacelet()

PawnLibs/topology/TOPOLOGY_PLACE

Summary

Array with named fields which represents screens place on the cube surface.

Synopsis

1#define TOPOLOGY_PLACE [ .face, .position ]
2 

Description

Fields:

• face - a face number on which screen is located
• position - a position on the face on which screen is located

See also

• TOPOLOGY_getFacelet()
• TOPOLOGY_getPlace()
• TOPOLOGY_getPlaceOrientation()

PawnLibs/topology/TOPOLOGY_TWIST_INFO

Summary

Array with named fields with twist parameters.

Synopsis

1#define TOPOLOGY_TWIST_INFO [ .screen, .count, TOPOLOGY_twist: .direction ]
2 

Description

Fields:

• screen - a number of the screen around which a twist was detected
• count - how many twists happened from the application start
• direction - a twist direction

See also

• TOPOLOGY_twist
• ON_Twist()

PawnLibs/topology/TOPOLOGY_neighbor

Summary

Enumeration of a facelet neighbor directions.

Synopsis

1const TOPOLOGY_neighbor: {
2  NEIGHBOR_SELF = 0,
3  NEIGHBOR_LEFT,
4  NEIGHBOR_DIAGONAL,
5  NEIGHBOR_TOP,
6  NEIGHBOR_RIGHT,
7  NEIGHBOR_BOTTOM,
8  NEIGHBOR_MAX,
9};
10 

PawnLibs/topology/TOPOLOGY_orientation

Summary

Enumeration of a face orientations.

Synopsis

1const TOPOLOGY_orientation: {
2  ORIENTATION_UP = 0,
3  ORIENTATION_DOWN,
4  ORIENTATION_FRONT,
5  ORIENTATION_BACK,
6  ORIENTATION_LEFT,
7  ORIENTATION_RIGHT,
8  ORIENTATION_MAX,
9};
10 

PawnLibs/topology/TOPOLOGY_orientation_mode

Summary

Enumeration of an orientation modes.

Synopsis

1const TOPOLOGY_orientation_mode: {
2  ORIENTATION_MODE_MENU = 0,
3  ORIENTATION_MODE_GRAVITY,
4  ORIENTATION_MODE_SPLASH,
5  ORIENTATION_MODE_MAX,
6};
7 

PawnLibs/topology/TOPOLOGY_reverseFaces

Summary

Array with opposite cube faces.

Synopsis

1stock const TOPOLOGY_reverseFaces { TOPOLOGY_FACES_MAX } = { 3, 5, 4, 0, 2, 1 };
2 

Description

Value at a face position corresponds its opposite face, e.g. face opposite to 0 is 3 and vice versa.

PawnLibs/topology/TOPOLOGY_twist

Summary

Enumeration of twist directions.

Synopsis

1const TOPOLOGY_twist: {
2  TWIST_UNINDENTIFIED = 0,
3  TWIST_LEFT,
4  TWIST_RIGHT,
5  TWIST_DOUBLE,
6  TWIST_MAX,
7};
8 

PawnLibs/topology/ON_Twist

Summary

Twist handler.

Synopsis

1forward ON_Twist(twist[TOPOLOGY_TWIST_INFO]);
2 

Description

Public function with such signature will be called when a cube twist detected.

Inputs

• twist - a twist description

See also

• TOPOLOGY_TWIST_INFO

PawnLibs/topology/TOPOLOGY_getAdjacentFacelet

Summary

Get a facelet neighbor in the given direction.

Synopsis

1native TOPOLOGY_getAdjacentFacelet[TOPOLOGY_FACELET_INFO](facelet[TOPOLOGY_FACELET], TOPOLOGY_neighbor: direction = NEIGHBOR_DIAGONAL);
2 

Description

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.

Inputs

• facelet - a facelet which neighbor is requested
• direction - a direction in which neighbor is requested

Return value

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

See also

• TOPOLOGY_FACELET
• TOPOLOGY_FACELET_INFO
• MODULES_MAX
• SCREENS_MAX
• TOPOLOGY_neighbor

PawnLibs/topology/TOPOLOGY_getAngle

Summary

Get an angle to align images on a face according to the orientation mode.

Synopsis

1native TOPOLOGY_getAngle(facelet[TOPOLOGY_FACELET], TOPOLOGY_orientation_mode: mode = ORIENTATION_MODE_MENU);
2 

Description

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.

Inputs

• facelet - a facelet for which screen an angle is requested
• mode - an orientation mode in which an angle is requested

Return value

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

See also

• TOPOLOGY_FACELET
• TOPOLOGY_orientation_mode
• PawnLibs/GFX module

PawnLibs/topology/TOPOLOGY_getFace

Summary

Get a face number which has the given orientation.

Synopsis

1native TOPOLOGY_getFace(TOPOLOGY_orientation: orientation = ORIENTATION_UP);
2 

Inputs

• orientation - a orientation of the requested face

Return value

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

See also

• TOPOLOGY_orientation
• TOPOLOGY_FACES_MAX

PawnLibs/topology/TOPOLOGY_getFacelet

Summary

Get a facelet located in the given place.

Synopsis

1native TOPOLOGY_getFacelet[TOPOLOGY_FACELET_INFO](place[TOPOLOGY_PLACE], TOPOLOGY_orientation_mode: mode = ORIENTATION_MODE_MENU);
2 

Inputs

• place - a place on a cube's face for which the facelet is requested
• mode - the place position orientation mode

Return value

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

See also

• TOPOLOGY_FACELET
• TOPOLOGY_FACELET_INFO
• TOPOLOGY_PLACE
• MODULES_MAX
• SCREENS_MAX
• TOPOLOGY_orientation_mode

PawnLibs/topology/TOPOLOGY_getFaceletOrientation

Summary

Get a face orientation on which the given facelet resides.

Synopsis

1native TOPOLOGY_orientation: TOPOLOGY_getFaceletOrientation(facelet[TOPOLOGY_FACELET]);
2 

Inputs

• facelet - a facelet for which the face orientation is requested

Return value

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

See also

• TOPOLOGY_FACELET
• TOPOLOGY_orientation

PawnLibs/topology/TOPOLOGY_getOppositeFacelet

Summary

Get an opposite facelet located on a diagonal counterpart module.

Synopsis

1native TOPOLOGY_getOppositeFacelet[TOPOLOGY_FACELET_INFO](facelet[TOPOLOGY_FACELET]);
2 

Inputs

• facelet - a facelet for which opposite diagonal counterpart is requested

Return value

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

See also

• TOPOLOGY_FACELET_INFO
• TOPOLOGY_FACELET
• MODULES_MAX
• SCREENS_MAX

PawnLibs/topology/TOPOLOGY_getPlace

Summary

Get a place of the facelet.

Synopsis

1native TOPOLOGY_getPlace[TOPOLOGY_PLACE](facelet[TOPOLOGY_FACELET], TOPOLOGY_orientation_mode: mode = ORIENTATION_MODE_MENU);
2 

Inputs

• facelet - facelet which place on cube surface is requested
• mode - place position orientation mode

Return value

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)

See also

• TOPOLOGY_FACELET
• TOPOLOGY_PLACE
• TOPOLOGY_FACES_MAX
• TOPOLOGY_POSITIONS_MAX
• TOPOLOGY_orientation_mode

PawnLibs/topology/TOPOLOGY_getPlaceOrientation

Summary

Get a face orientation on which the given place resides.

Synopsis

1native TOPOLOGY_orientation: TOPOLOGY_getPlaceOrientation(place[TOPOLOGY_PLACE]);
2 

Inputs

• place - a place for which the face orientation is requested

Return value

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

See also

• TOPOLOGY_PLACE
• TOPOLOGY_orientation

PawnLibs/topology/TOPOLOGY_isAssembled

Summary

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

Synopsis

1native bool: TOPOLOGY_isAssembled();
2 

Return value

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