Gauche-gl : OpenGL binding for Gauche

This is a reference manual of Gauche-gl, an OpenGL binding for the Gauche Scheme implementation. This manual is for version 0.3.1.

1. Introduction

Gauche-gl is an extension module of Gauche Scheme implementation. It provides the following modules:

gl

The module that provides bindings to OpenGL API. It covers almost all functions in OpenGL 1.2, and most functions in GLU. The functions are described in 4. OpenGL API and 5. GLU API.

gl.glut

The module that provides bindings to most functions in GLUT. The functions are described in 6. GLUT API.

gl.math3d

The module that provides vector and matrix calculations optimized for 3D homogeneous coordinates. The vector and matrix objects here can be directly passed to Gauche-gl functions. The functions are descrbied in 7. Vectors and matrices.

2. Installation

Installing Gauche-gl is usually straightforward on Unix variants. At the time of writing this Manual, Gauche-gl can't be complied on Cygwin.

You have to have the following programs installed on your machine.

• Gauche 0.6.7 or later
• OpenGL 1.1 equivalent library; the auther checked with Mesa 3.4 and NVidia's GLX driver.
• GLUT 3.7 or later.

The standard way to compile and install Gauche-gl is as follows:

% gzcat Gauche-gl-0.3.1.tgz | tar xf -
% cd Gauche-gl-0.3.1
% ./configure
% make
% make test
% make install

The confiugre script figures out the location Gauche is installed, and install Gauche-gl in the same place.

If you have GLUT installed in non-standard place, you have to tell the configure script where it is.

% ./configure --with-glut=DIR

It is reported that Mesa in FreeBSD ports is compiled with pthreads enabled, and Gauche-gl can't be linked unless Gauche itself is compiled with pthreads. The configure script of Gauche prints warning if you specify pthreads, but it is safe as far as you don't call make-thread in your program.

3. Getting Started

3.1 GL calls in Scheme

I assume you have basic knowledge of OpenGL API. Gauche-gl maps OpenGL calls to Scheme procedures pretty straightforwardly. For example, the very first example of "OpenGL Programming Guide", the pseudo code of OpenGL application, can be written in Gauche-gl like this:

(use gl)

(define (main args)
  (initialize-a-window-please)

  (gl-clear-color 0.0 0.0 0.0 0.0)
  (gl-clear GL_COLOR_BUFFER_BIT)
  (gl-color 1.0 1.0 1.0)
  (gl-ortho 0.0 1.0 0.0 1.0 -1.0 1.0)
  (gl-begin* GL_POLYGON
    (gl-vertex 0.25 0.25 0.0)
    (gl-vertex 0.75 0.25 0.0)
    (gl-vertex 0.75 0.75 0.0)
    (gl-vertex 0.25 0.75 0.0)
    )
  (gl-flush)
  (update-the-window-and-check-for-events)
  0)

Note that initialize-a-window-please and update-the-window-and-check-for-events are function calls dependent on the windowing system. Gauche-gl comes with GLUT binding and you can use it to do basic stuff. In the separate package Gauche-gtk, a binding to GtkGLExt is provided, which allows you to do GL rendering inside Gtk widgets.

For the time being, let's focus on the pure GL part.

The mapping of GL call name is straightforward. The mixed case names in OpenGL C API is expanded to hyphenated name, e.g. glClearColor => gl-clear-color. OpenGL enums are mapped as is, e.g. GL_POLYGON. (Note that Gauche is case-sensitive by default. Also note the underscore, not hyphen, in constants).

A few convenience macros, such as gl-begin*, is defined. There are straight bindings of gl-begin and gl-end, so you can write the drawing part in the same way as in C:

  (gl-begin GL_POLYGON)
    (gl-vertex 0.25 0.25 0.0)
    (gl-vertex 0.75 0.25 0.0)
    (gl-vertex 0.75 0.75 0.0)
    (gl-vertex 0.25 0.75 0.0)
  (gl-end)

Actually gl-begin* macro expands into the above calls. It's a matter of taste, but the macro version guarantees begin and end match, and the syntax-aware editor can indent internal calls accordingly.

