The ICamera graph node interface.
A camera represents a node positioned in world space through which any renderable geometry can be viewed within its viewing volume. The view volume can either be a box for orthographic cameras or a frustum for perspective cameras.
Along the screen-space Z axis, the view volume is bounded by a near plane and a far plane, which can be set by SetNearAndFarPlaneZ() and related methods. The values for the near and far plane always represent positive (absolute) distances from the camera's eye point, regardless of the actual camera position and orientation in world space.
For the screen-space X (left-right) and Y (bottom-top) axes, defining the view volume can be done independently in one of two ways:
- Specifying a unit size results in a constant mapping between output pixels and virtual coordinates catched by the camera, with a value of 1.0 producing a 1:1 relationship. In other words, if the output window is enlarged, more of the virtual space becomes visible for that camera.
- Specifying a field-of-view value keeps a constant relationship between virtual coordinates and window size. In other words, enlarging the window will enlarge the rendered scene, but no additional geometry will become visible.
The actual meaning of the given values is different for each type of camera:
- Orthographic cameras:
- The fovX and fovY parameters of the SetFieldOfView() method (and related ones) simply represent the X and Y extent of the viewing box from the center in both directions (i.e. the actual width and height of the box are 2*fovX and 2*fovY, respectively).
- The unitSizeX and unitSizeY parameters of the SetUnitSize() method (and related ones) directly map pixels to virtual coordinates.
- Perspective cameras:
- The fovX and fovY parameters of the SetFieldOfView() method (and related ones) represent the horizontal and vertical extent of the viewing frustum at the near plane, measured from the center. A near plane distance of 10.0 and a fovX of 10.0 therefore represent a 45° angle between the center line to both the left and right front edges of the frustum, resulting in a total horizontal field of view of 90°, with the virtual coordinates ranging from -10.0 to +10.0 in X direction, at a distance of 10.0 units in front of the camera.
- The unitSizeX and unitSizeY parameters of the SetUnitSize() method (and related ones) directly map pixels to virtual coordinates, again at the near plane.
Note, that you cannot specify both FOV and unit size for the same axis. It is however possible to define a FOV in X direction and a unit size in Y direction (and vice versa).
If only one axis is defined by an FOV or unit size value, the bounds of the missing dimension can be automatically calculated to maintain a given coordinate aspect ratio, which can be defined via SetAspectRatio(). (default 1.0). In this case (only one axis given), the aspect ratio cannot be 0, and the view area of the automatically calculated axis is adjusted with respect to the actual window size.
If both axes are set and the aspect ratio is set to a value higher than 0.0, the engine tries to both respect the given ratio as well as the FOV/unit size values. There are two cases how this is done:
- If SetAspectClippingEnabled() is set to false, the system always fits the camera to its output surface so that the given field of view is always fully visible. This may mean that the FOV of either the horizontal or vertical axis is actually bigger than specified (if the aspect ratio of the output surface is different from the camera aspect). To clip away this (possibly undesired) extra space, SetBorderMaskEnabled(true) can be called.
- If SetAspectClippingEnabled() is set to true, the system fits the camera to the output surface so that none of the given FOV values can become bigger than specified. If the aspect ratio of the output surface is different from the camera aspect, this means that either the horizontal or vertical FOV value becomes actually smaller than specified, clipping away those portions that do not fit.
In order to use a camera, it must be attached to a Graph::IView node, which specifies the actually visible area within the output surface (either the back buffer or a custom frame buffer). Attaching the camera can be done via the camera's Graph::IViewNodeTarget retrieved from GetViewNodeTarget(). If multiple cameras are attached to a single view, their drawing order can be specified via SetDepthOrder(), with higher values being "nearer", i.e. rendered later.
It is possible to define an explicit rectangular area to which the camera's given field of view is related. Setting this rectangle can be done via the SetBorderCoords() and SetBorderAnchors() methods (and related ones), which behaves analogously to setting the mask rectangle of a Graph::IView. See Graph::IView::SetMaskCoords() for details. By default, the border area covers the whole output surface, which is equivalent to all border coordinates equalling zero, and the left, top, right and bottom anchors set to the corresponding alignment values (IEnums::ALIGNMENT_X_LEFT, IEnums::ALIGNMENT_Y_TOP and so on).
Note, that setting a camera border rectangle does not actually clip the output at the given border edges; instead, the border rectangle only defines the reference edges to which the view volume is anchored. In other words, the view volume actually extends beyond this rectangle; if clipping is desired, it must be enabled in the camera's view by specifying arbitrary values for that view's mask coordinates and anchors.
Within the given border rectangle, it is possible to also define the camera's projection center via SetCenter(), with values ranging from -1.0 to 1.0 for left/right and bottom/top edges.
See Output-States, Slots und Units for an overview of state handling during scene graph traversal.
See Graph::ICameraTransform for setting a camera's position and orientation.
See Graph::ICameraState for activating a camera for rendering.
|
virtual INode * | GetNodeInterface ()=0 |
| Get the mutable Graph::INode interface. More...
|
|
virtual const INode * | GetNodeInterface () const =0 |
| Get the constant Graph::INode interface. More...
|
|
virtual ISubject * | GetSubjectInterface ()=0 |
| Get the mutable ISubject interface. More...
|
|
virtual const ISubject * | GetSubjectInterface () const =0 |
| Get the constant ISubject interface. More...
|
|
virtual ICameraNodeTarget * | GetSubCameraNodeTarget ()=0 |
| Get the mutable container holding the optional child cameras. More...
|
|
virtual const ICameraNodeTarget * | GetSubCameraNodeTarget () const =0 |
| Get the constant container holding the optional child cameras. More...
|
|
virtual IViewNodeTarget * | GetViewNodeTarget ()=0 |
| Get the mutable IViewNodeTarget container. More...
|
|
virtual const IViewNodeTarget * | GetViewNodeTarget () const =0 |
| Get the constant IViewNodeTarget container. More...
|
|
virtual Bool | SetProjectionType (IEnums::ProjectionType type)=0 |
| Set the projection type. More...
|
|
virtual IEnums::ProjectionType | GetProjectionType () const =0 |
| Get the projection type. More...
|
|
virtual Bool | SetDepthOrder (SInt32 depthOrder)=0 |
| Set the camera's absolute depth order. More...
|
|
virtual SInt32 | GetDepthOrder () const =0 |
| Get the camera's absolute depth order. More...
|
|
virtual Bool | SetFrontFacingVertexOrder (IEnums::VertexOrder order)=0 |
| Set the winding order for front-facing polygons. More...
|
|
virtual IEnums::VertexOrder | GetFrontFacingVertexOrder () const =0 |
| Get the winding order for front-facing polygons. More...
|
|
virtual Bool | SetDepthSortMode (IEnums::DepthSortMode mode)=0 |
| Set the depth sort mode for geometries within this camera. More...
|
|
virtual IEnums::DepthSortMode | GetDepthSortMode () const =0 |
| Get the depth sort mode for geometries within this camera. More...
|
|
virtual Bool | SetScreenOrientation (IEnums::ScreenOrientation orientation)=0 |
| Set the allowed screen orientation of the camera. More...
|
|
virtual IEnums::ScreenOrientation | GetScreenOrientation () const =0 |
| Get the depth sort mode for geometries within this camera. More...
|
|
virtual Bool | SetAutoDeactivationEnabled (Bool enabled)=0 |
| Enable/disable automatic deactivation if no geometry is to be rendered. More...
|
|
virtual Bool | IsAutoDeactivationEnabled () const =0 |
| Check if automatic deactivation is enabled if no geometry is to be rendered. More...
|
|
virtual Bool | SetColorBufferClearingEnabled (Bool enabled)=0 |
| Enable/disable clearing of the render target's color buffer. More...
|
|
virtual Bool | IsColorBufferClearingEnabled () const =0 |
| Check if clearing of the render target's color buffer is enabled. More...
|
|
virtual Bool | SetDepthBufferClearingEnabled (Bool enabled)=0 |
| Enable/disable clearing of the render target's depth buffer. More...
|
|
virtual Bool | IsDepthBufferClearingEnabled () const =0 |
| Check if clearing of the render target's depth buffer is enabled. More...
|
|
virtual Bool | SetStencilBufferClearingEnabled (Bool enabled)=0 |
| Enable/disable clearing of the render target's stencil buffer. More...
|
|
virtual Bool | IsStencilBufferClearingEnabled () const =0 |
| Check if clearing of the render target's stencil buffer is enabled. More...
|
|
virtual Bool | SetColorBufferClearValue (const Color &value)=0 |
| Set the clear color in effect when color buffer clearing is enabled. More...
|
|
virtual const Color & | GetColorBufferClearValue () const =0 |
| Get the clear color in effect when color buffer clearing is enabled. More...
|
|
virtual Bool | SetDepthBufferClearValue (Real value)=0 |
| Set the clear value in effect when depth buffer clearing is enabled. More...
|
|
virtual Real | GetDepthBufferClearValue () const =0 |
| Get the clear value in effect when depth buffer clearing is enabled. More...
|
|
virtual Bool | SetStencilBufferClearValue (UInt32 value)=0 |
| Set the clear value in effect when stencil buffer clearing is enabled. More...
|
|
virtual UInt32 | GetStencilBufferClearValue () const =0 |
| Get the clear value in effect when stencil buffer clearing is enabled. More...
|
|
virtual Bool | SetBorderCoords (SInt32 left, SInt32 right, SInt32 top, SInt32 bottom)=0 |
| Set the camera's view volume border coordinates. More...
|
|
virtual Bool | SetBorderCoordsX (SInt32 left, SInt32 right)=0 |
| Set the camera's horizontal view volume border coordinates. More...
|
|
virtual Bool | SetBorderCoordsY (SInt32 top, SInt32 bottom)=0 |
| Set the camera's vertical view volume border coordinates. More...
|
|
virtual SInt32 | GetLeftBorderCoord () const =0 |
| Get the camera's left view volume border coordinate. More...
|
|
virtual SInt32 | GetRightBorderCoord () const =0 |
| Get the camera's right view volume border coordinate. More...
|
|
virtual SInt32 | GetTopBorderCoord () const =0 |
| Get the camera's top view volume border coordinate. More...
|
|
virtual SInt32 | GetBottomBorderCoord () const =0 |
| Get the camera's bottom view volume border coordinate. More...
|
|
virtual Bool | SetBorderAnchors (IEnums::AlignmentX left, IEnums::AlignmentX right, IEnums::AlignmentY top, IEnums::AlignmentY bottom)=0 |
| Set the camera's view volume border anchors. More...
|
|
virtual Bool | SetBorderAnchorsX (IEnums::AlignmentX left, IEnums::AlignmentX right)=0 |
| Set the camera's horizontal view volume border anchors. More...
|
|
virtual Bool | SetBorderAnchorsY (IEnums::AlignmentY top, IEnums::AlignmentY bottom)=0 |
| Set the camera's vertical view volume border anchors. More...
|
|
virtual IEnums::AlignmentX | GetLeftBorderAnchor () const =0 |
| Get the camera's left view volume border anchor. More...
|
|
virtual IEnums::AlignmentX | GetRightBorderAnchor () const =0 |
| Get the camera's right view volume border anchor. More...
|
|
virtual IEnums::AlignmentY | GetTopBorderAnchor () const =0 |
| Get the camera's top view volume border anchor. More...
|
|
virtual IEnums::AlignmentY | GetBottomBorderAnchor () const =0 |
| Get the camera's bottom view volume border anchor. More...
|
|
virtual Bool | SetBorderMaskEnabled (Bool enabled)=0 |
| Enable/disable border masking. More...
|
|
virtual Bool | IsBorderMaskEnabled () const =0 |
| Check if border masking is enabled. More...
|
|
virtual Bool | SetAspectClippingEnabled (Bool enabled)=0 |
| Enable/disable aspect clipping. More...
|
|
virtual Bool | IsAspectClippingEnabled () const =0 |
| Check if aspect clipping is enabled. More...
|
|
virtual Bool | SetAspectRatio (Real ratio)=0 |
| Set the camera's aspect ratio. More...
|
|
virtual Real | GetAspectRatio () const =0 |
| Get the current aspect ratio. More...
|
|
virtual Bool | SetFieldOfView (Real fovX, Real fovY)=0 |
| Set the field of view at the near plane. More...
|
|
virtual Bool | SetFieldOfViewX (Real fovX)=0 |
| Set the horizontal field of view, at the near plane. More...
|
|
virtual Bool | SetFieldOfViewY (Real fovY)=0 |
| Set the vertical field of view, at the near plane. More...
|
|
virtual Real | GetFieldOfViewX () const =0 |
| Get the horizontal field of view. More...
|
|
virtual Real | GetFieldOfViewY () const =0 |
| Get the vertical field of view. More...
|
|
virtual Bool | SetUnitSize (Real unitSizeX, Real unitSizeY)=0 |
| Set the unit size, at the near plane. More...
|
|
virtual Bool | SetUnitSizeX (Real unitSizeX)=0 |
| Set the horizontal unit size, at the near plane. More...
|
|
virtual Bool | SetUnitSizeY (Real unitSizeY)=0 |
| Set the vertical unit size, at the near plane. More...
|
|
virtual Real | GetUnitSizeX () const =0 |
| Get the horizontal unit size. More...
|
|
virtual Real | GetUnitSizeY () const =0 |
| Get the vertical unit size. More...
|
|
virtual Bool | SetCenter (Real centerX, Real centerY)=0 |
| Set the projection center. More...
|
|
virtual Bool | SetCenterX (Real centerX)=0 |
| Set the horizontal projection center. More...
|
|
virtual Bool | SetCenterY (Real centerY)=0 |
| Set the vertical projection center. More...
|
|
virtual Real | GetCenterX () const =0 |
| Get the horizontal projection center. More...
|
|
virtual Real | GetCenterY () const =0 |
| Get the vertical projection center. More...
|
|
virtual Bool | SetShear (Real shearX, Real shearY)=0 |
| Set the projection shearing. More...
|
|
virtual Bool | SetShearX (Real shearX)=0 |
| Set the horizontal projection shearing. More...
|
|
virtual Bool | SetShearY (Real shearY)=0 |
| Set the vertical projection shearing. More...
|
|
virtual Real | GetShearX () const =0 |
| Get the horizontal projection shearing. More...
|
|
virtual Real | GetShearY () const =0 |
| Get the vertical projection shearing. More...
|
|
virtual Bool | SetPosition (Real posX, Real posY)=0 |
| Set the relative position within the view. More...
|
|
virtual Bool | SetPositionX (Real posX)=0 |
| Set the relative horizontal position within the view. More...
|
|
virtual Bool | SetPositionY (Real posY)=0 |
| Set the relative vertical position within the view. More...
|
|
virtual Real | GetPositionX () const =0 |
| Get the relative horizontal position within the view. More...
|
|
virtual Real | GetPositionY () const =0 |
| Get the relative vertical position within the view. More...
|
|
virtual Bool | SetSize (Real sizeX, Real sizeY)=0 |
| Set the relative size within the view. More...
|
|
virtual Bool | SetSizeX (Real sizeX)=0 |
| Set the relative horizontal size within the view. More...
|
|
virtual Bool | SetSizeY (Real sizeY)=0 |
| Set the relative vertical size within the view. More...
|
|
virtual Real | GetSizeX () const =0 |
| Get the relative horizontal size within the view. More...
|
|
virtual Real | GetSizeY () const =0 |
| Get the relative vertical size within the view. More...
|
|
virtual Bool | SetNearAndFarPlaneZ (Real nearZ, Real farZ)=0 |
| Set the absolute distances for both near and far clipping planes. More...
|
|
virtual Bool | SetNearPlaneZ (Real nearZ)=0 |
| Set the absolute distance for the near clipping plane. More...
|
|
virtual Bool | SetFarPlaneZ (Real farZ)=0 |
| Set the absolute distance for the far clipping plane. More...
|
|
virtual Real | GetNearPlaneZ () const =0 |
| Get the absolute distance for the near clipping plane. More...
|
|
virtual Real | GetFarPlaneZ () const =0 |
| Get the absolute distance for the far clipping plane. More...
|
|
virtual Bool | SetClipPlane (const Vector &clipPlane)=0 |
| Set a user-defined view volume clipping plane in world space. More...
|
|
virtual Bool | SetClipPlane (const Vector &position, const Vector &normal)=0 |
| Set a user-defined view volume clipping plane in world space. More...
|
|
virtual const Vector & | GetClipPlane () const =0 |
| Get the user-defined view volume clipping plane in world space. More...
|
|
virtual Vector | GetLocalPositionFromScreen (const Vector &screenCoord) const =0 |
| Calculate the camera space position from given screen coordinates. More...
|
|
virtual Vector | GetLocalPositionFromScreen (Real screenX, Real screenY, Real distance) const =0 |
| Calculate the camera space position from given screen coordinates. More...
|
|
virtual Vector | GetWorldPositionFromScreen (const Vector &screenCoord) const =0 |
| Calculate the world-space position from given screen coordinates. More...
|
|
virtual Vector | GetWorldPositionFromScreen (Real screenX, Real screenY, Real distance) const =0 |
| Calculate the world-space position from given screen coordinates. More...
|
|
virtual Vector | GetScreenPositionFromLocal (const Vector &localCoord) const =0 |
| Calculate the screen coordinates from a given coordinate in camera space. More...
|
|
virtual Vector | GetScreenPositionFromLocal (Real localX, Real localY, Real localZ) const =0 |
| Calculate the screen coordinates from a given coordinate in camera space. More...
|
|
virtual Vector | GetScreenPositionFromWorld (const Vector &worldCoord) const =0 |
| Calculate the screen coordinates from a given coordinate in world space. More...
|
|
virtual Vector | GetScreenPositionFromWorld (Real worldX, Real worldY, Real worldZ) const =0 |
| Calculate the screen coordinates from a given coordinate in world space. More...
|
|
virtual UInt32 | GetNumberOfStages () const =0 |
| Get the camera's number of stages. More...
|
|
virtual Video::ICamera * | GetVideoCameraObject (UInt32 stage) const =0 |
| Get the camera's internal video renderer object. More...
|
|
virtual Input::IProjection * | GetInputProjectionObject (UInt32 stage) const =0 |
| Get the camera's internal input handler object. More...
|
|
virtual Bool | SetSlot (SInt32 slot)=0 |
| Set the slot index to use. More...
|
|
virtual SInt32 | GetSlot () const =0 |
| Get the slot index to use. More...
|
|