Scene Class Reference
 
 
 
Scene Class Reference

This reference page is linked to from the following overview topics: Softimage 2014, Rendering Images.


#include <xsi_scene.h>


Class 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
Inheritance diagram for Scene:
ProjectItem SIObject CBase

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: