class RED::IMaterial

This interface gives access to the material's properties. More...

#include <REDIMaterial.h>

Inherits: IREDObject.

Public functions:

virtual RED_RCAddBatchArrays ( RED::Vector< void * > & iData, RED::Vector< RED::MESH_CHANNEL > & iChannel, RED::Vector< int > & iVertexSize, RED::Vector< RED::MESH_FORMAT > & iFormat, int iVerticesCount, const RED::State & iState ) = 0
virtual RED_RCAddBatchIndices ( int * iIndex, int iCount, int iPrimitiveSize, const RED::State & iState ) = 0
virtual RED_RCAddBatchSubArrayUpdate ( void * iData, int iNumVertexStart, int iVerticesCount, const RED::State & iState ) = 0
virtual RED_RCAddShaderToPass ( unsigned int iShaderID, RED::MATERIAL_PASS iPass, RED::LIST_POS iPosition, const RED::LayerSet & iLayerSet, const RED::State & iState ) = 0
virtual RED_RCClearShaderPass ( RED::MATERIAL_PASS iPass, const RED::LayerSet & iLayerSet, const RED::State & iState ) = 0
virtual RED_RCClearShaders ( const RED::State & iState ) = 0
virtual RED_RCCopyFrom ( const RED::Object & iMaterial, const RED::State & iState, int iSrcStateNumber = -1 ) = 0
virtual RED_RCCopyFrom ( const RED::Object & iMaterial, const RED::LayerSet & iLayerSetSrc, const RED::LayerSet & iLayerSetDest, const RED::State & iState, bool iImageCopy = false, bool iTinyImageCopy = false ) = 0
virtual RED_RCDeleteShader ( unsigned int iShaderID, const RED::State & iState ) = 0
virtual RED_RCGetBatchArrays ( RED::Vector< RED::Vector< void * > > & oData, RED::Vector< RED::Vector< RED::MESH_CHANNEL > > & oChannel, RED::Vector< RED::Vector< int > > & oVertexSize, RED::Vector< RED::Vector< RED::MESH_FORMAT > > & oFormat, RED::Vector< int > & oVerticesCount, int iStateNumber = -1 ) const = 0
virtual RED_RCGetBatchArraysCount ( int & oCount, int iStateNumber = -1 ) const = 0
virtual RED_RCGetBatchIndices ( RED::Vector< int * > & oIndex, RED::Vector< int > & oCount, RED::Vector< int > & oPrimitiveSize, int iStateNumber = -1 ) const = 0
virtual RED_RCGetBatchIndicesCount ( int & oCount, int iStateNumber = -1 ) const = 0
virtual RED_RCGetBatchMode ( bool & oBatchMode, int iStateNumber = -1 ) const = 0
virtual RED_RCGetCaustics ( bool & oReflectiveCaustics, bool & oRefractiveCaustics, const RED::LayerSet & iLayerSet, int iStateNumber = -1 ) const = 0
virtual RED_RCGetDisplacement ( float & oDispHeight, RED::Object *& oDispTexture, RED::Matrix & oDispMatrix, RED::MESH_CHANNEL & oDispUV, float & oDispOffset, const RED::LayerSet & iLayerSet, int iStateNumber = -1 ) const = 0
virtual RED_RCGetImageList ( RED::Map< RED::Object *, int > & oImageList, int iStateNumber = -1 ) const = 0
virtual RED_RCGetImmediateMode ( bool & oOnOff, int iNumState = -1 ) const = 0
virtual const RED::LayerSet &GetLayerSet ( int iLayerSet, int iStateNumber = -1 ) const = 0
virtual RED_RCGetPolygonOffset ( float & oPolyOffsetFactor, float & oPolyOffsetUnits, const RED::LayerSet & iLayerSet, int iStateNumber = -1 ) const = 0
virtual RED_RCGetPriority ( int & oPriority, int iStateNumber = -1 ) const = 0
virtual const RED::Shader *GetShader ( unsigned int iShaderID, RED::MATERIAL_PASS iPass, const RED::LayerSet & iLayerSet, int iNumState = -1 ) const = 0
virtual RED_RCGetShader ( unsigned int iShaderID, RED::MATERIAL_PASS iPass, RED::Shader *& oShader, const RED::LayerSet & iLayerSet, const RED::State & iState ) = 0
virtual RED_RCGetShaderList ( RED::Vector< const RED::Shader * > & oShaders, int iNumState = -1 ) const = 0
virtual RED_RCGetShaderList ( RED::Vector< RED::Shader * > & oShaders, const RED::State & iState ) = 0
virtual RED_RCGetShaders ( RED::Vector< RED::Shader * > & oShaders, RED::MATERIAL_PASS iPass, const RED::LayerSet & iLayerSet, const RED::State & iState ) = 0
virtual RED_RCGetShaders ( RED::Vector< RED::Shader * > & oShaders, RED::MATERIAL_PASS iPass, const RED::LayerSet & iLayerSet, int iNumState = -1 ) const = 0
virtual RED_RCGetUsedChannels ( RED::Map< RED::LayerSet, RED::Vector< RED::MESH_CHANNEL > > & ioChannels, int iNumState = -1 ) = 0
virtual RED_RCInsertShadersFrom ( const RED::Object & iMaterial, const RED::LayerSet & iLayerSet, const RED::State & iState ) = 0
virtual RED_RCIsBatchArrayUpdate ( bool & oUpdate, void * iRefData, void * iData, int iStateNumber = -1 ) const = 0
virtual boolIsRegistered ( unsigned int iID, int iStateNumber = -1 ) const = 0
virtual intLayerSetsCount ( int iStateNumber = -1 ) const = 0
virtual RED_RCRegisterShader ( const RED::Shader & iShader, const RED::State & iState ) = 0
virtual RED_RCRemoveBatchArray ( void * iData, const RED::State & iState ) = 0
virtual RED_RCRemoveShaderFromPass ( unsigned int iShaderID, RED::MATERIAL_PASS iPass, const RED::LayerSet & iLayerSet, const RED::State & iState ) = 0
virtual RED_RCSetBatchArrayUpdate ( void * iRefData, void * iData, const RED::State & iState ) = 0
virtual RED_RCSetBatchMode ( bool iBatchMode, const RED::State & iState ) = 0
virtual RED_RCSetCaustics ( bool iReflectiveCaustics, bool iRefractiveCaustics, const RED::LayerSet & iLayerSet, const RED::State & iState ) = 0
virtual RED_RCSetCuttingPlane ( const float iPlaneEquation[4], const RED::Shader * iSectionCapShader, const RED::LayerSet & iLayerSet, bool iEdgeMaterial, const RED::State & iState ) = 0
virtual RED_RCSetDisplacement ( float iDispHeight, const RED::Object * iDispTexture, const RED::Matrix & iDispMatrix, RED::MESH_CHANNEL iDispUV, float iDispOffset, const RED::LayerSet & iLayerSet, const RED::State & iState ) = 0
virtual RED_RCSetImmediateMode ( bool iOnOff, const RED::State & iState ) = 0
virtual RED_RCSetLogoMask ( const RED::Vector< RED::Object * > & iLogoMask, const RED::Vector< RED::Matrix > & iLogoMaskMatrix, const RED::Vector< RED::MESH_CHANNEL > & iLogoMaskUV, bool iInvert, const RED::LayerSet & iLayerSet, const RED::State & iState ) = 0
virtual RED_RCSetPolygonOffset ( float iPolyOffsetFactor, float iPolyOffsetUnits, const RED::LayerSet & iLayerSet, const RED::State & iState ) = 0
virtual RED_RCSetPriority ( int iPriority, const RED::State & iState ) = 0
virtual RED_RCSetupGenericBumpyDiffuseMaterial ( bool iDoubleSided, const RED::Color & iDiffuseColor, const RED::Object * iDiffuseTexture, const RED::Matrix & iDiffuseUVMatrix, RED::MESH_CHANNEL iDiffuseUVChannel, const RED::Object * iBumpTexture, const RED::Matrix & iBumpUVMatrix, RED::MESH_CHANNEL iBumpUVChannel, RED::MESH_CHANNEL iBumpTangentsChannel, const RED::LayerSet * iRealtimeLayerSet, const RED::LayerSet * iPhotorealisticLayerSet, RED::Object * iResourceManager, const RED::State & iState ) = 0
virtual RED_RCSetupGenericDiffuseMaterial ( bool iDoubleSided, const RED::Color & iDiffuseColor, const RED::Object * iDiffuseTexture, const RED::Matrix & iDiffuseUVMatrix, RED::MESH_CHANNEL iDiffuseUVChannel, const RED::LayerSet * iRealtimeLayerSet, const RED::LayerSet * iPhotorealisticLayerSet, RED::Object * iResourceManager, const RED::State & iState ) = 0
virtual RED_RCSetupGenericLambertMaterial ( bool iDoubleSided, const RED::Color & iEmissiveColor, const RED::Object * iEmissiveTexture, const RED::Matrix & iEmissiveUVMatrix, RED::MESH_CHANNEL iEmissiveUVChannel, const RED::Color & iAmbientColor, const RED::Object * iAmbientTexture, const RED::Matrix & iAmbientUVMatrix, RED::MESH_CHANNEL iAmbientUVChannel, const RED::Color & iDiffuseColor, const RED::Object * iDiffuseTexture, const RED::Matrix & iDiffuseUVMatrix, RED::MESH_CHANNEL iDiffuseUVChannel, const RED::Color & iOpacityColor, const RED::Object * iOpacityTexture, const RED::Matrix & iOpacityUVMatrix, RED::MESH_CHANNEL iOpacityUVChannel, float iOpacityGlossiness, const RED::Object * iBumpTexture, const RED::Matrix & iBumpUVMatrix, RED::MESH_CHANNEL iBumpUVChannel, RED::MESH_CHANNEL iBumpTangentsChannel, const RED::LayerSet * iRealtimeLayerSet, const RED::LayerSet * iPhotorealisticLayerSet, RED::Object * iResourceManager, const RED::State & iState ) = 0
virtual RED_RCSetupGenericMaterial ( bool iDoubleSided, bool iFresnel, const RED::Color & iEmissiveColor, const RED::Object * iEmissiveTexture, const RED::Matrix & iEmissiveUVMatrix, RED::MESH_CHANNEL iEmissiveUVChannel, const RED::Color & iAmbientColor, const RED::Object * iAmbientTexture, const RED::Matrix & iAmbientUVMatrix, RED::MESH_CHANNEL iAmbientUVChannel, const RED::Color & iDiffuseColor, const RED::Object * iDiffuseTexture, const RED::Matrix & iDiffuseUVMatrix, RED::MESH_CHANNEL iDiffuseUVChannel, const RED::Color & iSpecularColor, const RED::Object * iSpecularTexture, const RED::Matrix & iSpecularUVMatrix, RED::MESH_CHANNEL iSpecularUVChannel, float iSpecularExp, const RED::Color & iReflectionColor, const RED::Object * iReflectionTexture, const RED::Matrix & iReflectionUVMatrix, RED::MESH_CHANNEL iReflectionUVChannel, float iReflectionGlossiness, bool iAutoEnv, bool iBackgroundEnv, const RED::Object * iEnvironmentalTexture, const RED::Matrix & iEnvironmentalMatrix, float iIOR, const RED::Color & iOpacityColor, const RED::Object * iOpacityTexture, const RED::Matrix & iOpacityUVMatrix, RED::MESH_CHANNEL iOpacityUVChannel, float iOpacityGlossiness, const RED::Object * iBumpTexture, const RED::Matrix & iBumpUVMatrix, RED::MESH_CHANNEL iBumpUVChannel, RED::MESH_CHANNEL iBumpTangentsChannel, const RED::LayerSet * iRealtimeLayerSet, const RED::LayerSet * iPhotorealisticLayerSet, RED::Object * iResourceManager, const RED::State & iState ) = 0
virtual RED_RCSetupGenericPhongMaterial ( bool iDoubleSided, const RED::Color & iEmissiveColor, const RED::Object * iEmissiveTexture, const RED::Matrix & iEmissiveUVMatrix, RED::MESH_CHANNEL iEmissiveUVChannel, const RED::Color & iAmbientColor, const RED::Object * iAmbientTexture, const RED::Matrix & iAmbientUVMatrix, RED::MESH_CHANNEL iAmbientUVChannel, const RED::Color & iDiffuseColor, const RED::Object * iDiffuseTexture, const RED::Matrix & iDiffuseUVMatrix, RED::MESH_CHANNEL iDiffuseUVChannel, const RED::Color & iSpecularColor, const RED::Object * iSpecularTexture, const RED::Matrix & iSpecularUVMatrix, RED::MESH_CHANNEL iSpecularUVChannel, float iSpecularExp, const RED::Color & iOpacityColor, const RED::Object * iOpacityTexture, const RED::Matrix & iOpacityUVMatrix, RED::MESH_CHANNEL iOpacityUVChannel, float iOpacityGlossiness, const RED::Object * iBumpTexture, const RED::Matrix & iBumpUVMatrix, RED::MESH_CHANNEL iBumpUVChannel, RED::MESH_CHANNEL iBumpTangentsChannel, const RED::LayerSet * iRealtimeLayerSet, const RED::LayerSet * iPhotorealisticLayerSet, RED::Object * iResourceManager, const RED::State & iState ) = 0
virtual RED_RCSetupRealisticMaterial ( bool iDoubleSided, bool iFresnel, const RED::Color & iDiffuseColor, const RED::Object * iDiffuseTexture, const RED::Matrix & iDiffuseUVMatrix, RED::MESH_CHANNEL iDiffuseUVChannel, const RED::Color & iReflectionColor, const RED::Object * iReflectionTexture, const RED::Matrix & iReflectionUVMatrix, RED::MESH_CHANNEL iReflectionUVChannel, const RED::Color & iReflectionFogColor, float iReflectionFogDistance, bool iAutoEnv, bool iBackgroundEnv, const RED::Object * iEnvironmentalTexture, const RED::Matrix & iEnvironmentalMatrix, const RED::Color & iTransmissionColor, const RED::Object * iTransmissionTexture, const RED::Matrix & iTransmissionUVMatrix, RED::MESH_CHANNEL iTransmissionUVChannel, float iTransmissionGlossiness, const RED::Object * iTransmissionGlossinessTexture, const RED::Matrix & iTransmissionGlossinessUVMatrix, RED::MESH_CHANNEL iTransmissionGlossinessUVChannel, float iIOR, const RED::Color & iTransmissionScatteringColor, float iTransmissionScatteringScale, bool iCausticsReflective, bool iCausticsRefractive, const RED::Color & iAnisotropy, const RED::Object * iAnisotropyTexture, const RED::Matrix & iAnisotropyMatrix, RED::MESH_CHANNEL iAnisotropyUV, float iAnisotropyRotation, const RED::Object * iAnisotropyRotationTexture, const RED::Matrix & iAnisotropyRotationUVMatrix, RED::MESH_CHANNEL iAnisotropyRotationUVChannel, const RED::Object * iBumpTexture, const RED::Matrix & iBumpUVMatrix, RED::MESH_CHANNEL iBumpUVChannel, RED::MESH_CHANNEL iBumpTangentsChannel, float iDisplacementHeight, float iDisplacementOffset, const RED::Object * iDisplacementTexture, const RED::Matrix & iDisplacementUVMatrix, RED::MESH_CHANNEL iDisplacementUVChannel, const RED::LayerSet * iRealtimeLayerSet, const RED::LayerSet * iPhotorealisticLayerSet, RED::Object * iResourceManager, const RED::State & iState ) = 0
virtual RED_RCUpdateCuttingPlaneEquation ( const float iPlaneEquation[4], const RED::LayerSet & iLayerSet, const RED::State & iState ) = 0
virtual RED_RCUpdateLogoMaskMatrix ( const RED::Vector< RED::Matrix > & iLogoMaskMatrix, const RED::LayerSet & iLayerSet, const RED::State & iState ) = 0

