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

The IView graph node interface.

A view specifies the actually visible area within an output surface. Which output surface is used can be controlled by setting the Graph::IFrameBufferNodeTarget retrieved from GetFrameBufferNodeTarget(). If a null pointer is given, the view will render to the system back buffer, otherwise it is possible to set the target to a given Graph::IFrameBuffer node, which will instruct the view to render to that custom frame buffer.

A view can have any number of cameras attached, see the description of Graph::ICamera and Graph::ICamera::GetViewNodeTarget().

If multiple views are attached to the same output buffer, their drawing order can be specified via SetDepthOrder(), with higher values being "nearer", i.e. rendered later.

To allow for only rendering to a rectangular sub-region of the output surface, the view's SetMaskCoords() and SetMaskAnchors() methods (and related ones) can be used. By default, the view covers the whole output surface, which is equivalent to all mask 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). See SetMaskCoords() for details.


Table members

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

GetFrameBufferNodeTarget()

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

Murl.Graph.IGenericNodeTarget.GraphIFrameBuffer GetFrameBufferNodeTarget()

Returns
Murl.Graph.IGenericNodeTarget.GraphIFrameBuffer The constant IFrameBufferNodeTarget container, or null if not available

SetDepthOrder(depthOrder)

Set the view's absolute depth order. Analogous to Graph::ICamera::SetDepthOrder().

Boolean SetDepthOrder(Integer depthOrder)

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

GetDepthOrder()

Get the view's absolute depth order.

Integer GetDepthOrder()

Returns
Integer The absolute order of this view within its frame buffer.

SetMaskCoords(left, right, top, bottom)

Set the view 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 pixels 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 pixels left of the right window border. Note that the engine's window coordinate origin is at the left bottom corner of the surface with positive Y values running up. Therefore, to define e.g. a vertical mask that clips 100 pixels 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.

