Changeset 30848 in project


Ignore:
Timestamp:
05/12/14 00:12:47 (6 years ago)
Author:
acharlton
Message:

Update to version 0.4.0

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/opengl-glew

    r30828 r30848  
    55Chicken'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.
    66
     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
    79
    810=== Requirements
    9 * Make
    10 * Bind
     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
    1118
    1219=== Documentation
     
    1522Functions whose C counterparts accept or return {{GLboolean}} accept or return a Scheme boolean value. ''Do not'' pass {{+true+}} or {{+false+}} to these functions.
    1623
     24
    1725==== GLEW functions
    1826<procedure> (init)</procedure>
     
    2634
    2735==== 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
    2838<procedure> (make-shader TYPE SOURCE)</procedure>
    2939
     
    5868Analogous to their pluralized counterparts, but only accepts and deletes one (integer) object.
    5969
     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
    60257
    61258=== Example
     
    64261<enscript highlight="scheme">   
    65262(import chicken scheme)
    66 (use (prefix glfw3 glfw:) (prefix opengl-glew gl:))
     263(use (prefix glfw3 glfw:) (prefix opengl-glew gl:) gl-math gl-utils)
    67264
    68265(define *vertex*
     
    72269in vec3 color;
    73270out vec3 c;
    74 uniform mat4 viewMatrix;
     271uniform mat4 MVP;
    75272
    76273void main(){
    77    gl_Position = (viewMatrix * vec4(vertex, 0.0, 1.0));
     274   gl_Position = MVP * vec4(vertex, 0.0, 1.0);
    78275   c = color;
    79276}
     
    92289)
    93290
     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
    94325(glfw:with-window (640 480 "Example" resizable: #f)
    95326  ;; glfw3 automatically calls (gl:init) here when opengl-glew is loaded
     
    100331  (set! *fragment* (gl:make-shader gl:+fragment-shader+ *fragment*))
    101332
    102   ;;If this is not zero, then everything is working:
    103   (print (gl:make-program (list *vertex* *fragment*))))
     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))))
    104345</enscript>
    105346
    106347
    107348=== Version history
     349
     350==== Version 0.4.0
     351* Add gl-math module
     352* Add gl-utils module
     353* Add {{check-error}}
     354
    108355
    109356==== Version 0.3.0
    110357* Add single element {{gen}} and {{delete}} functions
    111358
     359
    112360==== Version 0.2.0
    113361* Add glcorearb.h - no longer downloaded at install time
    114362
     363
    115364==== Version 0.1.0
    116365* Initial release
    117366
     367
    118368=== Source repository
    119369Source available on [[https://github.com/AlexCharlton/chicken-opengl-glew|GitHub]].
Note: See TracChangeset for help on using the changeset viewer.