Commit | Line | Data |
---|---|---|
1a878fcf AW |
1 | # -*- org -*- |
2 | ||
b6b1f58d DH |
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 | ||
1a878fcf AW |
22 | * Completeness |
23 | ||
24 | ** Complete the high-level GL binding. | |
25 | ||
57a309e7 DH |
26 | *** Bind newer versions. |
27 | ||
1a878fcf AW |
28 | Would be nice to bind newer versions as well, while keeping the |
29 | compatibility profile. | |
30 | ||
57a309e7 DH |
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 | ||
1a878fcf AW |
39 | ** Complete the high-level GLU binding. |
40 | ||
41 | ** Complete the high-level GLX binding. | |
42 | ||
43 | ** Complete the high-level GLUT binding. | |
44 | ||
57a309e7 DH |
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 | ||
1a878fcf AW |
55 | ** Write an EGL binding. |
56 | ||
57 | There is a wip-egl branch with upstream documentation. | |
58 | ||
ce3c1d57 DH |
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 | ||
da2e2d6f DH |
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 | ||
1a878fcf AW |
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 | ||
fb44a6aa | 160 | ** TODO Document the naming convention. |
57a309e7 DH |
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 | |
fb44a6aa | 167 | accurately. |
57a309e7 DH |
168 | |
169 | ** Maybe drop the "gl-" prefix for high-level bindings. | |
1a878fcf | 170 | |
57a309e7 DH |
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. | |
1a878fcf AW |
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 | ||
57a309e7 DH |
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 | ||
1a878fcf AW |
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. |