This document is for a version of USD that is under development. See this page for the current release.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
SdfLayer Class Reference

A scene description container that can combine with other such containers to form simple component assets, and successively larger aggregates. More...

#include <layer.h>

+ Inheritance diagram for SdfLayer:

Classes

class  DetachedLayerRules
 Object used to specify detached layers. More...
 

Public Member Functions

virtual SDF_API ~SdfLayer ()
 Destructor.
 
 SdfLayer (const SdfLayer &)=delete
 Noncopyable.
 
SdfLayeroperator= (const SdfLayer &)=delete
 
SDF_API bool WriteDataFile (const std::string &filename)
 
SDF_API SdfChangeList CreateDiff (const SdfLayerHandle &layer, bool processPropertyFields=true) const
 Returns a SdfChangeList containing the minimal edits that would be needed to transform this layer to match the contents of the given layer parameter.
 
External references
SDF_API std::set< std::string > GetExternalReferences () const
 
SDF_API bool UpdateExternalReference (const std::string &oldAssetPath, const std::string &newAssetPath=std::string())
 
SDF_API std::set< std::string > GetCompositionAssetDependencies () const
 Return paths of all assets this layer depends on due to composition fields.
 
SDF_API bool UpdateCompositionAssetDependency (const std::string &oldAssetPath, const std::string &newAssetPath=std::string())
 Updates the asset path of a composation dependency in this layer.
 
SDF_API std::set< std::string > GetExternalAssetDependencies () const
 Returns a set of resolved paths to all external asset dependencies the layer needs to generate its contents.
 
Fields

All scene description for a given object is stored as a set of key/value pairs called fields.

These methods provide direct access to those fields, though most clients should use the Spec API to ensure data consistency.

These methods all take SdfPath to identify the queried spec.

SDF_API SdfSpecType GetSpecType (const SdfPath &path) const
 Return the spec type for path.
 
SDF_API bool HasSpec (const SdfPath &path) const
 Return whether a spec exists at path.
 
SDF_API std::vector< TfTokenListFields (const SdfPath &path) const
 Return the names of all the fields that are set at path.
 
SDF_API bool HasField (const SdfPath &path, const TfToken &fieldName, VtValue *value=NULL) const
 Return whether a value exists for the given path and fieldName.
 
SDF_API bool HasField (const SdfPath &path, const TfToken &fieldName, SdfAbstractDataValue *value) const
 
template<class T >
bool HasField (const SdfPath &path, const TfToken &name, T *value) const
 Returns true if the object has a non-empty value with name name and type T.
 
std::type_info const & GetFieldTypeid (const SdfPath &path, const TfToken &name) const
 Return the type of the value for name on spec path.
 
SDF_API bool HasFieldDictKey (const SdfPath &path, const TfToken &fieldName, const TfToken &keyPath, VtValue *value=NULL) const
 Return whether a value exists for the given path and fieldName and keyPath.
 
SDF_API bool HasFieldDictKey (const SdfPath &path, const TfToken &fieldName, const TfToken &keyPath, SdfAbstractDataValue *value) const
 
template<class T >
bool HasFieldDictKey (const SdfPath &path, const TfToken &name, const TfToken &keyPath, T *value) const
 Returns true if the object has a non-empty value with name name and keyPath and type T.
 
SDF_API VtValue GetField (const SdfPath &path, const TfToken &fieldName) const
 Return the value for the given path and fieldName.
 
template<class T >
GetFieldAs (const SdfPath &path, const TfToken &fieldName, const T &defaultValue=T()) const
 Return the value for the given path and fieldName.
 
SDF_API VtValue GetFieldDictValueByKey (const SdfPath &path, const TfToken &fieldName, const TfToken &keyPath) const
 Return the value for the given path and fieldName at keyPath.
 
SDF_API void SetField (const SdfPath &path, const TfToken &fieldName, const VtValue &value)
 Set the value of the given path and fieldName.
 
SDF_API void SetField (const SdfPath &path, const TfToken &fieldName, const SdfAbstractDataConstValue &value)
 
template<class T >
void SetField (const SdfPath &path, const TfToken &fieldName, const T &val)
 Set the value of the given path and fieldName.
 
SDF_API void SetFieldDictValueByKey (const SdfPath &path, const TfToken &fieldName, const TfToken &keyPath, const VtValue &value)
 Set the value of the given path and fieldName.
 
SDF_API void SetFieldDictValueByKey (const SdfPath &path, const TfToken &fieldName, const TfToken &keyPath, const SdfAbstractDataConstValue &value)
 
template<class T >
void SetFieldDictValueByKey (const SdfPath &path, const TfToken &fieldName, const TfToken &keyPath, const T &val)
 Set the value of the given path and fieldName.
 
SDF_API void EraseField (const SdfPath &path, const TfToken &fieldName)
 Remove the field at path and fieldName, if one exists.
 
SDF_API void EraseFieldDictValueByKey (const SdfPath &path, const TfToken &fieldName, const TfToken &keyPath)
 Remove the field at path and fieldName and keyPath, if one exists.
 
Metadata
SDF_API SdfAssetPath GetColorConfiguration () const
 Returns the color configuration asset-path for this layer.
 
SDF_API void SetColorConfiguration (const SdfAssetPath &colorConfiguration)
 Sets the color configuration asset-path for this layer.
 
SDF_API bool HasColorConfiguration () const
 Returns true if color configuration metadata is set in this layer.
 
SDF_API void ClearColorConfiguration ()
 Clears the color configuration metadata authored in this layer.
 
SDF_API TfToken GetColorManagementSystem () const
 Returns the color management system used to interpret the color configuration asset-path authored in this layer.
 
SDF_API void SetColorManagementSystem (const TfToken &cms)
 Sets the color management system used to interpret the color configuration asset-path authored this layer.
 
SDF_API bool HasColorManagementSystem () const
 Returns true if colorManagementSystem metadata is set in this layer.
 
SDF_API void ClearColorManagementSystem ()
 Clears the 'colorManagementSystem' metadata authored in this layer.
 
SDF_API std::string GetComment () const
 Returns the comment string for this layer.
 
SDF_API void SetComment (const std::string &comment)
 Sets the comment string for this layer.
 
SDF_API TfToken GetDefaultPrim () const
 Return the defaultPrim metadata for this layer.
 
SDF_API SdfPath GetDefaultPrimAsPath () const
 Return this layer's default prim metadata interpreted as an absolute prim path regardless of whether it was authored as a root prim name or a prim path.
 
SDF_API void SetDefaultPrim (const TfToken &name)
 Set the default prim metadata for this layer.
 
SDF_API void ClearDefaultPrim ()
 Clear the default prim metadata for this layer.
 
SDF_API bool HasDefaultPrim ()
 Return true if the default prim metadata is set in this layer.
 
SDF_API std::string GetDocumentation () const
 Returns the documentation string for this layer.
 
SDF_API void SetDocumentation (const std::string &documentation)
 Sets the documentation string for this layer.
 
SDF_API double GetStartTimeCode () const
 Returns the layer's start timeCode.
 
SDF_API void SetStartTimeCode (double startTimecode)
 Sets the layer's start timeCode.
 
SDF_API bool HasStartTimeCode () const
 Returns true if the layer has a startTimeCode opinion.
 
SDF_API void ClearStartTimeCode ()
 Clear the startTimeCode opinion.
 
SDF_API double GetEndTimeCode () const
 Returns the layer's end timeCode.
 
SDF_API void SetEndTimeCode (double endTimeCode)
 Sets the layer's end timeCode.
 
SDF_API bool HasEndTimeCode () const
 Returns true if the layer has an endTimeCode opinion.
 
SDF_API void ClearEndTimeCode ()
 Clear the endTimeCode opinion.
 
SDF_API double GetTimeCodesPerSecond () const
 Returns the layer's timeCodes per second.
 
SDF_API void SetTimeCodesPerSecond (double timeCodesPerSecond)
 Sets the layer's timeCodes per second.
 
SDF_API bool HasTimeCodesPerSecond () const
 Returns true if the layer has a timeCodesPerSecond opinion.
 
SDF_API void ClearTimeCodesPerSecond ()
 Clear the timeCodesPerSecond opinion.
 
SDF_API double GetFramesPerSecond () const
 Returns the layer's frames per second.
 
SDF_API void SetFramesPerSecond (double framesPerSecond)
 Sets the layer's frames per second.
 
SDF_API bool HasFramesPerSecond () const
 Returns true if the layer has a frames per second opinion.
 
SDF_API void ClearFramesPerSecond ()
 Clear the framesPerSecond opinion.
 
SDF_API int GetFramePrecision () const
 Returns the layer's frame precision.
 
SDF_API void SetFramePrecision (int framePrecision)
 Sets the layer's frame precision.
 
SDF_API bool HasFramePrecision () const
 Returns true if the layer has a frames precision opinion.
 
SDF_API void ClearFramePrecision ()
 Clear the framePrecision opinion.
 
SDF_API std::string GetOwner () const
 Returns the layer's owner.
 
SDF_API void SetOwner (const std::string &owner)
 Sets the layer's owner.
 
SDF_API bool HasOwner () const
 Returns true if the layer has an owner opinion.
 
