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
UsdNotice::ObjectsChanged Class Reference

Notice sent in response to authored changes that affect UsdObjects. More...

#include <notice.h>

+ Inheritance diagram for UsdNotice::ObjectsChanged:

Classes

class  PathRange
 An iterable range of paths to objects that have changed. More...
 

Public Member Functions

bool AffectedObject (const UsdObject &obj) const
 Return true if obj was possibly affected by the layer changes that generated this notice.
 
USD_API bool ResyncedObject (const UsdObject &obj) const
 Return true if obj was resynced by the layer changes that generated this notice.
 
USD_API bool ResolvedAssetPathsResynced (const UsdObject &obj) const
 Return true if asset path values in obj were resynced by the layer changes that generated this notice.
 
USD_API bool ChangedInfoOnly (const UsdObject &obj) const
 Return true if obj was changed but not resynced by the layer changes that generated this notice.
 
USD_API PathRange GetResyncedPaths () const
 Return the set of paths that are resynced in lexicographical order.
 
USD_API PathRange GetChangedInfoOnlyPaths () const
 Return the set of paths that have only info changes (those that do not affect the structure of cached UsdPrims on a UsdStage) in lexicographical order.
 
USD_API PathRange GetResolvedAssetPathsResyncedPaths () const
 Return the set of paths affected by changes that may cause asset path values to resolve to different locations, even though the asset path authored in scene description has not changed.
 
USD_API TfTokenVector GetChangedFields (const UsdObject &obj) const
 Return the set of changed fields in layers that affected obj.
 
USD_API TfTokenVector GetChangedFields (const SdfPath &path) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
USD_API bool HasChangedFields (const UsdObject &obj) const
 Return true if there are any changed fields that affected obj, false otherwise.
 
USD_API bool HasChangedFields (const SdfPath &path) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
- Public Member Functions inherited from UsdNotice::StageNotice
USD_API StageNotice (const UsdStageWeakPtr &stage)
 
const UsdStageWeakPtr & GetStage () const
 Return the stage associated with this notice.
 
- Public Member Functions inherited from TfNotice
TF_API size_t Send () const
 Deliver the notice to interested listeners, returning the number of interested listeners.
 
template<typename SenderPtr >
size_t Send (SenderPtr const &s) const
 Deliver the notice to interested listeners, returning the number of interested listeners.
 
TF_API size_t SendWithWeakBase (const TfWeakBase *senderWeakBase, const void *senderUniqueId, const std::type_info &type) const
 Variant of Send() that takes a specific sender in the form of a TfWeakBase pointer and a typeid.
 

Friends

class UsdStage
 

Additional Inherited Members

- Public Types inherited from TfNotice
typedef TfWeakPtr< ProbeWeakProbePtr
 
typedef std::vector< KeyKeys
 A TfNotice::Key container.
 
- Static Public Member Functions inherited from TfNotice
static TF_API void InsertProbe (const WeakProbePtr &probe)
 Register a probe that will be invoked when notices are sent and delivered.
 
static TF_API void RemoveProbe (const WeakProbePtr &probe)
 Remove a probe that was previously registered with InsertProbe.
 
template<class LPtr , class MethodPtr >
static TfNotice::Key Register (LPtr const &listener, MethodPtr method)
 Register a listener as being interested in a TfNotice.
 
template<class LPtr , class MethodPtr , class SenderPtr >
static TfNotice::Key Register (LPtr const &listener, MethodPtr method, SenderPtr const &sender)
 
template<class LPtr , class MethodPtr >
static TfNotice::Key Register (LPtr const &listener, MethodPtr method, const TfType &noticeType, const TfAnyWeakPtr &sender)
 
static TF_API bool Revoke (TfNotice::Key &key)
 Revoke interest by a listener.
 
static TF_API void Revoke (TfNotice::Keys *keys)
 Revoke interest by listeners.
 

Detailed Description

Notice sent in response to authored changes that affect UsdObjects.

The kinds of object changes are divided into these categories:

  • Object resync:

    "Resyncs" are potentially structural changes that invalidate entire subtrees of UsdObjects (including prims and properties). For example, if the path "/foo" is resynced, then all subpaths like "/foo/bar" and "/foo/bar.baz" may be arbitrarily changed.

    When a prim is resynced, say "/foo/bar", it might have been created or destroyed. Indication of possible changes flows down the resynced prim namespace, implicitly via prim resync notices. We do not consider the parent "/foo" to be resynced, as this would incorrectly imply that some or all of "/foo/bar"'s siblings (and their descendants) have also changed. Additionally, we do not propagate change indication to objects associated with the changed object through relationships or connections.

  • Resolved asset path resync:

    "Resolved asset path resyncs" invalidate asset paths in a subtree of objects. Asset paths authored anywhere in this subtree of objects (e.g. as attribute or metadata values) may now resolve to different locations, even though the asset path authored in scene description has not changed.

  • Changed info:

    "Changed-info" means that a nonstructural change has occurred, like an attribute value change or a value change to a metadata field not related to composition. Unlike resyncs, changed-info notices for an object do not imply that the subtree beneath that object have changed.