Public static functions:

static RED::CIDGetClassID ( )

Detailed description:

This interface gives access to the material's properties.

This class stores all graphical parameters that define the way a shape is rendered on screen. A shape defines its material using a call to RED::IShape::SetMaterial. Therefore, materials may be shared by many shapes, and are not destroyed by shapes that are deleted.

A material is created through the RED::IResourceManager::CreateMaterial method and is destroyed using RED::IResourceManager::DeleteMaterial.

The material acts as a specification of the way to show up data on screen. It's composed of different shaders that describe the way the data structures are to be used to generate the final lighting of the shape that is using the material. Shaders are RED::Shader objects combined in rendering sequences.

A material is basically understood by the rendering of the three rendering sequences that compose it:

A "sequence" of lighting is the execution of a list of RED::Shader objects. Shaders describe all operations to undertake for the rendering: they specify the shader programs, lighting model, render state and engine configuration (RED::RenderShader, RED::StateShader).

Every lighting sequence has its own properties:

The Red engine rendering pipeline renders the scene per material. From that, the IMaterial interface offers a way to render materials in a pre- defined order, using the RED::IMaterial::SetPriority call.

Performance wise, the material is a key piece in the REDsdk rendering pipeline. As explained in the Hardware display performances chapter, the rendering occurs on a per material basis to reduce the overhead of changing the graphic card state.

Several performance controls are available at the material level:

As many RED objects, the material is a "state sensitive" class, that enforces the constraints of the state management API defining transactions. To get a full understanding on state management, refer to the product documentation, or to the RED::IResourceManager interface description.

Functions documentation

public virtual RED_RC RED::IMaterial::AddBatchArrays(RED::Vector< void * > &iData,
RED::Vector< RED::MESH_CHANNEL > &iChannel,
RED::Vector< int > &iVertexSize,
RED::Vector< RED::MESH_FORMAT > &iFormat,
intiVerticesCount,
const RED::State &iState
) = 0

Defines a group of shared array as a uniquely instanced batch array.

This method sets one list of data arrays as having to be uniquely instanced on the GPU.

An array is shared by RED::IMeshShape::SetSharedArray (please note that similar methods exists for the RED::ILineShape and RED::IPointShape interfaces).

A shared array points onto a user controlled memory region. This is generally used to avoid a memory duplication of the shared data on the CPU side between the host application and REDsdk.

However, shared arrays are by default copied on the GPU and can be uloaded several times in the GPU memory due to the fact that geometries are batched together (several geometries are gathered, and their data are assembled into larger datasets independently of their sharing status) or due to the fact that the same geometry is visualized under different rendering conditions using different materials.

This method defines addresses that will be loaded as unique instances on the GPU: the arrays set by iData will be uploaded once on the GPU, and geometries (meshes, lines or points) will be pointing to these arrays only if all their valid data arrays are shared and indicated to this method.

Note that this mechanism differs from the instancing of shapes. Instanced shapes have their data uploaded once in the context of the material that render them. Here we're referring to shapes that share all their geometrical sources whatever their rendering context is.

Please also note that this API can be used from any valid material. Data arrays or indices arrays are shared globally for all materials in the cluster. Sharing an array twice will cause a RED_SCG_MULTIPLE_BATCH_SHARING_ERROR during the rendering in RED::IWindow::FrameDrawing.

Batching arrays is often used in conjunction with RED::IMaterial::SetBatchMode to disable primitive clustering on the GPU.

A few usage examples:

  • Different edge shapes based on the same vertex arrays as one mesh: the edge vertex array can be shared and loaded once for all edge shapes that are pointing into it.
  • Mesh level of details based on a unique set of geometrical arrays, with different shapes that redefine the level of tessellation to be displayed, without having to switch GPU memory.
  • Heavy geometries that have to be rendered using different materials and that have their data arrays shared across several materials.

Batched arrays are not saved in .red files. Saved geometries (meshes, lines and points) do save all their geometrical channels when written into .red files.

Parameters:

iData:The list of addresses of the arrays to batch. The first address in iData will be used as the lookup address for all other methods in the API. No addresses in iData can be NULL.
iChannel:Source channels for each array to batch.
iVertexSize:Number of components for each vertex in each array.
iFormat:Format of each vertex in each array.
iVerticesCount:Number of vertices for each array. All arrays must have the same number of vertices as defined in a RED::IMeshShape (same for lines and points).
iState:Current transaction.

Returns:

RED_OK if the method has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_ALLOC_FAILURE if a memory allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::AddBatchIndices(int *iIndex,
intiCount,
intiPrimitiveSize,
const RED::State &iState
) = 0

Defines a shared index array as a uniquely instanced batch array.

This the array batching method, dedicated to primitive index arrays that may have been shared using RED::IMeshShape::SetSharedTriangles.

See RED::IMaterial::AddBatchArrays for general details on this batching mechanism.

Parameters:

iIndex:The address of the array. This address will be used as lookup address for all the access methods in the API.
iCount:Number of primitives in the array.
iPrimitiveSize:Size of the primitive (triangle = 3, segments = 2, strips = 1, points = 1).
iState:Current transaction.

Returns:

RED_OK if the method has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_ALLOC_FAILURE if a memory allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::AddBatchSubArrayUpdate(void *iData,
intiNumVertexStart,
intiVerticesCount,
const RED::State &iState
) = 0

Declares a batch array or index array partial update.

