Interface for the functionality of a single viewport. More...

#include <FnViewport.h>

Inheritance diagram for Foundry::Katana::ViewerAPI::ViewportPluginBase:

Public Member Functions
	ViewportPluginBase ()
	Constructor.
virtual	~ViewportPluginBase ()
	Destructor.
std::string	getName ()
	Gets the Viewport name.
ViewerDelegateWrapperPtr	getViewerDelegate ()
	Gets the ViewerDelegate of thie Viewport.
unsigned int	getWidth ()
	Gets the width in pixels of the Viewport.
unsigned int	getHeight ()
	Gets the Height in pixels of the Viewport.
ViewportCameraWrapperPtr	getActiveCamera ()
	Gets the ViewportCamera of the Viewport.
ViewportCameraWrapperPtr	addCamera (const std::string &pluginName, const std::string &name)
	Creates a new ViewportCamera of the passed type.
ViewportCameraWrapperPtr	getCamera (const std::string &name) const
	Gets a ViewportCamera by name.
ViewportCameraWrapperPtr	getCamera (unsigned int index) const
	Gets a ViewportCamera by index.
void	removeCamera (const std::string &name)
	Removes a ViewportCamera by name.
void	removeCamera (unsigned int index)
	Removes a ViewportCamera by name.
unsigned int	getNumberOfCameras () const
	Gets the number of ViewportCameras.
std::string	getCameraName (unsigned int index)
	Gets the name of the ViewportCamera on a given index.
std::string	getCameraName (ViewportCameraWrapperPtr camera)
	Gets the name of the given camera.
int	getCameraIndex (const std::string &name)
	Gets the index of the ViewportCamera with a given name.
void	removeCamera (ViewportCameraWrapperPtr camera)
	Destorys the passed ViewportCamera.
void	setActiveCamera (ViewportCameraWrapperPtr camera)
	Makes the passed ViewportCamera active.
void	setViewFrozen (bool isViewFrozen)
	Freezes/thaws the viewport view.
bool	isViewFrozen () const
	Returns whether the viewport view is currently frozen.
const double *	getViewMatrix ()
	Gets the View Matrix for this Viewport.
Matrix44d	getViewMatrix44d ()
	Gets the View Matrix for this camera.
const double *	getProjectionMatrix ()
	Gets the Projection Matrix for this Viewport.
Matrix44d	getProjectionMatrix44d ()
	Gets the Projection Matrix for this camera.
bool	isDirty ()
	Returns whether the viewer state is dirty.
void	setDirty (bool dirty)
	Sets the viewer state of the Viewport.
ViewportLayerWrapperPtr	addLayer (const std::string &pluginName, const std::string &name)
	Adds a ViewportLayer.
ViewportLayerWrapperPtr	insertLayer (const std::string &pluginName, const std::string &name, unsigned int index)
	Inserts a ViewportLayer.
ViewportLayerWrapperPtr	getLayer (const std::string &name) const
	Gets a ViewportLayer by name.
ViewportLayerWrapperPtr	getLayer (unsigned int index) const
	Gets a ViewportLayer by index.
void	removeLayer (const std::string &name)
	Removes a ViewportLayer by name.
void	removeLayer (unsigned int index)
	Removes a ViewportLayer by name.
unsigned int	getNumberOfLayers () const
	Gets the number of ViewportLayers.
std::string	getLayerName (unsigned int index)
	Gets the name of the ViewportLayer on a given index.
int	getLayerIndex (const std::string &name)
	Gets the index of the ViewportLayer on a given name.
void	activateManipulator (const std::string &pluginName, const std::vector< std::string > &locationPaths)
	Activates a Manipulator on the Viewport.
void	deactivateManipulator (const std::string &pluginName)
	Deactivates a Manipulator on the Viewport.
void	deactivateAllManipulators ()
	Deactivates all Manipulators on the Viewport.
unsigned int	getNumberOfActiveManipulators ()
	Gets the number of active Manipulators on the Viewport.
