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

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

Update to version 0.4.2

File size: 17.6 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)</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
46<procedure> (gen-buffer)</procedure>
47<procedure> (gen-framebuffer)</procedure>
48<procedure> (gen-program-pipeline)</procedure>
49<procedure> (gen-query)</procedure>
50<procedure> (gen-renderbuffer)</procedure>
51<procedure> (gen-sampler)</procedure>
52<procedure> (gen-texture)</procedure>
53<procedure> (gen-transform-feedback)</procedure>
54<procedure> (gen-vertex-array)</procedure>
55
56Analogous to their pluralized counterparts, but only generates and returns one (integer) object.
57
58<procedure> (delete-buffer BUFFER)</procedure>
59<procedure> (delete-framebuffer FRAMEBUFFER)</procedure>
60<procedure> (delete-program-pipeline PROGRAM-PIPELINE)</procedure>
61<procedure> (delete-query QUERY)</procedure>
62<procedure> (delete-renderbuffer RENDERBUFFER)</procedure>
63<procedure> (delete-sampler SAMPLER)</procedure>
64<procedure> (delete-texture TEXTURE)</procedure>
65<procedure> (delete-transform-feedback TRANSFORM-FEEDBACK)</procedure>
66<procedure> (delete-vertex-array VERTEX-ARRAY)</procedure>
67
68Analogous to their pluralized counterparts, but only accepts and deletes one (integer) object.
69
70<procedure> (check-error)</procedure>
71
72Performs {{get-error}} ({{glGetError}}) and prints the error type when an error is returned.
73
74
75==== gl-math
76gl-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:
77
78* Matrix functions only operate on 4x4 matrices
79* Matrix functions can accept either f32vectors or pointers
80* No container is used to represent matrices
81
82Additionally, gl-math is one fifth the compiled size of glm, has a more straight-forward code-base, and complete documentation.
83
84gl-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.
85
86gl-math operates on matrices in a column-major fashion in correspondence with OpenGL (e.g. translation components are at indices 12, 13, and 14).
87
88<procedure> (print-mat4 MATRIX)</procedure>
89
90Prints the given {{MATRIX}} to {{(current-output-port)}}.
91
92<procedure> (m* A B #!optional RESULT)</procedure>
93
94Multiply 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.
95
96<procedure> (mat4-identity #!optional RESULT)</procedure>
97
98Return an identity matrix. If {{RESULT}} is not provided, the returned value will be an f32vector.
99
100<procedure> (translate X Y Z MATRIX)</procedure>
101
102Translate {{MATRIX}} by {{X}}, {{Y}}, and {{Z}}.
103
104<procedure> (rotate-x ANGLE MATRIX)</procedure>
105
106Rotate {{MATRIX}} around the x-axis by {{ANGLE}} radians.
107
108<procedure> (rotate-y ANGLE MATRIX)</procedure>
109
110Rotate {{MATRIX}} around the y-axis by {{ANGLE}} radians.
111
112<procedure> (rotate-z ANGLE MATRIX)</procedure>
113
114Rotate {{MATRIX}} around the z-axis by {{ANGLE}} radians.
115
116<procedure> (rotate X Y Z ANGLE MATRIX)</procedure>
117
118Rotate {{MATRIX}} around the vector given by {{X}}, {{Y}}, and {{Z}} by {{ANGLE}} radians.
119
120<procedure> (scale-2d SCALE-X SCALE-Y MATRIX)</procedure>
121
122Scale the x and y axis of {{MATRIX}} by {{SCALE-X}} and {{SCALE-Y}}.
123
124<procedure> (scale-3d SCALE-X SCALE-Y SCALE-Z MATRIX)</procedure>
125
126Scale the x, y, and z axis of {{MATRIX}} by {{SCALE-X}}, {{SCALE-Y}}, and {{SCALE-Z}}.
127
128<procedure> (scale SCALE MATRIX)</procedure>
129
130Scale the x, y, and z axis of {{MATRIX}} by {{SCALE}}.
131
132<procedure> (flip-x MATRIX)</procedure>
133
134Flip (mirror) {{MATRIX}} along the x-axis.
135
136<procedure> (flip-y MATRIX)</procedure>
137
138Flip (mirror) {{MATRIX}} along the y-axis.
139
140<procedure> (flip-z MATRIX)</procedure>
141
142Flip (mirror) {{MATRIX}} along the z-axis.
143
144<procedure> (translate-scale X Y Z SCALE #!optional RESULT)</procedure>
145
146Efficiently 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.
147
148<procedure> (translate-rotate-scale-2d X Y Z ANGLE SCALE #!optional RESULT)</procedure>
149
150Efficiently 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.
151
152<procedure> (translate-rotate-scale X Y Z RX RY RZ ANGLE SCALE #!optional RESULT)</procedure>
153
154Efficiently 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.
155
156<procedure> (transpose MATRIX #!optional RESULT)</procedure>
157
158Transpose {{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.
159
160<procedure> (inverse MATRIX #!optional RESULT)</procedure>
161
162Invert {{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.
163
164<procedure> (ortho WIDTH HEIGHT NEAR FAR #!optional RESULT)</procedure>
165
166Create 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.
167
168<procedure> (perspective WIDTH HEIGHT NEAR FAR ANGLE #!optional RESULT)</procedure>
169
170Create 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.
171
172<procedure> (frustum LEFT RIGHT BOTTOM TOP NEAR FAR #!optional RESULT)</procedure>
173
174Create 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.
175
176<procedure> (look-at EYE-X EYE-Y EYE-Z X Y Z UP-X UP-Y UP-Z #!optional RESULT)</procedure>
177
178Create 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.
179
180<procedure> (camera-inverse CAMERA #!optional RESULT)</procedure>
181
182Invert {{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.
183
184<procedure> (cross-product AX AY AZ BX BY BZ)</procedure>
185
186Return the result of the cross product between the vectors {{(AX, AY, AZ)}} and {{(BX, BY, BZ)}}. The resulting vector is returned as three values.
187
188<procedure> (dot-product AX AY AZ BX BY BZ)</procedure>
189
190Return the result of the dot product between the vectors {{(AX, AY, AZ)}} and {{(BX, BY, BZ)}}.
191
192<procedure> (normalize X Y Z)</procedure>
193
194Return the normalized vector {{(X, Y, Z)}}. The resulting vector is returned as three values.
195
196<procedure> (degrees->radians ANGLE)</procedure>
197
198Converts {{ANGLE}} from degrees to radians.
199
200<procedure> (radians->degrees ANGLE)</procedure>
201
202Converts {{ANGLE}} from radians to degrees.
203
204
205==== gl-utils
206gl-utils provides functions for creating VAOs, and loading PLY files.
207
208<procedure> (make-vao VERTEX-DATA INDEX-DATA ATTRIBUTES #!optional USAGE)</procedure>
209
210{{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.
211
212{{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}}.
213
214The 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+}}.
215
216{{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.
217
218<procedure> (load-ply FILE BUFFER-SPEC)</procedure>
219
220Loads 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:
221
222    (element-name n-elements (property-name property-type))
223
224Or, when an element is a property list:
225
226    (element-name n-elements (property-name (list: list-length-type element-type)))
227
228The 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:
229
230    (load-ply "example.ply.gz" '((vertex: (x y z r g b)) (face: vertex_index)))
231
232This 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.
233
234<procedure> (load-ply-vao FILE #!key VERTEX FACE)</procedure>
235
236Similar to {{load-ply}}, but returns a single vertex array ID as generated by {{make-vao}}. {{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.
237
238Again, 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:
239
240    (load-ply-vao "example.ply" vertex: `((,vertex-location x y z)
241                                          (,color-location r g b))
242                                face: vertex_index)
243   
244<procedure> (type->gl-type TYPE)</procedure>
245
246Converts the keyword {{TYPE}} into a OpenGL type enum value. Accepted types (grouped by synonyms) are:
247
248* {{char:}} {{int8:}} {{byte:}}
249* {{uchar:}} {{uint8:}} {{unsigned-byte:}}
250* {{short:}} {{int16:}}
251* {{ushort:}} {{uint16:}} {{unsigned-short:}}
252* {{int:}} {{int32:}} {{integer:}} {{integer32:}}
253* {{uint:}} {{uint32:}} {{unsigned-int:}} {{unsigned-int32:}} {{unsigned-integer:}} {{unsigned-integer32:}}
254* {{float:}} {{float32:}}
255* {{double:}} {{float64:}}
256
257
258=== Example
259This example depends on the [[http://wiki.call-cc.org/eggref/4/glfw3|glfw3]] egg for window and context creation.
260
261<enscript highlight="scheme">    
262(import chicken scheme)
263(use (prefix glfw3 glfw:) (prefix opengl-glew gl:) gl-math gl-utils)
264
265(define *vertex*
266#<<END
267#version 330
268in vec2 vertex;
269in vec3 color;
270out vec3 c;
271uniform mat4 MVP;
272
273void main(){
274   gl_Position = MVP * vec4(vertex, 0.0, 1.0);
275   c = color;
276}
277END
278)
279
280(define *fragment*
281#<<END
282#version 330
283in vec3 c;
284out vec4 fragColor;
285void main(){
286  fragColor = vec4(c, 1.0);
287}
288END
289)
290
291(define vertex-data (f32vector -1 -1 1 0 0
292                               1 -1 0 1 0
293                               1 1 0 0 1
294                               -1 1 1 0 1))
295
296(define index-data (u16vector 0 1 2
297                              0 2 3))
298
299(define vao (make-parameter #f))
300
301(define program (make-parameter #f))
302
303(define projection-matrix
304  (perspective 640 480 0.1 100 70))
305
306(define view-matrix
307  (look-at 1 0 3
308           0 0 0
309           0 1 0))
310
311(define model-matrix (mat4-identity))
312
313(define (render)
314  (gl:use-program (program))
315  (gl:uniform-matrix4fv (gl:get-uniform-location (program) "MVP")
316                        1 #f
317                        (m* projection-matrix
318                            (m* view-matrix model-matrix)))
319  (gl:bind-vertex-array (vao))
320  (gl:draw-elements-base-vertex gl:+triangles+ 6 (type->gl-type ushort:) #f 0)
321
322  (gl:check-error)
323  (gl:bind-vertex-array 0))
324
325(glfw:with-window (640 480 "Example" resizable: #f)
326  (gl:init)
327
328  (print (gl:supported? "GL_ARB_framebuffer_object"))
329
330  (set! *vertex* (gl:make-shader gl:+vertex-shader+ *vertex*))
331  (set! *fragment* (gl:make-shader gl:+fragment-shader+ *fragment*))
332
333  (program (gl:make-program (list *vertex* *fragment*)))
334
335  (vao (make-vao (f32vector->blob vertex-data) (u16vector->blob index-data)
336                 `((,(gl:get-attrib-location (program) "vertex") float: 2)
337                   (,(gl:get-attrib-location (program) "color") float: 3))))
338  (let loop ()
339     (glfw:swap-buffers (glfw:window))
340     (gl:clear (bitwise-ior gl:+color-buffer-bit+ gl:+depth-buffer-bit+))
341     (render)
342     (glfw:poll-events)
343     (unless (glfw:window-should-close (glfw:window))
344       (loop))))
345</enscript>
346
347
348=== Version history
349
350==== Version 0.4.2
35124 May 2014
352* Fix segfaults caused by glewExperimental not being set (thanks, Terpri!)
353
354'''Version 0.4.1'''
355
35612 May 2014
357* Remove rogue print statement
358
359'''Version 0.4.0'''
360
36111 May 2014
362* Add gl-math module
363* Add gl-utils module
364* Add {{check-error}}
365
366
367==== Version 0.3.0
368* Add single element {{gen}} and {{delete}} functions
369
370
371==== Version 0.2.0
372* Add glcorearb.h - no longer downloaded at install time
373
374
375==== Version 0.1.0
376* Initial release
377
378
379=== Source repository
380Source available on [[https://github.com/AlexCharlton/chicken-opengl-glew|GitHub]].
381
382Bug reports and patches welcome! Bugs can be reported via GitHub or to alex.n.charlton at gmail.
383
384
385=== Author
386Alex Charlton
387
388
389=== Licence
390BSD
Note: See TracBrowser for help on using the repository browser.