Commit | Line | Data |
---|---|---|
8925f36f AW |
1 | \input texinfo @c -*-texinfo-*- |
2 | @c %**start of header | |
3 | @setfilename figl.info | |
4 | @settitle Figl | |
5 | @c %**end of header | |
6 | ||
7 | @set VERSION 2.0.0 | |
8 | @set UPDATED 1 February 2013 | |
9 | ||
10 | @copying | |
11 | This manual is for Figl (version @value{VERSION}, updated | |
12 | @value{UPDATED}) | |
13 | ||
bf504ca3 | 14 | Copyright @copyright{} 2013 Andy Wingo and others. |
8925f36f AW |
15 | |
16 | @quotation | |
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. | |
21 | ||
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. | |
26 | ||
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/}. | |
30 | @end quotation | |
31 | ||
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. | |
36 | @end copying | |
37 | ||
38 | @dircategory The Algorithmic Language Scheme | |
39 | @direntry | |
ffdebc2e | 40 | * Figl: (figl.info). Guile Scheme interface to the OpenGL API. |
8925f36f AW |
41 | @end direntry |
42 | ||
43 | @titlepage | |
44 | @title Figl | |
45 | @subtitle version @value{VERSION}, updated @value{UPDATED} | |
46 | @author Andy Wingo | |
47 | @author (many others) | |
48 | @page | |
49 | @vskip 0pt plus 1filll | |
50 | @insertcopying | |
51 | @end titlepage | |
52 | ||
53 | @ifnottex | |
54 | @node Top | |
55 | @top Figl | |
56 | ||
8925f36f | 57 | @insertcopying |
29d7cd47 | 58 | |
8925f36f | 59 | @menu |
29d7cd47 AW |
60 | * Introduction:: The what, why, and how of Figl. |
61 | ||
1317e308 | 62 | * API Conventions:: General conventions used by the Figl APIs. |
fb44a6aa | 63 | |
ffdebc2e | 64 | * GL:: A Scheme interface to the OpenGL API. |
29d7cd47 | 65 | * GLU:: The GL Utility library. |
29d7cd47 | 66 | * GLX:: Using OpenGL with the X Window System. |
8f44ee57 AW |
67 | * GLUT:: The GL Utility Toolkit. |
68 | ||
69 | * FAQ:: Figl answers questions. | |
8925f36f | 70 | |
bf504ca3 DH |
71 | Appendices |
72 | ||
73 | * GNU General Public License:: | |
74 | * GNU Lesser General Public License:: | |
75 | ||
76 | Indices | |
77 | ||
8925f36f AW |
78 | * Function Index:: |
79 | @end menu | |
80 | ||
81 | @end ifnottex | |
82 | ||
83 | @iftex | |
84 | @shortcontents | |
85 | @end iftex | |
86 | ||
29d7cd47 AW |
87 | |
88 | @node Introduction | |
89 | @chapter Introduction | |
90 | ||
91 | Figl is the Foreign Interface to GL: an OpenGL binding for Guile. | |
8f44ee57 | 92 | |
ffdebc2e DH |
93 | In addition to the OpenGL API, Figl also provides access to related |
94 | libraries and toolkits such as GLU, GLX, and GLUT. The following | |
95 | chapters discuss the parts of OpenGL and how they are bound by Figl. | |
8f44ee57 AW |
96 | |
97 | But before that, some notes on the Figl binding as a whole. | |
98 | ||
99 | @menu | |
100 | * About Figl:: The structure of the binding. | |
101 | @end menu | |
102 | ||
103 | ||
104 | @node About Figl | |
105 | @section About Figl | |
106 | ||
ffdebc2e DH |
107 | Figl is a @dfn{foreign} interface to the OpenGL API because it uses |
108 | the dynamic @dfn{foreign function interface} provided by Guile 2.0, | |
8f44ee57 AW |
109 | providing access to OpenGL without any C code at all. In fact, much |
110 | of Figl (and this manual) is automatically generated from upstream API | |
29d7cd47 AW |
111 | specifications and documentation. |
112 | ||
8f44ee57 AW |
113 | We have tried to do a very complete job at wrapping OpenGL, and |
114 | additionally have tried to provide a nice Scheme interface as well. | |
115 | Our strategy has been to separate the binding into low-level and | |
116 | high-level pieces. | |
117 | ||
ffdebc2e | 118 | The low-level bindings correspond exactly with the OpenGL specification, |
8f44ee57 AW |
119 | and are well-documented. However, these interfaces are not so nice to |
120 | use from Scheme; output arguments have to be allocated by the caller, | |
121 | and there is only the most basic level of type checking, and no sanity | |
122 | checking at all. For example, you can pass a bytevector of image data | |
123 | to the low-level @code{glTexImage2D} procedure, but no check is made | |
124 | that the dimensions you specify actually correspond to the size of the | |
125 | bytevector. This function could end up reading past the end of the | |
126 | bytevector. Worse things can happen with procedures that write to | |
127 | arrays, like @code{glGetTexImage}. | |
128 | ||
129 | The high-level bindings are currently a work in progress, and are | |
130 | being manually written. They intend to be a complete interface to the | |
ffdebc2e DH |
131 | OpenGL API, without the need to use the low-level bindings. However, |
132 | the low-level bindings will always be available for you to use if | |
133 | needed, and have the advantage that their behavior is better | |
134 | documented and specified by OpenGL itself. | |
8f44ee57 AW |
135 | |
136 | Low-level bindings are accessed by loading the @code{(figl | |
137 | @var{module} low-level)}, for example via: | |
138 | ||
139 | @example | |
140 | (use-modules (figl gl low-level)) | |
141 | @end example | |
142 | ||
143 | The high-level modules are named like @code{(figl @var{module})}, for | |
144 | example @code{(figl gl)}. | |
145 | ||
146 | ||
1317e308 DH |
147 | @node API Conventions |
148 | @chapter API Conventions | |
fb44a6aa | 149 | |
aa1794f4 | 150 | FIXME: A very rough draft. Bindings and text are not fully synced |
fb44a6aa DH |
151 | until more work is done here. |
152 | ||
31e76884 DH |
153 | This chapter documents the general conventions used by Figl's |
154 | low-level and high-level bindings. Any conventions specific to a | |
155 | particular module are documented in the relevent section. | |
fb44a6aa DH |
156 | |
157 | As Figl is in very early stages of development these conventions are | |
158 | subject to change. Feedback is certainly welcome, and nothing is set | |
159 | in stone. | |
160 | ||
161 | @menu | |
162 | * Enumerations:: Using symbolic constants. | |
163 | * Functions:: Naming and behaviour. | |
164 | @c * State:: Accessing and mutating GL* state. | |
165 | @end menu | |
166 | ||
167 | ||
168 | @node Enumerations | |
169 | @section Enumerations | |
170 | ||
171 | The OpenGL API defines many @dfn{symbolic constants}, most of which | |
172 | are collected together as named @dfn{enumerations} or @dfn{bitfields}. | |
173 | Access to these constants in Figl is the same for the low-level | |
174 | bindings and high-level interface. | |
175 | ||
176 | For each OpenGL enumeration type, there is a similarly named Scheme | |
177 | type whose constructor takes an unquoted Scheme symbol naming one of | |
178 | the values. Figl translates the names to a more common Scheme style: | |
179 | ||
180 | @itemize @bullet | |
181 | @item any API prefix is removed (for example, GL_); and | |
182 | @item all names are lowercase, with underscores and CamelCase replaced by hyphens. | |
183 | @end itemize | |
184 | ||
185 | For example, the OpenGL API defines an enumeration with symbolic | |
186 | constants whose C names are GL_POINTS, GL_LINES, GL_TRIANGLES, and so | |
54ead4dd | 187 | on. Collectively they form the PrimitiveType enumeration. To access |
fb44a6aa | 188 | these constants in Figl, apply the constant name to the enumeration |
54ead4dd | 189 | type: @code{(primitive-type triangles)}. |
fb44a6aa DH |
190 | |
191 | Bitfields are similar, though the constructor accepts multiple symbols | |
31e76884 | 192 | and produces an appropriate mask. In the GLUT API there is the |
fb44a6aa DH |
193 | DisplayMode bitfield, with symbolic constants GLUT_RGB, GLUT_INDEX, |
194 | GLUT_SINGLE, and so on. To create a mask representing a | |
195 | double-buffered, rgb display-mode with a depth buffer: | |
196 | @code{(display-mode double rgb depth)}. | |
197 | ||
198 | Enumeration and bitfield values, once constructed, can be compared | |
199 | using @code{eqv?}. For example, to determine if @code{modelview} is | |
200 | the current matrix mode use | |
201 | @code{(eqv? (gl-matrix-mode) (matrix-mode modelview))}. | |
202 | ||
203 | ||
204 | @node Functions | |
205 | @section Functions | |
206 | ||
207 | The low-level bindings currently use names identical to their C API | |
208 | counterparts. | |
209 | ||
210 | High-level bindings adopt names that are closer to natural language, | |
211 | and a more common style for Scheme: | |
212 | ||
213 | @itemize @bullet | |
214 | @item the API prefix is always removed; | |
215 | @item abbreviations are avoided; and | |
216 | @item names are all lowercase with words separated by hyphens. | |
217 | @end itemize | |
218 | ||
219 | Some function names are altered in additional ways, to make clear | |
220 | which object is being operated on. Functions that mutate objects or | |
221 | state will have their name prefixed with @code{set-}, such as | |
31e76884 DH |
222 | @code{set-matrix-mode}. |
223 | ||
224 | FIXME: This choice may be too unnatural for GL users. | |
fb44a6aa DH |
225 | |
226 | Where the C API specifies multiple functions that perform a similar | |
227 | task on varying number and types of arguments, the high-level bindings | |
228 | provide a single function that takes optional arguments, and, where | |
229 | appropriate, using only the most natural type. Consider the group of | |
230 | C API functions including @code{glVertex2f}, @code{glVertex3f}, and so | |
231 | on; the high-level GL interface provides only a single function | |
31e76884 DH |
232 | @code{glVertex} with optional arguments. |
233 | ||
234 | @c FIXME: Not merged yet. | |
235 | @c Packed vector functions (such as @code{glColor3bv}) are combined in | |
236 | @c to a single high-level function with the suffix @code{-v}. Such a | |
237 | @c function will dispatch to the correct low-level binding based on the | |
238 | @c length and type of it's argument. There is no need to provide the | |
239 | @c length and type arguments specifically. For example, | |
240 | @c @code{(color-v #f32(1.0 0.0 0.8 0.5))} will determine that the argument | |
241 | @c is a float vector of length four, and dispatch to the low-level | |
242 | @c @code{glColor4fv}. | |
243 | ||
244 | The high-level interfaces may differ in other ways, and it is | |
fb44a6aa DH |
245 | important to refer to the specific documentation. |
246 | ||
247 | It is generally fine to intermix functions from corresponding | |
248 | low-level and high-level bindings. This can be useful if you know the | |
249 | specific type of data you are working with and want to avoid the | |
250 | overhead of dynamic dispatch at runtime. Any cases where such | |
251 | intermixing causes problems will be noted in the documentation for the | |
252 | high-level bindings. | |
253 | ||
254 | ||
22c0d71c | 255 | @include gl.texi |
8f44ee57 | 256 | |
2668d475 | 257 | @include glu.texi |
8925f36f | 258 | |
f17f286b | 259 | @include glx.texi |
29d7cd47 | 260 | |
f17f286b | 261 | @include glut.texi |
8f44ee57 AW |
262 | |
263 | ||
264 | @node FAQ | |
265 | @chapter FAQ | |
266 | ||
267 | TODO: Write about things readers will want to know (instead of | |
268 | commenting them in the source :) | |
269 | ||
270 | ||
bf504ca3 DH |
271 | @node GNU General Public License |
272 | @appendix GNU General Public License | |
273 | ||
274 | @include gpl.texi | |
275 | ||
276 | @node GNU Lesser General Public License | |
277 | @appendix GNU Lesser General Public License | |
278 | ||
279 | @include lgpl.texi | |
280 | ||
281 | ||
8925f36f AW |
282 | @node Function Index |
283 | @unnumbered Function Index | |
284 | @printindex fn | |
285 | @bye |