Changeset 37382 in project


Ignore:
Timestamp:
03/16/19 16:50:59 (16 months ago)
Author:
Kooda
Message:

Document glls for CHICKEN 5

File:
1 copied

Legend:

Unmodified
Added
Removed
  • wiki/eggref/5/glls

    r37369 r37382  
    22== glls
    33[[toc:]]
    4 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 recompilation is also supported. To those that want to dynamically construct shaders: I solute you.
     4glls (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 salute you.
    55
    66In 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.
     
    1010That said, while this library bears some superficial resemblance to Varjo, the approach is quite different. While Varjo does a lot of work to validate the the lispy-glls expressions (including type checking), glls only performs cursory syntactic checking. The result of this is that one could probably write shaders in Varjo without knowing the GLSL and could be reasonably sure that those shaders would always compile to something that would mostly work. glls makes no such promises, so it is entirely possible to generate GLSL that won’t compile. Being able to understand GLSL code is therefore a prerequisite for successful shader debugging. The GLSL code output by glls is beautifully formatted, thanks to Alex Shinn’s amazing [[http://synthcode.com/scheme/fmt/|fmt]] library. fmt is responsible for far more than just the GLSL formatting, since it is basically a compiler of its own. The compilation portion of glsl is more or less a thin layer on top of fmt.
    1111
    12 glls should work on Linux, Mac OS X, Windows, and with OpenGL ES. glls will automatically compile with ES support on ARM hardware, or when {{gles}} is defined during compilation (e.g. {{chicken-install -D gles}}).
     12glls should work on Linux, Mac OS X and Windows. Support for OpenGL ES is not yet in an usable state.
    1313
    1414
    1515=== Requirements
    16 * make
    1716* fmt
    1817* matchable
    1918* miscmacros
    20 * opengl-glew
     19* epoxy
     20* gl-utils
     21* srfi-1
    2122* srfi-42
     23* srfi-69
    2224
    2325
     
    2729<parameter> glsl-version</parameter>
    2830
    29 The default GLSL version used by shaders. Defaults to {{120}} on GL ES platforms, {{330}} otherwise. When compiling a file with a shader, this modifying this parameter will only take effect if you change it before the compilation phase. E.g.:
     31The default GLSL version used by shaders. Defaults to {{120}} on GL ES platforms, {{330}} otherwise. Can also be a list, see {{<version>}} under [[#shader-syntax|Shader syntax]]. When compiling a file with a shader, modifying this parameter will only take effect if you change it before the compilation phase. E.g.:
    3032
    3133<enscript highlight="scheme">   
    32 (use-for-syntax glls)
     34(import-for-syntax glls)
    3335(begin-for-syntax (glsl-version 300))
    3436</enscript>
     
    6870Defines 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}}.
    6971
    70 {{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.
     72{{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://www.upyum.com/cgit.cgi/glls/tree/examples/interactive.scm|interactive example]] for an example of how this can be accomplished.
    7173
    7274{{define-pipeline}} has additional effects when used with the {{glls-render}} module (see [[#automatic-render-functions|Automatic render functions]]).
     
    9496<procedure> (pipeline-mesh-attributes PIPELINE)</procedure>
    9597
    96 Return a list of {{(ATTRIBUTE-NAME . LOCATION)}} pairs, suitable for passing to [[http://wiki.call-cc.org/eggref/4/gl-utils|gl-utils’]] {{mesh-make-vao!}}.
     98Return a list of {{(ATTRIBUTE-NAME . LOCATION)}} pairs, suitable for passing to [[https://wiki.call-cc.org/egg/gl-utils|gl-utils’]] {{mesh-make-vao!}}.
    9799
    98100
     
    114116{{outputs}} is a list of the output variables from the shader. These are given in {{(name type)}} lists.
    115117
    116 {{version}} is the integer version number of the shader, i.e. the number you would write at the top of the shader source (e.g. {{#version 410}}). Defaults to the {{glsl-version}} parameter.
     118{{version}} is the integer version number of the shader, i.e. the number you would write at the top of the shader source (e.g. {{#version 410}}). Defaults to the {{glsl-version}} parameter. This can also be a list of the form {{'(<version> <specifiers> ...)}} where the specifiers will be appended to the {{#version}} line when compiled to glsl. For example, {{'(300 es)}} becomes {{#version 300 es}}.
    117119
    118120{{imports}} is the list of shaders that the current shader depends on. See the section [[#shaders-that-export|Shaders that export]] for more details. Defaults to {{()}}
     
    124126
    125127===== Shader Lisp
    126 For the most part, the Lisp used to define glls shaders looks like Scheme with one notable difference: types must be specified whenever a variable or function is defined. Under the hood, forms are being passed to [[https://wiki.call-cc.org/eggref/4/fmt#c-as-s-expressions|fmt]], so everything that you can do there will work in glls. Details of the Lisp used for shaders is provided in the following sections.
     128For the most part, the Lisp used to define glls shaders looks like Scheme with one notable difference: types must be specified whenever a variable or function is defined. Under the hood, forms are being passed to [[https://wiki.call-cc.org/egg/fmt#c-as-s-expressions|fmt]], so everything that you can do there will work in glls. Details of the Lisp used for shaders is provided in the following sections.
    127129
    128130It should be possible to do almost anything in glls that you would want to do with the GLSL. Known exceptions to this is are: layout qualifiers (which I don’t feel are terribly relevant in the context of Scheme, at least not until uniform locations become prevalent), do-while loops (which have no Scheme analog), and uniform blocks, {{#line}}, {{#undef}}, and struct uniforms all for no good reason. Let me know if there are any features that you find lacking.
     
    266268Shaders that export should not have any inputs or outputs.
    267269
    268 See the example [[https://github.com/AlexCharlton/glls/blob/master/examples/exports.scm|exports.scm]] to see this in action.
     270See the example [[https://www.upyum.com/cgit.cgi/glls/tree/examples/exports.scm|exports.scm]] to see this in action.
    269271
    270272
     
    292294Where {{PIPELINE-NAME}} is the name of the pipeline who’s renderables are being created.
    293295
    294 * {{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.
    295 * {{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}}.
     296* {{VAO}} – A VAO such as those returned by [[https://wiki.call-cc.org/egg/epoxy|epoxy’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.
     297* {{MODE}} – The drawing mode to use when drawing the elements of the VAO. Must be mode that is accepted by (gl-utils’) [[https://api.call-cc.org/5/doc/gl-utils/mode-%3Egl|mode->gl]]. Defaults to {{#:triangles}}.
    296298* {{N-ELEMENTS}} – The number of elements (vertices) to draw.
    297299* {{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).
    298300* {{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}}.
    299301* {{OFFSET}} – A byte offset to the location of the desired indices to draw.
    300 * {{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.
     302* {{DATA}} – An optional pointer to an appropriate glls renderable object. If not provided, a fresh renderable object will be created. [[https://www.upyum.com/cgit.cgi/glls/tree/gllsRender.h|gllsRender.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.
    301303
    302304See the [[https://www.opengl.org/sdk/docs/man/html/glDrawElements.xhtml|{{glDrawElements}} documentation]] for more information about these expected arguments.
     
    351353
    352354=== Examples
    353 These examples depends on the [[http://wiki.call-cc.org/eggref/4/glfw3|glfw3]] egg for window and context creation. The examples presented here illustrate only very basic shader definition and loading. For more complete examples, see the [[https://github.com/AlexCharlton/glls/tree/master/examples|examples directory]] of the source.
     355These examples depends on the [[https://wiki.call-cc.org/egg/glfw3|glfw3]] egg for window and context creation. The examples presented here illustrate only very basic shader definition and loading. For more complete examples, see the [[https://www.upyum.com/cgit.cgi/glls/tree/examples|examples directory]] of the source.
    354356
    355357Aside from knowing how to write glls shaders, only one macro, one function, and one record is necessary to use glls: {{define-pipeline}}, {{compile-pipelines}}, and the record {{pipeline}}. This example illustrates this minimal pipeline creation
    356358
    357359<enscript highlight="scheme">   
    358 (import chicken scheme)
    359 
    360 (use glls (prefix glfw3 glfw:) (prefix opengl-glew gl:))
     360(import scheme glls (prefix glfw3 glfw:) (prefix epoxy gl:))
    361361
    362362(define-pipeline foo
     
    373373
    374374(glfw:with-window (640 480 "Example" resizable: #f)
    375    (gl:init)
    376375   (compile-pipelines)
    377376   (print foo)
     
    382381
    383382<enscript highlight="scheme">   
    384 (import chicken scheme)
    385 
    386 (use glls (prefix glfw3 glfw:) (prefix opengl-glew gl:))
     383(import scheme glls (prefix glfw3 glfw:) (prefix epoxy gl:))
    387384
    388385(define-pipeline foo
     
    410407
    411408(glfw:with-window (640 480 "Example" resizable: #f)
    412    (gl:init)
    413409   (compile-pipelines)
    414410   (print foo)
     
    418414
    419415=== Version history
     416
     417==== Version 0.12.0
     41816 March 2019
     419
     420* Maintenance given to [[/users/kooda|Kooda]]
     421* Port to CHICKEN 5
     422
    420423
    421424==== Version 0.11.0
     
    545548
    546549=== Source repository
    547 Source available on [[https://github.com/AlexCharlton/glls|GitHub]].
    548 
    549 Bug reports and patches welcome! Bugs can be reported via GitHub or to alex.n.charlton at gmail.
    550 
    551 
    552 === Author
     550Source available [[https://www.upyum.com/cgit.cgi/glls/|here]].
     551
     552Bug reports and patches welcome! Bugs can be reported to kooda@upyum.com
     553
     554
     555=== Authors
    553556Alex Charlton
     557
     558Adrien (Kooda) Ramos
    554559
    555560
    556561=== Licence
    557562BSD
     563
Note: See TracChangeset for help on using the changeset viewer.