IMaterialControllerProperty

Detailed Description

class IMaterialControllerProperty : public RED::IREDObject

Material controller property interface.

@related The Material Controller, Writing Material Controller Properties, class RED::IMaterialController

See the RED::IMaterialController interface documentation and the \ref bk_bm_the_material_controller document for an in-depth understanding of the REDsdk material controller feature.

RED::IMaterialControllerProperty are basic components of a material controller. Each property describe the behavior of an underlying material at a macroscopic level.

Let’s take the example of a shiny plastic material. Intuitively, such a material should expose at least two parameters: one for the plastic color and another one for the shininess intensity. In REDsdk, a plastic material would use a RED::RenderShaderPhong for the lighting shading. This kind of shader exposes a lot more parameters than just two colors and therefore is a lot more complex to set for a non-professional user. A programmer using REDsdk can create a RED::IMaterialController for his shiny plastic material with the two mentioned colors added as properties. He would have to write a little bit of MSC code (Material Controller Script introduced in the Programming guide document) to connect properties input to underlying shader ones.

Material controller properties can be of any following built-in types:

float, integer, boolean, color, texture 2D, 3D or cube, layerset.

For each of these types, two accessors are available (one for reading, another one for writing).

When accessing to a property using an accessor of the wrong type, an undetermined result will be returned. Using an accessor in write mode overwrite the type of the property with the one of the accessor used.

A range of definition can be defined for float and integer scalar properties. REDsdk will not check that assigned values fall inside the range (if defined). It’s up to the caller to check them before setting them.

Finally, instances of that class can have additional information about the role they play in the underlying material setup (RED::IMaterialControllerProperty::GetDescription).

See also \ref tk_enumerating_a_material_controller_properties.

Public Functions

SET_CID(CID_class_REDIMaterialControllerProperty)
virtual const RED::String &GetName() const = 0

Gets the public name of the property.

Returns:the public name of the property.
virtual const RED::String &GetDescription() const = 0

Gets the property description.

Returns:the property description.
virtual RED_RC SetScript(const RED::String &iScript) = 0

Sets the script associated with the property.

The script is automatically compiled when set.

Parameters:iScript – Source code of the script.
Returns:RED_OK on success,

RED_MAT_COMPILATION_FAILED on compilation failure,

RED_FAIL otherwise.
virtual const RED::String &GetScript() const = 0

Gets the script associated with the property.

Returns:the script associated with the property.
virtual RED::PROPERTY_TYPE GetType() const = 0

Gets the property type.

Returns:the property type.
virtual RED_RC Set(const RED::IMaterialControllerProperty &iProperty, const RED::State &iState) = 0

Sets the property from an input RED::IMaterialControllerProperty instance.

This method overrides only the property value and type with the input ones. Property name, script and description are left unmodified.

Parameters:
  • iProperty – reference to the input property to be copied.
  • iState – Current transaction.
Returns:

RED_OK on success,

RED_FAIL otherwise.
virtual RED_RC SetColor(const RED::Color &iColor, const RED::State &iState) = 0

Sets the property color.

This method automatically set the property type to PYT_COLOR.

Parameters:
  • iColor – Poperty color.
  • iState – Current transaction.
Returns:

RED_OK on success,

RED_FAIL otherwise.
virtual const RED::Color &GetColor() const = 0

Gets the property color.

If the property type is not PYT_COLOR, the returned color may be undefined.

Returns:the property color.
virtual RED_RC SetFloatValue(float iValue, const RED::State &iState) = 0

Sets the float property value.

This method automatically set the property type to PYT_FLOAT. If the type cnanges, the value range is reset to [-FLT_MAX, FLT_MAX].

Parameters:
  • iValue – Poperty value.
  • iState – Current transaction.
Returns:

RED_OK on success,

RED_FAIL otherwise.
virtual float GetFloatValue() const = 0

Gets the float property value.

If the property type is not PYT_FLOAT, the returned value may be undefined.

Returns:the property value.
virtual RED_RC SetIntegerValue(int iValue, const RED::State &iState) = 0

Sets the integer property value.

This method automatically set the property type to PYT_INTEGER. If the type changes, the value range is reset to [INT_MIN, INT_MAX].

