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 )

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

The matrix transformations stages

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:

An object pointer of the given class on success, NULL otherwise.

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:

An object pointer of the given class on success, NULL otherwise.

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:

A pointer to a const instance of class T on success, NULL otherwise.

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:

A pointer to an instance of class T on success, NULL otherwise.

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

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:

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

public int * RED::RenderCode::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)).

public unsigned int RED::RenderCode::GetChannelLocalBindingsCount

(

) const

Returns the number of local channel bindings.

Returns:

The number of channel binding orders as program locals.

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:

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

public bool RED::RenderCode::HasModelMatrix

(

) const

Do we use the model matrix in our shader?

Returns:

true if we use that matrix, false otherwise.

public bool RED::RenderCode::HasModelViewMatrix

(

) const

Do we use the modelview matrix in our shader?

Returns:

true if we use that matrix, false otherwise.

public bool RED::RenderCode::HasModelViewProjectionMatrix

(

) const

Do we use the modelview projection matrix in our shader?

Returns:

true if we use that matrix, false otherwise.

public bool RED::RenderCode::HasViewMatrix

(

) const

Do we use the view matrix in our shader?

Returns:

true if we use that matrix, false otherwise.

public RED::RenderCode::IMPLEMENT_CHUNKINTERPRETER

(

)

public bool RED::RenderCode::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.

public bool RED::RenderCode::IsGenericGLSLBindings

(

) const

Returns:

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

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

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.