expand TODO

[clinton/guile-figl.git] / TODO

# -*- org -*-

* Completeness

** Complete the high-level GL binding.

*** Bind newer versions.

Would be nice to bind newer versions as well, while keeping the
compatibility profile.

The newer versions are backwards compatible with only rare exceptions
where some function's behaviour (but not prototype) is subtley
redefined.  To support newer versions in a simple way we can export
all bindings and the user effectively chooses which version they use
by their choice of procedures.

Exporting particular profiles is a nice addition to this.

** Complete the high-level GLU binding.

** Complete the high-level GLX binding.

** Complete the high-level GLUT binding.

*** Do not keep alive callback pointers indefinitely.

Perhaps by moving the gc-protect mechanism to the high-level bindings,
and track which callbacks are active on each window and globally.

Users of the low-level bindings can still use the foo-callback-*
helpers, but must assume control of pointer lifetime.  Such an
approach permits great flexibility for alternative high-level
interfaces to reuse the low-level bindings.

** Write an EGL binding.

There is a wip-egl branch with upstream documentation.

* Naming

** Mangle low-level binding names.

Probably we should do this only if this low-level bindings are good
enough.  In practice this means that output arguments should be natively
supported, and they low-level bindings should check errors as
appropriate.

** TODO Document the naming convention.                                :wigs:

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.

** Maybe drop the "gl-" prefix for high-level bindings.

The names for most gl, glu, etc.  procedures are unique enough to not
conflict with each other, and most Scheme names generally.  Removing
the prefix will make names where an additional prefix is used (such as
"set-") much more natural.

Users with specific namespace concerns can use selective and renaming
imports.

* Documentation

** Figure out how to incorporate low-level bindings into the
   documentation.

Often-times the high-level bindings just duplicate information from the
low-level bindings, but poorly.  To do this, we'd have to make a map of
how to organize the low-level bindings, probably according to their
section in the specification.

** Mangle enumeration names to link to the enumerator documentation.

** Give an @anchor{} to each API element so that we can link back and
   forth.

* Examples

** examples/README explaining the layout.

** OpenGL standards.

Language bindings typically provide ports of the standard examples, to
demonstrate usage patterns and their own unique style.

http://www.sgi.com/products/software/opengl/examples/index.html

Implement at least a few of these, their licencing is permissive
enough and they have been widely ported to Free Software language
bindings already.

** More interesting demos.

* Meta

** Mailing list?

** Web page for documentation?

Both of these point towards hosting on savannah at some point.  Figl
could become a GNU project but it will not have copyright assignment.