MaxwellMayaMaterialComponent class

Description

This is the abstract base class for all material components such as layers, BSDFs, coatings etc. It allows you to set attribute values and textures by name as well as query the attributes of a given component. Accessing attributes by name can be error-prone, but is useful in certain situations, e.g. when you are writing a table-driven material translator. The subclasses also offer explicit method calls for non-texturable attributes, so you can pick whichever approach is best suited for your application. You can identify the concrete type of the underlying material component by calling the GetComponentType method.

Subclasses: MaxwellMayaReflectance, MaxwellMayaCoating, MaxwellMayaBSDF, MaxwellMayaEmitter, MaxwellMayaDisplacement,
MaxwellMayaMaterialLayer, MaxwellMayaMaterialAttrs.

MaxwellMayaTexture

MaxwellMayaTexture is a structure used by the methods ApplyTexture and GetTexture to pass or retrieve information about a Maxwell texture. It is not an API interface so it doesn't need to be managed in the same way as the other API objects. It has the following fields:

• MString file: the path to the image file. Defaults to the empty string.
• double uvScale[2]: the UV scaling (tiling) factors. Both values default to 1.
• double uvOffset[2]: the UV offsets. Both values default to 0.
• unsigned int uvSet: the index of the UV set used by the texture. Defaults to 0.
• unsigned int flags: a combination of the following flag values:
  • Flag_TileU: enable tiling on U. Defaults to on.
  • Flag_TileV: enable tiling on V. Defaults to on.
  • Flag_Invert: invert the colors. Defaults to off.
  • Flag_Filter: enable image filtering. Defaults to on.
  • Flag_UseAlpha: sample the alpha channel of the image, ignoring the color channel. Defaults to off.
  • Flag_NmapFlipX: flip the X value when the image is used as a normal map. Defaults to off.
  • Flag_NmapFlipY: flip the Y value when the image is used as a normal map. Defaults to on.
  • Flag_NmapWide: when the image is used as a normal map, this flag indicates that the blue channel is mapped in the range 0..1. When the flag is off, the blue channel is mapped to -1..1 just like the other two channels (and since negative Z values are not used, effectively only half the channel range is used). Defaults to off.
  • Flag_MapAbsolute: use absolute (or "real scale") mapping. See this page for details on this mapping mode. Defaults to off.
• float saturation: image saturation adjustment, between -1 and 1. Defaults to 0.
• float contrast: image contrast adjustment, between -1 and 1. Defaults to 0.
• float brightness: image brightness adjustment, between -1 and 1. Defaults to 0.
• float clampMin: clamp channel values to this minimum. The range is 0 to 1. Defaults to 0.
• float clampMax: clamp channel values to this maximum. The range is 0 to 1. Defaults to 1.

The Python API uses a dictionary instead of this structure. The keys of the dictionary have the same names as the fields of the C++ structure. The array members (uvScale and uvOffset) are 2-tuples. If you pass an incomplete dictionary to ApplyTexture, the missing fields will be considered to have default values.

Methods

ComponentType GetComponentType() const

Returns the concrete type of the underlying material component as one of:

• ComponentType_MaterialAttrs: general material attributes. The object can be cast to MaxwellMayaMaterialAttrs.
• ComponentType_Layer: material layer. The object can be cast to MaxwellMayaMaterialLayer.
• ComponentType_Emitter: emitter. The object can be cast to MaxwellMayaEmitter.
• ComponentType_Displacement: displacement component. The object can be cast to MaxwellMayaDisplacement.
• ComponentType_Reflectance: reflectance component for a BSDF or coating. The object can be cast to MaxwellMayaReflectance.
• ComponentType_BSDF: BSDF. The object can be cast to MaxwellMayaBSDF.
• ComponentType_Coating: coating. The object can be cast to MaxwellMayaCoating class.

MStringArray GetAttributeNames() const

Returns an array of attribute names which are defined for the component. The Python version returns a regular list of strings.

bool HasAttribute(const MString& name) const

Allows you to check if the given name is a valid attribute for this component.

AttrType GetAttributeType(const MString& name) const

Returns the type for the given attribute as one of:

• AttrType_Bool: boolean.
• AttrType_Int: integer.
• AttrType_Double: floating point.
• AttrType_Color: color (3 floating point values).
• AttrType_String: string.

If the attribute does not exist, the C++ version returns -1, while the Python version raises maxwell.ParameterError.

bool IsTexturable(const MString& name) const

Allows you to check if you can apply a texture on the given attribute. The Python version raises maxwell.ParameterError if the attribute does not exist.

bool SetAttribute(const MString& name, double val)
bool SetAttribute(const MString& name, int val)
bool SetAttribute(const MString& name, bool val)
bool SetAttribute(const MString& name, const MFloatVector& val)
bool SetAttribute(const MString& name, const MString& val)

Set the value of an attribute. These methods do not attempt to perform type conversions in C++, so you must make sure you're calling the overload which is appropriate for the attribute you're trying to set. For example, calling SetAttribute("iorNd", 3) on a reflectance component will fail because it invokes the integer overload, while the iorNd attribute is floating point; use SetAttribute("iorNd", 3.0) instead. The Python version is a little more permissive: it allows you to pass an integer for a floating point attribute, but doesn't try to perform any other conversions. The C++ version will return false if the attribute does not exist or is of the wrong type, while the Python version will raise maxwell.ParameterError.

bool GetAttribute(const MString& name, double& val) const
bool GetAttribute(const MString& name, int& val) const
bool GetAttribute(const MString& name, bool& val) const
bool GetAttribute(const MString& name, MFloatVector& val) const
bool GetAttribute(const MString& name, MString& val) const

Retrieve the value of an attribute. The C++ methods return false if the attribute does not exist or if the type does not match the overload which was called. The Python version returns an object of the appropriate type, or raises maxwell.ParameterError if the attribute does not exist.

bool ApplyTexture(const MString& attributeName, const MaxwellMayaTexture& texture)

Applies the given texture on an attribute. If the attribute does not exist, the method returns false in C++ and raises maxwell.ParameterError in Python. The Python version removes the texture from the attribute if the texture argument is None.

bool RemoveTexture(const MString& attributeName)

Removes the texture from the specified attribute. This method does not exist in Python, where you can call ApplyTexture with None as the second argument to remove a texture from an attribute.

bool IsTextured(const MString& attributeName) const

Allows you to check if a texture is currently applied on the given attribute. This method does not exist in Python, where you can check if GetTexture returns None to see if a texture is present.

bool GetTexture(const MString& attributeName, MaxwellMayaTexture& texture) const

Retrieves the texture currently applied on an attribute. The C++ version returns false if the attribute does not exist or is not textured (or texturable). The Python version takes only the first argument and returns the texture object if a texture is present, or None. If the attribute does not exist or is not texturable, it raises maxwell.ParameterError.

static const char* GetAttrTypeName(AttrType type)

Returns a human-readable name for the given attribute type code.