Murl Engine Lua Addon API  Version 1.0 beta
Murl.Graph.ICamera

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 catch'd 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 equaling 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 sceneGraphStatesSlotsUnits 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.


Table members

Inherited


Murl.Graph.IStateSlot

Methods


GetNodeInterface()

Get the constant Graph::INode interface. This method returns a constant pointer to the node's Graph::INode interface, to be able to query common node properties such as active state, visibility or ID.

Murl.Graph.INode GetNodeInterface()

Returns
Murl.Graph.INode The constant Graph::INode interface, or null if not available

GetSubjectInterface()

Get the constant ISubject interface. This method returns a constant pointer to the node's ISubject interface, to be able to query subject properties such as world transform, viewing matrix, projection matrix etc.

Murl.Graph.ISubject GetSubjectInterface()

Returns
Murl.Graph.ISubject The mutable ISubject interface, or null if not available

GetSubCameraNodeTarget()

Get the constant container holding the optional child cameras. This method returns a constant pointer to the node's Graph::ICameraNodeTarget sub container, which is used to store multiple sub-cameras.

Murl.Graph.IGenericNodeTarget.GraphICamera GetSubCameraNodeTarget()

Returns
Murl.Graph.IGenericNodeTarget.GraphICamera The constant Graph::ICameraNodeTarget container, or null if not available.

GetViewNodeTarget()

Get the constant IViewNodeTarget container. This method returns a constant pointer to the node's IViewNodeTarget container, which allows to query the view object the camera is attached to.

Murl.Graph.IGenericNodeTarget.GraphIView GetViewNodeTarget()

Returns
Murl.Graph.IGenericNodeTarget.GraphIView The constant IViewNodeTarget container, or null if not available

SetProjectionType(type)

Set the projection type.

Boolean SetProjectionType(Murl.IEnums.ProjectionType type)

Parameters
typeThe projection type.
Returns
Boolean true if successful.

GetProjectionType()

Get the projection type.

Murl.IEnums.ProjectionType GetProjectionType()

Returns
Murl.IEnums.ProjectionType The projection type.

SetDepthOrder(depthOrder)

Set the camera's absolute depth order. When a Graph::IView contains more than one camera to render to, it may be necessary to define the exact order in which those cameras are overlaid. The given depth order value represents a 32 bit signed integer; higher values result in a "later" rendering on top of previous cameras, i.e. back-to-front rendering in ascending order of depth order values. See also Graph::IView::SetDepthOrder().

Boolean SetDepthOrder(Integer depthOrder)

Parameters
depthOrderThe absolute order of this camera within its view.
Returns
Boolean true if successful.

GetDepthOrder()

Get the camera's absolute depth order.

Integer GetDepthOrder()

Returns
Integer The absolute order of this camera within its view.

SetFrontFacingVertexOrder(order)

Set the winding order for front-facing polygons

Boolean SetFrontFacingVertexOrder(Murl.IEnums.VertexOrder order)

Parameters
orderThe winding order, either clockwise or counter-clockwise.
Returns
Boolean true if successful.

GetFrontFacingVertexOrder()

Get the winding order for front-facing polygons

Murl.IEnums.VertexOrder GetFrontFacingVertexOrder()

Returns
Murl.IEnums.VertexOrder The winding order, either clockwise or counter-clockwise.

SetDepthSortMode(mode)

Set the depth sort mode for geometries within this camera. When rendering alpha blended geometries, it is often necessary to sort these from back to front, to maintain correct blending.

Boolean SetDepthSortMode(Murl.IEnums.DepthSortMode mode)

Parameters
modeThe depth sort mode used for this camera.
Returns
Boolean true if successful.

GetDepthSortMode()

Get the depth sort mode for geometries within this camera.

Murl.IEnums.DepthSortMode GetDepthSortMode()

Returns
Murl.IEnums.DepthSortMode The depth sort mode used for this camera.

SetScreenOrientation(orientation)

Set the allowed screen orientation of the camera. By default, all screen orientations are allowed. Use this method to restrict the camera's orientation to the given value.

Boolean SetScreenOrientation(Murl.IEnums.ScreenOrientation orientation)

Parameters
orientationThe desired screen orientation.
Returns
Boolean true if successful.

GetScreenOrientation()

Get the depth sort mode for geometries within this camera.

Murl.IEnums.ScreenOrientation GetScreenOrientation()

Returns
Murl.IEnums.ScreenOrientation The depth sort mode used for this camera.

SetAutoDeactivationEnabled(enabled)

Enable/disable automatic deactivation if no geometry is to be rendered. When automatic deactivation is enabled, the renderer will not process that specific camera when it does not contain any visible geometry to render. In this case, the render target (e.g. frame buffer) will retain the most recently rendered image, and the target will not be cleared. When using an empty camera for e.g. clearing portions of the screen where no other camera is rendering to, this must be set to "false", otherwise this camera will never be processed.

Boolean SetAutoDeactivationEnabled(Boolean enabled)

Parameters
enabledSet to true if auto deactivation is desired.
Returns
Boolean true if successful.

IsAutoDeactivationEnabled()

Check if automatic deactivation is enabled if no geometry is to be rendered.

Boolean IsAutoDeactivationEnabled()

Returns
Boolean true if auto deactivation is enabled.

SetColorBufferClearingEnabled(enabled)

Enable/disable clearing of the render target's color buffer. When multiple cameras are defined for a specific Graph::IView (e.g. one for rendering a 3D scene and the other one for rendering a heads-up display), color buffer clearing should be disabled for the second camera to prevent overwriting all previously rendered pixels. The same applies, when multiple views with different cameras are stacked atop each other; in most cases only the "farthest away" camera should have color buffer clearing enabled. See SetColorBufferClearValue() for setting the color used for clearing. See also SetDepthBufferClearingEnabled() and SetStencilBufferClearingEnabled().

Boolean SetColorBufferClearingEnabled(Boolean enabled)

Parameters
enabledSet to false to disable color buffer clearing.
Returns
Boolean true if successful.

IsColorBufferClearingEnabled()

Check if clearing of the render target's color buffer is enabled.

Boolean IsColorBufferClearingEnabled()

Returns
Boolean true if color buffer clearing is enabled.

SetDepthBufferClearingEnabled(enabled)

Enable/disable clearing of the render target's depth buffer. In the example shown in SetColorBufferClearingEnabled(), color buffer clearing is intentionally disabled for the second camera. However, if the HUD rendered by the second camera also performs depth testing, it may be necessary to clear the depth buffer to prevent unwanted rendering artifacts. See SetDepthBufferClearValue() for setting the depth value used for clearing. See also SetStencilBufferClearingEnabled().

Boolean SetDepthBufferClearingEnabled(Boolean enabled)

Parameters
enabledSet to false to disable depth buffer clearing.
Returns
Boolean true if successful.

IsDepthBufferClearingEnabled()

Check if clearing of the render target's depth buffer is enabled.

Boolean IsDepthBufferClearingEnabled()

Returns
Boolean true if depth buffer clearing is enabled.

SetStencilBufferClearingEnabled(enabled)

Enable/disable clearing of the render target's stencil buffer. See SetStencilBufferClearValue() for setting the stencil value used for clearing. See SetDepthBufferClearingEnabled() and SetColorBufferClearingEnabled().

Boolean SetStencilBufferClearingEnabled(Boolean enabled)

Parameters
enabledSet to false to disable stencil buffer clearing.
Returns
Boolean true if successful.

IsStencilBufferClearingEnabled()

Check if clearing of the render target's stencil buffer is enabled.

Boolean IsStencilBufferClearingEnabled()

Returns
Boolean true if stencil buffer clearing is enabled.

SetColorBufferClearValue(value)

Set the clear color in effect when color buffer clearing is enabled.

Boolean SetColorBufferClearValue(Murl.Color value)

Parameters
valueThe clear color.
Returns
Boolean true if successful.

GetColorBufferClearValue()

Get the clear color in effect when color buffer clearing is enabled.

Murl.Color GetColorBufferClearValue()

Returns
Murl.Color The clear color.

SetDepthBufferClearValue(value)

Set the clear value in effect when depth buffer clearing is enabled.

Boolean SetDepthBufferClearValue(Number value)

Parameters
valueThe clear value.
Returns
Boolean true if successful.

GetDepthBufferClearValue()

Get the clear value in effect when depth buffer clearing is enabled.

