Viewport Cameras¶
-
group
FnViewportCamera Typedefs
-
typedef FnPlatform::internal::SharedPtr<ViewportCameraWrapper>::type
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
Public Functions
-
ViewportCameraPluginBase()¶
-
virtual
~ViewportCameraPluginBase()¶
-
ViewportWrapperPtr
getViewport()¶ Gets the Viewport.
- Return
- The Viewport that created and manages this layer.
-
const double *
getViewMatrix()¶ Gets the View Matrix for this camera.
- Return
- The 4x4 Viewer Matrix represented by 16 doubles.
-
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.
- Return
- The 4x4 Projection Matrix represented by 16 doubles.
-
Matrix44d
getProjectionMatrix44d()¶ Gets the Projection Matrix for this camera.
- Return
- 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.
- Return
- 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)
- Return
- 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.
- Return
- 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.
-
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.
- Return
- 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¶ - #include <FnViewportCamera.h>
The ViewportCamera class to be extended by plugins.
Inherits from Foundry::Katana::ViewerAPI::ViewportCameraPluginBase
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.
- Return
- 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.
-
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.
- Return
- Attribute with the value of the option.
- Parameters
optionId-The ID of the option created from OptionIdGenerator or manually defined by users.
-
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.
- Return
- The value of the option with the given name.
- Parameters
name-The name of the option whose value to retrieve.
-
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.
- Return
- 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.
- Return
- true if an intersection occured.
- 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.
-
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.
- Return
- 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.
- Parameters
point-The point in world space to transform.
-
virtual Vec3d
projectWindowIntoObject(Vec3d point) = 0¶ Converts a window co-ordinates into a point in the scene.
- Return
- The position of the transformed point in world space.
- 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.
-
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.
- Return
- The arbitrary private data. A void pointer that can be cast into specific object types by other plugins.
- Parameters
inputData-A pointer to some input data that can be used to produce the returned data.
-
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.
-
void
setHostHandle(FnViewportCameraHostHandle m_hostHandle)¶
-
FnViewportCameraHostHandle
getHostHandle()¶
Public Static Functions
-
static void
flush()¶ Flush plugin Caches.
Allows to discard any cache for this plugin when a Flush Caches event occurs.
-
static FnViewportCameraPluginSuite_v2 Foundry::Katana::ViewerAPI::ViewportCamera::createSuite(FnViewportCameraPluginHandle(*create)(FnViewportCameraHostHandle hostHandle))
-
static FnViewportCameraPluginHandle
newViewportCameraHandle(ViewportCamera *viewportCamera)¶
-
-
class
ViewportCameraWrapper¶ - #include <FnViewportCamera.h>
The ViewportCamera class accessed by other plugins.
Inherits from Foundry::Katana::ViewerAPI::ViewportCameraPluginBase
Public Functions
-
ViewportCameraWrapper(FnPluginHost *host, FnViewportCameraHostHandle hostHandle, FnViewportCameraPluginHandle pluginHandle, FnViewportCameraPluginSuite_v2 *pluginSuite)¶
-
~ViewportCameraWrapper()¶
- template <class T>
-
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.
-
void
setDirty(CameraDirtyBits dirtyBits)¶ Specifies what has changed in the camera.
-
-
typedef FnPlatform::internal::SharedPtr<ViewportCameraWrapper>::type