RenderCode

Functions

SET_CID

IMPLEMENT_AS

SET_CHUNK_SIGNATURE

IMPLEMENT_CHUNKINTERPRETER

RenderCode

~RenderCode

void

Reset

void

SetViewMatrix

bool

HasViewMatrix

void

SetModelMatrix

bool

HasModelMatrix

void

SetModelViewProjectionMatrix

bool

HasModelViewProjectionMatrix

void

SetModelViewMatrix

bool

HasModelViewMatrix

void

BindChannel

int

GetShaderInput

void

SetNormalizedChannel

bool

IsChannelNormalized

void

SetGenericGLSLBindings

bool

IsGenericGLSLBindings

RED_RC

BindChannelAsLocal

const int *

GetChannelLocalBindings

int *

GetChannelLocalBindings

unsigned int

GetChannelLocalBindingsCount

void

ClearChannelLocalBindings

RED_RC

Save

Detailed Description

class RenderCode : public RED::Object, public RED::IChunkSaver

Input specification of a RED::RenderShader.

@related Writing Custom Render Shaders, class RED::IMaterial, class RED::RenderShader, class RED::StateShader, Writing a Custom Rendering Shader in ARB, Writing a Custom Rendering Shader in GLSL

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’.

../build/doxygen/RED/xml/API_ModelViewProjMatrices.png

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.

Public Functions

SET_CID(CID_class_REDRenderCode)
IMPLEMENT_AS()
SET_CHUNK_SIGNATURE (0x00000408)
IMPLEMENT_CHUNKINTERPRETER()
RenderCode()

Default construction method.

virtual ~RenderCode()

Destructor.

void Reset()

Re-initializes a RenderCode.

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

inline void 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 \ref wf_custom_geometry_shader tutorial contains a good example of how this function works.

Parameters

iRequest – Ask for that matrix if true.

inline bool HasViewMatrix() const

Do we use the view matrix in our shader?

Returns

true if we use that matrix, false otherwise.

inline void 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 \ref wf_custom_geometry_shader tutorial contains a good example of how this function works.

Parameters

iRequest – Ask for that matrix if true.

inline bool HasModelMatrix() const

Do we use the model matrix in our shader?

Returns

true if we use that matrix, false otherwise.

inline void 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.

inline bool HasModelViewProjectionMatrix() const

Do we use the modelview projection matrix in our shader?

Returns

true if we use that matrix, false otherwise.

inline void 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.

inline bool HasModelViewMatrix() const

Do we use the modelview matrix in our shader?

Returns

true if we use that matrix, false otherwise.

inline void 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 \ref wf_custom_arb_shader tutorial.

Parameters
  • iShaderInput – Vertex shader input to bind.

  • iChannel – Geometrical data channel source of the information.

inline int 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

-1 if we have no data bound to this channel, or a value in the RED::MESH_CHANNEL enum.

inline void 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
  • iShaderInputShader input channel to be normalized.

  • iOnOff – Enable or disable the normalization.

inline bool IsChannelNormalized(RED_VSH_INPUT iShaderInput) const

Is the given channel normalized?

Parameters

iShaderInput – The channel id.

Returns

true if the corresponding channel is normalized, false otherwise.

inline void 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.

inline bool IsGenericGLSLBindings() const
Returns

true if generic GLSL bindings are in use everywhere, false otherwise.

RED_RC 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_OK if the operation has succeeded,

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.

inline const int *GetChannelLocalBindings() const

Returns the list of local channel bindings.

Returns

A list of (channel,local) bindings. Each integer in the list is encoded using (channel + (local << 16)).

inline int *GetChannelLocalBindings()

Returns the list of local channel bindings.

Returns

A list of (channel,local) bindings. Each integer in the list is encoded using (channel + (local << 16)).

inline unsigned int GetChannelLocalBindingsCount() const

Returns the number of local channel bindings.

Returns

The number of channel binding orders as program locals.

void ClearChannelLocalBindings()

Removes all mesh data channels local bindings.

virtual RED_RC 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_OK on success,

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.