# class RED::RenderCode

Input specification of a RED::RenderShader. More...

`#include <REDRenderCode.h>`

Inherits: IChunkSaver and Object.

## Public functions:

RenderCode ( ) | |

virtual | ~RenderCode ( ) |

virtual void * | As ( const RED::CID & iCID ) |

virtual const void * | As ( const RED::CID & iCID ) const |

template< class T_As > const T_As * | As ( ) const |

template< class T_As > T_As * | As ( ) |

void | BindChannel ( RED_VSH_INPUT iShaderInput, RED::MESH_CHANNEL iChannel ) |

RED_RC | BindChannelAsLocal ( int iLocal, RED::MESH_CHANNEL iChannel ) |

void | ClearChannelLocalBindings ( ) |

const int * | GetChannelLocalBindings ( ) const |

int * | GetChannelLocalBindings ( ) |

unsigned int | GetChannelLocalBindingsCount ( ) const |

int | GetShaderInput ( RED_VSH_INPUT iShaderInput ) const |

bool | HasModelMatrix ( ) const |

bool | HasModelViewMatrix ( ) const |

bool | HasModelViewProjectionMatrix ( ) const |

bool | HasViewMatrix ( ) const |

IMPLEMENT_CHUNKINTERPRETER ( ) | |

bool | IsChannelNormalized ( RED_VSH_INPUT iShaderInput ) const |

bool | IsGenericGLSLBindings ( ) const |

void | Reset ( ) |

virtual RED_RC | Save ( RED::IStream * iStream, StreamingPolicy & iPolicy, int iState = -1 ) const |

void | SetGenericGLSLBindings ( bool iGeneric ) |

void | SetModelMatrix ( bool iRequest ) |

void | SetModelViewMatrix ( bool iRequest ) |

void | SetModelViewProjectionMatrix ( bool iRequest ) |

void | SetNormalizedChannel ( RED_VSH_INPUT iShaderInput, bool iOnOff = true ) |

void | SetViewMatrix ( bool iRequest ) |

## Public static functions:

static RED::CID | GetClassID ( ) |

## Protected variables:

bool | _glsl_generic |

bool | _hdmv |

bool | _hdmvp |

bool | _iocs2wcs |

bool | _iwcs2vcs |

int | _meshaslocal [RED_RCODE_MAX_LOCAL_BINDINGS] |

unsigned int | _nb_meshaslocal |

bool | _normalized [RED_VSH_NB_INPUTS] |

int | _vshinput [RED_VSH_NB_INPUTS] |

## Detailed description:

Input specification of a RED::RenderShader.

This class performs the mapping between geometrical inputs and vertex shader inputs. We have two categories of shader inputs that are handled in the class:

- Input matrices: Matrices that are enabled will be loaded to vertex shaders and therefore accessible to the ARB or GLSL programs that are in the RED::RenderShader that are using the RED::RenderCode.
- Input vertex programs attributes: these are the vertex, normal, color, texture channels, and other parameters that can be sent along with a vertex as input to the vertex program of a shader.

We use the following definitions to classify matrices:

- WCS: World Coordinate System,
- VCS: View Coordinate System,
- OCS: Object Coordinate System,
- DCS: Device Coordinate System.

Some well known matrices are expressed this way:

- The "modelview" matrix is the OCS to VCS transformation: this is the inverse viewpoint matrix, multiplied by the model transformation matrix. A point local to an object is turned in the viewpoint axis system. Note that there are two versions of that matrix that can be bound to a program. See below for details.
- The "modelview projection" matrix is the OCS to DCS transformation. It adds the VCS to DCS transformation over the previous matrix.
- The "viewport" matrix is the VCS to DCS transformation. It converts an object from the view system to the screen, performing perspective foreshortening.
- The "model" matrix is the OCS to WCS transformation.

Input matrices are sent to the vertex shader program using the following bindings (ARB or GLSL):

- View matrix: 'state.matrix.program[0]' or 'gl_TextureMatrix[0]'.
- Model matrix: 'state.matrix.program[1]' or 'gl_TextureMatrix[1]'.
- Modelview projection matrix: 'state.matrix.program[2]' or 'gl_TextureMatrix[2]';
- Modelview matrix: 'state.matrix.program[3]' or 'gl_TextureMatrix[3]';

Matrices described above are high definition matrices, which are double precision concatenations of all the matrices that compose the transformation pipeline, before being loaded to the OpenGL layer.

The modelview matrix and the modelview projection matrices are enabled by default. The model matrix and the view matrices are disabled by default.

The legacy OpenGL pipeline matrix are still accessible in shaders. These matrices have a lower accuracy compared to matrices emitted by the RED::RenderCode and accessible by shaders using them:

- Modelview projection matrix: 'state.matrix.mvp' or 'gl_ModelViewProjectionMatrix'.
- Modelview matrix: 'state.matrix.program[3]' or 'gl_ModelViewMatrix'.

A vertex shader input channel must be set to an output of a geometrical data of a shape to be rendered. For instance, the RED::MCL_VERTEX vertex array of a geometry must be bound to the RED_VSH_VERTEX input channel of a vertex program for the positions of the geometry to be sent to the program. A value of (-1) indicates that the vertex shader input is not bound to any geometrical output of the engine.