SDF_API void ClearOwner ()
 Clear the owner opinion.
 
SDF_API std::string GetSessionOwner () const
 Returns the layer's session owner.
 
SDF_API void SetSessionOwner (const std::string &owner)
 Sets the layer's session owner.
 
SDF_API bool HasSessionOwner () const
 Returns true if the layer has a session owner opinion.
 
SDF_API void ClearSessionOwner ()
 
SDF_API bool GetHasOwnedSubLayers () const
 Returns true if the layer's sublayers are expected to have owners.
 
SDF_API void SetHasOwnedSubLayers (bool)
 Sets whether the layer's sublayers are expected to have owners.
 
SDF_API VtDictionary GetCustomLayerData () const
 Returns the CustomLayerData dictionary associated with this layer.
 
SDF_API void SetCustomLayerData (const VtDictionary &value)
 Sets the CustomLayerData dictionary associated with this layer.
 
SDF_API bool HasCustomLayerData () const
 Returns true if CustomLayerData is authored on the layer.
 
SDF_API void ClearCustomLayerData ()
 Clears out the CustomLayerData dictionary associated with this layer.
 
SDF_API VtDictionary GetExpressionVariables () const
 Returns the expression variables dictionary authored on this layer.
 
SDF_API void SetExpressionVariables (const VtDictionary &expressionVars)
 Sets the expression variables dictionary for this layer.
 
SDF_API bool HasExpressionVariables () const
 Returns true if expression variables are authored on this layer.
 
SDF_API void ClearExpressionVariables ()
 Clears the expression variables dictionary authored on this layer.
 
Sublayers
SDF_API SdfSubLayerProxy GetSubLayerPaths () const
 Returns a proxy for this layer's sublayers.
 
SDF_API void SetSubLayerPaths (const std::vector< std::string > &newPaths)
 Sets the paths of the layer's sublayers.
 
SDF_API size_t GetNumSubLayerPaths () const
 Returns the number of sublayer paths (and offsets).
 
SDF_API void InsertSubLayerPath (const std::string &path, int index=-1)
 Inserts new sublayer path at the given index.
 
SDF_API void RemoveSubLayerPath (int index)
 Removes sublayer path at the given index.
 
SDF_API SdfLayerOffsetVector GetSubLayerOffsets () const
 Returns the layer offsets for all the subLayer paths.
 
SDF_API SdfLayerOffset GetSubLayerOffset (int index) const
 Returns the layer offset for the subLayer path at the given index.
 
SDF_API void SetSubLayerOffset (const SdfLayerOffset &offset, int index)
 Sets the layer offset for the subLayer path at the given index.
 
Relocates
SDF_API SdfRelocates GetRelocates () const
 Get the list of relocates specified in this layer's metadata.
 
SDF_API void SetRelocates (const SdfRelocates &relocates)
 Set the entire list of namespace relocations specified on this layer to relocates.
 
SDF_API bool HasRelocates () const
 Returns true if this layer's metadata has any relocates opinion, including that there should be no relocates (i.e.
 
SDF_API void ClearRelocates ()
 Clears the layer relocates opinion in the layer's metadata.
 
Lookup
SDF_API SdfPrimSpecHandle GetPseudoRoot () const
 Returns the layer's pseudo-root prim.
 
SDF_API SdfSpecHandle GetObjectAtPath (const SdfPath &path)
 Returns the object at the given path.
 
SDF_API SdfPrimSpecHandle GetPrimAtPath (const SdfPath &path)
 Returns the prim at the given path.
 
SDF_API SdfPropertySpecHandle GetPropertyAtPath (const SdfPath &path)
 Returns a property at the given path.
 
SDF_API SdfAttributeSpecHandle GetAttributeAtPath (const SdfPath &path)
 Returns an attribute at the given path.
 
SDF_API SdfRelationshipSpecHandle GetRelationshipAtPath (const SdfPath &path)
 Returns a relationship at the given path.
 
Permissions
SDF_API bool PermissionToEdit () const
 Returns true if the caller is allowed to modify the layer and false otherwise.
 
SDF_API bool PermissionToSave () const
 Returns true if the caller is allowed to save the layer to its existing fileName and false otherwise.
 
SDF_API void SetPermissionToEdit (bool allow)
 Sets permission to edit.
 
SDF_API void SetPermissionToSave (bool allow)
 Sets permission to save.
 
Batch namespace editing
SDF_API SdfNamespaceEditDetail::Result CanApply (const SdfBatchNamespaceEdit &, SdfNamespaceEditDetailVector *details=NULL) const
 Check if a batch of namespace edits will succeed.
 
SDF_API bool Apply (const SdfBatchNamespaceEdit &)
 Performs a batch of namespace edits.
 
Layer state
SDF_API SdfLayerStateDelegateBasePtr GetStateDelegate () const
 Returns the state delegate used to manage this layer's authoring state.
 
SDF_API void SetStateDelegate (const SdfLayerStateDelegateBaseRefPtr &delegate)
 Sets the state delegate used to manage this layer's authoring state.
 
SDF_API bool IsDirty () const
 Returns true if the layer is dirty, i.e.
 
Time-sample API
SDF_API std::set< double > ListAllTimeSamples () const
 
SDF_API std::set< double > ListTimeSamplesForPath (const SdfPath &path) const
 
SDF_API bool GetBracketingTimeSamples (double time, double *tLower, double *tUpper)
 
SDF_API size_t GetNumTimeSamplesForPath (const SdfPath &path) const
 
SDF_API bool GetBracketingTimeSamplesForPath (const SdfPath &path, double time, double *tLower, double *tUpper)
 
SDF_API bool QueryTimeSample (const SdfPath &path, double time, VtValue *value=NULL) const
 
SDF_API bool QueryTimeSample (const SdfPath &path, double time, SdfAbstractDataValue *value) const
 
template<class T >
bool QueryTimeSample (const SdfPath &path, double time, T *data) const
 
SDF_API void SetTimeSample (const SdfPath &path, double time, const VtValue &value)
 
SDF_API void SetTimeSample (const SdfPath &path, double time, const SdfAbstractDataConstValue &value)
 
template<class T >
void SetTimeSample (const SdfPath &path, double time, const T &value)
 
SDF_API void EraseTimeSample (const SdfPath &path, double time)
 
- Public Member Functions inherited from TfRefBase
 TfRefBase (TfRefBase const &)
 
TfRefBaseoperator= (TfRefBase const &)
 
size_t GetCurrentCount () const
 Return the current reference count of this object.
 
bool IsUnique () const
 Return true if only one TfRefPtr points to this object.
 
void SetShouldInvokeUniqueChangedListener (bool shouldCall)
 
- Public Member Functions inherited from TfWeakBase
 TfWeakBase (const TfWeakBase &)
 
const TfWeakBase__GetTfWeakBase__ () const
 
const TfWeakBaseoperator= (const TfWeakBase &)
 
void EnableNotification2 () const
 
TF_API void const * GetUniqueIdentifier () const
 

Static Public Member Functions

static SDF_API void DumpLayerInfo ()
 
Detached Layers

Detached layers are layers that are detached from the serialized data store and isolated from any external changes to that serialized data.

File format plugins may produce layers that maintain a persistent connection to their serialized representation to read data on-demand. For example, a file format might set up layers to hold an open file handle and read attribute time samples from it only when requested, to avoid pulling in unnecessary data. However, there may be times when keeping this connection is undesirable. In the previous example, a crash might occur if some other process were to change the file on disk, or users might be prevented from overwriting the file at all which could interfere with workflow.

To avoid these problems, the functions below may be used to specify layers that are to be detached from the original serialized data.

static SDF_API void SetDetachedLayerRules (const DetachedLayerRules &mask)
 Sets the rules specifying detached layers.
 
static SDF_API const DetachedLayerRulesGetDetachedLayerRules ()
 Returns the current rules for the detached layer set.
 
static SDF_API bool IsIncludedByDetachedLayerRules (const std::string &identifier)
 Returns whether the given layer identifier is included in the current rules for the detached layer set.
 
- Static Public Member Functions inherited from TfRefBase
static TF_API void SetUniqueChangedListener (UniqueChangedListener listener)
 

Protected Member Functions

 SdfLayer (const SdfFileFormatConstPtr &fileFormat, const std::string &identifier, const std::string &realPath=std::string(), const ArAssetInfo &assetInfo=ArAssetInfo(), const FileFormatArguments &args=FileFormatArguments(), bool validateAuthoring=false)
 
- Protected Member Functions inherited from TfWeakBase
TfRefPtr< Tf_Remnant > _Register () const
 
template<class T >
TfRefPtr< Tf_Remnant > _Register (T *tempRmnt) const
 
bool _HasRemnant () const
 

Friends

class SdfSpec
 
class SdfPropertySpec
 
class SdfAttributeSpec
 
class SdfFileFormat
 
class SdfLayerStateDelegateBase
 

Primary API

typedef std::map< std::string, std::string > FileFormatArguments
 Type for specifying additional file format-specific arguments to layer API.
 
SDF_API const SdfSchemaBaseGetSchema () const
 Returns the schema this layer adheres to.
 
