XSI::MaterialLibrary

MaterialLibrary Class Reference

Related Scripting Object: MaterialLibrary

The material library object is a specialized source library for storing and sharing materials. More...

#include <xsi_materiallibrary.h>

Inheritance diagram for MaterialLibrary:

Library Source ProjectItem SIObject CBase List of all members.

Public Member Functions
  MaterialLibrary ()
  ~MaterialLibrary ()
  MaterialLibrary (const CRef &in_ref)
  MaterialLibrary (const MaterialLibrary &in_obj)
bool  IsA (siClassID in_ClassID) const
siClassID  GetClassID () const
MaterialLibrary &  operator= (const MaterialLibrary &in_obj)
MaterialLibrary &  operator= (const CRef &in_ref)
CRef  CreateMaterial (const CString &in_strPreset=CString(), const CString &in_strName=CString())

Detailed Description

The material library object is a specialized source library for storing and sharing materials.

The storage may be internal or external. If internal, the library is saved in the scene file. If external, the library is saved in a separate file. The library can be exported to and imported from dotXSI or a native binary format.

Note:
The parent of a material library is the Scene object.
See also:
Scene::GetActiveMaterialLibrary()

Library

Since:
5.0
Example: 
        using namespace XSI;

        Application app;
        Scene scene = app.GetActiveProject().GetActiveScene();

        MaterialLibrary matlib = scene.GetActiveMaterialLibrary();

        Material newPhongMat = matlib.CreateMaterial(L"Phong", L"MyNewPhong" );

        CRefArray materials = matlib.GetItems();

        for ( LONG i=0; i < materials.GetCount(); i++ )
        {
            Material mat( materials[i] );

            if (mat == newPhongMat)
            {
                // found the new mat
                app.LogMessage( L"Found My New Phong Material: " + newPhongMat.GetName() );
            }
        }

Constructor & Destructor Documentation

MaterialLibrary (  ) 

Constructs a MaterialLibrary object.

~MaterialLibrary (  ) 

Destroys a MaterialLibrary object.

MaterialLibrary ( const CRef &  in_ref  ) 

Constructs a MaterialLibrary object from a CRef object.

Parameters:
in_ref  A reference to a library.

MaterialLibrary ( const MaterialLibrary &  in_obj  ) 

Constructs a new MaterialLibrary object from an existing MaterialLibrary object.

Parameters:
in_obj  An existing MaterialLibrary object to copy into this MaterialLibrary 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 MaterialLibrary is a type of Source, so a MaterialLibrary object supports Source 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 Library.

siClassID GetClassID (  )  const [virtual]

Gets the class ID for this object.

Returns:
The class ID.

Reimplemented from Library.

MaterialLibrary& operator= ( const MaterialLibrary &  in_obj  ) 

Assigns a MaterialLibrary object to an existing MaterialLibrary object.

Parameters:
in_obj  A MaterialLibrary object to be copied into this object.
Returns:
The reinitialized MaterialLibrary object.

MaterialLibrary& operator= ( const CRef &  in_ref  ) 

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

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

Reimplemented from Library.

CRef CreateMaterial ( const CString &  in_strPreset = CString(),
const CString &  in_strName = CString()  
)

Creates and adds a Material to the material library. The newly created material is not attached to any object.

Parameters:
in_strPreset  Name of a shader preset to apply to object. If the name is empty, the material is still created and added but it will have no shaders connected to its parameters.
in_strName  Name of the new Material object.
Returns:
CRef The newly created Material object.
Since:
5.0
Example: 
        using namespace XSI;

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

        // Create a 2x2 grid w the mesh builder and assign a new material created in
        // the current material library
        X3DObject myObj;
        CMeshBuilder msBuilder;
        root.AddPolygonMesh( L"myObj", myObj, msBuilder );

        // Add vertices to mesh
        double myVertexPositionArray[27] =
        {
            -4, 0, -4,
            -4, 0,  0,
            -4, 0,  4,
             0, 0, -4,
             0, 0,  0,
             0, 0,  4,
             4, 0, -4,
             4, 0,  0,
             4, 0,  4
        };

        msBuilder.AddVertices( 9, myVertexPositionArray );

        // Appends polygons to mesh
        LONG pPolyVertexCounts[4] = {4,4,4,4};
        LONG pVtxIndices[16] =
        {
            0, 1, 4, 3,
            1, 2, 5, 4,
            3, 4, 7, 6,
            4, 5, 8, 7
        };

        msBuilder.AddPolygons( 4, pPolyVertexCounts, pVtxIndices );

        // Generate the new mesh
        msBuilder.Build(false);

        // Set polygon 1 and 3 with a new phong material created in the
        // current material library
        Scene scene = app.GetActiveProject().GetActiveScene();
        MaterialLibrary matlib = scene.GetActiveMaterialLibrary();
        Material myPhongMat = matlib.CreateMaterial(L"Phong", L"MyNewPhong" );

        LONG myPolys[2] = {1,3};
        msBuilder.SetPolygonsMaterial( myPhongMat, 2, myPolys );

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