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.                                :wigs:
 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.  Marking TODO and will work on a draft covering the
 149 conventions I have used/intend to use soon.
 150
 151 ** Maybe drop the "gl-" prefix for high-level bindings.
 152
 153 The names for most gl, glu, etc.  procedures are unique enough to not
 154 conflict with each other, and most Scheme names generally.  Removing
 155 the prefix will make names where an additional prefix is used (such as
 156 "set-") much more natural.
 157
 158 Users with specific namespace concerns can use selective and renaming
 159 imports.
 160
 161 * Documentation
 162
 163 ** Figure out how to incorporate low-level bindings into the
 164    documentation.
 165
 166 Often-times the high-level bindings just duplicate information from the
 167 low-level bindings, but poorly.  To do this, we'd have to make a map of
 168 how to organize the low-level bindings, probably according to their
 169 section in the specification.
 170
 171 ** Mangle enumeration names to link to the enumerator documentation.
 172
 173 ** Give an @anchor{} to each API element so that we can link back and
 174    forth.
 175
 176 * Examples
 177
 178 ** examples/README explaining the layout.
 179
 180 ** OpenGL standards.
 181
 182 Language bindings typically provide ports of the standard examples, to
 183 demonstrate usage patterns and their own unique style.
 184
 185 http://www.sgi.com/products/software/opengl/examples/index.html
 186
 187 Implement at least a few of these, their licencing is permissive
 188 enough and they have been widely ported to Free Software language
 189 bindings already.
 190
 191 ** More interesting demos.
 192
 193 * Meta
 194
 195 ** Mailing list?
 196
 197 ** Web page for documentation?
 198
 199 Both of these point towards hosting on savannah at some point.  Figl
 200 could become a GNU project but it will not have copyright assignment.