Scene index that prunes prims whose resolved (flattened) purpose is not in the configured set of accepted purposes. More...

#include <purposeFilteringSceneIndex.h>

Inheritance diagram for HdsiPurposeFilteringSceneIndex:

Public Member Functions
HDSI_API void	SetPurposes (VtArray< TfToken > const &purposes)
	Switch to explicit (accept-list) mode and set the accepted purposes.

HDSI_API VtArray< TfToken > const &	GetPurposes () const

HDSI_API HdSceneIndexPrim	GetPrim (const SdfPath &primPath) const override
	Returns a pair of (prim type, datasource).

HDSI_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

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

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 HDSI_API HdsiPurposeFilteringSceneIndexRefPtr	New (HdSceneIndexBaseRefPtr const &inputSceneIndex, HdContainerDataSourceHandle const &inputArgs)
	`The` fields in `inputArgs` that this scene index consumes are:

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

Protected Member Functions
HDSI_API void	_PrimsAdded (const HdSceneIndexBase &sender, const HdSceneIndexObserver::AddedPrimEntries &entries) override

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

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

HDSI_API	HdsiPurposeFilteringSceneIndex (HdSceneIndexBaseRefPtr const &inputSceneIndex, HdContainerDataSourceHandle const &inputArgs)

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
	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 TfRefBase
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

Scene index that prunes prims whose resolved (flattened) purpose is not in the configured set of accepted purposes.

Pruned prims are not removed from the scene index; instead, they are given an empty primType. This preserves hierarchy and allows children of pruned prims to still exist, which is important because they may have a different resolved purpose.

modes

This scene index operates in one of two modes:

Hint mode (the initial mode): The inputArgs container passed to New() is queried via HdSceneIndexCreateArgsSchema for the excludedPurposesHint field. If the field is present, prims whose resolved purpose appears in the hint are pruned. If the field is absent, no prims are pruned. This allows a renderer to declare which purposes it does not consume (e.g. proxy, guide) and have the scene index honor that automatically, without requiring an explicit call to SetPurposes() which can be expensive because it may require a full traversal of the input scene. This is because this scene index is currently stateless.

Explicit mode: Calling SetPurposes() exits hint mode and switches to an accept-list: only prims whose resolved purpose is in the provided array are kept; an empty array disables filtering entirely. The inputArgs container may also seed this mode directly by supplying the purposes key (HdsiPurposeFilteringSceneIndexTokens->purposes), in which case the scene index starts in explicit mode at construction time. This may be useful for non-interactive (aka batch) rendering scenarios where the renderable set of purposes is known and fixed.

Note: This scene index should be placed after an HdFlatteningSceneIndex instance with a HdFlattenedPurposeDataSourceProvider so that purpose has already been resolved through ancestor inheritance before this index queries it.

(Hydra 1) notes

Hydra 1 refers to the USD purpose as "render tag". Only HdRprim types have a render tag ( HdRprim::GetRenderTag). Purpose filtering happens during the sync phase ( HdRprim::Sync ) based on the render tags aggregated from the tasks ( HdTask::GetRenderTags ).

The USD "default" purpose maps to HdRenderTagTokens->geometry.

Physics Parsing Utils Overview.

UsdGeomImageable introduces the purpose attribute. The inheritance rules are as follows (from the "Rendering with USD" guide on OpenUSD):

"If a prim does not have an authored purpose but has an ancestor that may have an authored purpose, the rules about how the ancestor purpose is inherited at render-time are as follows: If a prim is not imageable or does not have an authored opinion about its own purpose, then it will inherit the purpose of the closest imageable ancestor with an authored purpose opinion. If there are no imageable ancestors with an authored purpose opinion then the prim uses its fallback purpose."

This behavior is provided by the HdFlattenedPurposeDataSourceProvider.

See also: HdRenderTagTokens; HdSceneIndexCreateArgsSchema

Definition at line 91 of file purposeFilteringSceneIndex.h.

Member Function Documentation

◆ _PrimsAdded()

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

overrideprotectedvirtual

Implements HdSingleInputFilteringSceneIndexBase.

◆ _PrimsDirtied()

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

overrideprotectedvirtual

Implements HdSingleInputFilteringSceneIndexBase.

◆ _PrimsRemoved()

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

overrideprotectedvirtual

Implements HdSingleInputFilteringSceneIndexBase.

◆ GetChildPrimPaths()

HDSI_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()

HDSI_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 HDSI_API HdsiPurposeFilteringSceneIndexRefPtr New	(	HdSceneIndexBaseRefPtr const &	inputSceneIndex,
		HdContainerDataSourceHandle const &	inputArgs )

static

The fields in inputArgs that this scene index consumes are:

excludedPurposesHint, a HdTokenArrayDataSource under HdSceneIndexCreateArgsSchema::GetSchemaToken()) and
purposes, also a HdTokenArrayDataSource

They dictate whether the initial operating mode of the scene index is in hint mode or explicit mode.

◆ SetPurposes()

HDSI_API void SetPurposes ( VtArray< TfToken > const & purposes )

Switch to explicit (accept-list) mode and set the accepted purposes.

Prims whose resolved purpose is not in this array will be pruned (primType set to empty). An empty array disables purpose filtering (no prims are pruned). Once called, hint mode is no longer active.

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

pxr/imaging/hdsi/purposeFilteringSceneIndex.h

Public Member Functions

Static Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

modes

(Hydra 1) notes

Physics Parsing Utils Overview.

Member Function Documentation

◆ _PrimsAdded()

◆ _PrimsDirtied()

◆ _PrimsRemoved()

◆ GetChildPrimPaths()

◆ GetPrim()

◆ New()

◆ SetPurposes()