UsdStageCacheContext Class Reference

A context object that lets the UsdStage::Open() API read from or read from and write to a UsdStageCache instance during a scope of execution. More...

#include <stageCacheContext.h>

Public Member Functions
	UsdStageCacheContext (UsdStageCache &cache)
	Bind a cache for calls to UsdStage::Open() to read from and write to.
	UsdStageCacheContext (Usd_NonPopulatingStageCacheWrapper holder)
	Bind a cache for calls to UsdStage::Open() to read from.
	UsdStageCacheContext (UsdStageCacheContextBlockType blockType)
	Disable cache use completely (with UsdBlockStageCaches) or only for writing (with UsdBlockStageCacheWrites).

Friends
class	UsdStage

Detailed Description

A context object that lets the UsdStage::Open() API read from or read from and write to a UsdStageCache instance during a scope of execution.

Code examples illustrate typical use:

{
    // A stage cache to work with.
    UsdStageCache stageCache;
 
    // Bind this cache.  UsdStage::Open() will attempt to find a matching
    // stage in the cache.  If none is found, it will open a new stage and
    // insert it into the cache.
    UsdStageCacheContext context(stageCache);
 
    // Since the cache is currently empty, this Open call will not find an
    // existing stage in the cache, but will insert the newly opened stage
    // in it.
    auto stage = UsdStage::Open(<args>);
 
    assert(stageCache.Contains(stage));
    
    // A subsequent Open() call with the same arguments will retrieve the
    // stage from cache.
    auto stage2 = UsdStage::Open(<args>);
    assert(stage2 == stage);
}

The UsdStage::Open() API examines caches in UsdStageCacheContexts that exist on the stack in the current thread in order starting with the most recently created (deepest in the stack) to the least recently created.

The UsdUseButDoNotPopulateCache() function makes a cache available for UsdStage::Open() to find stages in, but newly opened stages will not be published to it. This can be useful if you want to make use of a cache but cannot or do not wish to mutate that cache.

Passing UsdBlockStageCaches disables cache use entirely (as if no UsdStageCacheContexts exist on the stack), while UsdBlockStageCachePopulation disables writing to all bound caches (as if they were all established with UsdUseButDoNotPopulateCache()).

Threading note: Different threads have different call stacks, so UsdStageCacheContext objects that exist in one thread's stack do not influence calls to UsdStage::Open() from a different thread.

Definition at line 121 of file stageCacheContext.h.

Constructor & Destructor Documentation

UsdStageCacheContext() [1/3]

UsdStageCacheContext ( UsdStageCache &  cache )

inlineexplicit

Bind a cache for calls to UsdStage::Open() to read from and write to.

Definition at line 125 of file stageCacheContext.h.

UsdStageCacheContext() [2/3]

UsdStageCacheContext ( Usd_NonPopulatingStageCacheWrapper  holder )

inlineexplicit

Bind a cache for calls to UsdStage::Open() to read from.

See also

UsdUseButDoNotPopulateCache()

Definition at line 132 of file stageCacheContext.h.

UsdStageCacheContext() [3/3]

UsdStageCacheContext ( UsdStageCacheContextBlockType  blockType )

inlineexplicit

Disable cache use completely (with UsdBlockStageCaches) or only for writing (with UsdBlockStageCacheWrites).

Definition at line 139 of file stageCacheContext.h.

Friends And Related Function Documentation

UsdStage

friend class UsdStage

friend

Definition at line 143 of file stageCacheContext.h.

---

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

• pxr/usd/usd/stageCacheContext.h