Figl
****

This manual is for Figl (version 2.0.0, updated 1 February 2013)

Copyright © 2013 Andy Wingo and others.

     Figl is free software: you can redistribute and/or modify it and its documentation under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

     Figl is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.

     You should have received a copy of the GNU Lesser General Public License along with this program.  If not, see http://www.gnu.org/licenses/.

Portions of this document were generated from the upstream OpenGL documentation.  The work as a whole is redistributable under the license above.  Sections containing generated documentation are prefixed with a specific copyright header.

Introduction
************

Figl is the Foreign Interface to GL: an OpenGL binding for Guile.

In addition to the OpenGL API, Figl also provides access to related libraries and toolkits such as GLU, GLX, and GLUT.  The following chapters discuss the parts of OpenGL and how they are bound by Figl.

But before that, some notes on the Figl binding as a whole.

About Figl
==========

Figl is a foreign interface to the OpenGL API because it uses the dynamic foreign function interface provided by Guile 2.0, providing access to OpenGL without any C code at all.  In fact, much of Figl (and this manual) is automatically generated from upstream API specifications and documentation.

We have tried to do a very complete job at wrapping OpenGL, and additionally have tried to provide a nice Scheme interface as well. Our strategy has been to separate the binding into low-level and high-level pieces.

The low-level bindings correspond exactly with the OpenGL specification, and are well-documented.  However, these interfaces are not so nice to use from Scheme; output arguments have to be allocated by the caller, and there is only the most basic level of type checking, and no sanity checking at all.  For example, you can pass a bytevector of image data to the low-level glTexImage2D procedure, but no check is made that the dimensions you specify actually correspond to the size of the bytevector.  This function could end up reading past the end of the bytevector.  Worse things can happen with procedures that write to arrays, like glGetTexImage.

The high-level bindings are currently a work in progress, and are being manually written.  They intend to be a complete interface to the OpenGL API, without the need to use the low-level bindings.  However, the low-level bindings will always be available for you to use if needed, and have the advantage that their behavior is better documented and specified by OpenGL itself.

Low-level bindings are accessed by loading the (figl MODULE low-level), for example via:

     (use-modules (figl gl low-level))

The high-level modules are named like (figl MODULE), for example (figl gl).

API Conventions
***************

FIXME: A very rough draft.  Bindings and text are not fully synced until more work is done here.

This chapter documents the general conventions used by Figl's low-level and high-level bindings.  Any conventions specific to a particular module are documented in the relevent section.

As Figl is in very early stages of development these conventions are subject to change.  Feedback is certainly welcome, and nothing is set in stone.

Enumerations
============

The OpenGL API defines many symbolic constants, most of which are collected together as named enumerations or bitfields. Access to these constants in Figl is the same for the low-level bindings and high-level interface.

For each OpenGL enumeration type, there is a similarly named Scheme type whose constructor takes an unquoted Scheme symbol naming one of the values.  Figl translates the names to a more common Scheme style:

  * any API prefix is removed (for example, GL_); and

  * all names are lowercase, with underscores and CamelCase replaced by hyphens.

For example, the OpenGL API defines an enumeration with symbolic constants whose C names are GL_POINTS, GL_LINES, GL_TRIANGLES, and so on.  Collectively they form the BeginMode enumeration type.  To access these constants in Figl, apply the constant name to the enumeration type: (begin-mode triangles).

Bitfields are similar, though the constructor accepts multiple symbols and produces an appropriate mask.  In the GLUT API there is the DisplayMode bitfield, with symbolic constants GLUT_RGB, GLUT_INDEX, GLUT_SINGLE, and so on.  To create a mask representing a double-buffered, rgb display-mode with a depth buffer: (display-mode double rgb depth).

Enumeration and bitfield values, once constructed, can be compared using eqv?.  For example, to determine if modelview is the current matrix mode use (eqv? (gl-matrix-mode) (matrix-mode modelview)).

Functions
=========

The low-level bindings currently use names identical to their C API counterparts.

High-level bindings adopt names that are closer to natural language, and a more common style for Scheme:

  * the API prefix is always removed;

  * abbreviations are avoided; and

  * names are all lowercase with words separated by hyphens.

Some function names are altered in additional ways, to make clear which object is being operated on.  Functions that mutate objects or state will have their name prefixed with set-, such as set-matrix-mode.

FIXME: This choice may be too unnatural for GL users.

Where the C API specifies multiple functions that perform a similar task on varying number and types of arguments, the high-level bindings provide a single function that takes optional arguments, and, where appropriate, using only the most natural type.  Consider the group of C API functions including glVertex2f, glVertex3f, and so on; the high-level GL interface provides only a single function glVertex with optional arguments.

The high-level interfaces may differ in other ways, and it is important to refer to the specific documentation.

It is generally fine to intermix functions from corresponding low-level and high-level bindings.  This can be useful if you know the specific type of data you are working with and want to avoid the overhead of dynamic dispatch at runtime.  Any cases where such intermixing causes problems will be noted in the documentation for the high-level bindings.

     [file gl.texi not included]

     [file glu.texi not included]

     [file glx.texi not included]

     [file glut.texi not included]

FAQ
***

TODO: Write about things readers will want to know (instead of commenting them in the source :)

GNU General Public License
**************************

     [file gpl.texi not included]

GNU Lesser General Public License
*********************************

     [file lgpl.texi not included]