IMaterial
Functions
bool |
|
int |
|
const LayerSet & |
|
const Shader * |
|
Detailed Description
-
class IMaterial : public RED::IREDObject
This interface gives access to the material’s properties.
@related Building HOOPS Luminate Materials, Generic Material, Using the Realistic Material
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:
The pre-lighting sequence is executed first,
The lighting sequence follows it,
The post-lighting sequence completes the rendering of the material.
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 pre-lighting sequence is processed once per objects seen in the view, and is the first pass of the rendering of a frame. Ambient lighting is usually performed with a RED::RenderShader set to the built-in ambient lighting programs, which is set as unique shader in the pre-lighting sequence of the material.
The lighting sequence follows the pre-lighting, ans there’s one pass of rendering executed per object that receive illumination from a light. This is here that the lighting model is implemented, with the appropriate render shaders. Default pass blending mode is additive, so that every light’s contribution is added to the final image result.
The post-lighting sequence comes last. It can be used to apply post filterings, or any other kind of rendering tasks. It gets executed once per object seen in the view.
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 \ref bk_ap_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:
Immediate mode control, that can be used to reduce the amount of GPU memory being used, at the price of a slower display. See RED::IMaterial::SetImmediateMode.
Batching control, that can be used to gather shared resources used by geometrical primitives on the GPU. See RED::IMaterial::AddBatchArrays or RED::IMaterial::SetBatchMode.
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.
Public Functions
-
virtual RED_RC 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.
See also \ref wf_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.
-
virtual bool IsRegistered(unsigned int iID, int iStateNumber = -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.
-
virtual RED_RC DeleteShader(unsigned int iShaderID, 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.
-
virtual RED_RC UpdateShader(const RED::Shader &iShader, const RED::State &iState) = 0
Updates a shader inside the material.
The method look for a registered shader with the same ID as iShader’s own ID and replaces the contents it has with iShader’s contents.
- Parameters
iShader – The shader to update.
iState – Current transaction parameter.
- Returns
RED_OK if the shader can be updated,
RED_WORKFLOW_ERROR if a transaction error is found,
RED_ALLOC_FAILURE if an internal memory allocation fails,
RED_FAIL otherwise.
-
virtual RED_RC ClearShaders(const RED::State &iState) = 0
Deletes all shaders in the material.
All shaders are cleared from all configurations and rendering passes.
See also \ref bk_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.
-
virtual RED_RC AddShaderToPass(unsigned int iShaderID, RED::MATERIAL_PASS iPass, RED::LIST_POS iPosition, 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 \ref wf_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.
-
virtual RED_RC RemoveShaderFromPass(unsigned int iShaderID, RED::MATERIAL_PASS iPass, 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 \ref wf_custom_arb_shader.
- 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.
-
virtual RED_RC RemoveShaderFromLayerSets(unsigned int iShaderID, RED::MATERIAL_PASS iPass, const RED::State &iState) = 0
Removes a shader from all layersets for a given pass.
This method removes the shader identified by iShaderID from all material layersets configurations, for the specified iPass rendering pass.
Note that the shader is neither destroyed nor unregistered. To completely destroy the shader, please use the RED::IMaterial::DeleteShader method instead.
The method does nothing if iShaderID is not found.
- Parameters
iShaderID – Identifier of the shader.
iPass – The pass to look for across all layersets configurations.
iState – The current transaction parameter.
- Returns
RED_OK is the operation succeeds,
RED_WORKFLOW_ERROR if a transaction error occurs,
RED_ALLOC_FAILURE if an internal allocation fails,
RED_FAIL otherwise.
-
virtual RED_RC RemoveShaderFromPasses(unsigned int iShaderID, const RED::LayerSet &iLayerSet, const RED::State &iState) = 0
Removes a shader from all passes for a given layerset.
This method removes the shader identified by iShaderID from all rendering passes, for a given layerset.
Note that the shader is neither destroyed nor unregistered. To completely destroy the shader, please use the RED::IMaterial::DeleteShader method instead.
The method does nothing if iShaderID is not found or if iLayerSet is not found in the material layers.
- Parameters
iShaderID – Identifier of the shader.
iLayerSet – The targeted layerset configuration.
iState – The current transaction parameter.
- Returns
RED_OK is the operation succeeds,
RED_WORKFLOW_ERROR if a transaction error occurs,
RED_ALLOC_FAILURE if an internal allocation fails,
RED_FAIL otherwise.
-
virtual RED_RC RemoveShader(unsigned int iShaderID, const RED::State &iState) = 0
Removes a shader from all passes for all layersets.
This method removes the shader identified by iShaderID from all rendering passes, for all layersets.
Note that the shader is neither destroyed nor unregistered. To completely destroy the shader, please use the RED::IMaterial::DeleteShader method instead.
The method does nothing if iShaderID is not found.
- Parameters
iShaderID – Identifier of the shader.
iState – The current transaction parameter.
- Returns
RED_OK is the operation succeeds,
RED_WORKFLOW_ERROR if a transaction error occurs,
RED_ALLOC_FAILURE if an internal allocation fails,
RED_FAIL otherwise.
-
virtual RED_RC ClearShaderPass(RED::MATERIAL_PASS iPass, 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.
-
virtual RED_RC ClearShaderLayerSet(const RED::LayerSet &iLayerSet, const RED::State &iState) = 0
Removes all shaders associated to the iLayerSet configuration.
The method does nothing if iLayerSet is not found.
- Parameters
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.
-
virtual int LayerSetsCount(int iStateNumber = -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.
-
virtual const RED::LayerSet &GetLayerSet(int iLayerSet, int iStateNumber = -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.
-
virtual const RED::Shader *GetShader(unsigned int iShaderID, RED::MATERIAL_PASS iPass, const RED::LayerSet &iLayerSet, int iNumState = -1) const = 0
Gets a shader in read only mode.
Looks for the shader identified by iID, for a read only access.
See also \ref wf_custom_geometry_shader.
- 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.
-
virtual RED_RC GetShader(unsigned int iShaderID, RED::MATERIAL_PASS iPass, 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 \ref wf_custom_geometry_shader.
- 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 succeeds,
RED_BAD_PARAM if the method receives an invalid parameter,
RED_WORKFLOW_ERROR if a transaction error occurs,
RED_ALLOC_FAILURE if an internal memory allocation fails,
RED_FAIL otherwise.
-
virtual RED_RC GetShaders(RED::Vector<RED::Shader*> &oShaders, RED::MATERIAL_PASS iPass, const RED::LayerSet &iLayerSet, int iNumState = -1) const = 0
Gets all the shaders in a layer in read-only mode for a given pass and layerset.
See also \ref wf_volume_view for an usage example.
Shaders returned in oShaders may be duplicated. As this is the list of shaders actually registered for iPass and iLayerSet that is returned, so if a shader was set to be rendered twice, it’ll appear twice in that list.
- Parameters
oShaders – Addresses of 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 if the operation succeeds.
RED_BAD_PARAM if the method receives an invalid parameter,
RED_ALLOC_FAILURE if a memory allocation fails,
RED_FAIL otherwise.
-
virtual RED_RC GetShaders(RED::Vector<RED::Shader*> &oShaders, RED::MATERIAL_PASS iPass, const RED::LayerSet &iLayerSet, const RED::State &iState) = 0
Gets all the shaders in a layer in read-write mode for a given pass and layerset.
See also \ref wf_volume_view for an usage example.
Shaders returned in oShaders may be duplicated. As this is the list of shaders actually registered for iPass and iLayerSet that is returned, so if a shader was set to be rendered twice, it’ll appear twice in that list.
- Parameters
oShaders – Addresses of 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 if the operation succeeds,
RED_BAD_PARAM if the method receives an invalid parameter,
RED_WORKFLOW_ERROR if a transaction error occurs,
RED_ALLOC_FAILURE if an internal memory allocation fails,
RED_FAIL otherwise.
-
virtual RED_RC GetShaders(RED::Vector<RED::Shader*> &oShaders, RED::MATERIAL_PASS iPass, int iNumState = -1) const = 0
Gets all the shaders in a layer in read-only mode for a given pass and for all layersets.
The returned list is filtered and can’t contain twice the same shader.
- Parameters
oShaders – Addresses of found shaders. The list can’t contain twice the same shader.
iPass – Pass where to look for the requested shaders.
iNumState – The queried state number.
- Returns
RED_OK if the operation succeeds.
RED_BAD_PARAM if the method receives an invalid parameter,
RED_ALLOC_FAILURE if a memory allocation fails,
RED_FAIL otherwise.
-
virtual RED_RC GetShaders(RED::Vector<RED::Shader*> &oShaders, RED::MATERIAL_PASS iPass, const RED::State &iState) = 0
Gets all the shaders in a layer in read-write mode for a given pass and for all layersets.
The returned list is filtered and can’t contain twice the same shader.
- Parameters
oShaders – Addresses of found shaders. The list can’t contain twice the same shader.
iPass – Pass where to look for the requested shaders.
iState – The current transaction parameter.
- Returns
RED_OK if the operation succeeds,
RED_BAD_PARAM if the method receives an invalid parameter,
RED_WORKFLOW_ERROR if a transaction error occurs,
RED_ALLOC_FAILURE if an internal memory allocation fails,
RED_FAIL otherwise.
-
virtual RED_RC GetShaders(RED::Vector<RED::Shader*> &oShaders, const RED::LayerSet &iLayerSet, int iNumState = -1) const = 0
Gets all the shaders in a layer in read-only mode for all passes in a layerset.
The returned list is filtered and can’t contain twice the same shader.
- Parameters
oShaders – Addresses of found shaders. The list can’t contain twice the same shader.
iLayerSet – Layers set for which we want to retrieve the material’s layers.
iNumState – The queried state number.
- Returns
RED_OK if the operation succeeds.
RED_BAD_PARAM if the method receives an invalid parameter,
RED_ALLOC_FAILURE if a memory allocation fails,
RED_FAIL otherwise.
-
virtual RED_RC GetShaders(RED::Vector<RED::Shader*> &oShaders, const RED::LayerSet &iLayerSet, const RED::State &iState) = 0
Gets all the shaders in a layer in read-write mode for all passes in a layerset.
The returned list is filtered and can’t contain twice the same shader.
- Parameters
oShaders – Addresses of found shaders. The list can’t contain twice the same shader.
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.
-
virtual RED_RC GetShaderList(RED::Vector<const RED::Shader*> &oShaders, int iNumState = -1) const = 0
Gets all the shaders in read-only mode.
See also \ref bk_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.
-
virtual RED_RC GetShaderList(RED::Vector<RED::Shader*> &oShaders, const RED::State &iState) = 0
Gets all the shaders in read-write mode.
See also \ref bk_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.
-
virtual RED_RC GetImageList(RED::Map<RED::Object*, int> &oImageList, int iStateNumber = -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.
-
virtual RED_RC SetPriority(int iPriority, 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 \ref wf_polygon_offset_edges.
- 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.
-
virtual RED_RC GetPriority(int &oPriority, int iStateNumber = -1) const = 0
Gets the rendering priority of a material.
See RED::IMaterial::SetPriority.
See also \ref wf_polygon_offset_edges.
- 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.
-
virtual RED_RC CopyFrom(const RED::Object &iMaterial, const RED::State &iState, int iSrcStateNumber = -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.
-
virtual RED_RC CopyFrom(const RED::Object &iMaterial, const RED::LayerSet &iLayerSetSrc, const RED::LayerSet &iLayerSetDest, const RED::State &iState, bool iImageCopy = false, bool iTinyImageCopy = 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.
-
virtual RED_RC 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_03ls_01
ls_02
ls_02iMaterial
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_03ls_01
ls_01
ls_01iMaterial
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.
-
virtual RED_RC GetUsedChannels(RED::Map<RED::LayerSet, RED::Vector<RED::MESH_CHANNEL>> &ioChannels, int iNumState = -1) = 0
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.
-
virtual RED_RC SetImmediateMode(bool iOnOff, 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.
-
virtual RED_RC GetImmediateMode(bool &oOnOff, int iNumState = -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.
-
virtual RED_RC SetPolygonOffset(float iPolyOffsetFactor, float iPolyOffsetUnits, 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 \ref wf_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.
-
virtual RED_RC GetPolygonOffset(float &oPolyOffsetFactor, float &oPolyOffsetUnits, const RED::LayerSet &iLayerSet, int iStateNumber = -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 \ref wf_polygon_offset_edges.
- 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.
-
virtual RED_RC SetCaustics(bool iReflectiveCaustics, bool iRefractiveCaustics, 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 \ref bk_re_sw3d_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.
-
virtual RED_RC GetCaustics(bool &oReflectiveCaustics, bool &oRefractiveCaustics, const RED::LayerSet &iLayerSet, int iStateNumber = -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.
-
virtual RED_RC SetDisplacement(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
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 \ref wf_displacement 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.
-
virtual RED_RC GetDisplacement(float &oDispHeight, RED::Object *&oDispTexture, RED::Matrix &oDispMatrix, RED::MESH_CHANNEL &oDispUV, float &oDispOffset, const RED::LayerSet &iLayerSet, int iStateNumber = -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 \ref wf_displacement 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.
-
virtual RED_RC SetLogoMask(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
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 \ref wf_logomapping 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.
-
virtual RED_RC 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.
-
virtual RED_RC SetCuttingPlane(const float iPlaneEquation[4], const RED::Shader *iSectionCapShader, const RED::LayerSet &iLayerSet, bool iEdgeMaterial, 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:
RED_SECTION_CUT_SHADER_MESH_PRELIT_STRING_ID for the rendering of meshes or standard edges (no specific edge shader).
RED_SECTION_CUT_SHADER_EDGE_PRELIT_STRING_ID for the rendering of edges using the RED::RenderShaderEdges.
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 \ref wf_section_cutting 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.
-
virtual RED_RC UpdateCuttingPlaneEquation(const float iPlaneEquation[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..
-
virtual RED_RC SetupGenericMaterial(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, bool iRealtimeRefraction, 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
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 \ref wf_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.
iRealtimeRefraction – enable the realtime refraction effect.
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.
-
virtual RED_RC SetupGenericBumpyDiffuseMaterial(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
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 \ref wf_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.
-
virtual RED_RC SetupGenericDiffuseMaterial(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
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 \ref wf_material_generic.
- 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.
-
virtual RED_RC SetupGenericLambertMaterial(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
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 \ref wf_material_generic.
- 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.
-
virtual RED_RC SetupGenericPhongMaterial(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
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 \ref wf_material_generic.
- 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.
-
virtual RED_RC SetupRealisticMaterial(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::Object *iIORTexture, const RED::Matrix &iIORUVMatrix, RED::MESH_CHANNEL iIORUVChannel, 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
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.
iIORTexture – Material indice of refraction texture stored as R component. Overrides iIOR when set.
iIORUVMatrix – Material indice of refraction uv coordinates matrix.
iIORUVChannel – Material indice of refraction uv coordinates channel.
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.
iResourceManager – pointer to the resource manager.
iState – current 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.
-
virtual RED_RC SetBatchMode(bool iBatchMode, 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 \ref wf_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.
-
virtual RED_RC GetBatchMode(bool &oBatchMode, int iStateNumber = -1) const = 0
Returns the batching status for this material.
See also \ref wf_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.
-
virtual RED_RC AddBatchArrays(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
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.
-
virtual RED_RC AddBatchIndices(int *iIndex, int iCount, int iPrimitiveSize, 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.
-
virtual RED_RC 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.
-
virtual RED_RC GetBatchArraysCount(int &oCount, int iStateNumber = -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.
-
virtual RED_RC 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, int iStateNumber = -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.
-
virtual RED_RC GetBatchIndicesCount(int &oCount, int iStateNumber = -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.
-
virtual RED_RC GetBatchIndices(RED::Vector<int*> &oIndex, RED::Vector<int> &oCount, RED::Vector<int> &oPrimitiveSize, int iStateNumber = -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.
-
virtual RED_RC 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.
-
virtual RED_RC IsBatchArrayUpdate(bool &oUpdate, void *iRefData, void *iData, int iStateNumber = -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.
-
virtual RED_RC AddBatchSubArrayUpdate(void *iData, int iNumVertexStart, int iVerticesCount, 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.