This notice provides API for two client use-cases. Clients interested in testing whether specific objects are affected by the changes should use the methods that return a bool, like AffectedObject(). Clients that wish to reason about all changes as a whole should use the methods that return a PathRange, like GetResyncedPaths().

Definition at line 111 of file notice.h.

Member Function Documentation

◆ AffectedObject()

bool AffectedObject ( const UsdObject obj) const
inline

Return true if obj was possibly affected by the layer changes that generated this notice.

This is the case if either the object is subject to a resync or has changed info. Equivalent to:

USD_API bool ResolvedAssetPathsResynced(const UsdObject &obj) const
Return true if asset path values in obj were resynced by the layer changes that generated this notice...
USD_API bool ChangedInfoOnly(const UsdObject &obj) const
Return true if obj was changed but not resynced by the layer changes that generated this notice.
USD_API bool ResyncedObject(const UsdObject &obj) const
Return true if obj was resynced by the layer changes that generated this notice.

Definition at line 139 of file notice.h.

◆ ChangedInfoOnly()

USD_API bool ChangedInfoOnly ( const UsdObject obj) const

Return true if obj was changed but not resynced by the layer changes that generated this notice.

This is the case if this object's exact path is present in GetChangedInfoOnlyPaths().

◆ GetChangedFields() [1/2]

USD_API TfTokenVector GetChangedFields ( const SdfPath path) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ GetChangedFields() [2/2]

USD_API TfTokenVector GetChangedFields ( const UsdObject obj) const

Return the set of changed fields in layers that affected obj.

This set will be empty for objects whose paths are not in GetResyncedPaths() or GetChangedInfoOnlyPaths().

If a field is present in this set, it does not necessarily mean the composed value of that field on obj has changed. For example, if a metadata value on obj is overridden in a stronger layer and is changed in a weaker layer, that field will appear in this set. However, since the value in the stronger layer did not change, the composed value returned by GetMetadata() will not have changed.

◆ GetChangedInfoOnlyPaths()

USD_API PathRange GetChangedInfoOnlyPaths ( ) const

Return the set of paths that have only info changes (those that do not affect the structure of cached UsdPrims on a UsdStage) in lexicographical order.

Info changes do not imply entire subtree invalidation, so this set is not minimal regarding ancestors and descendants, as opposed to GetResyncedPaths(). For example, both the paths '/foo' and '/foo/bar' may appear in this set.

Note
The "only" in "changed info only paths" was historically meant to distinguish these paths from the object resync paths returned by GetResyncedPaths, since the former is subsumed by the latter. It is now slightly misleading; paths in "changed info only" are still subsumed by "object resync" paths, but are not subsumed by other types of changes, like "resolved asset path resyncs".

◆ GetResolvedAssetPathsResyncedPaths()

USD_API PathRange GetResolvedAssetPathsResyncedPaths ( ) const

Return the set of paths affected by changes that may cause asset path values to resolve to different locations, even though the asset path authored in scene description has not changed.

For example, asset paths using expression variables may be invalidated when a variable value is modified, even though the authored asset paths have not changed. The set of paths are returned in lexicographical order.

Resolved asset path resyncs imply invalidation of asset paths within entire subtrees including all descendant prims and properties, so this set is minimal regarding ancestors and descendants. For example, if the path '/foo' appears in this set, all asset paths in the entire subtree at '/foo' are invalidated, so the path '/foo/bar' will not appear, but asset paths on that prim should be considered invalidated.

◆ GetResyncedPaths()

USD_API PathRange GetResyncedPaths ( ) const

Return the set of paths that are resynced in lexicographical order.

Resyncs imply entire subtree invalidation of all descendant prims and properties, so this set is minimal regarding ancestors and descendants. For example, if the path '/foo' appears in this set, the entire subtree at '/foo' is resynced so the path '/foo/bar' will not appear, but it should be considered resynced.

Since object resyncs fully invalidate entire subtrees, this set of paths subsumes all other paths. For example, if the path '/foo' appears in this set, but an attribute value was changed at '/foo/bar.x', this notice will only contain '/foo' in the set returned by this path and empty sets from all other functions. This is because the change to '/foo/bar.x' is implied by the resync of '/foo'.

◆ HasChangedFields() [1/2]

USD_API bool HasChangedFields ( const SdfPath path) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ HasChangedFields() [2/2]

USD_API bool HasChangedFields ( const UsdObject obj) const

Return true if there are any changed fields that affected obj, false otherwise.

See GetChangedFields for more details.

◆ ResolvedAssetPathsResynced()

USD_API bool ResolvedAssetPathsResynced ( const UsdObject obj) const

Return true if asset path values in obj were resynced by the layer changes that generated this notice.

This is the case if the object's path or an ancestor path is present in GetResolvedAssetPathsResyncedPaths().

◆ ResyncedObject()

USD_API bool ResyncedObject ( const UsdObject obj) const

Return true if obj was resynced by the layer changes that generated this notice.

This is the case if the object's path or an ancestor path is present in GetResyncedPaths().

Friends And Related Function Documentation

◆ UsdStage

friend class UsdStage
friend

Definition at line 117 of file notice.h.


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