class RED::IMaterialController

Material controller interface. More...

#include <REDIMaterialController.h>

Inherits: IREDObject.

Public functions:

virtual RED_RCAddHint ( const RED::String & iName, const RED::String & iHint ) = 0
virtual RED::Object *AddProperty ( const RED::String & iName, const RED::String & iDescription ) = 0
virtual RED_RCAddProperty ( RED::Object *& ioProperty, bool iAutoMerge = false ) = 0
virtual voidClearHints ( ) = 0
virtual voidClearProperties ( ) = 0
virtual RED_RCCopyFrom ( const RED::Object & iMaterialController, RED::Object * iMaterial ) = 0
virtual const RED::String &GetAuthor ( ) const = 0
virtual const RED::String &GetCategory ( ) const = 0
virtual RED_RCGetCoverage ( RED::Vector3 & oCoverage ) const = 0
virtual const RED::String &GetCreationDate ( ) const = 0
virtual const RED::String &GetDescription ( ) const = 0
virtual const RED::String &GetHint ( const RED::String & iName ) const = 0
virtual const RED::String &GetHint ( unsigned int iIndex ) const = 0
virtual const RED::String &GetHintName ( unsigned int iIndex ) const = 0
virtual unsigned intGetHintsCount ( ) const = 0
virtual RED::Object *GetMaterial ( ) const = 0
virtual const RED::String &GetName ( ) const = 0
virtual unsigned intGetPropertiesCount ( ) const = 0
virtual RED::Object *GetProperty ( unsigned int iIndex ) const = 0
virtual RED::Object *GetProperty ( const RED::String & iName ) const = 0
virtual const RED::String &GetSdkVersion ( ) const = 0
virtual const RED::String &GetSubCategory ( ) const = 0
virtual RED::Object *GetThumbnail ( ) const = 0
virtual RED_RCMerge ( const RED::Object & iMaterialController ) = 0
virtual voidSetAuthor ( const RED::String & iAuthor ) = 0
virtual voidSetCategory ( const RED::String & iCategory ) = 0
virtual voidSetDescription ( const RED::String & iDescription ) = 0
virtual voidSetName ( const RED::String & iName ) = 0
virtual voidSetSubCategory ( const RED::String & iSubCategory ) = 0
virtual voidSetThumbnail ( RED::Object * iThumbnail ) = 0

Public static functions:

static RED::CIDGetClassID ( )

Detailed description:

Material controller interface.

A material controller exposes a high-level view for a given RED material. This view is usually very simple as it shows only very few parameters (e.g color or shininess). This way the user can get rid of the flexible but complex REDsdk material shader API. Moreover, a software developer can use the built-in parameters access mechanism to automatically expose RED materials in his own application.

A material controller is created and linked to a material using the RED::Factory::CreateMaterialController call. Then, the resource manager API can be used to manage or to remove the link between a material controller and a material (RED::IResourceManager::UnregisterMaterialController).

A material controller mainly stores two information: a pointer to a RED material and a list of properties (RED::IMaterialControllerProperty). Each property has a script associated to it that transforms parameters values to shader changes. This script is written in a minimal language that is described in the REDsdk Programming guide.

The controller also stores additional information about how and for what use the material was created. This includes REDsdk version, author name, material description, material category and sub-category...

Finally, users can add so called hints to their controllers. Hints are user strings stored in a controller map. They are automatically saved along with the material properties and can be freely retrieved using the RED::IMaterialController interface. They can be used to store additional information needed by user applications to correctly handle materials. For example, some real- time materials in the Redmaterials library have hints that describe their glossiness. Those hints are later used by Redexplorer to correctly select a pre-computed environmental texture when rendering the materials.

See the Writing material controller properties tutorial for an example of use.

Functions documentation

public static RED::CID RED::IMaterialController::GetClassID()
public virtual RED_RC RED::IMaterialController::AddHint(const RED::String &iName,
const RED::String &iHint
) = 0

Adds a hint string.

If a hint with the same name already exists, it will be overwritten by the new one.

Parameters:

iName:name of the hint.
iHint:hint string.

Returns:

