Material Class Reference
 
 
 
Material Class Reference

This reference page is linked to from the following overview topics: Checking Return Values for Type.


#include <xsi_material.h>


Class Description

The Material object represents a material property of a SceneItem object.

You can create a material with SceneItem::AddMaterial.

Note:
If you get a material from a Material Library, use ProjectItem::GetParent, not ProjectItem::GetModel, to get the Library object (ProjectItem::GetModel returns an invalid Model).
See also:
Scene::GetActiveMaterialLibrary(), OGLMaterial
Example:
                using namespace XSI;
                Application app;
                Model root = app.GetActiveSceneRoot();

                X3DObject myCube;
                root.AddGeometry( L"Cube",L"MeshSurface",L"" ,myCube );

                Material myMaterial;
                myCube.AddMaterial(L"Phong",false,L"",myMaterial);

                app.LogMessage( CString(L"The material: ") + myMaterial.GetFullName() );
Inheritance diagram for Material:
Property ProjectItem SIObject CBase

List of all members.

Public Member Functions

  Material ()
  ~Material ()
  Material (const CRef &in_ref)
  Material (const Material &in_obj)
bool  IsA (siClassID in_ClassID) const
siClassID  GetClassID () const
Material operator= (const Material &in_obj)
Material operator= (const CRef &in_ref)
CRefArray  GetShaders () const
CRefArray  GetImageClips () const
OGLMaterial  GetOGLMaterial () const
OGLTexture  GetOGLTexture () const
ClusterProperty  GetCurrentUV () const
ImageClip  GetCurrentImageClip () const
ImageClip2  GetCurrentImageClip2 () const
Texture  GetCurrentTexture () const
TextureLayer  CreateTextureLayer (const CString &in_strName=CString(), bool in_bAfter=true, const TextureLayer &in_refLayer=TextureLayer())
CStatus  AddSharedTextureLayer (const TextureLayer &in_layer, bool in_bAfter=true, const TextureLayer &in_refLayer=TextureLayer())
CRefArray  GetTextureLayers () const
CStatus  RemoveTextureLayer (const TextureLayer &in_layer)
CRefArray  GetUsedBy () const
bool  IsResolved ()
CStatus  Resolve ()
CString  GetUnresolvedFullname () const
Library  GetLibrary () const
Property  AddProperty (const CString &in_preset, bool in_bBranch=false, const CString &in_name=CString())
CRefArray  GetProperties () const
CRefArray  GetConnectedClusterProperties (CParameterRefArray &out_refArray) const
siShaderParameterType  GetShaderInputType (const CString &in_paramscriptname) const
CRefArray  FindShaders (const CString &in_filtername) const
CRefArray  GetAllShaders () const
CRefArray  GetAllImageClips () const

Constructor & Destructor Documentation

Material ( )

Constructs a Material object.

~Material ( )

Destroys a Material object.

Material ( const CRef in_ref )

Constructs a Material object from a CRef object.

Parameters:
in_ref A reference to a material.
Material ( const Material in_obj )

Constructs a new Material object from an existing Material object.

Parameters:
in_obj An existing Material object to copy into this Material object.

Member Function Documentation

bool IsA ( siClassID  in_ClassID ) const [virtual]

Returns True if this object supports the functionality of a specified class. For example, a Material is a type of Property, so a Material object supports Property functionality.

Parameters:
in_ClassID Test if this object supports this class.
Returns:
True if this object supports the specified class, and false otherwise.

Reimplemented from Property.

siClassID GetClassID ( ) const [virtual]

Returns the class ID for this object.

Returns:
The class ID.

Reimplemented from Property.

Material& operator= ( const Material in_obj )

Assigns a Material object to an existing Material object.

Parameters:
in_obj A Material object to be copied into this object.
Returns:
The reinitialized Material object.
Material& operator= ( const CRef in_ref )

Assigns a CRef to this material. The Material object is cleared if the CRef is not a reference to an object that supports the Material class.

Parameters:
in_ref A reference to an object that supports the Material class.
Returns:
The reinitialized Material object.

Reimplemented from Property.

CRefArray GetShaders ( ) const

Returns the shaders connected to this material.

Returns:
An array of references to Shader objects.
CRefArray GetImageClips ( ) const

Returns the image clips connected to the material.

Returns:
An array of references to ImageClip objects.
Since:
4.0
OGLMaterial GetOGLMaterial ( ) const

Returns the OGLMaterial for this material. The OGLMaterial is a read-only object that holds the material rendering information used by OpenGL.