Parameters:
  • iValue – Poperty value.
  • iState – Current transaction.
Returns:

RED_OK on success,

RED_FAIL otherwise.
virtual int GetIntegerValue() const = 0

Gets the integer property value.

If the property type is not PYT_INTEGER, the returned value may be undefined.

Returns:the property value.
virtual RED_RC SetBooleanValue(bool iValue, const RED::State &iState) = 0

Sets the boolean property value.

This method automatically set the property type to PYT_BOOL.

Parameters:
  • iValue – Poperty value.
  • iState – Current transaction.
Returns:

RED_OK on success,

RED_FAIL otherwise.
virtual bool GetBooleanValue() const = 0

Gets the boolean property value.

If the property type is not PYT_BOOLEAN, the returned value may be undefined.

Returns:the property value.
virtual RED_RC SetVector4(const RED::Vector4 &iVector, const RED::State &iState) = 0

Sets the property vector4.

This method automatically set the property type to PYT_VECTOR4.

Parameters:
  • iVector – Poperty vector4.
  • iState – Current transaction.
Returns:

RED_OK on success,

RED_FAIL otherwise.
virtual const RED::Vector4 &GetVector4() const = 0

Gets the property vector4.

If the property type is not PYT_VECTOR4, the returned vector may be undefined.

Returns:the property vector4.
virtual RED_RC SetLayerSet(const RED::LayerSet &iLayerSet, const RED::State &iState) = 0

Sets the property layer set.

This method automatically set the property type to PYT_LAYERSET.

Parameters:
  • iLayerSet – Poperty layer set.
  • iState – Current transaction.
Returns:

RED_OK on success,

RED_FAIL otherwise.
virtual const RED::LayerSet &GetLayerSet() const = 0

Gets the property layer set.

If the property type is not PYT_LAYERSET, the returned layer set may be undefined.

Returns:the property layer set.
virtual void SetRange(float iStart, float iEnd) = 0

Sets the definition range of the property.

If the property type is not PYT_FLOAT, the call will have no effect. The range includes iStart and iEnd values.

Parameters:
  • iStart – Starting value of the range.
  • iEnd – Ending value of the range.
virtual void SetRange(int iStart, int iEnd) = 0

Sets the definition range of the property.

If the property type is not PYT_INTEGER, the call will have no effect. The range includes iStart and iEnd values.

Parameters:
  • iStart – Starting value of the range.
  • iEnd – Ending value of the range.
virtual void GetRange(float &iStart, float &iEnd) const = 0

Gets the definition range of the property.

If the property type is not PYT_FLOAT, the returned range may be undefined.

Returns:the definition range of the property.
virtual void GetRange(int &iStart, int &iEnd) const = 0

Gets the definition range of the property.

If the property type is not PYT_INTEGER, the returned range may be undefined.

Returns:the definition range of the property.
virtual RED_RC SetTexture(const RED::Object *iTexture, const RED::String &iPath, const RED::State &iState) = 0

Sets the property texture.

This method automatically set the property type to PYT_TEXTURE2D, PYT_TEXTURE3D,

PYT_TEXTURECUBE or PYT_TEXTURECOMPOSITE according to the interface supported by iTexture.

If a previous texture was set, it is replaced by the new one (even if the new is NULL) but not deleted. If the new texture is NULL, the property type will be set to PYT_TEXTURE2D.

Parameters:
  • iTexture – Poperty texture.
  • iPath – Property texture path.
  • iState – Current transaction.
Returns:

RED_OK on success,

RED_FAIL otherwise.
virtual const RED::Object *GetTexture() const = 0
Returns:the property texture.
virtual const RED::String &GetTexturePath() const = 0

Gets the property texture path.

If the property type is not one of PYT_TEXTURE2D, PYT_TEXTURE3D, PYT_TEXTURECUBE, the returned texture path may be undefined.

Returns:the property texture path.
virtual void SetPrivate(bool iPrivate) = 0

Sets the private status of a property.

A property can be set private or not using that method. While the private status has no effect on REDsdk itself, it can be used by client application to determine if a material property should be exposed to the user or not.

Parameters:iPrivate – new private status of the property.
virtual bool IsPrivate() const = 0
Returns:true if the property is private, false otherwise.