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

1. Introduction

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

gl

This module provides bindings to OpenGL API. It covers most functions in OpenGL 1.0 through 2.0, and GLU. The functions are described in 4. OpenGL API.

gl.glut

This module provides bindings to most functions in GLUT. The functions are described in 5. GLUT API.

gl.math3d

This module 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 6. Vectors and matrices.

gl.simple-image

OpenGL doesn't provide any means of reading/writing image data, and it should be covered by other Gauche extensions. However, it is sometimes handy to have simple means to handle external image data, so that you can do some experiment with Gauche-gl alone. This module provides minimal support for that. The functions are descrbied in 7. Simple image handling.

2. Installation

Installing Gauche-gl is usually straightforward on Unix variants.

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

• Gauche 0.8.5 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.4.tgz | tar xf -
% cd Gauche-gl-0.4
% ./configure
% make
% make test
% make install

Or you can use `gauche-package' command:

% gauche-package install -C=<configure-option> Gauche-gl-0.4.tgz

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

Since version 0.4, Gauche-gl can be configured to include bindings to NVidia's Cg Toolkit. The binding code is contributed by Issac Trotts. To enable Cg binding, give --enable-cg option to the configure script.

% ./configure --enable-cg

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.

There are various examples under `examples/' directory. If you want to run the examples before installing Gauche-gl, you have to tell the location of the library to gosh command, e.g. gosh -I../src -I../lib gears.scm. Some demos under subdirectories have a shell script that invokes gosh with proper command-line options.

`gears.scm'

Brian Paul's 3D gear wheels.

`mandelbrot.scm'

Simple calculated texture.

`glbook/'

This subdirectory contains examples found in "OpenGL Programming Guide", a.k.a. Redbook.

`slbook/'

This subdirectory contains examples found in "OpenGL Shading Language". Each demo is under its own subdirectories. You need to have proper driver/hardware that supports GLSL to run these demos.

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

3.2 Advanced GL features

Although Gauche-gl supports up to OpenGL 2.0, all functionalities may not be available on the target machine's driver/hardware. The application needs to check the availability of the extension and/or GL version before using the features that are only supported by the extension/version.

Gauche-gl provides a couple of utility procedures to check the feature sets at runtime. For example, you can switch behavior depending on OpenGL 1.3 feature availability:

(if (gl-version>=? "1.3")
  (code-using-features-available-in-OpenGL-1.3-and-later ...)
  (alternative-code ...))

Or you can check the availability of extensions:

