1 \input texinfo @c -*-texinfo-*-
8 @set UPDATED 1 February 2013
11 This manual is for Figl (version @value{VERSION}, updated
14 Copyright @copyright{} 2013 Andy Wingo and others.
17 Figl is free software: you can redistribute and/or modify it and its
18 documentation under the terms of the GNU Lesser General Public License
19 as published by the Free Software Foundation, either version 3 of the
20 License, or (at your option) any later version.
22 Figl is distributed in the hope that it will be useful, but WITHOUT
23 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
24 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General
25 Public License for more details.
27 You should have received a copy of the GNU Lesser General Public
28 License along with this program. If not, see
29 @uref{http://www.gnu.org/licenses/}.
32 Portions of this document were generated from the upstream OpenGL
33 documentation. The work as a whole is redistributable under the
34 license above. Sections containing generated documentation are
35 prefixed with a specific copyright header.
38 @dircategory The Algorithmic Language Scheme
40 * Figl: (figl.info). An OpenGL interface for Guile.
45 @subtitle version @value{VERSION}, updated @value{UPDATED}
49 @vskip 0pt plus 1filll
60 * Introduction:: The what, why, and how of Figl.
62 * API Conventions:: General conventions used by the Figl APIs.
64 * GL:: A Scheme interface to OpenGL.
65 * GLU:: The GL Utility library.
66 * GLX:: Using OpenGL with the X Window System.
67 * GLUT:: The GL Utility Toolkit.
69 * FAQ:: Figl answers questions.
73 * GNU General Public License::
74 * GNU Lesser General Public License::
91 Figl is the Foreign Interface to GL: an OpenGL binding for Guile.
93 OpenGL is a family of APIs and layers. The following chapters discuss
94 the parts of OpenGL and how they are bound by Figl.
96 But before that, some notes on the Figl binding as a whole.
99 * About Figl:: The structure of the binding.
106 Figl is a @dfn{foreign} interface to OpenGL because it uses the
107 dynamic @dfn{foreign function interface} provided by Guile 2.0,
108 providing access to OpenGL without any C code at all. In fact, much
109 of Figl (and this manual) is automatically generated from upstream API
110 specifications and documentation.
112 We have tried to do a very complete job at wrapping OpenGL, and
113 additionally have tried to provide a nice Scheme interface as well.
114 Our strategy has been to separate the binding into low-level and
117 The low-level bindings correspond exactly with the GL specification,
118 and are well-documented. However, these interfaces are not so nice to
119 use from Scheme; output arguments have to be allocated by the caller,
120 and there is only the most basic level of type checking, and no sanity
121 checking at all. For example, you can pass a bytevector of image data
122 to the low-level @code{glTexImage2D} procedure, but no check is made
123 that the dimensions you specify actually correspond to the size of the
124 bytevector. This function could end up reading past the end of the
125 bytevector. Worse things can happen with procedures that write to
126 arrays, like @code{glGetTexImage}.
128 The high-level bindings are currently a work in progress, and are
129 being manually written. They intend to be a complete interface to the
130 GL, without the need to use the low-level bindings. However, the
131 low-level bindings will always be available for you to use if needed,
132 and have the advantage that their behavior is better documented and
133 specified by OpenGL itself.
135 Low-level bindings are accessed by loading the @code{(figl
136 @var{module} low-level)}, for example via:
139 (use-modules (figl gl low-level))
142 The high-level modules are named like @code{(figl @var{module})}, for
143 example @code{(figl gl)}.
146 @node API Conventions
147 @chapter API Conventions
149 FIXME: A very rough draft. Bindings and text are not fully synced
150 until more work is done here.
152 This chapter documents the general conventions used by Figl's
153 low-level and high-level bindings. Any conventions specific to a
154 particular module are documented in the relevent section.
156 As Figl is in very early stages of development these conventions are
157 subject to change. Feedback is certainly welcome, and nothing is set
161 * Enumerations:: Using symbolic constants.
162 * Functions:: Naming and behaviour.
163 @c * State:: Accessing and mutating GL* state.
168 @section Enumerations
170 The OpenGL API defines many @dfn{symbolic constants}, most of which
171 are collected together as named @dfn{enumerations} or @dfn{bitfields}.
172 Access to these constants in Figl is the same for the low-level
173 bindings and high-level interface.
175 For each OpenGL enumeration type, there is a similarly named Scheme
176 type whose constructor takes an unquoted Scheme symbol naming one of
177 the values. Figl translates the names to a more common Scheme style:
180 @item any API prefix is removed (for example, GL_); and
181 @item all names are lowercase, with underscores and CamelCase replaced by hyphens.
184 For example, the OpenGL API defines an enumeration with symbolic
185 constants whose C names are GL_POINTS, GL_LINES, GL_TRIANGLES, and so
186 on. Collectively they form the BeginMode enumeration type. To access
187 these constants in Figl, apply the constant name to the enumeration
188 type: @code{(begin-mode triangles)}.
190 Bitfields are similar, though the constructor accepts multiple symbols
191 and produces an appropriate mask. In the GLUT API there is the
192 DisplayMode bitfield, with symbolic constants GLUT_RGB, GLUT_INDEX,
193 GLUT_SINGLE, and so on. To create a mask representing a
194 double-buffered, rgb display-mode with a depth buffer:
195 @code{(display-mode double rgb depth)}.
197 Enumeration and bitfield values, once constructed, can be compared
198 using @code{eqv?}. For example, to determine if @code{modelview} is
199 the current matrix mode use
200 @code{(eqv? (gl-matrix-mode) (matrix-mode modelview))}.
206 The low-level bindings currently use names identical to their C API
209 High-level bindings adopt names that are closer to natural language,
210 and a more common style for Scheme:
213 @item the API prefix is always removed;
214 @item abbreviations are avoided; and
215 @item names are all lowercase with words separated by hyphens.
218 Some function names are altered in additional ways, to make clear
219 which object is being operated on. Functions that mutate objects or
220 state will have their name prefixed with @code{set-}, such as
221 @code{set-matrix-mode}.
223 FIXME: This choice may be too unnatural for GL users.
225 Where the C API specifies multiple functions that perform a similar
226 task on varying number and types of arguments, the high-level bindings
227 provide a single function that takes optional arguments, and, where
228 appropriate, using only the most natural type. Consider the group of
229 C API functions including @code{glVertex2f}, @code{glVertex3f}, and so
230 on; the high-level GL interface provides only a single function
231 @code{glVertex} with optional arguments.
233 @c FIXME: Not merged yet.
234 @c Packed vector functions (such as @code{glColor3bv}) are combined in
235 @c to a single high-level function with the suffix @code{-v}. Such a
236 @c function will dispatch to the correct low-level binding based on the
237 @c length and type of it's argument. There is no need to provide the
238 @c length and type arguments specifically. For example,
239 @c @code{(color-v #f32(1.0 0.0 0.8 0.5))} will determine that the argument
240 @c is a float vector of length four, and dispatch to the low-level
241 @c @code{glColor4fv}.
243 The high-level interfaces may differ in other ways, and it is
244 important to refer to the specific documentation.
246 It is generally fine to intermix functions from corresponding
247 low-level and high-level bindings. This can be useful if you know the
248 specific type of data you are working with and want to avoid the
249 overhead of dynamic dispatch at runtime. Any cases where such
250 intermixing causes problems will be noted in the documentation for the
266 TODO: Write about things readers will want to know (instead of
267 commenting them in the source :)
270 @node GNU General Public License
271 @appendix GNU General Public License
275 @node GNU Lesser General Public License
276 @appendix GNU Lesser General Public License
282 @unnumbered Function Index