Number GetDepthBufferClearValue()

Returns
Number The clear value.

SetStencilBufferClearValue(value)

Set the clear value in effect when stencil buffer clearing is enabled.

Boolean SetStencilBufferClearValue(Integer value)

Parameters
valueThe clear value.
Returns
Boolean true if successful.

GetStencilBufferClearValue()

Get the clear value in effect when stencil buffer clearing is enabled.

Integer GetStencilBufferClearValue()

Returns
Integer The clear value.

SetBorderCoords(left, right, top, bottom)

Set the camera's view volume border coordinates. See the Graph::ICamera description, and Graph::IView::SetMaskCoords().

Boolean SetBorderCoords(Integer left, Integer right, Integer top, Integer bottom)

Parameters
leftThe left border coordinate. Positive values run to the right.
rightThe right border coordinate. Positive values run to the right.
topThe top border coordinate. Positive values run up.
bottomThe bottom border coordinate. Positive values run up.
Returns
Boolean true if successful.

SetBorderCoordsX(left, right)

Set the camera's horizontal view volume border coordinates. See the Graph::ICamera description, and Graph::IView::SetMaskCoords().

Boolean SetBorderCoordsX(Integer left, Integer right)

Parameters
leftThe left border coordinate.
rightThe right border coordinate.
Returns
Boolean true if successful.

SetBorderCoordsY(top, bottom)

Set the camera's vertical view volume border coordinates. See the Graph::ICamera description, and Graph::IView::SetMaskCoords().

Boolean SetBorderCoordsY(Integer top, Integer bottom)

Parameters
topThe top border coordinate. Positive values run up.
bottomThe bottom border coordinate. Positive values run up.
Returns
Boolean true if successful.

GetLeftBorderCoord()

Get the camera's left view volume border coordinate. See the Graph::ICamera description, and Graph::IView::SetMaskCoords().

Integer GetLeftBorderCoord()

Returns
Integer The left border coordinate.

GetRightBorderCoord()

Get the camera's right view volume border coordinate. See the Graph::ICamera description, and Graph::IView::SetMaskCoords().

Integer GetRightBorderCoord()

Returns
Integer The right border coordinate.

GetTopBorderCoord()

Get the camera's top view volume border coordinate. See the Graph::ICamera description, and Graph::IView::SetMaskCoords().

Integer GetTopBorderCoord()

Returns
Integer The top border coordinate.

GetBottomBorderCoord()

Get the camera's bottom view volume border coordinate. See the Graph::ICamera description, and Graph::IView::SetMaskCoords().

Integer GetBottomBorderCoord()

Returns
Integer The bottom border coordinate.

SetBorderAnchors(left, right, top, bottom)

Set the camera's view volume border anchors. See the Graph::ICamera description, and Graph::IView::SetMaskCoords().

Boolean SetBorderAnchors(Murl.IEnums.AlignmentX left, Murl.IEnums.AlignmentX right, Murl.IEnums.AlignmentY top, Murl.IEnums.AlignmentY bottom)

Parameters
leftThe left border anchor.
rightThe right border anchor.
topThe top border anchor.
bottomThe bottom border anchor.
Returns
Boolean true if successful.

SetBorderAnchorsX(left, right)

Set the camera's horizontal view volume border anchors. See the Graph::ICamera description, and Graph::IView::SetMaskCoords().

Boolean SetBorderAnchorsX(Murl.IEnums.AlignmentX left, Murl.IEnums.AlignmentX right)

Parameters
leftThe left border anchor.
rightThe right border anchor.
Returns
Boolean true if successful.

SetBorderAnchorsY(top, bottom)

Set the camera's vertical view volume border anchors. See the Graph::ICamera description, and Graph::IView::SetMaskCoords().

Boolean SetBorderAnchorsY(Murl.IEnums.AlignmentY top, Murl.IEnums.AlignmentY bottom)

Parameters
topThe top border anchor.
bottomThe bottom border anchor.
Returns
Boolean true if successful.

GetLeftBorderAnchor()

Get the camera's left view volume border anchor. See the Graph::ICamera description, and Graph::IView::SetMaskCoords().

Murl.IEnums.AlignmentX GetLeftBorderAnchor()

Returns
Murl.IEnums.AlignmentX The left border anchor.