SDF_API const SdfFileFormatConstPtr & GetFileFormat () const
 Returns the file format used by this layer.
 
SDF_API const FileFormatArgumentsGetFileFormatArguments () const
 Returns the file format-specific arguments used during the construction of this layer.
 
SDF_API SdfDataRefPtr GetMetadata () const
 Returns the data from the absolute root path of this layer.
 
SDF_API SdfLayerHints GetHints () const
 Return hints about the layer's current contents.
 
SDF_API bool IsEmpty () const
 Returns whether this layer has no significant data.
 
SDF_API bool StreamsData () const
 Returns true if this layer streams data from its serialized data store on demand, false otherwise.
 
SDF_API bool IsDetached () const
 Returns true if this layer is detached from its serialized data store, false otherwise.
 
SDF_API void TransferContent (const SdfLayerHandle &layer)
 Copies the content of the given layer into this layer.
 
SDF_API bool IsAnonymous () const
 Returns true if this layer is an anonymous layer.
 
static SDF_API SdfLayerRefPtr CreateNew (const std::string &identifier, const FileFormatArguments &args=FileFormatArguments())
 Creates a new empty layer with the given identifier.
 
static SDF_API SdfLayerRefPtr CreateNew (const SdfFileFormatConstPtr &fileFormat, const std::string &identifier, const FileFormatArguments &args=FileFormatArguments())
 Creates a new empty layer with the given identifier for a given file format class.
 
static SDF_API SdfLayerRefPtr New (const SdfFileFormatConstPtr &fileFormat, const std::string &identifier, const FileFormatArguments &args=FileFormatArguments())
 Creates a new empty layer with the given identifier for a given file format class.
 
static SDF_API SdfLayerHandle Find (const std::string &identifier, const FileFormatArguments &args=FileFormatArguments())
 Return an existing layer with the given identifier and args.
 
static SDF_API SdfLayerHandle FindRelativeToLayer (const SdfLayerHandle &anchor, const std::string &identifier, const FileFormatArguments &args=FileFormatArguments())
 Return an existing layer with the given identifier and args.
 
static SDF_API SdfLayerRefPtr FindOrOpen (const std::string &identifier, const FileFormatArguments &args=FileFormatArguments())
 Return an existing layer with the given identifier and args, or else load it.
 
static SDF_API SdfLayerRefPtr FindOrOpenRelativeToLayer (const SdfLayerHandle &anchor, const std::string &identifier, const FileFormatArguments &args=FileFormatArguments())
 Return an existing layer with the given identifier and args, or else load it.
 
static SDF_API SdfLayerRefPtr OpenAsAnonymous (const std::string &layerPath, bool metadataOnly=false, const std::string &tag=std::string())
 Load the given layer from disk as a new anonymous layer.
 
static SDF_API SdfLayerHandleSet GetLoadedLayers ()
 Returns handles for all layers currently held by the layer registry.
 
static SDF_API SdfLayerRefPtr CreateAnonymous (const std::string &tag=std::string(), const FileFormatArguments &args=FileFormatArguments())
 Creates a new anonymous layer with an optional tag.
 
static SDF_API SdfLayerRefPtr CreateAnonymous (const std::string &tag, const SdfFileFormatConstPtr &format, const FileFormatArguments &args=FileFormatArguments())
 Create an anonymous layer with a specific format.
 
static SDF_API bool IsAnonymousLayerIdentifier (const std::string &identifier)
 Returns true if the identifier is an anonymous layer unique identifier.
 
static SDF_API std::string GetDisplayNameFromIdentifier (const std::string &identifier)
 Returns the display name for the given identifier, using the same rules as GetDisplayName.
 

Traversal

typedef std::function< void(const SdfPath &)> TraversalFunction
 Callback function for Traverse.
 
SDF_API void Traverse (const SdfPath &path, const TraversalFunction &func)
 

Prims

typedef SdfPrimSpecView RootPrimsView
 
SDF_API RootPrimsView GetRootPrims () const
 Returns a vector of the layer's root prims.
 
SDF_API void SetRootPrims (const SdfPrimSpecHandleVector &rootPrims)
 Sets a new vector of root prims.
 
SDF_API bool InsertRootPrim (const SdfPrimSpecHandle &prim, int index=-1)
 Adds a new root prim at the given index.
 
SDF_API void RemoveRootPrim (const SdfPrimSpecHandle &prim)
 Remove a root prim.
 
SDF_API void ScheduleRemoveIfInert (const SdfSpec &spec)
 Cause spec to be removed if it no longer affects the scene when the last change block is closed, or now if there are no change blocks.
 
SDF_API void RemovePrimIfInert (SdfPrimSpecHandle prim)
 Removes scene description that does not affect the scene in the layer namespace beginning with prim.
 
