USD Locators

group FnUsdBaseLocator

class SceneNode

#include <FnUsdBaseLocator.h>

A scene node in the scene tree that holds the required information for drawing the associated USD Prim.

Public Types

using Ptr = std::shared_ptr<SceneNode>

using WeakPtr = std::weak_ptr<SceneNode>

Public Functions

inline explicit SceneNode(usg::Path path = usg::Path::AbsoluteRootPath())

SceneNode(const SceneNode&) = delete

SceneNode(SceneNode&&) = delete

SceneNode &operator=(const SceneNode&) = delete

SceneNode &operator=(SceneNode&&) = delete

inline ~SceneNode()

inline const Ptr &getParentNode() const

inline const usg::Path &getPath() const

void setLocalXform(const Imath::M44d &localXform, bool localXformIsGlobal)

Sets the given transform in the node.

Recursively invalidates the transform of all descendants.

Parameters:

localXform – The transform to be set.
localXformIsGlobal – Whether the given transform is global.

Imath::M44d getOrComputeWorldXform()

Gets the world transform for the scene node.

In the first requests, ancestor nodes may be traversed to compute the world transform.

Returns:: The transform for scene node.

inline void setSkipped(const bool skipped)

inline bool isSkipped() const

void setSelected(bool selected, bool recursively)

inline bool isSelected() const

inline std::unordered_map<usg::Token, usg::Value> &getData()

inline const std::unordered_map<usg::Token, usg::Value> &getData() const

class Scene

#include <FnUsdBaseLocator.h>

A tree structure that holds the scene that locators will draw.

Public Functions

inline Scene()

~Scene() = default

Scene(const Scene&) = delete

Scene(Scene&&) = delete

Scene &operator=(const Scene&) = delete

Scene &operator=(Scene&&) = delete

inline const SceneNode::Ptr &getRootNode() const

Returns:: The root node of the scene.

SceneNode::Ptr getNode(const usg::Path &path) const

Finds the node associated with the given path.

Parameters:: path – The path to be searched for.
Returns:: The scene node associated with the path, or a null node if not found.

SceneNode::Ptr getOrCreateNode(const usg::Path &path)

Finds the node associated with the given path.

If the node cannot be found, it is created, along with all ancestor nodes if necessary.

Parameters:: path – The path to be searched for.
Returns:: The scene node associated with the path.

bool removeNode(const usg::Path &path)

Removes the target path and all its descendants.

Parameters:: path – The path to be searched for.
Returns:: true if the path was removed.

class FnUsdBaseLocator

Subclassed by ExampleUsdSpatialAudioLocator

Public Types

using Ptr = std::unique_ptr<FnUsdBaseLocator>

Public Functions

FnUsdBaseLocator() = default

virtual ~FnUsdBaseLocator() = default

FnUsdBaseLocator(const FnUsdBaseLocator&) = delete

FnUsdBaseLocator(FnUsdBaseLocator&&) = delete

FnUsdBaseLocator &operator=(const FnUsdBaseLocator&) = delete

FnUsdBaseLocator &operator=(FnUsdBaseLocator&&) = delete

virtual void setup() = 0: Called when the locator is initialized with a valid OpenGL context.

virtual void cleanup() = 0: Called before the locator is destroyed with a valid OpenGL context.

virtual bool matches(const ViewerAPI::ViewerUsdPrimEvent &event, const SceneNode::Ptr &node, bool matched) = 0

Determines whether the given scene node is to be handled by this locator.

Implementations of this virtual method can query attributes from the USD Prim (accessible from event) using the sample time (also accessible from event), and store any arbitrary data in the scene node (see SceneNode::getData()) that could be used at a later time during the draw call.

Parameters:

event – The USD Prim Event that trigger the creation or update of the scene node.
node – The scene node that has been created or updated.
matched – Whether any other locator has already matched this node.

Returns:

true if the locator matches the scene node (i.e. geometry will be drawn).

inline virtual void onFrameBegin(const bool picking)

Called at the beginning of each frame to allow batching of draws.

Only called if the locator has matched any scene node.

Parameters:: picking – Whether it is a picking draw call, or a regular draw call.

inline virtual void onFrameEnd(const bool picking)

Called at the end of each frame to allow batching of draws.

Only called if the locator has matched any scene node.

Parameters:: picking – Whether it is a picking draw call, or a regular draw call.

inline virtual void preDraw(const SceneNode::Ptr &node, const bool picking)