Boolean SetMaskCoords(Integer left, Integer right, Integer top, Integer 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.
Returns
Boolean true if successful.

SetMaskCoordsX(left, right)

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

Boolean SetMaskCoordsX(Integer left, Integer right)

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

SetMaskCoordsY(top, bottom)

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

Boolean SetMaskCoordsY(Integer top, Integer bottom)

Parameters
topThe top mask coordinate.
bottomThe bottom mask coordinate.
Returns
Boolean true if successful.

GetLeftMaskCoord()

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

Integer GetLeftMaskCoord()

Returns
Integer The left mask coordinate.

GetRightMaskCoord()

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

Integer GetRightMaskCoord()

Returns
Integer The right mask coordinate.

GetTopMaskCoord()

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

Integer GetTopMaskCoord()

Returns
Integer The top mask coordinate.

GetBottomMaskCoord()

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

Integer GetBottomMaskCoord()

Returns
Integer The bottom mask coordinate.

SetMaskAnchors(left, right, top, bottom)

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

Boolean 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.
Returns
Boolean true if successful.

SetMaskAnchorsX(left, right)

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

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

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

SetMaskAnchorsY(top, bottom)

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

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

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

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.

SetUnitMeasures(measureX, measureY)

Set the view's unit measures for width and height. If a camera attached to this view is defining its view volume via its unit size parameters for either X or Y direction or both (not via its FOV parameters), the respective unit measures defined here are taken into account for calculating the camera's projection matrix. By default, the view's unit measures in both dimensions are set to IEnums::LENGTH_MEASURE_PIXELS. Note that if the view is rendering to a frame buffer, this is the only allowed value.

Boolean SetUnitMeasures(Murl.IEnums.LengthMeasure measureX, Murl.IEnums.LengthMeasure measureY)

Parameters
measureXThe width unit measure.
measureYThe height unit measure.
Returns
Boolean true if successful.

SetUnitMeasureX(measureX)

Set the view's width unit measure. See SetUnitMeasures().

Boolean SetUnitMeasureX(Murl.IEnums.LengthMeasure measureX)

Parameters
measureXThe width unit measure.
Returns
Boolean true if successful.

SetUnitMeasureY(measureY)

Set the view's height unit measure. See SetUnitMeasures().

Boolean SetUnitMeasureY(Murl.IEnums.LengthMeasure measureY)

Parameters
measureYThe height unit measure.
Returns
Boolean true if successful.

GetUnitMeasureX()

Get the view's width unit measure.

Murl.IEnums.LengthMeasure GetUnitMeasureX()

Returns
Murl.IEnums.LengthMeasure The width unit measure.

GetUnitMeasureY()

Get the view's height unit measure.

Murl.IEnums.LengthMeasure GetUnitMeasureY()

Returns
Murl.IEnums.LengthMeasure The height unit measure.

GetUnitSizeX()

Get the view's unit width. If rendering to the system back buffer, the value returned equals the value specified in the application's IEngineConfiguration. If rendering to a frame buffer, this value is always 1.

Number GetUnitSizeX()

Returns
Number The view's unit width

GetUnitSizeY()

Get the view's unit height. If rendering to the system back buffer, the value returned equals the value specified in the application's IEngineConfiguration. If rendering to a frame buffer, this value is always 1.

Number GetUnitSizeY()

Returns
Number The view's unit height

SetFieldOfView(fovX, fovY)

Set the field of view. This method sets the view's field of view in both horizontal and vertical direction. These values act as multiplicators for any attached cameras, i.e. if the view has a FOV of 3 and the camera a FOV of 2, the resulting visible FOV will be 6. By default, both values are set to 1.

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.

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.

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.

GetFieldOfViewY()

Get the vertical field of view.

Number GetFieldOfViewY()

Returns
Number The vertical field of view.

GetPixelCenterX()

Get the horizontal pixel center offset. The value returned by this method represents a horizontal offset usually in the range from 0.0 to 1.0, which should be applied to the projection so that integer coordinate values directly map to a unique pixel in the output surface. This method returns the corresponding value from the IEngineConfiguration, which is usually set by the platform at application startup.

Number GetPixelCenterX()

Returns
Number The horizontal pixel center offset.

GetPixelCenterY()

Get the vertical pixel center offset. Analogous to GetPixelCenterX().

Number GetPixelCenterY()

Returns
Number The vertical pixel center offset.

GetDisplaySurfaceSizeX()

Get the output surface's actual width in pixels. If rendering to the system back buffer, this value reflects the current width of the output surface from the application's IAppConfiguration; this value may change when e.g. the window size is changed in a windowed application. If rendering to a frame buffer, this value reflects the frame buffer's actual width.

Integer GetDisplaySurfaceSizeX()

Returns
Integer The output surface width in pixels.

GetDisplaySurfaceSizeY()

Get the output surface's actual height in pixels. If rendering to the system back buffer, this value reflects the current height of the output surface from the application's IAppConfiguration; this value may change when e.g. the window size is changed in a windowed application. If rendering to a frame buffer, this value reflects the frame buffer's actual height.

Integer GetDisplaySurfaceSizeY()

Returns
Integer The output surface height in pixels.

GetDisplayRendererOrientation()

Get the renderer's surface orientation. If rendering to the system back buffer, this value represents the current renderer orientation in the application's IAppConfiguration. If rendering to a frame buffer, the actual value is controlled by the orientation specified in the Graph::IFrameBuffer node; see Graph::IFrameBuffer::SetRendererOrientation() for details.

Murl.IEnums.Orientation GetDisplayRendererOrientation()

Returns
Murl.IEnums.Orientation The current renderer orientation.

GetScreenOrientation()

Get the current screen orientation.

Murl.IEnums.ScreenOrientation GetScreenOrientation()

Returns
Murl.IEnums.ScreenOrientation The current screen orientation.

HasDisplaySurfaceChanged()

Check if the output surface changed since the most recent frame.

Boolean HasDisplaySurfaceChanged()

Returns
Boolean true if the output surface dimensions have changed.

GetNumberOfStages()

Get the view's number of stages.

Integer GetNumberOfStages()

Returns
Integer The number of stages.