HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
GusdStageCacheReader Class Reference

#include <stageCache.h>

+ Inheritance diagram for GusdStageCacheReader:

Public Types

using PrimStagePair = std::pair< UsdPrim, UsdStageRefPtr >
 

Public Member Functions

 GusdStageCacheReader (GusdStageCache &cache=GusdStageCache::GetInstance())
 Construct a reader for the cache singleton. More...
 
 GusdStageCacheReader (const GusdStageCacheReader &)=delete
 
GusdStageCacheReaderoperator= (const GusdStageCacheReader &)=delete
 
 ~GusdStageCacheReader ()
 
UsdStageRefPtr Find (const UT_StringRef &path, const GusdStageOpts &opts=GusdStageOpts::LoadAll(), const GusdStageEditPtr &edit=nullptr) const
 Find an existing stage on the cache. More...
 
UsdStageRefPtr FindOrOpen (const UT_StringRef &path, const GusdStageOpts &opts=GusdStageOpts::LoadAll(), const GusdStageEditPtr &edit=nullptr, UT_ErrorSeverity sev=UT_ERROR_ABORT)
 
void InsertStage (UsdStageRefPtr &stage, const UT_StringRef &path, const GusdStageOpts &opts, const GusdStageEditPtr &edit)
 
DEP_MicroNodeGetStageMicroNode (const UsdStagePtr &stage)
 
PrimStagePair GetPrim (const UT_StringRef &path, const SdfPath &primPath, const GusdStageEditPtr &stageEdit=GusdStageEditPtr(), const GusdStageOpts &opts=GusdStageOpts::LoadAll(), UT_ErrorSeverity sev=UT_ERROR_ABORT)
 
bool GetPrims (const GusdDefaultArray< UT_StringHolder > &filePaths, const UT_Array< SdfPath > &primPaths, const GusdDefaultArray< GusdStageEditPtr > &edits, UsdPrim *prims, const GusdStageOpts &opts=GusdStageOpts::LoadAll(), UT_ErrorSeverity sev=UT_ERROR_ABORT)
 
PrimStagePair GetPrimWithVariants (const UT_StringRef &path, const SdfPath &primPath, const GusdStageOpts &opts=GusdStageOpts::LoadAll(), UT_ErrorSeverity sev=UT_ERROR_ABORT)
 
PrimStagePair GetPrimWithVariants (const UT_StringRef &path, const UT_StringRef &primPath, const GusdStageOpts &opts=GusdStageOpts::LoadAll(), UT_ErrorSeverity sev=UT_ERROR_ABORT)
 
PrimStagePair GetPrimWithVariants (const UT_StringRef &path, const SdfPath &primPath, const SdfPath &variants, const GusdStageOpts &opts=GusdStageOpts::LoadAll(), UT_ErrorSeverity sev=UT_ERROR_ABORT)
 Different variations of the above the variants are stored separately. More...
 
PrimStagePair GetPrimWithVariants (const UT_StringRef &path, const UT_StringRef &primPath, const UT_StringRef &variants, const GusdStageOpts &opts=GusdStageOpts::LoadAll(), UT_ErrorSeverity sev=UT_ERROR_ABORT)
 

Protected Member Functions

 GusdStageCacheReader (GusdStageCache &cache, bool writer)
 

Protected Attributes

GusdStageCache_cache
 
const bool _writer
 

Detailed Description

Helper for reading from a GusdStageCache. Cache readers can both open existing stages on the cache, as well as cause additional stages to be inserted into the cache. Cache readers cannot clear out any existing stages or mutate auxiliary data caches.

Example usage:

// Pull a stage from the cache.
UsdStageRefPtr stage = cache.FindOrOpen(stagePath);
// Access a prim on the cache.
UsdPrim prim = cache.GetPrim(stagePath, primPath).first;
// Access a prim with a variant selection.
SdfPath primPath("/foo{variant=sel}bar");
UsdPrim prim = cache.GetPrim(stagePath, primPath);

Definition at line 169 of file stageCache.h.

Member Typedef Documentation

using GusdStageCacheReader::PrimStagePair = std::pair<UsdPrim,UsdStageRefPtr>

Definition at line 172 of file stageCache.h.

Constructor & Destructor Documentation

GusdStageCacheReader::GusdStageCacheReader ( GusdStageCache cache = GusdStageCache::GetInstance())
inline

Construct a reader for the cache singleton.

Definition at line 175 of file stageCache.h.

GusdStageCacheReader::GusdStageCacheReader ( const GusdStageCacheReader )
delete
GusdStageCacheReader::~GusdStageCacheReader ( )
GusdStageCacheReader::GusdStageCacheReader ( GusdStageCache cache,
bool  writer 
)
protected

Member Function Documentation

UsdStageRefPtr GusdStageCacheReader::Find ( const UT_StringRef path,
const GusdStageOpts opts = GusdStageOpts::LoadAll(),
const GusdStageEditPtr edit = nullptr 
) const

Find an existing stage on the cache.

UsdStageRefPtr GusdStageCacheReader::FindOrOpen ( const UT_StringRef path,
const GusdStageOpts opts = GusdStageOpts::LoadAll(),
const GusdStageEditPtr edit = nullptr,
UT_ErrorSeverity  sev = UT_ERROR_ABORT 
)

Return a stage from the cache, if one exists. If not, attempt to open the stage and add it to the cache. If path is a non-empty path and stage opening fails, errors are reporting to the currently scoped error manager at a severity of sev.

PrimStagePair GusdStageCacheReader::GetPrim ( const UT_StringRef path,
const SdfPath primPath,
const GusdStageEditPtr stageEdit = GusdStageEditPtr(),
const GusdStageOpts opts = GusdStageOpts::LoadAll(),
UT_ErrorSeverity  sev = UT_ERROR_ABORT 
)