ManipulatorWrapperPtr	getActiveManipulator (unsigned int index)
	Gets an active Manipulator by index.
ManipulatorWrapperPtr	getActiveManipulator (const std::string &pluginName)
	Gets an active Manipulator by plugin name.
bool	makeGLContextCurrent ()
	Makes the Viewport OpenGL context current.
bool	doneGLContextCurrent ()
	Makes the Viewport OpenGL context no longer current.
bool	isGLContextCurrent ()
	Determines if the Viewport's OpenGL context is the current context.
unsigned int	getDefaultFramebufferObject ()
	Gets the default framebuffer object of the viewport.
void	enableCap (uint32_t cap)
	Enables a server-side OpenGL capability.
void	disableCap (uint32_t cap)
	Disables a server-side OpenGL capability.
void	pick (unsigned int x, unsigned int y, unsigned int w, unsigned int h, bool deepPicking, PickedAttrsMap &pickedAttrs, float *singlePointDepth=NULL)
	Picks the objects that are inside a given viewport region.
void	setPanAndZoomActive (bool active)
	Sets the pan and zoom active state.
bool	isPanAndZoomActive ()
	Returns whether the pan and zoom is active.
float	getHorizontalOffset ()
	Returns the amount of horizontal offset.
float	getVerticalOffset ()
	Returns the amount of vertical offset.
float	getZoom ()
	Returns the zoom value.

Detailed Description

Interface for the functionality of a single viewport.

A Viewport's main responsibilities are to draw the contents of a single viewport widget and to handle the UI events of that widget. When the Qt GL Widget for the viewport is created an instance of the Viewport class is also instantiated and associated with it.

Several Viewports can share and access a single ViewerDelegate (see getViewerDelegate()). Some shared data structures can be owned by the ViewerDelegate, so it is convenient to build both plug-ins using the same compiler, so that the result of getViewerDelegate() can be cast into the known subclass of ViewerDelegate, which might contain specific methods and members that can be useful to the plug-in. If that is not possible, then the more generic getOption() / setOption() in both the Viewport and the ViewerDelegate can be used.

By default, the Katana UI will wait for an idle event, and then call the draw() function if the viewport has been marked as dirty via the setDirty() method. It is important to note that prior to draw(), resize() and setup() being called, the OpenGL context of the viewport widget will be made current. The makeGLContextCurrent() / doneGLContextCurrent() functions can also be used to force the GL context to be made current, but this should be used springly, as frequent GL context changes can lead to performance degradation. All of the viewport widgets hosted in a particular Viewer tab will attempt to share Open GL context data with each other. This allows viewports to share certain resources, such as Vertex Buffer Objects, but is subject to the usual limitations of context sharing, such as containers (Vertex Array Objects) not being shared. The default framebuffer in this context is the Qt widget's framebuffer, so any drawing on it will end up being shown on the widget.

The Viewport can create and own several ViewportLayers. These are independent plug-ins that can potentially be reusable between different Viewports that are responsible for a specific set of drawing and/or event processing activities. The Viewport delegates the draw() function and the event() function on its layers. These layers are organized in a linear sequence, in which the draw(), event() and resize() member functions will be called starting in the layer with the lowest index and ending with the one with the highest index.

The Viewport class is also responsible for activating and deactivating Manipulators on a list of locations (see activateManipulator() and deactivateManipulator()). The compatibility of these Manipulators should be checked previously with the ViewerDelegate.getCompatibleManipulatorsInfo() function, to guarantee that they are compatible with the locations to be manipulated. A ManipulatorLayer can be used then to actually draw and process the events of these manipulators, but the Viewport is responsible for keeping track of which ones are currently activated (see the functions getNumberOfActiveManipulators() and getActiveManipulator()).

A Viewport also allows picking / selection of rendered objects in the scene inside a certain region of the viewport. This can be a deep picking (all objects inside the region, independently if they are occluded or not from the current camera point of view) or it can select only the visible objects. The Viewport provides an optional internal mechanism that makes use of an internal ID pass framebuffer. This can be used by implementing the pickerDraw() virtual function, calling addPickableObject() in it. If the rendering technology provides its own picking mechanism, it can be used by implementing the customPick() function, which will not make use of the internal ID picking, and pickerDraw() will not be called. This mechanism also is present in ViewportLayers.

