All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
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);
}
A context object that lets the UsdStage::Open() API read from or read from and write to a UsdStageCac...
A strongly concurrency safe collection of UsdStageRefPtr s, enabling sharing across multiple clients ...
Definition: stageCache.h:68
bool Contains(const UsdStageRefPtr &stage) const
Return true if stage is present in this cache, false otherwise.
Definition: stageCache.h:289
static USD_API UsdStageRefPtr Open(const std::string &filePath, InitialLoadSet load=LoadAll)
Attempt to find a matching existing stage in a cache if UsdStageCacheContext objects exist on the sta...

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 104 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 108 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 115 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 122 of file stageCacheContext.h.

Friends And Related Function Documentation

◆ UsdStage

friend class UsdStage
friend

Definition at line 126 of file stageCacheContext.h.


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