#include <locatorCachingSceneIndex.h>

Inheritance diagram for HdsiLocatorCachingSceneIndex:

Classes
class	_DataSource

Public Member Functions
HD_API	~HdsiLocatorCachingSceneIndex () override

HD_API HdSceneIndexPrim	GetPrim (const SdfPath &primPath) const override

HD_API SdfPathVector	GetChildPrimPaths (const SdfPath &primPath) const override

Public Member Functions inherited from HdSingleInputFilteringSceneIndexBase
HD_API std::vector < HdSceneIndexBaseRefPtr >	GetInputScenes () const final

Public Member Functions inherited from HdSceneIndexBase
HD_API	HdSceneIndexBase ()

HD_API	~HdSceneIndexBase () override

HD_API void	AddObserver (const HdSceneIndexObserverPtr &observer)

HD_API void	RemoveObserver (const HdSceneIndexObserverPtr &observer)

HdDataSourceBaseHandle	GetDataSource (const SdfPath &primPath, const HdDataSourceLocator &locator) const

HD_API void	SystemMessage (const TfToken &messageType, const HdDataSourceBaseHandle &args)

HD_API std::string	GetDisplayName () const

HD_API void	SetDisplayName (const std::string &n)

HD_API void	AddTag (const TfToken &tag)

HD_API void	RemoveTag (const TfToken &tag)

HD_API bool	HasTag (const TfToken &tag) const

HD_API TfTokenVector	GetTags () const

Public Member Functions inherited from TfRefBase
	TfRefBase ()

	TfRefBase (TfRefBase const &)

TfRefBase &	operator= (TfRefBase const &)

size_t	GetCurrentCount () const
	Return the current reference count of this object. More...

bool	IsUnique () const
	Return true if only one `TfRefPtr` points to this object. More...

void	SetShouldInvokeUniqueChangedListener (bool shouldCall)

Public Member Functions inherited from TfWeakBase
	TfWeakBase ()

	TfWeakBase (const TfWeakBase &)

const TfWeakBase &	__GetTfWeakBase__ () const

const TfWeakBase &	operator= (const TfWeakBase &)

void	EnableNotification2 () const

TF_API void const *	GetUniqueIdentifier () const

Static Public Member Functions
static HD_API HdSceneIndexBaseRefPtr	AddDependencyForwardingAndCache (HdSceneIndexBaseRefPtr const &inputScene, HdDataSourceLocator const &locatorToCache, TfToken const &primTypeToCache)

static HD_API HdsiLocatorCachingSceneIndexRefPtr	New (HdSceneIndexBaseRefPtr const &inputScene, HdDataSourceLocator const &locatorToCache, TfToken const &primTypeToCache)

Static Public Member Functions inherited from TfRefBase
static TF_API void	SetUniqueChangedListener (UniqueChangedListener listener)

Protected Member Functions
HD_API	HdsiLocatorCachingSceneIndex (HdSceneIndexBaseRefPtr const &inputScene, HdDataSourceLocator const &locatorToCache, TfToken const &primTypeToCache)

void	_PrimsAdded (const HdSceneIndexBase &sender, const HdSceneIndexObserver::AddedPrimEntries &entries) override

void	_PrimsRemoved (const HdSceneIndexBase &sender, const HdSceneIndexObserver::RemovedPrimEntries &entries) override

void	_PrimsDirtied (const HdSceneIndexBase &sender, const HdSceneIndexObserver::DirtiedPrimEntries &entries) override

HdDataSourceBaseHandle	_GetWithCache (SdfPath const &primPath, HdDataSourceLocator const &locator, HdContainerDataSourceHandle const &inputDataSource) const

Protected Member Functions inherited from HdSingleInputFilteringSceneIndexBase
HD_API	HdSingleInputFilteringSceneIndexBase (const HdSceneIndexBaseRefPtr &inputSceneIndex)

virtual HD_API void	_PrimsRenamed (const HdSceneIndexBase &sender, const HdSceneIndexObserver::RenamedPrimEntries &entries)

const HdSceneIndexBaseRefPtr &	_GetInputSceneIndex () const

Protected Member Functions inherited from HdSceneIndexBase
HD_API void	_SendPrimsAdded (const HdSceneIndexObserver::AddedPrimEntries &entries)

HD_API void	_SendPrimsRemoved (const HdSceneIndexObserver::RemovedPrimEntries &entries)

HD_API void	_SendPrimsDirtied (const HdSceneIndexObserver::DirtiedPrimEntries &entries)

HD_API void	_SendPrimsRenamed (const HdSceneIndexObserver::RenamedPrimEntries &entries)