Pre-draw call.

Only called if the locator has previously matched the scene node (see matches()).

Parameters:

node – The scene node that is to be drawn.
picking – Whether it is a picking draw call, or a regular draw call.

inline virtual void postDraw(const SceneNode::Ptr &node, const bool picking)

Post-draw call.

Only called if the locator has previously matched the scene node (see matches()).

Parameters:

node – The scene node that is to be drawn.
picking – Whether it is a picking draw call, or a regular draw call.

virtual void draw(const SceneNode::Ptr &node, bool picking) = 0

Draws the locator for the given node.

Only called if the locator has previously matched the scene node (see matches()).

Parameters:

node – The scene node that is to be drawn.
picking – Whether it is a picking draw call, or a regular draw call.

inline virtual fdk::Box3d getBounds(const SceneNode::Ptr &node) const

Queries the bounds of the given node.

Only called if the locator has previously matched the scene node (see matches()).

Parameters:: node – The scene node being evaluated.
Returns:: The bounds for the given node.

GLShaderProgram &getDefaultShader()

Returns:: A reference to the default shader program owned by the ViewerDelegateComponent.

FnUsdBaseLocatorViewportLayer &getViewportLayer()

Returns:: A reference to the current viewport layer where the drawing is being performed.

class FnUsdBaseLocatorVDC : public Foundry::Katana::ViewerAPI::ViewerDelegateComponent 

Public Functions

~FnUsdBaseLocatorVDC() override = default

FnUsdBaseLocatorVDC(const FnUsdBaseLocatorVDC&) = delete

FnUsdBaseLocatorVDC(FnUsdBaseLocatorVDC&&) = delete

FnUsdBaseLocatorVDC &operator=(const FnUsdBaseLocatorVDC&) = delete

FnUsdBaseLocatorVDC &operator=(FnUsdBaseLocatorVDC&&) = delete

inline virtual void setup() override: Initializes the ViewportDelegateComponent’s resources.

inline virtual void cleanup() override: Cleans up the ViewportDelegateComponent’s resources.

inline virtual bool locationEvent(const ViewerAPI::ViewerLocationEvent &event, const bool locationHandled) override

Notification of scene graph location state changes.

Parameters:

event – Struct containing location event information (see “FnViewerLocationEvent.h” for details).
locationHandled – True if an already processed (later added) ViewerDelegateComponent has stated that it is handling this location by returning true. In this case, the ViewerDelegateComponent should not draw its own representation.

Returns:

true if the other ViewerDelegateComponents added to the ViewerDelegate before this one should receive locationHandled=true, false otherwise.

inline virtual void locationsSelected(const std::vector<std::string> &locations) override

Called when the location selection changes in Katana.

Parameters:: locationPaths – The selected location paths.

virtual bool usdPrimEvent(const ViewerAPI::ViewerUsdPrimEvent &event, bool handled) override

Notification of USD Prim state changes.

Parameters:

event – Struct containing the event information (i.e. a reference to the USD Prim, and whether it has been added or removed, or updated).
handled – true if another ViewerDelegateComponent with higher priority has stated, on processing this event, that it is handling the prim. In this case, this ViewerDelegateComponent should not draw its own representation.

Returns:

true if this ViewerDelegateComponent is handling the prim, making other ViewerDelegateComponents with lower priority receive this event with handled set to true.

virtual void usdPrimsSelected(const std::vector<std::string> &primPaths) override

Called when the USD Prim selection changes in Katana.

Parameters:: primPaths – The selected USD Prim paths.

virtual FnAttribute::DoubleAttribute getBounds(const std::string &locationPath) override

Gets the bounds of the given location.

Parameters:: locationPath – The location path.
Returns:: The bounds of the location (or an invalid attribute if not found).

virtual void setOption(ViewerAPI::OptionIdGenerator::value_type optionId, FnAttribute::Attribute attr) override

Sets a generic option.

Optional. Reacts to a generic option being set from Python or called directly by other C++ Viewer plugin classes. This can be used as a message passing mechanism from the outside into the ViewerDelegateComponent.

Parameters:

optionId – The ID of the option created from OptionIdGenerator or manually defined by users.
attr – Attribute with the value being set.

inline GLShaderProgram &getDefaultShader()

inline FnUsdBaseLocatorViewportLayer &getViewportLayer()

Public Static Functions

static inline ViewerAPI::ViewerDelegateComponent *create()

static inline void flush()