OGLTexture GetOGLTexture ( ) const

Returns the OGLTexture for this Material. The OGLTexture is a read-only object that holds the texturing information used by OpenGL.

ClusterProperty GetCurrentUV ( ) const

Returns the ClusterProperty containing the current UV coordinages used to display the texture in OpenGL.

ImageClip GetCurrentImageClip ( ) const
ImageClip2 GetCurrentImageClip2 ( ) const

Returns the current image clip used for OpenGL display.

Since:
4.0
Texture GetCurrentTexture ( ) const

Returns the texture using the default UV coordinates used in OpenGL.

TextureLayer CreateTextureLayer ( const CString in_strName = CString(),
bool  in_bAfter = true,
const TextureLayer in_refLayer = TextureLayer() 
)

Creates a new texture layer belonging to the container (the material).

Parameters:
in_strName The name of new texture layer.
in_bAfter True to insert the layer after the reference layer (in_refLayer), and False to insert the layer before the reference layer. If there is no reference layer, then True adds the layer to the end of the list, and False adds the layer to the start of the list.
in_refLayer The reference texture layer. Used to indicate where the new layer is inserted in the list.
Returns:
The new texture layer.
Since:
4.0
CStatus AddSharedTextureLayer ( const TextureLayer in_layer,
bool  in_bAfter = true,
const TextureLayer in_refLayer = TextureLayer() 
)

Adds an existing texture layer to the container. The layer already belongs to at least one other texture layer container (either a Shader or a Material).

Parameters:
in_layer The texture layer to add to this container.
in_bAfter True to insert the layer after the reference layer (in_refLayer), and False to insert the layer before the reference layer. If there is no reference layer, then True adds the layer to the end of the list, and False adds the layer to the start of the list.
in_refLayer The reference texture layer. Used to indicate where the new layer is inserted in the list.
Returns:
CStatus::OK if successful
CStatus::Fail if the texture layer could not be created.
Since:
4.0
CRefArray GetTextureLayers ( ) const

Returns the texture layers owned by the material.

Returns:
An array of references to TextureLayer objects.
Since:
4.0
CStatus RemoveTextureLayer ( const TextureLayer in_layer )

Removes a texture layer from the container. If this container is the only owner of the layer, then the layer is deleted from the scene. Otherwise, the layer is removed from this container only.

Parameters:
in_layer The texture layer to remove from this container.
Returns:
CStatus::OK if successful
CStatus::Fail if the texture layer could not be removed.
Since:
4.0
CRefArray GetUsedBy ( ) const

Returns the owners of this material.

Returns:
An array of references to the owners.
Since:
4.0
bool IsResolved ( )

Tests whether this material is the intended material or a stand-in.

Returns:
True if this material is the intended material, and False otherwise.
Since:
4.0
CStatus Resolve ( )

Attempts to reconnect to the proper material. This works only when Material::IsResolved returns False.

Returns:
CStatus::OK if successful
CStatus::Fail if the material could not be resolved.
Since:
4.0
CString GetUnresolvedFullname ( ) const

Returns the full name of the material that this material is supposed to reference.

Returns:
The fullname of the material.
Since:
4.0
Library GetLibrary ( ) const

Returns the material library that this material belongs to.

Since:
4.0
Property AddProperty ( const CString in_preset,
bool  in_bBranch = false,
const CString in_name = CString() 
)

Adds a Property to the material. For example, you can add a UserDataBlob or CustomProperty to store custom user data inside a render tree.

Parameters:
in_preset A preset name or the name of a self-installed CustomProperty.
in_bBranch Should always be false.
in_name Optional name for the new property. If no name is specified, the name is based on in_preset.
See also:
Material::GetProperties, SceneItem::AddProperty
Since:
4.0
CRefArray GetProperties ( ) const

Returns the properties applied to the material. A material may have nested CustomProperty or UserDataBlob properties.

Returns:
An array of Property objects.
See also:
Material::AddProperty, SceneItem::GetProperties
Since:
4.0
CRefArray GetConnectedClusterProperties ( CParameterRefArray out_refArray ) const

Returns an array of CustomProperty objects connected to this material shader. These cluster properties are mostly UV and Color at Vertices properties. The function also returns the shader connection points, as Parameter objects, for each cluster property.