SDF_API void RemovePropertyIfHasOnlyRequiredFields (SdfPropertySpecHandle prop)
 Removes prop if it has only required fields (i.e.
 
SDF_API void RemoveInertSceneDescription ()
 Removes all scene description in this layer that does not affect the scene.
 
SDF_API SdfNameOrderProxy GetRootPrimOrder () const
 Returns the list of prim names for this layer's reorder rootPrims statement.
 
SDF_API void SetRootPrimOrder (const std::vector< TfToken > &names)
 Given a list of (possible sparse) prim names, authors a reorder rootPrims statement for this prim.
 
SDF_API void InsertInRootPrimOrder (const TfToken &name, int index=-1)
 Adds a new root prim name in the root prim order.
 
SDF_API void RemoveFromRootPrimOrder (const TfToken &name)
 Removes a root prim name from the root prim order.
 
SDF_API void RemoveFromRootPrimOrderByIndex (int index)
 Removes a root prim name from the root prim order by index.
 
SDF_API void ApplyRootPrimOrder (std::vector< TfToken > *vec) const
 Reorders the given list of prim names according to the reorder rootPrims statement for this layer.
 

File I/O

SDF_API bool Save (bool force=false) const
 Returns true if successful, false if an error occurred.
 
SDF_API bool Export (const std::string &filename, const std::string &comment=std::string(), const FileFormatArguments &args=FileFormatArguments()) const
 Exports this layer to a file.
 
SDF_API bool ExportToString (std::string *result) const
 Writes this layer to the given string.
 
SDF_API bool ImportFromString (const std::string &string)
 Reads this layer from the given string.
 
SDF_API void Clear ()
 Clears the layer of all content.
 
SDF_API bool Reload (bool force=false)
 Reloads the layer from its persistent representation.
 
SDF_API bool Import (const std::string &layerPath)
 Imports the content of the given layer path, replacing the content of the current layer.
 
static SDF_API bool ReloadLayers (const std::set< SdfLayerHandle > &layers, bool force=false)
 Reloads the specified layers.
 

Identification

A layer's identifier is a string that uniquely identifies a layer.

At minimum, it is the string by which the layer was created, either via FindOrOpen or CreateNew. If additional arguments were passed to those functions, those arguments will be encoded in the identifier.

For example: FindOrOpen('foo.sdf', args={'a':'b', 'c':'d'}).identifier => "foo.sdf:SDF_FORMAT_ARGS:a=b&c=d"

Note that this means the identifier may in general not be a path.

The identifier format is subject to change; consumers should NOT parse layer identifiers themselves, but should use the supplied SplitIdentifier and CreateIdentifier helper functions.

SDF_API const std::string & GetIdentifier () const
 Returns the layer identifier.
 
SDF_API void SetIdentifier (const std::string &identifier)
 Sets the layer identifier.
 
SDF_API void UpdateAssetInfo ()
 Update layer asset information.
 
SDF_API std::string GetDisplayName () const
 Returns the layer's display name.
 
SDF_API const ArResolvedPathGetResolvedPath () const
 Returns the resolved path for this layer.
 
SDF_API const std::string & GetRealPath () const
 Returns the resolved path for this layer.
 
SDF_API std::string GetFileExtension () const
 Returns the file extension to use for this layer.
 
SDF_API const std::string & GetVersion () const
 Returns the asset system version of this layer.
 
SDF_API const std::string & GetRepositoryPath () const
 Returns the layer identifier in asset path form.
 
SDF_API const std::string & GetAssetName () const
 Returns the asset name associated with this layer.
 
SDF_API const VtValueGetAssetInfo () const
 Returns resolve information from the last time the layer identifier was resolved.
 
SDF_API std::string ComputeAbsolutePath (const std::string &assetPath) const
 Returns the path to the asset specified by assetPath using this layer to anchor the path if necessary.
 
static SDF_API bool SplitIdentifier (const std::string &identifier, std::string *layerPath, FileFormatArguments *arguments)
 Splits the given layer identifier into its constituent layer path and arguments.
 
static SDF_API std::string CreateIdentifier (const std::string &layerPath, const FileFormatArguments &arguments)
 Joins the given layer path and arguments into an identifier.
 

Muting

SDF_API bool IsMuted () const
 Returns true if the current layer is muted.
 
SDF_API void SetMuted (bool muted)
 Mutes the current layer if muted is true, and unmutes it otherwise.
 
static SDF_API std::set< std::string > GetMutedLayers ()
 Returns the set of muted layer paths.
 
static SDF_API bool IsMuted (const std::string &path)
 Returns true if the specified layer path is muted.
 
static SDF_API void AddToMutedLayers (const std::string &mutedPath)
 Add the specified path to the muted layers set.
 
static SDF_API void RemoveFromMutedLayers (const std::string &mutedPath)
 Remove the specified path from the muted layers set.
 

Additional Inherited Members

- Public Types inherited from TfRefBase
typedef void(* UniqueChangedFuncPtr) (TfRefBase const *, bool)
 

Detailed Description

A scene description container that can combine with other such containers to form simple component assets, and successively larger aggregates.

The contents of an SdfLayer adhere to the SdfData data model. A layer can be ephemeral, or be an asset accessed and serialized through the ArAsset and ArResolver interfaces.

The SdfLayer class provides a consistent API for accesing and serializing scene description, using any data store provided by Ar plugins. Sdf itself provides a UTF-8 text format for layers identified by the ".sdf" identifier extension, but via the SdfFileFormat abstraction, allows downstream modules and plugins to adapt arbitrary data formats to the SdfData/SdfLayer model.

The FindOrOpen() method returns a new SdfLayer object with scene description from any supported asset format. Once read, a layer remembers which asset it was read from. The Save() method saves the layer back out to the original asset. You can use the Export() method to write the layer to a different location. You can use the GetIdentifier() method to get the layer's Id or GetRealPath() to get the resolved, full URI.

Layer identifiers are UTF-8 encoded strings. A layer's file format is determined via the identifier's extension (as resolved by Ar) with [A-Z] (and no other characters) explicitly case folded.

Layers can have a timeCode range (startTimeCode and endTimeCode). This range represents the suggested playback range, but has no impact on the extent of the animation data that may be stored in the layer. The metadatum "timeCodesPerSecond" is used to annotate how the time ordinate for samples contained in the file scales to seconds. For example, if timeCodesPerSecond is 24, then a sample at time ordinate 24 should be viewed exactly one second after the sample at time ordinate 0.

Definition at line 81 of file layer.h.

Member Typedef Documentation

◆ FileFormatArguments

typedef std::map<std::string, std::string> FileFormatArguments

Type for specifying additional file format-specific arguments to layer API.

Definition at line 107 of file layer.h.

◆ RootPrimsView

Definition at line 1067 of file layer.h.

◆ TraversalFunction

typedef std::function<void(const SdfPath&)> TraversalFunction

Callback function for Traverse.

This callback will be invoked with the path of each spec that is visited.

See also
Traverse

Definition at line 755 of file layer.h.

Constructor & Destructor Documentation

◆ ~SdfLayer()

virtual SDF_API ~SdfLayer ( )
virtual

Destructor.

◆ SdfLayer()

SdfLayer ( const SdfLayer )
delete

Noncopyable.

Member Function Documentation

◆ AddToMutedLayers()

static SDF_API void AddToMutedLayers ( const std::string &  mutedPath)
static

Add the specified path to the muted layers set.

◆ Apply()

SDF_API bool Apply ( const SdfBatchNamespaceEdit )

Performs a batch of namespace edits.

Returns true on success and false on failure. On failure, no namespace edits will have occurred.

◆ ApplyRootPrimOrder()

SDF_API void ApplyRootPrimOrder ( std::vector< TfToken > *  vec) const

Reorders the given list of prim names according to the reorder rootPrims statement for this layer.

This routine employs the standard list editing operations for ordered items in a ListEditor.

◆ CanApply()

SDF_API SdfNamespaceEditDetail::Result CanApply ( const SdfBatchNamespaceEdit ,
SdfNamespaceEditDetailVector details = NULL 
) const

Check if a batch of namespace edits will succeed.

This returns SdfNamespaceEditDetail::Okay if they will succeed as a batch, SdfNamespaceEditDetail::Unbatched if the edits will succeed but will be applied unbatched, and SdfNamespaceEditDetail::Error if they will not succeed. No edits will be performed in any case.

If details is not NULL and the method does not return Okay then details about the problems will be appended to details. A problem may cause the method to return early, so details may not list every problem.

Note that Sdf does not track backpointers so it's unable to fix up targets/connections to namespace edited objects. Clients must fix those to prevent them from falling off. In addition, this method will report failure if any relational attribute with a target to a namespace edited object is subsequently edited (in the same batch). Clients should perform edits on relational attributes first.

Clients may wish to report unbatch details to the user to confirm that the edits should be applied unbatched. This will give the user a chance to correct any problems that cause batching to fail and try again.

◆ Clear()

SDF_API void Clear ( )

Clears the layer of all content.

This restores the layer to a state as if it had just been created with CreateNew(). This operation is Undo-able.

The fileName and whether journaling is enabled are not affected by this method.

◆ ClearColorConfiguration()

SDF_API void ClearColorConfiguration ( )

Clears the color configuration metadata authored in this layer.

See also
HasColorConfiguration(), SetColorConfiguration()

◆ ClearColorManagementSystem()

SDF_API void ClearColorManagementSystem ( )

Clears the 'colorManagementSystem' metadata authored in this layer.

See also
HascolorManagementSystem(), SetColorManagementSystem()

◆ ClearCustomLayerData()

SDF_API void ClearCustomLayerData ( )

Clears out the CustomLayerData dictionary associated with this layer.

◆ ClearDefaultPrim()

SDF_API void ClearDefaultPrim ( )

Clear the default prim metadata for this layer.

See GetDefaultPrim() and SetDefaultPrim().

◆ ClearEndTimeCode()

SDF_API void ClearEndTimeCode ( )

Clear the endTimeCode opinion.

◆ ClearExpressionVariables()

SDF_API void ClearExpressionVariables ( )

Clears the expression variables dictionary authored on this layer.

◆ ClearFramePrecision()

SDF_API void ClearFramePrecision ( )

Clear the framePrecision opinion.

◆ ClearFramesPerSecond()

SDF_API void ClearFramesPerSecond ( )

Clear the framesPerSecond opinion.

◆ ClearOwner()

SDF_API void ClearOwner ( )

Clear the owner opinion.

◆ ClearRelocates()

SDF_API void ClearRelocates ( )

Clears the layer relocates opinion in the layer's metadata.

◆ ClearStartTimeCode()

SDF_API void ClearStartTimeCode ( )

Clear the startTimeCode opinion.

◆ ClearTimeCodesPerSecond()

SDF_API void ClearTimeCodesPerSecond ( )

Clear the timeCodesPerSecond opinion.

◆ ComputeAbsolutePath()

SDF_API std::string ComputeAbsolutePath ( const std::string &  assetPath) const

Returns the path to the asset specified by assetPath using this layer to anchor the path if necessary.

Returns assetPath if it's empty or an anonymous layer identifier.

This method can be used on asset paths that are authored in this layer to create new asset paths that can be copied to other layers. These new asset paths should refer to the same assets as the original asset paths. For example, if the underlying ArResolver is filesystem-based and assetPath is a relative filesystem path, this method might return the absolute filesystem path using this layer's location as the anchor.

The returned path should in general not be assumed to be an absolute filesystem path or any other specific form. It is "absolute" in that it should resolve to the same asset regardless of what layer it's authored in.

◆ CreateAnonymous() [1/2]

static SDF_API SdfLayerRefPtr CreateAnonymous ( const std::string &  tag,
const SdfFileFormatConstPtr &  format,
const FileFormatArguments args = FileFormatArguments() 
)
static

Create an anonymous layer with a specific format.

◆ CreateAnonymous() [2/2]

static SDF_API SdfLayerRefPtr CreateAnonymous ( const std::string &  tag = std::string(),
const FileFormatArguments args = FileFormatArguments() 
)
static

Creates a new anonymous layer with an optional tag.

An anonymous layer is a layer with a system assigned identifier, that cannot be saved to disk via Save(). Anonymous layers have an identifier, but no real path or other asset information fields.

Anonymous layers may be tagged, which can be done to aid debugging subsystems that make use of anonymous layers. The tag becomes the display name of an anonymous layer, and is also included in the generated identifier. Untagged anonymous layers have an empty display name.

Additional arguments may be supplied via the args parameter. These arguments may control behavior specific to the layer's file format.

◆ CreateDiff()

SDF_API SdfChangeList CreateDiff ( const SdfLayerHandle &  layer,
bool  processPropertyFields = true 
) const

Returns a SdfChangeList containing the minimal edits that would be needed to transform this layer to match the contents of the given layer parameter.

If processPropertyFields is false, property fields will be ignored during the diff computation. Any differences in fields between properties with the same path in this layer and layer will not be captured in the returned SdfChangeList. This can, however, avoid potentially expensive data retrieval operations.

◆ CreateIdentifier()

static SDF_API std::string CreateIdentifier ( const std::string &  layerPath,
const FileFormatArguments arguments 
)
static

Joins the given layer path and arguments into an identifier.

◆ CreateNew() [1/2]

static SDF_API SdfLayerRefPtr CreateNew ( const SdfFileFormatConstPtr &  fileFormat,
const std::string &  identifier,
const FileFormatArguments args = FileFormatArguments() 
)
static

Creates a new empty layer with the given identifier for a given file format class.

This function has the same behavior as the other CreateNew function, but uses the explicitly-specified fileFormat instead of attempting to discern the format from identifier.

◆ CreateNew() [2/2]

static SDF_API SdfLayerRefPtr CreateNew ( const std::string &  identifier,
const FileFormatArguments args = FileFormatArguments() 
)
static

Creates a new empty layer with the given identifier.

Additional arguments may be supplied via the args parameter. These arguments may control behavior specific to the layer's file format.

◆ EraseField()

SDF_API void EraseField ( const SdfPath path,
const TfToken fieldName 
)

Remove the field at path and fieldName, if one exists.

◆ EraseFieldDictValueByKey()

SDF_API void EraseFieldDictValueByKey ( const SdfPath path,
const TfToken fieldName,
const TfToken keyPath 
)

Remove the field at path and fieldName and keyPath, if one exists.

The keyPath is a ':'-separated path addressing an element in sub-dictionaries.

◆ Export()

SDF_API bool Export ( const std::string &  filename,
const std::string &  comment = std::string(),
const FileFormatArguments args = FileFormatArguments() 
) const

Exports this layer to a file.

Returns true if successful, false if an error occurred.

If comment is not empty, the layer gets exported with the given comment. Additional arguments may be supplied via the args parameter. These arguments may control behavior specific to the exported layer's file format.

Note that the file name or comment of the original layer is not updated. This only saves a copy of the layer to the given filename. Subsequent calls to Save() will still save the layer to it's previously remembered file name.

◆ ExportToString()

SDF_API bool ExportToString ( std::string *  result) const

Writes this layer to the given string.

Returns true if successful and sets result, otherwise returns false.

◆ Find()

static SDF_API SdfLayerHandle Find ( const std::string &  identifier,
const FileFormatArguments args = FileFormatArguments() 
)
static

Return an existing layer with the given identifier and args.

If the layer can't be found, an error is posted and a null layer is returned.

Arguments in args will override any arguments specified in identifier.

◆ FindOrOpen()

static SDF_API SdfLayerRefPtr FindOrOpen ( const std::string &  identifier,
const FileFormatArguments args = FileFormatArguments() 
)
static

Return an existing layer with the given identifier and args, or else load it.

If the layer can't be found or loaded, an error is posted and a null layer is returned.

Arguments in args will override any arguments specified in identifier.

◆ FindOrOpenRelativeToLayer()

static SDF_API SdfLayerRefPtr FindOrOpenRelativeToLayer ( const SdfLayerHandle &  anchor,
const std::string &  identifier,
const FileFormatArguments args = FileFormatArguments() 
)
static

Return an existing layer with the given identifier and args, or else load it.

The given identifier will be resolved relative to the anchor layer. If the layer can't be found or loaded, an error is posted and a null layer is returned.

If the anchor layer is invalid, issues a coding error and returns a null handle.

Arguments in args will override any arguments specified in identifier.

◆ FindRelativeToLayer()

static SDF_API SdfLayerHandle FindRelativeToLayer ( const SdfLayerHandle &  anchor,
const std::string &  identifier,
const FileFormatArguments args = FileFormatArguments() 
)
static

Return an existing layer with the given identifier and args.

The given identifier will be resolved relative to the anchor layer. If the layer can't be found, an error is posted and a null layer is returned.

If the anchor layer is invalid, a coding error is raised, and a null handle is returned.

Arguments in args will override any arguments specified in identifier.

◆ GetAssetInfo()

SDF_API const VtValue & GetAssetInfo ( ) const

Returns resolve information from the last time the layer identifier was resolved.

◆ GetAssetName()

SDF_API const std::string & GetAssetName ( ) const

Returns the asset name associated with this layer.

◆ GetAttributeAtPath()

SDF_API SdfAttributeSpecHandle GetAttributeAtPath ( const SdfPath path)

Returns an attribute at the given path.

Returns NULL if there is no attribute at path. This is simply a more specifically typed version of GetObjectAtPath().

◆ GetColorConfiguration()

SDF_API SdfAssetPath GetColorConfiguration ( ) const

Returns the color configuration asset-path for this layer.

The default value is an empty asset-path.

◆ GetColorManagementSystem()

SDF_API TfToken GetColorManagementSystem ( ) const

Returns the color management system used to interpret the color configuration asset-path authored in this layer.

The default value is an empty token, which implies that the clients will have to determine the color management system from the color configuration asset path (i.e. from its file extension), if it's specified.

◆ GetComment()

SDF_API std::string GetComment ( ) const

Returns the comment string for this layer.

The default value for comment is "".

◆ GetCompositionAssetDependencies()

SDF_API std::set< std::string > GetCompositionAssetDependencies ( ) const

Return paths of all assets this layer depends on due to composition fields.

This includes the paths of all layers referred to by reference, payload, and sublayer fields in this layer. This function only returns direct composition dependencies of this layer, i.e. it does not recurse to find composition dependencies from its dependent layer assets.

◆ GetCustomLayerData()

SDF_API VtDictionary GetCustomLayerData ( ) const

Returns the CustomLayerData dictionary associated with this layer.

This is a dictionary is custom metadata that is associated with this layer. It allows users to encode any set of information for human or program consumption.

◆ GetDefaultPrim()

SDF_API TfToken GetDefaultPrim ( ) const

Return the defaultPrim metadata for this layer.

This field indicates the name or path of which prim should be targeted by a reference or payload to this layer that doesn't specify a prim path.

The default value is the empty token.

◆ GetDefaultPrimAsPath()

SDF_API SdfPath GetDefaultPrimAsPath ( ) const

Return this layer's default prim metadata interpreted as an absolute prim path regardless of whether it was authored as a root prim name or a prim path.

For example, if the authored default prim value is "rootPrim", return </rootPrim>. If the authored default prim value is "/path/to/non/root/prim", return </path/to/non/root/prim>. If the authored default prim value cannot be interpreted as a prim path, return the empty SdfPath.

The default value is an empty path.

◆ GetDetachedLayerRules()

static SDF_API const DetachedLayerRules & GetDetachedLayerRules ( )
static

Returns the current rules for the detached layer set.

◆ GetDisplayName()

SDF_API std::string GetDisplayName ( ) const

Returns the layer's display name.

The display name is the base filename of the identifier.

◆ GetDisplayNameFromIdentifier()

static SDF_API std::string GetDisplayNameFromIdentifier ( const std::string &  identifier)
static

Returns the display name for the given identifier, using the same rules as GetDisplayName.

◆ GetDocumentation()

SDF_API std::string GetDocumentation ( ) const

Returns the documentation string for this layer.

The default value for documentation is "".

◆ GetEndTimeCode()

SDF_API double GetEndTimeCode ( ) const

Returns the layer's end timeCode.

The start and end timeCode of a layer represent a suggested playback range.
However, time-varying content is not limited to the timeCode range of the layer.

The default value for endTimeCode is 0.

◆ GetExpressionVariables()

SDF_API VtDictionary GetExpressionVariables ( ) const

Returns the expression variables dictionary authored on this layer.

See Variable Expressions for more details.

◆ GetExternalAssetDependencies()

SDF_API std::set< std::string > GetExternalAssetDependencies ( ) const

Returns a set of resolved paths to all external asset dependencies the layer needs to generate its contents.

These are additional asset dependencies that are determined by the layer's file format and will be consulted during Reload() when determining if the layer needs to be reloaded. This specifically does not include dependencies related to composition, i.e. this will not include assets from references, payloads, and sublayers.

◆ GetExternalReferences()

SDF_API std::set< std::string > GetExternalReferences ( ) const
Deprecated:
Use GetCompositionAssetDependencies instead.

◆ GetField()

SDF_API VtValue GetField ( const SdfPath path,
const TfToken fieldName 
) const

Return the value for the given path and fieldName.

Returns an empty value if none is set.

◆ GetFieldAs()

T GetFieldAs ( const SdfPath path,
const TfToken fieldName,
const T &  defaultValue = T() 
) const
inline

Return the value for the given path and fieldName.

Returns the provided defaultValue value if none is set.

Definition at line 669 of file layer.h.

◆ GetFieldDictValueByKey()

SDF_API VtValue GetFieldDictValueByKey ( const SdfPath path,
const TfToken fieldName,
const TfToken keyPath 
) const

Return the value for the given path and fieldName at keyPath.

Returns an empty value if none is set. The keyPath is a ':'-separated path addressing an element in sub-dictionaries.

◆ GetFieldTypeid()

std::type_info const & GetFieldTypeid ( const SdfPath path,
const TfToken name 
) const
inline

Return the type of the value for name on spec path.

If no such field exists, return typeid(void).

Definition at line 622 of file layer.h.

◆ GetFileExtension()

SDF_API std::string GetFileExtension ( ) const

Returns the file extension to use for this layer.

If this layer was loaded from disk, it should match the extension of the file format it was loaded as; if this is an anonymous in-memory layer it will be the default extension.

◆ GetFileFormat()

SDF_API const SdfFileFormatConstPtr & GetFileFormat ( ) const

Returns the file format used by this layer.

◆ GetFileFormatArguments()

SDF_API const FileFormatArguments & GetFileFormatArguments ( ) const

Returns the file format-specific arguments used during the construction of this layer.

◆ GetFramePrecision()

SDF_API int GetFramePrecision ( ) const

Returns the layer's frame precision.

◆ GetFramesPerSecond()

SDF_API double GetFramesPerSecond ( ) const

Returns the layer's frames per second.

This makes an advisory statement about how the contained data can be most usefully consumed and presented. It's primarily an indication of the expected playback rate for the data, but a timeline editing tool might also want to use this to decide how to scale and label its timeline.

The default value for framesPerSecond is 24.

◆ GetHasOwnedSubLayers()

SDF_API bool GetHasOwnedSubLayers ( ) const

Returns true if the layer's sublayers are expected to have owners.

◆ GetHints()

SDF_API SdfLayerHints GetHints ( ) const

Return hints about the layer's current contents.

Any operation that dirties the layer will invalidate all hints.

See also
SdfLayerHints

◆ GetIdentifier()

SDF_API const std::string & GetIdentifier ( ) const

Returns the layer identifier.

◆ GetLoadedLayers()

static SDF_API SdfLayerHandleSet GetLoadedLayers ( )
static

Returns handles for all layers currently held by the layer registry.

◆ GetMetadata()

SDF_API SdfDataRefPtr GetMetadata ( ) const

Returns the data from the absolute root path of this layer.

◆ GetMutedLayers()

static SDF_API std::set< std::string > GetMutedLayers ( )
static

Returns the set of muted layer paths.

◆ GetNumSubLayerPaths()

SDF_API size_t GetNumSubLayerPaths ( ) const

Returns the number of sublayer paths (and offsets).

◆ GetObjectAtPath()

SDF_API SdfSpecHandle GetObjectAtPath ( const SdfPath path)

Returns the object at the given path.

There is no distinction between an absolute and relative path at the SdLayer level.

Returns NULL if there is no object at path.

◆ GetOwner()

SDF_API std::string GetOwner ( ) const

Returns the layer's owner.

◆ GetPrimAtPath()

SDF_API SdfPrimSpecHandle GetPrimAtPath ( const SdfPath path)

Returns the prim at the given path.

Returns NULL if there is no prim at path. This is simply a more specifically typed version of GetObjectAtPath().

◆ GetPropertyAtPath()

SDF_API SdfPropertySpecHandle GetPropertyAtPath ( const SdfPath path)

Returns a property at the given path.

Returns NULL if there is no property at path. This is simply a more specifically typed version of GetObjectAtPath().

◆ GetPseudoRoot()

SDF_API SdfPrimSpecHandle GetPseudoRoot ( ) const

Returns the layer's pseudo-root prim.

The layer's root prims are namespace children of the pseudo-root. The pseudo-root exists to make the namespace hierarchy a tree instead of a forest. This simplifies the implementation of some algorithms.

A layer always has a pseudo-root prim.

◆ GetRealPath()

SDF_API const std::string & GetRealPath ( ) const

Returns the resolved path for this layer.

This is equivalent to GetResolvedPath().GetPathString().

◆ GetRelationshipAtPath()

SDF_API SdfRelationshipSpecHandle GetRelationshipAtPath ( const SdfPath path)

Returns a relationship at the given path.

Returns NULL if there is no relationship at path. This is simply a more specifically typed version of GetObjectAtPath().

◆ GetRelocates()

SDF_API SdfRelocates GetRelocates ( ) const

Get the list of relocates specified in this layer's metadata.

Each individual relocate in the list is specified as a pair of \SdfPath where the first is the source path of the relocate and the second is target path.

Note that is NOT a proxy object and cannot be used to edit the field in place.

◆ GetRepositoryPath()

SDF_API const std::string & GetRepositoryPath ( ) const

Returns the layer identifier in asset path form.

In the presence of a properly configured path resolver, the asset path is a double-slash prefixed depot path. If the path resolver is not configured, the asset path of a layer is empty.

◆ GetResolvedPath()

SDF_API const ArResolvedPath & GetResolvedPath ( ) const

Returns the resolved path for this layer.

This is the path where this layer exists or may exist after a call to Save().

◆ GetRootPrimOrder()

SDF_API SdfNameOrderProxy GetRootPrimOrder ( ) const

Returns the list of prim names for this layer's reorder rootPrims statement.

See SetRootPrimOrder() for more info.

◆ GetRootPrims()

SDF_API RootPrimsView GetRootPrims ( ) const

Returns a vector of the layer's root prims.

◆ GetSchema()

SDF_API const SdfSchemaBase & GetSchema ( ) const

Returns the schema this layer adheres to.

This schema provides details about the scene description that may be authored in this layer.

◆ GetSessionOwner()

SDF_API std::string GetSessionOwner ( ) const

Returns the layer's session owner.

Note: This should only be used by session layers.

◆ GetSpecType()

SDF_API SdfSpecType GetSpecType ( const SdfPath path) const

Return the spec type for path.

This returns SdfSpecTypeUnknown if no spec exists at path.

◆ GetStartTimeCode()

SDF_API double GetStartTimeCode ( ) const

Returns the layer's start timeCode.

The start and end timeCodes of a layer represent the suggested playback range. However, time-varying content is not limited to the timeCode range of the layer.

The default value for startTimeCode is 0.

◆ GetStateDelegate()

SDF_API SdfLayerStateDelegateBasePtr GetStateDelegate ( ) const

Returns the state delegate used to manage this layer's authoring state.

◆ GetSubLayerOffset()

SDF_API SdfLayerOffset GetSubLayerOffset ( int  index) const

Returns the layer offset for the subLayer path at the given index.

◆ GetSubLayerOffsets()

SDF_API SdfLayerOffsetVector GetSubLayerOffsets ( ) const

Returns the layer offsets for all the subLayer paths.

◆ GetSubLayerPaths()

SDF_API SdfSubLayerProxy GetSubLayerPaths ( ) const

Returns a proxy for this layer's sublayers.

Sub-layers are the weaker layers directly included by this layer. They're in order from strongest to weakest and they're all weaker than this layer.

Edits through the proxy changes the sublayers. If this layer does not have any sublayers the proxy is empty.

Sub-layer paths are asset paths, and thus must contain valid asset path characters (UTF-8 without C0 and C1 controls). See SdfAssetPath for more details.

◆ GetTimeCodesPerSecond()

SDF_API double GetTimeCodesPerSecond ( ) const

Returns the layer's timeCodes per second.

Scales the time ordinate for samples contained in the file to seconds.
If timeCodesPerSecond is 24, then a sample at time ordinate 24 should be viewed exactly one second after the sample at time ordinate 0.

If this layer doesn't have an authored value for timeCodesPerSecond, but it does have an authored value for framesPerSecond, this method will return the value of framesPerSecond. This "dynamic fallback" allows layers to lock framesPerSecond and timeCodesPerSecond to the same value by specifying only framesPerSecond.

The default value of timeCodesPerSecond, used only if there is no authored value for either timeCodesPerSecond or framesPerSecond, is 24.

◆ GetVersion()

SDF_API const std::string & GetVersion ( ) const

Returns the asset system version of this layer.

If a layer is loaded from a location that is not version managed, or a configured asset system is not present when the layer is loaded or created, the version is empty. By default, asset version tracking is disabled; this method returns empty unless asset version tracking is enabled.

◆ HasColorConfiguration()

SDF_API bool HasColorConfiguration ( ) const

Returns true if color configuration metadata is set in this layer.

See also
GetColorConfiguration(), SetColorConfiguration()

◆ HasColorManagementSystem()

SDF_API bool HasColorManagementSystem ( ) const

Returns true if colorManagementSystem metadata is set in this layer.

See also
GetColorManagementSystem(), SetColorManagementSystem()

◆ HasCustomLayerData()

SDF_API bool HasCustomLayerData ( ) const

Returns true if CustomLayerData is authored on the layer.

◆ HasDefaultPrim()

SDF_API bool HasDefaultPrim ( )

Return true if the default prim metadata is set in this layer.

See GetDefaultPrim() and SetDefaultPrim().

◆ HasEndTimeCode()

SDF_API bool HasEndTimeCode ( ) const

Returns true if the layer has an endTimeCode opinion.

◆ HasExpressionVariables()

SDF_API bool HasExpressionVariables ( ) const

Returns true if expression variables are authored on this layer.

◆ HasField() [1/2]

SDF_API bool HasField ( const SdfPath path,
const TfToken fieldName,
VtValue value = NULL 
) const

Return whether a value exists for the given path and fieldName.

Optionally returns the value if it exists.

◆ HasField() [2/2]

bool HasField ( const SdfPath path,
const TfToken name,
T *  value 
) const
inline

Returns true if the object has a non-empty value with name name and type T.

If value ptr is provided, returns the value found.

Definition at line 602 of file layer.h.

◆ HasFieldDictKey() [1/2]

SDF_API bool HasFieldDictKey ( const SdfPath path,
const TfToken fieldName,
const TfToken keyPath,
VtValue value = NULL 
) const

Return whether a value exists for the given path and fieldName and keyPath.

The keyPath is a ':'-separated path addressing an element in sub-dictionaries. Optionally returns the value if it exists.

◆ HasFieldDictKey() [2/2]

bool HasFieldDictKey ( const SdfPath path,
const TfToken name,
const TfToken keyPath,
T *  value 
) const
inline

Returns true if the object has a non-empty value with name name and keyPath and type T.

If value ptr is provided, returns the value found. The keyPath is a ':'-separated path addressing an element in sub-dictionaries.

Definition at line 646 of file layer.h.

◆ HasFramePrecision()

SDF_API bool HasFramePrecision ( ) const

Returns true if the layer has a frames precision opinion.

◆ HasFramesPerSecond()

SDF_API bool HasFramesPerSecond ( ) const

Returns true if the layer has a frames per second opinion.

◆ HasOwner()

SDF_API bool HasOwner ( ) const

Returns true if the layer has an owner opinion.

◆ HasRelocates()

SDF_API bool HasRelocates ( ) const

Returns true if this layer's metadata has any relocates opinion, including that there should be no relocates (i.e.

an empty list). An empty list (no relocates) does not mean the same thing as a missing list (no opinion).