Unlike the RED::IMaterial::SetBatchArrayUpdate method that declares a batch array as needing a global update, this method can be used to do partial memory updates in shared arrays. This can be used to reduce GPU upload bandwidth in highly dynamic data environments.

Batches sub array update orders are valid only for one transaction. They are discarded once the transaction is rendered.

The memory is updated for all arrays identified by iData, between iNumVertexStart and iNumVertexStart plus iVerticesCount.

Parameters:

iData:Address of the array (data array or index array).
iNumVertexStart:Starting vertex number of the region to update.
iVerticesCount:Number of vertices to update after iNumVertexStart.
iState:Current transaction.

Returns:

RED_OK if the method has succeeded,
RED_ALLOC_FAILURE if a memory allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::AddShaderToPass(unsigned intiShaderID,
RED::MATERIAL_PASSiPass,
RED::LIST_POSiPosition,
const RED::LayerSet &iLayerSet,
const RED::State &iState
) = 0

Adds a shader to a rendering pass for a layer configuration.

This method adds the shader identified by iShaderID in the rendering pass iPass, for the iLayerSet layer configuration.

The shader must have been previously successfully registered to the material using RED::IMaterial::RegisterShader before calling that method.

See also Cartoon shading.

Parameters:

iShaderID:Identifier of the shader.
iPass:The rendering passes receiving the shader.
iPosition:List insertion position.
iLayerSet:The targeted layer configuration.
iState:Current transaction parameter.

Returns:

RED_OK when the operation succeeded,
RED_WORKFLOW_ERROR if a transaction error was found,
RED_ALLOC_FAILURE if an internal allocation did fail,
RED_FAIL if the shader was not registered.
public virtual RED_RC RED::IMaterial::ClearShaderPass(RED::MATERIAL_PASSiPass,
const RED::LayerSet &iLayerSet,
const RED::State &iState
) = 0

Removes all shaders from a rendering pass in a layer configuration.

This method is similar to RED::IMaterial::RemoveShaderFromPass, but is applied to all shaders in the pass.

Parameters:

iPass:The rendering pass targeted.
iLayerSet:The targeted layer configuration.
iState:Current transaction parameter.

Returns:

RED_OK when the operation succeeded,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_ALLOC_FAILURE if an internal allocation did fail,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::ClearShaders(const RED::State &iState) = 0

Deletes all shaders in the material.

All shaders are cleared from all configurations and rendering passes.

See also Improving CAD graphics.

Parameters:

iState:Current transaction parameter.

Returns:

RED_OK when all the shaders could be removed,
RED_WORKFLOW_ERROR if a transaction error was found,
RED_ALLOC_FAILURE if an internal allocation did fail,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::CopyFrom(const RED::Object &iMaterial,
const RED::State &iState,
intiSrcStateNumber = -1
) = 0

Copies the content of a RED::IMaterial instance to the current object.

Shaders of the destination material will be first cleared. Textures will be shared between both input and output materials.

This method does not copy the input material controller (if any). If you want this to have the same controller than iMaterial, duplicate it using the RED::IMaterialController::CopyFrom method. To create a new material controller use the RED::Factory::CreateMaterialController method.

Parameters:

iMaterial:Reference to the material to copy from.
iState:Current transaction.
iSrcStateNumber:State from which the source material must be copied.

Returns:

RED_OK on success,
RED_BAD_PARAM if iMaterial and this are from different classes, or if iSrcStateNumber is invalid,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL for any other error.
public virtual RED_RC RED::IMaterial::CopyFrom(const RED::Object &iMaterial,
const RED::LayerSet &iLayerSetSrc,
const RED::LayerSet &iLayerSetDest,
const RED::State &iState,
booliImageCopy = false,
booliTinyImageCopy = false
) = 0

Copies the content of a RED::IMaterial instance to the current object regarding to the source and destination layer sets.

Shaders of the destination material in the destination layer set will be first cleared. Textures will be shared between both input and output materials.

Only the shaders from the input material in the given iLayerSetSrc are copied. Every copied shader is inserted in the destination material in the iLayerDest layer set.

This method does not copy the input material controller (if any). If you want this to have the same controller than iMaterial, duplicate it using the RED::IMaterialController::CopyFrom method. To create a new material controller use the RED::Factory::CreateMaterialController method.

Depending on the value of iImageCopy and iTinyImageCopy, all images that are pointed to by the copied shaders can either be copies of all images in iSource or can be shared images.

Note that if an image is shared by several parameters in the iMaterial copied shaders, the copy of that image will be shared by the same set of copied parameters if iImageCopy ( or iTinyImageCopy depending on the image size ) is true. If iImageCopy ( or iTinyImageCopy ) is false, then the same image address will be shared by both sets of shader parameters in iMaterial and in this.

iImageCopy refers to images whose pixel size is above 1 in at least one dimension, iTinyImageCopy refers to images whose pixel size is exactly 1 in all dimensions. Tiny images are often used in textured shader constructions, where if a shader uses at least one texture, all its parameters are set to textures.

Note that all local storages of all images that are cloned are overriden during the operation. Therefore, any data stored in any duplicated image storage will be lost.

Parameters:

iMaterial:Reference to the material to copy from.
iLayerSetSrc:Source layer set from which shaders are copied.
iLayerSetDest:Destination layer set to which shaders are copied.
iState:Current transaction.
iImageCopy:If true, we do copy all images whose pixel size is greater than 1x1 in iSource and set these copies to be used by oMaterial. If false, all images in iSource are also pointed to by oMaterial.
iTinyImageCopy:If true, we do copy all images whose pixel size is exactly 1x1 in iSource and set these copies to be used by oMaterial. If false, all tiny images in iSource are also pointed to by oMaterial.

Returns:

RED_OK on success,
RED_BAD_PARAM if iMaterial and this are from different classes, or if iSrcStateNumber is invalid,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL for any other error.
public virtual RED_RC RED::IMaterial::DeleteShader(unsigned intiShaderID,
const RED::State &iState
) = 0

Removes a shader from the material.

The shader identified by its iID is removed from the material. It's removed from all shader configurations and passes, and destroyed.

Parameters:

iShaderID:Identifier of the shader.
iState:Current transaction parameter.

Returns:

RED_OK when the shader could be removed,
RED_WORKFLOW_ERROR if a transaction error was found,
RED_ALLOC_FAILURE if an internal allocation did fail,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::GetBatchArrays(RED::Vector< RED::Vector< void * > > &oData,
RED::Vector< RED::Vector< RED::MESH_CHANNEL > > &oChannel,
RED::Vector< RED::Vector< int > > &oVertexSize,
RED::Vector< RED::Vector< RED::MESH_FORMAT > > &oFormat,
RED::Vector< int > &oVerticesCount,
intiStateNumber = -1
)const = 0

Returns all lists of batched arrays stored in the material.

Parameters:

oData:The list of addresses of the arrays batched.
oChannel:Source channels for each array to batch.
oVertexSize:Number of components for each vertex in each array.
oFormat:Format of each vertex in each array.
oVerticesCount:Number of vertices for each array.
iStateNumber:Queried transaction number.

Returns:

RED_OK if the operation has succeeded.
RED_BAD_PARAM if the method has received an invalid parameter,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::GetBatchArraysCount(int &oCount,
intiStateNumber = -1
)const = 0

Returns the number of batched arrays we have in the material.

Parameters:

oCount:The number of batched arrays.
iStateNumber:Queried transaction number.

Returns:

RED_OK if the operation has succeeded.
RED_BAD_PARAM if the method has received an invalid parameter,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::GetBatchIndices(RED::Vector< int * > &oIndex,
RED::Vector< int > &oCount,
RED::Vector< int > &oPrimitiveSize,
intiStateNumber = -1
)const = 0

Returns all lists of batched index arrays stored in this material.

Parameters:

oIndex:The address of the array.
oCount:Number of primitives in the array.
oPrimitiveSize:Size of the primitive (triangle = 3, segments = 2, strips = 1, points = 1).
iStateNumber:Queried transaction number.

Returns:

RED_OK if the operation has succeeded.
RED_BAD_PARAM if the method has received an invalid parameter,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::GetBatchIndicesCount(int &oCount,
intiStateNumber = -1
)const = 0

Returns the number of batched indices arrays we have in the material.

Parameters:

oCount:The number of batched indices arrays.
iStateNumber:Queried transaction number.

Returns:

RED_OK if the operation has succeeded.
RED_BAD_PARAM if the method has received an invalid parameter,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::GetBatchMode(bool &oBatchMode,
intiStateNumber = -1
)const = 0

Returns the batching status for this material.

See also Hidden lines removal: A real-time example.

Parameters:

oBatchMode:The batch mode for our material.
iStateNumber:The queried transaction number.

Returns:

RED_OK if the operation has succeeded.
RED_BAD_PARAM if the method has received an invalid parameter,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::GetCaustics(bool &oReflectiveCaustics,
bool &oRefractiveCaustics,
const RED::LayerSet &iLayerSet,
intiStateNumber = -1
)const = 0

Query the caustics status for this material.

This method parses the material for RED::StateShader objects. If any state shader found has caustics enabled, this will set the corresponding method parameter flag to true.

Note that the query occurs for a given layerset configuration. The call has to be repeated if different layerset configurations have to be searched for.

Please also note that the query occurs for the RED::HW_GENERIC hardware platform.

Parameters:

oReflectiveCaustics:Do we have reflective caustics enabled for this material?
oRefractiveCaustics:Do we have refractive caustics enabled for this material?
iLayerSet:The layerset for which we do the setup.
iStateNumber:Queried transaction number.

Returns:

RED_OK on success,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::GetDisplacement(float &oDispHeight,
RED::Object *&oDispTexture,
RED::Matrix &oDispMatrix,
RED::MESH_CHANNEL &oDispUV,
float &oDispOffset,
const RED::LayerSet &iLayerSet,
intiStateNumber = -1
)const = 0

Query the displacement status for this material.

This method parses the material for RED::StateShader objects. If any state shader found has displacement enabled, this will set the corresponding method parameter flag to true.

Note that the query occurs for a given layerset configuration. The call has to be repeated if different layerset configurations have to be searched for.

Please also note that the query occurs for the RED::HW_GENERIC hardware platform.

See Adding displacement mapping to a material for further details.

Parameters:

oDispHeight:Displacement height. See RED::StateShader::SetDisplacement for details.
oDispTexture:Displacement image. See RED::StateShader::SetDisplacement for details.
oDispMatrix:Displacement texture matrix. See RED::StateShader::SetDisplacement for details.
oDispUV:Displacement texture UV channel. See RED::StateShader::SetDisplacement for details.
oDispOffset:Displacement offset. See RED::StateShader::SetDisplacement for details.
iLayerSet:The layerset for which we do the setup.
iStateNumber:Transaction number searched for.

