Viewport Cameras

group FnViewportCamera

Typedefs

typedef std::shared_ptr<ViewportCameraWrapper> ViewportCameraWrapperPtr

class ViewportCameraPluginBase

#include <FnViewportCamera.h>

Interface for a camera.

A ViewportCamera is an important component of a Viewport that is used by the Viewport, ViewportLayers and Manipulators to determine the view and projection matrices, and also to perform useful functions such as projecting points between world and window spaces. A Viewport requires a reference to a single ViewportCamera, however multiple viewports can reference the same camera if required. A camera can optionally be controlled by a location (see hasLocationPath(), getLocationPath() and setLocationPath).

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 ViewportCamera* create();

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

ViewportCamera is the class that plugins should extend and implement.

ViewportCameraWrapper is the class that allows other plugin types to access the ViewportCamera plugin.

ViewportCameraPluginBase is the base class that provides the common methods between ViewportCamera and ViewportCameraWrapper.

Subclassed by Foundry::Katana::ViewerAPI::ViewportCamera, Foundry::Katana::ViewerAPI::ViewportCameraWrapper

Public Types

enum CameraDirtyBits

Values:

enumerator Clean

enumerator DirtyParams

enumerator AllDirty

Public Functions

ViewportCameraPluginBase()

virtual ~ViewportCameraPluginBase()

ViewportWrapperPtr getViewport()

Gets the Viewport.

Returns:: The Viewport that created and manages this layer.

const double *getViewMatrix()

Gets the View Matrix for this camera.

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

Matrix44d getViewMatrix44d()

Gets the View Matrix for this camera.

Returns:: The 4x4 View Matrix.

void setViewMatrix(const double *matrix)

Sets the View Matrix for this camera.

Parameters:: matrix – The 4x4 Viewer Matrix represented by 16 doubles.

const double *getProjectionMatrix()

Gets the Projection Matrix for this camera.

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

Matrix44d getProjectionMatrix44d()

Gets the Projection Matrix for this camera.

Returns:: The 4x4 Projection Matrix.

void setProjectionMatrix(const double *matrix)

Sets the Projection Matrix for this camera.

Parameters:: matrix – The 4x4 Projection Matrix represented by 16 doubles.

double getCenterOfInterest()

Gets the center of interest for this camera.

Returns:: The distance along the cameras look direction to the center of interest.

void setCenterOfInterest(double coi)

Sets the center of interest for this camera.

Parameters:: coi – The distance along the cameras look direction to the center of interest.

double getFOV(): Gets the field of view for this camera.

void setFOV(double fov)

Sets the field of view for this camera.

Parameters:: fov – The field of view angle in degrees.

double getOrthographicWidth()

Gets the orthographic camera dimensions (if applicable)

Returns:: The orthographic width, or 0 in not applicable.

void setOrthographicWidth(double width)

Sets the orthographic width of the camera.

Parameters:: width – The new orthographic width.

void getNearFar(double &near, double &far)

Gets the near and far plane distances for this camera.

Parameters:

near – Will be set to the distance to the near clipping plane.
far – Will be set to the distance to the far clipping plane.

void setNearFar(double near, double far)

Sets the near and far plane distances for this camera.

Parameters:

near – The distance to the near clipping plane.
far – The distance to the far clipping plane.

void getScreenWindow(double &left, double &right, double &bottom, double &top)

Gets the screen window dimensions for this camera.

Parameters:

left – Will be set to the left position of the screen window.
right – Will be set to the right position of the screen window.
bottom – Will be set to the bottom position of the screen window.
top – Will be set to the top position of the screen window.

void setScreenWindow(double left, double right, double bottom, double top)

Sets the screen window dimensions for this camera.

Parameters:

left – The left position of the screen window.
right – The right position of the screen window.
bottom – The bottom position of the screen window.
top – The top position of the screen window.

bool hasLocationPath()

Returns true if this camera is controlled by a location.

A camera that is controlled by a location has its properties (including the transform) defined by a location produced by the ViewerDelegate.

std::string getLocationPath()

Gets the location path if this camera is controlled by one.

A camera that is controlled by a location has its properties (including the transform) defined by a location produced by the ViewerDelegate.

