A 3D scene composed from one or more Universal Scene Description (USD) documents.
Stages support authoring, animating, and composing 3D data from various
3D file formats. A stage can contain meshes, materials, cameras, lights, or
arbitrary custom data, as well as references to textures or additional scene
data stored in separate files.
A stage is a scene graph formed by opening a single document (the "root
layer") and then recursively following the composition rules described by
that document in order to assemble a scene graph. Because of this
composition process, a `USDStage` object presents a unified view that may
incorporate data from more than one source file.
A `USDStage` object is a mutable view onto the composed scene graph. It
consists of a tree-structured hierarchy of ``USDPrim`` objects representing
nodes in the scene graph. Each prim has schemas that give it a kind (is-a)
and capabilities (has-a), attributes that contain possibly-animated values,
and relationships that connect the prim to other objects in the stage.
The ``USDPrim``, ``USDPrim.Attribute``, and ``USDPrim.Relationship`` objects in a
stage are owned by the `USDStage` object. Values of these types act as views
or handles into the composed content of the stage. Modifying any value in a
stage authors a modification to an ``USDLayer`` that represents a file or
file-like storage. Values of these types refer to and act on the current
state of a particular stage, and become invalid if the stage is closed.
> Note: A stage may also possess a "session layer" that may contain
temporary modifications that will not be written to any file.
Defines a prim at a given path, if none already exists.
If a prim already exists at the given path, and that prim's type is
empty or equal to `type`, this function returns that prim. Otherwise,
the prim authored by this function will be an ``USDPrim/Specifier/def`` prim
with the given type.
- Parameters:
- path: An absolute path in this stage.
- type: The type name of the prim to define.
> Note: This function will also author any missing parent prims along
the given `path`. Prims authored this way will have an empty type.
get · iOS 27.0+
editTarget
TypeScript
get editTarget(): USDStage_EditTarget
Swift declaration
var editTarget: USDStage.EditTarget { get nonmutating set }
The destination for authoring operations on this stage.
set · iOS 27.0+
editTarget
TypeScript
set editTarget(value: USDStage_EditTarget)
Swift declaration
var editTarget: USDStage.EditTarget { get nonmutating set }
The destination for authoring operations on this stage.
get · iOS 27.0+
pseudoRoot
TypeScript
get pseudoRoot(): USDPrim
Swift declaration
var pseudoRoot: USDPrim { get }
The prim at the top of the stage's namespace, whose path is `/`.
Removes all authored data at the given path in the current edit target.
get · iOS 27.0+
defaultPrim
TypeScript
get defaultPrim(): (USDPrim) | null
Swift declaration
var defaultPrim: USDPrim? { get nonmutating set }
The prim designated as this stage's default entry point when the stage is referenced.
> Note: This property can be `nil` even if ``hasDefaultPrim`` is true.
This indicates that there is an authored reference to a default prim,
but it is invalid.
set · iOS 27.0+
defaultPrim
TypeScript
set defaultPrim(value: (USDPrim) | null)
Swift declaration
var defaultPrim: USDPrim? { get nonmutating set }
The prim designated as this stage's default entry point when the stage is referenced.
> Note: This property can be `nil` even if ``hasDefaultPrim`` is true.
This indicates that there is an authored reference to a default prim,
but it is invalid.
Creates a new memory-backed stage.
This is analogous to creating an anonymous ``USDLayer``.
method · iOS 27.0+
unmuteLayer
TypeScript
unmuteLayer(identifier: string): void
Swift declaration
func unmuteLayer(_ identifier: String)
Unmutes the layer with the given identifier, restoring its opinions to composition.
- Parameter identifier: The identifier of the layer to unmute.
method · iOS 27.0+
isLayerMuted
TypeScript
isLayerMuted(identifier: string): boolean
Swift declaration
func isLayerMuted(_ identifier: String) -> Bool
Returns a Boolean value that indicates whether the layer with the given identifier is muted.
- Parameter identifier: The identifier of the layer to query.
- Returns: `true` if the layer is muted; otherwise, `false`.
Authors an override prim at a given path, if no prim exists at that path.
If a prim already exists at the given path, this function returns that
prim. If no prim exists at that path, the prim authored by this function
will be an ``USDPrim/Specifier/over`` prim with no authored type.
> Note: Attributes on override prims change the values of attributes
on regular `def` prims underneath them in the layer stack.
Packages the stage into a USDZ archive.
The stage and its referenced assets are bundled into a USDZ file.
Layer structure is preserved — this operation does not flatten.
Throws an error if the extension is not `.usdz`.
func exportPackage(options: USDStage.ExportOptions = []) throws -> Data
Packages the stage into a USDZ archive and returns it as in-memory data.
The stage and its referenced assets are bundled into a USDZ archive in memory.
Layer structure is preserved - this operation does not flatten.
get · iOS 27.0+
metersPerUnit
TypeScript
get metersPerUnit(): number
Swift declaration
var metersPerUnit: Double { get nonmutating set }
The number of meters represented by one unit in this stage's
coordinate system.
set · iOS 27.0+
metersPerUnit
TypeScript
set metersPerUnit(value: number)
Swift declaration
var metersPerUnit: Double { get nonmutating set }
The number of meters represented by one unit in this stage's
coordinate system.
get · iOS 27.0+
timeCodeRange
TypeScript
get timeCodeRange(): SDKHandle
Swift declaration
var timeCodeRange: ClosedRange<USDStage.TimeCode> { get nonmutating set }
The range of time codes over which this stage has authored animation.
set · iOS 27.0+
timeCodeRange
TypeScript
set timeCodeRange(value: SDKHandle)
Swift declaration
var timeCodeRange: ClosedRange<USDStage.TimeCode> { get nonmutating set }
The range of time codes over which this stage has authored animation.
get · iOS 27.0+
allDescendants
TypeScript
get allDescendants(): Array<USDPrim>
Swift declaration
var allDescendants: [USDPrim] { get }
All descendant prims of this stage's pseudo-root.
get · iOS 27.0+
fallbackUpAxis
TypeScript
static get fallbackUpAxis(): USDToken
Swift declaration
static var fallbackUpAxis: USDToken { get }
The up axis used when a stage has no authored opinion.
get · iOS 27.0+
hasDefaultPrim
TypeScript
get hasDefaultPrim(): boolean
Swift declaration
var hasDefaultPrim: Bool { get }
Return true if this stage's root layer has an authored opinion for the
default prim layer metadata.
> Note: This function only consults the stage's root layer. To consult
a different layer, use ``USDLayer/defaultPrim``.
method · iOS 27.0+
exportFlattened
TypeScript
exportFlattenedTo(url: string): void
Swift declaration
func exportFlattened(to url: URL) throws
Exports the stage as a flattened USD file.
Composes all layers into a single layer and writes it to the specified
location. The output format is determined by the file extension.
> Important: Flattening is destructive. Layer structure, composition arcs,
and variant selections are resolved into the output. To preserve layer
structure, use ``exportPackage(to:options:)`` instead.
Throws an error if the extension is not `.usda`, `.usdc`, or `.usd`.
Saves the stage's changed session layers to their sources.
- Throws: An error if a layer cannot be saved. Some session layers may
already have been saved when the failure occurs.
get · iOS 27.0+
timeCodesPerSecond
TypeScript
get timeCodesPerSecond(): number
Swift declaration
var timeCodesPerSecond: Double { get nonmutating set }
The number of time codes per second of playback for this stage.
set · iOS 27.0+
timeCodesPerSecond
TypeScript
set timeCodesPerSecond(value: number)
Swift declaration
var timeCodesPerSecond: Double { get nonmutating set }
The number of time codes per second of playback for this stage.
get · iOS 27.0+
hasAuthoredMetersPerUnit
TypeScript
get hasAuthoredMetersPerUnit(): boolean
Swift declaration
var hasAuthoredMetersPerUnit: Bool { get }
A Boolean value that indicates whether this stage has an authored
``metersPerUnit`` opinion.
Opens a stage rooted at a given layer.
Recursively follows the composition rules described by `rootLayer`,
opening any files referenced by the layer and assembling a hierarchy of
``USDPrim``s from the combined contents of all layers.
This function creates a new, independent stage object even if there is
already a stage opened with `rootLayer` as its root layer.
Parameters:
- rootLayer: The root layer of the new stage.
- sessionLayer: A layer to use as a session layer. If `nil`, an anonymous layer will be created.
- options: Options that specify behavior related to opening a stage.
Opens a stage using a file as the root layer.
Recursively follows the composition rules described by the root layer,
opening any files referenced by that layer and assembling a hierarchy of
``USDPrim``s from the combined contents of all layers.
This function will not create a file if no file exists at `path`, unless
``OpenOptions.createNew`` is passed as an option.
This function creates a new, independent stage object even if there is
already a stage opened with `path` as its root layer.
Parameters:
- path: A file to use as the root layer of the new stage.
- sessionLayer: A layer to use as a session layer. If `nil`, an anonymous layer will be created.
- options: Options that specify behavior related to opening a stage.
Throws: An error if `path` does not exist or could not be read.
Opens a stage using the file at a URL as its root layer.
- Parameters:
- url: A file URL to use as the root layer of the new stage.
- loadingPayloads: The rule that determines which payloads are loaded when opening the stage.
- Returns: A new stage rooted at the layer loaded from `url`.
- Throws: An error if the URL does not refer to a readable file.
method · iOS 27.0+
prim
TypeScript
prim(path: USDLayer_Path): USDPrim
Swift declaration
func prim(at path: USDLayer.Path) -> USDPrim
Returns the prim at a given path, if it exists.
If `path` resolves to a prim beneath an instance, returns an instance
proxy prim if a prim exists at the corresponding path in that instance's
prototype.
If no prim exists at the resolved path, returns an invalid prim handle.
method · iOS 27.0+
save
TypeScript
save(): void
Swift declaration
func save() throws
Saves the stage's changed layers to their sources.
- Throws: An error if a layer cannot be saved. Some layers may already
have been saved when the failure occurs.
Creates a stage from a string containing a `.usda` document.
- Parameters:
- string: The text of a `.usda` document to open as the root layer.
- loadingPayloads: The rule that determines which payloads are loaded when opening the stage.
- Throws: An error if the string cannot be read as a `.usda` layer.
get · iOS 27.0+
upAxis
TypeScript
get upAxis(): USDToken
Swift declaration
var upAxis: USDToken { get nonmutating set }
The axis that points upward in this stage's coordinate system.
set · iOS 27.0+
upAxis
TypeScript
set upAxis(value: USDToken)
Swift declaration
var upAxis: USDToken { get nonmutating set }
The axis that points upward in this stage's coordinate system.
Creates a stage from in-memory data in a given format.
- Parameters:
- buffer: The serialized USD data to open as the root layer.
- type: The content type that identifies the format of `buffer`.
- loadingPayloads: The rule that determines which payloads are loaded when opening the stage.
- Throws: An error if the data cannot be read as a layer of the given type.
Skipped declarations
1 declarations were excluded from these bindings. Each reason comes from the generator or the iOS SDK compiler.