Returns:

RED_OK on success,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::GetImageList(RED::Map< RED::Object *, int > &oImageList,
intiStateNumber = -1
)const = 0

Retrieve the list of images used by the material.

This method parses all shaders registered in the material and builds a list of all images that are used by at least one of them. Note that composite images used by material shaders are also parsed for images they could use too.

Parameters:

oImageList:The list of images used by the material. All images addresses are stored as the map keys in the returned map.
iStateNumber:The transaction number.

Returns:

RED_OK if the operation has succeeded.
RED_BAD_PARAM if a the method has received an invalid parameter,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::GetImmediateMode(bool &oOnOff,
intiNumState = -1
)const = 0

Returns the rendering mode for all geometries using this material.

Refer to RED::IMaterial::SetImmediateMode for all details on the rendering mode setup: VBO or immediate mode.
Note that the RED::OPTIONS_IMMEDIATE_MODE option value can override the setup made at the material level.

Parameters:

oOnOff:true if immediate mode is enabled, false if disabled.
iNumState:Queried transaction number.

Returns:

RED_OK if the operation has succeeded.
RED_BAD_PARAM if the method has received an invalid parameter,
RED_FAIL otherwise.
public virtual const RED::LayerSet & RED::IMaterial::GetLayerSet(intiLayerSet,
intiStateNumber = -1
)const = 0

Gets to the i-th RED::LayerSet of the material.

This method returns the RED::LayerSet that defines the i-th shader configuration in our material. Layer sets in this list result of shader addition for distinct RED::LayerSet.

Parameters:

iLayerSet:Index of the layer set in our material list.
iStateNumber:Queried state.
public virtual RED_RC RED::IMaterial::GetPolygonOffset(float &oPolyOffsetFactor,
float &oPolyOffsetUnits,
const RED::LayerSet &iLayerSet,
intiStateNumber = -1
)const = 0

Query the polygon offset parameters for this material.

This method parses the material for RED::StateShader objects. The first state shader found in the rendering passes is asked for its polygon offset parameters and these are returned to the caller. Therefore, the method assumes that all shaders are having the same polygon offset setup. This is the case if the setup was made using RED::IMaterial::SetPolygonOffset, but this don't account for hand made shader configurations that can differ.

Note that the query occurs for a given layerset configuration. The call has to be repeated if different layerset configurations have to be searched for.

Please also note that the query occurs for the RED::HW_GENERIC hardware platform.

See also Applying polygon offset to see edges of a geometry.

Parameters:

oPolyOffsetFactor:Polygon offset factor.
oPolyOffsetUnits:Polygon offset units.
iLayerSet:The layerset for which we do the setup.
iStateNumber:Transaction number searched for.

Returns:

RED_OK on success,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::GetPriority(int &oPriority,
intiStateNumber = -1
)const = 0

Gets the rendering priority of a material.

See RED::IMaterial::SetPriority.

See also Applying polygon offset to see edges of a geometry.

Parameters:

oPriority:The rendering priority of the material.
iStateNumber:Queried transaction number.
iStateNumber:Queried transaction number.

Returns:

RED_OK if the operation has succeeded.
RED_BAD_PARAM if the method has received an invalid parameter,
RED_FAIL otherwise.
public virtual const RED::Shader * RED::IMaterial::GetShader(unsigned intiShaderID,
RED::MATERIAL_PASSiPass,
const RED::LayerSet &iLayerSet,
intiNumState = -1
)const = 0

Gets a shader in read only mode.

Looks for the shader identified by iID, for a read only access.

See also Writing a custom rendering shader using geometry program.

Parameters:

iShaderID:ID of the shader.
iPass:Pass where to look for the requested shader.
iLayerSet:Layer set of the shader.
iNumState:Queried state number.

Returns:

The requested shader address when found, NULL otherwise.
public virtual RED_RC RED::IMaterial::GetShader(unsigned intiShaderID,
RED::MATERIAL_PASSiPass,
RED::Shader *&oShader,
const RED::LayerSet &iLayerSet,
const RED::State &iState
) = 0

Gets a shader in read-write mode.

Looks for the shader identified by iID, for a write access.

See also Writing a custom rendering shader using geometry program.

Parameters:

iShaderID:ID of the shader.
iPass:Pass where to look for the requested shader.
oShader:Pointer to the address of the result if any was found.
iLayerSet:Layer set of the shader.
iState:The current transaction parameter.

Returns:

RED_OK if the operation has succeeded - whatever the result,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::GetShaderList(RED::Vector< const RED::Shader * > &oShaders,
intiNumState = -1
)const = 0

Gets all the shaders in read-only mode.

See also Improving CAD graphics.

Parameters:

oShaders:Reference to the list of the returned shaders.
iNumState:Queried transaction number.

Returns:

RED_OK when the operation succeeded.
RED_BAD_PARAM if a NULL address is provided,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::GetShaderList(RED::Vector< RED::Shader * > &oShaders,
const RED::State &iState
) = 0

Gets all the shaders in read-write mode.

See also Improving CAD graphics.

Parameters:

oShaders:Reference to the list of the returned shaders.
iState:The current transaction.

Returns:

RED_OK when the operation succeeded.
RED_BAD_PARAM if a NULL address is provided,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::GetShaders(RED::Vector< RED::Shader * > &oShaders,
RED::MATERIAL_PASSiPass,
const RED::LayerSet &iLayerSet,
const RED::State &iState
) = 0

Gets all the shaders in a layer in read-write mode.

See also Volume view.

Parameters:

oShaders:Reference to the vector containing the returned shaders.
iPass:Pass where to look for the requested shaders.
iLayerSet:Layers set for which we want to retrieve the material's layers.
iState:The current transaction parameter.

Returns:

RED_OK when the operation succeeded.
RED_BAD_PARAM if a NULL address is provided,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::GetShaders(RED::Vector< RED::Shader * > &oShaders,
RED::MATERIAL_PASSiPass,
const RED::LayerSet &iLayerSet,
intiNumState = -1
)const = 0

Gets all the shaders in a layer in read-only mode.

See also Volume view.

Parameters:

oShaders:Reference to the vector containing the returned shaders.
iPass:Pass where to look for the requested shaders.
iLayerSet:Layers set for which we want to retrieve the material's layers.
iNumState:The queried state number.

Returns:

RED_OK when the operation succeeded.
RED_BAD_PARAM if a NULL address is provided,
RED_FAIL otherwise.

Gets the lists of channels used by a material for each of its supported layers set configuration.

Channels are treated independently of the shaders platform. It means you'll get a list of channels used per layers set whatever the platform you're running on is.

Parameters:

ioChannels:reference to a map to be filled with the channels lists.
iNumState:Queried transaction number (default is -1 for current state).

Returns:

RED_OK on success,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::InsertShadersFrom(const RED::Object &iMaterial,
const RED::LayerSet &iLayerSet,
const RED::State &iState
) = 0

Inserts the shaders from an input material.

This method will insert the shaders from the input material into this using the supplied layer set. This enables the creation of a single material with different shaders configuration by layer set.

Example:

suppose we are in the following configuration

Material Shaders (ID) Layer set
this shader_01 ls_01
iMaterial shader_02
shader_03
ls_03
ls_04

After calling the method with layer set ls_02, the configuration will be

Material Shaders (ID) Layer set
this shader_01
shader_02
shader_03
ls_01
ls_02
ls_02
iMaterial shader_02
shader_03
ls_03
ls_04

If shaders are already defined for the iLayerSet layer set inside this, new shaders will be inserted after existing ones in the list.

Example:

suppose we are in the following configuration

Material Shaders (ID) Layer set
this shader_01 ls_01
iMaterial shader_02
shader_03
ls_02
ls_03

After calling the method with layer set ls_01, the configuration will be

Material Shaders (ID) Layer set
this shader_01
shader_02
shader_03
ls_01
ls_01
ls_01
iMaterial shader_02
shader_03
ls_02
ls_03

If an incoming shader as the same ID than a one already in the destination material, it will not be inserted and the method will return with a RED_WORKFLOW_ERROR.

Example:

suppose we are in the following configuration

Material Shaders (ID) Layer set
this shader_01 ls_01
iMaterial shader_01
shader_02
ls_03
ls_04

The input material and this have both a shader with ID "shader_01"; the method fails.

This method has no effect on the input material controller (if any). To merge two material controllers together, use the RED::IMaterialController::Merge method.

Parameters:

iMaterial:reference to the material to read the shaders from.
iLayerSet:layer set to used when inserting the shaders.
iState:current transaction.

Returns:

RED_OK on success,
RED_BAD_PARAM if iMaterial and this are from different classes,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL for any other error.
public virtual RED_RC RED::IMaterial::IsBatchArrayUpdate(bool &oUpdate,
void *iRefData,
void *iData,
intiStateNumber = -1
)const = 0

Do we have an update declared for this batch?

This method can be used for both the data arrays or for indices arrays.

Parameters:

oUpdate:Returned set to true if iData is declared as needing an update.
iRefData:Reference address used for the lookup of the batched arrays. This address is the first address provided to RED::IMaterial::AddBatchArrays.
iData:Address of the array to query (data array or index array).
iStateNumber:Queried transaction number.

Returns:

RED_OK if the operation has succeeded.
RED_BAD_PARAM if the method has received an invalid parameter,
RED_FAIL otherwise.
public virtual bool RED::IMaterial::IsRegistered(unsigned intiID,
intiStateNumber = -1
)const = 0

Do we have a shader registered with the specified ID?

We prevent two shaders with the same ID to be registered in the material to avoid mistakes during the assignation of shaders to rendering passes. This method can be used to figure out whether a given shader has been already registered in the material or not.

Parameters:

iID:Shader Id to check.
iStateNumber:Queried transaction number.

Returns:

true if the shader is already registered, false otherwise.
public virtual int RED::IMaterial::LayerSetsCount(intiStateNumber = -1) const = 0

Gets the number of different RED::LayerSet for which we have a definition.

This method returns the number of distinct layer sets for which we have stored a material definition.

Parameters:

iStateNumber:Queried state number.

Returns:

The number of distinct layer sets we have in the material.
public virtual RED_RC RED::IMaterial::RegisterShader(const RED::Shader &iShader,
const RED::State &iState
) = 0

Adds a shader to the material.

Register iShader in the material list. iShader is duplicated in the material internal shader list. iShader can be then accessed through its RED::Object::GetID() in all the material's methods.
Note that a shader must be added to a rendering pass for a given layer configuration to be usable during the rendering.
Note that it's not possible to register two shaders with the same identifier within a material: this could cause later errors during the assignation of shaders to rendering passes.

See also Cartoon shading.

