Summary

As described in Effect lifecycle in RAMSES, effects need to be preprocessed by RAMSES before passing them to an offline shader compiler which in turn creates binary shaders. In short, the tool generates two things:

parsed shader source code which RAMSES would pass to OpenGL
effect ID which will be used by ramses::IBinaryShaderCache to resolve binary shaders on the renderer side

The shader source is stored separately for the vertex and fragment shaders, so that they can be passed directly to an offline shader compiler.

Usage

With full named parameters:

ramses-shader-from-glsl-shader --in-vertex-shader <filename> --in-fragment-shader <filename>
--in-config <filename> --out-vertex-shader <filename> --out-fragment-shader <filename>
--out-effect-id <filename> --out-effect-id-type <client|renderer>

With short named parameters:

ramses-shader-from-glsl-shader -iv <filename> -if <filename> -ic <filename> -ov <filename> -of <filename>

-oe <filename> -ot <client|renderer>

Parameter description:

–in-vertex-shader/-iv: input file containing the vertex shader to convert
–in-fragment-shader/-if: input file containing the fragment shader to convert
–in-config/-ic: input config file which contains the definition of Uniform Semantics, Attribute Semantics and Compiler Defines (see below)
–out-vertex-shader/-ov: path to file where the generated ramses vertex shader will be stored
–out-fragment-shader/-of: path to file where the generated ramses fragment shader will be stored
–out-effect-id/-oe: path to file where the ramses effect ID will be stored
–out-effect-id-type/-ot: which type (client or renderer) of effectId to use when writing the effectId; see Effect lifecycle in RAMSES for more info

Effect config file description:

Besides the vertex and fragment shaders, the user also has to provide a configuration which contains additional information such as definition of Attribute Semantics, Uniform Semantics and Compiler Defines. The config file has a fixed and simple line-based format. Below is a complete example of a config file which has all possible types of parameters which can be passed to RAMSES. It is possible to omit properties which are not needed.

UNIFORM_SEMANTIC matrix44fInput EEffectUniformSemantic_ModelViewMatrix
UNIFORM_SEMANTIC texture2dInput EEffectUniformSemantic::TextTexture
ATTRIBUTE_SEMANTIC vec2fArrayInput EEffectAttributeSemantic::TextPositions
DEFINE enable_multidraw
DEFINE draw_buffers

The configuration properties are exactly the same as those provided to ramses::EffectDescription when creating effects with the RAMSES API. See the documentation of ramses::EffectDescription for more details.

Uniform semantic definition: UNIFORM_SEMANTIC inputName EEffectUniformSemantic_XXXX

To define a Uniform Semantic, start a line with keyword UNIFORM_SEMANTIC. The second token is the inputName for the semantic, and the third token is the semantic name.

Attribute semantic definition: ATTRIBUTE_SEMANTIC inputName EEffectAttributeSemantic::XXX

To define an attribute semantic, start a line with keyWord ATTRIBUTE_SEMANTIC. The second token is the inputName for the semantic, and the third token is the semantic name.

Compiler defintion: DEFINE nameOrExpression

To define a compiler defintion, the first Token is the keyword DEFINE, and the second token is the definition statement.