GetRightBorderAnchor()

Get the camera's right view volume border anchor. See the Graph::ICamera description, and Graph::IView::SetMaskCoords().

Murl.IEnums.AlignmentX GetRightBorderAnchor()

Returns
Murl.IEnums.AlignmentX The right border anchor.

GetTopBorderAnchor()

Get the camera's top view volume border anchor. See the Graph::ICamera description, and Graph::IView::SetMaskCoords().

Murl.IEnums.AlignmentY GetTopBorderAnchor()

Returns
Murl.IEnums.AlignmentY The top border anchor.

GetBottomBorderAnchor()

Get the camera's bottom view volume border anchor. See the Graph::ICamera description, and Graph::IView::SetMaskCoords().

Murl.IEnums.AlignmentY GetBottomBorderAnchor()

Returns
Murl.IEnums.AlignmentY The bottom border anchor.

SetBorderMaskEnabled(enabled)

Enable/disable border masking. See the Graph::ICamera description.

Boolean SetBorderMaskEnabled(Boolean enabled)

Parameters
enabledIf true, masking is enabled.
Returns
Boolean true if successful.

IsBorderMaskEnabled()

Check if border masking is enabled.

Boolean IsBorderMaskEnabled()

Returns
Boolean true if masking is enabled.

SetAspectClippingEnabled(enabled)

Enable/disable aspect clipping. See the Graph::ICamera description.

Boolean SetAspectClippingEnabled(Boolean enabled)

Parameters
enabledIf true, aspect clipping is enabled.
Returns
Boolean true if successful.

IsAspectClippingEnabled()

Check if aspect clipping is enabled.

Boolean IsAspectClippingEnabled()

Returns
Boolean true if clipping is enabled.

SetAspectRatio(ratio)

Set the camera's aspect ratio. The aspect ratio is used in different ways to calculate the actual field of view and border area, depending on the given FOV parameters:

  • If only one axis is defined using a unit size value, the missing one is calculated so that the virtual coordinate system maintains the given X:Y aspect ratio.
  • The same is true if only a single FOV value is given; in this case the FOV of the other axis grows or shrinks depending on the window size and window aspect.
  • If both FOV axes are specified and the given aspect ratio is not 0, the FOV of both axes remains as defined. Here, the actual outcome depends on whether aspect clipping and/or border masking is enabled or not:
  • If aspect clipping is enabled, the camera calculates the actual FOV so that the view area is always fully covered. If the window aspect is smaller than the FOV aspect (the window is taller than the FOV), the vertical FOV is clipped. If the window aspect is greater (wider than the FOV), the horizontal FOV is clipped.
  • If aspect clipping is disabled, the camera always keeps both FOV axes fully within the view. If the window is taller than the FOV, borders are added vertically, and if it is wider, horizontal borders are added. Note, that it is necessary to enable border masking (see SetBorderMaskEnabled()) so that these borders actually have effect.
  • If both FOV axes are specified and the given aspect ratio equals 0, the given FOV values are directly used regardless of the actual view size. In other words, the virtual coordinate system gets skewed, resulting in non-square coordinate units on screen.

Boolean SetAspectRatio(Number ratio)

Parameters
ratioThe X:Y aspect ratio.
Returns
Boolean true if successful.

GetAspectRatio()

Get the current aspect ratio.

Number GetAspectRatio()

Returns
Number The X:Y aspect ratio.

SetFieldOfView(fovX, fovY)

Set the field of view at the near plane. This method sets both the horizontal and vertical field of view values. See the detailed description above on how the camera's viewing volume is calculated from these values.

Boolean SetFieldOfView(Number fovX, Number fovY)

Parameters
fovXThe horizontal field of view.
fovYThe vertical field of view.
Returns
Boolean true if successful.

SetFieldOfViewX(fovX)

Set the horizontal field of view, at the near plane. See the detailed description above on how the camera's viewing volume is calculated.

Boolean SetFieldOfViewX(Number fovX)

Parameters
fovXThe horizontal field of view.
Returns
Boolean true if successful.

SetFieldOfViewY(fovY)

Set the vertical field of view, at the near plane. See the detailed description above on how the camera's viewing volume is calculated.

Boolean SetFieldOfViewY(Number fovY)

