Scene Class Reference

---

Detailed Description

The Scene object represents a Softimage scene that is loaded in memory.

You can access most of the contents of the scene using Scene::GetRoot, which returns the root Model.

The full path of the Scene is stored inside the FileName Parameter (see the example below for more details).

The scripting name of the scene is stored inside the Name Parameter

Note:

The scripting name is a valid variable name for scripting languages. It must contain only alphanumerals A-Z, a-z, 0-9, and must not begin with a numeral. Therefore, if you want to save a scene with a filename that begins with a numeral, XSI prefixes an underscore (_) to the actual filename you used.

See also:

Project, Application, Project::GetActiveScene

Example:

Demonstrates how to get the actual filename and the real name of the active scene.

        // Shortcut to application
        Application app = Application();

        // Start with a fresh scene
        CValue outArg;
        CValueArray args; args.Add( L"" ); args.Add( false );
        app.ExecuteCommand( L"NewScene", args, outArg );

        // Get the active scene as a scene object and then get its root
        Project proj = app.GetActiveProject();
        Scene scn = proj.GetActiveScene();
        Model root = scn.GetRoot();

        // Add a null and a cube to the scene root
        Null n; root.AddNull( L"Thing1", n );
        X3DObject c; root.AddGeometry( L"Cube", L"MeshSurface", L"Thing2", c );

        // Save the scene as "2Things.scn" under the projects directory
        CString sProjectsDir = app.GetInstallationPath( siProjectPath );
        args.Clear(); args.Add( sProjectsDir + L"\\2Things.scn" );
        app.ExecuteCommand( L"SaveSceneAs", args, outArg );

        // Save the actual scene name in a variable and display it
        CParameterRefArray params = scn.GetParameters();
        Parameter p = params.GetItem( L"Filename" );
        CString sRealName = p.GetValue( double(1) );
        app.LogMessage( L"My real name is " + sRealName );

        // Save the scripting name in a variable and display it
        Parameter q = params.GetItem( L"Name" );
        CString sScriptingName = q.GetValue( double(1) );
        app.LogMessage( L"My scripting name is " + sScriptingName );

        // Expected result:
        //INFO : My real name is <project location>\2Things.scn
        //INFO : My scripting name is _2Things

#include <xsi_scene.h>

Inheritance diagram for Scene:

List of all members.

Public Member Functions
	Scene ()
	~Scene ()
	Scene (const CRef &in_ref)
	Scene (const Scene &in_obj)
bool	IsA (siClassID in_ClassID) const
siClassID	GetClassID () const
Scene &	operator= (const Scene &in_obj)
Scene &	operator= (const CRef &in_ref)
Model	GetRoot () const
Property	GetColors () const
Layer	GetActiveLayer () const
Pass	GetActivePass () const
CRefArray	GetLayers () const
CRefArray	GetPasses () const
PassContainer	GetPassContainer () const
Library	GetActiveMaterialLibrary () const
CRefArray	GetMaterialLibraries () const
SimulationEnvironment	GetActiveSimulationEnvironment () const
CRefArray	GetSimulationEnvironments () const
CRefArray	GetProperties () const
CRefArray	GetExternalFiles () const
FileReference	GetExternalFileFromGUID (const CString &in_csGUID) const
CRefArray	GetImageClips () const
ImageClip2	GetDefaultImageClip ()
CRefArray	GetRenderableCameras () const
CRefArray	GetAllCacheClipsAndObjects (CString &out_csObjectNames) const

---

Constructor & Destructor Documentation

Scene

(

)

Default constructor.

~Scene

(

)

Default destructor.

Scene

(

const CRef &

in_ref

)

Constructor.

Parameters:

in_ref

constant reference object.

Scene

(

const Scene &

in_obj

)

Copy constructor.

Parameters:

in_obj

constant class object.

---

Member Function Documentation

bool IsA

(

siClassID

in_ClassID

)

const [virtual]

Returns true if a given class type is compatible with this API class.

Parameters:

in_ClassID

class type.

Returns:

true if the class is compatible, false otherwise.

Reimplemented from ProjectItem.

siClassID GetClassID

(

)

const [virtual]

Returns the type of the API class.

Returns:

The class type.

Reimplemented from ProjectItem.

Scene& operator=

(

const Scene &

in_obj

)

Creates an object from another object. The newly created object is set to empty if the input object is not compatible.

Parameters:

in_obj

constant class object.

Returns:

The new Scene object.

Scene& operator=

(

const CRef &

in_ref

)

Creates an object from a reference object. The newly created object is set to empty if the input reference object is not compatible.

Parameters:

in_ref

constant class object.

Returns:

The new Scene object.

Reimplemented from ProjectItem.

Model GetRoot

(

)

const

Returns the scene's root model (Scene_Root). The scene root is the entry point for a lot of functionality in the C++ API. For example, to add a 3D scene object you call X3DObject::AddGeometry on the scene root; to get the Mixer object you need to call Model::GetMixer on the scene root, etc.

This member is typically called from the active (or current) scene which you can get by calling Project::GetActiveScene on the active project, which is available from Application::GetActiveProject. However, there is a more direct way to access the scene root directly from the Application class which is preferable: Application.GetActiveSceneRoot.

Returns:

The scene_root Model

See also:

Project::ActiveScene, Application::GetActiveProject, Application::GetActiveSceneRoot

Property GetColors

(

)

const