This is a virtual base class to be extended in your plug-in. In addition to implementing all the pure virtual functions in this class, you must also implement this static method in your derived class:

 // Returns a new instance of your derived class.
 static Viewport* create();

To indicate an error to the caller, your implementation may throw an exception derived from std::exception.

ViewerDelegate is the class that plugins should extend and implement.

ViewerDelegateWrapper is the class that allows other plugin types to access the ViewerDelegate plugin.

ViewerDelegatePluginBase is the base class that provides the common methods between ViewerDelegate and ViewerDelegateWrapper.

Member Function Documentation

void Foundry::Katana::ViewerAPI::ViewportPluginBase::activateManipulator	(	const std::string &	pluginName,
		const std::vector< std::string > &	locationPaths
	)

Activates a Manipulator on the Viewport.

Activates a Manipulator with the given plugin name for the specified locations. This will instantiate a Manipulator plugin on this Viewport that manipulates those locations. After this the manipulator will be ready to be drawn and interacted with, which can either be implemented directly on the Viewport or in a ViewportLayer dedicated to manipulators. Only one Manipulator instance of the given type can be active at once.

This function is exposed in the Viewport Python class.

Parameters:

pluginName	The name of the Manipulator plugin.
locationPaths	The locations to be manipulated.

ViewportCameraWrapperPtr Foundry::Katana::ViewerAPI::ViewportPluginBase::addCamera	(	const std::string &	pluginName,
		const std::string &	name
	)

Creates a new ViewportCamera of the passed type.

If a camera of the same name already exists, it will be deleted. If said camera was the active camera, the new camera will become the active camera.

Parameters:

pluginName	The name of the ViewportCamera plugin.
name	The name of the new ViewportCamera.

Returns:: The newly created ViewportCamera.

ViewportLayerWrapperPtr Foundry::Katana::ViewerAPI::ViewportPluginBase::addLayer	(	const std::string &	pluginName,
		const std::string &	name
	)

Adds a ViewportLayer.

Instantiates a ViewportLayer and adds it to the end of the list of layers on this Viewport.

Parameters:

pluginName	The name of the ViewportLayer plugin.
name	The name for the new ViewportLayer.

Returns:: The newly created ViewportLayer.

void Foundry::Katana::ViewerAPI::ViewportPluginBase::deactivateAllManipulators ( )

Deactivates all Manipulators on the Viewport.

This function is exposed in the Viewport Python class.

Deactivates all Manipulators that have been previously activated in this Viewport.

void Foundry::Katana::ViewerAPI::ViewportPluginBase::deactivateManipulator ( const std::string & pluginName )

Deactivates a Manipulator on the Viewport.

Deactivates a Manipulator with the given plugin name that has been previously activated in this Viewport.

This function is exposed in the Viewport Python class.

Parameters:

pluginName The name of the Manipulator plugin.

void Foundry::Katana::ViewerAPI::ViewportPluginBase::disableCap ( uint32_t cap )

Disables a server-side OpenGL capability.

Parameters:

cap	Specifies a symbolic constant indicating a OpenGL capability.

Note:: To temporarily change the OpenGL state, please use GLStateRestore.

bool Foundry::Katana::ViewerAPI::ViewportPluginBase::doneGLContextCurrent ( )

Makes the Viewport OpenGL context no longer current.

Returns:: true if successful or false on failure.

void Foundry::Katana::ViewerAPI::ViewportPluginBase::enableCap ( uint32_t cap )

Enables a server-side OpenGL capability.

Parameters:

cap	Specifies a symbolic constant indicating a OpenGL capability.

Note:: To temporarily change the OpenGL state, please use GLStateRestore.

ViewportCameraWrapperPtr Foundry::Katana::ViewerAPI::ViewportPluginBase::getActiveCamera ( )