Parameters:

iShader:Shader to insert in the material.
iState:Current transaction parameter.

Returns:

RED_OK when the shader could be inserted,
RED_WORKFLOW_ERROR if the material already knows a shader that has the same identifier as iShader,
RED_WORKFLOW_ERROR if a transaction error was found,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::RemoveBatchArray(void *iData,
const RED::State &iState
) = 0

Removes arrays from our batching list.

The array should have been added by RED::IMaterial::AddBatchArrays or by RED::IMaterial::AddBatchIndices. The shared arrays list to which iData belongs is removed. The method does nothing if the array is not found.

Parameters:

iData:Address of the array.
iState:Current transaction.

Returns:

RED_OK if the method has succeeded,
RED_ALLOC_FAILURE if a memory allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::RemoveShaderFromPass(unsigned intiShaderID,
RED::MATERIAL_PASSiPass,
const RED::LayerSet &iLayerSet,
const RED::State &iState
) = 0

Removes a shader from a rendering pass in a layer configuration.

This method removes the shader identified by iShaderID from the rendering pass iPass in the layer configuration identified by iLayerSet.

Note that the shader is not destroyed, and can be reused in another rendering pass. To destroy the shader use RED::IMaterial::DeleteShader.

See also Writing a custom rendering shader in ARB.

Parameters:

iShaderID:Identifier of the shader.
iPass:The rendering pass targeted.
iLayerSet:The targeted layer configuration.
iState:Current transaction parameter.

Returns:

RED_OK when the operation succeeded,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_ALLOC_FAILURE if an internal allocation did fail,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::SetBatchArrayUpdate(void *iRefData,
void *iData,
const RED::State &iState
) = 0

Declares a batch array or index array contents as being updated.

This method indicates to the engine that the contents of the specified batched array needs to be updated for the next closed transaction. This method can be used for both data arrays or for indices arrays.

Parameters:

iRefData:Reference address used for the lookup of the batched arrays. This address is the first address provided to RED::IMaterial::AddBatchArrays.
iData:Address of the array to update (data array or index array).
iState:Current transaction.

Returns:

RED_OK if the method has succeeded,
RED_ALLOC_FAILURE if a memory allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::SetBatchMode(booliBatchMode,
const RED::State &iState
) = 0

Enables of disables primitive batching for all shapes rendered using this material.

This method enables or disables the internal engine primitive batching system that gathers all shapes rendered using that material. By default, the batching of primitives is enabled. All shapes geometries are grouped together to form larger memory blocks used to speed up the rendering of the scene.

Geometries are grouped together by the engine to assemble larger primitives made of up to 65536 vertices. Geometries that have more than 65536 vertices are not merged with any other primitive.

Disabling primitive batching may be useful for the rendering of datasets that are heavily using shared geometry arrays set by RED::IMeshShape::SetSharedArray or RED::IMeshShape::SetSharedTriangles, or for the rendering of primitives that constantly change in number of triangles, lines or points.

See also Hidden lines removal: A real-time example.

Parameters:

iBatchMode:Set to false to disable primitive batching for this material, or to true to enable it.
iState:The current transaction.

Returns:

RED_OK if the operation has succeeded,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::SetCaustics(booliReflectiveCaustics,
booliRefractiveCaustics,
const RED::LayerSet &iLayerSet,
const RED::State &iState
) = 0

Setup caustics for this material.

This helper method can be used to turn on or off caustics on this material. It parses all RED::StateShader instances found in the RED::MTL_PRELIT, RED::MTL_LIT and RED::MTL_POSTLIT rendering passes and setups caustics according to this method's parameters. The method may insert a RED::StateShader at the beginning of the first pass to setup caustics if no state shader is found in the material for the specified 'iLayerSet' configuration.

Note that the operation occurs for a given layerset configuration. The call has to be repeated if different layerset configurations have to support caustics.

Please also note that changes are applied to the RED::HW_GENERIC hardware platform.

See Caustics for details on caustics setup for photo-realistic rendering.

Parameters:

iReflectiveCaustics:Set to true to turn on reflective caustics for the material.
iRefractiveCaustics:Set to true to turn on refractive caustics for the material.
iLayerSet:The layerset for which we do the setup.
iState:The current transaction.

Returns:

RED_OK if the operation has succeeded,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::SetCuttingPlane(const floatiPlaneEquation[4],
const RED::Shader *iSectionCapShader,
const RED::LayerSet &iLayerSet,
booliEdgeMaterial,
const RED::State &iState
) = 0

Applies a section cutting plane to this material.

This method adds a cutting plane to the material that have the effect to slice the geometry according to the supplied plane equation. All rendered fragments on the positive side of any plane are discarded.

The setup of the material is modified: RED::RenderShaderSectionCut shader instances and RED::StateShader instances are inserted into the original flow of shaders that define the material to perform section cutting operations. Existing shaders may be modified too.

Cut materials for meshes are set as single sided if a section cap shader is used, otherwise they remain double sided if their original setup was double sided. Cut materials for meshes preserve polygon offset. Cut materials for edges preserve line thickness and stipple patterns.

Sliced geometries are capped: a iSectionCapShader can be specified to do the closing of cut geometries that would appear with holes otherwise. This extra shader is added in the RED::MTL_POSTLIT pass of the material, at the very end of the shading pipeline. This shader is applied to all geometries as all shaders are and it'll be only drawn on pixel fragments that need to be painted for the geometries to appear properly closed.

Please make sure that the ID of iSectionCapShader is only used by it and that no other shader that are registered in the material are using the same ID. Otherwise, the method will not register iSectionCapShader and will use the one already registered to draw the section cap contents. This can lead to unexpected results if iSectionCapShader's ID is used by some other shader in the material, but it also allow to share the cutting plane shader among different layersets in the material.

Note that the operation occurs for a given layerset configuration. The call has to be repeated if different layersets configurations have to support a section cutting plane.

A cutting plane can be applied to mesh or to edges. To apply the cutting plane to edges, please enable the iEdgeMaterial flag in the method.

The section cutting plane equation is stored by one of these shaders:

Please note that state changes are applied to the RED::HW_GENERIC hardware platform.

There may be conflicting IDs for the RED::RenderShaderSectionCut if the method is called several times for different RED::LayerSet configurations. If a cut shader is already registered and the method has to setup another cut shader, it'll modify the RED::RenderShaderSectionCut default string IDs, appending numbers '_x' after the cut shader string ID, starting at number 1.

See Cutting geometries: a practical example for details on how to use this method.

Parameters:

iPlaneEquation:Cutting plane equation. 4 values must be supplied in the array, in the order A, B, C, D that define each plane equation by A*x + B*y + C*z + D = 0. Coefficients must be in world space coordinates.
iSectionCapShader:Can be any RED::RenderShader. If NULL, cut geometries are not closed. This parameter is not used if iEdgeMaterial is true.
iLayerSet:The layerset for which we do the setup.
iEdgeMaterial:If true, the setup is set specifically for the rendering of edges.
iState:The current transaction.

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_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::SetDisplacement(floatiDispHeight,
const RED::Object *iDispTexture,
const RED::Matrix &iDispMatrix,
RED::MESH_CHANNELiDispUV,
floatiDispOffset,
const RED::LayerSet &iLayerSet,
const RED::State &iState
) = 0

Setup displacement for this material.

This helper method can be used to turn on or off displacement on this material. It parses all RED::StateShader instances found in the RED::MTL_PRELIT, RED::MTL_LIT and RED::MTL_POSTLIT rendering passes and setups displacement according to this method's parameters. The method may insert a RED::StateShader at the beginning of the first pass to setup displacement if no state shader is found in the material for the specified 'iLayerSet' configuration.

Note that the operation occurs for a given layerset configuration. The call has to be repeated if different layerset configurations have to support caustics.

Please also note that changes are applied to the RED::HW_GENERIC hardware platform.

See Adding displacement mapping to a material for further details.

Parameters:

iDispHeight:Displacement height. See RED::StateShader::SetDisplacement for details.
iDispTexture:Displacement image. See RED::StateShader::SetDisplacement for details.
iDispMatrix:Displacement texture matrix. See RED::StateShader::SetDisplacement for details.
iDispUV:Displacement texture UV channel. See RED::StateShader::SetDisplacement for details.
iDispOffset:Displacement offset. See RED::StateShader::SetDisplacement for details.
iLayerSet:The layerset for which we do the setup.
iState:The current transaction.

Returns:

RED_OK if the operation has succeeded,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::SetImmediateMode(booliOnOff,
const RED::State &iState
) = 0

Enables or disables the legacy "immediate mode" rendering protocol.

This method is used to control the way geometrical elements using this material are rendered. The control lets you change whether geometries using this material are uploaded on the GPU or not. This is known in OpenGL wording as the legacy "Immediate mode" which is opposed to the more recent "Vertex Buffer Object (VBO) mode".

Immediate mode renders slowly: every rendered geometry is pushed to the graphic card through the bus every frame. VBO mode renders a lot faster: every rendered geometry is uploaded on the graphic card memory first, and then a simple rendering order is launched to indicate to the card that is has to display the geometry.

Immediate mode is slow but does not consume any video memory.

VBO mode is fast but consumes video memory for the storage of all the primitives using this material.

Both modes produce the exact same picture. This method just changes the memory positioning and balance between memory and performances inside the application.

Note that the RED::OPTIONS_IMMEDIATE_MODE option value can override the setup made at the material level.

Parameters:

iOnOff:Set to true to enable immediate mode rendering for all geometries that are displayed using this material; set to false to use the default VBO rendering mode.
iState:The current transaction.

Returns:

RED_OK if the operation has succeeded,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::SetLogoMask(const RED::Vector< RED::Object * > &iLogoMask,
const RED::Vector< RED::Matrix > &iLogoMaskMatrix,
const RED::Vector< RED::MESH_CHANNEL > &iLogoMaskUV,
booliInvert,
const RED::LayerSet &iLayerSet,
const RED::State &iState
) = 0

Applies logo masking images based on alpha values to this material.

This helper method can be used to automatically apply logo images on an existing material. The setup of the material is modified: new shaders are created, shader ordering in rendering passes is modified and existing state shaders may be modified as well.

The method adds a RED::RenderShaderLogo at the startup of the RED::MTL_PRELIT pass (also to RED::MTL_INDIRECT_PRELIT passes if it has shaders). This shader displays all the logo images supplied to the method. The visibility of the logos over the existing material will be defined by the alpha channels of the supplied logo images in iLogoMask.

