cepl

CEPL (Code Evaluate Play Loop) - [Beta]

CEPL is a lispy and REPL-friendly Common Lisp library for working with OpenGL.

Its definition of success is making the user feel that GPU programming has always been part of the languages standard.

The usual approach to using CEPL is to start it at the beginning of your Lisp session and leave it open for the duration of your work. You can then treat the window it creates as just another output for your graphics, analogous to how *standard-output* is treated for text.

CEPL is in beta. The API is close to what it needs to be but there are still many bugs to fix, features to add, and experiences to smooth out.

See the cepl.examples repository for some examples of how CEPL can be used

Videos: http://www.youtube.com/playlist?list=PL2VAYZE_4wRKKr5pJzfYD1w4tKCXARs5y

Installing

Run (ql:quickload :cepl) at your REPL.

Cloning

Whilst it is recommended to get CEPL from quicklisp, if you clone please note that master is not the stable branch. Please use release-quicklisp for the stable code that will be in the next CEPL release.

Documentation

Currently we have full documentation of every exported symbol in the CEPL package. You can find this here: CEPL API Docs

Guides will be provided in future, however these take much longer to write.

I can also be reached by my email (techsnuffle [at] gmail · com) and sometimes on #lispgames IRC. Come to #lispgames anyway though, there are some lovely folks, all lispy dialects welcome!

Requirements

All of the following will be downloaded automatically by quicklisp

• cffi
• cl-opengl
• cl-plus-c
• cl-ppcre
• documentation-utils
• ieee-floats
• named-readtables
• varjo
• closer-mop
• bordeaux-threads

C Library dependency

CEPL uses OpenGL ( version >= 3.1 ) so you need to make sure it is available on your machine. Installing your GPU drivers will usually handle this.

CEPL's Host

CEPL abstracts working with OpenGL but is not responsible for creating a window or GL context; this is handled by a Host. Right now the only supported host is SDL2; the system to load is called cepl.sdl2, you can find it here: cepl.sdl2

Getting Started

Note: On OSX, slime users may want to add the code specifed in docs/single-thread-swank.md to their Emacs config file, and use the command slime-style which will start slime in a more OpenGL friendly mode. Then follow the rest of this as usual.

To load CEPL and the default host (sdl2) do the following:

• (ql:quickload :cepl.sdl2)
• (cepl:repl)

You should see an empty window appear, OpenGL is now initialized, and you can use CEPL as you like.

Making a CEPL Project

The best way to get started is to make a new project that uses CEPL. Do the following in your REPL to get set up:

• First, run (ql:quickload :cepl)
• Then run (ql:quickload :quickproject). CEPL uses this to create a lisp project using its own templates
• Then run (cepl:make-project "my-proj"). This will use quickproject to make a new project with all the correct dependencies. Remember that cepl does not handle window managers or input so by default your new project will use the following
• cepl for the graphics
• cepl.sdl2 for the host
• skitter for handling input and events
• dirt for loading images There are many good event systems & image loaders out there so browse around. But here are two :)

You are now ready to get started. Simply run: - (ql:quickload "my-proj") - (in-package :my-proj) - and finally (if you havent already) (cepl:repl)

Windows C Library Hack

If you are having issues getting the C libraries to load and just need to rule out whether Lisp can find them, try putting them in the same folder as the lisp exe. For example C:\Program Files\sbcl\.

CHANGELOG

This mainly covers features & news rather than individual bugfixes. When we are out of beta these will be covered more often

2018-02-17

BREAKING CHANGES

Due to the changes listed below you will now want to change your current asd's to require :rtg-math.vari and to change your packages to :use :rtg-math.

Some folks were asking for the ability to use their own math libraries rather than rtg-math which CEPL has depended on up until now. I have made this change but this means that this is something users will have to add themselves from now on.

