Node:Raw interface, Next:Symbolic interface, Previous:Script initialization, Up:Writing scripts
This chapter describes the basic interface that GNUbik provides to the
scheme world. This interface can be used with any cube geometry
that GNUbik supports, but is not intuitive for humans and the API may
change in the future.
If the API does change (to make it more consistent!) the version number of cube geometry in a cube object will also change, so any script which uses these functions directly should obtain a cube object from GNUbik and check the geometry version number.
In order to obtain a reflection of the current state of the cube, a script must call
| gnubik-cube-state | Procedure |
This will return a scheme object, which is in fact a cons cell
whose first component is a list describing the geometry of the cube,
and the second component is a vector of six vectors of nxn items,
where n is the size of the cube.
The geometry list consists of a version number, which will change if
the definition of the cube object ever changes (scripts should check
this to ensure compatibility or else things will surely break); the
current version is 1 (one). The next item in the list is the
dimensionality of the cube, which currently is always 3. The list then
holds three more numbers describing the size of the cube in each
direction. So a current 3x3x3 cube will have the geometry list
The second component of the cube cons cell is a vector of six vectors, one for each face. If you were to look at a cube with face index 4 towards you (remember vector indeces are zero based), then the top face would have index 0 (zero), the bottom 1 (one), the left 2, the right 3, and the back 5. Got it? Stay there. On faces 0 (zero), 3, and 4, the panels are numbered from left to right and top to bottom, so that panel 0 (zero) is at top-left and panel 5 is middle-right, for example. On the other faces, the panels are in the corresponding positions underneath their opposite faces, which means in practice that the numbering is from right to left, top to bottom. For example, the second panel (index 1) on face 2 is at the top. Finally, the 'top' edge of the top panel is against face 2. The elements of the vectors for each page represent the colour that the panels of that face are showing, numbered from 0 (zero) to 5 inclusive (the correspondence between these numbers and the actual colours seen on the cube on the screen is not provided by GNUbik to the scripts). |
Whew.
If that was too sticky and you are using a 3x3x3 cube, then you should proceed to the next chapter which presents a more comfortable (and stable) interface.
Once you have a cube object, the following procedures are available to facilitate access to it.
| get-colour cube face index | Procedure |
| This procedure gets the colour of the cube at panel index on face, where the meaning of the latter two arguments is described above. |
| set-colour! cube face index colour | Procedure |
This procedure sets the colour of the given face to colour. Note
that the change takes place only in the scheme cube
object, not in the actual cube that the user is seeing on her screen.
|
When a script has determined a set of moves which are to be made on a cube, it calls the following procedure to get GNUbik to put the moves into its internal move buffer.
| gnubik-rotate-animated move-list | Procedure |
The move-list is a list of lists of three items. For any one
move (a quarter turn of a slice of the cube), the first item in the
specification is the face which lies parallel to the desired slice,
and may be 0 (zero), 1 (one) or two corresponding to the back, right
and bottom faces. The second item in the specification is the slice
number parallel to that plane; the slice next to the specified face
has number (n-1) where n is the size of the cube, and
the slices below are separated by (-2). For example, for a cube with
three blocks per edge (a 3x3x3 cube, say), the slices are numbered 2,
0 and -2. The final component in a move specification may be 0 (zero)
or 1 (one) depending on whether the slice should be moved
anticlockwise or clockwise, respectively.
|
Note that the above function may be called as many times as desired during the execution of a script, but that the moves will not actually take place until the script finishes.
| gnubik-rotate-fast move-list | Procedure |
| This performs the same function as above, except that the moves take place instantly as soon as the script finishes, instead of being animated on the screen. |