Full Example of how to use Shader Tools in RAMSES

Summary

This example shows how to use the shader tools to get the most benefit.

Input

There are two different effects to be processed in this example:

• A car (vertex and a fragment shader)
• A tree (vertex and a fragment shader)

Pipelines

The input gets processed in two different pipelines:

• Client Pipeline: produces results for the ECU that contains the application with ramses::RamsesClient
• Renderer Pipeline: produces results for the ECU that contains the ramses::RamsesRenderer and the implementation of the ramses::IBinaryShaderCache
• (It's possible that these are not two seperate but one and the same ECU)

Guide: how to use shader tools and which ECUs use the results

Client Pipeline

For in advance known effects this pipeline saves the GLSL parsing in ramses::RamsesClient::createEffect() during runtime, by parsing it offline and storing the resulting resource file.

The client pipeline includes following stages:

• ramses-effect-from-glsl-shader (see Storing effects in resource files) gets executed with the shaders of both effects as input.
• Outputs one resource file (.res) and one file that holds a ramses::resourceId_t refering to a specific effect, for each effect.
• The two Ids must be saved on the ECU that runs the ramses::RamsesClient and known to the application, that wants to use the effects
• ramses-resource-packer (see Packing resources into larger files) gets executed with the two resource files as input
• Outputs one resource file containing both effects
• The resource file can now be loaded by ramses::RamsesClient::loadResources()
• In order to use one of these effects in run-time (e.g. to create a ramses::Appearance or query a uniform) it can be retrieved
  using ramses::RamsesClient::findResourceById() with the ramses::resourceId_t that was ouput by ramses-effect-from-glsl-shader and saved for the specific effect

Renderer Pipeline

This pipeline saves the OpenGL compilation of an effect on the renderer during runtime, by compiling it offline and storing the binary result.

The renderer pipeline includes following stages:

• ramses-shader-from-glsl-shader (see Storing GLSL as binary shaders) gets executed with the shaders of both effects as input.
• Outputs preprocessed shaders and a file that holds a ramses::effectId_t refering to the effect, for each effect
• The two Ids must be saved on the ECU that runs the ramses::RamsesRenderer and known to the implementation of ramses::IBinaryShaderCache
  Note that these Ids are different from the Ids used in the 'client pipeline' above
• An offline shader compiler executes the preprocessed shaders. Note that it is crucial that the offline shader compiler generates the correct binary shader format
  for the graphics device used by the renderer
• Outputs a binary shader for each effect
• The binary shaders can be stored in an implementation of ramses::IBinaryShaderCache that is accessible from the ramses::RamsesRenderer. The renderer will query
  cached shaders by calling ramses::IBinaryShaderCache::hasBinaryShader() with the associated ramses::effectId_t.
• The binary shaders can be stored on the ECU that runs the ramses::RamsesRenderer and can be used with the ramses::IBinaryShaderCache and the effect specific ramses::effectId_t that was output by ramses-shader-from-glsl-shader