This manual is for Figl (version @value{VERSION}, updated
@value{UPDATED})
-Copyright 2013 Andy Wingo and others.
+Copyright @copyright{} 2013 Andy Wingo and others.
@quotation
Figl is free software: you can redistribute and/or modify it and its
@menu
* Introduction:: The what, why, and how of Figl.
+* API Conventions:: General conventions used by the Figl APIs.
+
* GL:: A Scheme interface to OpenGL.
* GLU:: The GL Utility library.
* GLX:: Using OpenGL with the X Window System.
* FAQ:: Figl answers questions.
+Appendices
+
+* GNU General Public License::
+* GNU Lesser General Public License::
+
+Indices
+
* Function Index::
@end menu
example @code{(figl gl)}.
-@c Defines the GL node and chapter.
-@include gl.texi
-
-
-@node GLU
-@chapter GLU
-
-@menu
-* Low-Level GLU:: Primitive interface to ``glu'' functionality.
-@end menu
+@node API Conventions
+@chapter API Conventions
-@node Low-Level GLU
-@section Low-Level GLU
-@include low-level-glu.texi
+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.
-@node GLX
-@chapter GLX
+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.
@menu
-* Low-Level GLX:: Primitive interface to ``glX'' functionality.
-* GLX Enumerations:: GLX enumerated values.
+* Enumerations:: Using symbolic constants.
+* Functions:: Naming and behaviour.
+@c * State:: Accessing and mutating GL* state.
@end menu
-@node Low-Level GLX
-@section Low-Level GLX
-@include low-level-glx.texi
+@node Enumerations
+@section Enumerations
+
+The OpenGL API defines many @dfn{symbolic constants}, most of which
+are collected together as named @dfn{enumerations} or @dfn{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:
+
+@itemize @bullet
+@item any API prefix is removed (for example, GL_); and
+@item all names are lowercase, with underscores and CamelCase replaced by hyphens.
+@end itemize
+
+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: @code{(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:
+@code{(display-mode double rgb depth)}.
+
+Enumeration and bitfield values, once constructed, can be compared
+using @code{eqv?}. For example, to determine if @code{modelview} is
+the current matrix mode use
+@code{(eqv? (gl-matrix-mode) (matrix-mode modelview))}.
+
+
+@node Functions
+@section 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:
+
+@itemize @bullet
+@item the API prefix is always removed;
+@item abbreviations are avoided; and
+@item names are all lowercase with words separated by hyphens.
+@end itemize
+
+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 @code{set-}, such as
+@code{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 @code{glVertex2f}, @code{glVertex3f}, and so
+on; the high-level GL interface provides only a single function
+@code{glVertex} with optional arguments.
+
+@c FIXME: Not merged yet.
+@c Packed vector functions (such as @code{glColor3bv}) are combined in
+@c to a single high-level function with the suffix @code{-v}. Such a
+@c function will dispatch to the correct low-level binding based on the
+@c length and type of it's argument. There is no need to provide the
+@c length and type arguments specifically. For example,
+@c @code{(color-v #f32(1.0 0.0 0.8 0.5))} will determine that the argument
+@c is a float vector of length four, and dispatch to the low-level
+@c @code{glColor4fv}.
+
+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.
-@node GLX Enumerations
-@section GLX Enumerations
-@include low-level-glx-enums.texi
+@include gl.texi
+@include glu.texi
-@node GLUT
-@chapter GLUT
+@include glx.texi
-TODO: Write GLUT documentation.
+@include glut.texi
@node FAQ
commenting them in the source :)
+@node GNU General Public License
+@appendix GNU General Public License
+
+@include gpl.texi
+
+@node GNU Lesser General Public License
+@appendix GNU Lesser General Public License
+
+@include lgpl.texi
+
+
@node Function Index
@unnumbered Function Index
@printindex fn
HCoop / clinton / guile-figl.git / blobdiff