HD_API bool	_IsObserved () const

virtual HD_API void	_SystemMessage (const TfToken &messageType, const HdDataSourceBaseHandle &args)

Protected Member Functions inherited from TfRefBase
virtual TF_API	~TfRefBase ()

Protected Member Functions inherited from TfWeakBase
	~TfWeakBase ()

TfRefPtr< Tf_Remnant >	_Register () const

template<class T >
TfRefPtr< Tf_Remnant >	_Register (T *tempRmnt) const

bool	_HasRemnant () const

Additional Inherited Members
Public Types inherited from TfRefBase
typedef void(*	UniqueChangedFuncPtr )(TfRefBase const *, bool)

Detailed Description

A scene index that caches data sources for specified locators on specified prim types. This avoids redundant computation when scene indexes query the same locator on the same prims multiple times.

Caching Scenarios in Hydra Scene Indexes

The basic purpose of Hydra scene indexes is to transmit scene information to a renderer. In the simplest idealized form this can be thought of as a for() loop over the scene contents. In this single-traversal scenario, there is no need for scene indexes to internally cache data that would be visisted only once. In practice, however, several situations motivate some degree of caching.

The first is when scene indexes access data in other prims. A common example is resolving material bindings, which reads information from the material bound to each geometry prim. If the same material is bound to multiple prims it will be read multiple times. This pattern occurs in any binding-like concept.

Another inter-prim dependency situation is flattening. Hydra scene indexes present flat data to the renderer, without further implied hierarchical transformation of data. Since many input scene descriptions heavily rely on hierarchical structure of data, such as for xforms, a flattening scene index is used. In this situation, sibling prims access a shared parent multiple times.

A third case is repeated access to the same data source by distinct scene indexes in sequence. For example, there might be a series of scene indexes that analyze and modify a material network. In such cases, it may be preferable to cache intermediate state(s) of the material network to avoid re-running a growing series of transformations as downstream scene indexes each traverse the incoming material network.

A fourth case is interactive use when locator-based invalidation granularity is insufficient to avoid repeated computation. For example, some consumers of a scene index may not be able to retain full granularity of individual primvar updates, and instead collapse all primvar invalidation into a single "dirty bit". Observers of the dirty bit will have no choice but to re-query all primvars, widening the computation. Caching can avoid incurring undue extra cost.

In each of these situations, the appropriate scope of cache is distinct. This is why Hydra does not provide built-in "one size fits all" caching and instead encourages specific approaches based on the need.

Cache Implementation with HdsiLocatorCachingSceneIndex

HdsiLocatorCachingSceneIndex provides a response to these needs. It is a configurable, targeted cache to support specific cases where memoizing multiple-access to the same data is appropriate.

Scene index plugins should insert HdsiLocatorCachingSceneIndex instances, configured appropriately, based on the known structure of their computations: either caching input dependencies or their outputs.

For computations that pull on upstream prims from scene-defined paths, such as material bindings, it may be appropriate to insert a caching index immedately before the resolving scene index, configured according to the prim types and locators it depends upon.

In other cases it may be appropriate to append a caching index directly after the scene index producing an expensive result, if that result is expected to be accessed broadly or repeatedly.

Flattening is a special case where the scene index wants to compute a value on a prim, cache it, and then re-use that in comptutations on child prims. HdFlatteningSceneIndex, rather than HdsiLocatorCachingSceneIndex, is appropriate for such cases.

Cache Invalidation

HdsiLocatorCachingSceneIndex relies on PrimsDirtied notification to invalidate internal cache state correctly.

There are two approaches to dependency invalidation in Hydra.

The first is that a scene index may directly propagate invalidation to dependent prims and locators inside its PrimsDirtied notification handler.

The second is that a scene index can overlay the HdDependencySchema, and express its dependencies in that form. This approach relies on a downsteam HdDependencyForwardingSceneIndex to observe those dependnecies, and propagate invalidation to dependent prims and locators based on the provided dependency data.

Since HdsiLocatorCachingSceneIndex has no way of knowing what approach is used by upstream scene indexes, a straightforward way to achieve correct cache invalidation is by inserting a HdDependencyForwardingSceneIndex directly before the HdsiLocatorCachingSceneIndex in the scene index chain. The method AddDependencyForwardingAndLocatorCache() does this.

Note that this does rely on upstream scene indexes properly implementing one or the other of the two approaches above.

Internal Runtime State Caching

The discussion above pertains to caching the scene index data produced by a scene index and seen by observers. Some scene index implementations contain internal runtime state (as C++ member variables or thread-safe/protected global state).