static inline void registerLocator(const std::function<FnUsdBaseLocator::Ptr()> &createFunction)

Registers a locator class.

Registered locators will be constructed when FnUsdBaseLocatorVDC is constructed.

Parameters:: createFunction – The function that can construct the locator.

class FnUsdBaseLocatorViewportLayer : public Foundry::Katana::ViewerAPI::ViewportLayer 

#include <FnUsdBaseLocator.h>

A viewport layer where the registered locators, via the FnUsdBaseLocatorVDC, will perform the drawing.

Public Functions

~FnUsdBaseLocatorViewportLayer() override = default

FnUsdBaseLocatorViewportLayer(const FnUsdBaseLocatorViewportLayer&) = delete

FnUsdBaseLocatorViewportLayer(FnUsdBaseLocatorViewportLayer&&) = delete

FnUsdBaseLocatorViewportLayer &operator=(const FnUsdBaseLocatorViewportLayer&) = delete

FnUsdBaseLocatorViewportLayer &operator=(FnUsdBaseLocatorViewportLayer&&) = delete

inline virtual void freeze() override

Freezes the ViewportLayer when the viewport widget is hidden.

Allows the ViewportLayer to freeze its activities when the viewport is not visible. This allows the ViewerDelegate to stop any kind of unecessary processing that might happen during that time.

inline virtual void thaw() override

Thaws the ViewportLayer when the viewport widget is shown.

Allows the ViewportLayer to restart its activities when the viewport becomes visible. This restarts the activities paused by freeze().

This function is exposed in the Viewport Python class.

virtual void setup() override

Initializes the GL components of the ViewportLayer.

Called when a ViewportLayer is created. It runs inside the correct GL context. Can be used to initialize anything GL related. For example, in the case of an OpenGL renderer this function should set up any required OpenGL context rendering flags, defining display lists, etc.

This function is exposed in the Viewport Python class.

virtual void cleanup() override

Cleans up the ViewportLayer resources.

Called when a ViewportLayer is removed by the ViewerDelegate.

virtual void draw() override

Draws the scene.

Called when the scene needs to be drawn in the correct GL context. In a non-GL renderer the generated image should be drawn in the GL framebuffer in order to be displayed. This will be also propagated through the ViewerLayers of this ViewportLayer.

This function is exposed in the ViewportLayer Python class.

virtual void pickerDraw(unsigned int x, unsigned int y, unsigned int w, unsigned int h, const ViewerAPI::PickedAttrsMap &ignoreAttrs) override

Draws an ID pass to be used by the optional internal picking.

This allows this layer to make use of the internal ID framebuffer pass technique provided to the Viewport and ViewportLayers. This function should draw all the pickable objects into the current GL framebuffer using an ID color. Inside this function each pickable object has to be registered using addPickableObject(), which will return a FnPickId. This id can be converted into a color using pickIdToColor() (see FnPickingTypes.h), the objects should be rendered without any kind of antialiasing and with that flat color, so that they cover their pickable pixels.

This will be called by Katana if customPick() returns false or if it is not implemented.

This function receives a list of Attributes that refer to pickable objects to be ignored in this render. This is internally used to do a multi-pass id render for deep picking, in which an onion peeling technique is used to detect all the occluded objects. On each iteration this function should not render the objects that were detected in previous iterations. These Attributes correspond to the ones passed previously to addPickableObject().

Parameters:

x – The region origin X component in viewport pixels.
y – The region origin Y component in viewport pixels.
w – The region width in viewport pixels.
h – The region height in viewport pixels.
ignoreAttrs – Map that contains information about the objects that should not be rendered here. PickedAttrsMap has the same public interface as std::map<FnPickId, FnAttributes::Attribute>.

inline virtual void resize(const unsigned int width, const unsigned int height) override

Processes viewport resizing.

Called when the viewport widget is resized. This can be extended by sub-clases to accomodate viewport size changes in the renderer.

virtual void setOption(ViewerAPI::OptionIdGenerator::value_type optionId, FnAttribute::Attribute attr) override

Sets a generic option.

Optional. Reacts to a generic option being set from Python or called directly by other C++ Viewer plugin classes. This can be used as a message passing mechanism from the outside into the ViewportLayer.

Parameters:

optionId – The ID of the option created from OptionIdGenerator or manually defined by users.
attr – Attribute with the value being set.

Public Static Functions

static inline ViewerAPI::ViewportLayer *create()