You might have noticed that the type suffix in C API is not in Gauche binding. The Scheme function figures out the type of passed arguments and calls appropriate C API. SRFI-4 uniform numeric vectors are used to represent arrays of numbers.

  (gl-vertex 1.0 2.0 3.0)    => glVertex3d
  (gl-vertex '#f32(1.0 2.0)) => glVertex2fv
  (gl-vertex '#s32(3 2 5))   => glVertex3iv

Generally, passing uniform vectors is much more efficient than giving individual numbers, for the former can eliminate the cost of type checking and unboxing.

Some GL calls can also take gl.math3d primitive objects such as vector4f, point4f or matrix4f (See section 7. Vectors and matrices). For example, you can pass point4f object to gl-vertex, vector4f to gl-normal, and matrix4f to gl-mult-matrix. They are efficient since calculations on those types are defined natively in gl.math3d, and passing it to GL call doesn't cost unboxing.

Variables GL_VERSION_1_1, GL_VERSION_1_2 and GL_VERSION_1_3 may be defined and bound to #t if the platform on which Gauche-gl is compiled supports OpenGL version 1.1, 1.2 or 1.3, respectively. You can use symbol-bound? to check these variables are bound. You can also use symbol-bound? to check the existence of extensions, such as GL_ARB_multitexture.

3.2 Using GLUT

In order to make a runnable script, you need to use some windowing system interface. GLUT binding provides a simple way for it.

Here is a complete runnable Scheme script, ported from Example 1-2 in "OpenGL Programming Guide":

(use gl)
(use gl.glut)

(define (disp)
  (gl-clear GL_COLOR_BUFFER_BIT)
  (gl-color '#f32(1.0 1.0 1.0))
  (gl-begin* GL_POLYGON
    (gl-vertex '#f32(0.25 0.25 0.0))
    (gl-vertex '#f32(0.75 0.25 0.0))
    (gl-vertex '#f32(0.75 0.75 0.0))
    (gl-vertex '#f32(0.25 0.75 0.0))
    )
  (gl-flush)
  )

(define (init)
  (gl-clear-color 0.0 0.0 0.0 0.0)
  (gl-matrix-mode GL_PROJECTION)
  (gl-load-identity)
  (gl-ortho 0.0 1.0 0.0 1.0 -1.0 1.0)
  )

(define (keyboard key x y)
  (cond
   ((= key 27) (exit 0))
   ))

(define (main args)
  (glut-init args)
  (glut-init-display-mode (logior GLUT_SINGLE GLUT_RGB))
  (glut-init-window-size 250 250)
  (glut-init-window-position 100 100)
  (glut-create-window "hello")
  (init)
  (glut-display-func disp)
  (glut-keyboard-func keyboard)
  (glut-main-loop)
  0)

The (use gl.glut) form loads GLUT binding. The name mapping is the same as GL's: mixed case names to hyphenated names.

In order to handle various events, you can pass a closure to glut-display-func etc. In the keyboard and mouse event callback, all arguments are integers.

There are more examples under the `examples/' directory which uses GLUT.

3.3 Performance tips

If you want to display millions of polygons in 30 fps, Gauche-gl is not for you. Consider using implementations that compiles into native code. The purpose of Gauche-gl is to provide reasonable performance for interactive development and experiment.

However, if you know some tips, actually you can go quite far, especially with recent processors and graphics chips.

Avoid alocation within the inner loop.

The functional (non-destructive) operations tend to return newly-allocated objects. Use linear-update (destructive) versions instead, such as matrix-mul!, u8vector-add!, etc, whenever possible. Pre-allocating temporary vectors is also effective.

Reduce the number of calls within the inner loop.

Vertex arrays are much better than calling gl-vertex over and over. Also consider using display lists if you're displaying rigid objects.

Keep numbers within a uniform vector.

Every time you take a number out of a uniform vector (or <vector4f> etc.), Gauche has to wrap the number by a tag (boxing). Also when you store a number into a uniform vector, Gauche has to check the type of the object, then strip a tag (unboxing). Those are all overhead you wouldn't have if you operate directly on uniform vectors (or <vector4f> etc).

Write extensions to accelerate.

If the above strategies are not enough, consider writing computation-intensive part in C as an extension. The easier way is to make C routines operate on uniform vectors, which is essentially a pointer to an array of numbers from C, and let Scheme handle higher-level data structures. (It could be viewed like relations between a coprocessor and a processor; the former does simple, iterative calculations fast, and the latter handles complicated logic).

4. OpenGL API

5. GLU API

6. GLUT API

6.1 GLUT window manipulation

Function: glut-init args

Function: glut-init-display-mode mode

Constant: GLUT_RGB

Constant: GLUT_RGBA

Constant: GLUT_INDEX

Constant: GLUT_SINGLE

Constant: GLUT_DOUBLE

Constant: GLUT_ACCUM

Constant: GLUT_ALPHA

Constant: GLUT_DEPTH

Constant: GLUT_STENCIL

Constant: GLUT_MULTISAMPLE

Constant: GLUT_STEREO

Constant: GLUT_LUMINANCE

Function: glut-init-display-string string

Function: glut-init-window-size width height

Function: glut-init-window-position x y

Function: glut-main-loop

Function: glut-create-widnow name

Function: glut-create-sub-window win x y width height

Function: glut-destroy-window win

Function: glut-post-redisplay

Function: glut-post-window-redisplay win

Function: glut-swap-buffers

Function: glut-get-window

Function: glut-set-window win

Function: glut-set-window-title title

Function: glut-set-icon-title title

Function: glut-position-window x y

Function: glut-reshape-window width height

Function: glut-push-window

Function: glut-pop-window

Function: glut-iconify-window

Function: glut-show-window

Function: glut-hide-window

Function: glut-full-screen

Function: glut-set-cursor cursor

Constant: GLUT_CURSOR_RIGHT_ARROW

Constant: GLUT_CURSOR_LEFT_ARROW

Constant: GLUT_CURSOR_INFO

Constant: GLUT_CURSOR_DESTROY

Constant: GLUT_CURSOR_HELP

Constant: GLUT_CURSOR_CYCLE

Constant: GLUT_CURSOR_SPRAY

Constant: GLUT_CURSOR_WAIT

Constant: GLUT_CURSOR_TEXT

Constant: GLUT_CURSOR_CROSSHAIR

Constant: GLUT_CURSOR_UP_DOWN

Constant: GLUT_CURSOR_LEFT_RIGHT

Constant: GLUT_CURSOR_TOP_SIDE

Constant: GLUT_CURSOR_BOTTOM_SIDE

Constant: GLUT_CURSOR_LEFT_SIDE

Constant: GLUT_CURSOR_RIGHT_SIDE

Constant: GLUT_CURSOR_TOP_LEFT_CORNER

Constant: GLUT_CURSOR_TOP_RIGHT_CORNER

Constant: GLUT_CURSOR_BOTTOM_RIGHT_CORNER

Constant: GLUT_CURSOR_BOTTOM_LEFT_CORNER

Constant: GLUT_CURSOR_INHERIT

Constant: GLUT_CURSOR_NONE

Constant: GLUT_CURSOR_FULL_CROSSHAIR

Function: glut-warp-pointer x y

6.2 GLUT overlay

Function: glut-establish-overlay

Function: glut-remove-overlay

Function: glut-use-layer layer

Function: glut-post-overlay-redisplay

Function: glut-post-window-overlay-redisplay win

Function: glut-show-overlay

Function: glut-hide-overlay

6.3 GLUT menu API

Function: glut-create-menu callback

Function: glut-destroy-menu menu

Function: glut-get-emnu

Function: glut-set-menu menu

Function: glut-add-menu-entry label value

Function: glut-add-sub-menu label submenu

Function: glut-change-to-menu-entry item label value

Function: glut-change-to-sub-menu item label submenu

Function: glut-remove-menu-item item

Function: gult-attach-menu button

Function: glut-detach-menu button

6.4 GLUT callbacks

Function: glut-display-func fn

Function: glut-reshape-func fn

Function: glut-keyboard-func fn

Constant: GLUT_KEY_F1

Constant: GLUT_KEY_F2

Constant: GLUT_KEY_F3

Constant: GLUT_KEY_F4

Constant: GLUT_KEY_F5

Constant: GLUT_KEY_F6

Constant: GLUT_KEY_F7

Constant: GLUT_KEY_F8

Constant: GLUT_KEY_F9

Constant: GLUT_KEY_F10

Constant: GLUT_KEY_F11

Constant: GLUT_KEY_F12

Constant: GLUT_KEY_LEFT

Constant: GLUT_KEY_UP

Constant: GLUT_KEY_RIGHT

Constant: GLUT_KEY_DOWN

Constant: GLUT_KEY_PAGE_UP

Constant: GLUT_KEY_PAGE_DOWN

Constant: GLUT_KEY_HOME

Constant: GLUT_KEY_END

Constant: GLUT_KEY_INSERT

Function: glut-mouse-func fn

Constant: GLUT_LEFT_BUTTON

Constant: GLUT_MIDDLE_BUTTON

Constant: GLUT_RIGHT_BUTTON

Constant: GLUT_DOWN

Constant: GLUT_UP

Function: glut-motion-func fn

Function: glut-passive-motion-func fn

Function: glut-entry-func fn

Constant: GLUT_LEFT

Constant: GLUT_ENTERED

Function: glut-visibility-func fn

Constant: GLUT_NOT_VISIBLE

Constant: GLUT_VISIBLE

Function: glut-idle-func fn

Function: glut-timer-func millis fn value

Function: glut-menu-state-func fn

Function: glut-special-func fn

Function: glut-spaceball-motion-func fn

Function: glut-spaceball-rotate-func fn

Function: glut-spaceball-button-func fn

Function: glut-button-box-func fn

Function: glut-dials-func fn

Function: glut-tablet-motion-func fn

Function: glut-tablet-button-func fn

Function: glut-menu-status-func fn

Function: glut-overlay-dislay-func fn

Function: glut-window-status-func fn

Function: glut-keyboard-up-func fn

Function: glut-special-up-func fn

Function: glut-joystick-func fn interval

6.5 GLUT colormap

Function: glut-set-color index r g b

Function: glut-get-color index component

Constant: GLUT_RED

Constant: GLUT_GREEN

Constant: GLUT_BLUE

Function: glut-copy-colormap win

6.6 GLUT state retrieval

Function: glut-get type

Constant: GLUT_WINDOW_X

Constant: GLUT_WINDOW_Y

Constant: GLUT_WINDOW_WIDTH

Constant: GLUT_WINDOW_HEIGHT

Constant: GLUT_WINDOW_BUFFER_SIZE

Constant: GLUT_WINDOW_STENCIL_SIZE

Constant: GLUT_WINDOW_DEPTH_SIZE

Constant: GLUT_WINDOW_RED_SIZE

Constant: GLUT_WINDOW_GREEN_SIZE

Constant: GLUT_WINDOW_BLUE_SIZE

Constant: GLUT_WINDOW_ALPHA_SIZE

Constant: GLUT_WINDOW_ACCUM_RED_SIZE

Constant: GLUT_WINDOW_ACCUM_GREEN_SIZE

Constant: GLUT_WINDOW_ACCUM_BLUE_SIZE

Constant: GLUT_WINDOW_ACCUM_ALPHA_SIZE

Constant: GLUT_WINDOW_DOUBLEBUFFER

Constant: GLUT_WINDOW_RGBA

Constant: GLUT_WINDOW_PARENT

Constant: GLUT_WINDOW_NUM_CHILDREN

Constant: GLUT_WINDOW_COLORMAP_SIZE

Constant: GLUT_WINDOW_NUM_SAMPLES

Constant: GLUT_WINDOW_STEREO

Constant: GLUT_WINDOW_CURSOR

Constant: GLUT_SCREEN_WIDTH

Constant: GLUT_SCREEN_HEIGHT

Constant: GLUT_SCREEN_WIDTH_MM

Constant: GLUT_SCREEN_HEIGHT_MM

Constant: GLUT_MENU_NUM_ITEMS

Constant: GLUT_DISPLAY_MODE_POSSIBLE

Constant: GLUT_INIT_WINDOW_X

Constant: GLUT_INIT_WINDOW_Y

Constant: GLUT_INIT_WINDOW_WIDTH

Constant: GLUT_INIT_WINDOW_HEIGHT

Constant: GLUT_INIT_DISPLAY_MODE

Constant: GLUT_ELAPSED_TIME

Constant: GLUT_WINDOW_FORMAT_ID

Function: glut-device-get type

Constant: GLUT_HAS_KEYBOARD

Constant: GLUT_HAS_MOUSE

Constant: GLUT_HAS_SPACEBALL

Constant: GLUT_HAS_DIAL_AND_BUTTON_BOX

Constant: GLUT_HAS_TABLET

Constant: GLUT_NUM_MOUSE_BUTTONS

Constant: GLUT_NUM_SPACEBALL_BUTTONS

Constant: GLUT_NUM_BUTTON_BOX_BUTTONS

Constant: GLUT_NUM_DIALS

Constant: GLUT_NUM_TABLET_BUTTONS

Constant: GLUT_DEVICE_IGNORE_KEY_REPEAT

Constant: GLUT_DEVICE_KEY_REPEAT

Constant: GLUT_HAS_JOYSTICK

Constant: GLUT_OWNS_JOYSTICK

Constant: GLUT_JOYSTICK_BUTTONS

Constant: GLUT_JOYSTICK_AXES

Constant: GLUT_JOYSTICK_POLL_RATE

Function: glut-extension-supported name

Function: glut-get-modifiers

Constant: GLUT_ACTIVE_SHIFT

Constant: GLUT_ACTIVE_CTRL

Constant: GLUT_ACTIVE_ALT

Function: glut-layer-get type

Constant: GLUT_OVERLAY_POSSIBLE

Constant: GLUT_LAYER_IN_USE

Constant: GLUT_HAS_OVERLAY

Constant: GLUT_TRANSPARENT_INDEX

Constant: GLUT_NORMAL_DAMAGED

Constant: GLUT_OVERLAY_DAMAGED

6.7 GLUT font

Class: <glut-font>

Function: glut-bitmap-character font character

Function: glut-bitmap-width font character

Function: glut-stroke-character font character

Function: glut-stroke-width font character

Function: glut-bitmap-length font string

Function: glut-stroke-length font string

6.8 GLUT pre-built models

Function: glut-wire-sphere radius slices stacks

Function: glut-solid-sphere radius slices stacks

Function: glut-wire-cone radius height slices stacks

Function: glut-solid-cone radius height slices stacks

Function: glut-wire-cube size

Function: glut-solid-cube size

Function: glut-wire-torus inner outer sides rings

Function: glut-solid-torus inner outer sides rings

Function: glut-wire-dodecahedron

Function: glut-solid-dodecahedron

Function: glut-wire-teapot size

Function: glut-soild-teapot size

Function: glut-wire-octahedron

Function: glut-solid-octahedron

Function: glut-wire-tetrahedron

Function: glut-solid-tetrahedron

Function: glut-wire-icosahedron

Function: glut-solid-icosahedron

7. Vectors and matrices

Module: gl.math3d

The module provides vector and matrix operations useful for 3D computer graphics.

Actually this module itself doesn't depend on GL; you can use this module alone to do matrix calculations. However, the structure of objects are designed so that they can be passed directly to Gauche-gl functions, reducing the overhead of type conversions.

The purpose of this module is to provide reasonable performance. So the operations are fixed to 3D homogeneous coordinates, i.e. a vector is 4-element column vector, and a matrix is 4x4 square matrix. If you want more flexibility, <array> class in gauche.array provides much more generic structures, trading performance.

Elements of vectors and matrices are represented in float internally. When you retrieve each element individually, it is converted to double, so you might see some precision errors. There are lots of operations directly manipulate group of elements without retrieving each element to Scheme world, avoiding overhead of conversion.

7.1 Vectors and points

Class: <vector4f>

Class: <point4f>

4x1 column vectors. Vector4f is intended to be used to represent a vector, and point4f is to a point, but as far as OpenGL concerns, both are just an array of four floats, x, y, z and w.

These classes inherit <sequence> and <collection> classes. So if you import gauche.sequence module, you can use generic function such as ref and (setter ref) to get/set individual elements. The generic version of map and for-each can also be used on the vector4f and point4f instances.

Aside from the type, the only difference is that the default value of w component--- it's 0.0 for vectors, and 1.0 for points. So usual transformation produces expected results; for example point plus vector becomes point, vector plus vector becomes vector, and translating point changes its coordinates but translating vectors doesn't, and so on. However, you can set w component to other value to do nontrivial operations.

Reader syntax: #,(vector4f x y z w)

Reader syntax: #,(point4f x y z w)

These SRFI-10 syntax can be used to denote literal <vector4f> and <point4f> instance, respectively.

The write methods are defined so that the instance is written out in this form, and can be read back later.

Function: vector4f? obj

Function: point4f? obj

Returns true iff obj is vector4f and point4f, respectively.

Function: vector4f x y z &optional (w 0.0)

Function: point4f x y z &optional (w 1.0)

Creates a vector4f and point4f instance with given values, respectively.

Function: make-vector4f

Function: make-point4f

Another way to create a vector4f and a point4f. The first returns #,(vector4f 0.0 0.0 0.0 0.0), and the latter returns #,(point4f 0.0 0.0 0.0 1.0).

Function: list->vector4f l

Function: list->point4f l

Convert a list of three or four real numbers to a vector4f and a point4f, respectively. If l is not a list of three or four real numbers, an error is signalled.

(list->vector4f l) == (apply vector4f l) == (coerce-to <vector4f> l)

Function: vector4f->list v

Function: point4f->list p

Convert a vector4f and a point4f to a list of four real numbers, respectively.

(vector4f->list v) == (coerce-to <list> v) == (map (cut ref v <>) (iota 4))

Function: f32vector->vector4f v &optional start

Function: f32vector->point4f v &optional start

Creates a vector4f or a point4f, initializing by the elements of f32vector v. V must be longer than 4, and the first four elements are used to initialize the created vector or point.

If optional start argument is given, it specifies an index of v from which the initial values are taken; that is, start, start+1, start+2 and start+3-th elements are used to create a vector or a point. This allows to create vectors from plain float array:

(map (lambda (off) (f32vector->vector4f vec (* off 4))) (iota (/ (size-of vec) 4)))

The conversion can be done using coerce-to, as well.

(f32vector->vector4f vec) == (coerce-to <vector4f> vec)

Function: vector4f->f32vector v

Function: point4f->f32vector p

Convert a vector4f v or a point4f p to four-element f32vector.

(vector4f->f32vector v) == (coerce-to <f32vector> v)

Function: vector4f-copy v

Function: point4f-copy p

Returns a new copy of vector4f v or point4f p, respectively.

Function: vector4f-copy! dstv srcv

Function: point4f-copy! dstp srcp

Destructively sets the content of srcv or srcp to dstv or dstp, respectively.

Function: vector4f-set! v k value

Function: point4f-set! p k value

Sets a real number value to k-th element of a vector4f v or a point4f p.

(vector4f-set! v k value) == (set! (ref v k) value)

Function: vector4f-ref v k &optional fallback

Function: point4f-ref p k &optional fallback

Gets a value of k-th element of a vector4f v or a point4f p. If k is out of range, an error is signalled, unless fallback is provided, in such a case fallback is returned.

(vector4f-ref v k) == (ref v k)

Function: vector4f-dot x y

Returns a dot product of two vector4fs, x and y.

Function: vector4f-cross x y

Returns a cross product of two vector4fs, x and y. (w element is ignored).

Function: vector4f-normalize x

Function: vector4f-normalize! x

Returns a normalized vector of vector4f x. Vector4f-normalize allocates a new vector, while vector4f-normalize! modifies the original vector.

As a special case, if x is a vector of length 0, a vector of length 0 is returned.

Function: vector4f-add x y

Function: vector4f-sub x y

Function: vector4f-add! x y

Function: vector4f-sub! x y

Returns a sum of two vector4fs, x and y. The destructive version modifies x.

Function: point4f-add x y

Function: point4f-add! x y

Adds a point4f x and a vector4f y, and returns a translated point. The destructive version modifies x.

Function: point4f-sub x y

Subtracts either a vector4f or a point4f y from a point4f x. If y is a vector4f, returns a translated point. If y is a point4f, returns a vector4f from point y to point x.

7.2 Vector arrays and point arrays

Class: <vector4f-array>

Class: <point4f-array>

Represents an array of vector4fs and point4fs. This is an efficient way to keep an array of vectors or points, for the elements are packed in a simple float array. They are especially useful to work with GL's vertex array feature. gl-vertex-pointer can take <point4f-array>, and gl-normal-pointer can take <vector4f-array>.

It is also possible to "view" a plain f32vector as <vector4f-array> or <point4f-array> without copying its content, by f32vector->vector4f-array/shared and f32vector->point4f-array/shared. Combined to read-block!, you can do efficient binary I/O of vertex arrays, for example.

Inherits <sequence> and <collection>. When viewed as a sequence or a collection, they behaves like sequence or collection of vector4f and point4f objects, respectively.

Function: make-vector4f-array len &optional init-vector

Function: make-point4f-array len &optional init-point

Creates a vector4f-array or point4f-array with len elements. Each element is initialized by a vector4f init-vector or a point4f init-point if provided.

Function: vector4f-array? obj

Function: point4f-array? obj

Returns true iff obj is a vector4f-array or a point4f-array, respectively.

Function: vector4f-array-length array

Function: point4f-array-length array

Returns length (number of vectors/points) in array array.

Reader syntax: #,(vector4f-array len elt ...)

Reader syntax: #,(point4f-array len elt ...)

Vector4f-array and point4f-array have external representation using this SRFI-10 syntax. Len is a length of array, and each elt is a list of four floats representing each element of the array.

(f32vector->vector4f-array #f32(1 2 3 4 6 7 4 3)) => #,(vector4f-array 2 (1 2 3 4) (6 7 4 3) )

Function: list->vector4f-array list

Function: list->point4f-array list

From given list of vector4fs or point4fs, creates and returns a vector4f-array or point4f-array, respectively.

Function: f32vector->vector4f-array v

Function: f32vector->point4f-array v

Converts f32vector v to a vector4f-array or a point4f-array. The length of v must be multiple of four. The content of v is copied.

(f32vector->vector4f-array v) == (coerce-to <vector4f-array> v)

Function: f32vector->vector4f-array/shared v

Function: f32vector->point4f-array/shared v

Like above, but the content of v is shared by the result array, instead of being copied. So the modification of result array will be visible from original f32vector v and vice versa. It will allow efficient handling of large vertex arrays.

Function: vector4f-array->f32vector array

Function: point4f-array->f32vector array

Converts a vector4f-array or a point4f-array array to a f32vector.

(vector4f-array->f32vector array) == (coerce-to <f32vector> array)

Function: vector4f-array-set! array i vector

Function: point4f-array-set! array i point

Sets a vector4f vector or a point4f point to i-th element of vector4f-array or point4f-array array, respectively.

(vector4f-array-set! array i vector) == (set! (ref array i) vector)

Function: vector4f-array-ref array i &optional fallback

Function: point4f-array-ref array i &optional fallback

Returns a vector4f or a point4f which is the i-th element of array array, respectively. If k is out of range, an error is signalled, unless fallback is provided, in such a case fallback is returned.

(vector4f-array-ref array i) == (ref array i) (ref #,(vector4f-array 2 (1 2 3 4) (6 7 4 3)) 1) => #,(vector4f 6 7 4 3)

Function: vector4f-array-ref/shared array i &optional fallback

Function: point4f-array-ref/shared array i &optional fallback

Like above, but the returned vector4f or point4f shares the storage with the original array. Thus the modification of the result vector or point will be visible from array, and vice versa.

7.3 Matrices

Class: <matrix4f>

4x4 matrix. Internally it is represented as an array of 16 floats, stored in column-major order. (It is the same order OpenGL uses, so it can be passed to OpenGL calls without overhead).

Inherits <sequence> and <collection>. When a matrix4f is treated as a sequence, it works as if it is a single sequence of floats in column-major order.

Function: make-matrix4f &optional init

Returns a new matrix4f instance. If init is omitted, the matrix is a unit matrix. Otherwise, init must be a f32vector of length 16, and the elements in the matrix is initialized by ones in f32vector.

;; Creates a matrix like this: ;; 1 2 3 4 ;; 0 1 0 5 ;; 0 0 1 6 ;; 0 0 0 1 (make-matrix4f '#f32vector(1 0 0 0 2 1 0 0 3 0 1 0 4 5 6 1))

Function: matrix4f m00 m10 m20 m30 m01 m11 m21 m31 m02 m12 m22 m32 m03 m13 m23 m33

Creates a new matrix4f instance with give values.

Function: matrix4f? obj

Returns true iff obj is a matrix4f.

Reader syntax: #,(matrix4f elt ...)

A matrix4f is represented extrenally using SRFI-10 syntax. The elements are listed in column-major order.

Function: list->matrix4f l

Function: matrix4f->list m

Converts between list of 16 real numbers and matrix4f.

Function: f32vector->matrix4f v &optional start

Creates a new matrix4f and initializes it with 16 elements in f32vector v. If optional start is given, it specifies the start offset in vector v to be used as initial values. The f32vector v must have enough length.

Function: matrix4f->f32vector m

Returns a new f32vector that has elements from matrix4f m.

Function: matrix4f-copy m

Returns a new copy of m.

Function: matrix4f-copy! dstm srcm

Copies contents of srcm to dstm.

Function: matrix4f-set! m i value

Sets a real number value to i-th element of matrix m. Since the matrix is laid out in column-major order, the one-dimensional index m{i} and two-dimensional index m(i,j) corresponds as follows:

m(0,0) = m{0} m(0,1) = m{4} m(0,2) = m{8} m(0,3) = m{12} m(1,0) = m{1} m(1,1) = m{5} m(1,2) = m{9} m(1,3) = m{13} m(2,0) = m{2} m(2,1) = m{6} m(2,2) = m{10} m(2,3) = m{14} m(3,0) = m{3} m(3,1) = m{7} m(3,2) = m{11} m(3,3) = m{15}

Function: matrix4f-ref m i &optional fallback

Returns the i-th element of matrix m. If i is out of range, an error is signalled, unless fallback is provided, in such a case fallback is returned.

Function: matrix4f-set2! m i j value

Sets value to (i, j) element of matrix m.

Function: matrix4f-ref2 m i j

Returns the (i, j) element of matrix m.

Function: matrix4f-row m i

Function: matrix4f-column m i

Function: matrix4f-column/shared m i

Returns i-th row vector or i-th column vector of matrix m, as a vector4f instance.

Furthermore, the returned vector from matrix4f-column/shared shares the storage with m.

Function: matrix4f-mul m obj

Obj may be a scalar (real number), a vector4f, a point4f, or a matrix4f. Returns m x obj.

Function: matrix4f-mul! m obj

Obj may be a scalar or a matrix4f. Matrix m is multiplied by obj, and the result is set to m destructively.

Function: matrix4f-transpose m

Function: matrix4f-transpose! m

Returns a transposed matrix of m. The destructive version modifies m.

Function: matrix4f-determinant m

Returns a determinant of m.

Function: matrix4f-inverse m &optional (error-on-singular? #t)

Function: matrix4f-inverse! m &optional (error-on-singular? #t)

Returns a inverse matrix of m. The destructive version modifies m. If given m is a singular matrix, an error is signalled by default. However, if #f is given to the optional error-on-singular? argument, #f is returned in such a case.

Function: translation->matrix4f translation-vector

Function: translation->matrix4f! m translation-vector

Returns a matrix which represents a translation by translation-vector, which must be either a vector4f, a point4f, or a f32vector of length 3 or 4. Only the first three elements in translation-vector is used. The destructive version updates m.

Function: rotation->matrix4f axis angle

Function: rotation->matrix4f! m axis angle

Returns a matrix which represents a rotation around axis by angle radian. Axis must be a vector4f or a f32vector of length 3 or 4, and must be normalized. The result is undefined if anormalized vector is passed as axis. The destructive version updates m.

Function: scale->matrix4f scale-vector

Function: scale->matrix4f! m scale-vector

Returns a matrix which represents a scale by scale-vector, which must be either a vector4f, a point4f, or a f32vector of length 3 or 4. Only the first three elements in scale-vector is used. Each element of scale-vector represents the scale factor along x, y, and z axis. The destructive version updates m.

Function: trs->matrix4f translation rotation-axis rotation-angle scale

Function: trs->matrix4f! m translation rotation-axis rotation-angle scale

This combines above three procedure. Returns a matrix that represents translation, rotation and scale, specified by translation, rotation-axis, rotation-angle and scale. The destructive version updates m.

If T, R and S, are the matrices that represent translation, rotation and scale, respectively, then these procedures effectively calculates a matrix TRS.

Function: tqs->matrix4f translation rotation-quat scale

Function: tqs->matrix4f! m translation rotation-quat scale

A variation of trs->matrix4f. Instead of axis and angle, rotation is represented by a quaternion rotation-quat. See section 7.4 Quaternions, for more details about quaternions.

Function: euler-angle->matrxi4f xangle yangle zangle &optional order

Function: euler-angle->matrxi4f! m xangle yangle zangle &optional order

Returns a matrix that represents rotation along x, y and z axis by xangle, yangle, and zangle, respectively.

The order of rotation can be specified by the optional argument order, which may be one of the symbols xyz, xzy, yzx, yxz, zxy, or zyx. For example, symbol xyz means rotation around x-axis, then y-axis, then z-axis. Thus, if we write each rotation as Rx, Ry, and Rz, the returned matrix is RzRyRx. The default value of order is xyz.

The desrtuctive version modifies m.

Function: matrix4f-decompose m

Matrix m is a composition of translation, rotation, shear and scale. Suppose transformation is applied in the reverse order. This procedure decompose m into each individual transformation.

Returns five values.

• A flag to indicate if m is non-singular.
• A translation vector t, in vector4f. The first three elements of t are for x, y, and z translations.
• A rotation matrix r, in matrix4f. This is an orthogonal matrix represents rotation component.
• A shear vector h, in vector4f. The first three elements of h are for xy, xz and yz shear factors.
• A scale vector s, in vector4f. The first three elements of s are fof x, y, and z scale factors.

If m is singular, certain part of rotation matrix can't be recovered. In such a case, r becomes also singular matrix.

If the original matrix has negative scale factor in any of x, y, or z scale, the decomposed scale factor will have all negative components. The signs of elements of r are adjusted accordingly.

Due to the precision errors, you will see small values appear in shear component even m is pure TRS matrix.

Function: matrix4f-decompose! m t r h s

Linear update version of matrix4f-decompose. The result vectors and matrices are stored in t, r, h and s. The return value is a boolean value indicates m is non-singular or not.

Function: matrix4f->rotation m

From given orthogonal matrix m, extracts and returns and rotation axis and angle, as a vector4f and a real number.

Function: matrix4f->rotation! m v

Same as above, except the storage of vector4f v is reused to store the result axis.

7.4 Quaternions

Class: <quatf>

Quaternions. Internally quaternions are represented as just an array of four floats; the first three are the vector component and the last is the scalar component.

Inherits <sequence> and <collection>. When viewed as sequence, it is just like a vector of four floats.

Function: quatf? obj

Returns true iff obj is a quaternion.

Reader syntax: #,(quatf x y z w)

External representation of quaternion xi+yj+zk+w.

Function: make-quatf &optional axis (angle 0)

Returns a new unit quaternion that represents a rotation around vector axis by angle radians. Axis can be a vector4f, a point4f or a f32vector (only first three component is used). Axis must be a unit vector; if axis is anormalized, the result is undefined.

If both axis and angle is omitted, #,(quatf 0 0 0 1) is returned.

Function: quatf x y z w

Returns a new quaternion whose elements are initialized by x, y, z, w.

Function: list->quatf l

Function: quatf->list q

Converts between a list of four real numbers and a quaternion.

Function: f32vector->quatf x &optional start

Returns a new quaternion whose elements are initialized by the first four elements of f32vector x. If start is given, the initial value is taken starting from start-th index in x.

Function: quatf->f32vector q

Returns a new f32vector whose contents is the same as a quaternion q.

Function: quatf-copy q

Returns a fresh copy of a quaternion q.

Function: quatf-copy! dstq srcq

Copies contents of a quaternion srcq to a quaternion dstq.

Function: rotation->quatf! quat axis angle

Sets a quaternion quat so that it represents a rotation around a unit vector axis by angle angle radians. Axis can be a vector4f, a point4f or a f32vector (only first three component is used).

Function: quatf-add p q

Function: quatf-add! p q

Function: quatf-sub p q

Function: quatf-sub! p q

Addition and subtraction of quaternions. The destructive version modifies the first argument.

Function: quatf-scale q s

Function: quatf-scale! q s

Multiplies a quaternion q by a scalar value s. The destructive version modifies q.

Function: quatf-mul p q

Function: quatf-mul! p q

Multiply two quaternions p and q. The destructive version modifies p.

Function: quatf-conjugate q

Returns a conjugate of a quaternion q.

Function: quatf-transform q p

Transforms a vector or a point p by quaternion q, that is, returns qpq*, where q* is a conjugate of q.

This procedure assumes q is normalized.

P can be a vector4f, a point4f or a f32vector (only first three elements are used). Returns the same type of object as p.

Function: quatf-norm q

Returns norm of q.

Function: quatf-normalize q

Function: quatf-normalize! q

Returns normalized quaternion of q. The destructive version modifies q.

Function: quatf->matrix4f q

Function: quatf->matrix4f! m q

Returns a matrix that represents a rotation specified by a unit quaternion q. The behavior is undefined if q is not normalized. The destructive version modifies m.

Function: quatf-slerp p q t

Function: quatf-slerp! r p q t

Returns a quaternion that interpolates between two unit quaternions p and q, by a scalar value t. The destructive version modifies t.

A. Indices

A.1 Function and Syntax Index

A.2 Module Index

A.3 Class Index

For readability, the surrounding < and > are stripped off.

A.4 Variable Index

Table of Contents

1. Introduction
2. Installation
3. Getting Started

3.1 GL calls in Scheme
3.2 Using GLUT
3.3 Performance tips

4. OpenGL API
5. GLU API
6. GLUT API

6.1 GLUT window manipulation
6.2 GLUT overlay
6.3 GLUT menu API
6.4 GLUT callbacks
6.5 GLUT colormap
6.6 GLUT state retrieval
6.7 GLUT font
6.8 GLUT pre-built models

7. Vectors and matrices

7.1 Vectors and points
7.2 Vector arrays and point arrays
7.3 Matrices
7.4 Quaternions

A. Indices

A.1 Function and Syntax Index
A.2 Module Index
A.3 Class Index
A.4 Variable Index

Short Table of Contents

1. Introduction
2. Installation
3. Getting Started
4. OpenGL API
5. GLU API
6. GLUT API
7. Vectors and matrices
A. Indices

About this document

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

• 1. Section One
  • 1.1 Subsection One-One
    • ...
  • 1.2 Subsection One-Two
    • 1.2.1 Subsubsection One-Two-One
    • 1.2.2 Subsubsection One-Two-Two
    • 1.2.3 Subsubsection One-Two-Three     <== Current Position
    • 1.2.4 Subsubsection One-Two-Four
  • 1.3 Subsection One-Three
    • ...
  • 1.4 Subsection One-Four