UsdStageCacheContext Class Reference

#include <stageCacheContext.h>

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.

---

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

• pxr/usd/usd/stageCacheContext.h