TODO

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