◆ HasSessionOwner()

SDF_API bool HasSessionOwner ( ) const

Returns true if the layer has a session owner opinion.

◆ HasSpec()

SDF_API bool HasSpec ( const SdfPath path) const

Return whether a spec exists at path.

◆ HasStartTimeCode()

SDF_API bool HasStartTimeCode ( ) const

Returns true if the layer has a startTimeCode opinion.

◆ HasTimeCodesPerSecond()

SDF_API bool HasTimeCodesPerSecond ( ) const

Returns true if the layer has a timeCodesPerSecond opinion.

◆ Import()

SDF_API bool Import ( const std::string &  layerPath)

Imports the content of the given layer path, replacing the content of the current layer.

Note: If the layer path is the same as the current layer's real path, no action is taken (and a warning occurs). For this case use Reload().

◆ ImportFromString()

SDF_API bool ImportFromString ( const std::string &  string)

Reads this layer from the given string.

Returns true if successful, otherwise returns false.

◆ InsertInRootPrimOrder()

SDF_API void InsertInRootPrimOrder ( const TfToken name,
int  index = -1 
)

Adds a new root prim name in the root prim order.

If the index is -1, the name is inserted at the end.

◆ InsertRootPrim()

SDF_API bool InsertRootPrim ( const SdfPrimSpecHandle &  prim,
int  index = -1 
)

