Class Scene

A Scene object represents a UsdStage and enables USD serialization and deserialization.

Inheritance

Object

Scene

Inherited Members

Object.Equals(Object)

Object.Equals(Object, Object)

Object.ReferenceEquals(Object, Object)

Object.GetHashCode()

Object.GetType()

Object.MemberwiseClone()

Namespace: USD.NET

Syntax

public class Scene

Properties

AccessMask

When non-null, limits the members which the scene will read during serialization.

Declaration

public AccessMask AccessMask { get; set; }

Property Value

Type	Description
AccessMask

AllMeshes

Declaration

[Obsolete("Use Find<MeshSample>() instead. This API will be removed in a future release.")]
public SdfPath[] AllMeshes { get; }

Property Value

Type	Description
SdfPath[]

AllPaths

A list of all Prim paths present in the scene.

Declaration

public SdfPath[] AllPaths { get; }

Property Value

Type	Description
SdfPath[]

AllXforms

Declaration

[Obsolete("Use Find<XformableSample>() instead. This API will be removed in a future release.")]
public SdfPath[] AllXforms { get; }

Property Value

Type	Description
SdfPath[]

EndTime

The closing bracket at which animation ends, the time of the last key frame.

Declaration

public double EndTime { get; set; }

Property Value

Type	Description
Double

FilePath

Returns the root layer identifier upon which this scene is operating (the EditTarget identifier). Note that for in-memory layers, this may not be a path on disk.

Declaration

public string FilePath { get; }

Property Value

Type	Description
String

FrameRate

The rate at which the cache should playback, in frames per second.

Declaration

public double FrameRate { get; set; }

Property Value

Type	Description
Double

IsPopulatingAccessMask

When true, populates the AccessMask with with values which vary over time.

Declaration

public bool IsPopulatingAccessMask { get; set; }

Property Value

Type	Description
Boolean

Remarks

Usage: Set a valid AccessMaks, set the value to true, read all prims, set to false. Subsequent reads will only include prims from this set which vary over time.

MetersPerUnit

The linear meters per unit of the world contained in the cache. The fallback value if not authored is centimeters.

Declaration

public double MetersPerUnit { get; set; }

Property Value

Type	Description
Double

Stage

Gets the underlying UsdStage for this scene, if available.

Declaration

public UsdStage Stage { get; }

Property Value

Type	Description
UsdStage

Remarks

This is exposed only for low level, direct access to the underlying stage, not intended for common use.

StartTime

The beginning bracket at which animation begins, the time of the first key frame.

Declaration

public double StartTime { get; set; }

Property Value

Type	Description
Double

Time

Declaration

public double? Time { get; set; }

Property Value

Type	Description
Nullable<Double>

UpAxis

The Up-axis of the world contained in the cache.

Declaration

public Scene.UpAxes UpAxis { get; set; }

Property Value

Type	Description
Scene.UpAxes

WriteMode

Dicatates how calls to Write() are handled. When set to Define (the default), every write will ensure the prim is also defined.

Declaration

public Scene.WriteModes WriteMode { get; set; }

Property Value

Type	Description
Scene.WriteModes

Methods

AddSubLayer(Scene)

Adds the root layer of given Scene object as a sublayer of this Scene. Note that this operation triggers recomposition and will invalidate UsdPrim instances.

Declaration

public void AddSubLayer(Scene over)

Parameters

Type	Name	Description
Scene	over

Close()

Release any open files and stop asynchronous execution.

Declaration

public void Close()

ComputeKeyFrames(String, String)

Retuns a dictionary of paths and the times at which each path has a keyframe for the given attribute. Only paths rooted under the given rootPath are considered.

Declaration

public Dictionary<string, double[]> ComputeKeyFrames(string rootPath, string attribute)

Parameters

Type	Name	Description
String	rootPath
String	attribute

Returns

Type	Description
Dictionary<String, Double[]>

Create()

Constructs a new scene in memory, not backed by a file.

Declaration

public static Scene Create()

Returns

Type	Description
Scene

Remarks

Note that SaveAs can be used to write memory to disk.

Create(String)

Constructs a new scene at the given file path. If the file exists, it is erased, if the file is in use or cannot be created, an exception is thrown.

Declaration

public static Scene Create(string filePath)

Parameters

Type	Name	Description
String	filePath

Returns

Type	Description
Scene

Find(String, String)

Searches the USD Stage to find prims which either match the schema type name or those which are derived from it.

Declaration

public SdfPath[] Find(string rootPath, string usdSchemaTypeName)

Parameters

Type	Name	Description
String	rootPath
String	usdSchemaTypeName	The USD schema type name (e.g. UsdGeomMesh) or its alias (e.g. Mesh).