Then, for each existing RED::RenderShader in the material, the method adds a RED::StateShader before it (or modifies an existing shader) to change it's blending equation:

  • All source factors of the blending equation are set to RED::StateShader::DST_ALPHA* (or to RED::StateShader::ONE_MINUS_DST_ALPHA) so that the shader effect is modulated by the alpha produced by the logo shader. The logo is visible in areas with alpha > 0, and the material is visible in areas with alpha = 0.
  • If the DST_ALPHA blending factor is chosen (iInvert == false), the render shader after will only be visible inside the logos. If the ONE_MINUS_DST_ALPHA blending factor is chosen (iInvert == true), the render shader after will only be visible outside the logos. The logo masks the source material: in logo areas with alpha > 0, we see the material.

Each modified state shader is also modified to disable all alpha color writes in output as we don't want to affect the initial logo masking pass result of the RED::RenderShaderLogo.

Finally, the method addds a RED::RenderShaderSolid at the end of the RED::MTL_POSTLIT and RED::MTL_INDIRECT_POSTLIT pass to restore plain alpha values.

Note that the operation occurs for a given layerset configuration. The call has to be repeated if different layersets configurations have to support alpha mask.

if iInvert is true, the mask is inverted: DST_ALPHA blending factors are replaced by ONE_MINUS_DST_ALPHA.

There may be conflicting IDs for the RED::RenderShaderLogo if the method is called several times for different RED::LayerSet configurations. If a logo shader is already registered and the method has to setup another logo shader, it'll modify the RED::RenderShaderLogo default string IDs, appending numbers '_x' after the logo string ID, starting at number 1.

Please note that state changes are applied to the RED::HW_GENERIC hardware platform.

See Applying a logo over a material's geometry for a practical example of using this method.

Parameters:

iLogoMask:Logo texture masks. See the RED::RenderShaderLogo for the maximal number of logos that can be displayed. Each logo image must be a valid RED::TGT_TEX_2D image or a composite image.
iLogoMaskUV:Texture mapping channel for each logo mask.
iLogoMaskMatrix:Texture matrix for each logo mask.
iInvert:If set to false, the visible part of the material is defined inside the logo, in logo areas with alpha > 0. If set to true, the opposite rule is used: visible areas of the material are outside of the logo, in logo areas with alpha = 0.
iLayerSet:The layerset for which we do the setup.
iState:The current transaction.

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_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::SetPolygonOffset(floatiPolyOffsetFactor,
floatiPolyOffsetUnits,
const RED::LayerSet &iLayerSet,
const RED::State &iState
) = 0

Setups polygon offset for this material.

This helper method can be used to automatically setup polygon offset parameters for all rendering passes in this material.

It parses the RED::MTL_PRELIT, RED::MTL_LIT and RED::MTL_POSTLIT passes of the material and either inserts a RED::StateShader at the pass startup or modify an existing state shader so that it uses the iPolyOffsetFactor and iPolyOffsetUnits polygon offset values.

Refer to the RED::StateShader class for details on the polygon offset.

Note that the operation occurs for a given layerset configuration. The call has to be repeated if different layerset configurations have to support polygon offset.

Please note that changes are applied to the RED::HW_GENERIC hardware platform.

See Adding edges for a practical example of this method.

Parameters:

iPolyOffsetFactor:Polygon offset factor.
iPolyOffsetUnits:Polygon offset units.
iLayerSet:The layerset for which we do the setup.
iState:The current transaction.

Returns:

RED_OK if the operation has succeeded,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::SetPriority(intiPriority,
const RED::State &iState
) = 0

Defines the rendering priority of a material.

This method is used to assign a rendering priority to a material. Every engine rendering pass is sorted by materials, rendering all objects that are using a given material at a time, before proceeding to the rendering of objects using another material.

It's possible to sort objects that are using a given material by their child number under a transform shape, but this don't give the ability to sort objects that are using different materials, which is the purpose of this method.

Every material has a default priority of -1 (last). Set any positive or zero value to a material will make it rendered before any other material that has a greater priority value for each rendering pass.

If we have two materials with priorities 0 and 1, for which we have shaders in prelit, lit and postlit, then the rendering sequence will be:

  • Priority 0 prelit,
  • Priority 1 prelit,
  • Priority 0 lit,
  • Priority 1 lit,
  • Priority 0 postlit,
  • Priority 1 postlit.

See also Applying polygon offset to see edges of a geometry.

Parameters:

iPriority:New material priority (-1) to make it render last.
iState:The current transaction.

Returns:

RED_OK if the operation has succeeded,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::SetupGenericBumpyDiffuseMaterial(booliDoubleSided,
const RED::Color &iDiffuseColor,
const RED::Object *iDiffuseTexture,
const RED::Matrix &iDiffuseUVMatrix,
RED::MESH_CHANNELiDiffuseUVChannel,
const RED::Object *iBumpTexture,
const RED::Matrix &iBumpUVMatrix,
RED::MESH_CHANNELiBumpUVChannel,
RED::MESH_CHANNELiBumpTangentsChannel,
const RED::LayerSet *iRealtimeLayerSet,
const RED::LayerSet *iPhotorealisticLayerSet,
RED::Object *iResourceManager,
const RED::State &iState
) = 0

Setups a bumpy diffuse material with neither reflection nor refraction.

This is a helper method provided for convenience. The returned material is based on a call to RED::IMaterial::SetupGenericMaterial (see the method documentation for more details).

See also Hello world!.

Parameters:

iDoubleSided:true if the material is double sided, false otherwise.
iDiffuseColor:material diffuse color.
iDiffuseTexture:material diffuse texture.
iDiffuseUVMatrix:material diffuse uv coordinates matrix.
iDiffuseUVChannel:material diffuse uv coordinates channel.
iBumpTexture:material bump texture.
iBumpUVMatrix:material bump uv coordinates matrix.
iBumpUVChannel:material bump uv coordinates channel.
iBumpTangentsChannel:material tangents coordinates channel.
iRealtimeLayerSet:pointer to the layer set to be used to store the real-time configuration. Set it to NULL if you don't want a real-time configuration for the material.
iPhotorealisticLayerSet:pointer to the layer set to be used to store the photorealistic configuration. Set it to NULL if you don't want a photorealistic configuration for the material.
iResourceManager:pointer to the resource manager.
iState:current transaction.

Returns:

RED_OK on success,
RED_BAD_PARAM on an invalid parameter,
RED_ALLOC_FAILURE on a memory allocation error,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::SetupGenericDiffuseMaterial(booliDoubleSided,
const RED::Color &iDiffuseColor,
const RED::Object *iDiffuseTexture,
const RED::Matrix &iDiffuseUVMatrix,
RED::MESH_CHANNELiDiffuseUVChannel,
const RED::LayerSet *iRealtimeLayerSet,
const RED::LayerSet *iPhotorealisticLayerSet,
RED::Object *iResourceManager,
const RED::State &iState
) = 0

Setups a diffuse material with neither reflection, refraction nor bump.

This is a helper method provided for convenience. The returned material is based on a call to RED::IMaterial::SetupGenericMaterial (see the method documentation for more details).

See also Generic material.

Parameters:

iDoubleSided:true if the material is double sided, false otherwise.
iDiffuseColor:material diffuse color.
iDiffuseTexture:material diffuse texture.
iDiffuseUVMatrix:material diffuse uv coordinates matrix.
iDiffuseUVChannel:material diffuse uv coordinates channel.
iRealtimeLayerSet:pointer to the layer set to be used to store the real-time configuration. Set it to NULL if you don't want a real-time configuration for the material.
iPhotorealisticLayerSet:pointer to the layer set to be used to store the photorealistic configuration. Set it to NULL if you don't want a photorealistic configuration for the material.
iResourceManager:pointer to the resource manager.
iState:current transaction.

Returns:

RED_OK on success,
RED_BAD_PARAM on an invalid parameter,
RED_ALLOC_FAILURE on a memory allocation error,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::SetupGenericLambertMaterial(booliDoubleSided,
const RED::Color &iEmissiveColor,
const RED::Object *iEmissiveTexture,
const RED::Matrix &iEmissiveUVMatrix,
RED::MESH_CHANNELiEmissiveUVChannel,
const RED::Color &iAmbientColor,
const RED::Object *iAmbientTexture,
const RED::Matrix &iAmbientUVMatrix,
RED::MESH_CHANNELiAmbientUVChannel,
const RED::Color &iDiffuseColor,
const RED::Object *iDiffuseTexture,
const RED::Matrix &iDiffuseUVMatrix,
RED::MESH_CHANNELiDiffuseUVChannel,
const RED::Color &iOpacityColor,
const RED::Object *iOpacityTexture,
const RED::Matrix &iOpacityUVMatrix,
RED::MESH_CHANNELiOpacityUVChannel,
floatiOpacityGlossiness,
const RED::Object *iBumpTexture,
const RED::Matrix &iBumpUVMatrix,
RED::MESH_CHANNELiBumpUVChannel,
RED::MESH_CHANNELiBumpTangentsChannel,
const RED::LayerSet *iRealtimeLayerSet,
const RED::LayerSet *iPhotorealisticLayerSet,
RED::Object *iResourceManager,
const RED::State &iState
) = 0

Setups a Lambert material with emissive, ambient, diffuse, transparency and bump.

This is a helper method provided for convenience. The returned material is based on a call to RED::IMaterial::SetupGenericMaterial (see the method documentation for more details).

See also Generic material.

Parameters:

iDoubleSided:true if the material is double sided, false otherwise.
iEmissiveColor:material emissive color.
iEmissiveTexture:material emissive texture.
iEmissiveUVMatrix:material emissive uv coordinates matrix.
iEmissiveUVChannel:material emissive uv coordinates channel.
iAmbientColor:material ambient color.
iAmbientTexture:material ambient texture.
iAmbientUVMatrix:material ambient uv coordinates matrix.
iAmbientUVChannel:material ambient uv coordinates channel.
iDiffuseColor:material diffuse color.
iDiffuseTexture:material diffuse texture.
iDiffuseUVMatrix:material diffuse uv coordinates matrix.
iDiffuseUVChannel:material diffuse uv coordinates channel.
iOpacityColor:material opacity color.
iOpacityTexture:material opacity texture.
iOpacityUVMatrix:material opacity uv coordinates matrix.
iOpacityUVChannel:material opacity uv coordinates channel.
iOpacityGlossiness:material opacity glossiness (in [0 (not glossy), 1 (fully glossy)]).
iBumpTexture:material bump texture.
iBumpUVMatrix:material bump uv coordinates matrix.
iBumpUVChannel:material bump uv coordinates channel.
iBumpTangentsChannel:material tangents coordinates channel.
iRealtimeLayerSet:pointer to the layer set to be used to store the real-time configuration. Set it to NULL if you don't want a real-time configuration for the material.
iPhotorealisticLayerSet:pointer to the layer set to be used to store the photorealistic configuration. Set it to NULL if you don't want a photorealistic configuration for the material.
iResourceManager:pointer to the resource manager.
iState:current transaction.