Parameters
fovYThe vertical field of view.
Returns
Boolean true if successful.

GetFieldOfViewX()

Get the horizontal field of view.

Number GetFieldOfViewX()

Returns
Number The horizontal field of view, or 0.0 if variable.

GetFieldOfViewY()

Get the vertical field of view.

Number GetFieldOfViewY()

Returns
Number The vertical field of view, or 0.0 if variable.

SetUnitSize(unitSizeX, unitSizeY)

Set the unit size, at the near plane. This method sets both the horizontal and vertical unit size. See the detailed description above on how the camera's viewing volume is calculated from these values.

Boolean SetUnitSize(Number unitSizeX, Number unitSizeY)

Parameters
unitSizeXThe horizontal unit size.
unitSizeYThe vertical unit size.
Returns
Boolean true if successful.

SetUnitSizeX(unitSizeX)

Set the horizontal unit size, at the near plane. See the detailed description above on how the camera's viewing volume is calculated.

Boolean SetUnitSizeX(Number unitSizeX)

Parameters
unitSizeXThe horizontal unit size.
Returns
Boolean true if successful.

SetUnitSizeY(unitSizeY)

Set the vertical unit size, at the near plane. See the detailed description above on how the camera's viewing volume is calculated.

Boolean SetUnitSizeY(Number unitSizeY)

Parameters
unitSizeYThe vertical unit size.
Returns
Boolean true if successful.

GetUnitSizeX()

Get the horizontal unit size.

Number GetUnitSizeX()

Returns
Number The horizontal unit size, or 0.0 if variable.

GetUnitSizeY()

Get the vertical unit size.

Number GetUnitSizeY()

Returns
Number The vertical unit size, or 0.0 if variable.

SetCenter(centerX, centerY)

Set the projection center.

Boolean SetCenter(Number centerX, Number centerY)

Parameters
centerXThe horizontal projection center.
centerYThe vertical projection center.
Returns
Boolean true if successful.

SetCenterX(centerX)

Set the horizontal projection center.

Boolean SetCenterX(Number centerX)

Parameters
centerXThe horizontal projection center.
Returns
Boolean true if successful.

SetCenterY(centerY)

Set the vertical projection center.

Boolean SetCenterY(Number centerY)

Parameters
centerYThe vertical projection center.
Returns
Boolean true if successful.

GetCenterX()

Get the horizontal projection center.

Number GetCenterX()

Returns
Number The horizontal projection center.

GetCenterY()

Get the vertical projection center.

Number GetCenterY()

Returns
Number The vertical projection center.

SetShear(shearX, shearY)

Set the projection shearing.

Boolean SetShear(Number shearX, Number shearY)

Parameters
shearXThe horizontal projection shearing.
shearYThe vertical projection shearing.
Returns
Boolean true if successful.

SetShearX(shearX)

Set the horizontal projection shearing.

Boolean SetShearX(Number shearX)

Parameters
shearXThe horizontal projection shearing.
Returns
Boolean true if successful.

SetShearY(shearY)

Set the vertical projection shearing.

Boolean SetShearY(Number shearY)

Parameters
shearYThe vertical projection shearing.
Returns
Boolean true if successful.

GetShearX()

Get the horizontal projection shearing.

Number GetShearX()

Returns
Number The horizontal projection shearing.

GetShearY()

Get the vertical projection shearing.

Number GetShearY()

Returns
Number The vertical projection shearing.

SetPosition(posX, posY)

Set the relative position within the view.

Boolean SetPosition(Number posX, Number posY)

Parameters
posXThe horizontal position.
posYThe vertical position.
Returns
Boolean true if successful.

SetPositionX(posX)

Set the relative horizontal position within the view.

Boolean SetPositionX(Number posX)

Parameters
posXThe horizontal position.
Returns
Boolean true if successful.

SetPositionY(posY)

Set the relative vertical position within the view.

Boolean SetPositionY(Number posY)

Parameters
posYThe vertical position.
Returns
Boolean true if successful.

GetPositionX()

Get the relative horizontal position within the view.

Number GetPositionX()

Returns
Number The horizontal position.

GetPositionY()

Get the relative vertical position within the view.

Number GetPositionY()

Returns
Number The vertical position.

SetSize(sizeX, sizeY)