Returns

Type	Description
SdfPath[]	Returns an iterable collection of UsdPrim paths.

Find<T>()

Searches the USD Stage to find prims which either match the schema type name declared for the given sample type, or those which derive from it.

Declaration

public SdfPath[] Find<T>()
    where T : SampleBase, new()

Returns

Type	Description
SdfPath[]	An iterable collection of the paths discovered

Type Parameters

Name	Description
T	A type which inherits from SampleBase, adorned with a UsdSchemaAttribute.

Find<T>(SdfPath)

Searches the USD Stage to find prims which either match the schema type name declared for the given sample type, or those which derive from it.

Declaration

public SdfPath[] Find<T>(SdfPath rootPath)
    where T : SampleBase, new()

Parameters

Type	Name	Description
SdfPath	rootPath	The root path at which to begin the search.

Returns

Type	Description
SdfPath[]	An iterable collection of the paths discovered

Type Parameters

Name	Description
T	A type which inherits from SampleBase, adorned with a UsdSchemaAttribute.

Find<T>(String)

Searches the USD Stage to find prims which either match the schema type name declared for the given sample type, or those which derive from it.

Declaration

public SdfPath[] Find<T>(string rootPath)
    where T : SampleBase, new()

Parameters

Type	Name	Description
String	rootPath	The root path at which to begin the search.

Returns

Type	Description
SdfPath[]	An iterable collection of the paths discovered

Type Parameters

Name	Description
T	A type which inherits from SampleBase, adorned with a UsdSchemaAttribute.

FlattenAs(String)

Writes the current scene to the given file path, flattening all references.

Declaration

public void FlattenAs(string filePath)

Parameters

Type	Name	Description
String	filePath

Remarks

The resulting scene will have no external file references and all referenced data will be inlined.

GetAttributeAtPath(String)

Gets the UsdAttribute at the given path, retuns null if the UsdAttribute is invalid. Therefore, if the return value is not null, IsValid need not be checked.

Declaration

public UsdAttribute GetAttributeAtPath(string attrPath)

Parameters

Type	Name	Description
String	attrPath

Returns

Type	Description
UsdAttribute

GetPrimAtPath(String)

Gets the UsdPrim at the given path, retuns null if the UsdPrim is invalid. Therefore, if the return value is not null, IsValid need not be checked.

Declaration

public UsdPrim GetPrimAtPath(string primPath)

Parameters

Type	Name	Description
String	primPath

Returns

Type	Description
UsdPrim

GetRelationshipAtPath(String)

Gets the UsdRelationship at the given path, retuns null if the UsdRelationship is invalid. Therefore, if the return value is not null, IsValid need not be checked.

Declaration

public UsdRelationship GetRelationshipAtPath(string relPath)

Parameters

Type	Name	Description
String	relPath

Returns

Type	Description
UsdRelationship

GetSdfPath(String)

Translates the given string into an SdfPath, returning a cached value if possible.

Declaration

public SdfPath GetSdfPath(string path)

Parameters

Type	Name	Description
String	path

Returns

Type	Description
SdfPath

Open(UsdStage)

Constructs a scene from an existing stage.

Declaration

public static Scene Open(UsdStage stage)

Parameters

Type	Name	Description
UsdStage	stage

Returns

Type	Description
Scene

Open(String)

Opens an existing USD file for reading. An exception is thrown if the filePath cannot be opened.

Declaration

public static Scene Open(string filePath)

Parameters

Type	Name	Description
String	filePath

Returns

Type	Description
Scene

Read<T>(SdfPath, T)

Declaration

public void Read<T>(SdfPath path, T sample)
    where T : SampleBase

Parameters

Type	Name	Description
SdfPath	path
T	sample

Type Parameters

Name	Description
T

Read<T>(SdfPath, FieldInfo, ref T)

Declaration

public void Read<T>(SdfPath path, FieldInfo fieldInfo, ref T memberValue)

Parameters

Type	Name	Description
SdfPath	path
FieldInfo	fieldInfo
T	memberValue

Type Parameters

Name	Description
T

Read<T>(SdfPath, PropertyInfo, ref T)

Declaration

public void Read<T>(SdfPath path, PropertyInfo propInfo, ref T memberValue)

Parameters

Type	Name	Description
SdfPath	path
PropertyInfo	propInfo
T	memberValue

Type Parameters

Name	Description
T

Read<T>(String, T)

Reads and deserializes an object of type T at the given path in the current USD scene.

Declaration

public void Read<T>(string path, T sample)
    where T : SampleBase

Parameters

Type	Name	Description
String	path
T	sample

Type Parameters

Name	Description
T

Remarks

If reading fails, an excpetion is thrown and the object may be left in an incomplete state.

