Detailed Description

A library is a container of objects of the same type. For example, a material library contains a list of materials.

Library 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 library is the Scene object.

See also:: Scene::GetActiveMaterialLibrary

Since:: 4.0

Example:: Shows how to get the parameter values from a shared material. Parameters on a shared material have instance-specific values for each object sharing the material. This applies to the ImageShader.tspace_id, Material.ImageClipName, Material.UV, and Material.CAV parameters.

Note:: You need to define the CreateProjection and CreateImageClip commands as functions using the source code from the cmdstub.cpp example.

        CStatus st;
        Application app;

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

        Model root = scene.GetRoot();

        // Create a cube with a texture projection (not connected)
        X3DObject cube; st = root.AddGeometry( L"Cube", L"MeshSurface", L"MyCubeWithTexture", cube );

        // Create a projection for the cube
        CreateProjection(
            cube.GetRef(),
            siTxtCubic,
            siTxtDefaultCubic ,
            L"MyCubicTextureSupport",
            L"MyCubicTextureProjection" );

        // Create a sphere with a texture projection (not connected)
        X3DObject sphere; st = root.AddGeometry( L"Sphere", L"MeshSurface", L"MySphereWithTexture", sphere );

        // Create a projection for the sphere
        CreateProjection(
            sphere.GetRef(),
            siTxtSpherical,
            siTxtDefaultSpherical,
            L"MySphericalTextureSupport",
            L"MySphericalTextureProjection" );

        // Create a group with a material hooked up to a texture image
        CRefArray objs;

        objs.Add( cube );
        objs.Add( sphere );

        Group group; st = root.AddGroup( objs, L"MyGroup", false, group );

        Material mat; st = group.AddMaterial(L"Phong", false, L"MyGroupMaterialWithTexture", mat );

        CRefArray shaders = mat.GetShaders();

        Shader phong = shaders[0];

        Parameter ambient = phong.GetParameter(L"ambient");
        Parameter diffuse = phong.GetParameter(L"diffuse");

        // Create an image clip
        CString strFileName = app.GetInstallationPath( siFactoryPath ) + L"\\Data\\XSI_SAMPLES\\Pictures\\xsilogo.jpg";

        CRef imageclip = CreateImageClip( strFileName, L"MyImageClip" );

        // Connect the imageclip to phong.ambient
        CRef prevsrc, src;

        st = ambient.ConnectFromPreset( L"Image", siTextureShaderFamily, prevsrc, src );

        Shader imageshader = src;

        // Connect the imageclip to phong.diffuse
        st = diffuse.Connect( imageshader, prevsrc ) ;

        // Connect image.tex to imageclip
        Parameter tex = imageshader.GetParameter(L"tex");
        st = tex.Connect( imageclip, prevsrc );

        // Get tspace_id
        Parameter tspace_id = imageshader.GetParameter( L"tspace_id" );

        // Set cube.material.image.tspace_id = MyCubicTextureProjection
        st = tspace_id.PutInstanceValue(cube, L"MyCubicTextureProjection");

        // Set sphere.material.image.tspace_id = MySphericalTextureProjection
        st = tspace_id.PutInstanceValue(sphere, L"MySphericalTextureProjection");

        // Dump the tspace ids for objects found using materials
        // from material library
        Library lib = scene.GetActiveMaterialLibrary();

        CRefArray mat_refs = lib.GetItems();

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

            CRefArray ref_illum_shaders = mat.GetShaders();

            if ( ref_illum_shaders.GetCount() == 0  ) continue;

            Shader illum_shader =   ref_illum_shaders[0];
            CRefArray ref_image_shaders = illum_shader.GetShaders();

            Shader image = ref_image_shaders[0];

            CRefArray param_refs = image.GetParameters();

            for ( LONG j=0; i < param_refs.GetCount(); i++ )
            {
                 Parameter image_param( param_refs[i] );

                 // If the parameter is an instance value look up
                 // its object value
                 if ( image_param.HasInstanceValue() )
                 {
                        CRefArray owner_refs = mat.GetOwners();

                        for ( LONG k=0; k < owner_refs.GetCount(); k++ )
                        {
                            CRef owner_ref = owner_refs[k];

                            if ( owner_ref == lib ) continue;

                            if ( owner_ref.IsA( siGroupID ) )
                            {
                                Group group = owner_ref;

                                // Log the complete path to the parameter under the object that uses the material
                                // with an instance value.
                                app.LogMessage( image_param.GetFullName() + L" = " + image_param.GetValue().GetAsText()  );

                                CRefArray members = group.GetMembers();

                                for ( LONG l=0; l < members.GetCount(); l++ )
                                {
                                    SceneItem sceneitem = members[l];

                                    CValue val = image_param.GetInstanceValue( members[l] );

                                    // Log complete path to parameter under object that uses material
                                    // with instance value.
                                    app.LogMessage( sceneitem.GetFullName() + L" " + image_param.GetName() + L" = " + val.GetAsText()  );
                                }
                            }
                            else
                            {
                                CValue val = image_param.GetInstanceValue( owner_ref );

                                // Log complete path to parameter under object that uses material
                                // with instance value.
                                app.LogMessage( image_param.GetName() + L" = " + val.GetAsText()  );
                            }
                        }
                 }
            }
        }

#include <xsi_library.h>

Inheritance diagram for Library:

[legend]

List of all members.

Public Member Functions
	Library ()
	~Library ()
	Library (const CRef &in_ref)
	Library (const Library &in_obj)
bool	IsA (siClassID in_ClassID) const
siClassID	GetClassID () const
Library &	operator= (const Library &in_obj)
Library &	operator= (const CRef &in_ref)
CRefArray	GetItems () const

Constructor & Destructor Documentation

Library ( )

Constructs a Library object.

~Library ( )

Destroys a Library object.

Library ( const CRef & in_ref )

Constructs a Library object from a CRef object.

Parameters:

in_ref A reference to a library.

Library ( const Library & in_obj )

Constructs a new Library object from an existing Library object.

Parameters:

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

Reimplemented in MaterialLibrary.

siClassID GetClassID ( ) const [virtual]

Returns the class ID for this object.

Returns:: The class ID.

Reimplemented from Source.

Reimplemented in MaterialLibrary.

Library& operator= ( const Library & in_obj )

Assigns a Library object to an existing Library object.

Parameters:

in_obj A Library object to be copied into this object.

Returns:: The reinitialized Library object.

Library& operator= ( const CRef & in_ref )

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

Parameters:

in_ref A reference to an object that supports the Library class.

Returns:: The reinitialized Library object.

Reimplemented from Source.

Reimplemented in MaterialLibrary.

CRefArray GetItems ( ) const

Returns an array of the ProjectItem objects in this library.

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

xsi_library.h

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation