HdSceneIndexPluginRegistry Class Reference

A registry for renderer- and application-specific scene indices. More...

#include <sceneIndexPluginRegistry.h>

Inheritance diagram for HdSceneIndexPluginRegistry:

Public Types
enum	InsertionOrder { InsertionOrderAtStart , InsertionOrderAtEnd }
enum class	PluginOrderingPolicy { CppRegistrationOnly , JsonMetadataOnly , Hybrid }
	Enum to specify the policy for determining the order of scene index plugins. More...
using	InsertionPhase = int
using	SceneIndexAppendCallback = std::function< HdSceneIndexBaseRefPtr(const std::string &renderInstanceId, const HdSceneIndexBaseRefPtr &inputScene, const HdContainerDataSourceHandle &inputArgs)>

Public Member Functions
HD_API HdSceneIndexBaseRefPtr	AppendSceneIndex (const TfToken &sceneIndexPluginId, const HdSceneIndexBaseRefPtr &inputScene, const HdContainerDataSourceHandle &inputArgs, const std::string &renderInstanceId=std::string())
	Given a specific scene index plug-in id, give the plug-in a chance to add scene indices to the end of the chain.
HD_API HdSceneIndexBaseRefPtr	AppendSceneIndicesForRenderer (const std::string &rendererDisplayName, const HdSceneIndexBaseRefPtr &inputScene, const std::string &renderInstanceId=std::string(), const std::string &appName=std::string())
	Append scene indices generated by plug-ins registered (via RegisterSceneIndexForRenderer) for this renderer.
HD_API void	RegisterSceneIndexForRenderer (const std::string &rendererDisplayName, const TfToken &sceneIndexPluginId, const HdContainerDataSourceHandle &inputArgs, InsertionPhase insertionPhase, InsertionOrder insertionOrder)
	Register a scene index plugin to be instantiated for a specified renderer (or all renderers if rendererDisplayName is empty).
HD_API void	RegisterSceneIndexForRenderer (const std::string &rendererDisplayName, SceneIndexAppendCallback callback, const HdContainerDataSourceHandle &inputArgs, InsertionPhase insertionPhase, InsertionOrder insertionOrder)
	Register a scene index to be instantiated via a callback for a specified renderer (or all renderers if rendererDisplayName is empty).
HD_API std::vector< TfToken >	LoadAndGetSceneIndexPluginIds (const std::string &rendererDisplayName, const std::string &appName)
	Loads plugins for rendererDisplayName and appName.
bool	GetPluginInsertionMetadataForSceneIndex (const HdSceneIndexBaseRefPtr &sceneIndex, PluginInsertionMetadata &metadata)
	Gets metadata about the plugin that inserted the given scene index, if available.
HD_API void	SetPluginOrderingPolicy (PluginOrderingPolicy policy)
	Sets the policy for determining the order of scene index plugins.
Public Member Functions inherited from HfPluginRegistry
HF_API void	GetPluginDescs (HfPluginDescVector *plugins)
	Returns an ordered list of all registered plugins.
HF_API bool	GetPluginDesc (const TfToken &pluginId, HfPluginDesc *desc)
	Returns the description for the given plugin id.
HF_API void	AddPluginReference (HfPluginBase *plugin)
	Increment the reference count on an existing plugin.
HF_API void	ReleasePlugin (HfPluginBase *plugin)
	Decrement the reference count on the plugin.
HF_API bool	IsRegisteredPlugin (const TfToken &pluginId)
	Returns true if a plugin has been registered for the given id.
HF_API TfToken	GetPluginId (const HfPluginBase *plugin) const

Static Public Member Functions
static HD_API HdSceneIndexPluginRegistry &	GetInstance ()
	Returns the singleton registry for HdSceneIndexPlugin.
template<typename T , typename... Bases>
static void	Define ()
	Entry point for defining an HdSceneIndexPlugin plugin.

Protected Member Functions
void	_CollectAdditionalMetadata (const PlugRegistry &plugRegistry, const TfType &pluginType) override
	Gives subclasses an opportunity to inspect plugInfo-based metadata at the time of discovery.
Protected Member Functions inherited from HfPluginRegistry
HF_API	HfPluginRegistry (const TfType &pluginBaseType)
	Constructs a Plugin Registry.
HF_API HfPluginBase *	GetPlugin (const TfToken &pluginId)
	Returns the plugin from the given pluginId.
virtual HF_API void	_CollectAdditionalMetadata (const PlugRegistry &plugRegistry, const TfType &pluginType)
	Gives subclasses an opportunity to inspect plugInfo-based metadata at the time of discovery.

Friends
class	TfSingleton< HdSceneIndexPluginRegistry >

Additional Inherited Members
Static Protected Member Functions inherited from HfPluginRegistry
template<typename T , typename PluginBaseType , typename... Bases>
static void	Define ()
	Entry point for registering a types implementation.

Detailed Description

A registry for renderer- and application-specific scene indices.

Definition at line 39 of file sceneIndexPluginRegistry.h.

Member Typedef Documentation

InsertionPhase

using InsertionPhase = int

Definition at line 94 of file sceneIndexPluginRegistry.h.

SceneIndexAppendCallback

using SceneIndexAppendCallback = std::function< HdSceneIndexBaseRefPtr( const std::string &renderInstanceId, const HdSceneIndexBaseRefPtr &inputScene, const HdContainerDataSourceHandle &inputArgs)>

Definition at line 149 of file sceneIndexPluginRegistry.h.

Member Enumeration Documentation

InsertionOrder

enum InsertionOrder

Definition at line 88 of file sceneIndexPluginRegistry.h.

PluginOrderingPolicy

enum class PluginOrderingPolicy

strong

Enum to specify the policy for determining the order of scene index plugins.

This is primarily in service of testing, and to provide a pathway to deprecating the registration API in favor of JSON metadata-based ordering. The default is based off the environment setting HD_SCENE_INDEX_PLUGIN_ORDERING_POLICY_DEFAULT.

Enumerator
CppRegistrationOnly	The order of plugins is determined solely by the insertion phase/order arguments of the C++ registration API.
JsonMetadataOnly	The tags and ordering specified in the JSON metadata are used to drive the ordering of scene index plugins.
Hybrid	A hybrid ordering scheme where we attempt to honor both the insertion phase/order specified via the C++ registration API and the tags and ordering specified in the JSON metadata.

Definition at line 224 of file sceneIndexPluginRegistry.h.

Member Function Documentation

_CollectAdditionalMetadata()

void _CollectAdditionalMetadata ( const PlugRegistry &  plugRegistry, const TfType &  pluginType  )

overrideprotectedvirtual

Gives subclasses an opportunity to inspect plugInfo-based metadata at the time of discovery.

Reimplemented from HfPluginRegistry.

AppendSceneIndex()

HD_API HdSceneIndexBaseRefPtr AppendSceneIndex	(	const TfToken &	sceneIndexPluginId,
		const HdSceneIndexBaseRefPtr &	inputScene,
		const HdContainerDataSourceHandle &	inputArgs,
		const std::string &	renderInstanceId = std::string()
	)

Given a specific scene index plug-in id, give the plug-in a chance to add scene indices to the end of the chain.

Return value is the last scene index – or inputScene if the plug-in chooses not to act. Input arguments may be nullptr if not relevant to this plug-in.

AppendSceneIndicesForRenderer()

HD_API HdSceneIndexBaseRefPtr AppendSceneIndicesForRenderer	(	const std::string &	rendererDisplayName,
		const HdSceneIndexBaseRefPtr &	inputScene,
		const std::string &	renderInstanceId = std::string(),
		const std::string &	appName = std::string()
	)

Append scene indices generated by plug-ins registered (via RegisterSceneIndexForRenderer) for this renderer.

Return value is the last scene index – or inputScene if no plugins are registered or taking action. This also includes plug-ins registered for all renderers (via an empty rendererDisplayName) to be added in advance of any registered for the specified renderer.

Plugin libraries will only be loaded if they declare they are enabled for the provided app name. By default, plugins are auto-loaded for all apps, but plugin authors can put an preloadInApps array in their plugInfo to narrow down the set of applications they are auto-loaded for. Providing an empty app name here (the default) means this will not auto-load any application-specific plugin libraries.

Define()

void Define

static

Entry point for defining an HdSceneIndexPlugin plugin.

Definition at line 269 of file sceneIndexPluginRegistry.h.

GetInstance()

static HD_API HdSceneIndexPluginRegistry & GetInstance ( )

static

Returns the singleton registry for HdSceneIndexPlugin.

GetPluginInsertionMetadataForSceneIndex()

bool GetPluginInsertionMetadataForSceneIndex	(	const HdSceneIndexBaseRefPtr &	sceneIndex,
		PluginInsertionMetadata &	metadata
	)

Gets metadata about the plugin that inserted the given scene index, if available.

This is primarily intended for debugging and diagnostic use.

LoadAndGetSceneIndexPluginIds()

HD_API std::vector< TfToken > LoadAndGetSceneIndexPluginIds	(	const std::string &	rendererDisplayName,
		const std::string &	appName
	)

Loads plugins for rendererDisplayName and appName.

Returns the sceneIndexPluginId's in the order they'll be run. This does not include scene indices registered via the callback registration method.

This is primarily in service of tests.

RegisterSceneIndexForRenderer() [1/2]

HD_API void RegisterSceneIndexForRenderer	(	const std::string &	rendererDisplayName,
		const TfToken &	sceneIndexPluginId,
		const HdContainerDataSourceHandle &	inputArgs,
		InsertionPhase	insertionPhase,
		InsertionOrder	insertionOrder
	)

Register a scene index plugin to be instantiated for a specified renderer (or all renderers if rendererDisplayName is empty).

Note

The function name is misleading as this registers the plugin and not an instance of the scene index itself.

sceneIndexPluginId identifies the associated scene index plugin. This should match the name used in the plugInfo.json entry and is typically the class name (i.e. CPP type name). inputArgs is a container data source of arguments that is provided as a parameter to the scene index plugin's _AppendSceneIndex method. insertionPhase is a broad ordering value with lower values indicating earlier instantiation (possibly given render plugin-specific meaning via enum values). insertionOrder indicates whether this entry should go at the start or end of the specified phase.

Note

The plugInfo entry for a scene index plugin may have a "loadWithRenderer" key that specifies a list of renderer display names for which the plugin library should be loaded. This is separate from the registration of the scene index plugin for a renderer here, which is still necessary to have it be instantiated and be a part of the scene index graph that is built for that renderer.

This method is typically invoked via the TF_REGISTRY_FUNCTION macro at module load time, like:

TF_REGISTRY_FUNCTION(HdSceneIndexPlugin)
{
    HdSceneIndexPluginRegistry::GetInstance()
    .RegisterSceneIndexForRenderer(...);
}

This function may be invoked multiple times for the same sceneIndexPluginId to have multiple instances of the same set of scene indices inserted in _AppendSceneIndex at different points in the scene index graph.

RegisterSceneIndexForRenderer() [2/2]

HD_API void RegisterSceneIndexForRenderer	(	const std::string &	rendererDisplayName,
		SceneIndexAppendCallback	callback,
		const HdContainerDataSourceHandle &	inputArgs,
		InsertionPhase	insertionPhase,
		InsertionOrder	insertionOrder
	)

Register a scene index to be instantiated via a callback for a specified renderer (or all renderers if rendererDisplayName is empty).

This is most useful for application-specific behavior which wants to append and manage scene index instances associated with a specific render. To aid in that association, the callback is provided a renderInstanceId value typically defined by the application itself.

inputArgs is a container data source of arguments that is provided as a parameter to the scene index plugin's _AppendSceneIndex method. insertionPhase is a broad ordering value with lower values indicating earlier instantiation (possibly given render plugin-specific meaning via enum values). insertionOrder indicates whether this entry should go at the start or end of the specified phase.

Note

This method should be invoked before render index construction when Hydra scene index emulation is enabled.

Unlike the pattern for registering scene index plugins, it is better to invoke this method explicitly in application code rather than using a TF_REGISTRY_FUNCTION block.

SetPluginOrderingPolicy()

HD_API void SetPluginOrderingPolicy

(

PluginOrderingPolicy

policy

)

Sets the policy for determining the order of scene index plugins.

This is primarily in service of testing.

Friends And Related Function Documentation

TfSingleton< HdSceneIndexPluginRegistry >

friend class TfSingleton< HdSceneIndexPluginRegistry >

friend

Definition at line 248 of file sceneIndexPluginRegistry.h.

---

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

• pxr/imaging/hd/sceneIndexPluginRegistry.h