Adds a new root prim at the given index.

If the index is -1, the prim is inserted at the end. The layer will take ownership of the prim, via a TfRefPtr. Returns true if successful, false if failed (for example, due to a duplicate name).

◆ InsertSubLayerPath()

SDF_API void InsertSubLayerPath ( const std::string &  path,
int  index = -1 
)

Inserts new sublayer path at the given index.

The default index of -1 means to insert at the end.

◆ IsAnonymous()

SDF_API bool IsAnonymous ( ) const

Returns true if this layer is an anonymous layer.

◆ IsAnonymousLayerIdentifier()

static SDF_API bool IsAnonymousLayerIdentifier ( const std::string &  identifier)
static

Returns true if the identifier is an anonymous layer unique identifier.

◆ IsDetached()

SDF_API bool IsDetached ( ) const

Returns true if this layer is detached from its serialized data store, false otherwise.

Detached layers are isolated from external changes to their serialized data.

◆ IsDirty()

SDF_API bool IsDirty ( ) const

Returns true if the layer is dirty, i.e.

has changed from its persistent representation.

◆ IsEmpty()

SDF_API bool IsEmpty ( ) const

Returns whether this layer has no significant data.

◆ IsIncludedByDetachedLayerRules()

static SDF_API bool IsIncludedByDetachedLayerRules ( const std::string &  identifier)
static