For those picking a library cepl expects vectors & matrices to be sized simple-arrays of single-floats e.g. (make-array 3 :element-type 'single-float) for 3 component vectors.

We have also removed the dependency on fn & cl-fad.

Other Changes: - added the remove-surface function - closing primary window no longer quits cepl - removed interactive from lifecycle events (will add surface lifecycle events in future release)

2018-01-11

*I am terrible at changelogs. I am retroactively making the updates for everything between june 2017 and jan 2018

• Added support for using gpu-lambdas inline in defpipeline-g forms
• Lots of work on the cepl.tests project resulting in fixes for:
• gpu-lambdas
• lambda-pipelines
• struct uniforms
• uniform baking

2017-12-??

• Add render-buffer support
• Fix struct layout bugs. SSBOS work correctly now
• Add funcall-g (limited support for calling gpu-functions from cpu directly)
• Remove the deprecated g->, def-g-> & glambda macros

2017-11-??

• Add compute support
• Add SSBO support (though currently hobbled by struct layout bug)
• Add single stage pipeline support
• Add transform feedback support
• Add shared context support
• Add gpu-fence support
• Add gl query support
• Complete rewrite of pipeline state cache (now faster and safer)
• Avoid recompilation of pipelines where dependencies have not changed
• Rewrite struct code to get away from some dependencies

2017-10-??

• Multiple (non-shared) context support

2017-09-??

• Add border-color support

2017-08-??

• Mostly bugfixes

2017-07-??

• Add instance array support (per instance data in pipelines)
• Add stencil support
• Add scissor support
• Add color-mask support
• Add multisample support
• renaming macros with confusing/inconsistent naming
• blending param caching on context (not optimized yet)
• Make #'free work with pipelines

2017-06-??

• You can now modify a buffer-stream's primitive type after creation

• experimental profiler

• Huge improvements to per-frame performance through:

• typing of functions & inlining where it made sense

• fixing bug where uniforms ids queried too often

• macros to reduce frequency of fetching the context object

• much better state caching in context object

• avoiding cffi enum conversion when lookup functions are faster

• precompute & cache more size info in wrapper types

• attachments have their own viewports, no more computing of viewport during draw

• dont set viewport on every map-g (this was unnecessary)

• remove some of the 'with-*' macros whos contract forced us to do more state changes/caching that we would otherwise like.

• pipelines can be declared static. This tells cepl to type the generated functions.

• a huge pile of other small changes

2017-06-04

• pipelines can take :dynamic as their draw mode. This means they will take the draw-mode from the buffer-stream they are mapped over. This only works for pipelines with vertex & fragment stages.

• buffer-streams now hold the primitive type of their data. Defaults to :triangles

• Fix bug that was stopping g-structs contain matrices

• Cache more values in buffer-stream to save time during rendering

• Add surface-dimensions, surface-resolution, surface-title & surface-fullscreen-p

• add adjust-gpu-array (pretty basic right now)

• Remove cepl.spaces, It is now a seperate project (and will be in quicklisp in the next cycle)

• Remove cepl.misc. If you were using the draw-texture function then please consider Nineveh (which will be in quicklisp in the next cycle)

• make-project now uses dirt instead of devil. dirt uses cl-soil which ships with binaries for multiple paltforms so has a better 'out of the box' experience (plus also supports more formats)

2017-05-16

I missed some logs here so this is a recap of everything since 2017-02-19

• Geometry & Tessellation fully supported (including for inline glsl stages)

• Draw mode can now be specified for pipelines

• fixes for pull-g with gpu-functions & pipelines

• add with-gpu-array-range-as-pointer & with-gpu-array-range-as-c-array. These still feel experimental to me.

• add reallocate-gpu-array & reallocate-buffer

• buffer-streams always hold on to their gpu-arrays by default

• Refactoring based on changes in Varjo

• Added bordeux-threads as a dependency. Will be needed for some context related things

• Very basic support for multiple surfaces (windows)

• New 'host' api. Is versioned so old hosts are still supported

• remove run-session. All of these attempts at thread hackery felt bad. I'm sticking with slime-style until we have a better fix

2017-02-19

• Removed the continuable macro. The macro can be found in the livesupport project. Simply (ql:quickload :livesupport)

Copyright

Package Index

• CEPL.C-ARRAYS

  • C-ARRAY

    class

    C-ARRAY is a structure that represents an array in foreign memory.

    CEPL keeps not only the pointer to the foreign data in this structure but also metadata that makes moving this data to (and from) the gpu or lisp much easier.

  • ( AREF-C C-ARRAY &REST SUBSCRIPTS )

    accessor

    Accesses the c-array element specified by the subscripts

  • ( AREF-C* C-ARRAY SUBSCRIPTS )

    accessor

    Accesses the c-array element specified by the subscripts.

    The difference between this and aref-c is that this this function takes the subscripts as a list.

  • ( C-ARRAY-DIMENSIONS INSTANCE )

    accessor

    C-ARRAY-DIMENSIONS takes a c-array as an argument and returns the dimensions of the c-array

    You can also use the generic function DIMENSIONS to get the same result.

  • ( C-ARRAY-ELEMENT-TYPE INSTANCE )

    accessor

    C-ARRAY-POINTER takes a c-array as an argument and returns the type of the elements of the array.

    You can also use the generic function ELEMENT-TYPE to get the same result.

  • ( C-ARRAY-POINTER INSTANCE )

    accessor

    C-ARRAY-POINTER takes a c-array as an argument and returns the pointer to the foreign data.

    You can also use the generic function POINTER to get the same result.

  • ( C-ARRAY-TOTAL-SIZE INSTANCE )

    accessor

    No docstring provided.

  • ( ACROSS-C-PTR FUNCTION C-ARRAY )

    function

    This function takes two arguments:

    • A function that takes a pointer and a (unsigned-byte 32)
    • A c-array

    across-c-ptr will then call the given function once for every element in the c-array passing in the pointer to an element of the array and the index to that element.

  • ( C-ARRAY-P OBJECT )

    function

    Return t if the argument is a c-array. Returns nil otherwise.

  • ( CLONE-C-ARRAY C-ARRAY )

    function

    Takes a c-array and makes a new c-array with the same contents as the the original. The contents in foreign memory are copied.

  • ( FREE-C-ARRAY C-ARRAY )

    function

    Frees the foreign memory allocated with the c-array and 'blanks' the c-array.

    Blanking the c-array means its fields will be set to default values, for example dimensions will be 0, the pointer will be null etc.

    The generic function free will call free-c-array when passed a c-array.

  • ( MAKE-C-ARRAY INITIAL-CONTENTS &KEY DIMENSIONS ELEMENT-TYPE )

    function

    This function will make and return a new c-array.

    It can be used in a few different ways:

    • with :initial-contents to nil: In this case you need to provide dimensions and an element-type.

    • with :initial-contents populated. The initial-contents can be a (potentially nested) list or array.

    When :initial-contents is an array then the dimension of the c-array will be the same as the array passed in. CEPL currently only supports up to 4D c-arrays.

    When the :initial-contents is a flat list then each element is used as one element in the c-array. If the :initial-contents is a nested list then you must either:

    • specify multiple dimensions and an element-type
    • specify an element-type to be some struct type, then nested lists are then used to populate the fields of the foreign structs. For an example of this please see this example.

    If the :element-type is not provided then CEPL will look at every element in the initial-contents and try and find the smallest (in bytes) foreign type which works for every element. This mean if the array is full of single-floats then CEPL will choose :float, not :double. Naturally this behaviour is too slow for use in performance critical applications however it is nice for experimentation and working from the repl.

    If you need what would be called a displaced array in lisp then please see the subseq-c function.

  • ( MAKE-C-ARRAY-FROM-POINTER DIMENSIONS ELEMENT-TYPE POINTER &KEY (FREE (FUNCTION FOREIGN-FREE)) ELEMENT-BYTE-SIZE )

    function

    Will create a CEPL c-array with the element-type and dimensions specified, and will store the pointer as where the data is expected to be.

    This function does allocate the memory or validate the type or dimensions so be very careful when using this function.

  • ( MAP-C FUNCTION C-ARRAY &OPTIONAL (DESTINATION-ELEMENT-TYPE NIL) )

    function

    When given a function and a c-array this function will map the function across every element of the c-array and write the results of the function into a new c-array with the same element-type and dimensions as the original c-array.

    You may also pass in an optional foreign type that will be used as the element type of the new array.

    If, rather than making a new c-array, you wish to modify the given c-array you should use map-c-into instead.

  • ( MAP-C-INTO DESTINATION-C-ARRAY FUNCTION SOURCE-C-ARRAY )

    function

    When given a destination c-array, a function and a source c-array this function will map the function across every element of the source c-array and write the results of the function destrucively into the destination c-array.

  • ( PTR-INDEX C-ARRAY &OPTIONAL (X 0) (Y 0 Y-SET) (Z 0 Z-SET) (W 0 W-SET) )

    function

    This function takes a c-array and some subscripts and will return the ptr to the specified element of the c-array

  • ( ROW-MAJOR-AREF-C C-ARRAY INDEX )

    function

    No docstring provided.

  • ( SUBSEQ-C ARRAY START &OPTIONAL (END NIL) )

    function

    This function returns a c-array which contains a subset of the array passed into this function.

    It does not copy the foreign data, instead this array points to within the data of the original array. This means these arrays now share data (like a displaced array in standard CL.

    Due to this you have to be very careful when freeing the underlying array as this will affect any other array sharing that data.

    If you want a copy of a subseq of a c-array then use something like:

    (clone-c-array (subseq-c arr 3 10))
    

    The reason that this arguably more dangerous behaviour is default is efficiency. CEPL tries not to allocate new memory when the function is not explicitly about that.

  • ( ELEMENT-BYTE-SIZE ARRAY )

    generic

    Returns the size in bytes taken up by a single element of the c-array.

  • ( ELEMENT-TYPE ARRAY )

    generic

    Returns the type of the elements in the c-array.

  • ( POINTER C-ARRAY )

    generic

    Returns the pointer to the start of the foreign data that makes up the array

  • ( WITH-C-ARRAY-FREED (VAR-NAME C-ARRAY) &BODY BODY )

    macro

    Binds the c-array to the variable named by the var-name argument. Frees the c-array at the end of the scope.

  • ( WITH-C-ARRAYS-FREED (VAR-NAME C-ARRAYS) &BODY BODY )

    macro

    Binds a list of c-arrays to the variable named by the var-name argument. Frees all of the c-arrays at the end of the scope.

• CEPL.GPU-ARRAYS

  • GPU-ARRAY

    class

    GPU-ARRAY is a structure that represents an array in gpu-memory.

    Depending on how the array was created it is said that the gpu-array is either 'buffer-backed' or 'texture-backed'.

    • buffer-backed: Means it was created with make-gpu-array or make-gpu-arrays The data is stored in a gpu-buffer.
    • texture-backed: Means it was created along with a texture. Textures are structures that contain some number of gpu-arrays. The data is stored in texture memory. See texture for more details.

    Both have different use cases and allow different element types, however they are both an ordered block of typed data. They can have multiple dimensions and you can push-g and pull-g data to and from them.

    Note for folks who are used to OpenGL: texture-backed gpu-arrays are what opengl would normally call 'images'. This is a pretty terrible name for them as it implies they only can hold image data, or that they are 2d only. In fact 'images' can have 1 to 3 dimensions, can have elements that are single bytes, floats, vectors of either or a large number of other types. 'image' belies this nature and so CEPL chooses 'array'

    This also matches how the GLWiki chooses to explain them:

    an image is defined as a single array of pixels of a certain dimensionality (1D, 2D, or 3D), with a particular size, and a specific format.

  • ( GPU-ARRAY-DIMENSIONS INSTANCE )

    accessor

    Return a list whose elements are the dimensions of the array.

    You can also use the generic function dimensions to get this info.

  • ( BACKED-BY GPU-ARRAY )

    function

    This function takes a gpu-array and returns either :texture or :buffer depending on whether it is a texture-backed gpu-array or a buffer-backed gpu-array.

  • ( GPU-ARRAY-ACCESS-STYLE GPU-ARRAY )

    function

    When passed a buffer-backed gpu-array this function will return the access-style of the underlying gpu-buffer.

    The access-style of a gpu-array (or gpu-buffer) is a hint to OpenGL on how you intend to use the array. It is optional whether your gpu manufacturer's implementation of GL takes any notice of this option. When they do take notice of it, it will to optimize access to the underlying data.

    There are also no repercussions for accessing the data in a way contrary to the declared access-style (other than potential performance costs).

  • ( GPU-ARRAY-BUFFER GPU-ARRAY )

    function

    When passed a buffer-backed gpu-array this function will return the gpu-buffer backing this array.

    Note that if you made the array with make-gpu-arrays then there will be multiple gpu-arrays sharing this buffer, so care should be taken when modifying or freeing data.

  • ( GPU-ARRAY-ELEMENT-TYPE GPU-ARRAY )

    function

    Will return the type of the elements in the gpu-array given.

    If this is a texture-backed gpu-array then the element-type will be the same as the 'image-format' of the texture.

  • ( GPU-ARRAY-FACE-NUM GPU-ARRAY )

    function

    When passed a texture-backed gpu-array this function will return the index of the texture's cubeface that contains this gpu-array. This only truly applies to gpu-arrays belonging to cubemap textures, for all gpu-arrays this number will always be 0.

  • ( GPU-ARRAY-LAYER-NUM GPU-ARRAY )

    function

    When passed a texture-backed gpu-array this function will return the index of the gpu-array within the array-textures. This only truly applies to gpu-arrays belonging to array-textures, for all gpu-arrays this number will always be 0.

  • ( GPU-ARRAY-LEVEL-NUM GPU-ARRAY )

    function

    When passed a texture-backed gpu-array this function will return the mipmap level the gpu-array resides on within the texture.

    This only truly applies to gpu-arrays with mipmaps, for all gpu-arrays this number will always be 0.

  • ( GPU-ARRAY-P OBJECT )

    function

    Will return t if the value given is a gpu-array.

    This will return t for both texture-backed and buffer-backed gpu-arrays

  • ( GPU-ARRAY-TEXTURE-TYPE GPU-ARRAY )

    function

    When passed a texture-backed gpu-array this function will return the type of the texture containing this gpu-array.

    The result will be one of the following:

    :texture-1d
    :texture-2d
    :texture-3d
    :texture-1d-array
    :texture-2d-array
    :texture-cube-map
    :texture-cube-map-array
    :texture-rectangle
    :texture-buffer
    :texture-buffer
    :texture-buffer
    :texture-2d-multisample
    :texture-2d-multisample-array
    

  • ( MAKE-GPU-ARRAYS C-ARRAYS &KEY (ACCESS-STYLE :STATIC-DRAW) )

    function

    This function takes a list of x c-arrays and returns a list of x buffer-backed gpu-arrays.

    The reason to use this rather than:

    (mapcar `make-gpu-array` c-arrays-list)
    

    is that all of the gpu-arrays created will share the same gpu-buffer.

    Usually you will know if you need this instead of make-gpu-array as you will have some behaviour or performance characteristic in mind.

  • ( REALLOCATE-GPU-ARRAY GPU-ARRAY )

    function

    This function takes a gpu-array and reallocates the buffer that is backing it.

  • ( SUBSEQ-G ARRAY START &OPTIONAL (END NIL) )

    function

    This function returns a gpu-array which contains a subset of the gpu-array passed into this function.

    It does not copy the foreign data, instead this array points to within the data of the original array. This means these arrays now share data (like a displaced array in standard CL.

    Due to this you have to be very careful when freeing the underlying array as this will affect any other array sharing that data.

    The reason that this arguably more dangerous behaviour is default is efficiency. Mofidying gpu memory in performance critical applications should be done at specific times so as not to get blocked by rendering commands. As such CEPL tries not to allocate new memory when the function is not explicitly about that.

  • ( FREE-GPU-ARRAY GPU-ARRAY )

    generic

    When given a buffer-backed gpu-array this will do one of three things:

    If the gpu-array is the only gpu-array in the gpu-buffer then the gpu-buffer is freed and the gpu-array is blanked.

    If the gpu-array shares a gpu-buffer with other gpu-arrays and they are still live then blank this gpu-array.

    If the gpu-array shared a gpu-buffer with other gpu-buffer but they have all been freed then free the gpu-buffer and blank the gpu-array.

    Blanking the gpu-array means its fields will be set to default values, for example dimensions will be nil, the texture will be null etc.

    The generic function free will call #'free-gpu-array when passed a gpu-array.

  • ( MAKE-GPU-ARRAY INITIAL-CONTENTS &KEY DIMENSIONS ELEMENT-TYPE ACCESS-STYLE )

    generic

    This function creates a buffer-backed gpu-array. Texture-backed gpu-array can only be created via #'make-texture

    make-gpu-array is very similar to make-c-array.

    It can be used in a few different ways:

    • with :initial-contents to nil: In this case you need to provide dimensions and an element-type.

    • with :initial-contents populated. The initial-contents can be a (potentially nested) list, array or c-array.

    When the :initial-contents are a c-array then the dimensions and element-type are taken from the c-array. As the data is already in foreign memory the upload will be notable faster that from lisp-data->gpu as no type conversions are needed

    When the :initial-contents are an array then the dimension of the gpu-array will be the same as the array passed in. CEPL currently only supports up to 4D gpu-arrays.

    When the :initial-contents is a flat list then each element is used as one element in the gpu-array.

    If the :initial-contents is a nested list then you must either:

    • specify multiple dimensions and an element-type
    • specify an element-type to be some struct type, then nested lists are then used to populate the fields of the foreign structs. For an example of this please see this example.

    If the :element-type is not provided then CEPL will look at every element in the initial-contents and try and find the smallest (in bytes) foreign type which works for every element. This mean if the array is full of single-floats then CEPL will choose :float, not :double. Naturally this behaviour is too slow for use in performance critical applications however it is nice for experimentation and working from the repl.

    If you need what would be called a displaced array in lisp then please see the subseq-g function.

    Access style is optional but if you are comfortable with opengl, and know what type of usage pattern this array will have, you can set this to any of the following:

    The access-style argument is a hint to OpenGL on how you intend to use the array. It is optional whether your gpu manufacturer's implementation of GL takes any notice of this option. When they do take notice of it, it will to optimize access to the underlying data.

    There are also no repercussions for accessing the data in a way contrary to the declared access-style (other than potential performance costs).

    :stream-draw  :static-draw  :dynamic-draw
    :stream-read  :static-read  :dynamic-read
    :stream-copy  :static-copy  :dynamic-copy
    

  • ( WITH-GPU-ARRAY-AS-C-ARRAY (TEMP-NAME GPU-ARRAY &KEY (ACCESS-TYPE)) &BODY BODY )

    macro

    This macro takes a gpu-array and asks OpenGL to temporarily 'map' it to a c-array. Within the scope of the body you can run any of the c-array commands on it.

    This macro is really helpful if you need to have random access to the data in the gpu-array.

    A simple example would be if we wanted to set the 3rd element in a gpu array to 5.0 we could do the following:

    (with-gpu-array-as-c-array (tmp-c-arr my-gpu-array)
      (setf (aref-c tmp-c-arr 2) 5.0))
    

    The reason we provide this and not a function like aref-c for gpu-arrays is that it would give the impression that this kind of operation is cheap, which it is not. There are cases where using with-gpu-array-as-c-array will perform better than push-g and there cases where the opposite is true.

    Generally this will be to do with how much of the block of memory is being updated, but it is best to consult current graphics programming texts to find out the details.

    The valid values for the :access argument are :read-only :write-only or :read-write.

  • ( WITH-GPU-ARRAY-AS-POINTER (TEMP-NAME GPU-ARRAY &KEY (ACCESS-TYPE) (TARGET)) &BODY BODY )

    macro

    This macro takes a gpu-array and asks OpenGL to temporarily 'map' it to a pointer. Within the scope of the body you can run any cffi command on it.

    This macro is really helpful if you need to have random access to the data in the gpu-array.

    The valid values for the :access argument are :read-only :write-only or :read-write.

  • ( WITH-GPU-ARRAY-RANGE-AS-C-ARRAY (TEMP-NAME GPU-ARRAY START-INDEX LENGTH &KEY (ACCESS-SET)) &BODY BODY )

    macro

    This macro takes a gpu-array and asks OpenGL to temporarily 'map' it a portion of it to a c-array. Within the scope of the body you can run any of the c-array commands on it.

    This macro is really helpful if you need to have random access to the data in the gpu-array.

    A simple example would be if we wanted to set the 3rd element in a gpu array to 5.0 we could do the following:

    (with-gpu-array-range-as-c-array (tmp-c-arr my-gpu-array 10 20)
      (setf (aref-c tmp-c-arr 2) 5.0))
    

    The reason we provide this and not a function like aref-c for gpu-arrays is that it would give the impression that this kind of operation is cheap, which it is not. There are cases where using with-gpu-array-as-c-array will perform better than push-g and there cases where the opposite is true. Generally this will be to do with how much of the block of memory is being updated, but it is best to consult current graphics programming texts to find out the details.

    The valid values for the :access argument are :read-only :write-only or :read-write.

  • ( WITH-GPU-ARRAY-RANGE-AS-POINTER (TEMP-NAME GPU-ARRAY START-INDEX LENGTH &KEY (ACCESS-SET) (TARGET)) &BODY BODY )

    macro

    This macro takes a gpu-array and asks OpenGL to temporarily 'map' a portion ofit to a pointer. Within the scope of the body you can run any cffi command on it.

    This macro is really helpful if you need to have random access to the data in the gpu-array.

    The valid values for the :access argument are :read-only :write-only or :read-write.

• CEPL.STREAMS

  • BUFFER-STREAM

    class

    A buffer-stream is a structure that represents stream of gpu-data composed from gpu-array and/or gpu-buffers.

    To render in CEPL we map a buffer-stream over a gpu-pipeline. The buffer-stream contains data (usually geometry) that is passed to the vertex-shader.

    A buffer-stream composes various sources of gpu-data together. So if, for example, the vertex shader took 3 arguments of types :vec2 :vec3 :float. Then you could make a stream that composes 3 gpu-arrays with element-types :vec2 :vec3 :float and map this over the pipeline.

    Naturally, as we are talking about buffer-stream, only buffer-backed gpu-arrays can be composed with buffer-streams.

    Info for people used to OpenGL: A buffer-stream is basically a VAO with some extra metadata such as the 'range' of data to draw the 'style' of drawing & the 'primitive' the data represents .

  • ( BUFFER-STREAM-GPU-ARRAYS INSTANCE )

    accessor

    When you construct a buffer-stream it will (by default) hold onto the gpu-arrays that were composed.

    This function when given a buffer-stream will return those stored gpu-arrays

  • ( BUFFER-STREAM-INDEX-TYPE STREAM )

    accessor

    When passed a buffer-stream with an index this function will return the element-type of the index-data.

  • ( BUFFER-STREAM-LENGTH INSTANCE )

    accessor

    Returns the number of elements in the buffer-stream

  • ( BUFFER-STREAM-PRIMITIVE STREAM )

    accessor

    This function returns the primitive that the data pulled from buffer stream represents.

    The primitive says what the gpu will draw this data as. It can be any one of:

    :points :lines :line-loop :line-strip :lines-adjacency :line-strip-adjacency :triangles :triangle-fan :triangle-strip :triangles-adjacency :triangle-strip-adjacency (:patch )

    By default the primitive-type is :triangles

  • ( BUFFER-STREAM-VAO INSTANCE )

    accessor

    Returns the OpenGL Vertex Array Object (VAO) owned by this stream.

    Do not modify this unless you are sure what you are doing. In most cases you do not need to interact with the VAO directly

  • ( BUFFER-STREAM-P OBJECT )

    function

    Returns t if the value passed is a buffer-stream

  • ( FREE-BUFFER-STREAM BUFFER-STREAM )

    function

    Calling this with a buffer-stream will free the VAO owned by this buffer-stream and blank the buffer-stream object.

    It will not free any of the gpu-data that was composed to make this stream.

    Calling the generic function free with a buffer-stream will call this function

  • ( MAKE-BUFFER-STREAM GPU-ARRAYS &KEY INDEX-ARRAY (START 0) LENGTH (RETAIN-ARRAYS T) (PRIMITIVE :TRIANGLES) )

    function

    This function composes a number of gpu-arrays into a buffer-stream. No data is copied, the buffer-stream simply refers to the gpu-arrays so the gpu knows where to pull data from.

    You can optionally pass a gpu-array to act as an index into the other arrays.

    Usually when you map over a buffer-stream it will call the pipeline pulling 1 value from each of the composed gpu-arrays on each 'iteration'[0]. When you have an index then map-g will pull 1 value from index each 'iteration' and use that to pick which value to use from the other arrays. This approach gives bigs boosts in performance and memory usage when rendering.

    The element-type of the index-array must be of the following: :uint8 :ushort :uint :unsigned-short :unsigned-int

    As well as an element type you also can specify the primitive-type. This says what the gpu will draw this data as. It can be any one of:

    :points :lines :line-loop :line-strip :lines-adjacency :line-strip-adjacency :triangles :triangle-fan :triangle-strip :triangles-adjacency :triangle-strip-adjacency (:patch )

    By default the primitive-type is :triangles

    It is also worth noting that you can also use gpu-sub-arrays in here if you want to limit the data you are using, for example the following is perfectly legal code:

    (make-buffer-stream
      :gpu-arrays `(,(gpu-sub-array monster-pos-data 1000 2000)
                   ,(gpu-sub-array monster-col-data 1000 2000))
      :index-array monster-index-array
      :length 1000)
    

    [0] The use of the term 'iteration' here is quoted as the gpu is going to be doing this work in parallel, however it makes the explanation clearer so that is why it is there. If you have a clearer way of explaining the behaviour please file it as an issue on github.

• CEPL.VIEWPORTS

  • VIEWPORT

    class

    Viewport is a structure that represents a retangular region of the surface that CEPL can draw into.

    There is always a viewport current when rendering. If one of your own is not current then CEPL will use its default viewport, the resolution of which is the same as that of the surface when it was created.

    The default viewport can be modified, so feel free to update the resolution if the surface size changes.

  • ( VIEWPORT OBJ )

    accessor

    This is a placeholder generic function for future apis. Feel free to implement this in your own programs when yo want to get a viewport from some container

  • ( VIEWPORT-DIMENSIONS VIEWPORT )

    accessor

    This function returns the resolution of the viewport as a list of integers

    If you call the generic function dimensions with a viewport you will get this value.

    If you need this value as a vec2 use viewport-resolution or just the generic function resolution

  • ( VIEWPORT-ORIGIN VIEWPORT )

    accessor

    This function returns the origin of the viewport.

    This is the top-left corner of the rectangle within the surface that OpenGL (and thus CEPL) will draw into

  • ( VIEWPORT-RESOLUTION VIEWPORT )

    accessor

    This function returns the resolution of the viewport as a vec2

    If you call the generic function resolution with a viewport you will get this value.

    If you need this value as a list use viewport-dimensions or just the generic function dimensions

  • ( COPY-VIEWPORT INSTANCE )

    function

    This function returns a new viewport with identical origin and resolution to the viewport provided.

  • ( CURRENT-VIEWPORT &OPTIONAL (CEPL-CONTEXT (CEPL-CONTEXT)) )

    function

    This function returns the viewport that is current in this scope.

    If no other code in the callstack has used with-viewport or with-fbo-viewport then the result will be the default viewport.

  • ( MAKE-VIEWPORT &OPTIONAL (RESOLUTION '(320 240)) (ORIGIN '(0 0)) )

    function

    This function returns a new viewport with the specified resolution and origin

  • ( VIEWPORT-EQL V0 V1 )

    function

    This function returns t if the two viewports have the same resolution and origin.

  • ( VIEWPORT-P OBJECT )

    function

    This function will return t if the value given is a viewport, otherwise it will return nil

  • ( VIEWPORT-PARAMS-TO-VEC4 &OPTIONAL (VIEWPORT (CURRENT-VIEWPORT)) )

    function

    Will return a vec4 packed with the origin and resolution. The format is as follows:

    (v! origin-x origin-y resolution-x resolution-y)
    

    If now viewport is provided the the current-viewport is used.

  • ( VIEWPORT-RESOLUTION-X VIEWPORT )

    function

    This function returns the x component of the resolution of the viewport as a float.

  • ( VIEWPORT-RESOLUTION-Y VIEWPORT )

    function

    This function returns the y component of the resolution of the viewport as a float.

  • ( WITH-FBO-VIEWPORT (FBO &OPTIONAL (ATTACHMENT)) &BODY BODY )

    macro

    This macro behaves similarly to with-viewport in that is sets the current viewport. However rather than passing in a viewport, one is created[0] based on the dimensions of the gpu-array bound as the specified attachment to the given fbo.

    By default color-attachment0 will be used but you can provide your own attachment index using the :attachment argument.

    It will remain as the current-viewport until the end of the scope.

    [0] CEPL is free to reuse internal viewport objects where it makes sense instead of consing up a new viewport. This means that the viewport inside the scope may be eq to the viewport outside, but with different values in its slots for the duration of the body.

  • ( WITH-VIEWPORT VIEWPORT &BODY BODY )

    macro

    This macro sets the current viewport to the viewport given as the argument. It will remain as the current-viewport until the end of the scope.

• CEPL.TEXTURES

  • *IMMUTABLE-AVAILABLE*

    special

    After CEPL has been initialized this variable will hold t if immutable texture storage is available and nil if not.

    Immutable texture storage does not mean that the texture's gpu-array data is immutable. It means that the underlying format of the texture data cannot be changed. It is rare that you would want mutable storage and when you do, it is very hard to not create 'incomplete-textures'. https://www.opengl.org/wiki/Immutable_Storage_Texture#Texture_completeness

    CEPL tries to make only complete textures so this is not a concern. If you do need this level of control, please raise a github issue as I would love to understand your usecase.

  • BUFFER-TEXTURE

    class

    Buffer-textures are a special kind of texture where the data resides, not in texture memory, but in buffer memory.

    This means that when you call texref on this texture you will recieve a buffer-backed texture instead of the usual texture-backed ones.

    buffer-textures are created by calling make-texture with the :buffer key argument set to t.

    Buffer textures have limitations over regular textures:

    • cannot be mipmapped
    • can only only have one gpu-array
    • that gpu-array must be one dimensional
    • can only be accessed in shaders with #'texel-fetch
    • can have a more limited number of valid element-types[0] to choose from see valid-image-formats-for-buffer-backed-texture for details

    [0] OpenGL calls the element-types of textures 'image-formats' or sometimes 'internal-formats'. Even though the name implies they are only useful for image data we keep the name as the subject of image-formats is complicated enough without us adding more things to think about

  • TEXTURE

    class

    Textures are structures that hold a number of gpu-arrays that all have the same element-type.

    Textures can be used as a source of data or can be attached to an fbo, which means you can render into them instead of to the screen[0].

    These texture-backed arrays cannot contain arbitrary data, they are specific formats that are allowed in specific circumstances. CEPL makes working with these as smooth as possible, but the details are confusing and the best sources of information for the nitty-gritty are the GL-Wiki and the GL-Specification.

    -- Texture Types --

    The textures themselves have a number of configurations (known from here on as 'texture-types') that are allowed:

    :texture-1d
    Gpu-Arrays in this texture all are 1-dimensional.
    
    :texture-2d
    Gpu-Arrays in this texture all are 2-dimensional.
    
    :texture-3d
    Gpu-Arrays in this texture all are 3-dimensional.
    
    :texture-rectangle
    This texture only has one 2-dimensional gpu-array. The texture cannot have
    mipmapping. Texture coordinates used for these textures are not normalized.
    
    :texture-buffer
    See the documentation for `buffer-texture` for details
    
    :texture-cube-map
    There are exactly 6 distinct sets of 2D gpu-arrays, all of the same size.
    They act as 6 faces of a cube.
    
    :texture-1d-array
    Gpu-Arrays in this texture all are 1-dimensional. However, it contains
    multiple sets of 1-dimensional gpu-arrays, all within one texture.
    
    :texture-2d-array
    Gpu-Arrays in this texture all are 2-dimensional. However, it contains
    multiple sets of 2-dimensional gpu-arrays, all within one texture.
    
    :texture-cube-map-array
    Gpu-Arrays in this texture are all cube maps. It contains multiple sets of
    cube maps, all within one texture.
    
    :texture-2d-multisample & :texture-2d-multisample-array
    Not currently supported in CEPL
    

    -- Element Types --

    Unlike c-array and gpu-arrays (which use foreign types for their elements) textures have a different set of acceptable format. These are called 'image formats'.

    The name may imply that these formats are only usable for image data but this is not the case. Most of the types we are used to are there, but under unsual names.

    This would make this a ripe candidate for CEPL to clean up the naming.. but it doesnt, why?

    Well the answer to that is image-formats are damn confusing and if we change too much of the naming it will be even more confusing when trying to google information. Instead CEPL provides a number of functions for converting between (foreign) lisp types and their image-format counterparts.

    -- Mip Maps --

    When a texture is applied to a surface, the number of the texture's pixels (commonly called 'texels') that are used depends on the angle at which that surface is rendered. For example if we were rendering a TV then when it is almost side on we will use much less pixels that if we were rendering it from the front. At that point the gpu has to pick which texels from the texture to use. When an object is moving (or the camera is) the texels that are chosen to be drawn each frame will not be the same, this causes nasty visual artifacts.

    To get around this, gpus employ mip maps. These are pre-shrunk versions of the full-sized gpu-array. Each mipmap is half the size of the previous one in the chain. So a 64x16 2D texture can have 6 mip-maps: 32x8, 16x4, 8x2, 4x1, 2x1, and 1x1.

    OpenGL does not require that the entire mipmap chain is complete; you can specify what range of mipmaps in a texture are available.

    Some texture types have multiple independent sets of mipmaps. Each face of a cubemap has its own set of mipmaps, as does each entry in an array texture.

    When sampling a texture (see below), the implementation will automatically select which mipmap to use based on the viewing angle, size of texture, and various other factors.

    -- Mutable or Immutable Storage --

    First we will explain what this is not, this is not about whether you can change the contents of the gpu-arrays after the texture is created. It is about whether you can redefine the 'nature' of the data stored in the gpu-arrays after they are created, by that we mean things like the type of the data, the resolution of the gpu-arrays.

    It is hard to do without creating an 'incomplete' texture [1] and so CEPL opts to treat all textures as immutable textures. When the OpenGL version doesnt support immutable texture storage CEPL makes uses immutable storage, allocates all the memory at construction, and doesnt provide abstractions over the opengl features that would modify the storage.

    -- Sampling --

    Sampling is the process of fetching a value from a texture at a given position. It is interesting as, because of things like mipmaping, the usual case is that reading a single value from a texture involves reading from more than one of its gpu-arrays and combining the resultson some fashion.

    To control this process GL (and thus CEPL) have a special object called a sampler. Samplers have a number of values that can be tweaked that affect how the sampling is done.

    To find out more see the cepl.samplers section.

    [0] - more correctly the default-fbo

    [1] - glwiki: texture completeness

  • ( TEXTURE-BASE-DIMENSIONS INSTANCE )

    accessor

    Returns the resolution of the gpu-array at the 'base-level' of the mipmap chain. The base level is the largest one.

  • ( TEXTURE-CUBES-P INSTANCE )

    accessor

    This function returns t if the texture is a cube texture and nil otherwise

  • ( TEXTURE-ID INSTANCE )

    accessor

    This function returns the id of the GL Texture Object from the CEPL texture.

    Don't use this unless you know what you are doing on the GL side.

  • ( TEXTURE-LAYER-COUNT INSTANCE )

    accessor

    When called with a texture with one of the following texture-types: :texture-1d-array :texture-2d-array :texture-cube-map-array

    then this function returns the number of 'layers' in the texture.

    For all other texture types this will return 0

  • ( TEXTURE-MIPMAP-LEVELS INSTANCE )

    accessor

    When called with a texture with mipmaps enabled this function returns the number of 'mipmap levels' in the texture.

    For all other texture types this will return 0

  • ( TEXTURE-MUTABLE-P INSTANCE )

    accessor

    When called with a texture this function returns t if the texture was made with mutable texture storage and nil otherwise.

    Using immutable texture storage does not mean that the data inside the texture's gpu-arrays cannot be mutated.

    Mutable texture storage allows you to redefine the 'nature' of the data stored in the gpu-arrays after they are created, by that we mean things like the type of the data, the resolution of the gpu-arrays.

    As it is hard to change such things without creating an 'incomplete' texture[0] CEPL opts to treat all textures as immutable textures. When the OpenGL version doesnt support immutable texture storage CEPL makes uses immutable storage, allocates all the memory at construction, and doesnt provide abstractions over the opengl features that would modify the storage.

    [0] - https://www.opengl.org/wiki/Immutable_Storage_Texture#Texture_completeness

  • ( TEXTURE-TYPE INSTANCE )

    accessor

    This function will return the type of the given texture.

    The possible values are:

    :texture-1d
    :texture-2d
    :texture-3d
    :texture-rectangle
    :texture-buffer
    :texture-cube-map
    :texture-1d-array
    :texture-2d-array
    :texture-cube-map-array
    :texture-2d-multisample
    :texture-2d-multisample-array
    

  • ( BUFFER-TEXTURE-P OBJECT )

    function

    Return t if the given value is a texture who data is stored in a gpu-buffer as opposed to the usual texture memory. Returns nil otherwise

  • ( GENERATE-MIPMAPS TEXTURE )

    function

    Calling this with a texture asks OpenGL to generate mipmaps for the texture.

    You do not normally need to use this function as you can use the :mipmaps argument on make-texture. See make-texture for more details.

  • ( MAKE-TEXTURE INITIAL-CONTENTS &KEY DIMENSIONS ELEMENT-TYPE (MIPMAP NIL) (LAYER-COUNT 1) (CUBES NIL) (RECTANGLE NIL) (IMMUTABLE T) (BUFFER-STORAGE NIL) (GENERATE-MIPMAPS T) PIXEL-FORMAT (SAMPLES NIL) (FIXED-SAMPLE-LOCATIONS NIL) )

    function

    This function allows you to make any kind of texture based on the arguments provided. Whilst the signature is quite intimidating your rarely need to use more than a few of the arguments to make a given texture.

    For example:

    (make-texture '(1 2 3 4))
    

    will give you a valid texture.

    We will now go through the arguments and their behaviours:

    -- :initial-contents :dimensions & :element-type --

    • with :initial-contents to nil: In this case you need to provide dimensions and an element-type.

    • with :initial-contents populated. The initial-contents can be a (potentially nested) list, array or c-array.

    When the :initial-contents are a c-array then the dimensions and element-type are taken from the c-array. As the data is already in foreign memory the upload will be notable faster that from lisp-data->gpu as no type conversions are needed

    When the :initial-contents are an array then the dimension of the texture will be the same as the array passed in. Remember OpenGL only allows up to 3 dimensions for the textures

    When the :initial-contents is a flat list then each element is used as one element in the textures gpu-array

    If the :initial-contents is a nested list then you must either:

    • specify multiple dimensions and an element-type
    • specify an element-type to be some struct type, then nested lists are then used to populate the fields of the foreign structs. For an example of this please see this example: https://github.com/cbaggers/cepl.examples/blob/master/examples/triangle.lisp#L30.

    If the :element-type is not provided then CEPL will look at every element in the initial-contents and try and find the smallest (in bytes) foreign type which works for every element. This mean if the array is full of single-floats then CEPL will choose :float, not :double. Naturally this behaviour is too slow for use in performance critical applications however it is nice for experimentation and working from the repl.

    Extra element-type details: Unlike c-array and gpu-arrays (which use foreign types for their elements) textures have a different set of acceptable element-types. These are called 'image formats'.

    If you provide a GL image-format as the :element-type CEPL will use it directly

    If you provide a (foreign) lisp type then CEPL will try to find the appropriate image-format for that type.

    -- :pixel-format --

    If this optional argument is not nil, then CEPL will use the pixel format provided when uploading the pixel data.

    Usually this is not provided as CEPL can calculate a valid pixel-format to use from the element-type.

    -- :mipmap & :generate-mipmaps --

    If this is set to t then CEPL will make mipmaps for the texture. The texture will have (floor (log (apply #'max dimensions) 2)) levels of mipmaps

    If this is set to a positive integer CEPL will check that the number of levels is allowed for the dimensions given and make that many levels of mipmaps.

    If generate-mipmaps is t CEPL will ask OpenGL to generate content for all the mipmaps levels.

    -- :layer-count --

    If this is set to a value greater than 1 then you are trying to create one of the following:

    :texture-1d-array :texture-2d-array :texture-cube-map-array

    Which one is created depends on the dimensions provided and whether cubes is t.

    -- :cubes --

    If this is t then you are trying to make a cube-map texture

    -- :rectangle --

    If this is t then you are trying to make a rectangle texture.

    This is different from a regular 2d texture (which can also be rectangular)

    This texture only has one 2-dimensional gpu-array. The texture cannot have mipmapping. Texture coordinates used for these textures are not normalized.

    -- :multisample --

    This is not currently supported in CEPL

    -- :immutable --

    Set this to nil if you definitely dont want to use immutable texture storage. See the docstring for 'texture for more details

    -- :buffer-storage --

    If this is set to t you are trying to make a buffer-texture.

    If you set this to t then the element-type should NOT be an image-format. Use a foreign lisp type instead. Or leave it nil if you want CEPL to take the type from the initial-contents

    See the docstring for texture for more details.

  • ( MAKE-TEXTURE-FROM-ID GL-OBJECT &KEY BASE-DIMENSIONS TEXTURE-TYPE ELEMENT-TYPE MIPMAP-LEVELS LAYER-COUNT CUBES ALLOCATED MUTABLE-P SAMPLES FIXED-SAMPLE-LOCATIONS )

    function

    Wrap and existing GL Texture Object in a CEPL texture struct.

    This function does not do ANY sanity checking on the values provided, use only if you are 100% sure of what you are setting.

    For details on the meaning of the arguments see the docstring for make-texture

  • ( TEXREF TEXTURE &KEY (MIPMAP-LEVEL 0) (LAYER 0) (CUBE-FACE 0) )

    function

    This function allows you to access a specific gpu-array from the texture.

    :mipmap-level is invalid if the texture doesnt have mipmaps

    :layer is invalid if the texture-type is not a 1d,2d or cube-map array-texture.

    :cube-face is invalid if the texture is not a cube-map texture

  • ( TEXTURE-ELEMENT-TYPE TEXTURE )

    function

    This function returns the element-type of the given texture.

    If the texture is a buffer-texture then the element-type will be a foreign lisp type.

    Otherwise it will be one of the image-formats

    -- Element Types Details --

    Unlike c-array and gpu-arrays (which use foreign types for their elements) textures have a different set of acceptable format. These are called 'image formats'.

    The name may imply that these formats are only usable for image data but this is not the case. Most of the types we are used to are there, but under unsual names.

    This would make this a ripe candidate for CEPL to clean up the naming.. but it doesnt, why?

    Well the answer to that is image-formats are damn confusing and if we change too much of the naming it will be even more confusing when trying to google information. Instead CEPL provides a number of functions for converting between (foreign) lisp types and their image-format counterparts.

  • ( TEXTURE-P OBJECT )

    function

    This function returns t if the given value is a texture, otherwise nil is returned.

  • ( FREE-TEXTURE TEXTURE )

    generic

    This function will free the texture and all texture-memory behind the texture's gpu-arrays.

    Be sure not to use those arrays after this function has been called.

• CEPL.SAMPLERS

  • SAMPLER

    class

    As sampler is a structure which we pass to the a gpu-pipeline to specify how the pipeline should read from a particular texture (also known as sampling the texture).

    They are created by calling sample on a texture. You can then modify the various parameters and the pass the sampler to a pipeline as a uniform.

    Sampling Parameters cover four main aspects of how the values are read:

    • Wrapping
    • Filtering
    • LOD
    • Comparison

    We will dive into these topics below.

    -- Note for beginners --

    This area of GL can be incredibly confusing so don't worry if you don't grasp it immediately. Lots can be done without messing with these values, tackle each one when you have a usecase for it.

    -- Wrapping --

    When using normalized texture coordinates we are used to thinking about our coordinate being between 0s0 and 1s0 and that value dictating where we are sampling from.

    However normalized texture coordinates are not limited to values between 0s0 and 1s0. They can be any floating-point number.

    When a texture coordinate is not within the 0 → 1 range, some means must be employed to decide what the color value will be.

    The different approaches are as follows:

    :repeat: the texture coordinate wraps around the texture. so a texture
             coordinate of -0.2 becomes the equivalent of 0.8.
    
    :mirrored-repeat: the texture coordinate wraps around like a mirror.
                      -0.2 becomes 0.2, -1.2 becomes 0.8, etc.
    
    :clamp-to-edge: the texture coordinate is clamped to the 0 → 1 range.
    
    :clamp-to-border: the texture coordinate is clamped to the 0 → 1
                      range, but the edge texels are blended with a
                      constant border color.
    
    :mirror-clamp-to-edge: (only available with OpenGL 4.4 or
                           :arb-texture-mirror-clamp-to-edge) the texture
                           is clamped to the -1 → 1 range, but mirrors the
                           negative direction with the positive. Basically,
                           it acts as :clamp-to-edge, except that it
                           takes the absolute value of the texture
                           coordinates before clamping.
    

    This also applies to Rectangle Textures, except that the range at which they apply edge sampling is based on the texel width/height of the texture, not the normalized 0 → 1 range.

    This does not apply to Buffer Textures, as they must use the texelFetch sampling functions and thus cannot sample outside of the texel range of the texture.

    example:

    (setf (wrap texture-or-sampler)
          #(:clamp-to-edge :repeat-to-edge :clamp-to-edge))
    
    (setf (wrap texture-or-sampler) :clamp-to-edge)
    

    -- Filtering --

    Filtering is the process of accessing a particular sample from a texture.

    There are two cases when filtering is relevant: minification and magnification.

    Magnification means that the area of the fragment in texture space is smaller than a texel, and minification means that the area of the fragment in texture space is larger than a texel.

    Filtering for these two cases can be set independently.

    The magnification filter is controlled by the :magnify-filter texture parameter. This value can be :linear or :nearest.

    If :nearest is used, then the implementation will select the texel nearest the texture coordinate; this is commonly called 'point sampling').

    If :linear is used, the implementation will perform a weighted linear blend between the nearest adjacent samples.

    (setf (magnify-filter tex-or-sampler) :linear)
    (setf (magnify-filter tex-or-sampler) :nearest)
    

    The minification filter is controlled by the :texture-min-filter texture parameter. To understand these values better, it is important to discuss what the particular options are. Here is the full list:

    :nearest                 :linear
    :nearest-mipmap-nearest  :nearest-mipmap-linear
    :linear-mipmap-nearest   :linear-mipmap-linear
    

    When doing minification, you can choose to use mipmapping or not. Using mipmapping means selecting between multiple mipmaps based on the angle and size of the texture relative to the screen. Whether you use mipmapping or not, you can still select between linear blending of the particular layer or nearest. And if you do use mipmapping, you can choose to either select a single mipmap to sample from, or you can sample the two adjacent mipmaps and linearly blend the resulting values to get the final result.

    The OpenGL minification settings for these are as follows:

    Param Setting            Lin within mip-level
    :nearest                 No
    :linear                  Yes
    :nearest-mipmap-nearest  No
    :linear-mipmap-nearest   Yes
    :nearest-mipmap-linear   No
    :linear-mipmap-linear    Yes
    
    Param Setting            Has mipmapping
    :nearest                 No
    :linear                  No
    :nearest-mipmap-nearest  Yes
    :linear-mipmap-nearest   Yes
    :nearest-mipmap-linear   Yes
    :linear-mipmap-linear    Yes
    
    Param Setting            Linear between mip-levels
    :nearest                 -
    :linear                  -
    :nearest-mipmap-nearest  No
    :linear-mipmap-nearest   No
    :nearest-mipmap-linear   Yes
    :linear-mipmap-linear    Yes
    

    Remembering these combinations can be annoying so CEPL provides an additional function called #'set-minify-filter see the docstring for details

    examples:

    (setf (minify-filter tex-or-sampler) :linear)
    (setf (minify-filter tex-or-sampler) :nearest-mipmap-nearest)
    (setf-minify-filter tex-or-sampler :nearest :nearest)
    

    -- LOD --

    There is a pair of sampling parameters that affect the mipmap image selection: :max-lod and :min-lod (floating-point values).

    The way these work in mipmap selection is quite complicated; the specification goes into full detail about it.

    example:

    (setf (min-lod texture-or-sampler) value)
    (setf (max-lod texture-or-sampler) value)
    

    LOD bias: The mipmap image selection process can be adjusted coarsely by using the :lod-bias sampling parameter. This bias will be added to the mipmap LOD calculation (as well as added to the bias specified in one of the texture accessing functions in GLSL), which is used to select the image. A positive bias means that larger mipmaps will be selected even when the texture is viewed from farther away. This can cause visual aliasing, but in small quantities it can make textures a bit more sharp.

    (setf (lod-bias texture-or-sampler) value)
    

    -- Comparison --

    -WARNING-

    This feature is currently unsupported until shadow samplers are more fully tested in CEPL. Use at your own risk

    Depth textures (textures that have a depth component image format) can be sampled in one of two ways. They can be sampled as a normal texture, which simply retrieves the depth value (with filtering applied). This will return a vec4 containing a single floating-point value.

    They can also be fetched in comparison mode. This means that sampling from the texture requires a value to compare to those pulled from the texture; this value is called the reference value. The result of the comparison depends on the comparison function set in the texture. If the function succeeds, the resulting value is 1s0; if it fails, it is 0s0.

    When linear filtering is used, the actual returned value is implementation-defined. However, the value will be on the range 0 → 1 and will be proportional to the number of neighboring texels that pass the comparison based on the single given value.

    If the texture is a normalized integer depth format, then the reference value is clamped to 0 → 1, to match the values from the texture. Otherwise, the value is not clamped.

    Using this mode requires two special settings. First, the sampler used in GLSL must be a shadow sampler. Second, the texture used in that sampler must have activated depth comparison mode. Attempting to use a texture without comparison with a shadow sampler, or vice-versa, will result in an error upon rendering.

    To set the texture to comparison mode, set the :texture-compare-mode texture parameter to :compare-ref-to-texture. The comparison function to use when comparing the reference to the texture is set with the :texture-compare-func texture parameter. Acceptable values are:

    :never (always fails)
    :always (always succeeds)
    :less
    :lequal
    :equal,
    :not-equal
    :gequal
    :greater
    

    The comparison works as follows:

    (funcall operator ref texture)
    

    Where ref is the reference value given to the texture lookup function by GLSL, and texture is the value fetched from the texture. So :LESS will be true if the reference value is strictly less than the value pulled from the texture.

  • ( COMPARE SAMPLER )

    accessor

    This function sets the comparison mode of the texture or sampler given

    -WARNING-

    This feature is currently unsupported until shadow samplers are more fully tested in CEPL. Use at your own risk

    -- Comparison --

    Depth textures (textures that have a depth component image format) can be sampled in one of two ways. They can be sampled as a normal texture, which simply retrieves the depth value (with filtering applied). This will return a vec4 containing a single floating-point value.

    They can also be fetched in comparison mode. This means that sampling from the texture requires a value to compare to those pulled from the texture; this value is called the reference value. The result of the comparison depends on the comparison function set in the texture. If the function succeeds, the resulting value is 1s0; if it fails, it is 0s0.

    When linear filtering is used, the actual returned value is implementation-defined. However, the value will be on the range 0 → 1 and will be proportional to the number of neighboring texels that pass the comparison based on the single given value.

    If the texture is a normalized integer depth format, then the reference value is clamped to 0 → 1, to match the values from the texture. Otherwise, the value is not clamped.

    Using this mode requires two special settings. First, the sampler used in GLSL must be a shadow sampler. Second, the texture used in that sampler must have activated depth comparison mode. Attempting to use a texture without comparison with a shadow sampler, or vice-versa, will result in an error upon rendering.

    To set the texture to comparison mode, set the :texture-compare-mode texture parameter to :compare-ref-to-texture. The comparison function to use when comparing the reference to the texture is set with the :texture-compare-func texture parameter. Acceptable values are:

    :never (always fails)
    :always (always succeeds)
    :less
    :lequal
    :equal,
    :not-equal
    :gequal
    :greater
    

    The comparison works as follows:

    (funcall operator ref texture)
    

    where ref is the reference value given to the texture lookup function by GLSL, and texture is the value fetched from the texture. So :LESS will be true if the reference value is strictly less than the value pulled from the texture.

  • ( LOD-BIAS SAMPLER )

    accessor

    This function sets the lod-bias of the given texture or sampler

    -- LOD --

    There is a pair of sampling parameters that affect the mipmap image selection: :max-lod and :min-lod (floating-point values).

    The way these work in mipmap selection is quite complicated; the specification goes into full detail about it.

    example:

    (setf (min-lod texture-or-sampler) value)
    (setf (max-lod texture-or-sampler) value)
    

    LOD bias: The mipmap image selection process can be adjusted coarsely by using the :lod-bias sampling parameter. This bias will be added to the mipmap LOD calculation (as well as added to the bias specified in one of the texture accessing functions in GLSL), which is used to select the image. A positive bias means that larger mipmaps will be selected even when the texture is viewed from farther away. This can cause visual aliasing, but in small quantities it can make textures a bit more sharp.

    (setf (lod-bias texture-or-sampler) value)
    

  • ( MAGNIFY-FILTER SAMPLER )

    accessor

    This function takes a sampler or texture and sets the approach used when the area of the fragment in texture space is smaller than a texel.

    -- The magnification filter --

    The magnification filter is controlled by the :magnify-filter texture parameter. This value can be :linear or :nearest.

    If :nearest is used, then the implementation will select the texel nearest the texture coordinate; this is commonly called 'point sampling').

    If :linear is used, the implementation will perform a weighted linear blend between the nearest adjacent samples.

    (setf (magnify-filter tex-or-sampler) :linear)
    (setf (magnify-filter tex-or-sampler) :nearest)
    

  • ( MAX-LOD SAMPLER )

    accessor

    This function sets the max-lod of the given texture or sampler

    -- LOD --

    Together with :min-lod this sampling parameter affects the mipmap image selection.

    The way these work in mipmap selection is quite complicated; the specification goes into full detail about it.

    example:

    (setf (min-lod texture-or-sampler) value)
    (setf (max-lod texture-or-sampler) value)
    

  • ( MIN-LOD SAMPLER )

    accessor

    This function sets the min-lod of the given texture or sampler

    -- LOD --

    Together with :max-lod this sampling parameter affects the mipmap image selection.

    The way these work in mipmap selection is quite complicated; the specification goes into full detail about it.

    example:

    (setf (min-lod texture-or-sampler) value)
    (setf (max-lod texture-or-sampler) value)
    

  • ( MINIFY-FILTER SAMPLER )

    accessor

    This function takes a sampler or texture and sets the approach used when the area of the fragment in texture space is larger than a texel.

    -- The minification filter --

    The minification filter is controlled by the :texture-min-filter texture parameter. To understand these values better, it is important to discuss what the particular options are. Here is the full list:

    :nearest                 :linear
    :nearest-mipmap-nearest  :nearest-mipmap-linear
    :linear-mipmap-nearest   :linear-mipmap-linear
    

    When doing minification, you can choose to use mipmapping or not. Using mipmapping means selecting between multiple mipmaps based on the angle and size of the texture relative to the screen. Whether you use mipmapping or not, you can still select between linear blending of the particular layer or nearest. And if you do use mipmapping, you can choose to either select a single mipmap to sample from, or you can sample the two adjacent mipmaps and linearly blend the resulting values to get the final result.

    The OpenGL minification settings for these are as follows:
    Param Setting            Lin within mip-level
    :nearest                 No
    :linear                  Yes
    :nearest-mipmap-nearest  No
    :linear-mipmap-nearest   Yes
    :nearest-mipmap-linear   No
    :linear-mipmap-linear    Yes
    
    Param Setting            Has mipmapping
    :nearest                 No
    :linear                  No
    :nearest-mipmap-nearest  Yes
    :linear-mipmap-nearest   Yes
    :nearest-mipmap-linear   Yes
    :linear-mipmap-linear    Yes
    
    Param Setting            Linear between mip-levels
    :nearest                 -
    :linear                  -
    :nearest-mipmap-nearest  No
    :linear-mipmap-nearest   No
    :nearest-mipmap-linear   Yes
    :linear-mipmap-linear    Yes
    

    Remembering these combinations can be annoying so CEPL provides an additional function called #'set-minify-filter see the docstring for details

    examples:

    (setf (minify-filter tex-or-sampler) :linear)
    (setf (minify-filter tex-or-sampler) :nearest-mipmap-nearest)
    (setf-minify-filter tex-or-sampler :nearest :nearest)
    

  • ( WRAP SAMPLER )

    accessor

    This function sets the wrap parameter of the texture or sampler given.

    When setf'ing this parameter you can provide either one approach to be used for all 3 potential dimensions of the texture, or you can provide a vector of the 3 approaches you want to used.

    -- Wrapping --

    When using normalized texture coordinates we are used to thinking about our coordinate being between 0s0 and 1s0 and that value dictating where we are sampling from.

    However normalized texture coordinates are not limited to values between 0s0 and 1s0. They can be any floating-point number.

    When a texture coordinate is not within the 0 → 1 range, some means must be employed to decide what the color value will be.

    The different approaches are as follows:

    :repeat: the texture coordinate wraps around the texture. so a texture
             coordinate of -0.2 becomes the equivalent of 0.8.
    
    :mirrored-repeat: the texture coordinate wraps around like a mirror.
                      -0.2 becomes 0.2, -1.2 becomes 0.8, etc.
    
    :clamp-to-edge: the texture coordinate is clamped to the 0 → 1 range.
    
    :clamp-to-border: the texture coordinate is clamped to the 0 → 1
                      range, but the edge texels are blended with a
                      constant border color.
    
    :mirror-clamp-to-edge: (only available with OpenGL 4.4 or
                           :arb-texture-mirror-clamp-to-edge) the texture
                           is clamped to the -1 → 1 range, but mirrors the
                           negative direction with the positive. Basically,
                           it acts as :clamp-to-edge, except that it
                           takes the absolute value of the texture
                           coordinates before clamping.
    

    This also applies to Rectangle Textures, except that the range at which they apply edge sampling is based on the texel width/height of the texture, not the normalized 0 → 1 range.

    This does not apply to Buffer Textures, as they must use the texelFetch sampling functions and thus cannot sample outside of the texel range of the texture.

    example:

    (setf (wrap texture-or-sampler)
          #(:clamp-to-edge :repeat-to-edge :clamp-to-edge))
    
    (setf (wrap texture-or-sampler) :clamp-to-edge)
    

  • ( FREE-SAMPLER SAMPLER )

    function

    Calling this with a sampler will free the gl sampler and blank the lisp object representing it.

    Calling the generic function free with a sampler will call this function

  • ( SAMPLE TEXTURE &KEY (LOD-BIAS 0.0) (MIN-LOD -1000.0) (MAX-LOD 1000.0) (MINIFY-FILTER :LINEAR-MIPMAP-LINEAR) (MAGNIFY-FILTER :LINEAR) (WRAP #(:REPEAT :REPEAT :REPEAT)) (COMPARE :NONE) )

    function

    This function takes a texture and optionally some sampling parameters and returns a sampler.

    The sampler is an object that is passed to a pipeline so that the shaders in the gpu-functions in the pipeline can read from the gpu-arrays in the texture.

    For details on what the parameters are and mean see the docstring for the 'sampler type

    -- Note about GL Versions --

    Sampler Objects were introduced in GL 3.3. So for now CEPL needs at least v3.3 in future we hope to lower the requirement to 3.1 but this will take some extra work.

    -- NOTE For those with GL experience --

    You will have noticed that in CEPL your sampler is tied to one texture which is unlike in regular GL where a sample object can be used to override the sampling parameters of any number of textures. At first this would seem very wasteful however CEPL does not use 1 GL Sampler Object per CEPL sampler. The ID sharing is done based on the parameters.

    This means you get the same number of sampler objects as your would normally but with the added benefit that samplers are semantically dual with buffer-streams giving greater api consistancy.

  • ( SAMPLER-P OBJECT )

    function

    This function returns t if the supplied value is a sampler and nil otherwise

  • ( SAMPLER-TEXTURE SAMPLER )

    function

    This function takes a sampler as its only argument and returns the texture being sampled by the sampler.

  • ( SAMPLER-TYPE SAMPLER )

    function

    This function takes a sampler as its only argument and returns the kind of sampler it is.

    The result will be one of the kinds listed in cepl.samplers::+sampler-types+

  • ( SET-MINIFY-FILTER SAMPLER FOR-LEVEL &KEY (BETWEEN-LEVELS NIL) )

    function

    As the naming of the values for #'minify-filter are quite confusing this function allows you to set the minify filter for the given texture or sampler based on the following:

    • for-level: what sampling should be used between texels on the current mipmap level. The value can be :linear or :nearest

    • between-level: what sampling should be used between texels on different mipmap levels. The value can be :linear or :nearest This argument is optional.

  • ( WITH-TEMP-SAMPLER (VAR TEX) &BODY BODY )

    macro

    This macro takes a texture and creates a temporary sampler that is valid within the scope.

    As the sampler will be freed at the end of the scope, do not return it or assign it to any variable that outlasts the scope.

• CEPL.MEMORY

  • ( FREE OBJECT )

    generic

    The function takes a CEPL object of any one of the following types.

    • c-array
    • gpu-buffer
    • gpu-array (texture backed or buffer backed)
    • buffer-stream
    • texture
    • ubo
    • fbo

    And deletes the internal GL object, frees any associated memory and blanks the CEPL object.

    'Blanking', in this case, means the fields of the object will be set to some default.

  • ( INITIALIZED-P OBJECT )

    generic

    When given an object holding a gpu resource this function will return whether that object has been initialized.

    This will be t unless the GL context has not yet been created.

  • ( PULL-G OBJECT )

    generic

    This function takes a CEPL object containing foreign or gpu data as pulls the data into lisp performing any data conversions that are required on the way.

    CEPL types that can be pulled from are: - c-array - gpu-array (both texture-backed and buffer-backed) - texture - ubo - Any instance of a type defined using defstruct-g

  • ( PULL1-G OBJECT )

    generic

    This function is a varient of pull-g which, rather than pulling the gpu or foreign data to lisp, will instead pull it 1 level closer to lisp.

    What is meant by that is that, if the data is in foreign memory then it will be pulled to lisp data (just like pull-g). However if you call pull1-g on data stored on the gpu, then the data will be pulled to foreign memory instead.

    To clarify:

    (pull1-g c-array) -> lisp list
    (pull1-g gpu-array) -> c-array
    

    You can use pull1-g on the following CEPL types. - c-array - gpu-array (both texture-backed and buffer-backed) - texture - ubo - Any instance of a type defined using defstruct-g

  • ( PUSH-G OBJECT DESTINATION )

    generic

    This function takes a CEPL object as a desination and some data to push to the desination.

    It will then upload that data to the destination doing any data conversions that are required on the way.

    CEPL types supported as destinations are: - c-array - gpu-array (both texture-backed and buffer-backed) - texture - ubo - Any instance of a type defined using defstruct-g

• CEPL.MEASUREMENTS

  • ( DIMENSIONS OBJECT )

    accessor

    Returns the list containing the dimensions of the given value

  • ( ORIGIN OBJECT )

    accessor

    Returns the origin of the given value as a vec

  • ( RESOLUTION OBJECT )

    accessor

    Returns the resolution of the given value as a vec*

• CEPL.FBOS

  • FBO

    class

    A framebuffer object (FBO) is a structure that can be rendered into.

    When a FBO is rendered into the data from the pipeline is written into one or more of the attachments of the FBO

    An FBO attachment is a slot where a texture-backed gpu-array can be attached. When the gpu-array is attached the data from a pipeline rendering into the fbo is written into that gpu-array.

    This is the heart of how multi-pass rendering is done in OpenGL. One pipeline writes data into textures that are then used as inputs to another pipeline[0].

    A FBO can have: - 0 or more 'color attachments' - 0 or 1 'depth attachment' - 0 or 1 'stencil attachment' - 0 or 1 'depth-stencil attachment'

    Let's look at these in more detail:

    -- Color Attachments --

    Color attachments can only contain gpu-arrays whose element-type can be found in the color-renderable-formats list.

    Note that while OpenGL terminology mentions 'color' and 'image' a lot you are not limitted to only using textures or fbos for pictures. It is perfectly valid (and incredibly useful) to return data meaning all kinds of things other than colors.

    -- Depth Attachments --

    The depth attachment (when used) can only contain a gpu-array whos element-type can be found in depth-formats

    Usage Tip: Even if you don't plan on reading from this depth_attachment, any fbo that will be rendered to should have a depth attachment.

    -- Stencil Attachments (NOT SUPPORTED IN CURRENT CEPL VERSION) --

    The stencil attachment (when used) can only contain a gpu-array whos element-type can be found in stencil-formats

    -- Depth-Stencil Attachments (NOT SUPPORTED IN CURRENT CEPL VERSION) --

    The depth-stencil attachment (when used) can only contain a gpu-array whos element-type can be found in depth-stencil-formats

    This attachment is shorthand for 'both depth and stencil'. The gpu-array attached here becomes both the depth and stencil attachment.

    -- Choosing which attachment to render into --

    Making these choices is done with the with-fbo-bound macro. See its docstring for further details

    [0] WARNING:

    It is possible to bind a texture to an FBO, bind that same texture to a shader, and then try to sample from it at the same time. You will get undefined results.

    This means it may do what you want, the sampler may get old data, the sampler may get half old and half new data, or it may get garbage data. Any of these are possible outcomes.

    Do Not Do This!

  • ( ATTACHMENT FBO ATTACHMENT-NAME )

    accessor

    This function retrieves the attachment named by attachment-name from the given fbo. The result is a gpu-array

    The attachment-name can be one of the following:

    a positive integer - In which case this function returns the nth color-attachments where (= n attachment-name)

    :d - the depth-attachment is returned

    :s - the stencil-attachment is returned [0]

    :ds - the depth-stencil-attachment is returned [0]

    You can also setf this function, the value must be a texture-backed gpu-array with a valid element-type for that attachment.

    For color attachments this means the element type must be a member of the *color-renderable-formats* list

    For color attachments this means the element type must be a member of the *depth-formats* list

    For stencil attachments this means the element type must be a member of the *stencil-formats* list

    For depth-stencil attachments this means the element type must be a member of the *depth-stencil-formats* list

    [0] WARNING: :s & :ds are not supported in the current version of CEPL

  • ( ATTACHMENT-BLENDING FBO ATTACHMENT-NAME )

    accessor

    This function returns the blending parameters that will be used when rendering into the specified attachment on the given fbo

    Blending parameters tell OpenGL how values written into a gpu-array should be combined with any values that are already present.

    The canonical use for this is implementing transparency.

    The details of blending parameters and where they can be used is best covered in the docstring for the blending-params struct.

  • ( ATTACHMENT-TEX FBO ATTACHMENT-NAME )

    function

    This function take an fbo and the name of an attachment. It then returns the texture that backs the gpu-array in the specified attachment.

    It is equivalent to writing:

    (gpu-array-texture (attachment fbo attachmnent-name))
    

  • ( ATTACHMENT-VIEWPORT FBO ATTACHMENT-NAME )

    function

    This function takes an fbo and attachment-name and returns a new viewport whos dimensionsmatch those of the gpu-array connected to the attachment.

  • ( CHECK-FRAMEBUFFER-STATUS FBO )

    function

    This function asks OpenGL to check the given FBO and ensure that it is 'complete'.

    This function will either return the particular 'framebuffer complete' flag or will throw a condition with an explanation of the problem.

    For a full rundown on what it means for a fbo to be complete see: glwiki- framebuffer completeness

    All fbos made in CEPL using make-fbo are checked for completeness before being returned to the user.

  • ( CLEAR &OPTIONAL (TARGET NIL) )

    function

    What this function will clear depends on what is passed:

    • a fbo - See 'clearing fbos' below
    • an attachment - See 'clearing a single attachment' below
    • nothing - The 'current fbo' will be cleared

    -- Clearing Fbos --

    In this case clearing means that all the elements of the attachments will be set to a certain value. The value that the attachment's gpu-arrays will be set to varies based on the attachment.

    • color attachments: Will be set to the value set in #'gl:clear-color
    • depth attachments: Will be set to the value set in #'gl:clear-depth
    • stencil attachments: Will be set to the value set in #'gl:clear-stencil

    You can also use clear-fbo for this task

    -- Clearing a single attachment --

    Not currently implemented

  • ( CLEAR-ATTACHMENT ATTACHMENT )

    function

    Not currently implemented

    This function will clear a single attachment of a fbo.

  • ( CLEAR-FBO FBO )

    function

    This function will set the elements of the attachments of the fbo to a certain value. The value that the attachment's gpu-arrays will be set to varies based on the attachment.

    • color attachments: Will be set to the value set in #'gl:clear-color
    • depth attachments: Will be set to the value set in #'gl:clear-depth
    • stencil attachments: Will be set to the value set in #'gl:clear-stencil

    You can also perform this action by calling clear with an fbo

  • ( FBO-P OBJECT )

    function

    This function will return t if the given value is an fbo, otherwise it will return nil

  • ( MAKE-FBO &REST FUZZY-ATTACH-ARGS )

    function

    This, like other make-* functions in CEPL has a large variety of valid arguments. The goal of this apparent complexity is to make exploration from the repl easy, whilst still allowing absolutely control when it is needed.

    Lets look at the behaviour when given different arguments

    -- (make-fbo) --

    It is not valid is have an fbo with no attachments so this will fail

    -- (make-fbo 0) --

    Make an fbo with one color attachment in attachment slot 0. CEPL with make a texture with dimensions equal to that of the current viewport and with the element-type :rgba (which is a sensible default for a color attachment)

    -- (make-fbo 0 1) --

    Make an fbo with two color attachments 1 in each of attachment slots 0 & 1. CEPL with make the textures with dimensions equal to that of the current viewport and with the element-type :rgba (which is a sensible default for a color attachment)

    -- (make-fbo :d) --

    Make an fbo with one depth attachment. CEPL with make a texture with dimensions equal to that of the current viewport and with the element-type :depth-component24 (which is a sensible default for a depth attachment)

    -- (make-fbo 0 1 :d) --

    Make an fbo with two color attachments and one depth attachment.

    -- (make-fbo (list 0 some-gpu-array)) --

    Makes an fbo with one color attachment whos gpu-array is 'some-gpu-array'

    -- (make-fbo (list 0 some-texture)) --

    Makes an fbo with one color attachment whos gpu-array is (texref some-texture)

    -- (make-fbo '(0 :dimensions (100 100) :element-type :rgba8)) --

    Makes an fbo with one color attachment whos gpu-array is taken from a new texture created by taking the arguments after 0 and applying them to make-texture

    -- Any combination of the above --

    One last variant is allowed. You are allowed to pass a cube-map texture along with and optional depth option. This will result in each face of the cube being bound to the fbo's attachments.

    (make-fbo cube-tex)
    
    (make-fbo cube-tex '(:d :dimensions (32 32))
    
    (make-fbo cube-tex :d) ;; depth attachment dimensions will match faces
    

  • ( PER-ATTACHMENT-BLENDING-AVAILABLE-P &OPTIONAL (CEPL-CONTEXT (CEPL-CONTEXT)) )

    function

    This function will return t if you are on a version of opengl that supports setting blending parameters on framebuffer attachments. Otherwise it returns nil

    If the result is nil then you will only be able to change blend params on the first attachment. You can however enable blending on any number of attachments and they will inherit their params from attachment 0

    For more details see cepl.blending

  • ( WITH-FBO-BOUND (FBO &KEY (TARGET) (WITH-VIEWPORT) (ATTACHMENT-FOR-SIZE) (WITH-BLENDING) (DRAW-BUFFERS)) &BODY BODY )

    macro

    This is one macro you use when you want to capture the output from a pipeline in an FBO.

    with-fbo-bound will capture any rendering from any map-g calls inside it body.

    Also look at the docs for map-g-into and map-g-into* for a full picture of your options

    *-- draw buffers -- draw-buffers is an important argument, it allows you to direct the outputs from the fragment-shader of the pipeline into the fbo's color attachments. This means that your pipelines can write into multiple attachments (and thus multiple textures) at once.

    To use it either pass in:

    nil - Which means that the fbo is bound but no attachments will be draw into (rarely used)

    t - Which means the all attachments will be available to be drawn into this will happen in order, so the first output from the fragment shader will draw into the first attachment, the second output to the second attachment, etc

    -- with-viewport --

    If with-viewport is t then with-fbo-bound adds a with-fbo-viewport that uses this fbo to this scope. This means that the current-viewport within this scope will be set to the equivalent of:

    (make-viewport dimensions-of-fbo '(0 0))
    

    See the docstruct with-fbo-viewport for details on this behavior.

    One last detail is that you may want to take the dimensions of the viewport from an attachment other than attachment-0. To do this use the 'attachment-for-size argument and give the index of the color-attachment to use.

    -- with-blending --

    If with-blending is t then with-fbo-bound adds a with-blending that uses this fbo to this scope. This means that the blending parameters from your fbo will be used while rendering. For the details and version specific behaviours check out the docstring for cepl.blending:with-blending

    -- target --

    For target the choices are :framebuffer, :read_framebuffer and :draw_framebuffer.

    You normally dont need to worry about the target as the last two are only used when you need certain GL read and write operations to happen to different buffers. It remains for those who know they need this but otherwise you can let CEPL handle it.

• CEPL.BLENDING

  • BLENDING-PARAMS

    class

    Blending Parameters dictate how a color is written into an FBO's attachment if there is already a color there.

    Blending Parameters (or blending-params) can be applied in CEPL in 3 places:

    • On an FBO: This sets the rules for all attachments in the FBO

    • On an FBO Attachment: This overrides the rules set on the FBO but only for the one attachment. This is only supported on some versions of OpenGL.

    • On a blending-params object: This object can then be applied using with-blending (see with-blending's docstring for more info)

    The interaction between the options in the blending-params is fairly complex so whilst we seek to give an introduction here, some cases will be best covered in other documentation.

    -- The Parameters --

    There are 3 pairs of parameters that work together to tell GL how to compute the final color.

    In all cases below 'source' means the color coming from the pipeline that needs to be written into the FBO, and 'destination' means the color already in the FBO

    Conceptually what is happening is that source-rgb, source-alpha, destination-rgb and destination-alpha all name functions that will be called on their respective values. This will result in new source-rgb, source-alpha, destinations-rgb and destination-alpha values.

    Those new values are then given to the mode-rgb and mode-alpha functions which compute the final color.

    So in pseudo-code it would look this this:

    (defun compute-final-color (blend-params src-rgb src-alpha
                                dest-rgb dest-alpha)
      (let ((new-src-rgb
             (funcall (blend-params-source-rgb blend-params)
                      src-rgb
                      dest-rgb))
            (new-dest-rgb
             (funcall (blend-params-destination-rgb blend-params)
                      src-rgb
                      dest-rgb))
            (new-src-alpha
             (funcall (blend-params-source-alpha blend-params)
                      src-alpha
                      dest-alpha))
            (new-dest-alpha
             (funcall (blend-params-destination-alpha blend-params)
                      src-alpha
                      dest-alpha)))
        ;; compute final colors
        (values (funcall (blend-params-mode-rgb blend-params)
                         new-src-rgb
                         new-dest-rgb)
                (funcall (blend-params-mode-alpha blend-params)
                         new-src-alpha
                         new-dest-alpha))))
    

    -- :source-rgb, :source-alpha, :destination-rgb & :destination-alpha --

    This is the list of operations and what they do to the *-rgb or *alpha values given.

    Parameter                 | RGB Factor                      | Alpha Factor
    --------------------------------------------------------------------------
    :zero                     | (v! 0 0 0)                      | 0
    :one                      | (v! 1 1 1)                      | 1
    :src-color                | (v! rs0 gs0 bs0)                | as0
    :one-minus-src-color      | (- (v! 1 1 1) (v! rs0 gs0 bs0)) | 1 - as0
    :dst-color                | (v! rd gd bd)                   | ad
    :one-minus-dst-color      | (- (v! 1 1 1) (v! rd gd bd))    | 1 - ad
    :src-alpha                | (v! as0 as0 as0)                | as0
    :one-minus-src-alpha      | (- (v! 1 1 1) (v! as0 as0 as0)) | 1 - as0
    :dst-alpha                | (v! ad ad ad)                   | ad
    :one-minus-dst-alpha      | (- (v! 1 1 1) (v! ad ad ad))    | ad
    :constant-color           | (v! rc gc bc)                   | ac
    :one-minus-constant-color | (- (v! 1 1 1) (v! rc gc bc))    | 1 - ac
    :constant-alpha           | (v! ac ac ac)                   | ac
    :one-minus-constant-alpha | (- (v! 1 1 1) (v! ac ac ac))    | 1 - ac
    :src-alpha-saturate       | (v! i i i)                      | 1
    :src1-color               | (v! rs1 gs1 bs1)                | as1
    :one-minus-src1-color     | (- (v! 1 1 1) (v! rs1 gs1 bs1)) | 1 - as1
    :src1-alpha               | (v! as1 as1 as1)                | as1
    :one-minus-src1-alpha     | (- (v! 1 1 1) (v! as1 as1 as1)) | 1 - as1
    

    -- :mode-rgb & :mode-alpha --

    As mentioned above, to compute the final color two equations are used: one for the RGB portion of the color, and one for the alpha of the color. This is useful if you want treat rgb and alpha differently when producing the end result.

    The equations available are:

    :func-add - The source and destination colors are added to each other. O = sS + dD. The s and d are blending parameters that are multiplied into each of S and D before the addition.

    :func-subtract - Subtracts the destination from the source. O = sS - dD. The source and dest are again multiplied by blending parameters.

    :func-reverse-subtract - Subtracts the source from the destination. O = sD - dS. The source and dest are multiplied by blending parameters.

    :min - The output color is the component-wise minimum value of the source and dest colors. So performing :min in the RGB equation means that Or = min(Sr, Dr), Og = min(Sg, Dg), and so forth. The parameters s and d are ignored for this equation.

    :max - The output color is the component-wise maximum value of the source and dest colors. The parameters s and d are ignored for this equation.

    -- Precision --

    Despite the apparent precision of the above equations, blending arithmetic is not exactly specified, because blending operates with imprecise integer color values. However, a blend factor that should be equal to 1 is guaranteed not to modify its multiplicand, and a blend factor equal to 0 reduces its multiplicand to 0.

    For example, when:

    • srcRGB is GL_SRC_ALPHA
    • dstRGB is GL_ONE_MINUS_SRC_ALPHA,
    • As0 is equal to 1

    the equations reduce to simple replacement:

    todo

  • ( BLENDING-PARAMS FBO &OPTIONAL ATTACHMENT-NAME )

    accessor

    This function, when passed an fbo or attachment will return the blending-params for that object.

    For details on what blending-params are, see the docstring for the blending-params struct

  • ( DESTINATION-ALPHA FBO &OPTIONAL ATTACHMENT-NAME )

    accessor

    This function, when passed a blending-params object, will return the name of the function that will be applied to the alpha value that is currently in the fbo and is about to be combined with the value coming from the pipeline.

    The result will be one of the following:

    :zero
    :one
    :src-color
    :one-minus-src-color
    :dst-color
    :one-minus-dst-color
    :src-alpha
    :one-minus-src-alpha
    :dst-alpha
    :one-minus-dst-alpha
    :constant-color
    :one-minus-constant-color
    :constant-alpha
    :one-minus-constant-alpha
    :src-alpha-saturate
    :src1-color
    :one-minus-src-color
    :src1-alpha
    :one-minus-src-alpha
    

    To see more info on this subject please see the doc-string for the blending-params struct.

  • ( DESTINATION-RGB FBO &OPTIONAL ATTACHMENT-NAME )

    accessor

    This function, when passed a blending-params object, will return the name of the function that will be applied to the color value that is currently in the fbo and is about to be combined with the value coming from the pipeline.

    The result will be one of the following:

    :zero
    :one
    :src-color
    :one-minus-src-color
    :dst-color
    :one-minus-dst-color
    :src-alpha
    :one-minus-src-alpha
    :dst-alpha
    :one-minus-dst-alpha
    :constant-color
    :one-minus-constant-color
    :constant-alpha
    :one-minus-constant-alpha
    :src-alpha-saturate
    :src1-color
    :one-minus-src-color
    :src1-alpha
    :one-minus-src-alpha
    

    To see more info on this subject please see the doc-string for the blending-params struct.

  • ( MODE-ALPHA FBO &OPTIONAL ATTACHMENT-NAME )

    accessor

    This function, when passed a blending-params object, will return the name of the equation that will be used to compute the final alpha value from the processed source-alpha and destination-alpha.

    The result will be one of the following:

    :func-add
    :func-subtract
    :func-reverse-subtract
    :min
    :max
    

    To see more info on this subject please see the doc-string for the blending-params struct.

  • ( MODE-RGB FBO &OPTIONAL ATTACHMENT-NAME )

    accessor

    This function, when passed a blending-params object, will return the name of the equation that will be used to compute the final color value from the processed source-rgb and destination-rgb.

    The result will be one of the following:

    :func-add
    :func-subtract
    :func-reverse-subtract
    :min
    :max
    

    To see more info on this subject please see the doc-string for the blending-params struct.

  • ( SOURCE-ALPHA FBO &OPTIONAL ATTACHMENT-NAME )

    accessor

    This function, when passed a blending-params object, will return the name of the function that will be applied to the alpha value that is coming from the pipeline and is to be combined with the value already in the fbo.

    The result will be one of the following:

    :zero
    :one
    :src-color
    :one-minus-src-color
    :dst-color
    :one-minus-dst-color
    :src-alpha
    :one-minus-src-alpha
    :dst-alpha
    :one-minus-dst-alpha
    :constant-color
    :one-minus-constant-color
    :constant-alpha
    :one-minus-constant-alpha
    :src-alpha-saturate
    :src1-color
    :one-minus-src-color
    :src1-alpha
    :one-minus-src-alpha
    

    To see more info on this subject please see the doc-string for the blending-params struct.

  • ( SOURCE-RGB FBO &OPTIONAL ATTACHMENT-NAME )

    accessor

    This function, when passed a blending-params object, will return the name of the function that will be applied to the color value that is coming from the pipeline and is to be combined with the value already in the fbo.

    The result will be one of the following:

    :zero
    :one
    :src-color
    :one-minus-src-color
    :dst-color
    :one-minus-dst-color
    :src-alpha
    :one-minus-src-alpha
    :dst-alpha
    :one-minus-dst-alpha
    :constant-color
    :one-minus-constant-color
    :constant-alpha
    :one-minus-constant-alpha
    :src-alpha-saturate
    :src1-color
    :one-minus-src-color
    :src1-alpha
    :one-minus-src-alpha
    

    To see more info on this subject please see the doc-string for the blending-params struct.

  • ( BLENDING-PARAMS-P OBJECT )

    function

    This function returns t when the given value is a blending-params object, otherwise it returns nil

  • ( COPY-BLENDING-PARAMS INSTANCE )

    function

    This function, when passed a blending-params object, will create a new blending-params object with the same settings as the one passed.

  • ( MAKE-BLENDING-PARAMS &KEY ((:MODE-RGB MODE-RGB) :FUNC-ADD) ((:MODE-ALPHA MODE-ALPHA) :FUNC-ADD) ((:SOURCE-RGB SOURCE-RGB) :SRC-ALPHA) ((:SOURCE-ALPHA SOURCE-ALPHA) :SRC-ALPHA) ((:DESTINATION-RGB DESTINATION-RGB) :ONE-MINUS-SRC-ALPHA) ((:DESTINATION-ALPHA DESTINATION-ALPHA) :ONE-MINUS-SRC-ALPHA) )

    function

    This function makes a new blending-params object.

    The valid values for source-rgb, source-alpha, destination-rgb and destination-alpha are:

    :zero
    :one
    :src-color
    :one-minus-src-color
    :dst-color
    :one-minus-dst-color
    :src-alpha
    :one-minus-src-alpha
    :dst-alpha
    :one-minus-dst-alpha
    :constant-color
    :one-minus-constant-color
    :constant-alpha
    :one-minus-constant-alpha
    :src-alpha-saturate
    :src1-color
    :one-minus-src-color
    :src1-alpha
    :one-minus-src-alpha
    

    The valid values for mode-rgb and mode-alpha are:

    :func-add
    :func-subtract
    :func-reverse-subtract
    :min
    :max
    

    For details on their behaviour on the blending-params object please see the docstring for blending-params.

  • ( WITH-BLENDING BLENDING-PARAMS &BODY BODY )

    macro

    This macro will set the default blending parameters for the scope.

    These values will be used unless overriden by blend settings in an fbo.

    CEPL ensures the blending settings are undone at the end of the scope.

• CEPL.PIPELINES

  • ( BAKE-UNIFORMS PIPELINE &REST UNIFORMS &KEY &ALLOW-OTHER-KEYS )

    function

    WARNING EXPRERIMENTAL FEATURE

    This allows you to create a new lambda-pipeline from existing pipeline whilst also fixing the values for certain uniforms.

    These values will be baked into the gpu-code so that they will not need to be uploaded each time the pipeline is mapped over.

    For example:

    (defpipeline-g draw-cube ()
      :vertex (draw-cube-vert g-pnt)
      :fragment (draw-cube-frag :vec2))
    
    (defun fix-cube-size (size)
      (bake-uniforms #'draw-cube :edge-length (float size)))
    

  • ( COMPILE-G NAME &OPTIONAL DEFINITION )

    function

    This function takes a lambda-g form and compiles it to a gpu-lambda object.

    This is used for similar reasons to compile in Common Lisp, you have a lambda definition as lists and you want a compiled lambda.

    The result of this function is suitable for passing to pipeline-g which lets you define a map-g'able pipeline at runtime.

    Whilst this shares the same signature as CL's #'compile in our version the 'name' argument must be nil.

  • ( FREE-PIPELINE PIPELINE )

    function

    This function takes a pipeline designator[0] and frees it, this releases frees the gl-program object.

    [0] either a lambda-pipeline or a symbol naming a pipeline

  • ( FUNCALL-G NAME &REST ARGS )

    function

    funcall-g is an experimental function. What it aims to allow you to do is to generate and run a pipeline which runs the requested function once with the given arguments on the GPU.

    By doing this it gives you a way to try out your gpu-functions from the REPL without having to make a pipeline map-g over it whilst use ssbos or transform-feedback to capture the result.

    Currently this only works with functions that would work within a vertex shader (so things like gl-frag-pos will not work) however we want to expand on this in the future.

    This is not intended to be used anywhere where performance matters, it was made solely as a debugging/development aid. Every time it is run it must:

    • generate a pipeline
    • compile it
    • map-g over it
    • marshal the results back to lisp
    • free the pipeline

    This is extremly expensive, however as long as it takes less that 20ms or so it is fast enough for use from the repl.

  • ( GPU-FUNCTIONS NAME )

    function

    This function returns all the signatures of the gpu-functions named 'name'.

    The reason there may be many is that functions can be 'overloaded' so you can have multiple gpu-functions with the same name as long as they can be uniquely identified by the combination of their name and argument types.

  • ( DELETE-GPU-FUNCTION GFUNC-DESCRIPTION &OPTIONAL ERROR-IF-MISSING )

    generic

    This function will delete a gpu-function this will mean it can no longer be used in new pipelines.

    This function will only delete one function at a time, so if your gpu-function is overloaded then you will want to specify the function signature exactly.

    See the documentation for gpu-functions which will lists all the signatures for the gpu-functions with a given name.

  • ( DEF-GLSL-STAGE NAME ARGS BODY-FORM OUTPUTS )

    macro

    def-glsl-stage is useful when you wish to define a CEPL pipeline stage in glsl rather than lisp. This is especially useful if you want to use some pre-exisiting glsl without rewriting it to lisp.

    It is used like this:

    (def-glsl-stage frag-glsl (("color_in" :vec4) &context :330 :fragment)
      "void main() {
           color_out = color_in;
       }"
      (("color_out" :vec4)))
    

    It differs from a regular defun-g definition in a few ways.

    • argument names are specified using strings.

    • &context is mandatory. You must specify what shader stage this can be used for and also what version/s this stage requires

    • You are defining the entire stage, not just a function body. This means you can define local shader functions etc

    • You have to specify the outputs in lisp as well as the inputs. This allows CEPL to compose this stage in pipelines with regular CEPL gpu functions.

    CEPL will write all the in, out and uniform definitions for your shader so do not specify those yourself.

    This stage fully supports livecoding, so feel free to change and recomplile the text in the stage at runtime.

  • ( DEFINE-COMPILER-MACRO-G NAME LAMBDA-LIST &BODY BODY )

    macro

    This lets you define a compiler-macro that only works with gpu-functions.

    The &context lambda list keyword allows you to restrict this macro to only be valid in gpu functions with compatible contexts.

    &whole and &environment are not supported.

  • ( DEFMACRO-G NAME LAMBDA-LIST &BODY BODY )

    macro

    This lets you a define a macro that only works in gpu code.

    The &context lambda list keyword allows you to restrict this macro to only be valid in gpu functions with compatible contexts.

    &whole and &environment are not supported.

  • ( DEFPIPELINE-G NAME CONTEXT &BODY GPIPE-ARGS )

    macro

    defpipeline-g is how we define named rendering pipelines in CEPL.

    Rendering pipelines are constructed by composing gpu-functions.

    Rendering in OpenGL is descibed as a pipeline where a buffer-stream of data usually describing geometry) is mapped over whilst a number of uniforms are available as input and the outputs are written into an FBO.

    There are many stages to the pipeline and a full explanation of the GPU pipeline is beyond the scope of this docstring. However it surfices to say that only 5 stages are fully programmable (and a few more customizable).

    defpipeline-g lets you specify the code (shaders) to run the programmable parts (stages) of the pipeline.

    The available stages kinds are:

    • :vertex
    • :tessellation-control
    • :tessellation-evaluation
    • :geometry
    • :fragment
    • :compute

    To define code that runs on the gpu in CEPL we use gpu functions (gfuncs). Which are defined with defun-g.

    Here is an example pipeline:

    (defun-g vert ((position :vec4) &uniform (i :float))
      (values position (sin i) (cos i)))
    
    (defun-g frag ((s :float) (c :float))
      (v! s c 0.4 1.0))
    
    (defpipeline-g prog-1 ()
      (vert :vec4)
      (frag :float :float))
    

    Here we define a pipeline #'prog-1 which uses the gfunc vert as its vertex shader and used the gfunc frag as the fragment shader.

    It is also possible to specify the name of the stages

    (defpipeline-g prog-1 ()
      :vertex (vert :vec4)
      :fragment (frag :float :float))
    

    But this is not neccesary unless you need to distinguish between tessellation or geometry stages.

    -- Context --

    The second argument to defpipeline-g is the a list of additional information that is confusingly called the 'pipeline's context'. We need to change this name.

    Valid things that can be in this list are:

    A primitive type:

    This specifies what primitives can be passed into this pipeline. By default all pipelines expect triangles. When you map a buffer-stream over a pipeline the primitive kind of the stream must match the pipeline.

    The valid values are:

    :dynamic
    :points
    :lines :line-loop :line-strip
    :lines-adjacency :line-strip-adjacency
    :triangles :triangle-fan :triangle-strip
    :triangles-adjacency :triangle-strip-adjacency
    (:patch <patch-size>)
    

    :dynamic is special, it means that the pipeline will take the primitive kind from the buffer-stream being mapped over. This won't work for with pipelines with geometry or tessellation stages, but it otherwise quite useful.

    A version restriction:

    This tells CEPL to compile the stage for a specific version of GLSL. You usually do not want to use this as CEPL will compile for the version the user is using.

    The value can be one of:

    :140 :150 :330 :400 :410 :420 :430 :440 :450
    

    -- Stage Names --

    Notice that we have to specify the typed signature of the stage. This is because CEPL allows you to 'overload' gpu functions. The signature for the a gpu-function is a list which starts with the function name and whose other elements are the types of the non-uniforms arguments. As an example we can see above that the signature for vert is (vert :vec4), not (vert :vec4 :float).

    -- Passing values from Stage to Stage --

    The return values of the gpu functions that are used as stages are passed as the input arguments of the next. The exception to this rule is that the first return value from the vertex stage is taken and used by GL, so only the subsequent values are passed along.

    We can see this in the example above: #'vert returns 3 values but #'frag only receives 2.

    The values from the fragment stage are writen into the current FBO. This may be the default FBO, in which case you will likely see the result on the screen, or it may be a FBO of your own.

    By default GL only writed the fragment return value to the FBO. For handling multiple return values please see the docstring for with-fbo-bound.

    -- Using our pipelines --

    To call a pipeline we use the map-g macro (or one of its siblings map-g-into/map-g-into*). The doc-strings for those macros go into more details but the basics are that map-g maps a buffer-stream over our pipeline and the results of the pipeline are fed into the 'current' fbo.

    We pass our stream to map-g as the first argument after the pipeline, we then pass the uniforms in the same style as keyword arguments. For example let's see our prog-1 pipeline again:

    (defun-g vert ((position :vec4) &uniform (i :float))
      (values position (sin i) (cos i)))
    
    (defun-g frag ((s :float) (c :float))
      (v! s c 0.4 1.0))
    
    (defpipeline-g prog-1 ()
      (vert :vec4)
      (frag :float :float))
    

    We can call this as follows:

    (map-g #'prog-1 v4-stream :i game-time)
    

  • ( DEFUN-G NAME ARGS &BODY BODY )

    macro

    defun-g let's you define a function which will be run on the gpu. Commonly refered to in CEPL as a 'gpu function' or 'gfunc'

    Gpu functions try to feel similar to regular CL functions however naturally there are some differences.

    The first and most obvious one is that gpu function should only be called from other gpu functions and/or composed into a pipeline using defpipeline-g.

    Whilst it is actually possible to call on from a lisp function this is provided solely for making interactive development and debugging easier. Please see the EXPERIMENTAL section below for more info

    When a gfunc is composed into a pipeline then that function takes on the role of one of the 'shader stages' of the pipeline. For a proper breakdown of pipelines see the docstring for defpipeline-g.

    Let's see a simple example of a gpu function we can then break down

    ;;       {0}          {3}          {1}         {2}
    (defun-g example ((vert my-struct) &uniform (loop :float))
      (values (v! (+ (my-struct-pos vert) ;; {4}
                     (v! (sin loop) (cos loop) 0))
                  1.0)
              (my-struct-col vert)))
    

    {0} So like the normal defun we specify a name first, and the arguments as a list straight afterwards

    {1} The &uniform lambda keyword says that arguments following it are 'uniform arguments'. A uniform is an argument which has the same value for the entire stage. &optional and &key are not supported

    {2} Here is our definition for the uniform value. If used in a pipeline as a vertex shader #'example will be called once for every value in the buffer-stream given. That means the 'vert' argument will have a different value for each of the potentially millions of invocations in that ONE pipeline call, however 'loop' will have the same value for the entire pipeline call.

    {2 & 3} All arguments must have their types declared

    {4} Here we see we are using CL's values special form. CEPL fully supports multiple value return in your shaders. If our function #'example was called from another gpu-function then you can use multiple-value-bind to bind the returned values. If however our example function were used as a stage in a pipeline then the multiple returned values will be mapped to the multiple arguments of the next stage in the pipeline.

    That's the basics of gpu-functions. For more details on how they can be used in pipelines please see the documentation for defpipeline-g.

    EXPRERIMENTAL

    CEPL has a highly experimental feature to allow you to call gpu-functions directly What it aims to allow you to do is to generate and run a pipeline which runs your function once with the given arguments on the GPU.

    By doing this it gives you a way to try out your gpu-functions from the REPL without having to make a pipeline map-g over it whilst use ssbos or transform-feedback to capture the result.

    Currently this only works with functions that would work within a vertex shader (so things like gl-frag-pos will not work) however we want to expand on this in the future.

    This is not intended to be used anywhere where performance matters, it was made solely as a debugging/development aid. Every time it is run it must:

    • generate a pipeline
    • compile it
    • map-g over it
    • marshal the results back to lisp
    • free the pipeline

    This is extremly expensive, however as long as it takes less that 20ms or so it is fast enough for use from the repl.

  • ( DEFUN-G-EQUIV NAME ARGS &BODY BODY )

    macro

    Defun-g-equiv let's you define a function which will be run on the gpu. Commonly refered to in CEPL as a 'gpu function' or 'gfunc'

    The difference between defun-g-equiv & defun-g is that defun-g will create a 'dummy' lisp function so that 'jump to definition' and signature hits work in your editor, defun-g-equiv does not do this.

    The advantage of defun-g-equiv is that you are then free define a lisp equivalent of your gpu-function. This means you can use the same functions in cpu or gpu code, which is very compelling.

    - the rest of the doc-string is the same as for defun-g -

    Gpu functions try to feel similar to regular CL functions however naturally there are some differences.

    The first and most obvious one is that whilst gpu function can be called from other gpu functions, they cannot be called from lisp functions directly. They first must be composed into a pipeline using defpipeline-g.

    When a gfunc is composed into a pipeline then that function takes on the role of one of the 'shader stages' of the pipeline. For a proper breakdown of pipelines see the docstring for defpipeline-g.

    Let's see a simple example of a gpu function we can then break down

    ;;       {0}          {3}          {1}         {2}
    (defun-g-equiv example ((vert my-struct) &uniform (loop :float))
      (values (v! (+ (my-struct-pos vert) ;; {4}
                     (v! (sin loop) (cos loop) 0))
                  1.0)
              (my-struct-col vert)))
    

    {0} So like the normal defun we specify a name first, and the arguments as a list straight afterwards

    {1} The &uniform lambda keyword says that arguments following it are 'uniform arguments'. A uniform is an argument which has the same value for the entire stage. &optional and &key are not supported

    {2} Here is our definition for the uniform value. If used in a pipeline as a vertex shader #'example will be called once for every value in the buffer-stream given. That means the 'vert' argument will have a different value for each of the potentially millions of invocations in that ONE pipeline call, however 'loop' will have the same value for the entire pipeline call.

    {2 & 3} All arguments must have their types declared

    {4} Here we see we are using CL's values special form. CEPL fully supports multiple value return in your shaders. If our function #'example was called from another gpu-function then you can use multiple-value-bind to bind the returned values. If however our example function were used as a stage in a pipeline then the multiple returned values will be mapped to the multiple arguments of the next stage in the pipeline.

    That's the basics of gpu-functions. For more details on how they can be used in pipelines please see the documentation for defpipeline-g.

  • ( GPU-FUNCTION NAME )

    macro

    This is CEPL's equivalent of Common Lisp's #'function function.

    It returns the object that represents the gpu-function with the specified signature.

    Currently there is no reason to use this function. It is only available for the sake of completeness and future features.

  • ( LAMBDA-G ARGS &BODY BODY )

    macro

    lambda-g let's you define an anonymous function which can run on the gpu. Commonly refered to in CEPL as a 'gpu function' or 'gfunc'

    Gpu functions try to feel similar to regular CL functions however naturally there are some differences.

    The first and most obvious one is that whilst gpu function can be called from other gpu functions, they cannot be called from lisp functions directly. They first must be composed into a pipeline using defpipeline-g.

    When a gfunc is composed into a pipeline then that function takes on the role of one of the 'shader stages' of the pipeline. For a proper breakdown of pipelines see the docstring for defpipeline-g.

    Let's see a simple example of a gpu function we can then break down

    ;;       {0}       {3}        {1}           {2}
    (lambda-g ((vert my-struct) &uniform (loop :float))
      (values (v! (+ (my-struct-pos vert) ;; {4}
                     (v! (sin loop) (cos loop) 0))
                  1.0)
              (my-struct-col vert)))
    

    {0} So like the normal lambda we specify the arguments (as a list) first

    {1} The &uniform lambda keyword says that arguments following it are 'uniform arguments'. A uniform is an argument which has the same value for the entire stage. &optional and &key are not supported

    {2} Here is our definition for the uniform value. If used in a pipeline as a vertex shader #'example will be called once for every value in the buffer-stream given. That means the 'vert' argument will have a different value for each of the potentially millions of invocations in that ONE pipeline call, however 'loop' will have the same value for the entire pipeline call.

    {2 & 3} All arguments must have their types declared

    {4} Here we see we are using CL's values special form. CEPL fully supports multiple value return in your shaders. If our function #'example was called from another gpu-function then you can use multiple-value-bind to bind the returned values. If however our example function were used as a stage in a pipeline then the multiple returned values will be mapped to the multiple arguments of the next stage in the pipeline.

    That's the basics of gpu-functions. For more details on how they can be used in pipelines please see the documentation for defpipeline-g.

  • ( MAP-G PIPELINE-FUNC STREAM &REST UNIFORMS )

    macro

    The map-g macro maps a buffer-stream over our pipeline and the results of the pipeline are fed into the 'current' fbo.

    This is how we run our pipelines and thus is how we render in CEPL.

    The arguments to map-g are going to depend on what gpu-functions were composed in the pipeline you are calling. However the layout is always as follows.

    • the pipeline function: The first argument is always the pipeline you wish to map the data over.

    • The stream: The next argument will be the buffer-stream which will be used as the inputs to the vertex-shader of the pipeline. The type of the buffer-stream must be mappable onto types of the non uniform args of the gpu-function being used as the vertex-shader.

    • Uniform args: Next you must provide the uniform arguments. These are passed in the same fashion as regular &key arguments.

    CEPL will then run the pipeline with the given args and the results will be fed into the current FBO. If no FBO has been bound by the user then the current FBO will be the default FBO which will most likely mean you are rendering into the surface visable on your screen.

    If an FBO has been bound then the value/s from the fragment shader will be written into the attachments of the FBO. To control this please see the doc-string for with-fbo-bound. The default behaviour is that each of the multiple returns values from the gpu-function used as the fragment shader will be written into the respective attachments of the FBO (first value to first attachment, second value to second attachment, etc)

  • ( MAP-G-INTO FBO PIPELINE-FUNC STREAM &REST UNIFORMS )

    macro

    The map-g-into macro maps a buffer-stream over our pipeline and the results of the pipeline are fed into the supplied fbo.

    This is how we run our pipelines and thus is how we render in CEPL.

    The arguments to map-g-into are going to depend on what gpu-functions were composed in the pipeline you are calling. However the layout is always as follows:

    • target fbo: This is where the results of the pipeline will be written.

    • the pipeline function: The first argument is always the pipeline you wish to map the data over.

    • The stream: The next argument will be the buffer-stream which will be used as the inputs to the vertex-shader of the pipeline. The type of the buffer-stream must be mappable onto types of the non uniform args of the gpu-function being used as the vertex-shader.

    • Uniform args: Next you must provide the uniform arguments. These are passed in the same fashion as regular &key arguments.

    CEPL will then run the pipeline with the given args and the results will be fed into the specified FBO. The value/s from the fragment shader will be written into the attachments of the FBO. If you need to control this in the fashion usualy provided by with-fbo-bound then please see the doc-string for map-g-into*.

    The default behaviour is that each of the multiple returns values from the gpu-function used as the fragment shader will be written into the respective attachments of the FBO (first value to first attachment, second value to second attachment, etc)

    Internally map-g-into wraps call to map-g in with-fbo-bound. The with-fbo-bound has its default configuration which means that:

    • the viewport being will be the dimensions of the gpu-array in the first fbo attachment
    • and blending is enabled

    If you want to use map-g-into and have control over these options please use map-g-into*

  • ( PIPELINE-G CONTEXT &BODY GPIPE-ARGS )

    macro

    pipeline is how we define anonymous rendering pipelines in CEPL.

    Rendering pipelines are constructed by composing gpu-functions.

    Rendering in OpenGL is descibed as a pipeline where a buffer-stream of data usually describing geometry) is mapped over whilst a number of uniforms are available as input and the outputs are written into an FBO.

    There are many stages to the pipeline and a full explanation of the GPU pipeline is beyond the scope of this docstring. However it surfices to say that only 5 stages are fully programmable (and a few more customizable).

    pipeline lets you specify the code (shaders) to run the programmable parts (stages) of the pipeline.

    The available stages kinds are:

    • :vertex
    • :tessellation-control
    • :tessellation-evaluation
    • :geometry
    • :fragment
    • :compute

    To define code that runs on the gpu in CEPL we use gpu functions (gfuncs) Which are defined with defun-g or lambda-g.

    Here is an example pipeline:

    (defun-g vert ((position :vec4) &uniform (i :float))
      (values position (sin i) (cos i)))
    
    (defun-g frag ((s :float) (c :float))
      (v! s c 0.4 1.0))
    
    (defun make-lambda-pipeline ()
      (pipeline ()
        (vert :vec4)
        (frag :float :float)))
    

    Here we define a lambda pipeline which uses the gfunc vert as its vertex shader and used the gfunc frag as the fragment shader.

    It is also possible to specify the name of the stages

    (defun make-lambda-pipeline ()
      (pipeline ()
        :vertex (vert :vec4)
        :fragment (frag :float :float)))
    

    But this is not neccesary unless you need to distinguish between tessellation or geometry stages.

    -- Context --

    The first argument to pipeline-g is the a list of additional information that is confusingly called the 'pipeline's context'. We need to change this name.

    Valid things that can be in this list are:

    A primitive type:

    This specifies what primitives can be passed into this pipeline. By default all pipelines expect triangles. When you map a buffer-stream over a pipeline the primitive kind of the stream must match the pipeline.

    The valid values are:

    :dynamic
    :points
    :lines :line-loop :line-strip
    :lines-adjacency :line-strip-adjacency
    :triangles :triangle-fan :triangle-strip
    :triangles-adjacency :triangle-strip-adjacency
    (:patch <patch-size>)
    

    :dynamic is special, it means that the pipeline will take the primitive kind from the buffer-stream being mapped over. This won't work for with pipelines with geometry or tessellation stages, but it otherwise quite useful.

    A version restriction:

    This tells CEPL to compile the stage for a specific version of GLSL. You usually do not want to use this as CEPL will compile for the version the user is using.

    The value can be one of:

    :140 :150 :330 :400 :410 :420 :430 :440 :450
    

    -- Stage Names --

    Notice that we have to specify the typed signature of the stage. This is because CEPL allows you to 'overload' gpu functions. The signature for the a gpu-function is a list which starts with the function name and whose other elements are the types of the non-uniforms arguments. As an example we can see above that the signature for vert is (vert :vec4), not (vert :vec4 :float).

    -- Passing values from Stage to Stage --

    The return values of the gpu functions that are used as stages are passed as the input arguments of the next. The exception to this rule is that the first return value from the vertex stage is taken and used by GL, so only the subsequent values are passed along.

    We can see this in the example above: #'vert returns 3 values but #'frag only receives 2.

    The values from the fragment stage are writen into the current FBO. This may be the default FBO, in which case you will likely see the result on the screen, or it may be a FBO of your own.

    By default GL only writed the fragment return value to the FBO. For handling multiple return values please see the docstring for with-fbo-bound.

    -- Using our pipelines --

    To call a pipeline we use the map-g macro (or one of its siblings map-g-into/map-g-into*). The doc-strings for those macros go into more details but the basics are that map-g maps a buffer-stream over our pipeline and the results of the pipeline are fed into the 'current' fbo.

    We pass our stream to map-g as the first argument after the pipeline, we then pass the uniforms in the same style as keyword arguments. For example let's see our lambda pipeline example again:

    (defun-g vert ((position :vec4) &uniform (i :float))
      (values position (sin i) (cos i)))
    
    (defun-g frag ((s :float) (c :float))
      (v! s c 0.4 1.0))
    
    (defun make-lambda-pipeline ()
      (pipeline ()
        (vert :vec4)
        (frag :float :float)))
    

    We can call this as follows:

    (setf some-var (make-lambda-pipeline))
    
    (map-g some-var v4-stream :i game-time)
    

  • ( WITH-INSTANCES COUNT &BODY BODY )

    macro

    The with-instances macro is used to enable instancing. You specify number number of instances with the count argument.

    An example of its usage is as follows:

    (with-instances 1000
      (map-g #'draw-grass grass-data :tex *grass-texture*))
    

    This behaves kind of like you had written the following..

    (dotimes (x 1000)
      (map-g #'draw-grass grass-data :tex *grass-texture*))
    

    ..except MUCH more efficiently as you did not have to submit 1000 draw calls.

    Another difference is that, in the pipeline, the variable gl-instance-id will contain the index of which of the 1000 instances is currently being drawn.

• CEPL.IMAGE-FORMATS

  • *BPTC-COMPRESSED-FORMATS*

    special

    A list of all of OpenGL's bptc compressed formats

  • *COLOR-RENDERABLE-FORMATS*

    special

    A list of all of OpenGL's color renderable formats

  • *DEPTH-FORMATS*

    special

    A list of all of OpenGL's depth formats

  • *DEPTH-STENCIL-FORMATS*

    special

    A list of all of OpenGL's depth stencil formats

  • *FLOATING-POINT-FORMATS*

    special

    A list of all of OpenGL's floating point formats

  • *IMAGE-FORMATS*

    special

    A list of all of OpenGL's image formats

  • *RED/GREEN-COMPRESSED-FORMATS*

    special

    A list of all of OpenGL's red/green compressed formats

  • *REGULAR-COLOR-FORMATS*

    special

    A list of all of OpenGL's regular color formats

  • *S3TC/DXT-COMPESSED-FORMATS*

    special

    A list of all of OpenGL's s3tc/dxt compessed formats

  • *SIGNED-INTEGRAL-FORMATS*

    special

    A list of all of OpenGL's signed integral formats

  • *SIGNED-NORMALIZED-INTEGER-FORMATS*

    special

    A list of all of OpenGL's signed normalized integer formats

  • *SPECIAL-COLOR-FORMATS*

    special

    A list of all of OpenGL's special color formats

  • *SRGB-COLOR-FORMATS*

    special

    A list of all of OpenGL's srgb color formats

  • *STENCIL-FORMATS*

    special

    A list of all of OpenGL's stencil formats

  • *UNSIGNED-INTEGRAL-FORMATS*

    special

    A list of all of OpenGL's unsigned integral formats

  • *UNSIGNED-NORMALIZED-INTEGER-FORMATS*

    special

    A list of all of OpenGL's unsigned normalized integer formats

  • *VALID-IMAGE-FORMATS-FOR-BUFFER-BACKED-TEXTURE*

    special

    A list of all of OpenGL's valid image formats for buffer backed texture

  • ( COLOR-RENDERABLE-FORMATP FORMAT )

    function

    This function returns t if the value provided is a keyword that can be found in color-renderable-formats

  • ( DEPTH-FORMATP FORMAT )

    function

    This function returns t if the value provided is a keyword that can be found in depth-formats

  • ( DEPTH-STENCIL-FORMATP FORMAT )

    function

    This function returns t if the value provided is a keyword that can be found in depth-stencil-formats

  • ( IMAGE-FORMATP FORMAT )

    function

    This function returns t if the value provided is a keyword that can be found in image-formats

  • ( STENCIL-FORMATP FORMAT )

    function

    This function returns t if the value provided is a keyword that can be found in stencil-formats

  • ( VALID-IMAGE-FORMAT-FOR-BUFFER-BACKED-TEXTUREP FORMAT )

    function

    This function returns t if the value provided is a keyword that can be found in valid-image-formats-for-buffer-backed-texture

• CEPL.PIXEL-FORMATS

  • PIXEL-FORMAT

    class

    pixel-formats exist to aid the handling and conversion of types in CEPL.

    OpenGL does not make it easy to understand the types involved with textures.

    First there is the name of the type you would use in lisp (or C)

    Then there is the image-format (sometimes called internal-format) which specifies the format on the GPU

    Then there are the types and formats that must be specified when uploading or downloading data to/from a texture (or rather a texture-backed gpu-array).

    CEPL's pixel-fromat pulls together enough metadata that conversions to and from these various representations is easy.

    Technically you shouldnt need to use this directly as it will be handled by CEPL however if you ever have to deal with the formats directly, this type can be a boon.

    It doesnt cover every combination yet, but will in time. Anything missing is considered a bug, so please report it on Github so it can be added to the todo list.

  • ( PIXEL-FORMAT-COMP-LENGTH INSTANCE )

    accessor

    This function when passed a pixel-format will return the number of components it has. The values will be from 1 upto 4

  • ( PIXEL-FORMAT-COMPONENTS INSTANCE )

    accessor

    This function returns the components of the given pixel-format as a keyword

    possible values are: :r :rg :rgb :rgba :stencil-only :depth

  • ( PIXEL-FORMAT-NORMALIZE INSTANCE )

    accessor

    This function returns whether values of the components belonging to the pixel-format are normalized.

    If t then sampling the values on the gpu will gives values in the range 0s0 → 1s0

  • ( PIXEL-FORMAT-REVERSED INSTANCE )

    accessor

    Some pixel-formats are 'reversed' meaning the component order in the data is reversed.

    This function will return t if the pixel format provided is a reversed-type

  • ( PIXEL-FORMAT-SIZES INSTANCE )

    accessor

    Some pixel-formats and image-formats are 'special' and have specifically sized components.

    This function will return a list of sizes in bits of the components.

  • ( PIXEL-FORMAT-TYPE INSTANCE )

    accessor

    This function returns the lisp type of a single 'element' of the given pixel-format.

    For example: - the element type of a :vec3 is a :float. - the element type of a :vec2 is a :float. - the element type of a :int8 is a :int8

  • ( PIXEL-FORMAT-P OBJECT )

    function

    This function returns t if the the given value is a pixel-format. Otherwise it returns nil

• CEPL.UBOS

  • UBO

    class

    A UBO is a structure that abstracts an OpenGL Uniform Buffer Object

    A Ubo is chunk of data stored in a gpu-buffer, which can be used as a uniform in shader pipelines.

    The advantage of using a UBO over just passing the data as regular unforms is that UBOs can be used to share uniforms between different programs, as well as quickly change between sets of uniforms for the same pipeline.

    Let's expand on that a little:

    Switching between uniform buffer bindings is typically faster than switching dozens of uniforms in a pipeline.

    Also, uniform buffer objects can typically store more data than non-buffered uniforms. So they can be used to store and access larger blocks of data than unbuffered uniform values.

    Lastly, they can be used to share information between different programs. So modifying a single buffer can effectively allow uniforms in multiple programs to be updated.

  • ( UBO-DATA INSTANCE )

    accessor

    Returns the gpu-array that contains the data presented by this UBO

  • ( UBO-ID INSTANCE )

    accessor

    This function return the id of the GL UBO abstracted by this CEPL UBO.

  • ( UBO-INDEX INSTANCE )

    accessor

    This function returns the index into the ubo-data where the element defined by this ubo is located

  • ( UBO-OWNS-GPU-ARRAY INSTANCE )

    accessor

    This function returns t if the gpu-array was created by make-ubo or nil if it is using data from a gpu-array passed to make-ubo

  • ( MAKE-UBO DATA &OPTIONAL ELEMENT-TYPE )

    function

    This function will make and return a new ubo

    You need only provide an element type and the lisp data to populate that type.

    For example, given the following type:

    (defstruct-g test (scale :float :accessor scale) (age :int))

    You create a ubo using this type as follows:

    (make-ubo '(1.2 10) 'test)
    

    You can also pass in a c-array or gpu-array and omit the optional type specifier.

    If you wish to make a ubo from a specific element of a c-array or gpu-array please see the #'make-ubo-from-array function.

  • ( MAKE-UBO-FROM-ARRAY DATA &OPTIONAL (INDEX 0) ELEMENT-TYPE )

    function

    This function takes a lisp-array, c-array or gpu-array and an index. It returns a new ubo with the specified element as the data of the ubo.

    If made from a c-array or lisp-array, a fresh gpu memory is allocated to hold the data

    If made from a gpu-array the ubo simply holds a reference to the gpu-array and the index. No new memory is allocated. This means that if that gpu-array is destroyed then this ubo is in an invalid state.

    This also means it is possible to do invalid things when rendering. For example say you used the ubo as an input whilst streaming vertex data from the same array. Consult GL documentation for details on such exceptional cases.

  • ( UBO-DATA-TYPE UBO )

    function

    This function returns the type of the data that is contained in the UBO

• CEPL.GPU-BUFFERS

  • GPU-BUFFER

    class

    gpu-buffer is a struct that abstracts a OpenGL 'Buffer Object'

    Along with the the ID of the GL Object itself it stores the unformatted data as an array of gpu-arrays.

    Every gpu-array in the buffer will have an element-type of :uint8, even if this buffer was created for a gpu-array with a different element-type.

    For example:

    (make-gpu-array '(.1 .2 .3 .4))
    

    will make a gpu-array of 4 floats. However the buffer backing this gpu-array will contain a single array with element-type :uint8 and a length of 16.

    It is not expected that users will be using gpu-buffers directly. Instead they are ususal interacted with via CEPL's gpu-array and ubo features.

  • ( GPU-BUFFER-ARRAYS INSTANCE )

    accessor

    This function returns an array of the raw :uint8 gpu-arrays that make up the data in this gpu-buffer.

  • ( GPU-BUFFER-ID INSTANCE )

    accessor

    This function, when passed a gpu-buffer will return the OpenGL buffer object from the gpu-buffer.

    It is not recommended to modify this directly as the changes from doing so won't be reflected in the layout of the gpu-buffer, which may potentially put the gpu-buffer (and and gpu-array or ubo using it) into an invalid state.

  • ( BUFFER-DATA BUFFER C-ARRAY &KEY (TARGET :ARRAY-BUFFER) (USAGE :STATIC-DRAW) (OFFSET 0) BYTE-SIZE )

    function

    This function populates the gpu-buffer with the contents of the c-array.

    You also pass in the buffer type and the draw type this buffer is to be used for.

    The function returns a buffer object with its format slot populated with the details of the data stored within the buffer

  • ( BUFFER-DATA-RAW DATA-POINTER BYTE-SIZE BUFFER &OPTIONAL (TARGET :ARRAY-BUFFER) (USAGE :STATIC-DRAW) (BYTE-OFFSET 0) )

    function

    This function populates an opengl buffer with the 'data-byte-size' bytes of data from the given point, optionally at the offset provided.

    You also pass in the buffer type and the draw type this buffer is to be used for.

    The function returns a buffer object with its format slot populated with the details of the data stored within the buffer

  • ( BUFFER-RESERVE-BLOCK BUFFER TYPE DIMENSIONS TARGET USAGE )

    function

    This function creates an empty block of data in the opengl buffer equal in size to:

    (* length size-in-bytes-of-type).
    

    It will remove ALL data currently in the buffer

  • ( FREE-BUFFER BUFFER )

    function

    This function, when passed a gpu-buffer will free the memory on the gpu and 'blank' the gpu-buffer.

    Blanking in this case means that the slots of the gpu-buffer will all be set to default values.

  • ( FREE-BUFFERS BUFFERS )

    function

    This function, when passed a list of gpus-buffer will free the gpu memory for all the gpus-buffers and 'blank' them.

    Blanking in this case means that the slots of each gpu-buffer will all be set to default values.

  • ( GPU-BUFFER-P OBJECT )

    function

    This function returns t if the given value is a gpu-buffer. Otherwise it returns nil.

  • ( MAKE-GPU-BUFFER &KEY INITIAL-CONTENTS (BUFFER-TARGET :ARRAY-BUFFER) (USAGE :STATIC-DRAW) )

    function

    This function creates and returns a new gpu-buffer.

    If you wish to populate the buffer during construction you can pass a c-array as the :initial-contents.

    The :usage argument is a hint to OpenGL on how you intend to use the gpu-buffer. It is optional whether your gpu manufacturer's implementation of GL takes any notice of this option. When they do take notice of it, it will to optimize access to the underlying data.

    The :target argument can take any of the following binding targets:

    Buffer Binding Target      Purpose
    -------------------------------------------------------------
    :array-buffer              Vertex attributes
    :atomic-counter-buffer     Atomic counter storage
    :copy-read-buffer          Buffer copy source
    :copy-write-buffer         Buffer copy destination
    :dispatch-indirect-buffer  Indirect compute dispatch commands
    :draw-indirect-buffer      Indirect command arguments
    :element-array-buffer      Vertex array indices
    :pixel-pack-buffer         Pixel read target
    :pixel-unpack-buffer       Texture data source
    :query-buffer              Query result buffer
    :shader-storage-buffer     Read-write storage for shaders
    :texture-buffer            Texture data buffer
    :transform-feedback-buffer Transform feedback buffer
    :uniform-buffer            Uniform block storage
    

    Do note that the default of :array-buffer is perfectly fine for creating the gpu-buffer and uploading the data. It does not limit how the buffer can be used in future parts of your program.

  • ( MAKE-GPU-BUFFER-FROM-ID GL-OBJECT &KEY INITIAL-CONTENTS (BUFFER-TARGET :ARRAY-BUFFER) (USAGE :STATIC-DRAW) )

    function

    This function takes an existing GL Buffer Object and wraps it in a new gpu-buffer.

    If you wish to populate the buffer during construction you can pass a c-array as the :initial-contents.

    The :usage argument is a hint to OpenGL on how you intend to use the gpu-buffer. It is optional whether your gpu manufacturer's implementation of GL takes any notice of this option. When they do take notice of it, it will to optimize access to the underlying data.

    The :target argument can take any of the following binding targets:

    Buffer Binding Target      Purpose
    -------------------------------------------------------------
    :array-buffer              Vertex attributes
    :atomic-counter-buffer     Atomic counter storage
    :copy-read-buffer          Buffer copy source
    :copy-write-buffer         Buffer copy destination
    :dispatch-indirect-buffer  Indirect compute dispatch commands
    :draw-indirect-buffer      Indirect command arguments
    :element-array-buffer      Vertex array indices
    :pixel-pack-buffer         Pixel read target
    :pixel-unpack-buffer       Texture data source
    :query-buffer              Query result buffer
    :shader-storage-buffer     Read-write storage for shaders
    :texture-buffer            Texture data buffer
    :transform-feedback-buffer Transform feedback buffer
    :uniform-buffer            Uniform block storage
    

    Do note that the default of :array-buffer is perfectly fine for creating the gpu-buffer and uploading the data. It does not limit how the buffer can be used in future parts of your program.

  • ( MULTI-BUFFER-DATA BUFFER C-ARRAYS TARGET USAGE )

    function

    This function takes a list of c-arrays and uploads all of the data to the gpu-buffer.

  • ( REALLOCATE-BUFFER BUFFER )

    function

    This function takes a buffer and recreates the data-store for it. All data currently in the buffer will be lost.

• CEPL.VAOS

  • ( FREE-VAO VAO )

    function

    Takes a GL VAO and deletes it

  • ( FREE-VAOS VAOS )

    function

    Takes a list of GL VAOs and deletes them.

    This function exists as a minor optimization.

  • ( MAKE-VAO GPU-ARRAYS &OPTIONAL (INDEX-ARRAY NIL) )

    function

    This function returns a new GL VAO when given

    • a list of gpu-arrays
    • optionally 1 gpu-array to be used as an index

  • ( MAKE-VAO-FROM-ID GL-OBJECT GPU-ARRAYS &OPTIONAL (INDEX-ARRAY NIL) )

    function

    This function takes an existing OpenGL VAO and set it up to stream vertices from the given arrays.

  • ( WITH-VAO-BOUND VAO &BODY BODY )

    macro

    Binds the vao to the gl context and guarentees it will be unbound after the body scope.

    Usually you will not need to interact with the vao directly as you can simply use a buffer-stream and let map-g handle when it should be bound and unbound.

• CEPL.COMPUTE

  • COMPUTE-SPACE

    class

    No docstring provided.

  • ( COMPUTE-SPACE-AS-UVEC3 SPACE )

    accessor

    No docstring provided.

  • ( COMPUTE-SPACE-DIMENSIONS SPACE )

    accessor

    No docstring provided.

  • ( COMPUTE-SPACE-SIZE-X INSTANCE )

    accessor

    No docstring provided.

  • ( COMPUTE-SPACE-SIZE-Y INSTANCE )

    accessor

    No docstring provided.

  • ( COMPUTE-SPACE-SIZE-Z INSTANCE )

    accessor

    No docstring provided.

  • ( MAKE-COMPUTE-SPACE &OPTIONAL (SIZE-X 1) (SIZE-Y 1) (SIZE-Z 1) )

    function

    No docstring provided.

• CEPL.QUERIES

  • ANY-SAMPLES-PASSED-CONSERVATIVE-QUERY

    class

    No docstring provided.

  • ANY-SAMPLES-PASSED-QUERY

    class

    No docstring provided.

  • PRIMITIVES-GENERATED-QUERY

    class

    No docstring provided.

  • SAMPLES-PASSED-QUERY

    class

    No docstring provided.

  • TIME-ELAPSED-QUERY

    class

    No docstring provided.

  • TIMESTAMP-QUERY

    class

    No docstring provided.

  • TRANSFORM-FEEDBACK-PRIMITIVES-WRITTEN-QUERY

    class

    No docstring provided.

  • ( GPU-QUERY-RESULT-AVAILABLE-P QUERY )

    function

    No docstring provided.

  • ( MAKE-ANY-SAMPLES-PASSED-CONSERVATIVE-QUERY )

    function

    No docstring provided.

  • ( MAKE-ANY-SAMPLES-PASSED-QUERY )

    function

    No docstring provided.

  • ( MAKE-PRIMITIVES-GENERATED-QUERY )

    function

    No docstring provided.

  • ( MAKE-SAMPLES-PASSED-QUERY )

    function

    No docstring provided.

  • ( MAKE-TIME-ELAPSED-QUERY )

    function

    No docstring provided.

  • ( MAKE-TIMESTAMP-QUERY )

    function

    No docstring provided.

  • ( MAKE-TRANSFORM-FEEDBACK-PRIMITIVES-WRITTEN-QUERY )

    function

    No docstring provided.

  • ( PULL-ALL-GPU-COMMANDS-ISSUED-TIME )

    function

    No docstring provided.

  • ( PULL-GPU-QUERY-RESULT QUERY &OPTIONAL (WAIT T) )

    function

    No docstring provided.

  • ( PUSH-GPU-QUERY-RESULT-TO-GPU-ARRAY QUERY DESTINATION-GPU-ARRAY &OPTIONAL (DESTINATION-ARRAY-INDEX 0) )

    function

    No docstring provided.

  • ( QUERY-ALL-GPU-COMMANDS-COMPLETED-TIME TIMESTAMP-QUERY )

    function

    No docstring provided.

  • ( WITH-GPU-QUERY-BOUND (QUERY) &BODY BODY )

    macro

    No docstring provided.

• CEPL.RENDER-BUFFERS

  • RENDER-BUFFER

    class

    No docstring provided.

  • ( MAKE-RENDER-BUFFER ELEMENT-TYPE DIMENSIONS &KEY MULTISAMPLE )

    function

    No docstring provided.

  • ( RENDER-BUFFER-DIMENSIONS RENDER-BUFFER )

    function

    No docstring provided.

  • ( RENDER-BUFFER-IMAGE-FORMAT RENDER-BUFFER )

    function

    No docstring provided.

  • ( RENDER-BUFFER-MULTISAMPLE-P RENDER-BUFFER )

    function

    No docstring provided.

  • ( RENDER-BUFFER-P OBJECT )

    function

    No docstring provided.

  • ( RENDER-BUFFER-RESOLUTION RENDER-BUFFER )

    function

    No docstring provided.

• CEPL.SCISSOR

  • ( SCISSOR-VIEWPORT &OPTIONAL (INDEX 0) (CEPL-CONTEXT (CEPL-CONTEXT)) )

    accessor

    No docstring provided.

• CEPL.SSBOS

  • SSBO

    class

    SSBO is a structure that abstracts an OpenGL Shader Storage Buffer Object

    An SSBO is chunk of data stored in a gpu-buffer, which can be used in shader pipelines. They are very similar to UBOs and are used in pretty much the same way. The big differences between them are:

    • SSBOs can be much larger. The OpenGL spec guarantees that UBOs can be up to 16KB in size (implementations can allow them to be bigger). The spec guarantees that SSBOs can be up to 128MB. Most implementations will let you allocate a size up to the limit of GPU memory.

    • SSBOs are writable (even atomically) whereas UBOs are not. Be aware that SSBOs reads and writes use incoherent memory accesses, so they need the appropriate barriers.

    • SSBO access, all things being equal, will likely be slower than UBO access. SSBOs generally are accesses like buffer textures, while UBO data is accessed through internal shader-accessible memory reads. At the very least, UBOs will be no slower than SSBOs.

    • Not yet supported in CEPL SSBOs can have variable storage, up to whatever buffer range was bound for that particular buffer; UBOs must have a specific, fixed storage size. This means that you can have an array of arbitrary length in an SSBO (at the end, rather). The actual size of the array, based on the range of the buffer bound, can be queried at runtime in the shader using the length function on the unbounded array variable.

  • ( SSBO-DATA INSTANCE )

    accessor

    Returns the gpu-array that contains the data presented by this SSBO

  • ( SSBO-ID INSTANCE )

    accessor

    This function return the id of the GL SSBO abstracted by this CEPL SSBO.

  • ( SSBO-INDEX INSTANCE )

    accessor

    This function returns the index into the ssbo-data where the element defined by this ssbo is located

  • ( SSBO-OWNS-GPU-ARRAY INSTANCE )

    accessor

    This function returns t if the gpu-array was created by make-ssbo or nil if it is using data from a gpu-array passed to make-ssbo

  • ( MAKE-SSBO DATA &OPTIONAL ELEMENT-TYPE )

    function

    This function will make and return a new ssbo

    You need only provide an element type and the lisp data to populate that type.

    For example, given the following type:

    (defstruct-g test (scale :float :accessor scale) (age :int))

    You create a ssbo using this type as follows:

    (make-ssbo '(1.2 10) 'test)
    

    You can also pass in a c-array or gpu-array and omit the optional type specifier.

    If you wish to make a ssbo from a specific element of a c-array or gpu-array please see the #'make-ssbo-from-array function

  • ( MAKE-SSBO-FROM-ARRAY DATA &OPTIONAL (INDEX 0) ELEMENT-TYPE )

    function

    This function takes a lisp-array, c-array or gpu-array and an index. It returns a new ssbo with the specified element as the data of the ssbo.

    If made from a c-array or lisp-array, a fresh gpu memory is allocated to hold the data

    If made from a gpu-array the ssbo simply holds a reference to the gpu-array and the index. No new memory is allocated. This means that if that gpu-array is destroyed then this ssbo is in an invalid state.

    This also means it is possible to do invalid things when rendering. For example say you used the ssbo as an input whilst streaming vertex data from the same array. Consult GL documentation for details on such exceptional cases.

  • ( SSBO-DATA-TYPE SSBO )

    function

    This function returns the type of the data that is contained in the SSBO

• CEPL.STENCIL

  • STENCIL-PARAMS

    class

    No docstring provided.

  • ( CURRENT-STENCIL-PARAMS FACE &OPTIONAL (CEPL-CONTEXT (CEPL-CONTEXT)) )

    accessor

    No docstring provided.

  • ( MAKE-STENCIL-PARAMS &KEY (TEST (FUNCTION NEVER)) (VALUE 0) (MASK 0) (ON-STENCIL-TEST-FAIL (FUNCTION KEEP)) (ON-STENCIL-PASS-DEPTH-TEST-FAIL (FUNCTION KEEP)) (ON-STENCIL-PASS-DEPTH-TEST-PASS (FUNCTION KEEP)) )

    function

    No docstring provided.

  • ( STENCIL-PARAMS-MASK PARAMS )

    function

    No docstring provided.

  • ( STENCIL-PARAMS-ON-DPFAIL PARAMS )

    function

    No docstring provided.

  • ( STENCIL-PARAMS-ON-DPPASS PARAMS )

    function

    No docstring provided.

  • ( STENCIL-PARAMS-ON-SFAIL PARAMS )

    function

    No docstring provided.

  • ( STENCIL-PARAMS-ON-STENCIL-PASS-DEPTH-TEST-FAIL PARAMS )

    function

    No docstring provided.

  • ( STENCIL-PARAMS-ON-STENCIL-PASS-DEPTH-TEST-PASS PARAMS )

    function

    No docstring provided.

  • ( STENCIL-PARAMS-ON-STENCIL-TEST-FAIL PARAMS )

    function

    No docstring provided.

  • ( STENCIL-PARAMS-TEST PARAMS )

    function

    No docstring provided.

  • ( STENCIL-PARAMS-VALUE PARAMS )

    function

    No docstring provided.

• CEPL.SYNC

  • ( GPU-FENCE-SIGNALLED-P FENCE )

    function

    No docstring provided.

  • ( MAKE-GPU-FENCE )

    function

    No docstring provided.

  • ( WAIT-ON-GPU-FENCE FENCE &OPTIONAL (TIMEOUT 0) (FLUSH NIL) )

    function

    No docstring provided.

• CEPL.TRANSFORM-FEEDBACK

  • ( TRANSFORM-FEEDBACK-STREAM-ARRAYS TFS )

    accessor

    No docstring provided.

  • ( MAKE-TRANSFORM-FEEDBACK-STREAM &REST BUFFER-BACKED-GPU-ARRAYS )

    function

    No docstring provided.

  • ( WITH-TRANSFORM-FEEDBACK (TRANSFORM-FEEDBACK-STREAM) &BODY BODY )

    macro

    No docstring provided.

• CEPL.TYPES

  • ( IMAGE-FORMAT->LISP-TYPE IMAGE-FORMAT )

    function

    This function, when given a image-format name, will attempt to find and return the name of a lisp type that is equivalent.

    If no such type is found then nil is returned

  • ( IMAGE-FORMAT->PIXEL-FORMAT IMAGE-FORMAT &KEY (ERROR-IF-MISSING T) )

    function

    This function, when given an image-format name, will attempt to find and return equivalent equivalent pixel-format.

    If no such type is found then nil is returned

  • ( LISP-TYPE->IMAGE-FORMAT LISP-TYPE )

    function

    This function, when given a lisp type name, will attempt to find and return the name of a GL image-format that is equivalent.

    If no such type is found then nil is returned

  • ( PIXEL-FORMAT->IMAGE-FORMAT PIXEL-FORMAT &KEY (ERROR-IF-MISSING T) )

    function

    This function, when given a pixel-format object, will attempt to find and return the name of a GL image-format that is equivalent.

    If no such type is found then nil is returned

  • ( PIXEL-FORMAT->LISP-TYPE PIXEL-FORMAT )

    function

    This function, when given a pixel-format object, will attempt to find and return the name of a lisp type that is equivalent.

    If no such type is found then nil is returned

  • ( CAN-BE-SHARED-BETWEEN-CONTEXTS-P OBJECT )

    generic

    This function returns t if the object you pass it can be safely used from two shared contexts. As this function cannot detect which contexts you are refering to you must ensure yourself that the contexts are shared.

  • ( ELEMENT-BYTE-SIZE ARRAY )

    generic

    Returns the size in bytes taken up by a single element of the c-array.

  • ( ELEMENT-TYPE ARRAY )

    generic

    Returns the type of the elements in the c-array.

  • ( GET-TYPED-FROM-FOREIGN TYPE-NAME )

    generic

    This function, when given a foreign type name returns a function that when given a pointer reads the named type foreign from the pointer.

    For example

    (get-typed-from-foreign :vec3)
    

    returns a function that when given a pointer to a :vec3 will return a lisp vec3.

  • ( GET-TYPED-TO-FOREIGN TYPE-NAME )

    generic

    This function, when given a foreign type name returns a function that when given a pointer and a lisp value, converts and writes the value to the foreign location specified by the pointer pointer.

    For example:

    (get-typed-to-foreign :vec3)
    

    returns a function that when given a pointer and a lisp vec3 will write the value into foreign memory.

  • ( LISP-TYPE->PIXEL-FORMAT TYPE )

    generic

    This function, when given a lisp type name, will attempt to find and return an equivalent pixel-format.

    If no such type is found then nil is returned

  • ( DEFSTRUCT-G NAME-AND-OPTIONS &BODY SLOT-DESCRIPTIONS )

    macro

    defstruct-g defines a struct that can be used both gpu-side (in gpu functions, gpu-arrays, ubos, etc) and also cpu-side (in c-arrays, other gstructs, etc)

    You create these using defstruct-g so lets look at an example right now:

    (defstruct-g our-data
      (position :vec3)
      (val :int :accessor val))
    

    This should seem familiar if you have used common lisp's structs.

    You provide a name (with options if you need them) and the definitions for the slots. The format for a slot is:

    (slot-name slot-type)
    
    -or-
    
    (slot-name slot-type :accessor accessor-name)
    

    -- make-* --

    Once defined you would create the above struct as follows:

    (defvar x (make-our-data :position (v! 1 2 3) :val 5))
    

    This will return a fully populated struct in foreign memory. if values are not provided then the slots will be left uninitialized and the contents of the slot are unknown (and likely unsafe) It is rather rare to make a one-off struct like this as it is much more common to use the type in a data-structure like a c-arrays or gpu-array.

    -- Accessors --

    In the 'our-data' example above, the slot named 'position' doesnt have an accesor but the 'val' slot does.

    Both slots will get a lisp-struct-style accessor functions however because of the :accessor in val's slot definition a generic function named by the symbol after :accessor will also be created.

    For the example this means the functions #'our-data-position, #'our-data-val and the generic function #'val are available.

    Whilst :accessor results in a generic function on the cpu side (with the associated overheads) on the gpu side the function to be used is resolved statically and so there is not performance cost.

    -- Options --

    With the exception of :constructor the options for defstruct-g are rarely used but are documented here for the sake of completeness.

    :constructor Setting this to nil means that you will get no make- function Setting this to any other symbol will name the constructor using that symbol The default will is that the constructor will be called make-

    :readers Setting this to nil means that you will get no functions to get the slots' data

    :writers Setting this to nil means that you will get no setf functions to set the slots' data

    :accessors Setting this to nil means that you will get neither of the above.

    :pull-push Setting this to nil means that you will get no push-g or pull-g methods defined for your type

    :attribs Setting this to nil means that defstruct-g will not be able to make buffer-streams from arrays of this type.

    :populate Setting this to nil means that you will not get a internal populate function for this type.

    Some of the above options are redundent in combination with others. For example the push-g method uses #'populate behind the scenes so with populate disabled you can have push-g for this type.

    CEPL currently does a poor job at communicating these conflicts to the user.

• CEPL.TYPES.PREDEFINED

  • G-PC

    class

    g-pc is a CEPL gpu struct with the following slots:

    position: of type vec3 with an accessor method: pos color: of type vec4 with an accessor method: col

  • G-PN

    class

    g-pn is a CEPL gpu struct with the following slots:

    position: of type vec3 with an accessor method: pos normal: of type vec3 with an accessor method: norm

  • G-PNC

    class

    g-pnc is a CEPL gpu struct with the following slots:

    position: of type vec3 with an accessor method: pos normal: of type vec3 with an accessor method: norm color: of type vec4 with an accessor method: col

  • G-PNT

    class

    g-pnt is a CEPL gpu struct with the following slots:

    position: of type vec3 with an accessor method: pos normal: of type vec3 with an accessor method: norm texture: of type vec2 with an accessor method: tex

  • G-PNTC

    class

    g-pntc is a CEPL gpu struct with the following slots:

    position: of type vec3 with an accessor method: pos normal: of type vec3 with an accessor method: norm texture: of type vec2 with an accessor method: tex color: of type vec4 with an accessor method: col

  • G-PT

    class

    g-pt is a CEPL gpu struct with the following slots:

    position: of type vec3 with an accessor method: pos texture: of type vec2 with an accessor method: tex

  • ( BI-TANGENT OBJECT )

    accessor

    This function, returns a :vec3 which is the bi-tangent of the instance.

    You can alternatively use the generic function #'bi-tangent to get this value.

  • ( COL OBJECT )

    accessor

    This function, returns a :vec4 which is the color of the instance.

    You can alternatively use the generic function #'col to get this value.

  • ( NORM OBJECT )

    accessor

    This function, returns a :vec3 which is the normal of the instance.

    You can alternatively use the generic function #'norm to get this value.

  • ( POS OBJECT )

    accessor

    This function, returns a :vec3 which is the position of the instance.

    You can alternatively use the generic function #'pos to get this value.

  • ( TANGENT OBJECT )

    accessor

    This function, returns a :vec3 which is the tangent of the instance.

    You can alternatively use the generic function #'tangent to get this value.

  • ( TEX OBJECT )

    accessor

    This function, returns a :vec2 which is the texture of the instance.

    You can alternatively use the generic function #'tex to get this value.

  • ( MAKE-G-PC &KEY POSITION COLOR )

    function

    This function returns a new instance of the gpu struct of type G-PC

  • ( MAKE-G-PN &KEY POSITION NORMAL )

    function

    This function returns a new instance of the gpu struct of type G-PN

  • ( MAKE-G-PNC &KEY POSITION NORMAL COLOR )

    function

    This function returns a new instance of the gpu struct of type G-PNC

  • ( MAKE-G-PNT &KEY POSITION NORMAL TEXTURE )

    function

    This function returns a new instance of the gpu struct of type G-PNT

  • ( MAKE-G-PNTC &KEY POSITION NORMAL TEXTURE COLOR )

    function

    This function returns a new instance of the gpu struct of type G-PNTC

  • ( MAKE-G-PT &KEY POSITION TEXTURE )

    function

    This function returns a new instance of the gpu struct of type G-PT