Storing effects in resource files

Summary

As described in Effect lifecycle in RAMSES the overhead of effect creation in ramses::RamsesClient::createEffect() can be significantly reduced by creating the effects offline and storing them in resource files.

RAMSES provides a set of tools which enable the bundling of effects in resource files. The effects can be loaded during runtime from these files by using one of the resource loading methods in the client API (e.g. ramses::RamsesClient::loadResources). The resources can be resolved using their client-side id (see Effect lifecycle in RAMSES to avoid mixing up the effect id's) by calling ramses::RamsesClient::findResourceById after the loading is finished. RAMSES allows partitioning the effects in multiple files and/or creating some effects online and loading some from files.

Usage

Each effect has to be converted individually by calling ramses-effect-from-glsl-shader:

With full-named arguments:

ramses-effect-from-glsl-shader --in-vertex-shader <filename> --in-fragment-shader <filename> --in-config <filename> --out-resource-file <filename> --out-effect-id <filename> --out-effect-id-type <client|renderer> --out-effect-name <optional string>

With short-named arguments:

ramses-effect-from-glsl-shader -iv <filename> -if <filename> -ic <filename> -or <filename>  -oe <filename> -ot <client|renderer> -on <optional string>

Parameter description:

–in-vertex-shader/-iv:input, the custom vertex shader.
–in-fragment-shader/-if:input, the custom fragment shader.
–in-config/-ic:input, the effect config file, which contains the definition of Uniform Semantics, Attribute Semantics and Compiler Defines.
–out-resource-file/-or:output, the effect resource created by the tool.
–out-effect-id/-oe: path to file where the ramses effect ID will be stored
–out-effect-id-type/-ot: which type of effectId (client or renderer) to use when writing the effectId; see Effect lifecycle in RAMSES for more info
–out-effect-name/-on:optional output, the name for the generated effect. If no name is provided, "in-vertex-shader-file-name_in-fragment-shader-file-name" will be used as the name for the generated effect.

Effect config file description:

For a detailed description of the effect config file, please refer to: Storing GLSL as binary shaders

Combining multiple effects into one file

The file produced by the 'ramses-effect-from-glsl-shader' executable is a common ramses resource file. As such, it can be combined with the ramses resource packer tool (see Packing resources into larger files).