Returns:

RED_OK on success,
RED_BAD_PARAM on an invalid parameter,
RED_ALLOC_FAILURE on a memory allocation error,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::SetupGenericMaterial(booliDoubleSided,
booliFresnel,
const RED::Color &iEmissiveColor,
const RED::Object *iEmissiveTexture,
const RED::Matrix &iEmissiveUVMatrix,
RED::MESH_CHANNELiEmissiveUVChannel,
const RED::Color &iAmbientColor,
const RED::Object *iAmbientTexture,
const RED::Matrix &iAmbientUVMatrix,
RED::MESH_CHANNELiAmbientUVChannel,
const RED::Color &iDiffuseColor,
const RED::Object *iDiffuseTexture,
const RED::Matrix &iDiffuseUVMatrix,
RED::MESH_CHANNELiDiffuseUVChannel,
const RED::Color &iSpecularColor,
const RED::Object *iSpecularTexture,
const RED::Matrix &iSpecularUVMatrix,
RED::MESH_CHANNELiSpecularUVChannel,
floatiSpecularExp,
const RED::Color &iReflectionColor,
const RED::Object *iReflectionTexture,
const RED::Matrix &iReflectionUVMatrix,
RED::MESH_CHANNELiReflectionUVChannel,
floatiReflectionGlossiness,
booliAutoEnv,
booliBackgroundEnv,
const RED::Object *iEnvironmentalTexture,
const RED::Matrix &iEnvironmentalMatrix,
floatiIOR,
const RED::Color &iOpacityColor,
const RED::Object *iOpacityTexture,
const RED::Matrix &iOpacityUVMatrix,
RED::MESH_CHANNELiOpacityUVChannel,
floatiOpacityGlossiness,
const RED::Object *iBumpTexture,
const RED::Matrix &iBumpUVMatrix,
RED::MESH_CHANNELiBumpUVChannel,
RED::MESH_CHANNELiBumpTangentsChannel,
const RED::LayerSet *iRealtimeLayerSet,
const RED::LayerSet *iPhotorealisticLayerSet,
RED::Object *iResourceManager,
const RED::State &iState
) = 0

Setups a generic material from user parameters.

This method configures an all-purpose generic material. It creates, setups and assembles shaders in a single RED material for real-time, photorealistic or both rendering modes. If the material has been previously setup (by the user or by a previous call to this method), it will be reset before processing. Any controller previously registered with the material will be unregistered and destroyed.

The generic material features:

  • An ambient and / or emissive term,
  • A Lambertian or Phong lighting model,
  • Bump mapping,
  • Glossy reflections with optional Fresnel term,
  • Colored ior-based glossy refractions or transparencies.

Transparency is expressed using opacity. Opacity is the opposite of the intuitive understanding of transparency: a material fully transparent will have a black opacity, while a fully opaque object will have a white opacity.

As for all REDsdk shaders, the bump texture must be a normal map (if your input texture is not already a normal map, you can convert it using RED::IImage2D::NormalMap).

The setup material requires at least one valid uv channel from geometries using it.

The material can be used either in real-time or in photorealistic rendering using the corresponding layer set. However, there are some differences between real-time and rendering configurations:

  • In real-time, environmental mapping is used in place of ray-traced reflections. Note that if automatic environment reflections are disabled (iAutoEnv == false && iBackgroundEnv == false), a valid cube texture pointer should be provided instead (i.e not NULL).
  • Glossy reflections and refractions are sampled using ray-tracing in photorealistic rendering mode.

Unlike the realistic material, the generic material has no built-in energy preservation. Therefore, if used in photo-realistic rendering environments with global illumination, care should be taken in ensuring that the material parameters are consistent: the sum of the diffusion, reflection and transmission terms from the material should be lower than or equal to 1.0.

Along with the shaders setup, a material controller is created giving access to all the material parameters really used. You can retrieve it by invoking the RED::IResourceManager::GetMaterialController method making the further edition of material parameters easy.

The list of all properties of a generic material can be found in REDIMaterialController.h.

At least one valid layer set pointer must be passed to the method. If both are equal, a RED_BAD_PARAM code will be returned.

See also Hello world!.

Parameters:

iDoubleSided:true if the material is double sided, false otherwise.
iFresnel:true if the material features Fresnel balancing between reflections and refractions, false otherwise.
iEmissiveColor:material emissive color.
iEmissiveTexture:material emissive texture.
iEmissiveUVMatrix:material emissive uv coordinates matrix.
iEmissiveUVChannel:material emissive uv coordinates channel.
iAmbientColor:material ambient color.
iAmbientTexture:material ambient texture.
iAmbientUVMatrix:material ambient uv coordinates matrix.
iAmbientUVChannel:material ambient uv coordinates channel.
iDiffuseColor:material diffuse color.
iDiffuseTexture:material diffuse texture.
iDiffuseUVMatrix:material diffuse uv coordinates matrix.
iDiffuseUVChannel:material diffuse uv coordinates channel.
iSpecularColor:material specular color.
iSpecularTexture:material specular texture.
iSpecularUVMatrix:material specular uv coordinates matrix.
iSpecularUVChannel:material specular uv coordinates channel.
iSpecularExp:material specular exponent.
iReflectionColor:material reflection color.
iReflectionTexture:material reflection texture.
iReflectionUVMatrix:material reflection uv coordinates matrix.
iReflectionUVChannel:material reflection uv coordinates channel.
iReflectionTexture:material reflection texture.
iReflectionGlossiness:material reflection glossiness (in [0 (not glossy), 1 (fully glossy)]).
iAutoEnv:flag indicating if auto environment should be computed for the real-time version of the material or not.
iBackgroundEnv:flag indicating if background environment should be used for the real-time version of the material or not. If both iAutoEnv and iBackgroundEnv are set to true, background environment reflection will be used.
iEnvironmentalTexture:if iAutoEnv and iBackgroundEnv are false this pointer to a cube texture will be used for real-time reflections.
iEnvironmentalMatrix:matrix to be applied to the provided iEnvironmentalTexture cube texture.
iIOR:material indice of refraction.
iOpacityColor:material opacity color.
iOpacityTexture:material opacity texture.
iOpacityUVMatrix:material opacity uv coordinates matrix.
iOpacityUVChannel:material opacity uv coordinates channel.
iOpacityGlossiness:material opacity glossiness (in [0 (not glossy), 1 (fully glossy)]).
iBumpTexture:material bump texture.
iBumpUVMatrix:material bump uv coordinates matrix.
iBumpUVChannel:material bump uv coordinates channel.
iBumpTangentsChannel:material tangents coordinates channel.
iRealtimeLayerSet:pointer to the layer set to be used to store the real-time configuration. Set it to NULL if you don't want a real-time configuration for the material.
iPhotorealisticLayerSet:pointer to the layer set to be used to store the photorealistic configuration. Set it to NULL if you don't want a photorealistic configuration for the material.
iResourceManager:pointer to the resource manager.
iState:current transaction.

Returns:

RED_OK on success,
RED_BAD_PARAM on an invalid parameter,
RED_ALLOC_FAILURE on a memory allocation error,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::SetupGenericPhongMaterial(booliDoubleSided,
const RED::Color &iEmissiveColor,
const RED::Object *iEmissiveTexture,
const RED::Matrix &iEmissiveUVMatrix,
RED::MESH_CHANNELiEmissiveUVChannel,
const RED::Color &iAmbientColor,
const RED::Object *iAmbientTexture,
const RED::Matrix &iAmbientUVMatrix,
RED::MESH_CHANNELiAmbientUVChannel,
const RED::Color &iDiffuseColor,
const RED::Object *iDiffuseTexture,
const RED::Matrix &iDiffuseUVMatrix,
RED::MESH_CHANNELiDiffuseUVChannel,
const RED::Color &iSpecularColor,
const RED::Object *iSpecularTexture,
const RED::Matrix &iSpecularUVMatrix,
RED::MESH_CHANNELiSpecularUVChannel,
floatiSpecularExp,
const RED::Color &iOpacityColor,
const RED::Object *iOpacityTexture,
const RED::Matrix &iOpacityUVMatrix,
RED::MESH_CHANNELiOpacityUVChannel,
floatiOpacityGlossiness,
const RED::Object *iBumpTexture,
const RED::Matrix &iBumpUVMatrix,
RED::MESH_CHANNELiBumpUVChannel,
RED::MESH_CHANNELiBumpTangentsChannel,
const RED::LayerSet *iRealtimeLayerSet,
const RED::LayerSet *iPhotorealisticLayerSet,
RED::Object *iResourceManager,
const RED::State &iState
) = 0

Setups a Phong material with emissive, ambient, diffuse, specular, transparency and bump.

This is a helper method provided for convenience. The returned material is based on a call to RED::IMaterial::SetupGenericMaterial (see the method documentation for more details).

See also Generic material.

Parameters:

iDoubleSided:true if the material is double sided, false otherwise.
iEmissiveColor:material emissive color.
iEmissiveTexture:material emissive texture.
iEmissiveUVMatrix:material emissive uv coordinates matrix.
iEmissiveUVChannel:material emissive uv coordinates channel.
iAmbientColor:material ambient color.
iAmbientTexture:material ambient texture.
iAmbientUVMatrix:material ambient uv coordinates matrix.
iAmbientUVChannel:material ambient uv coordinates channel.
iDiffuseColor:material diffuse color.
iDiffuseTexture:material diffuse texture.
iDiffuseUVMatrix:material diffuse uv coordinates matrix.
iDiffuseUVChannel:material diffuse uv coordinates channel.
iSpecularColor:material specular color.
iSpecularTexture:material specular texture.
iSpecularUVMatrix:material specular uv coordinates matrix.
iSpecularUVChannel:material specular uv coordinates channel.
iSpecularExp:material specular exponent.
iOpacityColor:material opacity color.
iOpacityTexture:material opacity texture.
iOpacityUVMatrix:material opacity uv coordinates matrix.
iOpacityUVChannel:material opacity uv coordinates channel.
iOpacityGlossiness:material opacity glossiness (in [0 (not glossy), 1 (fully glossy)]).
iBumpTexture:material bump texture.
iBumpUVMatrix:material bump uv coordinates matrix.
iBumpUVChannel:material bump uv coordinates channel.
iBumpTangentsChannel:material tangents coordinates channel.
iRealtimeLayerSet:pointer to the layer set to be used to store the real-time configuration. Set it to NULL if you don't want a real-time configuration for the material.
iPhotorealisticLayerSet:pointer to the layer set to be used to store the photorealistic configuration. Set it to NULL if you don't want a photorealistic configuration for the material.
iResourceManager:pointer to the resource manager.
iState:current transaction.

