IMaterialController
Functions
void |
|
const String & |
|
void |
|
const String & |
|
void |
|
const String & |
|
const String & |
|
const String & |
|
void |
|
void |
|
const String & |
|
const String & |
|
Object * |
|
Object * |
|
void |
|
Object * |
|
Object * |
|
Object * |
|
unsigned int |
|
void |
|
const String & |
|
const String & |
|
const String & |
|
unsigned int |
|
void |
|
Detailed Description
-
class IMaterialController : public RED::IREDObject
Material controller interface.
@related The Material Controller, Writing Material Controller Properties, class RED::IMaterialControllerProperty
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 \ref wf_writing_material_controller_properties tutorial for an example of use.
Public Functions
-
SET_CID(CID_class_REDIMaterialController)
-
virtual void SetName(const RED::String &iName) = 0
Sets the public name of the material controller.
- Parameters
iName – name of the material controller.
-
virtual void SetCategory(const RED::String &iCategory) = 0
Sets the material controller category.
- Parameters
iCategory – category of the material controller.
-
virtual void SetSubCategory(const RED::String &iSubCategory) = 0
Sets the material controller sub-category.
- Parameters
iSubCategory – sub-category of the material controller.
-
virtual const RED::String &GetSubCategory() const = 0
- Returns
the material controller sub-category.
-
virtual const RED::String &GetSdkVersion() const = 0
- Returns
the REDsdk version used to create the material.
-
virtual void SetDescription(const RED::String &iDescription) = 0
Sets the material controller description.
- Parameters
iDescription – description of the material controller.
-
virtual void SetAuthor(const RED::String &iAuthor) = 0
Sets the material controller author’s name.
- Parameters
iAuthor – name of the material controller author.
-
virtual const RED::String &GetAuthor() const = 0
- Returns
the name of the material controller author.
-
virtual RED::Object *GetThumbnail() const = 0
- Returns
a pointer to the material thumbnail image (if any), NULL otherwise.
-
virtual void 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.
-
virtual RED::Object *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 \ref wf_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.
-
virtual RED_RC AddProperty(RED::Object *&ioProperty, bool iAutoMerge = 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 \ref wf_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.
-
virtual RED::Object *GetProperty(unsigned int iIndex) const = 0
Gets a material property (which implements the RED::IMaterialControllerProperty interface).
See also \ref wf_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.
-
virtual RED::Object *GetProperty(const RED::String &iName) const = 0
Gets a material property (which implements the RED::IMaterialControllerProperty interface).
See also \ref wf_writing_material_controller_properties.
- Parameters
iName – Name of the property to retrieve.
- Returns
a pointer to the requested property (if any), NULL otherwise.
-
virtual unsigned int GetPropertiesCount() const = 0
Gets the properties count.
See also \ref tk_enumerating_a_material_controller_properties.
- Returns
the number of properties.
-
virtual void ClearProperties() = 0
Clears the controller properties.
-
virtual RED_RC 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.
-
virtual const RED::String &GetHintName(unsigned int iIndex) 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.
-
virtual const RED::String &GetHint(unsigned int iIndex) 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.
-
virtual const RED::String &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.
-
virtual unsigned int GetHintsCount() const = 0
- Returns
the number of hints.
-
virtual void ClearHints() = 0
Clears the controller hints.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
SET_CID(CID_class_REDIMaterialController)
