doc/figl.texi

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