The RenderCode features a specific binding mechanism usable only for all ray-traced indirect lighting calculations: mesh input channels can be bound as program locals for the processing of indirect rays. This mechanism aims at overcoming the limited number of interpolation channels provided by the hardware that is often outnumbered by indirect shaders.

GLSL bindings can be modified for some hardware. See RED::RenderCode::SetGenericGLSLBindings.

## Functions documentation

public RED::RenderCode::RenderCode | ( | ) |

Default construction method.

public virtual RED::RenderCode::~RenderCode | ( | ) |

Destructor.

public static RED::CID RED::RenderCode::GetClassID | ( | ) |

Reimplements: RED::IChunkSaver::GetClassID.

public virtual void * RED::RenderCode::As | ( | const RED::CID & | iCID | ) |

Converts the object to an instance of the given type.

Parameters:

iCID: | Requested class. |

Returns:

Reimplements: RED::Object::As.

public virtual const void * RED::RenderCode::As | ( | const RED::CID & | iCID | ) const |

Converts the object to an instance of the given type.

Parameters:

iCID: | Requested class. |

Returns:

Reimplements: RED::Object::As.

template< class T_As > public const T_As * RED::RenderCode::As | ( | ) const |

Template version of the as const method.

Simply set *T* to be the class you want to retrieve an interface to.

Returns:

Reimplements: RED::Object::As.

template< class T_As > public T_As * RED::RenderCode::As | ( | ) |

Template version of the as method.

Simply set *T* to be the class you want to retrieve an interface to.

Returns:

Reimplements: RED::Object::As.

public void RED::RenderCode::BindChannel | ( | RED_VSH_INPUT | iShaderInput, |

RED::MESH_CHANNEL | iChannel | ||

) |

Binds a geometrical data channel on a vertex shader's channel.

This method specify which geometrical channel of the input geometry is to be bound as a vertex attribute of the vertex shader.

An example of use of this function can be found in the Writing a custom rendering shader in ARB tutorial.

Parameters:

iShaderInput: | Vertex shader input to bind. |

iChannel: | Geometrical data channel source of the information. |

public RED_RC RED::RenderCode::BindChannelAsLocal | ( | int | iLocal, |

RED::MESH_CHANNEL | iChannel | ||

) |

Binds a channel as program local parameter.

This method only works for the rendering of indirect lighting passes. It binds the specified mesh input channel directly as a set of three constants accessible directly at the pixel shader stage.

The reason behind this mechanism is the fact that there's only a limited number of interpolation channels available between a vertex program and a pixel program. Because we replicate each data channel three times for each vertex of a triangle, we quickly overload the number of available interpolation channels.

iChannel triangle data of rendered meshes will be bound at iLocal, iLocal+1 and iLocal+2 for all indirect lighting passes. The method stacks all channel binding orders so that the same channel can be bound twice or more on program locals.

Parameters:

iLocal: | 'program.local' slots that are to be used for the binding of iChannel. We use three consecutive slots iLocal, iLocal+1 and iLocal+2. |

iChannel: | Mesh input channel to bind. |

Returns:

RED_BAD_PARAM if the method has received an invalid parameter,

RED_ALLOC_FAILURE if an internal allocation has failed,

RED_FAIL if we exceed the maximal number of possible local bindings.

public void RED::RenderCode::ClearChannelLocalBindings | ( | ) |

Removes all mesh data channels local bindings.

public const int * RED::RenderCode::GetChannelLocalBindings | ( | ) const |

Returns the list of local channel bindings.

Returns:

public int * RED::RenderCode::GetChannelLocalBindings | ( | ) |

Returns the list of local channel bindings.

Returns:

public unsigned int RED::RenderCode::GetChannelLocalBindingsCount | ( | ) const |

Returns the number of local channel bindings.

Returns:

public int RED::RenderCode::GetShaderInput | ( | RED_VSH_INPUT | iShaderInput | ) const |

Returns the vertex shader input binding.

This method returns the geometrical channel that is bound to a given vertex shader attribute entry.

Parameters:

iShaderInput: | The queried vertex shader input. |

Returns:

public bool RED::RenderCode::HasModelMatrix | ( | ) const |

Do we use the model matrix in our shader?

Returns:

public bool RED::RenderCode::HasModelViewMatrix | ( | ) const |

Do we use the modelview matrix in our shader?

Returns:

public bool RED::RenderCode::HasModelViewProjectionMatrix | ( | ) const |

Do we use the modelview projection matrix in our shader?

Returns:

public bool RED::RenderCode::HasViewMatrix | ( | ) const |

Do we use the view matrix in our shader?

Returns:

public bool RED::RenderCode::IsChannelNormalized | ( | RED_VSH_INPUT | iShaderInput | ) const |

Is the given channel normalized?

Parameters:

iShaderInput: | The channel id. |

Returns:

public bool RED::RenderCode::IsGenericGLSLBindings | ( | ) const |

Returns:

