Changeset 32815 in project


Ignore:
Timestamp:
10/05/15 02:29:11 (4 years ago)
Author:
acharlton
Message:

wiki/glls: Improve documentation around renderables

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/glls

    r32206 r32815  
    264264
    265265==== Automatic render functions
    266 By using the {{glls-render}} module, you can have glls automatically generate a function that will render an object with your glls shader. {{glls-render}} exports a new {{define-pipeline}} that defines a set of functions used for rendering and managing the objects that will be rendered. {{glls-render}} should not be used with the {{glls}} module: It reexports everything that you need from {{glls}}.
     266By using the {{glls-render}} module, you can have glls automatically generate functions that will render an object with your glls pipeline. {{glls-render}} wraps {{define-pipeline}} so that it also defines a set of functions used for rendering and managing the ''renderable'' objects that are specific to that pipeline: one to create them, several to render them, and others to manipulate them. {{glls-render}} should not be used with the {{glls}} module: It reexports everything that you need from {{glls}}.
    267267
    268268Recalling {{define-pipeline}}:
     
    270270    (define-pipeline PIPELINE-NAME . SHADERS)
    271271
    272 There is one difference that you need to know when calling {{glls-render}}’s {{define-pipeline}}: All shaders must include a list of the shader’s uniforms since the uniforms are the important information needed to derive rendering functions. This means that if you previously define some shaders (for example: {{my-vertex-shader}} and {{my-fragment-shader}}) and you wish to combine them in a pipeline, you ''must'' include the uniforms in the pipeline definition. This is done with a list that takes the form {{(SHADER uniform: [UNIFORM] ...)}}. This list must be present even if the shader does not use any uniforms. For example:
     272There is one difference with {{glls-render}}’s {{define-pipeline}}: All shaders must include a list of the shader’s uniforms since the uniforms are the important information needed to derive rendering functions. This means that if you previously define some shaders (for example: {{my-vertex-shader}} and {{my-fragment-shader}}) and you wish to combine them in a pipeline, you ''must'' include the uniforms in the pipeline definition. This is done with a list that takes the form {{(SHADER uniform: [UNIFORM] ...)}}. This list must be present even if the shader does not use any uniforms. For example:
    273273
    274274    (define-pipeline my-pipeline
     
    278278Of course, if you are defining the shaders in the pipeline, then a separate list of uniforms is not necessary.
    279279
    280 {{glls-render}} causes {{define-pipeline}} to define several new functions. First is {{render-PIPELINE-NAME}}. {{render-PIPELINE-NAME}} takes one argument: a renderable object (see [[#renderables|Renderables]]).
    281 
    282 The {{render-PIPELINE-NAME}} function works differently depending on whether the {{define-pipeline}} has been compiled or interpreted (although the end results should stay the same). When {{define-pipeline}} is compiled, the resulting {{render-PIPELINE-NAME}} function is compiled directly to efficient (non-branching) C. When {{define-pipeline}} is interpreted, {{render-PIPELINE-NAME}} calls a generic rendering function that is not nearly as fast.
    283 
    284 The {{render-PIPELINE-NAME}} function draws the renderable using {{draw-elements}}. While this is typically the most efficient way to render a set of vertices, sometimes {{draw-arrays}} is preferable. A function similar to {{render-PIPELINE-NAME}} is therefore defined, {{render-arrays-PIPELINE-NAME}}, which functions identically except for calling {{draw-arrays}} instead of {{draw-elements}}.
    285 
    286280
    287281===== Renderables
    288 In order to use one of the automatically generated render functions, you must have something to render. That’s why {{define-pipeline}} also defines a function that constructs a renderable object: {{make-SHADER-NAME-renderable}}. This function takes a number of keyword arguments:
    289 
    290 * {{vao:}} – A VAO such as those returned by [[http://api.call-cc.org/doc/opengl-glew/make-vao|opengl-glew’s {{make-vao}}]]. I.e.: A VAO that binds an array of attributes – for each element in the pipeline – as well as an element array.
    291 * {{mode:}} – The drawing mode to use when drawing the elements of the VAO. Must be mode that is accepted by (gl-utils’) [[http://api.call-cc.org/doc/gl-utils/mode-%3Egl|mode->gl]]. Defaults to {{#:triangles}}.
    292 * {{n-elements:}} – The number of elements (vertices) to draw.
    293 * {{element-type:}} – The type of the values in the VAO’s element array. Must be one of {{#:unsigned-byte}}, {{#:unsigned-short}}, or {{#:unsigned-int}}. Not required if the VAO has no element array (i.e. {{render-arrays-PIPELINE-NAME}} is being used to render).
    294 * {{mesh:}} – A [[http://wiki.call-cc.org/eggref/4/gl-utils|gl-utils]] mesh, provided in place of {{vao:}}, {{mode:}}, {{n-elements:}}, and {{element-type:}}.
    295 * {{offset:}} – A byte offset to the location of the desired indices to draw.
    296 * {{data:}} – An optional pointer to an appropriate glls renderable object. If not provided, a fresh renderable object will be created. [[https://github.com/AlexCharlton/glls/blob/master/gllsRender.h|gllsRenderable.h]] defines the structs used for renderables. Which struct is used for a given pipeline is chosen based on the number of uniforms present in the pipeline.
     282{{glls-render}}’s {{define-piplelines}} defines a function for creating renderable objects:
     283
     284    (make-PIPELINE-NAME-renderable [vao: VAO] [mode: MODE] [n-elements: N-ELEMENTS] [element-type: ELEMENT-TYPE] [mesh: MESH] [offset: OFFSET] [data: DATA] + PIPELINE-SPECIFIC-KEYWORDS)
     285
     286Where {{PIPELINE-NAME}} is the name of the pipeline who’s renderables are being created.
     287
     288* {{VAO}} – A VAO such as those returned by [[http://api.call-cc.org/doc/opengl-glew/make-vao|opengl-glew’s {{make-vao}}]]. I.e.: A VAO that binds an array of attributes – for each element in the pipeline – as well as an element array.
     289* {{MODE}} – The drawing mode to use when drawing the elements of the VAO. Must be mode that is accepted by (gl-utils’) [[http://api.call-cc.org/doc/gl-utils/mode-%3Egl|mode->gl]]. Defaults to {{#:triangles}}.
     290* {{N-ELEMENTS}} – The number of elements (vertices) to draw.
     291* {{ELEMENT-TYPE}} – The type of the values in the VAO’s element array. Must be one of {{#:unsigned-byte}}, {{#:unsigned-short}}, or {{#:unsigned-int}}. Not required if the VAO has no element array (i.e. {{render-arrays-PIPELINE-NAME}} is being used to render).
     292* {{MESH}} – A [[http://wiki.call-cc.org/eggref/4/gl-utils|gl-utils]] mesh, provided in place of {{VAO}}, {{MODE}}, {{N-ELEMENTS}}, and {{ELEMENT-TYPE}}.
     293* {{OFFSET}} – A byte offset to the location of the desired indices to draw.
     294* {{DATA}} – An optional pointer to an appropriate glls renderable object. If not provided, a fresh renderable object will be created. [[https://github.com/AlexCharlton/glls/blob/master/gllsRender.h|gllsRenderable.h]] defines the structs used for renderables. Which struct is used for a given pipeline is chosen based on the number of uniforms present in the pipeline.
    297295
    298296See the [[https://www.opengl.org/sdk/docs/man/html/glDrawElements.xhtml|{{glDrawElements}} documentation]] for more information about these expected arguments.
    299297
    300 {{make-SHADER-NAME-renderable}} also expects one keyword argument for each uniform in the pipeline. These arguments should either be an f32vector, an s32vector, a u32vector, a pointer to the uniform data, or – in the case of a texture – a fixnum. Even if the uniform is a single value (e.g. a float), it must still be passed as a vector (or a pointer). This lets the value of the uniform be updated independently of the renderable.
    301 
    302 Additionally, there are a number of renderable setters for each of the keyword arguments accepted by {{make-SHADER-NAME-renderable}}:
     298{{make-PIPELINE-NAME-renderable}} also expects one keyword argument for each uniform in the pipeline. These arguments should either be an f32vector, an s32vector, a u32vector, a pointer to the uniform data, or – in the case of a texture – a fixnum. Even if the uniform is a single value (e.g. a float), it must still be passed as a vector (or a pointer). This lets the value of the uniform be updated independently of the renderable.
     299
     300Additionally, there are a number of renderable setters for each of the keyword arguments accepted by {{make-PIPELINE-NAME-renderable}}:
    303301
    304302<procedure> (set-renderable-vao! RENDERABLE VAO)</procedure>
     
    307305<procedure> (set-renderable-mode! RENDERABLE MODE)</procedure>
    308306<procedure> (set-renderable-offset! RENDERABLE OFFSET)</procedure>
    309 
    310 These setters accept two arguments: a renderable and a value. The values correspond to those that {{make-SHADER-NAME-renderable}} accepts.
    311 
    312 And for each uniform in the pipeline, {{set-SHADER-NAME-renderable-UNIFORM-NAME!}} is also created.
     307   
     308    (set-PIPELINE-NAME-renderable-UNIFORM-NAME! RENDERABLE UNIFORM-VALUE)
     309
     310These setters accept two arguments: a renderable and a value. The values correspond to those that {{make-PIPELINE-NAME-renderable}} accepts. For each uniform in the pipeline, a function named {{set-PIPELINE-NAME-renderable-UNIFORM-NAME!}} is created.
    313311
    314312<procedure> (renderable-size PIPELINE)</procedure>
     
    317315
    318316
    319 ===== Fast render functions
    320 When compiled, the render function defined by {{define-pipeline}} is actually a combination of three “fast” render functions: a begin render function, a render function, and an end render function. The array rendering function is a similar combination: the begin render function, an array render function and the end render function. This is done so that, if desired, all of the renderables that belong to the same pipeline may be rendered at the same time, without needing to perform expensive calls like program changes or texture binding more than once. To use these functions, simply call the begin render function with the first renderable, then call the render (or array render) function on all renderables (including the first), finally calling the end render function (with no arguments) to clean up.
    321 
    322 {{define-pipeline}} does not define all of these functions separately, but instead defines a single function with which to access them: {{PIPELINE-NAME-fast-render-functions}}. This function returns eight values: the begin render function, the render function, the end render function, the array render function, and pointers to those same C functions in that order.
     317===== Rendering renderables
     318    (render-PIPELINE-NAME RENDERABLE)
     319    (render-arrays-PIPELINE-NAME RENDERABLE)
     320
     321Where {{PIPELINE-NAME}} is the name of the pipeline who’s renderables are being rendered. {{render-PIPELINE-NAME}} and {{render-arrays-PIPELINE-NAME}} both render the given renderable.
     322
     323These render functions work differently depending on whether the {{define-pipeline}} has been compiled or interpreted (although the end results should look the same). When {{define-pipeline}} is compiled, the resulting render functions are compiled directly to efficient (non-branching) C. When {{define-pipeline}} is interpreted, the render functions call a generic rendering function that is not nearly as fast.
     324
     325The {{render-PIPELINE-NAME}} function draws the renderable using {{draw-elements}}. While this is typically the most efficient way to render a set of vertices, sometimes {{draw-arrays}} is preferable. {{render-arrays-PIPELINE-NAME}} functions identically except for calling {{draw-arrays}} instead of {{draw-elements}}.
     326
     327
     328====== Fast render functions
     329When compiled, the render function defined by {{define-pipeline}} is actually a combination of three “fast” render functions: a ''begin-render'' function, a ''render'' function, and an ''end-render'' function. The array rendering function is a similar combination: the ''begin-render'' function, an ''array-render'' function and the ''end-render'' function. This is done so that, if desired, all of the renderables that belong to the same pipeline may be rendered at the same time, without needing to perform expensive calls like program changes or texture binding more than once. To use these functions, call the ''begin-render'' function with the first renderable, then call the ''render'' (or ''array-render'') function on all renderables (including the first), finally calling the ''end-render'' function (with no arguments) to clean up.
     330
     331    (PIPELINE-NAME-fast-render-functions)
     332
     333{{define-pipeline}} does not define all of the render functions separately, but instead defines a single function with which to access them: {{PIPELINE-NAME-fast-render-functions}}, where {{PIPELINE-NAME}} is the name of the pipeline. This function returns eight values: the ''begin-render'' function, the ''render'' function, the ''end-render'' function, the ''array-render'' function, and pointers to those same C functions in that order.
    323334
    324335<parameter> unique-textures?</parameter>
     
    330341<macro> (export-pipeline . PIPELINES)</macro>
    331342
    332 Since glls-render causes {{define-pipeline}} to define multiple functions, this macro exports everything related to each pipeline in {{PIPELINES}}, except for the {{set-SHADER-NAME-renderable-UNIFORM!}} setters. These must be exported individually.
     343Since glls-render causes {{define-pipeline}} to define multiple functions, this macro exports everything related to each pipeline in {{PIPELINES}}, except for the {{set-PIPELINE-NAME-renderable-UNIFORM!}} setters. These must be exported individually.
    333344
    334345
Note: See TracChangeset for help on using the changeset viewer.