TODO

   1 # -*- org -*-
   2
   3 * Completeness
   4
   5 ** Complete the high-level GL binding.
   6
   7 *** Bind newer versions.
   8
   9 Would be nice to bind newer versions as well, while keeping the
  10 compatibility profile.
  11
  12 The newer versions are backwards compatible with only rare exceptions
  13 where some function's behaviour (but not prototype) is subtley
  14 redefined.  To support newer versions in a simple way we can export
  15 all bindings and the user effectively chooses which version they use
  16 by their choice of procedures.
  17
  18 Exporting particular profiles is a nice addition to this.
  19
  20 ** Complete the high-level GLU binding.
  21
  22 ** Complete the high-level GLX binding.
  23
  24 ** Complete the high-level GLUT binding.
  25
  26 *** Do not keep alive callback pointers indefinitely.
  27
  28 Perhaps by moving the gc-protect mechanism to the high-level bindings,
  29 and track which callbacks are active on each window and globally.
  30
  31 Users of the low-level bindings can still use the foo-callback-*
  32 helpers, but must assume control of pointer lifetime.  Such an
  33 approach permits great flexibility for alternative high-level
  34 interfaces to reuse the low-level bindings.
  35
  36 ** Write an EGL binding.
  37
  38 There is a wip-egl branch with upstream documentation.
  39
  40 ** Packed structures.
  41
  42 To facilitate passing data to buffer objects.  Rather than dealing
  43 with bytevectors, offsets, and strides directly, we can use a
  44 packed-struct. and field pair to compute the arguments for
  45 vertex-pointer and friends (size, type, stride, and pointer).
  46
  47 Existing work:
  48
  49 - make-structure-descriptor (r7rs-large):
  50   http://trac.sacrideo.us/wg/wiki/StructuresCowan
  51
  52   : (define-structure my-vertex-type
  53   :   (position 'f32 3 position-ref position-set!)
  54   :   (normal 'f32 3 normal-ref normal-set!)
  55   :   (color 'u8 4 color-ref color-set!)
  56   :   (non-gl-data 'f32 2))
  57   : (define foo (list->structure my-vertex-type ...))
  58   : ;; (set-vertex-pointer FIELD BV)
  59   : (set-vertex-pointer position foo)
  60   : (set-color-pointer color foo)
  61   : ;; position, normal, etc. are identifiers bound to the required
  62   : ;; field specs. by the define-structure expression.
  63
  64 - define-gl-array-format (cl-opengl):
  65
  66   Specifically maps each component to an OpenGL array type (one of
  67   vertex, color, normal, ...).  This permits automatically binding an
  68   entire structure to the relevent array pointers.
  69
  70   Additional per-component options include:
  71   - named access to sub-components (e.g. vertex x, y, z);
  72   - whether values are normalized on assignment.
  73
  74 * Interface
  75
  76 ** Implement rest of spec parsing module.
  77
  78 To parse functions (gl.spec, etc.), enums, and typemaps.
  79
  80 ** Do not export meta-enumerations (version-2-1, etc.).
  81
  82 These are listed in the “Extensions” definition (enum.spec) and are
  83 defined only to indicate the version or extension that introduces
  84 various symbolic constants.  In theory, all useful constants that
  85 appear in version-2-1, for example, also appear in at least one other
  86 enumeration which is an actual data type as referred to by gl.spec.
  87
  88 They can still be used to provide versioned interfaces and profiles,
  89 there is just no need to export them as enumerations at run time.
  90
  91 Need to make sure all required symbolic constants will still be
  92 accessible before removing these.
  93
  94 ** Make using enumerations implicit.
  95
  96 Instead of:
  97
  98 : (gl-begin (begin-mode triangles) ...)
  99 : (gl-matrix-mode) => 123
 100
 101 more like this:
 102
 103 : (gl-begin #:triangles ...)
 104 : (gl-matrix-mode) => #:modelview
 105
 106 and lists of symbols for bitfields.
 107
 108 Enumeration type checking (i.e. does gl-begin accept #:foo?) can be
 109 done two ways.
 110
 111 *** Type checking by Guile.
 112
 113 Before this can be done we must parse gl.spec to know which enums to
 114 apply for each procedure argument.  _Probably_ foreign-types can no
 115 longer be syntax either.
 116
 117 Requires also some manual overriding and mapping as there is some
 118 inconsistency between gl.spec, gl.tm, and enum.spec.  For example,
 119 gl.spec occasionally refers to an enumeration type that is not listed
 120 in enum.spec, or is listed under another name.
 121
 122 *** Type checking by GL.
 123
 124 Most GL procedures already check the range of enum and bitfield
 125 arguments, and flag an invalid-enum error as appropriate.  We can rely
 126 on this and create a single, super-enumeration to convert to and from
 127 symbols.
 128
 129 This may incur a notable performance hit due to the large number of
 130 symbolic constants.
 131
 132 * Naming
 133
 134 ** Mangle low-level binding names.
 135
 136 Probably we should do this only if this low-level bindings are good
 137 enough.  In practice this means that output arguments should be natively
 138 supported, and they low-level bindings should check errors as
 139 appropriate.
 140
 141 ** TODO Document the naming convention.
 142
 143 Specifically we should document when a name changes significantly,
 144 like when to use a "set-" prefix and the abbreviation expansions
 145 ("accum" -> "accumulation-buffer", "coord" -> "coordinates").
 146
 147 Getting this done early will permit implementing the policy more
 148 accurately.
 149
 150 ** Maybe drop the "gl-" prefix for high-level bindings.
 151
 152 The names for most gl, glu, etc.  procedures are unique enough to not
 153 conflict with each other, and most Scheme names generally.  Removing
 154 the prefix will make names where an additional prefix is used (such as
 155 "set-") much more natural.
 156
 157 Users with specific namespace concerns can use selective and renaming
 158 imports.
 159
 160 * Documentation
 161
 162 ** Figure out how to incorporate low-level bindings into the
 163    documentation.
 164
 165 Often-times the high-level bindings just duplicate information from the
 166 low-level bindings, but poorly.  To do this, we'd have to make a map of
 167 how to organize the low-level bindings, probably according to their
 168 section in the specification.
 169
 170 ** Mangle enumeration names to link to the enumerator documentation.
 171
 172 ** Give an @anchor{} to each API element so that we can link back and
 173    forth.
 174
 175 * Examples
 176
 177 ** examples/README explaining the layout.
 178
 179 ** OpenGL standards.
 180
 181 Language bindings typically provide ports of the standard examples, to
 182 demonstrate usage patterns and their own unique style.
 183
 184 http://www.sgi.com/products/software/opengl/examples/index.html
 185
 186 Implement at least a few of these, their licencing is permissive
 187 enough and they have been widely ported to Free Software language
 188 bindings already.
 189
 190 ** More interesting demos.
 191
 192 * Meta
 193
 194 ** Mailing list?
 195
 196 ** Web page for documentation?
 197
 198 Both of these point towards hosting on savannah at some point.  Figl
 199 could become a GNU project but it will not have copyright assignment.