Node:Raw interface, Next:, Previous:Script initialization, Up:Writing scripts

The basic (low-level) interface

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.

The object given to the scheme world

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 (1 3 3 3 3).

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


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.

Looking at the colours on the faces

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.

Moving the object on the 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.