Foundry::Katana::ViewerAPI::ViewportLayer Class Reference

The ViewportLayer class to be extended by plugins. More...

#include <FnViewportLayer.h>

Inheritance diagram for Foundry::Katana::ViewerAPI::ViewportLayer:

List of all members.

Public Member Functions
	ViewportLayer (bool usePickingOnHover=false)
	Constructor.
virtual	~ViewportLayer ()
	Destructor.
virtual void	setup ()=0
	Initializes the GL components of the ViewportLayer.
virtual void	cleanup ()=0
	Cleans up the ViewportLayer resources.
virtual bool	event (const FnEventWrapper &eventData)
	Processes UI events.
virtual void	draw ()=0
	Draws the scene.
virtual void	resize (unsigned int width, unsigned int height)=0
	Processes viewport resizing.
virtual void	hover (bool isHovering, int x, int y)
	Called when the mouse hovers the ViewportLayer.
virtual void	freeze ()=0
	Freezes the ViewportLayer when the viewport widget is hidden.
virtual void	thaw ()=0
	Thaws the ViewportLayer when the viewport widget is shown.
virtual void *	getPrivateData (void *inputData)
	Returns some arbitrary data.
virtual void	setOption (OptionIdGenerator::value_type optionId, FnAttribute::Attribute attr)
	Sets a generic option.
virtual FnAttribute::Attribute	getOption (OptionIdGenerator::value_type optionId)
	Gets the value of a generic option.
void	setOption (const std::string &name, FnAttribute::Attribute attr)
	Sets a generic option by generating an option ID from the passed name.
FnAttribute::Attribute	getOption (const std::string &name)
	Gets a generic option by generating an option ID from the passed name.
bool	usesPickingOnHover ()
	Tells if the layer picks objects when the mouse is hovering them.
virtual void	pickerDraw (unsigned int x, unsigned int y, unsigned int w, unsigned int h, const PickedAttrsMap &ignoreAttrs)
	Draws an ID pass to be used by the optional internal picking.
virtual bool	customPick (unsigned int x, unsigned int y, unsigned int w, unsigned int h, bool deepPicking, PickedAttrsMap &pickedAttrs, float *singlePointDepth=NULL)
	Overrides the internal ID picking using a third party technique.
FnPickId	addPickableObject (FnAttribute::Attribute attr)
	Registers a pickable object during pickerDraw().
Static Public Member Functions
static void	flush ()
	Flush plugin Caches.

---

Detailed Description

The ViewportLayer class to be extended by plugins.

---

Constructor & Destructor Documentation

Foundry::Katana::ViewerAPI::ViewportLayer::ViewportLayer

(

bool

usePickingOnHover = false

)

Constructor.

Parameters:

usePickingOnHover

If true, then this layer will be calling pick() very frequently to detect if the mouse is hovering any pickable object. This can be used, for example, to highlight an object hovered by the mouse. This specifies that pickerDraw() will run right after any draw() call, so that the IDs readily available on each mouse move. If set to false, the ID pass render will only occur when pick() is called, which is more efficient.

---

Member Function Documentation

FnPickId Foundry::Katana::ViewerAPI::ViewportLayer::addPickableObject

(

FnAttribute::Attribute

attr

)

Registers a pickable object during pickerDraw().

This should be called inside pickerDraw() in order to let the internal ID picking system know about each pickable object.

The ID returned by this function can be used to both identify an object in some data structure implemented inside this plugin and to define the color to be used by the object when rendering itself in the current ID framebuffer in pickerDraw(), via the pickIdToColor() function (see FnPickingTypes.h). Also see FnGLShaderProgram.h, which implements a way of loading GLSL shaders.

The Attribute passed to this function can contain further information about the pickable object. For some generic cases there will be Attribute conventions that prescribe how this Attribute should be structured in order to be recognized as some typical objects. This allows some out-of-the-box or third party plugins, like other ViewportLayer plugins, to identify objects like, for example, a location:

• A location should be identified using a GroupAttribute containing at least a child StringAttribute named "location" and with a single value containing the full location path. This will be recognized by the ViewportLayer plugin "SelectionLayer" shipped with Katana, which is responsible for dealing with locations selection in the Viewer.

Any kind of rendered object, other than locations, can be pickable. For example, a handle of some overlay widget that can be manipulated using the mouse. For this, each Viewport will make use of some Attribute convention that is suitable to identify its own pickable objects.