Returns:: The location path that controls this camera or an empty string if it is not controlled by any location.

void setLocationPath(const std::string &locationPath)

Sets the location that will control this camera.

A camera that is controlled by a location has its properties (including the transform) defined by a location produced by the ViewerDelegate.

Vec3d getOrigin(): Gets the camera origin.

Vec3d getDirection(): Gets the camera look direction.

Vec3d getUp(): Gets the camera up direction.

Vec3d getLeft(): Gets the camera left direction.

bool isInteractionDisabled()

Checks whether the camera has been flagged as non-interactive.

Layers that wish to start an interaction should check for this predicate before making any change to the camera.

Returns:: True if interaction has been explicitly disabled.

void disableInteraction(bool disabled)

Flags the camera as non-interactive.

Parameters:: disabled – Set it to true to disable interaction or false to re-enable it.

class ViewportCamera : public Foundry::Katana::ViewerAPI::ViewportCameraPluginBase 

#include <FnViewportCamera.h>

The ViewportCamera class to be extended by plugins.

Public Functions

ViewportCamera()

virtual ~ViewportCamera()

virtual int getCameraTypeID() = 0

Returns an integer indicating the type of the camera.

Can be kPERSPECTIVE_CAMERA, kORTHOGRAPHIC_CAMERA, or another custom type.

Returns:: The camera type ID.

virtual void setViewportDimensions(unsigned int width, unsigned int height) = 0

Processes Viewport resizing.

Used to specify the dimensions of a Viewport which can affect picking calculations.

Parameters:

width – The viewport width in pixels.
height – The viewport height in pixels.

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

Sets a generic option.

Reacts to a generic option being set by other C++ Viewer plugin classes. This can be used as a message passing mechanism from the outside into the ViewportCamera.

Parameters:

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

virtual FnAttribute::Attribute getOption(OptionIdGenerator::value_type optionId)

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.

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

FnAttribute::Attribute 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 startInteraction() = 0

Called when the user starts interacting with the camera.

This is called when starts interacting with this camera while, for example, is viewing through it. This allows the camera to initialize some initial values used during the user interaction. The translate() and rotate() functions are expected to be called after startInteraction() and before endInteraction().

virtual void endInteraction() = 0

Called when the user finishes interacting with the camera.

This is called when finishes interacting with this camera while, for example, is viewing through it. This allows the camera to commit or tear down some values used during the user interaction. One example could be set the final camera transform values back into the node graph in a location-backed camera. The translate() and rotate() functions are expected to be called after startInteraction() and before endInteraction().

virtual void translate(double x, double y, double z) = 0

Handles translation movement of the camera.

This is expected to be called after startInteraction() and before endInteraction().

Parameters:

x – The X-axis translation in camera’s local space.
y – The Y-axis translation in camera’s local space.
z – The Z-axis translation in camera’s local space.

virtual void rotate(double x, double y, double z) = 0

Handles rotation movement of the camera.

This is expected to be called after startInteraction() and before endInteraction().

Parameters:

x – The X-axis rotation in camera’s local space.
y – The Y-axis rotation in camera’s local space.
z – The Z-axis rotation in camera’s local space.

virtual void setup(FnAttribute::GroupAttribute attr) = 0

Initializes the camera with values from an attribute.

If the camera is based on a scene graph camera, the passed attribute will be the relevant attributes from the scene graph location.

Parameters:: attr – Attribute with the initial camera state values.

virtual FnAttribute::GroupAttribute asAttribute() = 0

Returns the camera settings as a GroupAttribute.

This function should return a GroupAttribute that fully represents the current camera settings in a format that can be passed into the setup() function (as a way of duplicating the camera) or into a scene graph location in order to populate a camera location.

Returns:: A GroupAttribute representing the camera state.

virtual bool getPointOnPlane(int x, int y, const Vec3d &planeOrigin, const Vec3d &planeNormal, Vec3d &intersection) = 0

Maps window coordinates to a 3D point on a plane.

Parameters:

x – The X co-ordinate of the window.
y – The Y co-ordinate of the window.
planeOrigin – The coordinates of the plane origin.
planeNormal – The normal direction of the plane.
intersection – Output argument where the intersection position (if any) is set.