Gets the ViewportCamera of the Viewport.

Returns:: The ViewportCamera for this Viewport.

ManipulatorWrapperPtr Foundry::Katana::ViewerAPI::ViewportPluginBase::getActiveManipulator ( unsigned int index )

Gets an active Manipulator by index.

Get the active Manipulator on the given index. Each active Manipulator has an associated index internally. The indices are always sequential, so this can be used to iterate through all the active Manipulators, using getNumberOfActiveManipulators() to know how many there are.

Note:: An index might not refer to the same Manipulator on consecutive calls.

Parameters:

index The index of the Manipulator.

Returns:: The active Manipulator with the given index or 0 if no Manipulator has that index.

ManipulatorWrapperPtr Foundry::Katana::ViewerAPI::ViewportPluginBase::getActiveManipulator ( const std::string & pluginName )

Gets an active Manipulator by plugin name.

Parameters:

pluginName The name of the Manipulator plugin.

Returns:: The active Manipulator with the given plugin name or 0 if there no active Manipulators with that pluginName.

ViewportCameraWrapperPtr Foundry::Katana::ViewerAPI::ViewportPluginBase::getCamera ( unsigned int index ) const

Gets a ViewportCamera by index.

Parameters:

index The position in the list of ViewportLayers on this Viewport.

This function is exposed in the Viewport Python class as Viewport.getCameraByIndex().

Returns:: The ViewportCamera in this Viewport with the given index or 0 if no such layer exists.

ViewportCameraWrapperPtr Foundry::Katana::ViewerAPI::ViewportPluginBase::getCamera ( const std::string & name ) const

Gets a ViewportCamera by name.

This function is exposed in the Viewport Python class.

Parameters:

name	The name of the ViewportCamera.

Returns:: The ViewportCamera in this Viewport with the given name or 0 if no such layer exists.

int Foundry::Katana::ViewerAPI::ViewportPluginBase::getCameraIndex ( const std::string & name )

Gets the index of the ViewportCamera with a given name.

Parameters:

name	The name of the ViewportCamera.

Returns:: The index of the ViewportCamera with the given name or -1 if it doesn't exist.

std::string Foundry::Katana::ViewerAPI::ViewportPluginBase::getCameraName ( unsigned int index )

Gets the name of the ViewportCamera on a given index.

Parameters:

index The position in the list of ViewportLayers on this Viewport.

Returns:: The name of the ViewportCamera on the given index or empty string if it doesn't exist.

std::string Foundry::Katana::ViewerAPI::ViewportPluginBase::getCameraName ( ViewportCameraWrapperPtr camera )

Gets the name of the given camera.

Parameters:

camera ViewportCamera whose name is to be returned.

Returns:: The name of the given ViewportCamera or empty string if it doesn't exist in the viewport.

unsigned int Foundry::Katana::ViewerAPI::ViewportPluginBase::getDefaultFramebufferObject ( )

Gets the default framebuffer object of the viewport.

This is of type GLuint.

By the time draw() is invoked, the default framebuffer object will have been automatically bound. If the plug-in implementation binds a different framebuffer object, this function can be used to retrieve the original framebuffer object, which is where the plug-in needs to perform the final drawing.

Returns:: The GL name that identifies the framebuffer object.

unsigned int Foundry::Katana::ViewerAPI::ViewportPluginBase::getHeight ( )

Gets the Height in pixels of the Viewport.

Returns:: The height in pixels of 0 if the Viewport hasn't been initialized.

ViewportLayerWrapperPtr Foundry::Katana::ViewerAPI::ViewportPluginBase::getLayer ( const std::string & name ) const

Gets a ViewportLayer by name.

This function is exposed in the Viewport Python class.

Parameters:

name	The name of the ViewportLayer.

Returns:: The ViewportLayer in this Viewport with the given name or 0 if no such layer exists.

ViewportLayerWrapperPtr Foundry::Katana::ViewerAPI::ViewportPluginBase::getLayer ( unsigned int index ) const

Gets a ViewportLayer by index.

Parameters:

