#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

GusdStageCacheReader &	operator= (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_MicroNode *	GetStageMicroNode (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:

GusdStageCacheReader cache;
// 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 172 of file stageCache.h.

Member Typedef Documentation

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

Definition at line 175 of file stageCache.h.

Constructor & Destructor Documentation

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

inline

Construct a reader for the cache singleton.

Definition at line 178 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 331 of file stageCache.h.

const bool GusdStageCacheReader::_writer

protected

Definition at line 332 of file stageCache.h.

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

gusd/stageCache.h

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Accessors

Encapsulation

Member Data Documentation