1/****h* PawnLibs/topology
2 * Description
3 *   Topology provides a set of interfaces to detect how the modules are
4 *   connected to each other and how a cube is oriented in the space.
5 *
6 *   Cube has 8 modules and 6 faces. Module is a piece of cube, which has 3
7 *   screens. Each cube face has 4 screens and a space orientation
8 *   characteristic (up, front, left, etc). Thereby each screen in an entire
9 *   cube system can be addressed in two ways: statically and dynamically (or in
10 *   other words: physical and logical "coordinates").
11 *
12 *   TBD: figure of disassembled cube with labels should be embedded here
13 *
14 *   Facelet is a static address of the screen. It is a pair of the module ID
15 *   and the screen number. Module ID determined during the cube startup and
16 *   based on the module hardware ID and how big it is comparing with other
17 *   modules in a system. Screen number corresponds to the order number of the
18 *   display on a bus. Therefore facelet address represents physical
19 *   "coordinates" of the particular screen and guarantee to be immutable for
20 *   that particular hardware setup.
21 *
22 *   Place is a dynamic address of the screen. It is a pair of the face number
23 *   and the screen position on that face. Faces are always have the same
24 *   relationship one to each other. Basically their numbers always corresponds
25 *   to the screen numbers of a master module (module with ID 0) and its
26 *   diagonal counterpart. Positions on the face are always enumerated in the
27 *   same order. Positions order based on the orientation mode, there are 3 of
28 *   them:
29 *   * menu - default, position on the face enumerates counter clockwise from
30 *     the master module or its diagonal counterpart
31 *   * splash - TBD: check
32 *   * gravity - position on side faces enumerates from a top left module, TBD:
33 *     check
34 *   After each cube permutation places are recalculated for the entire system.
35 *   One can think of a place as a logical "coordinates" on the cube surface.
36 *
37 *   Actually topology purpose is a function from the set of facelets to the set
38 *   of places. Topology assigns each facelet to the exactly one place and vice
39 *   versa. Several interfaces provided for convenient application development.
40 ******/
41 
42/****d* PawnLibs/topology/TOPOLOGY_FACES_MAX
43 * Summary
44 *   How many faces the cube has.
45 * Synopsis
46 */
47#define TOPOLOGY_FACES_MAX 6
48/******/
49 
50/****d* PawnLibs/topology/TOPOLOGY_POSITIONS_MAX
51 * Summary
52 *   How many screens there are on a single cube face.
53 * Synopsis
54 */
55#define TOPOLOGY_POSITIONS_MAX 4
56/******/
57 
58/****s* PawnLibs/topology/TOPOLOGY_FACELET
59 * Summary
60 *   Array with named fields which represents a single facelet.
61 * Synopsis
62 */
63#define TOPOLOGY_FACELET [ .module, .screen ]
64/*
65 * Description
66 *   Fields:
67 *   * module - an ID of the module on which facelet is located
68 *   * screen - a number of the module screen which corresponds to the facelet
69 * See also
70 *   * TOPOLOGY_FACELET_INFO
71 *   * TOPOLOGY_getAdjacentFacelet()
72 *   * TOPOLOGY_getPlace()
73 *   * TOPOLOGY_getOppositeFacelet()
74 *   * TOPOLOGY_getAngle()
75 *   * TOPOLOGY_getFaceletOrientation()
76 ******/
77 
78/****s* PawnLibs/topology/TOPOLOGY_FACELET_INFO
79 * Summary
80 *   Array with named fields with meta information about a single facelet.
81 * Synopsis
82 */
83#define TOPOLOGY_FACELET_INFO [ TOPOLOGY_FACELET, .connected ]
84/*
85 * Description
86 *   Fields:
87 *   * module - an ID of the module on which the facelet is located
88 *   * screen - a number of the module screen which corresponds to the facelet
89 *   * connected - connection status, depends on the context
90 * See also
91 *   * TOPOLOGY_FACELET
92 *   * TOPOLOGY_getFacelet()
93 *   * TOPOLOGY_getAdjacentFacelet()
94 *   * TOPOLOGY_getOppositeFacelet()
95 ******/
96 
97/****s* PawnLibs/topology/TOPOLOGY_PLACE
98 * Summary
99 *   Array with named fields which represents screens place on the cube surface.
100 * Synopsis
101 */
102#define TOPOLOGY_PLACE [ .face, .position ]
103/*
104 * Description
105 *   Fields:
106 *   * face - a face number on which screen is located
107 *   * position - a position on the face on which screen is located
108 * See also
109 *   * TOPOLOGY_getFacelet()
110 *   * TOPOLOGY_getPlace()
111 *   * TOPOLOGY_getPlaceOrientation()
112 ******/
113 
114/****s* PawnLibs/topology/TOPOLOGY_TWIST_INFO
115 * Summary
116 *   Array with named fields with twist parameters.
117 * Synopsis
118 */
119#define TOPOLOGY_TWIST_INFO [ .screen, .count, TOPOLOGY_twist: .direction ]
120/*
121 * Description
122 *   Fields:
123 *   * screen - a number of the screen around which a twist was detected
124 *   * count - how many twists happened from the application start
125 *   * direction - a twist direction
126 * See also
127 *   * TOPOLOGY_twist
128 *   * ON_Twist()
129 ******/
130 
131/****c* PawnLibs/topology/TOPOLOGY_neighbor
132 * Summary
133 *   Enumeration of a facelet neighbor directions.
134 * Synopsis
135 */
136const TOPOLOGY_neighbor: {
137  NEIGHBOR_SELF = 0,
138  NEIGHBOR_LEFT,
139  NEIGHBOR_DIAGONAL,
140  NEIGHBOR_TOP,
141  NEIGHBOR_RIGHT,
142  NEIGHBOR_BOTTOM,
143  NEIGHBOR_MAX,
144};
145/******/
146 
147/****c* PawnLibs/topology/TOPOLOGY_orientation
148 * Summary
149 *   Enumeration of a face orientations.
150 * Synopsis
151 */
152const TOPOLOGY_orientation: {
153  ORIENTATION_UP = 0,
154  ORIENTATION_DOWN,
155  ORIENTATION_FRONT,
156  ORIENTATION_BACK,
157  ORIENTATION_LEFT,
158  ORIENTATION_RIGHT,
159  ORIENTATION_MAX,
160};
161/*
162 * History
163 *   * v5.0 - renamed from TOPOLOGY_location to the TOPOLOGY_orientation
164 ******/
165 
166/****c* PawnLibs/topology/TOPOLOGY_orientation_mode
167 * Summary
168 *   Enumeration of an orientation modes.
169 * Synopsis
170 */
171const TOPOLOGY_orientation_mode: {
172  ORIENTATION_MODE_MENU = 0,
173  ORIENTATION_MODE_GRAVITY,
174  ORIENTATION_MODE_SPLASH,
175  ORIENTATION_MODE_MAX,
176};
177/*
178 * History
179 *   * v5.0 - renamed from TOPOLOGY_orientation to TOPOLOGY_orientation_mode
180 ******/
181 
182/****c* PawnLibs/topology/TOPOLOGY_twist
183 * Summary
184 *   Enumeration of twist directions.
185 * Synopsis
186 */
187const TOPOLOGY_twist: {
188  TWIST_UNINDENTIFIED = 0,
189  TWIST_LEFT,
190  TWIST_RIGHT,
191  TWIST_DOUBLE,
192  TWIST_MAX,
193};
194/******/
195 
196/****c* PawnLibs/topology/TOPOLOGY_reverseFaces
197 * Summary
198 *   Array with opposite cube faces.
199 * Synopsis
200 */
201stock const TOPOLOGY_reverseFaces { TOPOLOGY_FACES_MAX } = { 3, 5, 4, 0, 2, 1 };
202/*
203 * Description
204 *   Value at a face position corresponds its opposite face, e.g. face opposite
205 *   to 0 is 3 and vice versa.
206 ******/
207 
208/****e* PawnLibs/topology/ON_Twist
209 * Summary
210 *   Twist handler.
211 * Synopsis
212 */
213forward ON_Twist(twist[TOPOLOGY_TWIST_INFO]);
214/*
215 * Description
216 *   Public function with such signature will be called when a cube twist
217 *   detected.
218 * Inputs
219 *   * twist - a twist description
220 * See also
221 *   * TOPOLOGY_TWIST_INFO
222 ******/
223 
224/****n* PawnLibs/topology/TOPOLOGY_getAdjacentFacelet
225 * Summary
226 *   Get a facelet neighbor in the given direction.
227 * Synopsis
228 */
229native TOPOLOGY_getAdjacentFacelet[TOPOLOGY_FACELET_INFO](facelet[TOPOLOGY_FACELET], TOPOLOGY_neighbor: direction = NEIGHBOR_DIAGONAL);
230/*
231 * Description
232 *   Facelet can have neighbors on the same cube face or neighbors by module.
233 *   This function provide a neighbor of the given facelet in the given
234 *   direction. Connection status indicates if there is a connection between
235 *   modules on which given facelet and its neighbor are located.
236 * Inputs
237 *   * facelet - a facelet which neighbor is requested
238 *   * direction - a direction in which neighbor is requested
239 * Return value
240 *   Neighbor facelet in a given direction with its connection status. The
241 *   module ID will be MODULES_MAX and the screen number will be SCREENS_MAX in
242 *   case of an error (e.g. incorrect arguments or the topology malfunction).
243 * See also
244 *   * TOPOLOGY_FACELET
245 *   * TOPOLOGY_FACELET_INFO
246 *   * MODULES_MAX
247 *   * SCREENS_MAX
248 *   * TOPOLOGY_neighbor
249 ******/
250 
251/****n* PawnLibs/topology/TOPOLOGY_getFacelet
252 * Summary
253 *   Get a facelet located in the given place.
254 * Synopsis
255 */
256native TOPOLOGY_getFacelet[TOPOLOGY_FACELET_INFO](place[TOPOLOGY_PLACE], TOPOLOGY_orientation_mode: mode = ORIENTATION_MODE_MENU);
257/*
258 * Inputs
259 *   * place - a place on a cube surface which corresponding facelet is
260 *     requested
261 *   * mode - the place position orientation mode
262 * Return value
263 *   Facelet located in the given place, connection status indicates if there
264 *   any connection to the module on which this facelet resides. The module ID
265 *   will be MODULES_MAX and the screen screen will be SCREENS_MAX in case of an
266 *   error (e.g. incorrect arguments or the topology malfunction).
267 * See also
268 *   * TOPOLOGY_FACELET
269 *   * TOPOLOGY_FACELET_INFO
270 *   * TOPOLOGY_PLACE
271 *   * MODULES_MAX
272 *   * SCREENS_MAX
273 *   * TOPOLOGY_orientation_mode
274 ******/
275 
276/****n* PawnLibs/topology/TOPOLOGY_getPlace
277 * Summary
278 *   Get a place of the facelet.
279 * Synopsis
280 */
281native TOPOLOGY_getPlace[TOPOLOGY_PLACE](facelet[TOPOLOGY_FACELET], TOPOLOGY_orientation_mode: mode = ORIENTATION_MODE_MENU);
282/*
283 * Inputs
284 *   * facelet - facelet which place on cube surface is requested
285 *   * mode - place position orientation mode
286 * Return value
287 *   Place on cube surface where the given facelet located. Face will be
288 *   TOPOLOGY_FACES_MAX and position will be TOPOLOGY_POSITIONS_MAX in case of
289 *   an error (e.g. incorrect arguments or topology malfunction)
290 * See also
291 *   * TOPOLOGY_FACELET
292 *   * TOPOLOGY_PLACE
293 *   * TOPOLOGY_FACES_MAX
294 *   * TOPOLOGY_POSITIONS_MAX
295 *   * TOPOLOGY_orientation_mode
296 ******/
297 
298/****n* PawnLibs/topology/TOPOLOGY_getOppositeFacelet
299 * Summary
300 *   Get an opposite facelet located on a diagonal counterpart module.
301 * Synopsis
302 */
303native TOPOLOGY_getOppositeFacelet[TOPOLOGY_FACELET_INFO](facelet[TOPOLOGY_FACELET]);
304/*
305 * Inputs
306 *   * facelet - a facelet for which opposite diagonal counterpart is requested
307 * Return value
308 *   Diagonal opposite counterpart facelet. Connection status indicates if there
309 *   any connection to the module on which that facelet resides. The module ID
310 *   will be MODULES_MAX and the screen number will be SCREENS_MAX in case of an
311 *   error (e.g. incorrect arguments or topology malfunction).
312 * See also
313 *   * TOPOLOGY_FACELET_INFO
314 *   * TOPOLOGY_FACELET
315 *   * MODULES_MAX
316 *   * SCREENS_MAX
317 ******/
318 
319/****n* PawnLibs/topology/TOPOLOGY_getAngle
320 * Summary
321 *   Get an angle to align images on a face according to the orientation mode.
322 * Synopsis
323 */
324native TOPOLOGY_getAngle(facelet[TOPOLOGY_FACELET], TOPOLOGY_orientation_mode: mode = ORIENTATION_MODE_MENU);
325/*
326 * Description
327 *   Display coordinates system is persistent on a module screen. Different
328 *   angles are needed to align images on all modules with screens on the same
329 *   face. This function returns the angle for the screen specified by the
330 *   facelet. The angle is relative to the position 0 on the same face where the
331 *   facelet is located in the given orientation mode.
332 * Inputs
333 *   * facelet - a facelet for which screen an angle is requested
334 *   * mode - an orientation mode in which an angle is requested
335 * Return value
336 *   Angle to align images on the same face according to the orientation mode, 0
337 *   in case of an error (e.g. incorrect arguments or the topology malfunction).
338 * See also
339 *   * TOPOLOGY_FACELET
340 *   * TOPOLOGY_orientation_mode
341 *   * PawnLibs/GFX module
342 ******/
343 
344/****n* PawnLibs/topology/TOPOLOGY_getFaceletOrientation
345 * Summary
346 *   Get a face orientation on which the given facelet resides.
347 * Synopsis
348 */
349native TOPOLOGY_orientation: TOPOLOGY_getFaceletOrientation(facelet[TOPOLOGY_FACELET]);
350/*
351 * Inputs
352 *   * facelet - a facelet for which the face orientation is requested
353 * Return value
354 *   Face orientation on which the given facelet resides, ORIENTATION_MAX in
355 *   case of an error (e.g. incorrect arguments or the topology malfunction).
356 * See also
357 *   * TOPOLOGY_FACELET
358 *   * TOPOLOGY_orientation
359 * History
360 *   * v5.0 - renamed from TOPOLOGY_getFaceletLocation() to the
361 *   TOPOLOGY_getFaceletOrientation()
362 ******/
363 
364/****n* PawnLibs/topology/TOPOLOGY_getPlaceOrientation
365 * Summary
366 *   Get a face orientation on which the given place resides.
367 * Synopsis
368 */
369native TOPOLOGY_orientation: TOPOLOGY_getPlaceOrientation(place[TOPOLOGY_PLACE]);
370/*
371 * Inputs
372 *   * place - a place for which the face orientation is requested
373 * Return value
374 *   Face orientation on which the given place resides, ORIENTATION_MAX in case
375 *   of an error (e.g. incorrect arguments or the topology malfunction).
376 * See also
377 *   * TOPOLOGY_PLACE
378 *   * TOPOLOGY_orientation
379 * History
380 *   * v5.0 - renamed from TOPOLOGY_getPlaceLocation() to the
381 *   TOPOLOGY_getPlaceOrientation()
382 ******/
383 
384/****n* PawnLibs/topology/TOPOLOGY_getFace
385 * Summary
386 *   Get a face number which has the given orientation.
387 * Synopsis
388 */
389native TOPOLOGY_getFace(TOPOLOGY_orientation: orientation = ORIENTATION_UP);
390/*
391 * Inputs
392 *   * orientation - a orientation of the requested face
393 * Return value
394 *   Face number which has the given orientation, TOPOLOGY_FACES_MAX in case of
395 *   an error (e.g. incorrect arguments or the topology malfunction).
396 * See also
397 *   * TOPOLOGY_orientation
398 *   * TOPOLOGY_FACES_MAX
399 ******/
400 
401/****n* PawnLibs/topology/TOPOLOGY_isAssembled
402 * Summary
403 *   Check that all modules in a system are connected to each other.
404 * Synopsis
405 */
406native bool: TOPOLOGY_isAssembled();
407/*
408 * Return value
409 *   True if all modules in a system are connected to each other, false
410 *   otherwise.
411 ******/
412