A scene index that caches data sources for specified locators on specified prim types. More...

#include <locatorCachingSceneIndex.h>

Inheritance diagram for HdsiLocatorCachingSceneIndex:

Public Member Functions
HD_API HdSceneIndexPrim	GetPrim (const SdfPath &primPath) const override
	Returns a pair of (prim type, datasource).

HD_API SdfPathVector	GetChildPrimPaths (const SdfPath &primPath) const override
	Returns the paths of all scene index prims located immediately below primPath.

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

virtual std::vector< HdSceneIndexBaseRefPtr >	GetInputScenes () const =0

Public Member Functions inherited from HdSceneIndexBase
HD_API void	AddObserver (const HdSceneIndexObserverPtr &observer)
	Adds an observer to this scene index.

HD_API void	RemoveObserver (const HdSceneIndexObserverPtr &observer)
	Removes an observer from this scene index; the given observer will no longer be forwarded notices.

virtual HdSceneIndexPrim	GetPrim (const SdfPath &primPath) const =0
	Returns a pair of (prim type, datasource).

virtual SdfPathVector	GetChildPrimPaths (const SdfPath &primPath) const =0
	Returns the paths of all scene index prims located immediately below primPath.

HdDataSourceBaseHandle	GetDataSource (const SdfPath &primPath, const HdDataSourceLocator &locator) const
	A convenience function: look up the object at primPath, and if successful return the datasource at locator within that prim.

HD_API void	SystemMessage (const TfToken &messageType, const HdDataSourceBaseHandle &args)
	Sends a message with optional arguments to this and any upstream input scene indices.

HD_API std::string	GetDisplayName () const
	Returns a value previously set by SetDisplayName.

HD_API void	SetDisplayName (const std::string &n)
	Allows for scene index instances to be identified in a more contextually relevant way.

HD_API void	AddTag (const TfToken &tag)
	Adds a specified tag token to a scene index instance.

HD_API void	RemoveTag (const TfToken &tag)
	Removes a specified tag token to a scene index instance.

HD_API bool	HasTag (const TfToken &tag) const
	Returns true if a specified tag token has been added to a scene index instance.

HD_API TfTokenVector	GetTags () const
	Returns all tag tokens currently added to a scene index instance.

Public Member Functions inherited from TfRefBase
	TfRefBase (TfRefBase const &)

TfRefBase &	operator= (TfRefBase const &)

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

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

void	SetShouldInvokeUniqueChangedListener (bool shouldCall)

Public Member Functions inherited from 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)
	Creates a new HdDependencyForwardingSceneIndex followed by a HdsiLocatorCachingSceneIndex.

static HD_API HdsiLocatorCachingSceneIndexRefPtr	New (HdSceneIndexBaseRefPtr const &inputScene, HdDataSourceLocator const &locatorToCache, TfToken const &primTypeToCache)
	Creates a new HdsiLocatorCachingSceneIndex.

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 void	_PrimsAdded (const HdSceneIndexBase &sender, const HdSceneIndexObserver::AddedPrimEntries &entries)=0

virtual void	_PrimsRemoved (const HdSceneIndexBase &sender, const HdSceneIndexObserver::RemovedPrimEntries &entries)=0

virtual void	_PrimsDirtied (const HdSceneIndexBase &sender, const HdSceneIndexObserver::DirtiedPrimEntries &entries)=0

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

const HdSceneIndexBaseRefPtr &	_GetInputSceneIndex () const
	Returns the input scene.

Protected Member Functions inherited from HdSceneIndexBase
HD_API void	_SendPrimsAdded (const HdSceneIndexObserver::AddedPrimEntries &entries)
	Notify attached observers of prims added to the scene.

HD_API void	_SendPrimsRemoved (const HdSceneIndexObserver::RemovedPrimEntries &entries)
	Notify attached observers of prims removed from the scene.

HD_API void	_SendPrimsDirtied (const HdSceneIndexObserver::DirtiedPrimEntries &entries)
	Notify attached observers of datasource invalidations from the scene.

HD_API void	_SendPrimsRenamed (const HdSceneIndexObserver::RenamedPrimEntries &entries)
	Notify attached observers of prims (and their descendents) which have been renamed or reparented.

HD_API bool	_IsObserved () const
	Returns whether the scene index has any registered observers; this information can be used to skip work preparing notices when there are no observers.

virtual HD_API void	_SystemMessage (const TfToken &messageType, const HdDataSourceBaseHandle &args)
	Implement in order to react directly to system messages sent from downstream.

Protected Member Functions inherited from 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.

Member Function Documentation

◆ _PrimsAdded()

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

overrideprotectedvirtual

Implements HdSingleInputFilteringSceneIndexBase.

◆ _PrimsDirtied()

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

overrideprotectedvirtual

Implements HdSingleInputFilteringSceneIndexBase.

◆ _PrimsRemoved()

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

overrideprotectedvirtual

Implements HdSingleInputFilteringSceneIndexBase.

◆ AddDependencyForwardingAndCache()

static HD_API HdSceneIndexBaseRefPtr 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

◆ GetChildPrimPaths()

HD_API SdfPathVector 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.

◆ GetPrim()

HD_API HdSceneIndexPrim 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.

◆ New()

static HD_API HdsiLocatorCachingSceneIndexRefPtr 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

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

Member Function Documentation

◆ _PrimsAdded()

◆ _PrimsDirtied()

◆ _PrimsRemoved()

◆ AddDependencyForwardingAndCache()

◆ GetChildPrimPaths()

◆ GetPrim()

◆ New()