5.3.17 Rendering Engine

The (chickadee graphics engine) module provides a Scheme abstraction to the state of the GPU driver. When the Chickadee game loop launches, it takes care to initialize the engine. All draw calls and state changes happen within the context of this engine.

Performing a custom draw call could look something like this:

(with-graphics-state ((g:blend-mode blend:alpha)
                      (g:texture-0 my-texture))
  (shader-apply my-shader #:foo 1))

5.3.17.1 Render States

Render states represent individual state values on the GPU. For example, the current shader. As a naming convention, Chickadee prefixes variables containing render states with g:. Render states can be manipulated using the with-graphics-state macro.

Syntax: with-graphics-state ((name value) …) body …

Evaluate body with render states defined by name changed to value. The render states are restored to their previous values afterwards.

One additional piece of state that the rendering engine has, that is not part of the GPU state, is the current projection matrix:

Procedure: current-projection

Return the currently bound projection matrix (see Matrices).

Syntax: with-projection projection body …

Evaluate body with the current projection matrix bound to projection (see Matrices).

5.3.17.2 Rendering

Chickadee likens a GPU draw call to a Scheme procedure call. A shader (see Shaders) is like a procedure for the GPU to apply. Shaders are passed arguments: The positional arguments are vertex array attributes (see Buffers) and the keyword arguments correspond to the shader’s uniform variables. Scheme uses apply to call a procedure, so Chickadee uses shader-apply to call a shader.

Syntax: shader-apply shader vertex-array [#:uniform-key uniform-value …]

Syntax: shader-apply* shader vertex-array count [#:uniform-key uniform-value …]

Render vertex-array using shader with the uniform values specified in the following keyword arguments.

While shader-apply will draw every vertex in vertex-array, shader-apply* will only draw count vertices.

Syntax: shader-apply/instanced shader vertex-array n [#:uniform-key uniform-value …]

Syntax: shader-apply/instanced shader vertex-array count n [#:uniform-key uniform-value …]

Render vertex-array n times using shader with the uniform values specified in the following keyword arguments.

Instanced rendering is very beneficial for rendering the same object many times with only small differences for each one. For example, the particle effects described in Particles use instanced rendering.

While shader-apply/instanced will draw every vertex in vertex-array, shader-apply* will only draw count vertices.