source: project/wiki/eggref/4/opengl-glew @ 30953

Last change on this file since 30953 was 30953, checked in by acharlton, 6 years ago

Update to 0.4.4

File size: 18.2 KB
Line 
1== opengl-glew
2[[toc:]]
3Bindings to OpenGL with GLEW extension loading.
4
5Chicken's other [[http://wiki.call-cc.org/eggref/4/opengl|opengl]] bindings are based on the old fixed function pipeline OpenGL. These bindings generated by [[http://wiki.call-cc.org/eggref/4/bind|bind]] with the OpenGL [[http://www.opengl.org/registry/api/GL/glcorearb.h|core header file]]. Additionally, bindings to [[http://glew.sourceforge.net/|GLEW]] are provided for extension management.
6
7The opengl-glew egg provides three modules, an eponymous module that provides the main OpenGl and GLEW functionality, {{gl-math}} which provides functions for working with matrices (similar to those that are found in GLU), and {{gl-utils}} which provides various high-level functions.
8
9
10=== Requirements
11* make
12* bind
13* z3 (gl-utils)
14* matchable (gl-utils and a compile-time requirement for gl-math)
15* miscmacros (gl-utils)
16* srfi-42 (gl-utils
17
18
19=== Documentation
20All functions and constants from the OpenGL [[http://www.opengl.org/registry/api/GL/glcorearb.h|core header file]] are exported. Scheme style names are provided (underscores and camelCase replaced with hyphens), the {{gl}} prefix is removed from names, {{is}} functions are given question marks, and constants are bookended by {{+}}s (e.g. {{tex-image2d}}, {{enabled?}}, {{+arb-viewport-array+}}).
21
22Functions whose C counterparts accept or return {{GLboolean}} accept or return a Scheme boolean value. ''Do not'' pass {{+true+}} or {{+false+}} to these functions.
23
24
25==== GLEW functions
26<procedure> (init)</procedure>
27
28Required to initialize GLEW/OpenGL. An OpenGL context must be created before this is called.
29
30<procedure> (supported? EXTENSION-NAME)</procedure>
31
32Query whether the OpenGL extension, given as a string, is supported.
33
34
35==== GL helper functions
36The functions in this section are part of the opengl-glew module, rather than gl-utils because they either provide a direct interface to an OpenGL function in a more Scheme-like fashion, or they simplify fundamental operations that rarely must be performed differently.
37
38<procedure> (make-shader TYPE SOURCE)</procedure>
39
40Creates and compiles a shader object given the shader's type (e.g. {{+vertex-shader+}}, {{+geometry-shader+}}, {{+fragment-shader}}), and a string containing the GLSL source. Returns an integer representing the ID of the shader.
41
42<procedure> (make-program SHADER-LIST [PROGRAM-ID])</procedure>
43
44Creates and links a program object, given a list of shader objects (i.e. the integers returned by {{make-shader}}. Returns an integer representing the ID of the program.
45
46Accepts an optional {{PROGRAM-ID}} argument. If given, {{make-program}} will use this ID rather than generating a new one.
47
48<procedure> (gen-buffer)</procedure>
49<procedure> (gen-framebuffer)</procedure>
50<procedure> (gen-program-pipeline)</procedure>
51<procedure> (gen-query)</procedure>
52<procedure> (gen-renderbuffer)</procedure>
53<procedure> (gen-sampler)</procedure>
54<procedure> (gen-texture)</procedure>
55<procedure> (gen-transform-feedback)</procedure>
56<procedure> (gen-vertex-array)</procedure>
57
58Analogous to their pluralized counterparts, but only generates and returns one (integer) object.
59
60<procedure> (delete-buffer BUFFER)</procedure>
61<procedure> (delete-framebuffer FRAMEBUFFER)</procedure>
62<procedure> (delete-program-pipeline PROGRAM-PIPELINE)</procedure>
63<procedure> (delete-query QUERY)</procedure>
64<procedure> (delete-renderbuffer RENDERBUFFER)</procedure>
65<procedure> (delete-sampler SAMPLER)</procedure>
66<procedure> (delete-texture TEXTURE)</procedure>
67<procedure> (delete-transform-feedback TRANSFORM-FEEDBACK)</procedure>
68<procedure> (delete-vertex-array VERTEX-ARRAY)</procedure>
69
70Analogous to their pluralized counterparts, but only accepts and deletes one (integer) object.
71
72<procedure> (check-error)</procedure>
73
74Performs {{get-error}} ({{glGetError}}) and prints the error type when an error is returned.
75
76
77==== gl-math
78gl-math provides a number of functions for working with 4x4 matrices (plus a handful of others). The functionality is similar to what can be found in the [[http://wiki.call-cc.org/eggref/4/glm|glm egg]], but with some notable differences:
79
80* Matrix functions only operate on 4x4 matrices
81* Matrix functions can accept either f32vectors or pointers
82* No container is used to represent matrices
83
84Additionally, gl-math is one fifth the compiled size of glm, has a more straight-forward code-base, and complete documentation.
85
86gl-math expects matrices to be f32vectors or pointers. f32vectors must be 16 elements long. The memory pointed to should likewise be an array of 16 floats. If a function accepts more than one matrix, all matrices must be of the same type.
87
88gl-math operates on matrices in a column-major fashion in correspondence with OpenGL (e.g. translation components are at indices 12, 13, and 14).
89
90<procedure> (print-mat4 MATRIX)</procedure>
91
92Prints the given {{MATRIX}} to {{(current-output-port)}}.
93
94<procedure> (m* A B #!optional RESULT)</procedure>
95
96Multiply matrix {{A}} by matrix {{B}}. If the matrix {{RESULT}} is given, it will be modified to contain the results of the multiplication. If {{RESULT}} is not provided, {{A}} and {{B}} must be f32vectors and the returned value will be an f32vector.
97
98<procedure> (mat4-identity #!optional RESULT)</procedure>
99
100Return an identity matrix. If {{RESULT}} is not provided, the returned value will be an f32vector.
101
102<procedure> (translate X Y Z MATRIX)</procedure>
103
104Translate {{MATRIX}} by {{X}}, {{Y}}, and {{Z}}.
105
106<procedure> (rotate-x ANGLE MATRIX)</procedure>
107
108Rotate {{MATRIX}} around the x-axis by {{ANGLE}} radians.
109
110<procedure> (rotate-y ANGLE MATRIX)</procedure>
111
112Rotate {{MATRIX}} around the y-axis by {{ANGLE}} radians.
113
114<procedure> (rotate-z ANGLE MATRIX)</procedure>
115
116Rotate {{MATRIX}} around the z-axis by {{ANGLE}} radians.
117
118<procedure> (rotate X Y Z ANGLE MATRIX)</procedure>
119
120Rotate {{MATRIX}} around the vector given by {{X}}, {{Y}}, and {{Z}} by {{ANGLE}} radians.
121
122<procedure> (scale-2d SCALE-X SCALE-Y MATRIX)</procedure>
123
124Scale the x and y axis of {{MATRIX}} by {{SCALE-X}} and {{SCALE-Y}}.
125
126<procedure> (scale-3d SCALE-X SCALE-Y SCALE-Z MATRIX)</procedure>
127
128Scale the x, y, and z axis of {{MATRIX}} by {{SCALE-X}}, {{SCALE-Y}}, and {{SCALE-Z}}.
129
130<procedure> (scale SCALE MATRIX)</procedure>
131
132Scale the x, y, and z axis of {{MATRIX}} by {{SCALE}}.
133
134<procedure> (flip-x MATRIX)</procedure>
135
136Flip (mirror) {{MATRIX}} along the x-axis.
137
138<procedure> (flip-y MATRIX)</procedure>
139
140Flip (mirror) {{MATRIX}} along the y-axis.
141
142<procedure> (flip-z MATRIX)</procedure>
143
144Flip (mirror) {{MATRIX}} along the z-axis.
145
146<procedure> (translate-scale X Y Z SCALE #!optional RESULT)</procedure>
147
148Efficiently create a matrix translated by {{X}}, {{Y}}, and {{Z}} then scaled by {{SCALE}}. If the matrix {{RESULT}} is given, it will be modified to contain the result. If {{RESULT}} is not provided, the returned value will be an f32vector.
149
150<procedure> (translate-rotate-scale-2d X Y Z ANGLE SCALE #!optional RESULT)</procedure>
151
152Efficiently create a matrix translated by {{X}}, {{Y}}, and {{Z}}, rotated around the z-axis by {{ANGLE}} radians, then scaled by {{SCALE}}. If the matrix {{RESULT}} is given, it will be modified to contain the result. If {{RESULT}} is not provided, the returned value will be an f32vector.
153
154<procedure> (translate-rotate-scale X Y Z RX RY RZ ANGLE SCALE #!optional RESULT)</procedure>
155
156Efficiently create a matrix translated by {{X}}, {{Y}}, and {{Z}}, rotated {{ANGLE}} radians around the axis defined by {{(RX, RY, RZ)}}, then scaled by {{SCALE}}. If the matrix {{RESULT}} is given, it will be modified to contain the result. If {{RESULT}} is not provided, the returned value will be an f32vector.
157
158<procedure> (transpose MATRIX #!optional RESULT)</procedure>
159
160Transpose {{MATRIX}}. If the matrix {{RESULT}} is given, it will be modified to contain the result. If {{RESULT}} is not provided, the returned value will be an f32vector.
161
162<procedure> (inverse MATRIX #!optional RESULT)</procedure>
163
164Invert {{MATRIX}}. If the matrix {{RESULT}} is given, it will be modified to contain the result. If {{RESULT}} is not provided, the returned value will be an f32vector.
165
166<procedure> (ortho WIDTH HEIGHT NEAR FAR #!optional RESULT)</procedure>
167
168Create an orthographic projection matrix. If the matrix {{RESULT}} is given, it will be modified to contain the result. If {{RESULT}} is not provided, the returned value will be an f32vector.
169
170<procedure> (perspective WIDTH HEIGHT NEAR FAR ANGLE #!optional RESULT)</procedure>
171
172Create an perspective projection matrix. If the matrix {{RESULT}} is given, it will be modified to contain the result. If {{RESULT}} is not provided, the returned value will be an f32vector.
173
174<procedure> (frustum LEFT RIGHT BOTTOM TOP NEAR FAR #!optional RESULT)</procedure>
175
176Create a view-frustum matrix. If the matrix {{RESULT}} is given, it will be modified to contain the result. If {{RESULT}} is not provided, the returned value will be an f32vector.
177
178<procedure> (look-at EYE-X EYE-Y EYE-Z X Y Z UP-X UP-Y UP-Z #!optional RESULT)</procedure>
179
180Create a “look-at” style camera matrix. The camera is positioned at {{(EYE-X, EYE-Y, EYE-Z)}}, pointing towards {{(X, Y, Z)}}. {{(UP-X, UP-Y, UP-Z)}} defines the camera’s up vector. If the matrix {{RESULT}} is given, it will be modified to contain the result. If {{RESULT}} is not provided, the returned value will be an f32vector.
181
182<procedure> (camera-inverse CAMERA #!optional RESULT)</procedure>
183
184Invert {{CAMERA}} in an efficient fashion. This allows the camera to be constructed in an intuitive fashion by translating and rotating before inverting in order to position the scene properly. This function is far faster than the general {{inverse}} function, but the matrix {{CAMERA}} must only be a matrix representing a translation and a rotation (no scaling). If the matrix {{RESULT}} is given, it will be modified to contain the result. If {{RESULT}} is not provided, the returned value will be an f32vector.
185
186<procedure> (cross-product AX AY AZ BX BY BZ)</procedure>
187
188Return the result of the cross product between the vectors {{(AX, AY, AZ)}} and {{(BX, BY, BZ)}}. The resulting vector is returned as three values.
189
190<procedure> (dot-product AX AY AZ BX BY BZ)</procedure>
191
192Return the result of the dot product between the vectors {{(AX, AY, AZ)}} and {{(BX, BY, BZ)}}.
193
194<procedure> (normalize X Y Z)</procedure>
195
196Return the normalized vector {{(X, Y, Z)}}. The resulting vector is returned as three values.
197
198<procedure> (degrees->radians ANGLE)</procedure>
199
200Converts {{ANGLE}} from degrees to radians.
201
202<procedure> (radians->degrees ANGLE)</procedure>
203
204Converts {{ANGLE}} from radians to degrees.
205
206
207==== gl-utils
208gl-utils provides functions for creating VAOs, and loading PLY files.
209
210<procedure> (make-vao VERTEX-DATA INDEX-DATA ATTRIBUTES #!optional USAGE)</procedure>
211
212{{make-vao}} generalizes the typically repetitious code used to initialize vertex attribute objects. It deals with the case of having packed vertex data ({{VERTEX-DATA}}) and a vector of indices ({{INDEX-DATA}}) for those vertexes.
213
214{{ATTRIBUTES}} is the list of data necessary for the vertex attributes, in the form of {{((LOCATION TYPE N [normalize?: NORMALIZE?]) ...)}}. {{LOCATION}} is the attribute location, {{TYPE}} is the type of data corresponding to the given attribute, given as a keyword. For possible types, see {{type->gl-type}}. {{N}} is the number of elements for the givien attribute. The keyword {{normalize?:}} accepts a boolean argument which instructs OpenGL to normalize the attribute or not. Defaults to {{#f}}.
215
216The optional {{USAGE}} must be one of {{+stream-data+}}, {{+stream-read+}}, {{stream-copy}}, {{+static-data+}}, {{+static-read+}}, {{static-copy}}, {{+dynamic-data+}}, {{+dynamic-read+}}, {{dynamic-copy}}. Defaults to {{+static-draw+}}.
217
218{{make-vao}} returns the ID of a vertex array object. This object should be deleted with {{delete-vertex-array}} when no longer used. Intermediate vertex buffers are generated and deleted, thus only the returned vertex array ID needs to be managed.
219
220<procedure> (load-ply FILE BUFFER-SPEC)</procedure>
221
222Loads a [[http://paulbourke.net/dataformats/ply/|PLY]] file. {{FILE}} is a path that may be pointing to a gziped PLY file. {{BUFFER-SPEC}} is a list in the form {{((NAME VARS) ...)}} where {{NAME}} is the name of an element in the PLY file and {{VARS}} is either a list of property names or, in the case of a property list, a single name. Two values are returned: a list of blobs which correspond to the buffers named in {{BUFFER-SPEC}} and a list of the elements that are in the PLY file in the form of:
223
224    (element-name n-elements (property-name property-type))
225
226Or, when an element is a property list:
227
228    (element-name n-elements (property-name (list: list-length-type element-type)))
229
230The buffers returned are packed with the contents of the properties named in the {{BUFFER-SPEC}}. Thus, for a PLY file that has element {{vertex}} with properties {{float x}}, {{float y}}, {{float z}}, {{float confidence}}, {{uchar r}}, {{uchar g}}, and {{uchar b}}, as well as a nelement {{face}} with a property list {{uchar ushort vertex_index}}, the following {{BUFFER-SPEC}} could be used:
231
232    (load-ply "example.ply.gz" '((vertex: (x y z r g b)) (face: vertex_index)))
233
234This buffer spec would result in a list of two blobs being returned: one with the packed elements corresponding to properties {{x}}, {{y}}, {{z}}, {{r}}, {{g}}, and {{b}} (with the corresponding property types), and the second containing the vertex indices.
235
236<procedure> (load-ply-vao FILE #!key VERTEX FACE)</procedure>
237
238Similar to {{load-ply}}, but returns a number of values:
239
240* A vertex array ID as generated by {{make-vao}}.
241* A blob representing the vertex data of the model
242* A blob representing the index data of the model
243* The number of vertices of the model
244* The GL enum value of the type of primitive used for the model (e.g. {{+triangles+}})
245* The GL enum value of the element data type
246
247{{FILE}} is a PLY file (which may be gziped). The PLY file must contain at least the elements {{vertex}} and {{face}} (other elements will be ignored). {{VERTEX}} is a list of {{(attribute-location property-name ...)}} elements, which specifies how the vertex buffers of the VAO will be arranged. All properties named by each element of {{VERTEX}} must be of the same type. {{FACE}} is the name of the face property list.
248
249Again, for a PLY file that has element {{vertex}} with properties {{float x}}, {{float y}}, {{float z}}, {{float confidence}}, {{uchar r}}, {{uchar g}}, and {{uchar b}}, as well as a element {{face}} with a property list {{uchar ushort vertex_index}}, the following could be used:
250
251    (load-ply-vao "example.ply" vertex: `((,vertex-location x y z)
252                                          (,color-location r g b))
253                                face: vertex_index)
254   
255<procedure> (type->gl-type TYPE)</procedure>
256
257Converts the keyword {{TYPE}} into a OpenGL type enum value. Accepted types (grouped by synonyms) are:
258
259* {{char:}} {{int8:}} {{byte:}}
260* {{uchar:}} {{uint8:}} {{unsigned-byte:}}
261* {{short:}} {{int16:}}
262* {{ushort:}} {{uint16:}} {{unsigned-short:}}
263* {{int:}} {{int32:}} {{integer:}} {{integer32:}}
264* {{uint:}} {{uint32:}} {{unsigned-int:}} {{unsigned-int32:}} {{unsigned-integer:}} {{unsigned-integer32:}}
265* {{float:}} {{float32:}}
266* {{double:}} {{float64:}}
267
268
269=== Example
270This example depends on the [[http://wiki.call-cc.org/eggref/4/glfw3|glfw3]] egg for window and context creation.
271
272<enscript highlight="scheme">    
273(import chicken scheme)
274(use (prefix glfw3 glfw:) (prefix opengl-glew gl:) gl-math gl-utils)
275
276(define *vertex*
277#<<END
278#version 330
279in vec2 vertex;
280in vec3 color;
281out vec3 c;
282uniform mat4 MVP;
283
284void main(){
285   gl_Position = MVP * vec4(vertex, 0.0, 1.0);
286   c = color;
287}
288END
289)
290
291(define *fragment*
292#<<END
293#version 330
294in vec3 c;
295out vec4 fragColor;
296void main(){
297  fragColor = vec4(c, 1.0);
298}
299END
300)
301
302(define vertex-data (f32vector -1 -1 1 0 0
303                               1 -1 0 1 0
304                               1 1 0 0 1
305                               -1 1 1 0 1))
306
307(define index-data (u16vector 0 1 2
308                              0 2 3))
309
310(define vao (make-parameter #f))
311
312(define program (make-parameter #f))
313
314(define projection-matrix
315  (perspective 640 480 0.1 100 70))
316
317(define view-matrix
318  (look-at 1 0 3
319           0 0 0
320           0 1 0))
321
322(define model-matrix (mat4-identity))
323
324(define (render)
325  (gl:use-program (program))
326  (gl:uniform-matrix4fv (gl:get-uniform-location (program) "MVP")
327                        1 #f
328                        (m* projection-matrix
329                            (m* view-matrix model-matrix)))
330  (gl:bind-vertex-array (vao))
331  (gl:draw-elements-base-vertex gl:+triangles+ 6 (type->gl-type ushort:) #f 0)
332
333  (gl:check-error)
334  (gl:bind-vertex-array 0))
335
336(glfw:with-window (640 480 "Example" resizable: #f)
337  (gl:init)
338
339  (print (gl:supported? "GL_ARB_framebuffer_object"))
340
341  (set! *vertex* (gl:make-shader gl:+vertex-shader+ *vertex*))
342  (set! *fragment* (gl:make-shader gl:+fragment-shader+ *fragment*))
343
344  (program (gl:make-program (list *vertex* *fragment*)))
345
346  (vao (make-vao (f32vector->blob vertex-data) (u16vector->blob index-data)
347                 `((,(gl:get-attrib-location (program) "vertex") float: 2)
348                   (,(gl:get-attrib-location (program) "color") float: 3))))
349  (let loop ()
350     (glfw:swap-buffers (glfw:window))
351     (gl:clear (bitwise-ior gl:+color-buffer-bit+ gl:+depth-buffer-bit+))
352     (render)
353     (glfw:poll-events)
354     (unless (glfw:window-should-close (glfw:window))
355       (loop))))
356</enscript>
357
358
359=== Version history
360
361==== Version 0.4.4
3622 June 2014
363
364* {{load-ply-vao}} now returns buffer data (which is important to keep around!)
365
366'''Version 0.4.3'''
367
36830 May 2014
369
370* Add optional program argument to {{make-program}}
371* gl-math short-circuits rotations of 0
372
373'''Version 0.4.2'''
374
37524 May 2014
376
377* Fix segfaults caused by glewExperimental not being set (thanks, Terpri!)
378
379'''Version 0.4.1'''
380
38112 May 2014
382
383* Remove rogue print statement
384
385'''Version 0.4.0'''
386
38711 May 2014
388
389* Add gl-math module
390* Add gl-utils module
391* Add {{check-error}}
392
393
394==== Version 0.3.0
395* Add single element {{gen}} and {{delete}} functions
396
397
398==== Version 0.2.0
399* Add glcorearb.h - no longer downloaded at install time
400
401
402==== Version 0.1.0
403* Initial release
404
405
406=== Source repository
407Source available on [[https://github.com/AlexCharlton/chicken-opengl-glew|GitHub]].
408
409Bug reports and patches welcome! Bugs can be reported via GitHub or to alex.n.charlton at gmail.
410
411
412=== Author
413Alex Charlton
414
415
416=== Licence
417BSD
Note: See TracBrowser for help on using the repository browser.