Returns:

RED_OK on success,
RED_BAD_PARAM on an invalid parameter,
RED_ALLOC_FAILURE on a memory allocation error,
RED_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::SetupRealisticMaterial(booliDoubleSided,
booliFresnel,
const RED::Color &iDiffuseColor,
const RED::Object *iDiffuseTexture,
const RED::Matrix &iDiffuseUVMatrix,
RED::MESH_CHANNELiDiffuseUVChannel,
const RED::Color &iReflectionColor,
const RED::Object *iReflectionTexture,
const RED::Matrix &iReflectionUVMatrix,
RED::MESH_CHANNELiReflectionUVChannel,
const RED::Color &iReflectionFogColor,
floatiReflectionFogDistance,
booliAutoEnv,
booliBackgroundEnv,
const RED::Object *iEnvironmentalTexture,
const RED::Matrix &iEnvironmentalMatrix,
const RED::Color &iTransmissionColor,
const RED::Object *iTransmissionTexture,
const RED::Matrix &iTransmissionUVMatrix,
RED::MESH_CHANNELiTransmissionUVChannel,
floatiTransmissionGlossiness,
const RED::Object *iTransmissionGlossinessTexture,
const RED::Matrix &iTransmissionGlossinessUVMatrix,
RED::MESH_CHANNELiTransmissionGlossinessUVChannel,
floatiIOR,
const RED::Color &iTransmissionScatteringColor,
floatiTransmissionScatteringScale,
booliCausticsReflective,
booliCausticsRefractive,
const RED::Color &iAnisotropy,
const RED::Object *iAnisotropyTexture,
const RED::Matrix &iAnisotropyMatrix,
RED::MESH_CHANNELiAnisotropyUV,
floatiAnisotropyRotation,
const RED::Object *iAnisotropyRotationTexture,
const RED::Matrix &iAnisotropyRotationUVMatrix,
RED::MESH_CHANNELiAnisotropyRotationUVChannel,
const RED::Object *iBumpTexture,
const RED::Matrix &iBumpUVMatrix,
RED::MESH_CHANNELiBumpUVChannel,
RED::MESH_CHANNELiBumpTangentsChannel,
floatiDisplacementHeight,
floatiDisplacementOffset,
const RED::Object *iDisplacementTexture,
const RED::Matrix &iDisplacementUVMatrix,
RED::MESH_CHANNELiDisplacementUVChannel,
const RED::LayerSet *iRealtimeLayerSet,
const RED::LayerSet *iPhotorealisticLayerSet,
RED::Object *iResourceManager,
const RED::State &iState
) = 0

Setups a realistic material from the user parameters.

Realistic materials are needed to render photorealistic images. They allow the simulation of complex, physically-based materials with only a few parameters.

This material features:

  • Energy conservation: it can't reflect more energy than it receives. This guarantees that the rendered image will be visually consistent.
  • Anisotropic reflection model: it can simulate anisotropic reflections like those produced by brushed metals, hair...
  • Bump and displacement mapping.
  • Glossy reflections and refractions
  • Reflective and refractive caustics.
  • Transmission scattering and reflection fogs.

The material can be used either in real-time or in photorealistic rendering using the corresponding used RED::LayerSet. However, there are some differences between real-time and rendering configurations:

  • In real-time, environmental mapping is used in place of ray-traced reflections. Hence, glossy reflections will be rendered sharp in real-time. Note that if automatic environment reflections are disabled (iAutoEnv == false && iBackgroundEnv == false), a valid cube texture pointer should be provided instead (i.e not NULL).
  • Similarly, in real-time a fake refractions are used instead of true ray-traced refractions.

The built material uses:

  • The RED::MCL_VERTEX channel of the source geometries for vertex positions.
  • The RED::MCL_NORMAL channel of the source geometries for vertex normals.
  • The specified iBumpTangentsChannel value if the material has a bumpy surface or if it uses glossy reflections or refractions. Tangents can be built using RED::IMeshShape::BuildTangents.

Parameters:

iDoubleSided:true if the material is double sided, false otherwise.
iFresnel:true if the material features Fresnel balancing between reflections and refractions, false otherwise.
iDiffuseColor:Material diffuse color.
iDiffuseTexture:Material diffuse texture. Overrides iDiffuseColor when set.
iDiffuseUVMatrix:Material diffuse uv coordinates matrix.
iDiffuseUVChannel:Material diffuse uv coordinates channel.
iReflectionColor:Material reflection color.
iReflectionTexture:Material reflection texture. Overrides iReflectionColor when set.
iReflectionUVMatrix:Material reflection uv coordinates matrix.
iReflectionUVChannel:Material reflection uv coordinates channel.
iReflectionFogColor:This is the color taken by reflections at iReflectionFogDistance. The reflection fog smoothly fades the true reflection color out and replaces it by the reflection fog color.
iReflectionFogDistance:Distance along a reflection ray at which the true reflection color has vanished and is replaced by the iReflectionFogColor. Set iReflectionFogDistance to FLT_MAX to disable all effect of the reflection fog.
iAutoEnv:Flag indicating if auto environment should be computed for the real-time version of the material or not.
iBackgroundEnv:Flag indicating if background environment should be used for the real-time version of the material or not. If both iAutoEnv and iBackgroundEnv are set to true, background environment reflection will be used.
iEnvironmentalTexture:If iAutoEnv and iBackgroundEnv are false this pointer to a cube texture will be used for real-time reflections.
iEnvironmentalMatrix:Matrix to be applied to the provided iEnvironmentalTexture cube texture.
iTransmissionColor:Material transmission color.
iTransmissionTexture:Material transmission texture. Overrides iTransmissionColor when set.
iTransmissionUVMatrix:Material transmission uv coordinates matrix.
iTransmissionUVChannel:Material transmission uv coordinates channel.
iTransmissionGlossiness:Material transmission glossiness (in [0 (not glossy), 1 (fully glossy)]).
iTransmissionGlossinessTexture:Material transmission glossiness texture stored as R component in [0.0, 1.0].
iTransmissionGlossinessUVMatrix:Material transmission glossiness uv coordinates matrix.
iTransmissionGlossinessUVChannel:Material transmission glossiness uv coordinates channel.
iIOR:Material indice of refraction.
iTransmissionScatteringColor:This is transmission scattering color. The transmission scattering color of a transparent material is an out-scattering coefficient applied to the transmission of the material all along of the path of a ray into the material. Consequently, the transmission of the material decreases with the distance crossed into the material, proportionnally to the value of the transmission scattering color. This scattering coefficient is expressed in model units. The material must be transparent for the transmission scattering color to have a visible effect, as this is an out-scattering term which is applied to the material transmission.
iTransmissionScatteringScale:The effect of the scattering due to iTransmissionScatteringColor may be modulated by iTransmissionScatteringScale, which acts as a multiplier on the distance in the crossed media, and therefore that multiplies the effect of the transmission scattering color as it gets scaled.
iCausticsReflective:True to enable the caustics due to reflections, false otherwise.
iCausticsRefractive:True to enable the caustics due to refractions, false otherwise.
iAnisotropy:Material anisotropy along U and V stored as R and G color components, in [0.0, 1.0]. 0.0 is non glossy. Glossiness increases quickly with iAnisotropy values.
iAnisotropyTexture:Material anisotropy texture. Overrides iAnisotropy when set. This texture is not supported for GPU rendering, and iAnisotropy values are used instead.
iAnisotropyMatrix:Material anisotropy texture UV transformation matrix.
iAnisotropyUV:Material anisotropy UV channel.
iAnisotropyRotation:Material anisotropy rotation angle (in [0, 1]). The value is mapped onto [0.0, 2 * RED_PI].
iAnisotropyRotationTexture:Material anisotropy rotation texture. The texture first channel value is mapped onto [0.0, 2 * RED_PI].
iAnisotropyRotationUVMatrix:Material anisotropy rotation uv coordinates matrix.
iAnisotropyRotationUVChannel:Material anisotropy rotation uv coordinates channel.
iBumpTexture:Material bump texture.
iBumpUVMatrix:Material bump uv coordinates matrix.
iBumpUVChannel:Material bump uv coordinates channel.
iBumpTangentsChannel:Material tangents coordinates channel.
iDisplacementHeight:Height of the displacement.
iDisplacementOffset:Offset of the displacement.
iDisplacementTexture:Displacement texture.
iDisplacementUVMatrix:Displacement texture uv coordinates matrix.
iDisplacementUVChannel:Displacement texture uv coordinates channel.
iRealtimeLayerSet:Pointer to the layer set to be used to store the real-time configuration. Set it to NULL if you don't want a real-time configuration for the material.
iPhotorealisticLayerSet:Pointer to the layer set to be used to store the photorealistic configuration. Set it to NULL if you don't want a photorealistic configuration for the material.
iResourceManagerpointer to the resource manager.
iStatecurrent transaction.

Returns:

RED_OK on success,
RED_BAD_PARAM on an invalid parameter,
RED_BAD_PARAM if iRealtimeLayerSet equals iPhotorealisticLayerSet RED_ALLOC_FAILURE on a memory allocation error, RED_WORKFLOW_ERROR if a transaction error has occurred, RED_FAIL otherwise.
public virtual RED_RC RED::IMaterial::UpdateCuttingPlaneEquation(const floatiPlaneEquation[4],
const RED::LayerSet &iLayerSet,
const RED::State &iState
) = 0

Changes the equation of the cutting plane.

After a call to RED::IMaterial::SetCuttingPlane, this method can be used to dynamically change the equation of the cutting plane for a given layerset configuration.

Parameters:

iPlaneEquation:Cutting plane equation. 4 values must be supplied in the array, in the order A, B, C, D that define each plane equation by A*x + B*y + C*z + D = 0. Coefficients must be in world space coordinates.
iLayerSet:The layerset for which we do the setup.
iState:The current transaction.

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_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL if the method could not change the cutting plane equation..
public virtual RED_RC RED::IMaterial::UpdateLogoMaskMatrix(const RED::Vector< RED::Matrix > &iLogoMaskMatrix,
const RED::LayerSet &iLayerSet,
const RED::State &iState
) = 0

Changes matrices of a logo masked material.

After a call to RED::IMaterial::SetLogoMask, the values of all matrices used to position the logo images can be changed directly using this method. Of course, the number of matrices in iLogoMaskMatrix should be the same as the one used during the setup of logo masks.

Parameters:

iLogoMaskMatrix:Texture matrix for each logo mask.
iLayerSet:The layerset for which we do the setup.
iState:The current transaction.

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_WORKFLOW_ERROR if a transaction error has occurred,
RED_FAIL otherwise.