Returns:

true if an intersection occured.

virtual void getRay(int x, int y, Vec3d &pos, Vec3d &dir) = 0

Calculates the ray from the camera through the given window coordinates.

Parameters:

x – The X co-ordinate of the window.
y – The Y co-ordinate of the window.
pos – Output argument where the line position is set.
dir – Output argument where the line direction is set.

virtual Vec3d projectObjectIntoWindow(Vec3d point) = 0

Converts a 3D point in the scene into window co-ordinates.

Parameters:: point – The point in world space to transform.
Returns:: A 3 dimensional vector representing the screen coordinates of the point in its X, Y members and the depth of the point in the Z member.

virtual Vec3d projectWindowIntoObject(Vec3d point) = 0

Converts a window co-ordinates into a point in the scene.

Parameters:: point – The point in window space to transform into world space. point.x and point.y indicate the X and Y position in pixels and point.z indicates the depth into the scene in world space.
Returns:: The position of the transformed point in world space.

inline virtual void *getPrivateData(void *inputData)

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 setDirty(CameraDirtyBits dirtyBits) = 0

Specifies what has changed in the camera.

Something has changed and the camera needs to be updated. DirtyFlag is passed to specify what has been changed so the plugin can update accordingly.

Parameters:: dirtyBits – Flag to specify what has changed.

Public Static Functions

static inline void flush()

Flush plugin Caches.

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

class ViewportCameraWrapper : public Foundry::Katana::ViewerAPI::ViewportCameraPluginBase 

#include <FnViewportCamera.h>

The ViewportCamera class accessed by other plugins.

Public Functions

ViewportCameraWrapper(FnPluginHost *host, FnViewportCameraHostHandle hostHandle, FnViewportCameraPluginHandle pluginHandle, FnViewportCameraPluginSuite_v2 *pluginSuite)

~ViewportCameraWrapper()

template<class T> inline T *getPluginInstance()

Gets a pointer to the real plugin instance.

WARNING: This function purposely breaks the compiler agnostic pattern of the Katana plugin API, so it needs to be used with care. This performs a dynamic cast to the real type so the implications of what that means in different circumstances should be understood. If the caller and plugin instance are not contained in the same shared library the RTTI check may fail.

This function allows a plugin wrapper to return the actual plugin class. The plugin is returned as a pointer to a child class of ViewportCamera that is a registerd plugin. The type of that child class needs to be specified in the template, so that it can be properly cast. If the specified type doesn’t match the plugin type then NULL is returned.

int getCameraTypeID(): Returns an integer indicating the type of the camera.

void setViewportDimensions(unsigned int width, unsigned int height): Informs the camera of the Viewport dimensions in pixels.

void setOption(OptionIdGenerator::value_type optionId, FnAttribute::Attribute attr): Sets a generic camera option.

FnAttribute::Attribute getOption(OptionIdGenerator::value_type optionId): Gets a generic camera option.

void setOption(const std::string &name, FnAttribute::Attribute attr): Sets a generic camera option.

FnAttribute::Attribute getOption(const std::string &name): Gets a generic camera option.

void translate(double x, double y, double z): Translates the camera.

void rotate(double x, double y, double z): Rotates the camera.

void startInteraction(): Called when the user starts interacting with the camera.

void endInteraction(): Called when the user finishes interacting with the camera.

void setup(FnAttribute::GroupAttribute attr): Initializes the camera from a GroupAttribute.

FnAttribute::GroupAttribute asAttribute(): Returns the camera settings as a GroupAttribute.

bool getPointOnPlane(int x, int y, const Vec3d &planeOrigin, const Vec3d &planeNormal, Vec3d &intersection): Returns the point 3D on a plane when passed X and Y window coordinates.

void getRay(int x, int y, Vec3d &pos, Vec3d &dir): Returns the ray from the observer through the X and Y window coordinates.

Vec3d projectObjectIntoWindow(Vec3d point): Converts a 3D point into window space.

Vec3d projectWindowIntoObject(Vec3d point): Converts a window space point into 3D space.

void setDirty(CameraDirtyBits dirtyBits): Specifies what has changed in the camera.