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-uni