The pick() function will return the FnPickID / Attribute pairs of all picked objects inside its region.

Parameters:

attr	The Attribute that describes the pickable object.

Returns:

A picking ID assigned to the pickable object.

virtual void Foundry::Katana::ViewerAPI::ViewportLayer::cleanup

(

)

[pure virtual]

Cleans up the ViewportLayer resources.

Called when a ViewportLayer is removed by the ViewerDelegate.

Implemented in Foundry::Katana::ViewerUtils::FnBaseLocatorViewportLayer, BallLayer, and ExampleSceneLayer.

virtual bool Foundry::Katana::ViewerAPI::ViewportLayer::customPick	(	unsigned int	x,
		unsigned int	y,
		unsigned int	w,
		unsigned int	h,
		bool	deepPicking,
		PickedAttrsMap &	pickedAttrs,
		float *	singlePointDepth = NULL
	)		[virtual]

Overrides the internal ID picking using a third party technique.

If the technology used in the Viewport implements its own picking, or if a GL ID pass is not feasible, then this function allows to override the internal ID picking and to implement the picking of what is present in the scene. If this is implemented and returns true, then pickerDraw() will never be called by Katana. This is called internally by pick(), which will return the returned values of this function.

An example of the use of this function is when using a non-realtime renderer that is able to produce its own ID pass or when the renderer data structures allows to query the geometry present inside the frustrum defined by the picking area.

There is no need to call addPickableObject() inside this function.

This should return a map of FnPickId to Attributes, similar to the one returned by pickerDraw(), which can identify or contain information about each picked objects. The

This can optionally return a depth value for when the picked region is one single pixel.

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.
	deepPicking	Specifies if all objects inside the region, including occluded ones, will be picked. If set to false, only the visible objects should be picked.
[out]	pickedAttrs	A map top be filled with FnPickId (key) to Attribute (value) pairs that represent the picked objects. Internally, this will be either populated by customPick() or by addPickableObject() calls inside pickerDraw(). PickedAttrsMap has the same public interface as std::map<FnPickId, FnAttributes::Attribute>.
[out]	singlePointDepth	The value pointed by this will be set with the GL depth of a single pixel when the region with and height are both 1 and this pointer is set to something other than NULL. This can be used to solve occlusion between picked objects from the Viewport and different ViewportLayers when, for example, the user clicks on a single pixel when selecting something.

virtual void Foundry::Katana::ViewerAPI::ViewportLayer::draw

(

)

[pure virtual]

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.

Implemented in Foundry::Katana::ViewerUtils::FnBaseLocatorViewportLayer, BallLayer, ExampleSpotlightLocatorViewportLayer, and ExampleSceneLayer.

virtual bool Foundry::Katana::ViewerAPI::ViewportLayer::event

(

const FnEventWrapper &

eventData

)

[inline, virtual]

Processes UI events.

Called whenever a user interaction event occurs. This will be also propagated through the ViewerLayers of this ViewportLayer.

Parameters:

eventData

The event data (see FnEventWrapper).

Returns:

True if the event has been handled, in that case it will not be passed to the following layers. Otherwise false and the event will be passed to the following layers.

Reimplemented in ExampleSceneLayer.

static void Foundry::Katana::ViewerAPI::ViewportLayer::flush

(

)

[inline, static]

Flush plugin Caches.

Allows to discard any cache for this plugin when a Flush Caches event occurs.

This function is exposed in the Viewport Python class.

virtual void Foundry::Katana::ViewerAPI::ViewportLayer::freeze

(

)

[pure virtual]

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.

Implemented in Foundry::Katana::ViewerUtils::FnBaseLocatorViewportLayer, BallLayer, and ExampleSceneLayer.

virtual FnAttribute::Attribute Foundry::Katana::ViewerAPI::ViewportLayer::getOption

(

OptionIdGenerator::value_type

optionId

)

[virtual]

Gets the value of a generic option.

Optional. Returns the value of a generic option being requested from Python or from other C++ Viewer plugin classes.

Parameters:

optionId

The ID of the option created from OptionIdGenerator or manually defined by users.

Returns:

Attribute with the value of the option.

FnAttribute::Attribute Foundry::Katana::ViewerAPI::ViewportLayer::getOption

(

const std::string &

name

)

Gets a generic option by generating an option ID from the passed name.

This generates an Option ID from the passed string and passes it to getOption(OptionIdGenerator::value_type optionId). Since the ID is generated on every call, it is more efficient to generate the ID once, and store it for future use.

