![]() |
Murl Engine Lua Addon API
Version 1.0 beta
|
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:
The actual meaning of the given values is different for each type of camera:
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:
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 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.
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()
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()
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()
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()
Set the projection type.
Boolean SetProjectionType(Murl.IEnums.ProjectionType type)
type | The projection type. |
Get the projection type.
Murl.IEnums.ProjectionType GetProjectionType()
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)
depthOrder | The absolute order of this camera within its view. |
Get the camera's absolute depth order.
Integer GetDepthOrder()
Set the winding order for front-facing polygons
Boolean SetFrontFacingVertexOrder(Murl.IEnums.VertexOrder order)
order | The winding order, either clockwise or counter-clockwise. |
Get the winding order for front-facing polygons
Murl.IEnums.VertexOrder GetFrontFacingVertexOrder()
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)
mode | The depth sort mode used for this camera. |
Get the depth sort mode for geometries within this camera.
Murl.IEnums.DepthSortMode GetDepthSortMode()
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)
orientation | The desired screen orientation. |
Get the depth sort mode for geometries within this camera.
Murl.IEnums.ScreenOrientation GetScreenOrientation()
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)
enabled | Set to true if auto deactivation is desired. |
Check if automatic deactivation is enabled if no geometry is to be rendered.
Boolean IsAutoDeactivationEnabled()
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)
enabled | Set to false to disable color buffer clearing. |
Check if clearing of the render target's color buffer is enabled.
Boolean IsColorBufferClearingEnabled()
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)
enabled | Set to false to disable depth buffer clearing. |
Check if clearing of the render target's depth buffer is enabled.
Boolean IsDepthBufferClearingEnabled()
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)
enabled | Set to false to disable stencil buffer clearing. |
Check if clearing of the render target's stencil buffer is enabled.
Boolean IsStencilBufferClearingEnabled()
Set the clear color in effect when color buffer clearing is enabled.
Boolean SetColorBufferClearValue(Murl.Color value)
value | The clear color. |
Get the clear color in effect when color buffer clearing is enabled.
Murl.Color GetColorBufferClearValue()
Set the clear value in effect when depth buffer clearing is enabled.
Boolean SetDepthBufferClearValue(Number value)
value | The clear value. |
Get the clear value in effect when depth buffer clearing is enabled.
Number GetDepthBufferClearValue()
Set the clear value in effect when stencil buffer clearing is enabled.
Boolean SetStencilBufferClearValue(Integer value)
value | The clear value. |
Get the clear value in effect when stencil buffer clearing is enabled.
Integer GetStencilBufferClearValue()
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)
left | The left border coordinate. Positive values run to the right. |
right | The right border coordinate. Positive values run to the right. |
top | The top border coordinate. Positive values run up. |
bottom | The bottom border coordinate. Positive values run up. |
Set the camera's horizontal view volume border coordinates. See the Graph::ICamera description, and Graph::IView::SetMaskCoords().
Boolean SetBorderCoordsX(Integer left, Integer right)
left | The left border coordinate. |
right | The right border coordinate. |
Set the camera's vertical view volume border coordinates. See the Graph::ICamera description, and Graph::IView::SetMaskCoords().
Boolean SetBorderCoordsY(Integer top, Integer bottom)
top | The top border coordinate. Positive values run up. |
bottom | The bottom border coordinate. Positive values run up. |
Get the camera's left view volume border coordinate. See the Graph::ICamera description, and Graph::IView::SetMaskCoords().
Integer GetLeftBorderCoord()
Get the camera's right view volume border coordinate. See the Graph::ICamera description, and Graph::IView::SetMaskCoords().
Integer GetRightBorderCoord()
Get the camera's top view volume border coordinate. See the Graph::ICamera description, and Graph::IView::SetMaskCoords().
Integer GetTopBorderCoord()
Get the camera's bottom view volume border coordinate. See the Graph::ICamera description, and Graph::IView::SetMaskCoords().
Integer GetBottomBorderCoord()
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)
left | The left border anchor. |
right | The right border anchor. |
top | The top border anchor. |
bottom | The bottom border anchor. |
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)
left | The left border anchor. |
right | The right border anchor. |
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)
top | The top border anchor. |
bottom | The bottom border anchor. |
Get the camera's left view volume border anchor. See the Graph::ICamera description, and Graph::IView::SetMaskCoords().
Murl.IEnums.AlignmentX GetLeftBorderAnchor()
Get the camera's right view volume border anchor. See the Graph::ICamera description, and Graph::IView::SetMaskCoords().
Murl.IEnums.AlignmentX GetRightBorderAnchor()
Get the camera's top view volume border anchor. See the Graph::ICamera description, and Graph::IView::SetMaskCoords().
Murl.IEnums.AlignmentY GetTopBorderAnchor()
Get the camera's bottom view volume border anchor. See the Graph::ICamera description, and Graph::IView::SetMaskCoords().
Murl.IEnums.AlignmentY GetBottomBorderAnchor()
Enable/disable border masking. See the Graph::ICamera description.
Boolean SetBorderMaskEnabled(Boolean enabled)
enabled | If true, masking is enabled. |
Check if border masking is enabled.
Boolean IsBorderMaskEnabled()
Enable/disable aspect clipping. See the Graph::ICamera description.
Boolean SetAspectClippingEnabled(Boolean enabled)
enabled | If true, aspect clipping is enabled. |
Check if aspect clipping is enabled.
Boolean IsAspectClippingEnabled()
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:
Boolean SetAspectRatio(Number ratio)
ratio | The X:Y aspect ratio. |
Get the current aspect ratio.
Number GetAspectRatio()
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)
fovX | The horizontal field of view. |
fovY | The vertical field of view. |
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)
fovX | The horizontal field of view. |
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)
fovY | The vertical field of view. |
Get the horizontal field of view.
Number GetFieldOfViewX()
Get the vertical field of view.
Number GetFieldOfViewY()
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)
unitSizeX | The horizontal unit size. |
unitSizeY | The vertical unit size. |
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)
unitSizeX | The horizontal unit size. |
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)
unitSizeY | The vertical unit size. |
Get the horizontal unit size.
Number GetUnitSizeX()
Get the vertical unit size.
Number GetUnitSizeY()
Set the projection center.
Boolean SetCenter(Number centerX, Number centerY)
centerX | The horizontal projection center. |
centerY | The vertical projection center. |
Set the horizontal projection center.
Boolean SetCenterX(Number centerX)
centerX | The horizontal projection center. |
Set the vertical projection center.
Boolean SetCenterY(Number centerY)
centerY | The vertical projection center. |
Get the horizontal projection center.
Number GetCenterX()
Get the vertical projection center.
Number GetCenterY()
Set the projection shearing.
Boolean SetShear(Number shearX, Number shearY)
shearX | The horizontal projection shearing. |
shearY | The vertical projection shearing. |
Set the horizontal projection shearing.
Boolean SetShearX(Number shearX)
shearX | The horizontal projection shearing. |
Set the vertical projection shearing.
Boolean SetShearY(Number shearY)
shearY | The vertical projection shearing. |
Get the horizontal projection shearing.
Number GetShearX()
Get the vertical projection shearing.
Number GetShearY()
Set the relative position within the view.
Boolean SetPosition(Number posX, Number posY)
posX | The horizontal position. |
posY | The vertical position. |
Set the relative horizontal position within the view.
Boolean SetPositionX(Number posX)
posX | The horizontal position. |
Set the relative vertical position within the view.
Boolean SetPositionY(Number posY)
posY | The vertical position. |
Get the relative horizontal position within the view.
Number GetPositionX()
Get the relative vertical position within the view.
Number GetPositionY()
Set the relative size within the view.
Boolean SetSize(Number sizeX, Number sizeY)
sizeX | The horizontal size. |
sizeY | The vertical size. |
Set the relative horizontal size within the view.
Boolean SetSizeX(Number sizeX)
sizeX | The horizontal size. |
Set the relative vertical size within the view.
Boolean SetSizeY(Number sizeY)
sizeY | The vertical size. |
Get the relative horizontal size within the view.
Number GetSizeX()
Get the relative vertical size within the view.
Number GetSizeY()
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)
nearZ | The positive near plane distance. |
farZ | The positive near plane distance. |
Set the absolute distance for the near clipping plane. See SetNearAndFarPlaneZ().
Boolean SetNearPlaneZ(Number nearZ)
nearZ | The positive near plane distance. |
Set the absolute distance for the far clipping plane. See SetNearAndFarPlaneZ().
Boolean SetFarPlaneZ(Number farZ)
farZ | The positive near plane distance. |
Get the absolute distance for the near clipping plane.
Number GetNearPlaneZ()
Get the absolute distance for the far clipping plane.
Number GetFarPlaneZ()
Set a user-defined view volume clipping plane in world space.
Boolean SetClipPlane(Murl.Math.Vector clipPlane)
clipPlane | 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. The x, y and z components represent the actual plane normal, where the w component represents the plane's normal distance from the origin. |
Set a user-defined view volume clipping plane in world space.
Boolean SetClipPlane(Murl.Math.Vector position, Murl.Math.Vector normal)
position | A vector holding the position of an arbitrary point in world space that is lying on the clip plane. |
normal | A vector holding the clipping plane's normal vector in its x, y and z components. |
Get the user-defined view volume clipping plane in world space.
Murl.Math.Vector GetClipPlane()
Calculate the camera space position from given screen coordinates. See GetLocalPositionFromScreen(const Vector& screenCoord).
Murl.Math.Vector GetLocalPositionFromScreen(Number screenX, Number screenY, Number distance)
screenX | The X coordinate on screen for which to calculate the local point. |
screenY | The Y coordinate on screen for which to calculate the local point. |
distance | The distance from the camera. |
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)
screenCoord | A 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. |
Calculate the world-space position from given screen coordinates. See GetWorldPositionFromScreen(const Vector& screenCoord).
Murl.Math.Vector GetWorldPositionFromScreen(Number screenX, Number screenY, Number distance)
screenX | The X coordinate on screen for which to calculate the world point. |
screenY | The Y coordinate on screen for which to calculate the world point. |
distance | The distance from the camera. |
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)
screenCoord | A 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. |
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)
localX | The input coordinate's X component, in camera space. |
localY | The input coordinate's Y component, in camera space. |
localZ | The input coordinate's Z component, in camera space. |
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)
localCoord | The coordinate to transform, in camera space. |
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)
worldX | The input coordinate's X component, in world space. |
worldY | The input coordinate's Y component, in world space. |
worldZ | The input coordinate's Z component, in world space. |
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)
worldCoord | The coordinate to transform, in world space. |
Get the camera's number of stages.
Integer GetNumberOfStages()
Get the camera's internal input handler object.
Murl.Input.IProjection GetInputProjectionObject(Integer stage)
stage | The stage to query. |