Return values:
out_refArray Array of Parameter objects that connect the cluster properties.
Returns:
Array of Cluster Property objects.
See also:
CGeometryAccessor::GetMaterials
Since:
5.0
Example:
                using namespace XSI;

                Application app;
                Model root = app.GetActiveSceneRoot();

                X3DObject myCube;
                root.AddGeometry( L"Cube",L"MeshSurface",L"" ,myCube );

                Material myMaterial;
                myCube.AddMaterial(L"Phong",false,L"",myMaterial);

                //Adding an image
                CValueArray args(4L);
                CValue outArg;
                args[0] = CValue( CString(L"Image") );
                args[1] = CValue(myCube.GetRef());
                args[2] = CValue((short)1);
                args[3] = CValue(false);

                app.ExecuteCommand( L"BlendInPresets", args, outArg );

                //Adding a texture support
                args[0] = myCube.GetRef();
                args[1] = (LONG)siTxtPlanarXY;
                args[2] = (LONG)siTxtDefaultSpherical;
                args[3] = CString(L"Texture_Support");
                app.ExecuteCommand( L"CreateTextureSupport", args, outArg );

                //Now get the cluster properties connected to this material
                Primitive prim = myCube.GetActivePrimitive();
                PolygonMesh mesh = prim.GetGeometry();
                CGeometryAccessor mt = mesh.GetGeometryAccessor();

                CRefArray mats = mt.GetMaterials();

                LONG nVals = mats.GetCount();

                for ( LONG i=0; i<nVals; i++ )
                {
                        Material mat(mats[i]);

                        CParameterRefArray params;
                        CRefArray clsProps = mat.GetConnectedClusterProperties(params);

                        CString str(mat.GetName());

                        for (LONG j=0; j<clsProps.GetCount(); j++)
                        {
                                str += L"\n\t";

                                ClusterProperty cp(clsProps[j]);

                                str += cp.GetName();

                                str += L" type: ";
                                switch (cp.GetPropertyType())
                                {
                                        case siClusterPropertyEnvelopeWeightType:
                                                str += L"siClusterPropertyEnvelopeWeightType";
                                                break;
                                        case siClusterPropertyShapeKeyType:
                                                str += L"siClusterPropertyShapeKeyType";
                                                break;
                                        case siClusterPropertyWeightMapType:
                                                str += L"siClusterPropertyWeightMapType";
                                                break;
                                        case siClusterPropertyUVType:
                                                str += L"siClusterPropertyUVType";
                                                break;
                                        case siClusterPropertyVertexColorType:
                                                str += L"siClusterPropertyVertexColorType";
                                                break;
                                        case siClusterPropertyUserNormalType:
                                                str += L"siClusterPropertyUserNormalType";
                                                break;
                                        case siClusterPropertyUserMotionType:
                                                str += L"siClusterPropertyUserMotionType";
                                                break;
                                };

                                str += L" elem count: " + CString(cp.GetValueSize());

                                // connection point parameter
                                Parameter param = params[j];

                                str += L"\n\t\tParameter path: ";
                                str += param.GetFullName();
                                str += L"\n";

                                // show texture information
                                Texture txt(param.GetParent());
                                str += L"\t\tParameter parent: ";
                                str += txt.GetFullName();
                                str += L"\n";

                                // get the image clip filename
                                ImageClip2 clip(txt.GetImageClip());

                                str += L"\t\tTexture image: ";
                                str += clip.GetFileName();
                        }

                        app.LogMessage( CString(i) + L" : " + str );
                }
siShaderParameterType GetShaderInputType ( const CString in_paramscriptname ) const

Returns the input type of a material parameter. Before you connect a shader to the parameter, use Parameter::GetCapabilities to make sure that the parameter supports the siTexturable capability.

Parameters:
in_paramscriptname The script name of a parameter.
Returns:
The shader input type.
siUnknownParameterType if the parameter cannot be connected to a shader.
Since:
5.0
CRefArray FindShaders ( const CString in_filtername ) const

Returns all shaders that match a Filter. For example, you can write a custom filter that matches shaders with texturespace and colormap parameters, and then use this custom filter with this function.

Parameters:
in_filtername The name of a shader Filter (for example, siShaderFilter).
Returns:
Array of shaders that match the filter.
Since:
5.0
CRefArray GetAllShaders ( ) const

Returns a list of shaders nested under this Material.

Returns:
CRefArray of references to the nested Shader objects.
Since:
7.0
CRefArray GetAllImageClips ( ) const

Returns a list of the image clips nested under this Material.

Returns:
CRefArray of references to the nested ImageClip2 objects.
See also:
Light::GetAllImageClips, Camera::GetAllImageClips, Pass:GetAllImageClips, Shader::GetAllImageClips, Override::GetAllImageClips
Since:
7.0

The documentation for this class was generated from the following file: