Changeset 31296 in project


Ignore:
Timestamp:
08/26/14 21:42:30 (5 years ago)
Author:
acharlton
Message:

wiki opengl-glew: Update to 0.8.0

File:
1 edited

Legend:

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

    r31200 r31296  
     1
    12== opengl-glew
    23[[toc:]]
     
    56Chicken'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.
    67
    7 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.
    8 
    98
    109=== Requirements
    1110* make
    1211* bind
    13 * z3 (gl-utils)
    14 * matchable (gl-utils)
    15 * miscmacros (gl-utils)
    16 * srfi-42 (gl-utils)
    1712
    1813
    1914=== Documentation
    20 All 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+}}).
     15All 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, functions starting with {{is}} instead end in question marks, and constants are bookended by {{+}}s (e.g. {{delete-texture}}, {{enabled?}}, {{+arb-viewport-array+}}). The terms {{1D}}, {{2D}} and {{3D}} are additionally hyphen separated in order to match their constant counterparts (e.g. {{tex-image-2d}} and {{+texture-2d+}}).
    2116
    2217Functions whose C counterparts accept or return {{GLboolean}} accept or return a Scheme boolean value. ''Do not'' pass {{+true+}} or {{+false+}} to these functions.
     
    3328
    3429
    35 ==== GL helper functions
    36 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.
    37 
    38 <procedure> (make-shader TYPE SOURCE)</procedure>
    39 
    40 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.
    41 
    42 <procedure> (make-program SHADER-LIST [PROGRAM-ID])</procedure>
    43 
    44 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.
    45 
    46 Accepts 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 
    58 Analogous 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 
    70 Analogous to their pluralized counterparts, but only accepts and deletes one (integer) object.
    71 
    72 <procedure> (check-error)</procedure>
    73 
    74 Performs {{get-error}} ({{glGetError}}) and prints the error type when an error is returned.
    75 
    76 
    77 ==== gl-utils
    78 gl-utils provides functions for creating VAOs, and loading PLY files.
    79 
    80 <procedure> (make-vao VERTEX-DATA INDEX-DATA ATTRIBUTES [USAGE])</procedure>
    81 
    82 {{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.
    83 
    84 {{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}}.
    85 
    86 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+}}.
    87 
    88 {{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.
    89 
    90 <procedure> (load-ply FILE BUFFER-SPEC)</procedure>
    91 
    92 Loads 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 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:
    93 
    94     (element-name n-elements (property-name property-type))
    95 
    96 Or, when an element is a property list:
    97 
    98     (element-name n-elements (property-name (list: list-length-type element-type)))
    99 
    100 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:
    101 
    102     (load-ply "example.ply.gz" '((vertex: (x y z r g b)) (face: vertex_index)))
    103 
    104 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.
    105 
    106 <procedure> (load-ply-vao FILE vertex: VERTEX face: FACE)</procedure>
    107 
    108 Similar to {{load-ply}}, but returns a number of values:
    109 
    110 * A vertex array ID as generated by {{make-vao}}.
    111 * A u8vector representing the vertex data of the model
    112 * A u8vector representing the index data of the model
    113 * The number of vertices of the model
    114 * The GL enum value of the type of primitive used for the model (e.g. {{+triangles+}})
    115 * The GL enum value of the element data type
    116 
    117 {{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.
    118 
    119 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:
    120 
    121     (load-ply-vao "example.ply" vertex: `((,vertex-location x y z)
    122                                           (,color-location r g b))
    123                                 face: vertex_index)
    124    
    125 <procedure> (type->gl-type TYPE)</procedure>
    126 
    127 Converts the keyword {{TYPE}} into a OpenGL type enum value. Accepted types (grouped by synonyms) are:
    128 
    129 * {{char:}} {{int8:}} {{byte:}}
    130 * {{uchar:}} {{uint8:}} {{unsigned-byte:}}
    131 * {{short:}} {{int16:}}
    132 * {{ushort:}} {{uint16:}} {{unsigned-short:}}
    133 * {{int:}} {{int32:}} {{integer:}} {{integer32:}}
    134 * {{uint:}} {{uint32:}} {{unsigned-int:}} {{unsigned-int32:}} {{unsigned-integer:}} {{unsigned-integer32:}}
    135 * {{float:}} {{float32:}}
    136 * {{double:}} {{float64:}}
    137 
    138 
    139 ===== Vectors (srfi-4)
    140 gl-utils reexports a version of [[http://api.call-cc.org/doc/srfi-4|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.
    141 
    142 The {{NNNvector}} and {{list->NNNvector}} constructors have been modified so that they return vectors in non-garbage collected memory.
    143 
    144 The {{make-NNNvector}} constructors act as their srfi-4 counterparts, except they now return vectors in non-garbage collected memory by default.
    145 
    146 Additionally, the following non-srfi-4 procedures are exported:
    147 
    148 <procedure> (->pointer VECTOR)</procedure>
    149 
    150 Returns the pointer to a srfi-4 vector or blob.
    151 
    152 <procedure> (size VECTOR)</procedure>
    153 
    154 Returns the size, in bytes, of a srfi-4 vector or blob.
    155 
    156 
    15730=== Example
    158 This example depends on the [[http://wiki.call-cc.org/eggref/4/glfw3|glfw3]] egg for window and context creation, and the [[http://wiki.call-cc.org/eggref/4/gl-math|gl-math]] egg for matrix math.
    159 
    160 <enscript highlight="scheme">   
    161 (import chicken scheme)
    162 (use (prefix glfw3 glfw:) (prefix opengl-glew gl:) gl-math gl-utils)
    163 
    164 (define *vertex*
    165 #<<END
    166 #version 330
    167 in vec2 vertex;
    168 in vec3 color;
    169 out vec3 c;
    170 uniform mat4 MVP;
    171 
    172 void main(){
    173    gl_Position = MVP * vec4(vertex, 0.0, 1.0);
    174    c = color;
    175 }
    176 END
    177 )
    178 
    179 (define *fragment*
    180 #<<END
    181 #version 330
    182 in vec3 c;
    183 out vec4 fragColor;
    184 void main(){
    185   fragColor = vec4(c, 1.0);
    186 }
    187 END
    188 )
    189 
    190 (define vertex-data (f32vector -1 -1 1 0 0
    191                                1 -1 0 1 0
    192                                1 1 0 0 1
    193                                -1 1 1 0 1))
    194 
    195 (define index-data (u16vector 0 1 2
    196                               0 2 3))
    197 
    198 (define vao (make-parameter #f))
    199 
    200 (define program (make-parameter #f))
    201 
    202 (define projection-matrix
    203   (perspective 640 480 0.1 100 70))
    204 
    205 (define view-matrix
    206   (look-at 1 0 3
    207            0 0 0
    208            0 1 0))
    209 
    210 (define model-matrix (mat4-identity))
    211 
    212 (define (render)
    213   (gl:use-program (program))
    214   (gl:uniform-matrix4fv (gl:get-uniform-location (program) "MVP")
    215                         1 #f
    216                         (m* projection-matrix
    217                             (m* view-matrix model-matrix)))
    218   (gl:bind-vertex-array (vao))
    219   (gl:draw-elements-base-vertex gl:+triangles+ 6 (type->gl-type ushort:) #f 0)
    220 
    221   (gl:check-error)
    222   (gl:bind-vertex-array 0))
    223 
    224 (glfw:with-window (640 480 "Example" resizable: #f)
    225   (gl:init)
    226 
    227   (print (gl:supported? "GL_ARB_framebuffer_object"))
    228 
    229   (set! *vertex* (gl:make-shader gl:+vertex-shader+ *vertex*))
    230   (set! *fragment* (gl:make-shader gl:+fragment-shader+ *fragment*))
    231 
    232   (program (gl:make-program (list *vertex* *fragment*)))
    233 
    234   (vao (make-vao vertex-data index-data
    235                  `((,(gl:get-attrib-location (program) "vertex") float: 2)
    236                    (,(gl:get-attrib-location (program) "color") float: 3))))
    237   (let loop ()
    238      (glfw:swap-buffers (glfw:window))
    239      (gl:clear (bitwise-ior gl:+color-buffer-bit+ gl:+depth-buffer-bit+))
    240      (render)
    241      (glfw:poll-events)
    242      (unless (glfw:window-should-close (glfw:window))
    243        (loop))))
    244 </enscript>
     31For numerous examples of opengl-glew usage, look at the [[http://wiki.call-cc.org/eggref/4/gl-utils|gl-utils]] egg, [[http://wiki.call-cc.org/eggref/4/glls|glls]] egg, or the [[http://wiki.call-cc.org/eggref/4/noise|noise]] egg.
    24532
    24633
    24734=== Version history
     35
     36==== Version 0.8.0
     3724 August 2014
     38
     39* Split [[http://wiki.call-cc.org/eggref/4/gl-utils|gl-utils]] into its own egg
     40* Hyphen-separate {{2D}}, {{3D}}, and {{4D}} in name conversion
     41
    24842
    24943==== Version 0.7.0
Note: See TracChangeset for help on using the changeset viewer.