Changeset 30947 in project


Ignore:
Timestamp:
05/31/14 15:28:31 (6 years ago)
Author:
acharlton
Message:

Grammar, clarification

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/glls

    r30944 r30947  
    11== glls
    22[[toc:]]
    3 glls (GL Lisp Shaders) lets you write [[https://www.opengl.org/documentation/glsl/|GLSL]] (OpenGL Shader Language) shaders in a convenient pseudo-scheme language in Chicken Scheme. The compilation into GLSL happens at compile-time for zero run-time cost. Run-time compilation and dynamic re-compilation is also supported. To those that want to dynamically construct shaders: I solute you.
     3glls (GL Lisp Shaders) lets you write [[https://www.opengl.org/documentation/glsl/|GLSL]] (OpenGL Shader Language) shaders in a convenient pseudo-scheme language in Chicken Scheme. The compilation into GLSL happens at compile-time for zero run-time cost. Run-time compilation and dynamic recompilation is also supported. To those that want to dynamically construct shaders: I solute you.
    44
    55In addition to the eponymous module, glls also provides the {{glls-render}} module. {{glls-render}} enhances glls to create automatic rendering functions for each pipeline. When compiled, these rendering functions are created in efficient C, although dynamic functions are also provided. See the section [[#automatic-render-functions|Automatic render functions]] for details.
     
    3232<macro> (define-shader SHADER-NAME GLLS-SHADER)</macro>
    3333
    34 Defines, for syntax and run-time, a new {{shader}} named {{NAME}}. The (unquoted) form {{GLLS-SHADER}} should conform to language defined in the section [[#the-glls-shader-language|The glls shader language]]. Before shaders are used, they must be compiled by OpenGL with {{compile-shader}}.
     34Defines a new {{shader}} named {{NAME}}. The (unquoted) form {{GLLS-SHADER}} should conform to language defined in the section [[#the-glls-shader-language|The glls shader language]]. Before shaders are used, they must be compiled by OpenGL with {{compile-shader}}.
    3535
    3636<procedure> (create-shader GLLS-SHADER #!key INPUTS)</procedure>
    3737
    38 Creates a new {{shader}}. The form {{GLLS-SHADER}} should conform to language defined in the section [[#the-glls-shader-language|The glls shader language]]. The key {{INPUTS}} can be used to include additional inputs to the shader. Before shaders are used, they must be compiled by OpenGL with {{compile-shader}}.
     38Creates (at run-time) a new {{shader}}. The form {{GLLS-SHADER}} should conform to language defined in the section [[#the-glls-shader-language|The glls shader language]]. The key {{INPUTS}} can be used to include additional inputs to the shader. Before shaders are used, they must be compiled by OpenGL with {{compile-shader}}.
    3939
    4040<procedure> (compile-glls GLLS-SHADER #!key INPUTS)</procedure>
     
    5656<macro> (define-pipeline PIPELINE-NAME . SHADERS)</macro>
    5757
    58 Defines, for syntax and run-time, a new {{pipeline}} named {{NAME}}. The {{SHADERS}} should either be forms conforming to language defined in the section [[#the-glls-shader-language|The glls shader language]], {{shader}}s defined by {{define-shader}}, or a mix of the two. Pipelines must have at least one vertex and one fragment shader to be able to compile. Before pipelines are used, they must be compiled by OpenGL with {{compile-pipeline}} or {{compile-pipelines}}.
    59 
    60 {{define-pipeline}} behaves differently when it is being evaluated ''and'' when a given pipeline is being re-defined. In this case, the pipeline inherits the GL program ID of the pipeline that is being redefined. Additionally, the pipeline is compiled by OpenGL right away (and as a consequence, so are any pipelines that are pending compilation). This is done so that pipelines can be edited and re-evaluated in a REPL session and one’s scene will be updated as expected. See the [[https://github.com/AlexCharlton/glls/blob/master/examples/interactive.scm|interactive example]] for an example of how this can be accomplished.
     58Defines a new {{pipeline}} named {{NAME}}. The {{SHADERS}} should either be forms conforming to language defined in the section [[#the-glls-shader-language|The glls shader language]], {{shader}}s defined by {{define-shader}}, or a mix of the two. Pipelines must have at least one vertex and one fragment shader to be able to compile. Before pipelines are used, they must be compiled by OpenGL with {{compile-pipeline}} or {{compile-pipelines}}.
     59
     60{{define-pipeline}} behaves differently when it is being evaluated ''and'' when a given pipeline is being redefined. In this case, the new pipeline inherits the GL program ID of the old one. Additionally, the pipeline is compiled by OpenGL right away (and as a consequence, so are any pipelines that are pending compilation). This is done so that pipelines can be edited and reevaluated in a REPL session and one’s scene will be updated as expected. See the [[https://github.com/AlexCharlton/glls/blob/master/examples/interactive.scm|interactive example]] for an example of how this can be accomplished.
    6161
    6262{{define-pipeline}} has additional effects when used with the {{glls-render}} module (see [[#automatic-render-functions|Automatic render functions]]).
     
    6464<procedure> (create-pipeline . SHADERS)</procedure>
    6565
    66 Creates a new {{pipeline}}. The {{SHADERS}} should either be forms conforming to language defined in the section [[#the-glls-shader-language|The glls shader language]], {{shader}}s, or a mix of the two. Pipelines must have at least one vertex and one fragment shader to be able to compile. Before pipelines are used, they must be compiled by OpenGL with {{compile-pipeline}} or {{compile-pipelines}}.
     66Creates (at run-time) a new {{pipeline}}. The {{SHADERS}} should either be forms conforming to language defined in the section [[#the-glls-shader-language|The glls shader language]], {{shader}}s, or a mix of the two. Pipelines must have at least one vertex and one fragment shader to be able to compile. Before pipelines are used, they must be compiled by OpenGL with {{compile-pipeline}} or {{compile-pipelines}}.
    6767
    6868<procedure> (compile-pipeline PIPELINE)</procedure>
    6969
    70 Compile (in OpenGL) the {{PIPELINE}} and sets its {{PROGRAM}} slot to the OpenGL program ID. Compiles all of the pipeline’s shaders with {{compile-shader}}. Must be called while there is an active OpenGL context.
     70Compile (in OpenGL) the {{PIPELINE}} and sets its {{PROGRAM}} slot to the OpenGL program ID. If the pipeline’s {{PROGRAM}} slot is already set to a non-zero value, this ID will be reused for the new program. Compiles all of the pipeline’s shaders with {{compile-shader}}. Must be called while there is an active OpenGL context.
    7171
    7272<procedure> (compile-pipelines)</procedure>
     
    8888The shaders of glls – the forms that {{define-shader}}, {{define-pipeline}}, etc. expect – have the following syntax:
    8989
    90     (<type> [#:version <version>] [#:extensions <extension>] [#:pragmas <pragma>]) <inputs> <body> -> <outputs>
     90    (<type> [version: <version>] [extensions: <extension>] [pragmas: <pragma>])
     91      <inputs> <body> -> <outputs>
    9192
    9293{{type}} is the keyword type of the shader. It must be one of {{#:vertex}}, {{#:fragment}}, {{#:geometry}}, {{#:tess-control}}, {{#:tess-evaluation}}, or {{#:compute}}.
     
    9899{{pragmas}} is the list of GLSL pragmas desired (in string form). E.g. {{'("optimize(on)")}}. Defaults to {{'()}}
    99100
    100 {{inputs}} is a list of the input variables to the shader. These are given in {{(name type)}} lists. The keyword {{#:uniform}} may be used, and all following inputs will be uniforms. E.g.: {{((vertex #:vec2) (color #:vec3) #:uniform (view-matrix #:mat4))}}
     101{{inputs}} is a list of the input variables to the shader. These are given in {{(name type)}} lists. The keyword {{uniform:}} may be used, and all following inputs will be uniforms. E.g.: {{((vertex #:vec2) (color #:vec3) uniform: (view-matrix #:mat4))}}
    101102
    102103{{body}} is the form representing the code of the shader. See the section [[#shader-lisp|Shader Lisp]] for an explanation of the kind of code that is expected.
     
    145146* {{swizzle}}: {{.}} (vector swizzling, e.g. {{(swizzle color r g)}} → {{color.rg}})
    146147* {{array-ref}}, {{vector-ref}}: {{[]}} (array reference, e.g. {{(array-ref a 4)}} → {{a[4]}})
    147 * {{length}}: {{.length()}} (vector length, e.g. {{(length vec)}} → {{vec.length()}}
     148* {{length}}: {{.length()}} (vector length, e.g. {{(length vec)}} → {{vec.length()}})
    148149
    149150
    150151====== Definition
    151 Variables, functions, and records (structs) are defined much like they are in Scheme, with additional requirement of including types.
     152Variables, functions, and records (structs) are defined much like they are in Scheme, with the additional requirement of including types.
    152153
    153154    (define <name> <type> [<value>])
     
    213214
    214215==== Automatic render functions
    215 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 re-exports everything that you need from {{glls}}.
     216By 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}}.
    216217
    217218Recalling {{define-pipeline}}:
     
    229230{{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]]).
    230231
    231 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 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.
     232The {{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.
    232233
    233234
    234235===== Renderables
    235 In order to use one of the pre-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:
     236In 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:
    236237
    237238* {{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.
     
    240241* {{element-type:}} – The type of the values in the VAO’s element array. Must be one of {{+unsigned-byte+}}, {{+unsigned-short+}}, or {{+unsigned-int+}}.
    241242* {{offset:}} – A byte offset to the location of the desired indices to draw.
    242 * {{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. The are chosen based on the number of uniforms present in the pipeline.
     243* {{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.
    243244
    244245See the [[https://www.opengl.org/sdk/docs/man/html/glDrawElements.xhtml|{{glDrawElements}} documentation]] for more information about these expected arguments.
     
    276277
    277278(define-pipeline foo
    278   ((#:vertex) ((vertex #:vec2) (color #:vec3) #:uniform (mvp #:mat4))
     279  ((#:vertex) ((vertex #:vec2) (color #:vec3) uniform: (mvp #:mat4))
    279280     (define (main) #:void
    280281       (set! gl:position (* mvp (vec4 vertex 0.0 1.0)))
     
    301302
    302303(define-pipeline foo
    303   ((#:vertex) ((vertex #:vec2) (color #:vec3) #:uniform (mvp #:mat4))
     304  ((#:vertex) ((vertex #:vec2) (color #:vec3) uniform: (mvp #:mat4))
    304305     (define (main) #:void
    305306       (set! gl:position (* mvp (vec4 vertex 0.0 1.0)))
     
    312313
    313314(define-shader bar (#:vertex)
    314     ((vertex #:vec2) (color #:vec3) #:uniform (mvp #:mat4))
     315    ((vertex #:vec2) (color #:vec3) uniform: (mvp #:mat4))
    315316  (define (main) #:void
    316317    (set! gl:position (* mvp (vec4 vertex 0.0 1.0)))
     
    33533630 May 2014
    336337
    337 * Support dynamic re-evaluation of pipelines
     338* Support dynamic reevaluation of pipelines
    338339
    339340
     
    360361
    361362
    362 === Roadmap
    363 Some features that are planned for glls:
    364 
    365 * Automatic creation and compilation of rendering functions for a given pipeline
    366 * Dynamic re-compilation of pipelines suited for REPL sessions
    367 
    368 
    369363=== Source repository
    370364Source available on [[https://github.com/AlexCharlton/glls|GitHub]].
Note: See TracChangeset for help on using the changeset viewer.