Read<T>(String, FieldInfo, ref T)

Reads a single field of a sample, attribute ecorations are respected.

Declaration

public void Read<T>(string path, FieldInfo fieldInfo, ref T memberValue)

Parameters

Type	Name	Description
String	path
FieldInfo	fieldInfo
T	memberValue

Type Parameters

Name	Description
T

Remarks

Note only one level of nesting is supported, e.g. if a sample has a nested structure, only immediate child structures of the root may be deserialized.

Read<T>(String, PropertyInfo, ref T)

Reads a single property of a sample, attribute decorations are respected.

Declaration

public void Read<T>(string path, PropertyInfo fieldInfo, ref T memberValue)

Parameters

Type	Name	Description
String	path
PropertyInfo	fieldInfo
T	memberValue

Type Parameters

Name	Description
T

Remarks

Note only one level of nesting is supported, e.g. if a sample has a nested structure, only immediate child structures of the root may be deserialized.

ReadAll<T>()

Searches the USD Stage to find prims which either match the schema type name or those which are derived from it.

Declaration

public SampleCollection<T> ReadAll<T>()
    where T : SampleBase, new()

Returns

Type	Description
SampleCollection<T>	Returns a collection which will read each prim found and return the requested SampleBase object type.

Type Parameters

Name	Description
T	A type which inherits from SampleBase, adorned with a UsdSchemaAttribute.

Remarks

Internally, this method reuses a single object while reading to minimize garbage generated during iteration.

ReadAll<T>(SdfPath)

Searches the USD Stage to find prims which either match the schema type name or those which are derived from it.

Declaration

public SampleCollection<T> ReadAll<T>(SdfPath rootPath)
    where T : SampleBase, new()

Parameters

Type	Name	Description
SdfPath	rootPath	The root path at which to begin the search.

Returns

Type	Description
SampleCollection<T>	Returns a collection which will read each prim found and return the requested SampleBase object type.

Type Parameters

Name	Description
T	A type which inherits from SampleBase, adorned with a UsdSchemaAttribute.

Remarks

Internally, this method reuses a single object while reading to minimize garbage generated during iteration.

ReadAll<T>(SdfPath[])

At each path, reads the given sample type from t he USD Stage.

Declaration

public SampleCollection<T> ReadAll<T>(SdfPath[] paths)
    where T : SampleBase, new()

Parameters

Type	Name	Description
SdfPath[]	paths

Returns

Type	Description
SampleCollection<T>	Returns a collection which will read each prim found and return the requested SampleBase object type.

Type Parameters

Name	Description
T	A type which inherits from SampleBase, adorned with a UsdSchemaAttribute.

ReadAll<T>(String)

Searches the USD Stage to find prims which either match the schema type name or those which are derived from it.

Declaration

public SampleCollection<T> ReadAll<T>(string rootPath)
    where T : SampleBase, new()

Parameters

Type	Name	Description
String	rootPath	The root path at which to begin the search.

Returns

Type	Description
SampleCollection<T>	Returns a collection which will read each prim found and return the requested SampleBase object type.

Type Parameters

Name	Description
T	A type which inherits from SampleBase, adorned with a UsdSchemaAttribute.

Remarks

Internally, this method reuses a single object while reading to minimize garbage generated during iteration.

Save()

Saves the current scene if backed by a file, throws an exception if this scene is in memory only.

Declaration

public void Save()

SaveAs(String)

Write the root layer of the current scene to the given file path, preserving all references.

Declaration

public void SaveAs(string filePath)

Parameters

Type	Name	Description
String	filePath

SetEditTarget(Scene)

Set the layer to which this scene will author when writing values.

Declaration

public void SetEditTarget(Scene other)

Parameters

Type	Name	Description
Scene	other

SetInterpolation(Scene.InterpolationMode)

Sets the active interpolation mode.

Declaration

public void SetInterpolation(Scene.InterpolationMode mode)

Parameters

Type	Name	Description
Scene.InterpolationMode	mode

ToString()

Returns the entire scene serialized as a string. Expensive for large scenes.

Declaration

public override string ToString()

Returns

Type	Description
String

Overrides

Object.ToString()

Write<T>(SdfPath, T)

Declaration

public void Write<T>(SdfPath path, T sample)
    where T : SampleBase

Parameters

Type	Name	Description
SdfPath	path
T	sample

Type Parameters

Name	Description
T

Write<T>(String, T)

Writes an object of type T to the given path in the current USD scene.

Declaration

public void Write<T>(string path, T sample)
    where T : SampleBase

Parameters

Type	Name	Description
String	path
T	sample

Type Parameters

Name	Description
T

Remarks

If writing fails, the scene description may be partially written.