Parameters:

name	The name of the option whose value to retrieve.

Returns:

The value of the option with the given name.

virtual void* Foundry::Katana::ViewerAPI::ViewportLayer::getPrivateData

(

void *

inputData

)

[inline, virtual]

Returns some arbitrary data.

This can be used by other plugins to access some data that is specific to this object after it is compiled, allowing built-in parts of existing Viewers to be extendable by other plugins like ViewerDelegateComponents, Viewports and ViewportLayers.

This function should be called by other plugins after getting a ManipulatorWrapperPtr and converting it into a concrete instance via ManipulatorWrapper::getPluginInstance(). These other plugins will have to be built with the same compiler and using the same compiler flags as the ViewerDelegate so that this data can be cast and used without running into C++ name mangling issues.

Parameters:

inputData

A pointer to some input data that can be used to produce the returned data.

Returns:

The arbitrary private data. A void pointer that can be cast into specific object types by other plugins.

virtual void Foundry::Katana::ViewerAPI::ViewportLayer::hover	(	bool	isHovering,
		int	x,
		int	y
	)		[inline, virtual]

Called when the mouse hovers the ViewportLayer.

The Viewport can detect when the mouse is hovering it so that, for example, objects under the mouse pointer can be highlighted. This is called with the correct GL context so that GL based picking can be executed.

Parameters:

isHovering	Flag that specifies if the mouse is hovering the viewport. If false, then the mouse left the viewport. In this case x and y should be ignored.
x	The horizontal pixel coordinate of the mouse pointer in the Viewport's local coordinate system.
y	The vertical pixel coordinate of the mouse pointer in the Viewport's local coordinate system.

Reimplemented from Foundry::Katana::ViewerAPI::ViewportLayerPluginBase.

virtual void Foundry::Katana::ViewerAPI::ViewportLayer::pickerDraw	(	unsigned int	x,
		unsigned int	y,
		unsigned int	w,
		unsigned int	h,
		const PickedAttrsMap &	ignoreAttrs
	)		[inline, virtual]

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

Reimplemented in Foundry::Katana::ViewerUtils::FnBaseLocatorViewportLayer, and BallLayer.

virtual void Foundry::Katana::ViewerAPI::ViewportLayer::resize	(	unsigned int	width,
		unsigned int	height
	)		[pure virtual]

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.

Implemented in Foundry::Katana::ViewerUtils::FnBaseLocatorViewportLayer, BallLayer, and ExampleSceneLayer.

void Foundry::Katana::ViewerAPI::ViewportLayer::setOption	(	const std::string &	name,
		FnAttribute::Attribute	attr
	)

Sets a generic option by generating an option ID from the passed name.

This generates an Option ID from the passed string and passes it to setOption(OptionIdGenerator::value_type optionId, FnAttribute::Attribute attr). Since the ID is generated on every call, it is more efficient to generate the ID once, and store it for future use.

Parameters:

name	The name of the option whose value to set.
attr	Attribute with the value to set for the option.

virtual void Foundry::Katana::ViewerAPI::ViewportLayer::setOption	(	OptionIdGenerator::value_type	optionId,
		FnAttribute::Attribute	attr
	)		[inline, virtual]

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.

Reimplemented in Foundry::Katana::ViewerUtils::FnBaseLocatorViewportLayer, and ExampleSpotlightLocatorViewportLayer.

virtual void Foundry::Katana::ViewerAPI::ViewportLayer::setup

(

)

[pure virtual]

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.

Implemented in Foundry::Katana::ViewerUtils::FnBaseLocatorViewportLayer, BallLayer, and ExampleSceneLayer.

virtual void Foundry::Katana::ViewerAPI::ViewportLayer::thaw

(

)

[pure virtual]

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.

Implemented in Foundry::Katana::ViewerUtils::FnBaseLocatorViewportLayer, BallLayer, and ExampleSceneLayer.

bool Foundry::Katana::ViewerAPI::ViewportLayer::usesPickingOnHover

(

)

[inline]

Tells if the layer picks objects when the mouse is hovering them.

This returns the value passed to the ViewportLayer's constructor argument usePickingOnHover. This leads to pickerDraw() to be called right after any draw() call, so that each frame produces the correct pickable IDs pass internall. This will not happen if customPick() is implemented and returns true.

Reimplemented in Foundry::Katana::ViewerUtils::FnBaseLocatorViewportLayer, and BallLayer.

---

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

• FnViewportLayer.h