(unless (gl-extension-supported? 'GL_ARB_shader_objects
                                 'GL_ARB_fragment_shader
                                 'GL_ARB_vertex_shader
                                 'GL_ARB_shading_language_100)
   (error "OpenGL Shading Language extensions not available"))

See 4.2 GL feature checking for the details.

If the client program calls a GL API that are not supported on the platform, an error is signalled.

3.3 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.4 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

In this chapter we list a GL and GLU procedures accessible from Gauche-gl, with brief descriptions to help programmers to remind what the functions are. We don't intend to make this an OpenGL reference, though; you should look at the OpenGL book for the details of what each API do.

4.1 GL data types

GL doesn't define many data structures: some scalar primitives (e.g. GLint) and arrays of them.

For scalar values, Gauche-gl has natural mappings:

GLboolean

Scheme booleans.

GLbyte, GLubyte, GLshort, GLushort, GLint, GLuint, GLenum, GLbitfield

Scheme exact integers.

GLfloat, GLdouble, GLclampf, GLclampd

Scheme real numbers.

For arrays, Gauche-gl uses uniform (srfi-4) vector whenever possible. For float arrays, however, Gauche-gl allows more structured types, such as points or matrices, when they are relevant. Such types are provided in gl.math3d module (see 6. Vectors and matrices), which also provides common arithmetics between those types. Another exception is an array of GLboolean--it doesn't have corresponding uniform vector representation. Gauche-gl defines a new type, <gl-boolean-vector>, to represent an array of GLboolean. See below for operations provided on it.

GLbyte[]

<s8vector>

GLubyte[]

<u8vector>

GLshort[]

<s16vector>

GLushort[]

<u16vector>

GLint[]

<s32vector>

GLuint[]

<u32vector>

GLfloat[], GLclampf[]

<f32vector>, <point4f>, <vector-4f>, <point4f-array>, <vector4f-array>, <matrix4f>, <quatf>.

GLdouble[], GLclampd[]

<f64vector>

GLboolean[]

<gl-boolean-vector>

GL boolean vectors

Class: <gl-boolean-vector>

A class for an array of boolean values. You can pass its instance to the GL APIs that expect an array of GLbooleans. Its internal representation is bitwise compatible to GLbooean array, so passing it is quite efficient.

This class inherits <sequence>, so you can use generic sequence operations on it.

The external representation of GL boolean vector uses srfi-10 notation, and can be read back. For example, a GL boolean vector of length 5 may be written something like this:

#,(gl-boolean-vector #t #f #t #f #t)

Function: make-gl-boolean-vector size &optional init

Returns a GL boolean vector of size elements. Elements are initialized by either #f or #t, according to init.

(make-gl-boolean-vector 3 #t) => #,(gl-boolean-vector #t #t #t)

Function: gl-boolean-vector bool ...

Returns a GL boolean vector, whose elements are bool ....

(gl-boolean-vector #f #t #t) => #,(gl-boolean-vector #f #t #t)

Function: gl-boolean-vector? obj

Returns #t if obj is a GL boolean vector, #f otherwise.

Function: gl-boolean-vector-length v

Returns length of a GL boolean vector v. You can also use the sequence generic function size-of.

Function: gl-boolean-vector-fill! v bool

Fills a GL boolean vector v with a boolean value bool.

Function: list->gl-boolean-vector bools

Coerce list of boolean values to a GL boolean vector.

You can also use the coerce-to generic function to convert between GL boolean vectors and other sequences.

Function: gl-boolean-vector-ref v k &optional fallback

Returns k-th element of a GL boolean vector v. If k is out of range and fallback is provided, it is returned. If k is out of range and fallback is omitted, an error is signalled.

You can also use generic function ref to access a GL boolean vector.

Function: gl-boolean-vector-set! v k bool

Sets k-th element of a GL boolean vector v by a boolean value bool.

You can also use generic function (setter ref) to modify a GL boolean vector.

Function: gl-boolean-vector-copy v

Returns a copy of a GL boolean vector v.

4.2 GL feature checking

If you want to use a feature that are in OpenGL 1.2 or later, or in a GL extension, you have to check its availability before actually calling the API function. You can use the following utility procedures.

Note that those functions may return #f if the connection to the display subsystem isn't established yet. Usually you have to initialize and open an window before checking the features.

Function: gl-extension-available? extension-name ...

Returns #t if GL extensions listed in extension-name ... are all available. Extension-name can be a symbol or a string (e.g. GL_ARB_multisample).

Function: gl-version<? version

Function: gl-version<=? version

Function: gl-version>? version

Function: gl-version>=? version

Function: gl-version=? version

Returns #t if the runtime OpenGL version is less than, less thanor equal to, greater than, greater than or equal to, and equal to, the given version, respectively.

Give version in a string, e.g. "1.3".

4.3 Drawing functions

Macro: gl-begin* mode gl-commands ...

Executes gl-commands between (gl-begin mode) and (gl-end). Mode can be one of the following constants.

GL_POINTS

Individual points.

GL_LINES

Pairs of vertices interpreted as individual line segments.

GL_LINE_STRIP

Series of connected line segments.

GL_LINE_LOOP

Same as above, with a segment added between last and first vertices.

GL_TRIANGLES

Triples of vertices interpreted as triangles.

GL_TRIANGLE_STRIP

Linked trip of triangles.

GL_TRIANGLE_FAN

Linked fan of triangles.

GL_QUADS

Quadruples of vertices interpreted as four-sided polygons.

GL_QUAD_STRIP

Linked strip of quadrilaterals.

GL_POLYGON

Boundary of a simple, convex polygon.

Function: gl-begin mode

Function: gl-end

Corresponds to glBegin and glEnd. Use of gl-begin* macro is recommended, though.

Function: gl-flush

Flush the GL command buffer.

Function: gl-finish

Make sure all previously issued GL commands are completed.

Function: gl-rect point1 point2

Function: gl-rect x1 y1 x2 y2

Draws a rectangle. In the first form, point1 and point2 can be either <point4f>, or f32, f64, s32, or s16vector of length 2. Types of both args should match. In the second form, all args should be a real numbers (glRectd is used).

Function: gl-vertex point

Function: gl-vertex x y &optional z w

Specify vertices. In the first form, point can be either <point4f>, or f32, f64, s32 or s16vector of length 2, 3 or 4. In the second form, all args should be a real numbers.

Function: gl-normal vector

Function: gl-normal x y z

Sets vertex normal vector. In the first form, vector can be either <vector4f> (the fourth element is ignored), or f32, f64, s32 ro s16vector of length 3. In the second form, all args should be a real numbers.

Function: gl-color color

Function: gl-color r g b &optional a

Sets the current color. In the first form, color can be either f32, f64, u8, u16, u32, s8, s16, or s32vector of length 3 or 4. In the second form, all args should be a real numbers.

Function: gl-tex-coord coord

Function: gl-tex-coord u v &optional s t

Sets the current texture coordinates. In the first form, coord can be either f32, f64, s32 or s16vector of length 1, 2, 3, or 4. In the second form, all args should be a real numbers.

Function: gl-raster-pos pos

Function: gl-raster-pos x y &optional z w

Sets the current raster position. In the first form, pos can be eitehr f32, f64, s32 or s16vector. In the second form, all args should be a real numbers.

4.4 GL state control

Capabilities

Function: gl-enable cap

Function: gl-disable cap

Turns on and off a capability cap. Check out OpenGL reference for the list of capabilities.

Function: gl-is-enabled cap

Returns #t of #f depending on cap is enabled or not.

Function: gl-enable-client-state array

Function: gl-disable-client-state array

Enable/disable a client-side array (e.g. vertex array) specified by array. Array can be one of the following constants.

GL_VERTEX_ARRAY

GL_COLOR_ARRAY

GL_INDEX_ARRAY

GL_NORMAL_ARRAY

GL_TEXTURE_COORD_ARRAY

GL_EDGE_FLAG_ARRAY

State values

Gauche has two variations for each type of OpenGL glGetTYPE APIs; nondestructive version and destructive versions. Nondestructive versions such as gl-get-boolean allocates and returns the vector of appropriate type for the state. For destructive versions such as gl-get-boolean!, you need to pass a vector to be filled in.

The destructive version is non-allocating operation, so it is suitable if you call it within the drawing loop.

If the state has a scalar value, the non-destructive version of query function returns a scalar value, but you need to pass a (uniform) vector of length 1 for the destructive version.

Function: gl-state-vector-size state

[Gauche specific] Returns the required size of the vector to retrieve GL state state. It is useful to prepare the vector to pass to the destructive version of glGetTYPE API.

Function: gl-get-boolean state

Function: gl-get-boolean! gl-boolean-vector state

Get (a) boolean state value(s).

Function: gl-get-integer state

Function: gl-get-integer! s32vector state

Get (an) integer state value(s).

Function: gl-get-float state

Function: gl-get-float! f32vector state

Get (a) single-precision floating-point state value(s).

Function: gl-get-double state

Function: gl-get-double! f64vector state

Get (a) double-precision floating-point state value(s).

Push/pop attributes

Function: gl-push-attrib mask

Function: gl-pop-attrib

Push/pop attributes indicated by mask. Valid mask can be logior of the following bits (GLL_ALL_ATTRIB_BITS is logior of all the bits).

GL_ACCUM_BUFFER_BIT

GL_COLOR_BUFFER_BIT

GL_CURRENT_BIT

GL_DEPTH_BUFFER_BIT

GL_ENABLE_BIT

GL_EVAL_BIT

GL_FOG_BIT

GL_HINT_BIT

GL_LIGHTING_BIT

GL_LINE_BIT

GL_LIST_BIT

GL_PIXEL_MODE_BIT

GL_POINT_BIT

GL_POLYGON_BIT

GL_POLYGON_STIPPLE_BIT

GL_SCISSOR_BIT

GL_STENCIL_BUFFER_BIT

GL_TEXTURE_BIT

GL_TRANSFORM_BIT

GL_VIEWPORT_BIT

GL_ALL_ATTRIB_BITS

All of the above.

Function: gl-push-client-attrib mask

Function: gl-pop-client-attrib

Push/pop client attributes. Valid mask can be logior of the following

GL_CLIENT_PIXEL_STORE_BIT

GL_CLIENT_VERTEX_ARRAY_BIT

GL_ALL_CLIENT_ATTRIB_BITS

All of the above.

Other queries

Function: gl-get-error

Returns the value of the error flag. Returned an integer value. Check out the OpenGL documentation for the possible error values.

This function resets the error flag to GL_NO_ERROR.

Function: glu-error-string error-code

Returns a descriptive string for error-code returned by gl-get-error.

Function: gl-get-string name

Returns informative string about name of the GL library. Name can be one of the following.

GL_VENDOR

GL_RENDERER

GL_VERSION

GL_EXTENSIONS

To check a specific version or extension, you can also use the utility procedure gl-version>? etc. See 4.2 GL feature checking.

Function: glu-get-string name

Returns informative string about name of the GLU library. Name can be one of the following.

GLU_VERSION

GLU_EXTENSIONS

Hints

Function: gl-hint target hint

Controls quality of target by hint. Target can be one of the following:

GL_POINT_SMOOTH_HINT

GL_LINE_SMOOTH_HINT

GL_POLYGON_SMOOTH_HINT

GL_FOG_HINT

GL_PERSPECTIVE_CORRECTION_HINT

And hint can be one of the following:

GL_FASTEST

GL_NICEST

GL_DONT_CARE

4.5 GL states for drawing

Function: gl-point-size size

Sets the width in pixels for rendered points. The possible range of size on the running GL implementation can be obtained by passing either GL_ALIASED_POINT_SIZE_RANGE or GL_SMOOTH_POINT_SIZE_RANGE to gl-get-float.

Function: gl-line-width width

Sets the width in pixels for rendered lines. The possible range of width on the running GL implementation can be obtained by passing either GL_ALIASED_LINE_WIDTH_RANGE or GL_SMOOTH_LINE_WIDTH_RANGE to gl-get-float.

Function: gl-line-stipple factor pat

Sets the current stippling pattern for lines. pat must be an exact integer, and its lower 16 bits are used to specify the stipple pattern. Factor is an integer factor to specify how many pixels corresponds to one bit in pat.

You have to enable GL_LINE_STIPPLE to use face culling.

Function: gl-polygon-mode face mode

Specifies the drawing mode for a polygon's front and back faces. Face can be one of the followings:

GL_FRONT_AND_BACK

GL_FRONT

GL_BACK

Mode can be one of the followings:

GL_POINT

GL_LINE

GL_FILL

Function: gl-front-face mode

Controls how OpenGL determine front face of a polygon Mode can be one of the followings:

GL_CCW

Front face is where ordered vertices appear in a counterclockwise orientation (default).

GL_CW

Front face is where ordered vertices appear in a clockwise orientation.

Function: gl-cull-face mode

Indicates which face of polygons should be culled. Mode can be one of the followings:

GL_FRONT

GL_BACK

GL_FRONT_AND_BACK

You have to enable GL_CULL_FACE to use face culling.

Function: gl-polygon-stipple mask

Defines the current stipple pattern for filled polygons. Mask has to be a u8vector of length 128, specifying a 32x32 bitmap pattern. You have to enable GL_POLYGON_STIPPLE to use this feature.

Function: gl-edge-flag flag

Sets the edge flag(s) of vertices. When flag is a GL boolean vector, glEdgeFlagv is called. Otherwise flag is used as a single boolean value for glEdgeFlag.

Function: gl-blend-func sfactor dfactor

Controls how color values in the fragment being processed (the source) are combined with the ones in the framebuffer (the destination).

Possible values for the sfactor and dfactor arguments are as follows.

GL_ZERO

GL_ONE

GL_DST_COLOR

GL_SRC_COLOR

GL_ONE_MINUS_DST_COLOR

GL_ONE_MINUS_SRC_COLOR

GL_SRC_ALPHA

GL_ONE_MINUS_SRC_ALPHA

GL_DST_ALPHA

GL_ONE_MINUS_DST_ALPHA

GL_SRC_ALPHA_SATURATE

GL_CONSTANT_COLOR

GL_ONE_MINUS_CONSTANT_COLOR

GL_CONSTANT_ALPHA

GL_ONE_MINUS_CONSTANT_ALPHA

Function: gl-blend-equation mode

[GL_ARB_imaging] By default, the source and destination colors are added after processed as specified by gl-blend-func. With this extension API you can change the function. Mode can be one of the following values:

GL_FUNC_ADD

GL_FUNC_SUBTRACT

GL_FUNC_REVERSE_SUBTRACT

GL_MIN

GL_MAX

Function: gl-blend-color red green blue alpha

[GL_ARB_imaging] Sets the constant color used in the blending function.

Function: gl-polygon-offset factor units

[GL1.1] Offset the depth value of each fragment. Useful to avoid artifacts when you draw polygon edges over its surfaces, for example.

Function: gl-clip-plane plane equation

Defines a clipping plane. Plane specifies which clipping plane you're defining. Use GL_MAX_CLIP_PLANES to gl-get-integer to obtain the number of clipping planes you can use. You have to enable the specific clipping plane (e.g. (gl-enable GL_CLIP_PLANE0)) to use the clipping plane.

Equation must be an f64vector of size 4, specifying four coefficients of the plane equation, Ax + By + Cz + D = 0.

Function: gl-get-clip-plane plane

Returns the four coefficients of the equation of clipping plane plane, in f64vector.

Function: gl-fog pname param

Sets the parameters and function for the fog effect. Possible values for pname and accepted param for each pname are shown below.

GL_FOG_MODE

Either GL_EXP, GL_EXP2, GL_LINEAR to select the fog factors.

GL_FOG_DENSITY

GL_FOG_START

GL_FO_END

A real number to specify those parametes.

GL_FOG_COLOR

An f32vector of size 4 to specify the color.

4.6 Transformation

Function: gl-matrix-mode mode

Speficies whether the modelview, projection, or texture matrix will be modified. Mode can be one of the followings:

GL_MODELVIEW

GL_PROJECTION

GL_TEXTURE

Function: gl-load-identity

Loads an identity matrix to the current modifiable matrix.

Function: gl-load-matrix mat

Loads the matrix mat to the current modifiable matrix. Mat can be a <matrix4f> instance, or f32 or f64vector of length 16.

Function: gl-mult-matrix mat

Multiplies the matrix mat to the current modifiable matrix. Mat can be a <matrix4f> instance, or f32 or f64vector of length 16.

Function: gl-translate x y z

Multiplies the current matrix by a matrix taht translates an object by (x, y, z). Internally, glTranslated is called.

Function: gl-rotate angle x y z

Multiplies the current matrix by a matrix that rotates an object in a counterclockwise direction about the ray from the origin through the point (x, y, z) by angle degrees. Internally, glRotated is called.

Function: gl-scale x y z

Multiplies the current matrix by a matrix that scales an object by (x, y, z). Internally, glScaled is called.

Function: glu-look-at eyex eyey eyez ctrx ctry ctrz upx upy upz

Defines a viewing matrix and multiplies it to the right of the current matrix.

Function: gl-frustum left right bottom top nearv farv

Creates a matrix for a perspective-view frustum and multiplies the current matrix by it.

Function: glu-perspective fovy aspect znear zfar

Creates a matrix for a symmetrix perspective-view frustum and multiplies the current matrix by it.

Function: gl-ortho left right bottom top nearv farv

Creates a matrix for an orthographic parallel viewing volume nand multiplies the current matrix by it.

Function: glu-ortho-2d left right bottom top

Convenience procedure for 2D drawing; it is the same as gl-ortho except nearv and farv are fixed (along Z axis) to -1.0 and 1.0, respectively.

Function: gl-viewport x y width height

Defines a pixel rectangle in the window into which the final image is mapped.

Function: gl-push-matrix

Function: gl-pop-matrix

Pushes/pops the current matrix.

Macro: gl-push-matrix* expr ...

A convenience macro. Pushes the current matrix, executes exprs, then pop the current matrix.

4.7 Display lists

Function: gl-gen-lists range

Allocates range number of contiguous display list indices. Returns an integer which is the smallest display list index you can use.

Function: gl-new-list list-no mode

Starts a display list construction. Mode may be one of the constants GL_COMPILE or GL_COMPILE_AND_EXECUTE.

Function: gl-end-list

Ends a display list construction.

Function: gl-call-list list-no

Calls a display list.

Function: gl-is-list list-no

Returns #t if list-no is an already used display list number, #f otherwise.

Function: gl-delete-lists list-no-start range

Deletes range display list, beginning from list-no-start.

Function: gl-list-base base

Specifies the offset that's added to the display list indices in gl-call-list.

Function: gl-call-lists size type lists

Function: gl-call-lists size lists

Function: gl-call-lists lists

Executes size display list, whose indices are contained in lists. You can pass a u8, s8, u16, s16, u32, s32 or f32vector, or a string, as lists. If it is a string, each byte consists of the string is interpreted as an unsigned integer specifying a display list. It is useful for the technique to display character strings by creating display lists for each ASCII characters. But be aware that it doesn't work for multibyte characters.

Usually you can use the simplest form (the third form) and Gauche-gl infers the size and type from the passed lists. You can explicitly specify size if you want to use just a beginning portion of lists. An error is signalled if you specify size that is larger than the size of lists.

Specifying type is useful only if lists is a u8vector, and you want to use one of three special types allowed to glCallLists, namely GL_2_BYTES, GL_3_BYTES, and GL_4_BYTES.

4.8 Vertex arrays

Scheme version of APIs doesn't have GLenum type argument in C API, since Gauche-gl can figure out the type by passed vectors.

Scheme API of gl-*-array has offset optional argument, by which you can pass the GL the values beginning from the offset-th element of the passed uniform vector. This isn't in GL C API, since you can just offset the pointer in C.

NOTE: it is caller's responsibility to guarantee the passed vector has enough length. GL doesn't have an interface to specify the boundary, so Gauche can't detect an invalid length vector.

Function: gl-vertex-pointer size vec &optional stride offset

Sets the vertex array. Size specifies the number of scalar values per vertex (2, 3, or 4), and vec provides the actual value in either f32, f64, s32 or s16vector. Stride and offset can be used to tell GL to access vec sparsely.

Function: gl-normal-pointer vec &optional stride offset

Sets the normal array. Vec should be either a f32, f64, s32 or s16vector, where each consecutive triplet specifies a normal vector. Stride and offset can be used to tell GL to access vec sparsely.

Function: gl-color-pointer size vec &optional stride offset

Sets the color array. Size specifies the number of scalar values per color (3 or 4), and vec provides the actual values in either f32, f64, u32, u16, u8, s32, s16, or s8vector. Stride and offset can be used to tell GL to access vec sparsely.

Function: gl-index-pointer vec &optional stride offset

Sets the index array. Vec can be either s32, s16, u8, f32, or f64vector. Stride and offset can be used to tell GL to access vec sparsely.

Function: gl-tex-coord-pointer size vec &optional stride offset

Sets the texture coordinate array. Size specifies the number of scalar values per texture coordinate (1, 2, 3 or 4), and vec provides the actual values in either f32, f64, s32 or s16vector. Stride and offset can be used to tell GL to access vec sparsely.

Function: gl-edge-flag-pointer vec &optional stride offset

Sets the edge flag array. Vec must be a GL boolean vector. Stride and offset can be used to tell GL to access vec sparsely.

Function: gl-array-element ith

Dereference ith vertex information of the currently enabled arrays.

Function: gl-draw-elements mode indices

Issues geometric primitive calls consists of the vertex information of the currently enabled arrays, each of which is specified by indices, which should be either a u8, u16 or u32vector.

Mode is the same as of gl-begin.

Function: gl-draw-range-elements mode start end indices

[GL1.2] Like gl-draw-elements, but limits the range of indices between start and end, inclusive. GL driver may take advantage of the information for better performance.

Function: gl-draw-arrays mode first count

This is more straightforward. Starting from first index, count vertices is wrtten in the drawing mode mode (same as of gl-begin), taken from the current enabled arrays.

Function: gl-interleaved-arrays format vec &optional stride offset

Vec must be a f32vector. It contains various information (e.g. vertex position, color and texture coordinate) interleaved, in the way specified by format.

In Scheme API, we only allow uniform vector as vec, so you can't use the format that mixes float and integer, such as GL_C4UB_V2F.

4.9 Lighting

Function: gl-shade-model mode

Sets the shading model, either GL_SMOOTH or GL_FLAT.

Function: gl-light light pname param

Creates a light specified by light, which is one of GL_LIGHT0, ..., GL_LIGHT7, and sets a characteristics named by pname with the value param.

Possible values as pname and acceptable types of param are as follows.

GL_AMBIENT, GL_DIFFUSE, GL_SPECULAR, GL_POSITION

Accepts an f32 or s32vector of size 4.

GL_SPOT_DIRECTION

Accepts an f32 or s32vector of size 3.

GL_SPOT_EXPONENT, GL_SPOT_CUTOFF, GL_CONSTNAT_ATTENUATION, GL_LINEAR_ATTENUATION, GL_QUADRATIC_ATTENUATION

Accepts a real number (glLightf is used).

Function: gl-get-light light pname

Returns the value of the property pname of the light light. Returned value can be f32vector or a real number.

Function: gl-light-model pname param

Sets the value of the property pname of the lighting model. Possible pname and its allowed param is as follows.

GL_LIGHT_MODEL_AMBIENT

Accepts f32 or s32vector of size 4.

GL_LIGHT_MODEL_LOCAL_VIEWER, GL_LIGHT_MODEL_TWO_SIDE

Accepts any Scheme value, which is interpreted as a boolean value. (That is, you have to pass #f to turn off these properties, and any other value to turn on.

GL_LIGHT_MODEL_COLOR_CONTROL

Accepts an enum value either GL_SINGLE_COLOR or GL_SEPARATE_SPECULAR_COLOR.

Function: gl-matrial face pname param

Sets the current material property. Face may be either GL_FRONT, GL_BACK, or GL_FRONT_AND_BACK. Possible values of pname and acceptable param types are as follows.

GL_AMBIENT, GL_DIFFUSE, GL_AMBIENT_AND_DIFFUSE, GL_SPECULAR, GL_EMISSION

Accepts f32 or s32vector of size 4.

GL_SHININESS

Accepts a single real number (glMatrialf is called).

GL_COLOR_INDEXES

Accepts f32 or s32vector of size 3.

Function: gl-get-material face pname

Returns the current material property of face and pname. The type of returned value may be f32vector, s32vector (only for GL_COLOR_INDEXES), or a real number.

Function: gl-color-material face mode

Makes the material property mode (e.g. GL_AMBIENT etc.) of the face face follow the current color set by gl-color.

4.10 Pixels, bitmaps and images

Pixel operations

Function: gl-bitmap width height xbo ybo xbi ybi bitmap

Draws a bitmap. Width and height gives the dimension of the bitmap. Xbo, ybo, xbi, and ybi specifies the origin and increment of the current raster position. Bitmap is the actual bitmap data, packed in a u8vector.

Function: gl-read-pixels x y width height format type

Reads pixel data from the framebuffer. Returns the pixel data in a uniform vector of the type determined by format and type (check out OpenGL doc to find out the actual data format).

Function: gl-draw-pixels width height format type pixels

Draws a pixel data pixels at the current raster position. Pixels must be a uniform vector compatible to the specified format and type values.

Function: gl-copy-pixels x y width height buffer

Copies pixel data in a rectangle area of the framebuffer, specified by lower-left corner (x, y) and dimensions (width, height). Buffer specifies which buffer is used, and should be one of GL_COLOR, GL_STENCIL or GL_DEPTH.

Function: gl-pixel-store pname param

Sets the pixel stroage models. Check out the OpenGL doc for the possible pname and param values.

Function: gl-pixel-transfer pname param

Sets the pixel transfer modes. Check out the OpenGL doc for the possible pname and param values.

Function: gl-pixel-map map values

Sets the pixel map table map with values, which must be either u16, u32 or f32vecotor. Check out the OpenGL doc for the possible map values.

Function: gl-pixel-zoom xfactor yfactor

Sets the magnification/reduction factors for pixel-write operations.

Function: gl-get-pixel-map map &optional type

Returns the current pixel map table as an uniform vector specified by type, which must be either a class <u32vector> (default), <u16vector>, or <f32vector>.

Function: gl-get-pixel-map! map values

Like gl-get-pixel-map, but instead of allocating a new vector, it stores the result to a uniform vector passed to values. It is a caller's responsibility to ensure values has enough size.

Color tables

Function: gl-color-table target internal-format width format type data

[GL_ARB_imaging] Specifies one of the color table target. Data should be a uniform vector compatible to the format and type parameters.

Function: gl-color-table-parameter target pname param

[GL_ARB_imaging] Sets the color table parameter pname (either GL_COLOR_TABLE_SCALE or GL_COLOR_TABLE_BIAS), of the color table target. Param must be an f32 or s32vector of size 4.

Function: gl-copy-color-table target internal-format x y width

[GL_ARB_imaging] Creates a color table target using framebuffer data. The pixels are read from the current buffer for read (specified by glReadBuffer).

Function: gl-color-sub-table target start count format type data

[GL_ARB_imaging] Replaces a part of color table target, starting start and count entries. Values are given in data as a uniform vector compatible to the format and type arguments.

Function: gl-copy-color-sub-table target start x y width

[GL_ARB_imaging] Replaces a part of color table entries using framebuffer data.

Function: gl-get-color-table! target format type data

[GL_ARB_imaging] Reads the color table target and store it in data, in the format specified by format and type. Data must be a uniform vector compatible to the format and type arguments. The caller must ensure that data has enough size to contain the result.

Convolutions

Function: gl-convolution-filter-2d target internal-format width height format type data

[GL_ARB_imaging] Defines a 2D convolution filter. Target must be GL_CONVOLUTION_2D. Data must be a uniform vector compatible to the format and type arguments, and must have enough size.

Function: gl-copy-convolution-filter-2d target internal-format x y width height

[GL_ARB_imaging] Defines a 2D convolution filter, taking the convolution filter data from the current color buffer to read.

Function: gl-separable-filetr-2d target internal-format width height format type row column

[GL_ARB_imaging] Defines a 2D convolution filter by a product of a 1D row vector and 1D column vector. Target must be GL_SEPARABLE_2D. Both row and column must be a uniform vector, compatible with the format and type arguments, and must have enough size.

Function: gl-convolution-filter-1d target internal-format width format type data

[GL_ARB_imaging] Defines 1D convolution filter. Target must be GL_CONVOLUTION_1D. Data must be a uniform vector compatible to the format and type arguments, and must have enough size.

Function: gl-copy-convolution-filter-1d target internal-format x y width

[GL_ARB_imaging] Defines 1D convolution filter, taking the convolution filter data from the current color buffer to read.

Function: gl-convolution-parameter target pname param

[GL_ARB_imaging] Sets a parameter for a convolution filter target, which can be either GL_CONVOLUTION_2D, GL_SEPARABLE_2D, or GL_CONVOLUTION_1D. Possible values of pname and their acceptable param are as follows.

GL_CONVOLUTION_BORDER_MODE

Either one of the constants: GL_REDUCE, GL_CONSTNAT_BORDER, GL_REPLICATE_BORDER

GL_CONVOLUTION_FILTER_SCALE, GL_CONVOLUTION_FILTER_BIAS

An s32 or f32vector of size 4, specifying color values.

Histogram

Function: gl-histogram target width internal-format sink

[GL_ARB_imaging] Specifies the way the histogram data is stored. Target must be either GL_HISTOGRAM or GL_PROXY_HISTOGRAM. Width is the number of entires of the histogram, and has to be a power of 2. Sink is a boolean value to indicate whether pixels should be discarded or sent down further to the pipeline.

Function: gl-reset-histogram target

[GL_ARB_imaging] Resets the histogram counters. Target must be GL_HISTOGRAM.

Function: gl-get-histogram target reset format type

[GL_ARB_imaging] Returns histogram data in a uniform vector, whose type and size are determined by format and type. A boolean value reset specifies whether the histogram should be reset or not.

Function: gl-get-histogram-parameter target pname

[GL_ARB_imaging] Returns the parameter value of the histogram. Pname can be either one of GL_HISTOGRAM_WIDTH, GL_HISTOGRAM_FORMAT, GL_HISTOGRAM_RED_SIZE, GL_HISTOGRAM_GREEN_SIZE, GL_HISTOGRAM_BLUE_SIZE, GL_HISTOGRAM_ALPHA_SIZE, GL_HISTOGRAM_LUMINANCE_SIZE, or GL_HISTOGRAM_SINK. The returned value is an integer, except the case of GL_HISTOGRAM_SINK, which returns a boolean value.

Minmax

Function: gl-minmax target internal-format sink

[GL_ARB_imaging] Computes the minimum and maximum pixel values for an image. Target must be GL_MINMAX. Sink is a boolean value to indicate whether pixels should be discarded or sent down further to the pipeline.

Function: gl-get-minmax target reset format type

[GL_ARB_imaging] Returns the results of the minmax operation in a uniform vector, whose type and size are determined by the format and type arguments. A boolean value reset specifies whether the histogram should be reset or not.

Function: gl-reset-minmax target

[GL_ARB_imaging] Resets the minmax counter.

Function: gl-get-minmax-parameter target pname

[GL_ARB_imaging] Returns the parameter value of the histogram. Pname can be either GL_MINMAX_SINK (returns a boolean value) or GL_MINMAX_FORMAT (returns an integer).

4.11 Texture mapping

Defining textures

Function: gl-tex-image-1d target level internalformat width border format type texels

Function: gl-tex-image-2d target level internalformat width height border format type texels

Function: gl-tex-image-3d target level internalformat width height depth border format type texels

Defines an 1D, 2D or 3D texture. 3D texture is available only if the GL version is 1.2 or later. The target parameter can be GL_TEXTURE_1D or GL_PROXY_TEXTURE_1D for gl-tex-image-1d, etc. The level parameter can be used for multiresolution textures; if this is a single resolution texture, pass 0.

Width, height, and depth specify the dimensions of the texture. Border can be 0 or 1, specifying the border.

The actual texture data is passed to the texels argument in a uniform vector, which should be compatible with the format and type parameters and match the size calculated by width, height and depth (and possibly the pixel store setting).

Function: gl-copy-tex-image-1d target level internal-format x y width border

Function: gl-copy-tex-image-2d target level internal-format x y width height border

Cerates a 1D or 2D texture from the framebuffer data.

Function: gl-tex-sub-image-1d target level xoffset width format type texels

Function: gl-tex-sub-image-2d target level xoffset yoffset width height format type texels

Function: gl-tex-sub-image-3d target level xoffset yoffset zoffset width height depth format type texels

Replaces a part of the current 1D, 2D or 3D texture image by texels. 3D texture is available only if the GL version is 1.2 or later.

Function: gl-copy-tex-sub-image-1d target level xoffset x y width

Function: gl-copy-tex-sub-image-2d target level xoffset yoffset x y width height

Function: gl-copy-tex-sub-image-3d target level xoffset yoffset zoffset x y width height

Replaces a part of the current 1D, 2D or 3D texture image by the data from the framebuffer. 3D texture is available only if the GL version is 1.2 or later.

Texture parameters

Function: gl-tex-parameter target pname param

Sets parameters for the current texture. Target can be either GL_TEXTURE_1D, GL_TEXTURE_2D or GL_TEXTURE_3D. Possible values for pname, and accepted type of param for each pname, are shown below.

GL_TEXTURE_WRAP_S

GL_TEXTURE_WRAP_T

GL_TEXTURE_WRAP_R

GL_TEXTURE_BASE_LEVEL

GL_TEXTURE_MAX_LEVEL

GL_TEXTURE_MAG_FILTER

GL_TEXTURE_MIN_FILTER

Param must be an integer.

GL_TEXTURE_PRIORITY

GL_TEXTURE_MIN_LOD

GL_TEXTURE_MAX_LOD

Param must be a real number.

GL_TEXTURE_BORDER_COLOR

Param must be an f32vector of size 4, representing a color.

Function: gl-get-tex-parameter target pname

Obtains the parameter of the current texture, set by gl-tex-parameter.

Function: gl-get-tex-level-parameter target level pname

Obtains the parameter of the level level of the current texture specified by target, which can be either GL_TEXTURE_1D, GL_TEXTURE_2D, GL_TEXTURE_3D, GL_PROXY_TEXTURE_1D, GL_PROXY_TEXTURE_2D, or GL_PROXY_TEXTURE_3D.

Possible values for pname is either one of the following constants: GL_TEXTURE_WIDTH, GL_TEXTURE_HEIGHT, GL_TEXTURE_DEPTH, GL_TEXTURE_BORDER, GL_TEXTURE_INTERNAL_FORMAT, GL_TEXTURE_RED_SIZE, GL_TEXTURE_GREEN_SIZE, GL_TEXTURE_BLUE_SIZE, GL_TEXTURE_ALPHA_SIZE, GL_TEXTURE_LUMINANCE_SIZE, or GL_TEXTURE_INTENSITY_SIZE. This procedure returns an integer.

Mipmaps

Function: glu-build-1d-mipmaps target internal-format width format type texels

Function: glu-build-2d-mipmaps target internal-format width height format type texels

Function: glu-build-3d-mipmaps target internal-format width height depth format type texels

Constructs a serids of mipmaps and calls gl-tex-image-*d to load the images. Returns 0 on success, or a GLU error code on failure. Texels is a uniform vector, that must be compatible with format and type arguments, and must have the enough length as specified by width, height and depth parameters.

Function: glu-build-1d-mipmap-levels target internal-format width format type level base max texels

Function: glu-build-2d-mipmap-levels target internal-format width height format type level base max texels

Function: glu-build-3d-mipmap-levels target internal-format width height depth format type level base max texels

Like glu-build-*d-mipmaps, but you can specify the level of texels, and the range of levels to be generated by the base and max parameters. It is used to generate a subset of mipmaps.

Returns 0 on success, or a GLU error code on failure. Texels is a uniform vector, that must be compatible with format and type arguments, and must have the enough length as specified by width, height and depth parameters.

Texture objects

Function: gl-gen-textures size

Returns size new names for texture objects in a u32vector.

Function: gl-is-texture name

Returns #t if an integer name is the name of a texture that has been bound and not deleted yet, #f otherwise.

Function: gl-bind-texture target name

Bind the current texture (specified by target, e.g. GL_TEXTURE_2D) to the integer name. If there's already a texture bound to name, it becomes current. Otherwise a new texture object is created and made current.

Function: gl-delete-textures names

Delets textures. Names must be a u32vector contains integer names of the texture objects to be deleted.

Function: gl-are-textures-resident! names residences

Names must be a u32vector contains integer names of the texture objects, and residences must be a GL boolean vector of the same length as names. If all textures named in names are resident, #t is returned and residences is not modified. Othewise, #f is returned and residences is modified to contain #t if the corresponding texture in names is resident, #f othewise.

Function: gl-prioritize-textures names priorities

Sets the prioridies of texture objects named by names to the corresponding entry of priorities Names must be a u32vectore and priorities must be an f32vector, and the lengths of both vectors must match.

Texture environment and coordinates

Function: gl-tex-env target pname param

Sets the current texturing function. Target must be GL_TEXTURE_ENV. Possible values of pname and accepted param for each value is as follows.

GL_TEXTURE_ENV_MODE

One of GL_DECAL, GL_REPLACE, GL_MODULATE or GL_BLEND.

GL_TEXTURE_ENV_COLOR

f32vector of size 4 to specify the color.

Function: gl-tex-gen coord pname param

Specifies the functions for automatic texture coordinate generation. Coord specifies the coordinates, either one of GL_S, GL_T, GL_R or GL_Q. Possible values of pname and accepted param for each value is as follows.

GL_TEXTURE_GEN_MODE

Either GL_OBJECT_LINEAR, GL_EYE_LINEAR or GL_SPHERE_MAP.

GL_OBJECT_PLANE

GL_EYE_PLANE

An s32, f32 or f64vector of size 4 to specify the plane.

Multitexturing

Function: gl-active-texture-arb texunit

[GL_ARB_multitexture] Selects the texture unit that is currently modified by texturing routines. Texunit is a constant GL_TEXTUREi_ARB, where i is 0 to the maximum number of the supported texture units.

Function: gl-multi-tex-coord-arb texunit coords

Function: gl-multi-tex-coord-arb texunit s &optional t r q

[GL_ARB_multitexture] Specifies the texture coordinate of the texture unit texunit. In the first form, you can pass either an f32, f64, s32, or s16vector of length 1 to 4. In the second form, s, t, r and q must be real numbers.

Function: gl-client-active-texture-arb texunit

Selects the current texture unit for specifying texutre-coordinate data with vertex arrays.

4.12 Framebuffers

Clearing buffers

Function: gl-clear-color r g b a

Sets the current clearing color. Each color value sould be a real number, and is clamped to [0.0,1.0].

Function: gl-clear-index c

Sets the current clearing color (in color index mode). c must be a real number.

Function: gl-clear-depth depth

Sets the current clearing depth value. Depth must be a real number and clamped to [0.0,1.0].

Function: gl-clear-stencil s

Sets the current clearing value of the stencil buffer.

Function: gl-clear-accum r g b a

Sets the current clearing value of accumulation buffer.

Function: gl-clear mask

Clears the specified buffer. Mask is a logical-or of the following constants.

GL_COLOR_BUFFER_BIT

GL_DEPTH_BUFFER_BIT

GL_ACCUM_BUFFER_BIT

GL_STENCIL_BUFFER_BIT

Selecting color buffers

Function: gl-draw-buffer mode

Selects (a) buffer(s) to which the image is rendered. Possible mode values are: GL_FRONT, GL_FRONT_LEFT, GL_FRONT_RIGHT, GL_BACK, GL_BACK_LEFT, GL_BACK_RIGHT, GL_LEFT, GL_RIGHT, GL_AUXi, GL_FRONT_AND_BACK, and GL_NONE.

Function: gl-read-buffer mode

Selects a color buffer as the source for reading pixels. Possible mode values are the same as gl-draw-buffer except GL_FRONT_AND_BACK and GL_NONE.

Masking buffers

Function: gl-index-mask mask

In color index mode, sets the mask of the color-index buffer. Mask is an exact integer.

Function: gl-color-mask r g b a

R, g, b and a are boolean values to specify whether the corresponding color channel should be written to the color buffer or not.

Function: gl-depth-mask flag

Flag is a boolean value specifies whether depth buffer should be written or not.

Function: gl-stencil-mask mask

Sets the mask bit pattern for the stencil buffer. Mask is an exact integer.

Testing and operating on fragments

Function: gl-scissor x y width height

Sets the scissor rectangle. If the scissor test is enabled (use (gl-enable GL_SCISSOR_TEST)), only the pixels that lie inside the rectangle are written.

Function: gl-alpha-func func ref

Sets the reference value and comparison function for the alpha test. Func may be either one of GL_NEVER, GL_ALWAYS, GL_LESS, GL_LEQUAL, GL_EQUAL, GL_GEQUAL, GL_GREATER, or GL_NOTEQUAL. Ref sets the reference value, a real number clamped to be between 0.0 and 1.0.

Function: gl-stencil-func func ref mask

Sets the comparison function, the reference value, and a mask for stencil test. Func specifies the funciton, and its possible value is the same as gl-alpha-func's. Ref is an integer reference value, and mask is an integer specifying bitwise mask. Before the comparison, the reference value and the fragment value are taken bitwise AND by mask.

Function: gl-stencil-op func zfail zpass

Speficies how the stencil buffer should be modified by the result of the stencil test. Each three parameter can take one of the following values independently: GL_KEEP, GL_ZERO, GL_REPLACE, GL_INCR, GL_DECR, or GL_INVERT.

Function: gl-depth-func func

Sets the comparison function for the depth test. Func may be one of the following constant value: GL_NEVER, GL_ALWAYS, GL_LESS, GL_LEQUAL, GL_EQUAL, GL_GEQUAL, GL_GREATER, or GL_NOTEQUAL.

Function: gl-depth-range nearv farv

Defines an encoding for z-coordinates. Nearv and farv define the minimum and maximum values that can be stored in the depth buffer. By default, they're 0.0 and 1.0, respectively.

Function: gl-logic-op opcode

Selects the logical operation to be performed, given an incoming (source) fragment and the pixel currently in the color buffer (destination). Opcode may be one of the following values: GL_CLEAR, GL_COPY, GL_NOOP, GL_SET, GL_COPY_INVERTED, GL_INVERT, GL_AND_REVERSE, GL_OR_REVERSE, GL_AND, GL_OR, GL_NAND, GL_NOR, GL_XOR, GL_EQUIV, GL_AND_INVERTED or GL_OR_INVERTED.

Function: gl-accum op value

Sets the accumulation buffer operation mode. Op may be one of the following values:

GL_ACCUM

Reads each pixel from the current selected buffer to read (by gl-read-buffer), multiplies its values by value, and adds the result into the accumulation buffer.

GL_LOAD

Same as GL_ACCUM but replacing the accumulation buffer by the result of multiplication, instead of adding it.

GL_RETURN

Takes the values from accumulation buffer, multiplies them with value, then write it to the current color buffer to write (by gl-draw-buffer).

GL_ADD

Adds value to each pixel in the accumulation buffer and write it back.

GL_MULT

Multiplies value to each pixel in the accumulation buffer and write it back. The result value is clamped to [-1.0, 1.0].

4.13 Selection and feedback

Function: gl-feedback-buffer type buffer

Function: gl-select-buffer buffer

Function: gl-render-mode mode

Function: gl-pass-through token

Function: gl-init-names

Function: gl-load-name name

Function: gl-push-name name

Function: gl-pop-name

4.14 Projection

Function: glu-pick-matrix x y w h vp

Function: glu-project objx objy objz model-mat proj-mat vp

Function: glu-un-project winx winy winz model-mat proj-mat vp

Function: glu-project! win obj model-mat proj-mat vp

Function: glu-un-project! obj win model-map proj-mat vp

4.15 Quadrics

Class: <glu-quadric>

Function: glu-quadric-draw-style quad style

Constant: GLU_POINT

Constant: GLU_LINE

Constant: GLU_FILL

Constant: GLU_SILHUETTE

Function: glu-quadric-orientation quad orientation

Constant: GLU_OUTSIDE

Constant: GLU_INSIDE

Function: glu-quadric-normals quad normals

Constant: GLU_SMOOTH

Constant: GLU_FLAT

Constant: GLU_NONE

Function: glu-quadric-texture quad texcoords

Function: glu-cylinder quad base-radius top-radius height slices stacks

Function: glu-sphere quad radius slices stacks

Function: glu-disk quad inner-radius outer-radius slices loops

Function: glu-partial-disk quad inner-radius outer-radius slices loops start-angle sweep-angle

4.16 Nurbs

Class: <glu-nurbs>

Function: glu-load-sampling-matrices nurbs model-matrix proj-matrix viewport

Function: glu-nurbs-property nurbs property value

Function: glu-get-nurbs-property nurbs property

Function: glu-begin-curve nurbs

Function: glu-end-curve nurbs

Function: glu-nurbs-curve nurbs knot stride ctlarray order type

Function: glu-begin-surface nurbs

Function: glu-end-surface nurbs

4.17 Polygon tesselation

Class: <glu-tesselator>

4.18 Programmable shaders

Shader objects

Function: gl-create-shader-object-arb type

[GL_ARB_shader_objects] Creates a new shader object and returns its handle. Type can be either GL_VERTEX_SHADER_ARB or GL_FRAGMENT_SHADER_ARB.

Function: gl-shader-source-arb shader strings

[GL_ARB_shader_objects] Sets the source code of the shader, whose handle is shader. You can give the source code as a list of strings to strings. All strings are concatenated internally in the OpenGL driver.

Function: gl-compile-shader-arb shader

[GL_ARB_shader_objects] Compile the source code attached to the shader, whose handle is shader. You can query the result of the compilation by passing GL_OBJECT_COMPILE_STATUS_ARB to gl-get-object-parameter-arb; it returns #t if the compilation succeeded, or #f if failed. The information about the compilation can be obtained by gl-get-info-log-arb.

Function: gl-create-program-object-arb

[GL_ARB_shader_objects] Creates a new program object and returns its handle.

Function: gl-attach-object-arb program shader

[GL_ARB_shader_objects] Attach a shader whose handle is shader to the program whose handle is program.

Function: gl-detach-object-arb program shader

[GL_ARB_shader_objects] Detach a shader from a program.

Function: gl-link-program-arb program

[GL_ARB_shader_objects] Link the program object. The result of linking can be queried by passing GL_OBJECT_LINK_STATUS_ARB to gl-get-object-parameter-arb.

Function: gl-use-program-object-arb program

[GL_ARB_shader_objects] Installs the program to the current rendering state.

Function: gl-delete-object-arb handle

[GL_ARB_shader_objects] Deletes either a shader object or a program object specified by handle.

Function: gl-get-object-parameter-arb object pname

[GL_ARB_shader_objects] Queries the value of pname of the shader or the program specified by object. The following values are accepted as pname: GL_OBJECT_TYPE_ARB, GL_OBJECT_SUBTYPE_ARB, GL_OBJECT_DELETE_STATUS_ARB, GL_OBJECT_COMPILE_STATUS_ARB, GL_OBJECT_LINK_STATUS_ARB, GL_OBJECT_VALIDATE_STATUS_ARB, GL_OBJECT_INFO_LOG_LENGTH_ARB, GL_OBJECT_ATTACHED_OBJECTS_ARB, GL_OBJECT_ACTIVE_ATTRIBUTES_ARB, GL_OBJECT_ACTIVE_ATTRIBUTE_MAX_LENGTH_ARB, GL_OBJECT_ACTIVE_UNIFORMS_ARB, GL_OBJECT_ACTIVE_UNIFORM_MAX_LENGTH_ARB, and GL_OBJECT_SHADER_SOURCE_LENGTH_ARB. The procedure returns an integer value.

Function: gl-get-shader-source-arb shader

[GL_ARB_shader_objects] Returns the shader source code of a shader object shader in a string.

Function: gl-get-info-log-arb handle

[GL_ARB_shader_objects] Returns the information log of an object pointed by handle.

Function: gl-get-handle-arb pname

[GL_ARB_shader_objects] Returns the handle to an object that is used in the current state. The only argument accepted currently as pname is GL_PROGRAM_OBJECT_ARB, which returns the handle to the current program object.

Function: gl-get-attached-objects-arb program

[GL_ARB_shader_objects] Rethrns a vector of GL object handles that are attached to the program.

Function: gl-validate-program-arb program

[GL_ARB_shader_objects] Checks whether the program can execute in the current GL state. The result is stored in program's log.

Specifying vertex attributes

Function: gl-vertex-attrib-arb index values

Function: gl-vertex-attrib-arb index v0 &rest v1 v2 v3

[GL_ARB_vertex_program] Sets the generic vertex attribute specified by index. In the first form, you can pass f32, f64, or s16vector of size 1 to 4, or u8, s8, u16, s32, or u32vector of size 4. In the second form, you can pass 1 to 4 real numbers (they are interpreted as C doubles and glVertexAttrib4dARB is called).

Function: gl-vertex-attrib-4n-arb index values

Function: gl-vertex-attrib-4n-arb index v0 v1 v2 v3

[GL_ARB_vertex_program] These variations can be used to pass normalized values. The first form accepts s8, u8, s16, u16, s32, u32, f32 and f64vector of size 4. The second value takes four integers, whose lower 8bits are taken as unsigned byte and passed to glVertexAttrib4NubARB.

Function: gl-vertex-attrib-pointer-arb index size vec &optional normalized stride offset

[GL_ARB_vertex_program] This is the generic version of vertex arrays. Index names the attribute, size specifies the number of components (1, 2, 3 or 4), and vec is a uniform vector that contains the array of values.

The optional boolean normalized argument tells whether the passed integer values should be mapped to normalized range (#t or taken as are #f, default). The optional stride argument specifies the gap between each set of values within vec. The optional offset argument tells GL to take values beginning from the offset-th element of vec.

Function: gl-enable-vertex-attrib-array-arb index

Function: gl-disable-vertex-attrib-array-arb index

[GL_ARB_vertex_program] Enable or disable a vertex attribute array specified by index.

Function: gl-bind-attrib-location-arb program index name

[GL_ARB_vertex_shader] Associates a user-defined attribute variable in the program object program with an index-th generic vertex attribute. Name is a string of the name of user-defined attribute as appears in the shader program.

Function: gl-get-attrib-location-arb program name

[GL_ARB_vertex_shader] Returns an integer index of the user-defined attribute name in the program. Must be called after program is linked.

Function: gl-get-active-attrib-arb program index

[GL_ARB_vertex_shader] Obtains information about the index-th user-defined attribute in the program. Must be called after program is linked.

It returns three values: the size of the attribute (1, 2, 3 or 4), the type of the attribute (an integer that matches one of the following constants: GL_FLOAT, GL_FLOAT_VEC2_ARB, GL_FLOAT_VEC3_ARB, GL_FLOAT_VEC4_ARB, GL_FLOAT_MAT2_ARB, GL_FLOAT_MAT3_ARB, or GL_FLOAT_MAT4_ARB.), and the name of the attribute.

Specifying uniform variables

Function: gl-get-uniform-location-arb program name

[GL_ARB_shader_objects] Returns an integer location of the uniform variable name of the program program.

Function: gl-uniform1-arb location vec

Function: gl-uniform1-arb location v0

Function: gl-uniform2-arb location vec

Function: gl-uniform2-arb location v0 v1

Function: gl-uniform3-arb location vec

Function: gl-uniform3-arb location v0 v1 v2

Function: gl-uniform4-arb location vec

Function: gl-uniform4-arb location v0 v1 v1 v3

[GL_ARB_shader_objects] Sets a value of the uniform variable specified by location. gl-uniform1-arb sets a single component value (e.g. float) gl-uniform2-arb sets a double component value (e.g. vec2) etc.

The first form of each function takes either an s32vector or f32vector. It can have a size multiple of the number of components to set an array uniform variable (e.g. you can pass an f32vector of size 8 to fill vec2[2]).

The second form just sets the component(s) of a single uniform variable. The arguments v0 to v3 must be real numbers, and coerced to C float (i.e. glUniform*fARB is used).

Function: gl-uniform-matrix2-arb location transpose v

Function: gl-uniform-matrix3-arb location transpose v

Function: gl-uniform-matrix4-arb location transpose v

[GL_ARB_shader_objects] Sets a matrix uniform variable (or an array of matrix uniform variables) specified by location. A boolean flag transpose specifies whether the matrix should be transposed. The v argument must be a f32vector of size multiple of 4, 9, or 16, respectively.

Function: gl-get-active-uniform-arb program index

[GL_ARB_shader_objects] Returns informaton about the index-th uniform variable of program.

Returns three values. The first one is the size, either 1, 2, 3 or 4. The second value is the type, which is an integer that matches one of the following constants: GL_FLOAT, GL_FLOAT_VEC(1|2|3|4)_ARB, GL_INT, GL_INT_VEC(1|2|3|4)_ARB, GL_BOOL, GL_BOOL_VEC(1|2|3|4)_ARB, GL_FLOAT_MAT(2|3|4)_ARB. And the third value is the name of the uniform variable.

Vertex and fragment programs

These APIs are for low-level vertex/fragment pipeline programming.

Function: gl-gen-programs-arb n

[GL_ARB_vertex_program] Generates N names (integers) for the new programs and returns them in an s32vector.

Function: gl-delete-programs-arb programs

[GL_ARB_vertex_program] Deletes programs whose names are specified by an s32vector programs.

Function: gl-is-program-arb prog-id

[GL_ARB_vertex_program] Returns #t if an integer prog-id refers to a valid program.

Function: gl-bind-program-arb target prog-id

[GL_ARB_vertex_program] Binds a program specified by prog-id to a target, which is either GL_VERTEX_PROGRAM_ARB or GL_FRAGMENT_PROGRAM_ARB.

Function: gl-program-string-arb target format text

[GL_ARB_vertex_program] Sets the source code of the program currently bound to the target (GL_VERTEX_PROGRAM_ARB or GL_FRAGMENT_PROGRAM_ARB).

Format must be GL_PROGRAM_FORMAT_ASCII_ARB. Text is a string for the program source.

Function: gl-program-env-parameter-arb target param-id args

Function: gl-program-env-parameter-arb target param-id arg0 arg1 arg2 arg3

Function: gl-program-local-parameter-arb target param-id args

Function: gl-program-local-parameter-arb target param-id arg0 arg1 arg2 arg3

[GL_ARB_vertex_program] Sets the value of the environment and local parameter specified by param-id of the program currently bount to the target. In the first form of each, args must be either f32 or f64vector of size 4 or <vector4f> object.

5. GLUT API

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

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

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

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

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

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

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

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

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

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

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

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

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

7. Simple image handling

Module: gl.simple-image

This module provides a minimal support to handle external image data, so that one can do some experiment in Gauche-gl alone.

The functionality might be extended over time, but this is never intended to be a full featured image library. A separate Gauche extension should be a better place to have it.

Currently, only reading from 8bit SGI image file is supported. It is written in pure Scheme, so don't expect the performance.

Function: read-sgi-image filename

Function: read-sgi-image-from-port port

Reads an image data in SGI format from the named file or the input port, respectively.

Only 8bit-per-channel, direct color mode is supported.

Returns four values: the image's width in pixels, its height in pixels, number of channels (e.g. 1 for grayscale, 3 for RGB, 4 for RGBA), and the image data in u8vector. The pixel data is packed, i.e. there's no padding between each pixel nor each scanline.

Warning: be careful to call this function interactively. The image data vector is usually huge, and you have to wait long for the REPL to display the entire result.