Maintaining integrity of internal runtime cache state is the responsibility of the scene index, and this will require handling inside change notification methods. Such state is not addressed by the dependency schema or HdDependencyForwardingSceneIndex.

Definition at line 140 of file locatorCachingSceneIndex.h.

Constructor & Destructor Documentation

HD_API HdsiLocatorCachingSceneIndex::~HdsiLocatorCachingSceneIndex ( )

override

HD_API HdsiLocatorCachingSceneIndex::HdsiLocatorCachingSceneIndex	(	HdSceneIndexBaseRefPtr const &	inputScene,
		HdDataSourceLocator const &	locatorToCache,
		TfToken const &	primTypeToCache
	)

protected

Member Function Documentation

HdDataSourceBaseHandle HdsiLocatorCachingSceneIndex::_GetWithCache	(	SdfPath const &	primPath,
		HdDataSourceLocator const &	locator,
		HdContainerDataSourceHandle const &	inputDataSource
	)		const

protected

void HdsiLocatorCachingSceneIndex::_PrimsAdded	(	const HdSceneIndexBase &	sender,
		const HdSceneIndexObserver::AddedPrimEntries &	entries
	)

overrideprotectedvirtual

Implements HdSingleInputFilteringSceneIndexBase.

void HdsiLocatorCachingSceneIndex::_PrimsDirtied	(	const HdSceneIndexBase &	sender,
		const HdSceneIndexObserver::DirtiedPrimEntries &	entries
	)

overrideprotectedvirtual

Implements HdSingleInputFilteringSceneIndexBase.

void HdsiLocatorCachingSceneIndex::_PrimsRemoved	(	const HdSceneIndexBase &	sender,
		const HdSceneIndexObserver::RemovedPrimEntries &	entries
	)

overrideprotectedvirtual

Implements HdSingleInputFilteringSceneIndexBase.

static HD_API HdSceneIndexBaseRefPtr HdsiLocatorCachingSceneIndex::AddDependencyForwardingAndCache	(	HdSceneIndexBaseRefPtr const &	inputScene,
		HdDataSourceLocator const &	locatorToCache,
		TfToken const &	primTypeToCache
	)

static

Creates a new HdDependencyForwardingSceneIndex followed by a HdsiLocatorCachingSceneIndex.

See Also: New() for parameter documentation

HD_API SdfPathVector HdsiLocatorCachingSceneIndex::GetChildPrimPaths ( const SdfPath & primPath ) const

overridevirtual

Returns the paths of all scene index prims located immediately below primPath. This function can be used to traverse the scene by recursing from SdfPath::AbsoluteRootPath. The traveral is expected to give exactly the set of paths where prim exists as defined in GetPrim. The traversal is also expected to give the same set of prims as the flattening of the scene index's PrimsAdded and PrimsRemoved messages.

This function is expected to be threadsafe.

Implements HdSceneIndexBase.

HD_API HdSceneIndexPrim HdsiLocatorCachingSceneIndex::GetPrim ( const SdfPath & primPath ) const

overridevirtual

Returns a pair of (prim type, datasource). A prim exists at primPath if and only if datasource is a non-null pointer. In particular, we consider the prim to exist even if the prim type or the container that datasource points to is empty.

Note that we require GetChildPrimPaths to be consistent with this notion of prim existence. That is, unless primPath is the absolute root path, the prim at primPath exists if and only if primPath is contained in GetChildPrimPaths of the parent path.

This function is expected to be threadsafe.

Implements HdSceneIndexBase.

static HD_API HdsiLocatorCachingSceneIndexRefPtr HdsiLocatorCachingSceneIndex::New	(	HdSceneIndexBaseRefPtr const &	inputScene,
		HdDataSourceLocator const &	locatorToCache,
		TfToken const &	primTypeToCache
	)

static

Creates a new HdsiLocatorCachingSceneIndex.

Note: AddDependencyForwardingAndLocatorCache() is recommended for most uses. See class notes regarding cache invalidation.

Parameters

inputScene	The upstream input scene index to cache
locatorToCache	The data source locator to cache; for example, HdMaterialSchema::GetDefaultLocator(). Must not be empty.
primTypeToCache	If specified, caching only applies to prims of this data type; if empty token, caching applies to all prim types

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

pxr/imaging/hdsi/locatorCachingSceneIndex.h

Classes

Public Member Functions

Static Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Caching Scenarios in Hydra Scene Indexes

Cache Implementation with HdsiLocatorCachingSceneIndex

Cache Invalidation

Internal Runtime State Caching

Constructor & Destructor Documentation

Member Function Documentation