Set the relative size within the view.

Boolean SetSize(Number sizeX, Number sizeY)

Parameters
sizeXThe horizontal size.
sizeYThe vertical size.
Returns
Boolean true if successful.

SetSizeX(sizeX)

Set the relative horizontal size within the view.

Boolean SetSizeX(Number sizeX)

Parameters
sizeXThe horizontal size.
Returns
Boolean true if successful.

SetSizeY(sizeY)

Set the relative vertical size within the view.

Boolean SetSizeY(Number sizeY)

Parameters
sizeYThe vertical size.
Returns
Boolean true if successful.

GetSizeX()

Get the relative horizontal size within the view.

Number GetSizeX()

Returns
Number The horizontal size.

GetSizeY()

Get the relative vertical size within the view.

Number GetSizeY()

Returns
Number The vertical size.

SetNearAndFarPlaneZ(nearZ, farZ)

Set the absolute distances for both near and far clipping planes. Both values must be positive, with 0 < nearZ < farZ.

Boolean SetNearAndFarPlaneZ(Number nearZ, Number farZ)

Parameters
nearZThe positive near plane distance.
farZThe positive near plane distance.
Returns
Boolean true if successful.

SetNearPlaneZ(nearZ)

Set the absolute distance for the near clipping plane. See SetNearAndFarPlaneZ().

Boolean SetNearPlaneZ(Number nearZ)

Parameters
nearZThe positive near plane distance.
Returns
Boolean true if successful.

SetFarPlaneZ(farZ)

Set the absolute distance for the far clipping plane. See SetNearAndFarPlaneZ().

Boolean SetFarPlaneZ(Number farZ)

Parameters
farZThe positive near plane distance.
Returns
Boolean true if successful.

GetNearPlaneZ()

Get the absolute distance for the near clipping plane.

Number GetNearPlaneZ()

Returns
Number The positive near plane distance.

GetFarPlaneZ()

Get the absolute distance for the far clipping plane.

Number GetFarPlaneZ()

Returns
Number The positive far plane distance.

SetClipPlane(clipPlane)

Set a user-defined view volume clipping plane in world space.

Boolean SetClipPlane(Murl.Math.Vector clipPlane)

Parameters
clipPlaneA vector holding the A, B, C and D coefficients from the plane equation defining the clipping plane, contained in the vector's x, y, z and w components, respectively. The x, y and z components represent the actual plane normal, where the w component represents the plane's normal distance from the origin.
Returns
Boolean true if successful.

SetClipPlane(position, normal)

Set a user-defined view volume clipping plane in world space.

Boolean SetClipPlane(Murl.Math.Vector position, Murl.Math.Vector normal)

Parameters
positionA vector holding the position of an arbitrary point in world space that is lying on the clip plane.
normalA vector holding the clipping plane's normal vector in its x, y and z components.
Returns
Boolean true if successful.

GetClipPlane()

Get the user-defined view volume clipping plane in world space.

Murl.Math.Vector GetClipPlane()

Returns
Murl.Math.Vector A vector holding the A, B, C and D coefficients from the plane equation defining the clipping plane, contained in the vector's x, y, z and w components, respectively.

GetLocalPositionFromScreen(screenX, screenY, distance)

Calculate the camera space position from given screen coordinates. See GetLocalPositionFromScreen(const Vector& screenCoord).

Murl.Math.Vector GetLocalPositionFromScreen(Number screenX, Number screenY, Number distance)

Parameters
screenXThe X coordinate on screen for which to calculate the local point.
screenYThe Y coordinate on screen for which to calculate the local point.
distanceThe distance from the camera.
Returns
Murl.Math.Vector The camera-space position.

GetLocalPositionFromScreen(screenCoord)

Calculate the camera space position from given screen coordinates. This method can be used to get a vector to a point in camera space, defined by a pair of X and Y screen coordinates, and a distance along the camera's viewing axis. As the viewing axis is always parallel to the Z axis, looking in the negative direction, the given distance must also be negative to represent a point in front of the camera.

Murl.Math.Vector GetLocalPositionFromScreen(Murl.Math.Vector screenCoord)

Parameters
screenCoordA vector containing the horizontal and vertical screen coordinates in the X and Y components, and the distance from the camera along its viewing axis in the Z component. A negative distance represents a point in front of the camera.
Returns
Murl.Math.Vector The camera-space position.

