<!--
{
  "availability" : [
    "iOS: 27.0.0 -",
    "iPadOS: 27.0.0 -",
    "macCatalyst: 27.0.0 -",
    "macOS: 27.0.0 -",
    "tvOS: 27.0.0 -",
    "visionOS: 27.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "USDKit",
  "identifier" : "/documentation/USDKit/USDLayer",
  "metadataVersion" : "0.1.0",
  "role" : "Structure",
  "symbol" : {
    "kind" : "Structure",
    "modules" : [
      "USDKit"
    ],
    "preciseIdentifier" : "s:6USDKit8USDLayerV"
  },
  "title" : "USDLayer"
}
-->

# USDLayer

A single USD document that stores scene description in a file or in memory.

```
struct USDLayer
```

## Topics

### Creating a layer

[`init(displayName: String?) throws`](/documentation/USDKit/USDLayer/init(displayName:))

Creates an anonymous, in-memory layer.

### Opening and finding layers

[`static func find(identifier: String) -> USDLayer?`](/documentation/USDKit/USDLayer/find(identifier:))

Returns an already-loaded layer with this identifier, or `nil` if
none is loaded. Does no I/O.

[`static func open(String, options: USDLayer.OpenOptions) throws -> USDLayer`](/documentation/USDKit/USDLayer/open(_:options:))

Returns an already-loaded layer at the identifier, or opens it from
the resolved asset path.

[`struct OpenOptions`](/documentation/USDKit/USDLayer/OpenOptions)

Options for opening a layer.

[`enum Permission`](/documentation/USDKit/USDLayer/Permission)

Access permission for a spec.

### Saving and reloading

[`func save() throws`](/documentation/USDKit/USDLayer/save())

Saves the layer to its source if it has unsaved changes.

[`func reload() throws`](/documentation/USDKit/USDLayer/reload())

Reloads the layer from its source, discarding any unsaved changes.

[`func clear()`](/documentation/USDKit/USDLayer/clear())

Removes all in-memory content from the layer. The file on disk is
unaffected until [`save()`](/documentation/USDKit/USDLayer/save()) is called.

### Exporting and importing

[`func export(to: URL) throws`](/documentation/USDKit/USDLayer/export(to:)-7vouy)

Writes the layer’s contents to a file at the given URL.

[`func export(to: FilePath) throws`](/documentation/USDKit/USDLayer/export(to:)-5hboj)

Writes the layer’s contents to a file at the given path.

[`func importContents(from: FilePath) throws`](/documentation/USDKit/USDLayer/importContents(from:)-2ipug)

Replaces the layer’s contents with the layer file at the given path.

[`func importContents(from: String) throws`](/documentation/USDKit/USDLayer/importContents(from:)-99hnf)

Replaces the layer’s contents with the USDA string.

### Inspecting identity and state

[`var identifier: String`](/documentation/USDKit/USDLayer/identifier)

The layer’s identifier — typically a file path, URL, or anonymous
identifier string. Identifies the layer in OpenUSD’s global registry.

[`var resolvedPath: FilePath?`](/documentation/USDKit/USDLayer/resolvedPath)

The resolved filesystem location of the layer’s source, or `nil`
for anonymous layers.

[`var displayName: String`](/documentation/USDKit/USDLayer/displayName)

A human-readable name for the layer, derived from its identifier.
Suitable for display in UI.

[`var isAnonymous: Bool`](/documentation/USDKit/USDLayer/isAnonymous)

Whether the layer is anonymous (in-memory, no file backing).

[`var isValid: Bool`](/documentation/USDKit/USDLayer/isValid)

Whether the layer is still valid. Returns `false` if the underlying
data has been released.

[`var isDirty: Bool`](/documentation/USDKit/USDLayer/isDirty)

Whether the layer has unsaved changes.

[`var isMuted: Bool`](/documentation/USDKit/USDLayer/isMuted)

Whether the layer is muted from composition.

### Composing the scene

[`var defaultPrim: USDToken?`](/documentation/USDKit/USDLayer/defaultPrim)

The name of the layer’s default prim — the prim referenced when this
layer is included as a reference or payload without specifying a
target. `nil` if not authored.

[`var subLayerPaths: [USDLayer.AssetPath]`](/documentation/USDKit/USDLayer/subLayerPaths)

The asset paths of the layer’s sublayers, ordered from strongest
to weakest opinion.

[`struct AssetPath`](/documentation/USDKit/USDLayer/AssetPath)

A reference to an external asset such as a texture, audio file, or USD layer.

### Accessing scene description by path

[`func prim(at: USDLayer.Path) -> USDPrim.Spec?`](/documentation/USDKit/USDLayer/prim(at:))

Returns the prim spec authored at the given path, or `nil` if no
prim spec exists there.

[`func property(at: USDLayer.Path) -> USDPrim.Property.Spec?`](/documentation/USDKit/USDLayer/property(at:))

Returns the property spec at the given path.

[`func attribute(at: USDLayer.Path) -> USDPrim.Attribute.Spec?`](/documentation/USDKit/USDLayer/attribute(at:))

Returns the attribute spec at the given path.

[`func relationship(at: USDLayer.Path) -> USDPrim.Relationship.Spec?`](/documentation/USDKit/USDLayer/relationship(at:))

Returns the relationship spec at the given path.

[`func spec(at: USDLayer.Path) -> USDLayer.Spec?`](/documentation/USDKit/USDLayer/spec(at:))

Returns the spec at the given path, or `nil` if no spec is authored there.

[`func specType(at: USDLayer.Path) -> USDLayer.SpecType?`](/documentation/USDKit/USDLayer/specType(at:))

Returns the kind of spec authored at the given path, or `nil`
if nothing is authored there.

[`func traverse(at: USDLayer.Path, (USDLayer.Path) -> Void)`](/documentation/USDKit/USDLayer/traverse(at:_:))

Walks the spec tree rooted at the given path, calling `body` for
each spec’s path.

[`struct Path`](/documentation/USDKit/USDLayer/Path)

A path within a USD scene hierarchy.

[`struct PathExpression`](/documentation/USDKit/USDLayer/PathExpression)

A boolean expression over path patterns for selecting sets of prims.

[`struct Spec`](/documentation/USDKit/USDLayer/Spec)

A handle to a single spec stored in a layer.

[`enum SpecType`](/documentation/USDKit/USDLayer/SpecType)

The kind of spec stored at a path in a layer.

### Reading and authoring fields

[`func field(at: USDLayer.Path, name: USDToken) -> USDValue?`](/documentation/USDKit/USDLayer/field(at:name:))

Returns the value of the named field at the given path, or `nil`
if no such field is authored.

[`func fields(at: USDLayer.Path) -> [USDToken]`](/documentation/USDKit/USDLayer/fields(at:))

Returns the names of the fields authored at the given path.

[`func setField(at: USDLayer.Path, name: USDToken, value: USDValue)`](/documentation/USDKit/USDLayer/setField(at:name:value:)-83nwe)

Sets the value of the named field at the given path.

[`func setField<T>(at: USDLayer.Path, name: USDToken, value: T)`](/documentation/USDKit/USDLayer/setField(at:name:value:)-3242k)

Sets the value of the named field at the given path, wrapping
the typed value in a `USDValue`.

### Working with time samples

[`func timeSample(at: USDLayer.Path, time: USDLayer.TimeCode) -> USDValue?`](/documentation/USDKit/USDLayer/timeSample(at:time:))

Returns the time-sampled value for the attribute at the given path
at the specified time, or `nil` if none is authored at that time.

[`func timeSamples(at: USDLayer.Path) -> Set<USDLayer.TimeCode>`](/documentation/USDKit/USDLayer/timeSamples(at:))

Returns the time codes for which the attribute at the given path
has authored time samples.

[`var allTimeSamples: Set<USDLayer.TimeCode>`](/documentation/USDKit/USDLayer/allTimeSamples)

All time codes for which any attribute in the layer has an authored
time sample.

[`func setTimeSample(at: USDLayer.Path, time: USDLayer.TimeCode, value: USDValue)`](/documentation/USDKit/USDLayer/setTimeSample(at:time:value:)-6t3qd)

Sets the time-sampled value for the attribute at the given path
at the specified time.

[`func setTimeSample<T>(at: USDLayer.Path, time: USDLayer.TimeCode, value: T)`](/documentation/USDKit/USDLayer/setTimeSample(at:time:value:)-3ot1j)

Sets the time-sampled value for the attribute at the given path
at the specified time, wrapping the typed value in a `USDValue`.

[`func eraseTimeSample(at: USDLayer.Path, time: USDLayer.TimeCode)`](/documentation/USDKit/USDLayer/eraseTimeSample(at:time:))

Erases the authored time sample at the given path and time.

### Setting the time range

[`var startTimeCode: USDLayer.TimeCode?`](/documentation/USDKit/USDLayer/startTimeCode)

The first time code in the layer’s animation range.
`nil` if not authored.

[`var endTimeCode: USDLayer.TimeCode?`](/documentation/USDKit/USDLayer/endTimeCode)

The last time code in the layer’s animation range.
`nil` if not authored.

[`var timeCodesPerSecond: Double?`](/documentation/USDKit/USDLayer/timeCodesPerSecond)

The rate at which time codes advance per second.
`nil` if not authored.

[`struct TimeCode`](/documentation/USDKit/USDLayer/TimeCode)

A time value in USD, typically used for animation keyframe times.

[`struct TimeOffset`](/documentation/USDKit/USDLayer/TimeOffset)

A time transformation applied when composing layers.

### Editing scene description

[`func copy(from: USDLayer.Path, to: USDLayer.Path, in: USDLayer?) -> Bool`](/documentation/USDKit/USDLayer/copy(from:to:in:))

Copies the spec at `srcPath` in this layer (and its children) to
`dstPath`.

[`struct ListOperation`](/documentation/USDKit/USDLayer/ListOperation)

A non-destructive list of incremental editing operations for
list-valued metadata and properties.

[`enum ListOperationType`](/documentation/USDKit/USDLayer/ListOperationType)

Identifies an operation slot in a [`USDLayer.ListOperation`](/documentation/USDKit/USDLayer/ListOperation).

[`typealias Relocate`](/documentation/USDKit/USDLayer/Relocate)

A single path relocation from source to target.

[`typealias RelocatesMap`](/documentation/USDKit/USDLayer/RelocatesMap)

A mapping from source paths to target paths for relocations.

[`struct ChangeList`](/documentation/USDKit/USDLayer/ChangeList)

A list of changes made to a layer.

## Relationships

### Conforms To

[`Hashable`](/documentation/Swift/Hashable)

[`Escapable`](/documentation/Swift/Escapable)

[`CustomStringConvertible`](/documentation/Swift/CustomStringConvertible)

[`Copyable`](/documentation/Swift/Copyable)

[`Equatable`](/documentation/Swift/Equatable)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)