RED_OK on success,
RED_ALLOC_FAILURE on memory allocation error,
RED_FAIL otherwise.
public virtual RED::Object * RED::IMaterialController::AddProperty(const RED::String &iName,
const RED::String &iDescription
) = 0

Adds a property (RED::IMaterialControllerProperty instance) to the controller. The method takes care of allocating the property object.

See also Writing material controller properties.

Parameters:

iName:Property name.
iDescription:Property description.

Returns:

A pointer to the added property on success,
NULL if a property of the same name already exists in the controller or if an allocation failure has occurred.
public virtual RED_RC RED::IMaterialController::AddProperty(RED::Object *&ioProperty,
booliAutoMerge = false
) = 0

Adds an existing property to a controller.

The controller becomes the owner of the property, meaning that it will delete it upon destruction. If auto merging is enabled and the added property is merged with an already existing one, the added property will be automatically deleted by the method (this is because the material controller is now the owner of the added property).

See also Writing material controller properties.

Parameters:

ioProperty:reference to the pointer to the property to be added.
iAutoMerge:flag indicating if the added property should be automatically merged if one of the controller properties shares the same name (default is false). If two properties share the same name and the flag is set to false, the method will return RED_FAIL.

Returns:

RED_OK on success,
RED_BAD_PARAM on an invalid parameter,
RED_ALLOC_FAILURE on a memory allocation error,
RED_FAIL otherwise.
public virtual void RED::IMaterialController::ClearHints() = 0

Clears the controller hints.

public virtual void RED::IMaterialController::ClearProperties() = 0

Clears the controller properties.

public virtual RED_RC RED::IMaterialController::CopyFrom(const RED::Object &iMaterialController,
RED::Object *iMaterial
) = 0

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

This method will work for only two instances of the same concrete class. It creates a clone of the given material controller and applies it to the supplied material instance. If a thumbnail image is present in the given material controller, it is neither duplicated nor referenced. The thumbnail of the destination controller will be left unchanged.

Parameters:

iMaterialController:Reference to the object to copy from.
iMaterial:Pointer to a valid material to control.

Returns:

RED_OK on success,
RED_BAD_PARAM if iMaterialController and this are from different classes, or iMaterial does not implement RED::IMaterial,
RED_FAIL on any other error.
public virtual const RED::String & RED::IMaterialController::GetAuthor() const = 0

Returns:

the name of the material controller author.
public virtual const RED::String & RED::IMaterialController::GetCategory() const = 0

Returns:

the material controller category.
public virtual RED_RC RED::IMaterialController::GetCoverage(RED::Vector3 &oCoverage) const = 0

Helper method to retrieve the surface covered by a material.

Coverage information can be associated to materials using textures through the RED::IMaterialController hints system. The materials from the RED materials library which use textures are all using this mechanism to give users information about the surface being covered by the materials.

To make this helper works, the hint describing the texture coverage must respect the following format:

  • hint name: Coverage
  • hint string: Texture coverage is Xm x Ym x Zm where X, Y & Z are optional distances

A material covering a surface of 0.5 meter by 2.8 meters will then be described by hint:

Coverage

, Texture coverage is 0.5m x 2.8m

A call to GetCoverage on that material will return RED::Vector3( 0.5, 2.8, 0.0 ).

If no coverage information is available, or if the hint does not satisfy the previously described format, RED::Vector3::ZERO is returned.

Parameters:

oCoverage:reference to the returned RED::Vector3 storing the material coverage in each dimension.

Returns:

RED_OK on success (even if no coverage information is available),
RED_ALLOC_FAILURE on a memory allocation error,
RED_FAIL otherwise.
public virtual const RED::String & RED::IMaterialController::GetCreationDate() const = 0

Returns:

the material creation date.
public virtual const RED::String & RED::IMaterialController::GetDescription() const = 0

Returns:

the material description.
public virtual const RED::String & RED::IMaterialController::GetHint(const RED::String &iName) const = 0

Gets a hint.

Parameters:

iName:Name of the hint to retrieve.

Returns:

the hint string on success, an empty string otherwise.
public virtual const RED::String & RED::IMaterialController::GetHint(unsigned intiIndex) const = 0