index The position in the list of ViewportLayers on this Viewport.

This function is exposed in the Viewport Python class as Viewport.getLayerByIndex().

Returns:: The ViewportLayer in this Viewport with the given index or 0 if no such layer exists.

int Foundry::Katana::ViewerAPI::ViewportPluginBase::getLayerIndex ( const std::string & name )

Gets the index of the ViewportLayer on a given name.

Parameters:

name	The name of the ViewportLayer.

Returns:: The index of the ViewportLayer with the given name or -1 if it doesn't exist.

std::string Foundry::Katana::ViewerAPI::ViewportPluginBase::getLayerName ( unsigned int index )

Gets the name of the ViewportLayer on a given index.

Parameters:

index The position in the list of ViewportLayers on this Viewport.

Returns:: The name of the ViewportLayer on the given index or empty string if it doesn't exist.

std::string Foundry::Katana::ViewerAPI::ViewportPluginBase::getName ( )

Gets the Viewport name.

This function is exposed in the Viewport Python class.

Returns:: The name given to the Viewport when it was created.

unsigned int Foundry::Katana::ViewerAPI::ViewportPluginBase::getNumberOfActiveManipulators ( )

Gets the number of active Manipulators on the Viewport.

This function is exposed in the Viewport Python class.

Deactivates all Manipulators that have been previously activated in this Viewport.

unsigned int Foundry::Katana::ViewerAPI::ViewportPluginBase::getNumberOfCameras ( ) const

Gets the number of ViewportCameras.

This function is exposed in the Viewport Python class.

Returns:: The number of ViewportCameras added to this Viewport.

unsigned int Foundry::Katana::ViewerAPI::ViewportPluginBase::getNumberOfLayers ( ) const

Gets the number of ViewportLayers.

This function is exposed in the Viewport Python class.

Returns:: The number of ViewportLayers added to this Viewport.

const double* Foundry::Katana::ViewerAPI::ViewportPluginBase::getProjectionMatrix ( )

Gets the Projection Matrix for this Viewport.

Returns:: The 4x4 Projection Matrix represented by 16 doubles.

Matrix44d Foundry::Katana::ViewerAPI::ViewportPluginBase::getProjectionMatrix44d ( )

Gets the Projection Matrix for this camera.

Returns:: The 4x4 Projection Matrix.

ViewerDelegateWrapperPtr Foundry::Katana::ViewerAPI::ViewportPluginBase::getViewerDelegate ( )

Gets the ViewerDelegate of thie Viewport.

Returns:: The ViewerDelegate that serves this Viewport.

const double* Foundry::Katana::ViewerAPI::ViewportPluginBase::getViewMatrix ( )

Gets the View Matrix for this Viewport.

Returns:: The 4x4 Viewer Matrix represented by 16 doubles.

Matrix44d Foundry::Katana::ViewerAPI::ViewportPluginBase::getViewMatrix44d ( )

Gets the View Matrix for this camera.

Returns:: The 4x4 View Matrix.

unsigned int Foundry::Katana::ViewerAPI::ViewportPluginBase::getWidth ( )

Gets the width in pixels of the Viewport.

Returns:: The width in pixels of 0 if the Viewport hasn't been initialized.

ViewportLayerWrapperPtr Foundry::Katana::ViewerAPI::ViewportPluginBase::insertLayer	(	const std::string &	pluginName,
		const std::string &	name,
		unsigned int	index
	)

Inserts a ViewportLayer.

Instantiates a ViewportLayer and adds it a specified index on the list of layers on this Viewport.

This function is exposed in the Viewport Python class.

Parameters:

pluginName	The name of the ViewportLayer plugin.
name	The name for the new ViewportLayer.
index	The index of the parameter

Returns:: The newly created ViewportLayer.

bool Foundry::Katana::ViewerAPI::ViewportPluginBase::isDirty ( )

Returns whether the viewer state is dirty.

Returns whether the viewport state is dirty, if so it will be re-drawn.

This function is exposed in the Viewport Python class.