GetWorldPositionFromScreen(screenX, screenY, distance)

Calculate the world-space position from given screen coordinates. See GetWorldPositionFromScreen(const Vector& screenCoord).

Murl.Math.Vector GetWorldPositionFromScreen(Number screenX, Number screenY, Number distance)

Parameters
screenXThe X coordinate on screen for which to calculate the world point.
screenYThe Y coordinate on screen for which to calculate the world point.
distanceThe distance from the camera.
Returns
Murl.Math.Vector The world-space position.

GetWorldPositionFromScreen(screenCoord)

Calculate the world-space position from given screen coordinates. This method first calculates the local position via GetLocalPositionFromScreen(), and then transforms the resulting point to world space by multiplying it with the camera's world transform.

Murl.Math.Vector GetWorldPositionFromScreen(Murl.Math.Vector screenCoord)

Parameters
screenCoordA vector containing the horizontal and vertical screen coordinates in the X and Y components, and the distance from the camera along its viewing axis in the Z component. A negative distance represents a point in front of the camera.
Returns
Murl.Math.Vector The world-space position.

GetScreenPositionFromLocal(localX, localY, localZ)

Calculate the screen coordinates from a given coordinate in camera space. See GetScreenPositionFromLocal(const Vector& localCoord).

Murl.Math.Vector GetScreenPositionFromLocal(Number localX, Number localY, Number localZ)

Parameters
localXThe input coordinate's X component, in camera space.
localYThe input coordinate's Y component, in camera space.
localZThe input coordinate's Z component, in camera space.
Returns
Murl.Math.Vector The camera space position.

GetScreenPositionFromLocal(localCoord)

Calculate the screen coordinates from a given coordinate in camera space. This method performs a regular view space to screen space transformation, using the projection matrix set for the camera. The input coordinate is relative to the camera itself.

Murl.Math.Vector GetScreenPositionFromLocal(Murl.Math.Vector localCoord)

Parameters
localCoordThe coordinate to transform, in camera space.
Returns
Murl.Math.Vector The camera space position.

GetScreenPositionFromWorld(worldX, worldY, worldZ)

Calculate the screen coordinates from a given coordinate in world space. See GetScreenPositionFromWorld(const Vector& worldCoord).

Murl.Math.Vector GetScreenPositionFromWorld(Number worldX, Number worldY, Number worldZ)

Parameters
worldXThe input coordinate's X component, in world space.
worldYThe input coordinate's Y component, in world space.
worldZThe input coordinate's Z component, in world space.
Returns
Murl.Math.Vector The camera space position.

GetScreenPositionFromWorld(worldCoord)

Calculate the screen coordinates from a given coordinate in world space. This method performs a regular world space to screen space transformation, using the inverse model matrix and the regular projection matrix set for the camera. The input coordinate represents an absolute world position.

Murl.Math.Vector GetScreenPositionFromWorld(Murl.Math.Vector worldCoord)

Parameters
worldCoordThe coordinate to transform, in world space.
Returns
Murl.Math.Vector The camera space position.

GetNumberOfStages()

Get the camera's number of stages.

Integer GetNumberOfStages()

Returns
Integer The number of stages.

GetInputProjectionObject(stage)

Get the camera's internal input handler object.

Murl.Input.IProjection GetInputProjectionObject(Integer stage)

Parameters
stageThe stage to query.
Returns
Murl.Input.IProjection The input handler object.

SetMaskCoords(left, right, top, bottom)

Set the camera mask's border coordinates. To define a rectangular mask for the view, it is necessary to specify 4 values, one for each edge of the desired rectangle: left, right, top and bottom. In addition, it is necessary to specify an anchor point for each of these edges, via SetMaskAnchors() or related methods, which represents the absolute origin for the respective coordinate value. For example, if the left coordinate value is set to a value of 50 and the left anchor is set to IEnums::ALIGNMENT_X_LEFT, the mask is always anchored at the left window edge with an offset of 50 units to the right. If the left coordinate has a value of -200 and the left anchor is set to IEnums::ALIGNMENT_X_RIGHT, the mask's left border will always be 200 units left of the right window border. Note that the engine's camera coordinate origin is at the center of the screen with positive Y values running up. Therefore, to define e.g. a vertical mask that clips 100 units from both top and bottom, it is necessary to specify a value of +100 for the bottom coordinate (with the bottom anchor set to IEnums::ALIGNMENT_Y_BOTTOM), and a value of -100 for the top coordinate, with IEnums::ALIGNMENT_Y_TOP for the top anchor.