Returns whether the given layer identifier is included in the current rules for the detached layer set.

This is equivalent to GetDetachedLayerRules().IsIncluded(identifier).

◆ IsMuted() [1/2]

SDF_API bool IsMuted ( ) const

Returns true if the current layer is muted.

◆ IsMuted() [2/2]

static SDF_API bool IsMuted ( const std::string &  path)
static

Returns true if the specified layer path is muted.

◆ ListFields()

SDF_API std::vector< TfToken > ListFields ( const SdfPath path) const

Return the names of all the fields that are set at path.

◆ New()

static SDF_API SdfLayerRefPtr New ( const SdfFileFormatConstPtr &  fileFormat,
const std::string &  identifier,
const FileFormatArguments args = FileFormatArguments() 
)
static

Creates a new empty layer with the given identifier for a given file format class.

The new layer will not be dirty and will not be saved.

Additional arguments may be supplied via the args parameter. These arguments may control behavior specific to the layer's file format.

◆ OpenAsAnonymous()

static SDF_API SdfLayerRefPtr OpenAsAnonymous ( const std::string &  layerPath,
bool  metadataOnly = false,
const std::string &  tag = std::string() 
)
static

Load the given layer from disk as a new anonymous layer.

If the layer can't be found or loaded, an error is posted and a null layer is returned.

The anonymous layer does not retain any knowledge of the backing file on the filesystem.

metadataOnly is a flag that asks for only the layer metadata to be read in, which can be much faster if that is all that is required. Note that this is just a hint: some FileFormat readers may disregard this flag and still fully populate the layer contents.

An optional tag may be specified. See CreateAnonymous for details.

◆ PermissionToEdit()

SDF_API bool PermissionToEdit ( ) const

Returns true if the caller is allowed to modify the layer and false otherwise.

A layer may have to perform some action to acquire permission to be edited.

◆ PermissionToSave()

SDF_API bool PermissionToSave ( ) const

Returns true if the caller is allowed to save the layer to its existing fileName and false otherwise.

◆ QueryTimeSample()

bool QueryTimeSample ( const SdfPath path,
double  time,
T *  data 
) const
inline

Definition at line 1566 of file layer.h.

◆ Reload()

SDF_API bool Reload ( bool  force = false)

Reloads the layer from its persistent representation.

This restores the layer to a state as if it had just been created with FindOrOpen(). This operation is Undo-able.

The fileName and whether journaling is enabled are not affected by this method.

When called with force = false (the default), Reload attempts to avoid reloading layers that have not changed on disk. It does so by comparing the file's modification time (mtime) to when the file was loaded. If the layer has unsaved modifications, this mechanism is not used, and the layer is reloaded from disk. If the layer has any external asset dependencies their modification state will also be consulted when determining if the layer needs to be reloaded.

Passing true to the force parameter overrides this behavior, forcing the layer to be reloaded from disk regardless of whether it has changed.

◆ ReloadLayers()

static SDF_API bool ReloadLayers ( const std::set< SdfLayerHandle > &  layers,
bool  force = false 
)
static

Reloads the specified layers.

Returns false if one or more layers failed to reload.

See Reload() for a description of the force flag.

◆ RemoveFromMutedLayers()

static SDF_API void RemoveFromMutedLayers ( const std::string &  mutedPath)
static

Remove the specified path from the muted layers set.

◆ RemoveFromRootPrimOrder()

SDF_API void RemoveFromRootPrimOrder ( const TfToken name)

Removes a root prim name from the root prim order.

◆ RemoveFromRootPrimOrderByIndex()

SDF_API void RemoveFromRootPrimOrderByIndex ( int  index)

Removes a root prim name from the root prim order by index.

◆ RemoveInertSceneDescription()

SDF_API void RemoveInertSceneDescription ( )

Removes all scene description in this layer that does not affect the scene.

This method walks the layer namespace hierarchy and removes any prims and that are not contributing any opinions.

◆ RemovePrimIfInert()

SDF_API void RemovePrimIfInert ( SdfPrimSpecHandle  prim)

Removes scene description that does not affect the scene in the layer namespace beginning with prim.

Calling this method on a prim will only clean up prims with specifier 'over' that are not contributing any opinions. The prim will only be removed if all of its nameChildren are also inert. The hierarchy prim is defined in will be pruned up to the layer root for each successive inert parent that has specifier 'over'.

note: PrimSpecs that contain any PropertySpecs, even PropertySpecs with required fields only (see PropertySpec::HasRequiredFieldsOnly) are not considered inert, and thus the prim won't be removed.

◆ RemovePropertyIfHasOnlyRequiredFields()

SDF_API void RemovePropertyIfHasOnlyRequiredFields ( SdfPropertySpecHandle  prop)

Removes prop if it has only required fields (i.e.

is not contributing any opinions to the scene other than property instantiation).

The hierarchy prop is defined in will then be pruned up to the layer root for each successive inert parent.

◆ RemoveRootPrim()

SDF_API void RemoveRootPrim ( const SdfPrimSpecHandle &  prim)

Remove a root prim.

◆ RemoveSubLayerPath()

SDF_API void RemoveSubLayerPath ( int  index)

Removes sublayer path at the given index.

◆ Save()

SDF_API bool Save ( bool  force = false) const

Returns true if successful, false if an error occurred.

Returns false if the layer has no remembered file name or the layer type cannot be saved. The layer will not be overwritten if the file exists and the layer is not dirty unless force is true.

◆ ScheduleRemoveIfInert()

SDF_API void ScheduleRemoveIfInert ( const SdfSpec spec)