Accessors

These helpers return prims on masked stages, where only the parts of the stage required to produce a given prim are composed. This helps support workflows such as setting variants on packed prims, where either many stage mutations may be made that conflict with each other, or in isolation, such that different mutations can't be made to share stages without intrusive locking. In all cases, if a full stage which satisfies the stage options and edits has already been loaded on the cache, the prim will fetched from that stage instead.

This use of masking may be disabled by way of the GUSD_STAGEMASK_ENABLE environment variable, but beware that doing so may significantly degrade performance for certain access patterns, such as if many separate prims are being queried from the cache with different stage edits.

Encapsulation

Because primitives are masked to include a subset of a stage, there is an expectation that the caller follows encapsulation rules. When we read in a prim, we consider that prim to be encapsulated, which means that if any other primitives from the stage are required to process an encapsulated primitive, they are expected to either be descendants or ancestors of the encapsulated prim, or the dependency to that external prim must be discoverable using either relationships or attribute connections. Following those encapsulation rules, neither siblings of the prim being requested, nor other prims in separate branches of the stage are guaranteed to be loaded. Any attempt to reach other prims that can't be discovered using the above rules for discovering dependencies may either fail or introduce non-deterministic behavior. Get a prim from the cache, on a masked stage. If path and primPath are both valid, and either a stage load error occurs or no prim can be found, errors are reported on the currently scoped error manager at a severity of sev. If primPath is equal to 'defaultPrim', the stage's defaultPrim is returned. If primPath is equal to '/', the entire stage is loaded, and the pseudo-root is returned.

bool GusdStageCacheReader::GetPrims ( const GusdDefaultArray< UT_StringHolder > &  filePaths,
const UT_Array< SdfPath > &  primPaths,
const GusdDefaultArray< GusdStageEditPtr > &  edits,
UsdPrim prims,
const GusdStageOpts opts = GusdStageOpts::LoadAll(),
UT_ErrorSeverity  sev = UT_ERROR_ABORT 
)

Get multiple prims from the cache (in parallel). If the configured error severity is less than UT_ERROR_ABORT, prim loading will continue even after load errors have occurred. If any stage load errors occur, or if any prims cannot be found, errors are reported on the currently scoped error manager with a severity of sev. If sev is less than UT_ERROR_ABORT, prim loading will continue even when errors occur for some prims. Otherwise, loading aborts upon the first error. If a path in primPaths is equal to defaultPrim, the stage's defaultPrim will be returned for that element. If a path in primPaths is equal to / – I.e., the absolute root – then the full stage of the corresponding element is loaded, and the pseudo-root is returned.

PrimStagePair GusdStageCacheReader::GetPrimWithVariants ( const UT_StringRef path,
const SdfPath primPath,
const GusdStageOpts opts = GusdStageOpts::LoadAll(),
UT_ErrorSeverity  sev = UT_ERROR_ABORT 
)

Get a prim from the cache, given a prim path that may contain variant selections. This is a convenience method for the common case of accessing a prim given parameters for just a file path and prim path. If primPath is equal to 'defaultPrim', the stage's defaultPrim is returned. If primPath is equal to /, the entire stage is loaded, and the pseudo-root is returned.

PrimStagePair GusdStageCacheReader::GetPrimWithVariants ( const UT_StringRef path,
const UT_StringRef primPath,
const GusdStageOpts opts = GusdStageOpts::LoadAll(),
UT_ErrorSeverity  sev = UT_ERROR_ABORT 
)

Get a prim from the cache, given a prim path that may contain variant selections. This is a convenience method for the common case of accessing a prim given parameters for just a file path and prim path. If primPath is equal to 'defaultPrim', the stage's defaultPrim is returned. If primPath is equal to /, the entire stage is loaded, and the pseudo-root is returned.

PrimStagePair GusdStageCacheReader::GetPrimWithVariants ( const UT_StringRef path,
const SdfPath primPath,
const SdfPath variants,
const GusdStageOpts opts = GusdStageOpts::LoadAll(),
UT_ErrorSeverity  sev = UT_ERROR_ABORT 
)

Different variations of the above the variants are stored separately.

PrimStagePair GusdStageCacheReader::GetPrimWithVariants ( const UT_StringRef path,
const UT_StringRef primPath,
const UT_StringRef variants,
const GusdStageOpts opts = GusdStageOpts::LoadAll(),
UT_ErrorSeverity  sev = UT_ERROR_ABORT 
)

Get a prim from the cache, given a prim path that may contain variant selections. This is a convenience method for the common case of accessing a prim given parameters for just a file path and prim path. If primPath is equal to 'defaultPrim', the stage's defaultPrim is returned. If primPath is equal to /, the entire stage is loaded, and the pseudo-root is returned.

DEP_MicroNode* GusdStageCacheReader::GetStageMicroNode ( const UsdStagePtr &  stage)

Get a micro node for a stage. Micro nodes are created on demand, and are dirtied both for stage reloading and cache evictions.

void GusdStageCacheReader::InsertStage ( UsdStageRefPtr &  stage,
const UT_StringRef path,
const GusdStageOpts opts,
const GusdStageEditPtr edit 
)

Insert a stage into our cache. The lifetime of this stage is not fully controlled by this cache. The cache is just a holder for the stage for as long as the gusd library is allowed access to it until it is destroyed by the external owner, which must then call Clear() with the same path.

GusdStageCacheReader& GusdStageCacheReader::operator= ( const GusdStageCacheReader )
delete

Member Data Documentation

GusdStageCache& GusdStageCacheReader::_cache
protected

Definition at line 328 of file stageCache.h.

const bool GusdStageCacheReader::_writer
protected

Definition at line 329 of file stageCache.h.


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