SetMaskCoords(Number left, Number right, Number top, Number bottom)

Parameters
leftThe left mask coordinate. Positive values run to the right.
rightThe right mask coordinate. Positive values run to the right.
topThe top mask coordinate. Positive values run up.
bottomThe bottom mask coordinate. Positive values run up.

SetMaskCoordsX(left, right)

Set the view mask's horizontal border coordinates. See SetMaskCoords() for details.

SetMaskCoordsX(Number left, Number right)

Parameters
leftThe left mask coordinate.
rightThe right mask coordinate.

SetMaskCoordsY(top, bottom)

Set the view mask's vertical border coordinates. See SetMaskCoords() for details.

SetMaskCoordsY(Number top, Number bottom)

Parameters
topThe top mask coordinate.
bottomThe bottom mask coordinate.

GetLeftMaskCoord()

Get the view mask's left border coordinate. See SetMaskCoords() for details.

Number GetLeftMaskCoord()

Returns
Number The left mask coordinate.

GetRightMaskCoord()

Get the view mask's right border coordinate. See SetMaskCoords() for details.

Number GetRightMaskCoord()

Returns
Number The right mask coordinate.

GetTopMaskCoord()

Get the view mask's top border coordinate. See SetMaskCoords() for details.

Number GetTopMaskCoord()

Returns
Number The top mask coordinate.

GetBottomMaskCoord()

Get the view mask's bottom border coordinate. See SetMaskCoords() for details.

Number GetBottomMaskCoord()

Returns
Number The bottom mask coordinate.

SetMaskAnchors(left, right, top, bottom)

Set the view mask's border anchors. See SetMaskCoords() for details.

SetMaskAnchors(Murl.IEnums.AlignmentX left, Murl.IEnums.AlignmentX right, Murl.IEnums.AlignmentY top, Murl.IEnums.AlignmentY bottom)

Parameters
leftThe left mask anchor.
rightThe right mask anchor.
topThe top mask anchor.
bottomThe bottom mask anchor.

SetMaskAnchorsX(left, right)

Set the view mask's horizontal border anchors. See SetMaskCoords() for details.

SetMaskAnchorsX(Murl.IEnums.AlignmentX left, Murl.IEnums.AlignmentX right)

Parameters
leftThe left mask anchor.
rightThe right mask anchor.

SetMaskAnchorsY(top, bottom)

Set the view mask's vertical border anchors. See SetMaskCoords() for details.

SetMaskAnchorsY(Murl.IEnums.AlignmentY top, Murl.IEnums.AlignmentY bottom)

Parameters
topThe top mask anchor.
bottomThe bottom mask anchor.

GetLeftMaskAnchor()

Get the view mask's left border anchor. See SetMaskCoords() for details.

Murl.IEnums.AlignmentX GetLeftMaskAnchor()

Returns
Murl.IEnums.AlignmentX The left mask anchor.

GetRightMaskAnchor()

Get the view mask's right border anchor. See SetMaskCoords() for details.

Murl.IEnums.AlignmentX GetRightMaskAnchor()

Returns
Murl.IEnums.AlignmentX The right mask anchor.

GetTopMaskAnchor()

Get the view mask's top border anchor. See SetMaskCoords() for details.

Murl.IEnums.AlignmentY GetTopMaskAnchor()

Returns
Murl.IEnums.AlignmentY The top mask anchor.

GetBottomMaskAnchor()

Get the view mask's bottom border anchor. See SetMaskCoords() for details.

Murl.IEnums.AlignmentY GetBottomMaskAnchor()

Returns
Murl.IEnums.AlignmentY The bottom mask anchor.

SetMaskCoordScaleFactor(factor)

Set the view mask's coordinates scale factor. See SetMaskCoords() for details.

SetMaskCoordScaleFactor(Number factor)

Parameters
factormask coordinates will be multiplied by 1/factor.