Cause spec to be removed if it no longer affects the scene when the last change block is closed, or now if there are no change blocks.

◆ SetColorConfiguration()

SDF_API void SetColorConfiguration ( const SdfAssetPath colorConfiguration)

Sets the color configuration asset-path for this layer.

◆ SetColorManagementSystem()

SDF_API void SetColorManagementSystem ( const TfToken cms)

Sets the color management system used to interpret the color configuration asset-path authored this layer.

◆ SetComment()

SDF_API void SetComment ( const std::string &  comment)

Sets the comment string for this layer.

◆ SetCustomLayerData()

SDF_API void SetCustomLayerData ( const VtDictionary value)

Sets the CustomLayerData dictionary associated with this layer.

◆ SetDefaultPrim()

SDF_API void SetDefaultPrim ( const TfToken name)

Set the default prim metadata for this layer.

The prim at this path will be targeted by a reference or a payload to this layer that doesn't specify a prim path. Note that this can be a name if it refers to a root prim, or a path to any prim in this layer. E.g. "rootPrim", "/path/to/non/root/prim" or "/rootPrim". See GetDefaultPrim().

◆ SetDetachedLayerRules()

static SDF_API void SetDetachedLayerRules ( const DetachedLayerRules mask)
static

Sets the rules specifying detached layers.

Newly-created or opened layers whose identifiers are included in rules will be opened as detached layers. Existing layers that are now included or no longer included will be reloaded. Any unsaved modifications to those layers will be lost.

This function is not thread-safe. It may not be run concurrently with any other functions that open, close, or read from any layers.

The detached layer rules are initially set to exclude all layers. This may be overridden by setting the environment variables SDF_LAYER_INCLUDE_DETACHED and SDF_LAYER_EXCLUDE_DETACHED to specify the initial set of include and exclude patterns in the rules. These variables can be set to a comma-delimited list of patterns. SDF_LAYER_INCLUDE_DETACHED may also be set to "*" to include all layers. Note that these environment variables only set the initial state of the detached layer rules; these values may be overwritten by subsequent calls to this function.

See SdfLayer::DetachedLayerRules::IsIncluded for details on how the rules are applied to layer identifiers.

◆ SetDocumentation()

SDF_API void SetDocumentation ( const std::string &  documentation)

Sets the documentation string for this layer.

◆ SetEndTimeCode()

SDF_API void SetEndTimeCode ( double  endTimeCode)

Sets the layer's end timeCode.

◆ SetExpressionVariables()

SDF_API void SetExpressionVariables ( const VtDictionary expressionVars)

Sets the expression variables dictionary for this layer.

◆ SetField() [1/2]

void SetField ( const SdfPath path,
const TfToken fieldName,
const T &  val 
)
inline

Set the value of the given path and fieldName.

Definition at line 693 of file layer.h.

◆ SetField() [2/2]

SDF_API void SetField ( const SdfPath path,
const TfToken fieldName,
const VtValue value 
)

Set the value of the given path and fieldName.

◆ SetFieldDictValueByKey() [1/2]

void SetFieldDictValueByKey ( const SdfPath path,
const TfToken fieldName,
const TfToken keyPath,
const T &  val 
)
inline

Set the value of the given path and fieldName.

The keyPath is a ':'-separated path addressing an element in sub-dictionaries.

Definition at line 722 of file layer.h.

◆ SetFieldDictValueByKey() [2/2]

SDF_API void SetFieldDictValueByKey ( const SdfPath path,
const TfToken fieldName,
const TfToken keyPath,
const VtValue value 
)

Set the value of the given path and fieldName.

The keyPath is a ':'-separated path addressing an element in sub-dictionaries.

◆ SetFramePrecision()

SDF_API void SetFramePrecision ( int  framePrecision)

Sets the layer's frame precision.

◆ SetFramesPerSecond()

SDF_API void SetFramesPerSecond ( double  framesPerSecond)

Sets the layer's frames per second.

◆ SetHasOwnedSubLayers()

SDF_API void SetHasOwnedSubLayers ( bool  )

Sets whether the layer's sublayers are expected to have owners.

◆ SetIdentifier()

SDF_API void SetIdentifier ( const std::string &  identifier)

Sets the layer identifier.

Note that the new identifier must have the same arguments (if any) as the old identifier.

◆ SetMuted()

SDF_API void SetMuted ( bool  muted)

Mutes the current layer if muted is true, and unmutes it otherwise.

◆ SetOwner()

SDF_API void SetOwner ( const std::string &  owner)

Sets the layer's owner.

◆ SetPermissionToEdit()

SDF_API void SetPermissionToEdit ( bool  allow)

Sets permission to edit.

◆ SetPermissionToSave()

SDF_API void SetPermissionToSave ( bool  allow)

Sets permission to save.

◆ SetRelocates()

SDF_API void SetRelocates ( const SdfRelocates relocates)

Set the entire list of namespace relocations specified on this layer to relocates.

◆ SetRootPrimOrder()

SDF_API void SetRootPrimOrder ( const std::vector< TfToken > &  names)

Given a list of (possible sparse) prim names, authors a reorder rootPrims statement for this prim.

This reorder statement can modify the order of root prims that have already been explicitly ordered with InsertRootPrim() or SetRootPrims(); but only during composition. Therefore, GetRootPrims(), InsertRootPrim(), SetRootPrims(), etc. do not read, author, or pay any attention to this statement.

◆ SetRootPrims()

SDF_API void SetRootPrims ( const SdfPrimSpecHandleVector &  rootPrims)

Sets a new vector of root prims.

You can re-order, insert and remove prims but cannot rename them this way. If any of the listed prims have an existing owner, they will be reparented.

◆ SetSessionOwner()

SDF_API void SetSessionOwner ( const std::string &  owner)

Sets the layer's session owner.

Note: This should only be used by session layers.

◆ SetStartTimeCode()

SDF_API void SetStartTimeCode ( double  startTimecode)

Sets the layer's start timeCode.

◆ SetStateDelegate()

SDF_API void SetStateDelegate ( const SdfLayerStateDelegateBaseRefPtr &  delegate)

Sets the state delegate used to manage this layer's authoring state.

The 'dirty' state of this layer will be transferred to the new delegate.

◆ SetSubLayerOffset()

SDF_API void SetSubLayerOffset ( const SdfLayerOffset offset,
int  index 
)

Sets the layer offset for the subLayer path at the given index.

◆ SetSubLayerPaths()

SDF_API void SetSubLayerPaths ( const std::vector< std::string > &  newPaths)

Sets the paths of the layer's sublayers.

◆ SetTimeCodesPerSecond()

SDF_API void SetTimeCodesPerSecond ( double  timeCodesPerSecond)

Sets the layer's timeCodes per second.

◆ SetTimeSample()

void SetTimeSample ( const SdfPath path,
double  time,
const T &  value 
)
inline

Definition at line 1593 of file layer.h.

◆ SplitIdentifier()

static SDF_API bool SplitIdentifier ( const std::string &  identifier,
std::string *  layerPath,
FileFormatArguments arguments 
)
static

Splits the given layer identifier into its constituent layer path and arguments.

◆ StreamsData()

SDF_API bool StreamsData ( ) const

Returns true if this layer streams data from its serialized data store on demand, false otherwise.

Layers with streaming data are treated differently to avoid pulling in data unnecessarily. For example, reloading a streaming layer will not perform fine-grained change notification, since doing so would require the full contents of the layer to be loaded.

◆ TransferContent()

SDF_API void TransferContent ( const SdfLayerHandle &  layer)

Copies the content of the given layer into this layer.

Source layer is unmodified.

◆ UpdateAssetInfo()

SDF_API void UpdateAssetInfo ( )

Update layer asset information.

Calling this method re-resolves the layer identifier, which updates asset information such as the layer's resolved path and other asset info. This may be used to update the layer after external changes to the underlying asset system.

◆ UpdateCompositionAssetDependency()

SDF_API bool UpdateCompositionAssetDependency ( const std::string &  oldAssetPath,
const std::string &  newAssetPath = std::string() 
)

Updates the asset path of a composation dependency in this layer.

If newAssetPath is supplied, the update works as "rename", updating any occurrence of oldAssetPath to newAssetPath in all reference, payload, and sublayer fields.

If newAssetPath is not given, this update behaves as a "delete", removing all occurrences of oldAssetPath from all reference, payload, and sublayer fields.

◆ UpdateExternalReference()

SDF_API bool UpdateExternalReference ( const std::string &  oldAssetPath,
const std::string &  newAssetPath = std::string() 
)
Deprecated:
Use UpdateCompositionAssetDependency instead.

Friends And Related Function Documentation

◆ SdfAttributeSpec

friend class SdfAttributeSpec
friend

Definition at line 2049 of file layer.h.

◆ SdfFileFormat

friend class SdfFileFormat
friend

Definition at line 2059 of file layer.h.

◆ SdfLayerStateDelegateBase

friend class SdfLayerStateDelegateBase
friend

Definition at line 2063 of file layer.h.

◆ SdfPropertySpec

friend class SdfPropertySpec
friend

Definition at line 2048 of file layer.h.

◆ SdfSpec

friend class SdfSpec
friend

Definition at line 2047 of file layer.h.


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