public void RED::RenderCode::Reset | ( | ) |

Re-initializes a RenderCode.

Set all values back to "no bind" (-1), disarms all matrix requests.

public virtual RED_RC RED::RenderCode::Save | ( | RED::IStream * | iStream, |

StreamingPolicy & | iPolicy, | ||

int | iState = -1 | ||

) | const |

Saves the object content as one or more chunks in the given stream.

Parameters:

iStream: | Pointer to the stream where the data must be saved. |

iPolicy: | Reference to the streaming policy to be used. |

iState: | Optional state number parameter at which the data to be saved must be retrieved. Default is set to 0 (for current state). |

Returns:

RED_FILE_WRITE_ERROR on a file write error (if iStream is a file stream),

RED_ALLOC_FAILURE on a memory allocation error,

RED_FAIL otherwise.

Implements: RED::IChunkSaver::Save.

public void RED::RenderCode::SetGenericGLSLBindings | ( | bool | iGeneric | ) |

Override legacy GLSL bindings on AMD and INTEL to favor generic attributes bindings.

When running GLSL shaders - by default and to get the broadest range of compatible hardware - REDsdk uses:

- glVertexAttribPointer calls to bind mesh inputs on NVIDIA hardware.
- glVertexPointer, glNormalPointer, glTexCoordPointer, ...on AMD and INTEL hardware.

These legacy bindings that can be used to write old style GLSL programs don't allow the use of modern bindings based on 'layout( location = xxx ) in vec4 myValue" on AMD and INTEL graphics. By turning on the iGeneric flag in this method, legacy bindings are replaced by generic attribute bindings allowing the usage of layout declarations across all hardware.

Parameters:

iGeneric: | Set to true to force generic bindings across all hardwares, false to keep generic bindings on NVIDIA, and legacy bindings on AMD / INTEL. |

public void RED::RenderCode::SetModelMatrix | ( | bool | iRequest | ) |

Requests the model matrix.

The model matrix is bound to the vertex shader input, if iRequest is true. The model matrix can be accessed as the GL_MATRIX1_ARB bound matrix in OpenGL. Therefore, it can be accessed as 'state.matrix.program[1]' in ARB shaders and as 'gl_TextureMatrix[1]' in GLSL.

This matrix is disabled by default.

The Writing a custom rendering shader using geometry program tutorial contains a good example of how this function works.

Parameters:

iRequest: | Ask for that matrix if true. |

public void RED::RenderCode::SetModelViewMatrix | ( | bool | iRequest | ) |

Requests the modelview matrix.

This matrix is the result of the double precision multiplication of the camera view matrix by the current model transformation matrix. The result is double precision and uploaded on the GPU. It can be accessed as the GL_MATRIX3_ARB bound matrix in OpenGL. Therfore it can be accessed as 'state.matrix.program[3]' in ARB shaders and as 'gl_TextureMatrix[3]' in GLSL.

This matrix is enabled by default.

Parameters:

iRequest: | Ask for the calculation of that matrix if true. |

public void RED::RenderCode::SetModelViewProjectionMatrix | ( | bool | iRequest | ) |

Requests the modelview projection matrix.

This matrix is the result of the double precision multiplication of the projection matrix by the camera view matrix and by the current model transformation matrix. The result is double precision and uploaded on the GPU. It can be accessed as the GL_MATRIX2_ARB bound matrix in OpenGL. Therefore it can be accessed as 'state.matrix.program[2]' in ARB shaders and as 'gl_TextureMatrix[2]' in GLSL.

This matrix is enabled by default.

Parameters:

iRequest: | Ask for the calculation of that matrix if true. |

public void RED::RenderCode::SetNormalizedChannel | ( | RED_VSH_INPUT | iShaderInput, |

bool | iOnOff = true | ||

) |

Forces the data bound to a channel to be normalized.

The default behavior of the RenderCode is to let the data sent for a rendering order unmodified. However, through this method a channel can be normalized: e.g. the length of the vector sent to the GPU is set to 1.

The channel normalization may not be supported for all combinations of vector sizes/formats.

Parameters:

iShaderInput: | Shader input channel to be normalized. |

iOnOff: | Enable or disable the normalization. |

public void RED::RenderCode::SetViewMatrix | ( | bool | iRequest | ) |

Requests the view matrix.

The view matrix is bound to the vertex shader input, if iRequest is true. The view matrix can be accessed as the GL_MATRIX0_ARB bound matrix in OpenGL. Therefore, it can be accessed as 'state.matrix.program[0]' in ARB shaders and as 'gl_TextureMatrix[0]' in GLSL.

This matrix is disabled by default.

The Writing a custom rendering shader using geometry program tutorial contains a good example of how this function works.

Parameters:

iRequest: | Ask for that matrix if true. |

## Variables documentation

GLSL generic binding mode.

Request the high definition modelview matrix?

Request the high definition modelview projection matrix?

Request the model matrix?

Request the view matrix?

Mesh channel bindings as program.local list. Encoded as channel + ( local << 16 ).

Number of bindings currently registered in _meshaslocal.

List of normalized channels.

Vertex shader channels bindings.