Returns the Scene Colors property (found under the scene's Preferences in the UI). The Scene Colors property allows you to control the color that objects and components display in their selected, unselected, and unselectable state.

The value of each color Parameter represents an RGB value as a LONG (0 to 1023). For more details, see the explanation for how Wireframe colors are represented in the CColor documentation.

Returns:

The scene colors Property.

See also:

Preferences, CColor, Property, Property::GetParameters, Parameter

Layer GetActiveLayer

(

)

const

Returns the currently active Layer object. Layers help you organize, view, and edit the contents in your scene, but they only affect the final render if you want them to (they are not associated with render passes).

Returns:

The current Layer.

See also:

Scene::GetLayers, Layer

Since:

4.0

Pass GetActivePass

(

)

const

Returns the currently active render Pass object. A render pass creates a picture layer of a scene that can be composited with any other pass(es) to create a complete image. Passes also allow you to quickly re-render a single layer without re-rendering the entire scene.

Returns:

The current Pass.

See also:

Scene::GetPasses, Pass

Since:

4.0

CRefArray GetLayers

(

)

const

Returns an array of references to the Layer objects associated with the scene.

Returns:

Array of all Layer objects.

See also:

Scene::GetActiveLayer, Layer

Since:

4.0

CRefArray GetPasses

(

)

const

Returns an array of references to the Pass objects associated with the scene.

Returns:

Array of all Pass objects.

See also:

Scene::GetActivePass, Pass

Since:

4.0

PassContainer GetPassContainer

(

)

const

Returns the scene's pass container. The pass container contains all the passes in the scene, along with scene global render options properties.

Returns:

The PassContainer object.

See also:

PassContainer SceneRenderProperty Scene::GetActivePass Scene::GetPasses Pass

CreatePass CreatePassWithPartition GetCurrentPass SetCurrentPass DeleteCurrentPass

Since:

6.0

Library GetActiveMaterialLibrary

(

)

const

Returns the currently active MaterialLibrary. A material library is a common container for materials used in a scene. Every Material you create is added to a library. You can then assign it to one or more objects (or clusters, hierarchies, groups, partitions, and so on). This makes it easy to share a single material between multiple scene elements while having only the one material to manage.

Returns:

The current Material Library.

See also:

Scene::GetMaterialLibraries, MaterialLibrary, Material, Library

Since:

4.0

CRefArray GetMaterialLibraries

(

)

const

Returns an array of references to the MaterialLibrary objects associated with the scene. This list contains all material libraries under the Source container ("Scene.Sources").

Returns:

Array of references to all material libraries.

See also:

Scene::GetActiveMaterialLibrary, MaterialLibrary, Material, Library

Since:

4.0

SimulationEnvironment GetActiveSimulationEnvironment

(

)

const

Returns the currently active SimulationEnvironment. All elements that are part of a rigid body simulation are controlled within a simulation environment. A simulation environment is created as soon as you make an object into a rigid body. You can also create environments so that you can have multiple simulation environments in one scene.

Returns:

The current SimulationEnvironment.

See also:

Scene::GetSimulationEnvironments, SimulationEnvironment

Since:

4.2

CRefArray GetSimulationEnvironments

(

)

const

Returns an array of references to the SimulationEnvironment objects associated with the scene. This list contains all simulation environments under the Environments container ("Scene.Environments").

Returns:

Array of references to all simulation environments.

See also:

Scene::GetActiveSimulationEnvironment, SimulationEnvironment

Since:

4.2

CRefArray GetProperties

(

)

const

Returns an array of references to the properties installed on the scene.

Returns:

Array of references to the scene's Property objects

See also:

Property::GetParameters, Parameter

CRefArray GetExternalFiles

(

)

const

Returns a list of FileReference objects containing all external files related to this scene. Only input files are added to this list (for example graphics files, audio files, referenced model files, etc.).

Returns:

Array of references to FileReference objects.

See also:

Scene::GetExternalFileFromGUID, Model::GetExternalFiles, FileReference

Since:

5.0

FileReference GetExternalFileFromGUID

(

const CString &

in_csGUID

)

const

Returns the FileReference object which corresponds to the specified unique indentifier (GUID).

Note:

Only source files are in the external file list (for example, graphics files, audio files, referenced model files, etc.).

Parameters:

in_csGUID

The GUID of the object to retrieve

Returns:

The new FileReference object

See also:

Scene::GetExternalFiles, Model::GetExternalFiles, FileReference

Since:

5.0

CRefArray GetImageClips

(

)

const

Returns an array of all ImageClip2 objects associated with the scene. Image clips and their sources are always stored under the scene in the Clips ("Scene.Clips.Image") and Sources ("Scene.Sources.Image") containers.

This differs from animation clips and sources for animation which are stored under the Track, Mixer, and Model where they are used, so Scene::GetImageClips returns all image clips in the scene, whereas ClipContainer::GetClips and Track::GetClips return only clips for the specific container (mixer or track).

Returns:

Array of references to image clips.

See also:

ImageClip2, Image

Since:

5.0

ImageClip2 GetDefaultImageClip

(

)

Returns or creates an ImageClip2 object representing the default image clip.

Returns:

the default image clip

See also:

ImageClip2, Image

Since:

9.0 (2011)

CRefArray GetRenderableCameras

(

)

const

Returns an array of all cameras under the scene and additional cameras that can be rendered.

Returns:

Array of references to the cameras.

See also:

Camera

Since:

12.0 (2014)

CRefArray GetAllCacheClipsAndObjects

(

CString &

out_csObjectNames

)

const

Returns an array of all file cache clips in the scene as well as a list of object name they are applied on.

Returns:

Array of file cache clips

Since:

12.0 (2014)

---

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

• xsi_scene.h