# opengl-glew Bindings to OpenGL with GLEW extension loading. Chicken's other [opengl](http://wiki.call-cc.org/eggref/4/opengl) bindings are based on the old fixed function pipeline OpenGL. These bindings generated by [bind](http://wiki.call-cc.org/eggref/4/bind) with the OpenGL [core header file](http://www.opengl.org/registry/api/GL/glcorearb.h). Additionally, bindings to [GLEW](http://glew.sourceforge.net/) are provided for extension management. The opengl-glew egg provides two modules, an eponymous module that provides the main OpenGl and GLEW functionality, and `gl-utils` which provides various high-level functions. ## Installation This repository is a [Chicken Scheme](http://call-cc.org/) egg. It is part of the [Chicken egg index](http://wiki.call-cc.org/chicken-projects/egg-index-4.html) and can be installed with `chicken-install opengl-glew`. ## Requirements - make - bind - z3 (gl-utils) - matchable (gl-utils) - miscmacros (gl-utils) - srfi-42 (gl-utils) ## Documentation All functions and constants from the OpenGL [core header file](http://www.opengl.org/registry/api/GL/glcorearb.h) 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+`). Functions whose C counterparts accept or return `GLboolean` accept or return a Scheme boolean value. *Do not* pass `+true+` or `+false+` to these functions. ### GLEW functions [procedure] (init) Required to initialize GLEW/OpenGL. An OpenGL context must be created before this is called. [procedure] (supported? EXTENSION-NAME) Query whether the OpenGL extension, given as a string, is supported. ### GL helper functions The 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. [procedure] (make-shader TYPE SOURCE) Creates 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. [procedure] (make-program SHADER-LIST [PROGRAM-ID]) Creates 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. Accepts an optional `PROGRAM-ID` argument. If given, `make-program` will use this ID rather than generating a new one. [procedure] (gen-buffer) [procedure] (gen-framebuffer) [procedure] (gen-program-pipeline) [procedure] (gen-query) [procedure] (gen-renderbuffer) [procedure] (gen-sampler) [procedure] (gen-texture) [procedure] (gen-transform-feedback) [procedure] (gen-vertex-array) Analogous to their pluralized counterparts, but only generates and returns one (integer) object. [procedure] (delete-buffer BUFFER) [procedure] (delete-framebuffer FRAMEBUFFER) [procedure] (delete-program-pipeline PROGRAM-PIPELINE) [procedure] (delete-query QUERY) [procedure] (delete-renderbuffer RENDERBUFFER) [procedure] (delete-sampler SAMPLER) [procedure] (delete-texture TEXTURE) [procedure] (delete-transform-feedback TRANSFORM-FEEDBACK) [procedure] (delete-vertex-array VERTEX-ARRAY) Analogous to their pluralized counterparts, but only accepts and deletes one (integer) object. [procedure] (check-error) Performs `get-error` (`glGetError`) and prints the error type when an error is returned. ### gl-utils gl-utils provides functions for creating VAOs, and loading PLY files. [procedure] (make-vao VERTEX-DATA INDEX-DATA ATTRIBUTES [USAGE]) `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. This data may be passed as any sort of (srfi-4) vector or a blob. `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 given attribute. The keyword `normalize?:` accepts a boolean argument which instructs OpenGL to normalize the attribute or not. Defaults to `#f`. The 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+`. `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. [procedure] (load-ply FILE BUFFER-SPEC) Loads a [PLY](http://paulbourke.net/dataformats/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 u8vectors 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: (element-name n-elements (property-name property-type)) Or, when an element is a property list: (element-name n-elements (property-name (list: list-length-type element-type))) The 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: (load-ply "example.ply.gz" '((vertex: (x y z r g b)) (face: vertex_index))) This buffer spec would result in a list of two u8vectors 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. [procedure] (load-ply-vao FILE vertex: VERTEX face: FACE) Similar to `load-ply`, but returns a number of values: - A vertex array ID as generated by `make-vao`. - A u8vector representing the vertex data of the model - A u8vector representing the index data of the model - The number of vertices of the model - The GL enum value of the type of primitive used for the model (e.g. `+triangles+`) - The GL enum value of the element data type `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. Again, 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: (load-ply-vao "example.ply" vertex: `((,vertex-location x y z) (,color-location r g b)) face: vertex_index) [procedure] (type->gl-type TYPE) Converts the keyword `TYPE` into a OpenGL type enum value. Accepted types (grouped by synonyms) are: - `char:` `int8:` `byte:` - `uchar:` `uint8:` `unsigned-byte:` - `short:` `int16:` - `ushort:` `uint16:` `unsigned-short:` - `int:` `int32:` `integer:` `integer32:` - `uint:` `uint32:` `unsigned-int:` `unsigned-int32:` `unsigned-integer:` `unsigned-integer32:` - `float:` `float32:` - `double:` `float64:` #### Vectors (srfi-4) gl-utils reexports a version of [srfi-4](http://api.call-cc.org/doc/srfi-4) that gives preference to vectors being created in non-garbage collected memory. This is useful for use with OpenGL, since it is often desirable to pass vectors to OpenGL that will remain in one place. All srfi-4 functions not mentioned below are reexported without changes. The `NNNvector` and `list->NNNvector` constructors have been modified so that they return vectors in non-garbage collected memory. The `make-NNNvector` constructors act as their srfi-4 counterparts, except they now return vectors in non-garbage collected memory by default. ## Example This example depends on the [glfw3](http://wiki.call-cc.org/eggref/4/glfw3) egg for window and context creation, and the [gl-math](http://wiki.call-cc.org/eggref/4/gl-math) egg for matrix math. ``` Scheme (import chicken scheme) (use (prefix glfw3 glfw:) (prefix opengl-glew gl:) gl-math gl-utils) (define *vertex* #<gl-type ushort:) #f 0) (gl:check-error) (gl:bind-vertex-array 0)) (glfw:with-window (640 480 "Example" resizable: #f) (gl:init) (print (gl:supported? "GL_ARB_framebuffer_object")) (set! *vertex* (gl:make-shader gl:+vertex-shader+ *vertex*)) (set! *fragment* (gl:make-shader gl:+fragment-shader+ *fragment*)) (program (gl:make-program (list *vertex* *fragment*))) (vao (make-vao vertex-data index-data `((,(gl:get-attrib-location (program) "vertex") float: 2) (,(gl:get-attrib-location (program) "color") float: 3)))) (let loop () (glfw:swap-buffers (glfw:window)) (gl:clear (bitwise-ior gl:+color-buffer-bit+ gl:+depth-buffer-bit+)) (render) (glfw:poll-events) (unless (glfw:window-should-close (glfw:window)) (loop)))) ``` ## Version history ### Version 0.6.0 17 June 2014 * Remove gl-math module (which is now its own egg: [gl-math](http://wiki.call-cc.org/eggref/4/gl-math)) ### Version 0.5.0 3 June 2014 * `make-vao` accepts vectors and blobs * `load-ply` returns u8vectors rather than blobs * gl-utils exports a non-garbage collected by default version of srfi-4 * gl-math can create non-garbage collected matrices ### Version 0.4.4 2 June 2014 * `load-ply-vao` now returns buffer data (which is important to keep around!) **Version 0.4.3** 30 May 2014 * Add optional program argument to `make-program` * gl-math short-circuits rotations of 0 **Version 0.4.2** 24 May 2014 * Fix segfaults caused by glewExperimental not being set (thanks, Terpri!) **Version 0.4.1** 12 May 2014 * Remove rogue print statement **Version 0.4.0** 11 May 2014 * Add gl-math module * Add gl-utils module * Add `check-error` ### Version 0.3.0 * Add single element `gen` and `delete` functions ### Version 0.2.0 * Add glcorearb.h - no longer downloaded at install time ### Version 0.1.0 * Initial release ## Source repository Source available on [GitHub](https://github.com/AlexCharlton/chicken-opengl-glew). Bug reports and patches welcome! Bugs can be reported via GitHub or to alex.n.charlton at gmail. ## Author Alex Charlton ## Licence BSD