| 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. |