There is a wip-egl branch with upstream documentation.
+** Packed structures.
+
+To facilitate passing data to buffer objects. Rather than dealing
+with bytevectors, offsets, and strides directly, we can use a
+packed-struct. and field pair to compute the arguments for
+vertex-pointer and friends (size, type, stride, and pointer).
+
+Existing work:
+
+- make-structure-descriptor (r7rs-large):
+ http://trac.sacrideo.us/wg/wiki/StructuresCowan
+
+ : (define-structure my-vertex-type
+ : (position 'f32 3 position-ref position-set!)
+ : (normal 'f32 3 normal-ref normal-set!)
+ : (color 'u8 4 color-ref color-set!)
+ : (non-gl-data 'f32 2))
+ : (define foo (list->structure my-vertex-type ...))
+ : ;; (set-vertex-pointer FIELD BV)
+ : (set-vertex-pointer position foo)
+ : (set-color-pointer color foo)
+ : ;; position, normal, etc. are identifiers bound to the required
+ : ;; field specs. by the define-structure expression.
+
+- define-gl-array-format (cl-opengl):
+
+ Specifically maps each component to an OpenGL array type (one of
+ vertex, color, normal, ...). This permits automatically binding an
+ entire structure to the relevent array pointers.
+
+ Additional per-component options include:
+ - named access to sub-components (e.g. vertex x, y, z);
+ - whether values are normalized on assignment.
+
+* Interface
+
+** Implement rest of spec parsing module.
+
+To parse functions (gl.spec, etc.), enums, and typemaps.
+
+** Do not export meta-enumerations (version-2-1, etc.).
+
+These are listed in the “Extensions” definition (enum.spec) and are
+defined only to indicate the version or extension that introduces
+various symbolic constants. In theory, all useful constants that
+appear in version-2-1, for example, also appear in at least one other
+enumeration which is an actual data type as referred to by gl.spec.
+
+They can still be used to provide versioned interfaces and profiles,
+there is just no need to export them as enumerations at run time.
+
+Need to make sure all required symbolic constants will still be
+accessible before removing these.
+
+** Make using enumerations implicit.
+
+Instead of:
+
+: (gl-begin (begin-mode triangles) ...)
+: (gl-matrix-mode) => 123
+
+more like this:
+
+: (gl-begin #:triangles ...)
+: (gl-matrix-mode) => #:modelview
+
+and lists of symbols for bitfields.
+
+Enumeration type checking (i.e. does gl-begin accept #:foo?) can be
+done two ways.
+
+*** Type checking by Guile.
+
+Before this can be done we must parse gl.spec to know which enums to
+apply for each procedure argument. _Probably_ foreign-types can no
+longer be syntax either.
+
+Requires also some manual overriding and mapping as there is some
+inconsistency between gl.spec, gl.tm, and enum.spec. For example,
+gl.spec occasionally refers to an enumeration type that is not listed
+in enum.spec, or is listed under another name.
+
+*** Type checking by GL.
+
+Most GL procedures already check the range of enum and bitfield
+arguments, and flag an invalid-enum error as appropriate. We can rely
+on this and create a single, super-enumeration to convert to and from
+symbols.
+
+This may incur a notable performance hit due to the large number of
+symbolic constants.
+
* Naming
** Mangle low-level binding names.
supported, and they low-level bindings should check errors as
appropriate.
-** TODO Document the naming convention. :wigs:
+** TODO Document the naming convention.
Specifically we should document when a name changes significantly,
like when to use a "set-" prefix and the abbreviation expansions
("accum" -> "accumulation-buffer", "coord" -> "coordinates").
Getting this done early will permit implementing the policy more
-accurately. Marking TODO and will work on a draft covering the
-conventions I have used/intend to use soon.
+accurately.
** Maybe drop the "gl-" prefix for high-level bindings.
@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.
example @code{(figl gl)}.
+@node API Conventions
+@chapter 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 API conventions used by Figl's
+various 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.
+
+@menu
+* Enumerations:: Using symbolic constants.
+* Functions:: Naming and behaviour.
+@c * State:: Accessing and mutating GL* state.
+@end menu
+
+
+@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.
+
+Packaged vector functions (such as @code{glColor3bv}) are combined in
+to a single high-level function with the suffice @code{-v}. Such a
+function will dispatch to the correct low-level binding based on the
+length and type of it's argument. There is no need to provide the
+length and type arguments specifically. For example,
+@code{(color #f32(1.0 0.0 0.8 0.5))} will determine that the argument
+is a float vector of length four, and dispatch to the low-level
+@code{glColor4fv}.
+
+The high-level interfaces often 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.
+
+
@include gl.texi
@include glu.texi
a vertex captures the current state and associates it with the
vertex.
-@defun gl-texture-coordinate s [t=0.0] [r=0.0] [q=1.0]
+@defun gl-texture-coordinates s [t=0.0] [r=0.0] [q=1.0]
Set the current texture coordinate.
@end defun
-@defun gl-multi-texture-coordinate texture s [t=0.0] [r=0.0] [q=1.0]
+@defun gl-multi-texture-coordinates texture s [t=0.0] [r=0.0] [q=1.0]
Set the current texture coordinate for a specific texture unit.
@end defun
(define* (gl-vertex x y #:optional (z 0.0) (w 1.0))
(%glVertex4f x y z w))
-(define* (gl-texture-coordinate s #:optional (t 0.0) (r 0.0) (q 1.0))
+(define* (gl-texture-coordinates s #:optional (t 0.0) (r 0.0) (q 1.0))
(%glTexCoord4f s t r q))
-(define* (gl-multi-texture-coordinate texture s #:optional (t 0.0) (r 0.0) (q 1.0))
+(define* (gl-multi-texture-coordinates texture s #:optional (t 0.0) (r 0.0) (q 1.0))
(%glMultiTexCoord4f texture s t r q))
(define* (gl-color red green blue #:optional (alpha 1.0))
(%glVertexAttrib4f index x y z w))
(export gl-vertex
- gl-texture-coordinate
- gl-multi-texture-coordinate
+ gl-texture-coordinates
+ gl-multi-texture-coordinates
gl-color
gl-vertex-attribute)
HCoop / clinton / guile-figl.git / commitdiff