bool Foundry::Katana::ViewerAPI::ViewportPluginBase::isGLContextCurrent ( )

Determines if the Viewport's OpenGL context is the current context.

Returns:: true if the Viewport's OpenGL context is current; false otherwise.

bool Foundry::Katana::ViewerAPI::ViewportPluginBase::isViewFrozen ( ) const

Returns whether the viewport view is currently frozen.

When the view is frozen, viewers are not allowed to make changes in the active camera. However, this is only a soft condition that viewers might decide to ignore.

bool Foundry::Katana::ViewerAPI::ViewportPluginBase::makeGLContextCurrent ( )

Makes the Viewport OpenGL context current.

Returns:: true if successful or false on failure.

void Foundry::Katana::ViewerAPI::ViewportPluginBase::pick	(	unsigned int	x,
		unsigned int	y,
		unsigned int	w,
		unsigned int	h,
		bool	deepPicking,
		PickedAttrsMap &	pickedAttrs,
		float *	singlePointDepth = `NULL`
	)

Picks the objects that are inside a given viewport region.

Allows to query the scene for objects that are visible inside a given rectangular region in the viewport. This region can be a single pixel on the screen, by setting both its width and height to 1.

The object picking can optionally be deep, meaning that all the objects viewed inside the region will be picked even if they are currently occluded by other objects. A non-deep picking means that only currently visible objects inside the region will be picked.

Picking can be implemented in two ways:

Using the internal ID framebuffer based technique implemented via pickerDraw() and addPickableObject()

Implementing a custom picking implemented using some third party technology via customPick().

This function makes use of whatever picking technique is implemented in this Viewport.

This function returns a map of picking IDs to Attributes that represent the picked objects and, optionally a depth value for when the picked region is one single pixel. If pickerDraw() is used, as opposed to customPick(), then the IDs are returned by the addPickableObject() calls inside pickerDraw() and the Attributes are the ones passed to it. They can be used to identify what objects have been picked.

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.

void Foundry::Katana::ViewerAPI::ViewportPluginBase::removeCamera ( const std::string & name )

Removes a ViewportCamera by name.

This function is exposed in the Viewport Python class.

Parameters:

name	The name of the ViewportCamera to be removed.

void Foundry::Katana::ViewerAPI::ViewportPluginBase::removeCamera ( unsigned int index )

Removes a ViewportCamera by name.

This function is exposed in the Viewport Python class as Viewport.removeCameraByIndex().

Parameters:

index The position in the list of ViewportLayers on this Viewport

void Foundry::Katana::ViewerAPI::ViewportPluginBase::removeLayer ( unsigned int index )

Removes a ViewportLayer by name.

This function is exposed in the Viewport Python class as Viewport.removeLayerByIndex().

Parameters:

index The position in the list of ViewportLayers on this Viewport

void Foundry::Katana::ViewerAPI::ViewportPluginBase::removeLayer ( const std::string & name )

Removes a ViewportLayer by name.

This function is exposed in the Viewport Python class.

Parameters:

name	The name of the ViewportLayer to be removed.

void Foundry::Katana::ViewerAPI::ViewportPluginBase::setDirty ( bool dirty )

Sets the viewer state of the Viewport.

Sets whether the viewport state is dirty (due to something that happened that led to the need or re-drawing the scene).

This function is exposed in the Viewport Python class.

void Foundry::Katana::ViewerAPI::ViewportPluginBase::setViewFrozen ( bool isViewFrozen )

Freezes/thaws the viewport view.

When the view is frozen, viewers are not allowed to make changes in the active camera. However, this is only a soft condition that viewers might decide to ignore.

The viewer delegate will emit an event "__VIEWPORT_VIEW_FROZEN_STATE_CHANGED" containing the viewport's name and the new state.

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

FnViewport.h

Foundry::Katana::ViewerAPI::ViewportPluginBase Class ReferenceViewport Plugin

Public Member Functions

Detailed Description

Member Function Documentation

Foundry::Katana::ViewerAPI::ViewportPluginBase Class Reference
Viewport Plugin