Gets a hint.

Parameters:

iIndex:Index of the hint to retrieve (must be comprised between 0 and GetHintsCount()-1).

Returns:

the hint string on success, an empty string otherwise.
public virtual const RED::String & RED::IMaterialController::GetHintName(unsigned intiIndex) const = 0

Gets the name of a hint.

Parameters:

iIndex:Index of the hint to retrieve (must be comprised between 0 and GetHintsCount()-1).

Returns:

the hint name string on success, an empty string otherwise.
public virtual unsigned int RED::IMaterialController::GetHintsCount() const = 0

Returns:

the number of hints.
public virtual RED::Object * RED::IMaterialController::GetMaterial() const = 0

Returns:

a pointer to the controlled material.
public virtual const RED::String & RED::IMaterialController::GetName() const = 0

Returns:

the public name of the material controller.
public virtual unsigned int RED::IMaterialController::GetPropertiesCount() const = 0

Gets the properties count.

See also Enumerating a material controller's properties.

Returns:

the number of properties.
public virtual RED::Object * RED::IMaterialController::GetProperty(unsigned intiIndex) const = 0

Gets a material property (which implements the RED::IMaterialControllerProperty interface).

See also Writing material controller properties.

Parameters:

iIndex:Index of the property to retrieve (must be comprised between 0 and GetPropertiesCount()-1).

Returns:

a pointer to the requested property (if any), NULL otherwise.
public virtual RED::Object * RED::IMaterialController::GetProperty(const RED::String &iName) const = 0

Gets a material property (which implements the RED::IMaterialControllerProperty interface).

See also Writing material controller properties.

Parameters:

iName:Name of the property to retrieve.

Returns:

a pointer to the requested property (if any), NULL otherwise.
public virtual const RED::String & RED::IMaterialController::GetSdkVersion() const = 0

Returns:

the REDsdk version used to create the material.
public virtual const RED::String & RED::IMaterialController::GetSubCategory() const = 0

Returns:

the material controller sub-category.
public virtual RED::Object * RED::IMaterialController::GetThumbnail() const = 0

Returns:

a pointer to the material thumbnail image (if any), NULL otherwise.
public virtual RED_RC RED::IMaterialController::Merge(const RED::Object &iMaterialController) = 0

Merges two controllers into a single one.

The callee is merged with the input controller to create a single controller using the following rules:

  • any property of the input controller not found in the callee's properties will be added to it
  • any property with the same name and type but different scripts in both controllers will be merged together in the callee (scripts will be concateneted)
  • any property with the same name, type and script in both controllers will be discarded
  • any property with the same name but different types in both controllers will make the method to return with RED_FAIL.

Please note that the hints are also merged using the previous rules. However, there is an exception in the case of two hints with the same name but different values: the hint from the input controller is added to the callee ones with a different name (a '_2' string is added at the end of the name).

Parameters:

iMaterialController:reference to the input controller.

Returns:

RED_OK on success,
RED_BAD_PARAM on an invalid parameter,
RED_FAIL on any other error.
public virtual void RED::IMaterialController::SetAuthor(const RED::String &iAuthor) = 0

Sets the material controller author's name.

Parameters:

iAuthorname of the material controller author.
public virtual void RED::IMaterialController::SetCategory(const RED::String &iCategory) = 0

Sets the material controller category.

Parameters:

iCategorycategory of the material controller.
public virtual void RED::IMaterialController::SetDescription(const RED::String &iDescription) = 0

Sets the material controller description.

Parameters:

iDescriptiondescription of the material controller.
public virtual void RED::IMaterialController::SetName(const RED::String &iName) = 0

Sets the public name of the material controller.

Parameters:

iNamename of the material controller.
public virtual void RED::IMaterialController::SetSubCategory(const RED::String &iSubCategory) = 0

Sets the material controller sub-category.

Parameters:

iSubCategorysub-category of the material controller.
public virtual void RED::IMaterialController::SetThumbnail(RED::Object *iThumbnail) = 0

Sets the material thumbnail image.

If NULL is passed, the previous thumbnail image will be removed.

Parameters:

iThumbnail:Pointer to the new material thumbnail image.