|
Katana Plug-in APIs 0.1
|
|
Katana Plug-in APIs 0.1
|
The Viewport class to be extended by plugins. More...
#include <FnViewport.h>
Public Member Functions | |
| Viewport () | |
| Constructor. | |
| virtual | ~Viewport () |
| Destructor. | |
| virtual void | setup ()=0 |
| Initializes the GL components of the Viewport. | |
| virtual void | cleanup ()=0 |
| Cleans up the Viewport resources. | |
| virtual bool | event (const FnEventWrapper &eventData) |
| Processes UI events. | |
| virtual void | draw () |
| Draws the scene. | |
| virtual void | resize (unsigned int width, unsigned int height) |
| Processes Viewport resizing. | |
| virtual void | hover (bool isHovering, int x, int y) |
| Called when the mouse hovers the Viewport. | |
| 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. | |
| virtual void | freeze ()=0 |
| Freezes the Viewport when the Viewer is hidden. | |
| virtual void | thaw ()=0 |
| Thaws the Viewport when the Viewer is shown. | |
| virtual void * | getPrivateData (void *inputData) |
| Returns some arbitrary data. | |
| 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. | |
The Viewport class to be extended by plugins.
| FnPickId Foundry::Katana::ViewerAPI::Viewport::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:
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.
| attr | The Attribute that describes the pickable object. |
| virtual void Foundry::Katana::ViewerAPI::Viewport::cleanup | ( | ) | [pure virtual] |
Cleans up the Viewport resources.
Called when a Viewport is removed by the ViewerDelegate.
Implemented in ExampleViewport.
| virtual bool Foundry::Katana::ViewerAPI::Viewport::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.
| 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::Viewport::draw | ( | ) | [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 Viewport.
This function is exposed in the Viewport Python class.
Reimplemented in ExampleViewport.
| virtual bool Foundry::Katana::ViewerAPI::Viewport::event | ( | const FnEventWrapper & | eventData | ) | [virtual] |
Processes UI events.
Called whenever a user interaction event occurs. This will be also propagated through the ViewerLayers of this Viewport.
This function is exposed in the Viewport Python class.
| eventData | The event data (see FnEventWrapper). |
Reimplemented in ExampleViewport.
| static void Foundry::Katana::ViewerAPI::Viewport::flush | ( | ) | [inline, static] |
Flush plugin Caches.
Allows to discard any cache for this plugin when a Flush Caches event occurs.
Reimplemented in ExampleViewport.
| virtual void Foundry::Katana::ViewerAPI::Viewport::freeze | ( | ) | [pure virtual] |
Freezes the Viewport when the Viewer is hidden.
Allows the Viewport to freeze its activities when the Viewer is not visible. This allows the ViewerDelegate to stop any kind of unecessary processing that might happen durging that time.
This function is exposed in the Viewport Python class.
Implemented in ExampleViewport.
| virtual FnAttribute::Attribute Foundry::Katana::ViewerAPI::Viewport::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.
This function is exposed in the Viewport Python class.
| optionId | The ID of the option created from OptionIdGenerator or manually defined by users. |
Reimplemented in ExampleViewport.
| FnAttribute::Attribute Foundry::Katana::ViewerAPI::Viewport::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.
| name | The name of the option whose value to retrieve. |
| virtual void* Foundry::Katana::ViewerAPI::Viewport::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.
| inputData | A pointer to some input data that can be used to produce the returned data. |
| virtual void Foundry::Katana::ViewerAPI::Viewport::hover | ( | bool | isHovering, |
| int | x, | ||
| int | y | ||
| ) | [virtual] |
Called when the mouse hovers the Viewport.
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.
This function is exposed in the Viewport Python class.
| 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. |
| virtual void Foundry::Katana::ViewerAPI::Viewport::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 Viewport 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().
| 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 | Contains information about the objects that should not be rendered here. PickedAttrsMap has the same public interface as std::map<FnPickId, FnAttributes::Attribute>. |
| virtual void Foundry::Katana::ViewerAPI::Viewport::resize | ( | unsigned int | width, |
| unsigned int | height | ||
| ) | [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.
This function is exposed in the Viewport Python class.
| width | The viewport width in pixels. |
| height | The viewport height in pixels. |
Reimplemented in ExampleViewport.
| void Foundry::Katana::ViewerAPI::Viewport::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.
| 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::Viewport::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 Viewport.
This function is exposed in the Viewport Python class.
| optionId | The ID of the option created from OptionIdGenerator or manually defined by users. |
| attr | Attribute with the value being set. |
Reimplemented in ExampleViewport.
| virtual void Foundry::Katana::ViewerAPI::Viewport::setup | ( | ) | [pure virtual] |
Initializes the GL components of the Viewport.
Called when a Viewport 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 ExampleViewport.
| virtual void Foundry::Katana::ViewerAPI::Viewport::thaw | ( | ) | [pure virtual] |
Thaws the Viewport when the Viewer is shown.
Allows the Viewport to restart its activities when the Viewer becomes visible. This restarts the activities paused by freeze().
This function is exposed in the Viewport Python class.
Implemented in ExampleViewport.
1.7.3
