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

The IFrameBuffer graph node interface.

Normally, all geometry contained in the scene graph gets rendered to the back buffer provided by the platform, which gets presented to the user once per frame. For certain purposes however, it can be necessary not to render directly to the back buffer but to an off-screen area:

  • Post-processing effects on the rendered scene
  • Dynamic reflections
  • Statically generated 2D backgrounds etc.

A frame buffer represents a render target to such an off-screen area. To be able to access the generated contents, a frame buffer must refer to at least one Graph::ITexture, which holds the generated image after rendering to the frame buffer is complete, and serves as the pixel input for a later render stage.

Depending on which information is actually needed for such a later stage, one or more different texture attachment points can be used for a given frame buffer, e.g. the color target texture receives actual RGBA pixel color values, and a depth target texture receives pixel depth values.

Often, only color values are needed later but the rendering process requires an active depth buffer for correct display. In such a case, it is not necessary to create and attach a depth texture; instead, it is sufficient to explicitly set a depth buffer format to create a depth buffer that is only used internally.

To use a frame buffer for rendering, one or more Graph::IView nodes must refer to this frame buffer; after activating a Graph::ICamera referring to such a view, all subsequent geometry is then rendered to that frame buffer, with the given view and camera settings.

Note, that when multiple textures are attached, all of these textures must have the same dimensions, or initialization will fail.


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

GetColorTextureNodeTarget()

Get the constant Graph::ITextureNodeTarget color buffer container. This method returns a constant pointer to the node's Graph::ITextureNodeTarget container to query the referenced texture node used for storing the frame buffer's output color values.

Murl.Graph.IGenericNodeTarget.GraphITexture GetColorTextureNodeTarget()

Returns
Murl.Graph.IGenericNodeTarget.GraphITexture The constant Graph::ITextureNodeTarget color buffer container, or null if not available.

GetDepthTextureNodeTarget()

Get the constant Graph::ITextureNodeTarget depth buffer container. This method returns a constant pointer to the node's Graph::ITextureNodeTarget container to query the referenced texture node used for storing the frame buffer's output depth values.

Murl.Graph.IGenericNodeTarget.GraphITexture GetDepthTextureNodeTarget()

Returns
Murl.Graph.IGenericNodeTarget.GraphITexture The constant Graph::ITextureNodeTarget depth buffer container, or null if not available.

GetStencilTextureNodeTarget()

Get the constant Graph::ITextureNodeTarget stencil buffer container. This method returns a constant pointer to the node's Graph::ITextureNodeTarget container to query the referenced texture node used for storing the frame buffer's output stencil values.

Murl.Graph.IGenericNodeTarget.GraphITexture GetStencilTextureNodeTarget()

Returns
Murl.Graph.IGenericNodeTarget.GraphITexture The constant Graph::ITextureNodeTarget stencil buffer container, or null if not available.

SetDepthBufferFormat(format)

Explicitly set the format of the depth buffer. If no texture is specified as a target for storing depth buffer values, the explicit depth buffer format is used to create an offscreen buffer. In that case, the depth buffer is only used for rendering internally and cannot be accessed from the outside.

Boolean SetDepthBufferFormat(Murl.IEnums.DepthBufferFormat format)

Parameters
formatThe explicit depth buffer format.
Returns
Boolean true if successful.

GetDepthBufferFormat()

Get the explicit depth buffer format.

Murl.IEnums.DepthBufferFormat GetDepthBufferFormat()

Returns
Murl.IEnums.DepthBufferFormat The explicit depth buffer format.

SetStencilBufferFormat(format)

Explicitly set the format of the stencil buffer. If no texture is specified as a target for storing stencil buffer values, the explicit stencil buffer format is used to create an offscreen buffer. In that case, the stencil buffer is only used for rendering internally and cannot be accessed from the outside.

Boolean SetStencilBufferFormat(Murl.IEnums.StencilBufferFormat format)

Parameters
formatThe explicit stencil buffer format.
Returns
Boolean true if successful.

GetStencilBufferFormat()

Get the explicit stencil buffer format.

Murl.IEnums.StencilBufferFormat GetStencilBufferFormat()

Returns
Murl.IEnums.StencilBufferFormat The explicit stencil buffer format.

SetRendererOrientation(orientation)

Set the framebuffer's orientation. By default, the framebuffer has this value set to IEnums::ORIENTATION_ROTATE_0, so all views referring to this framebuffer as a render target will render their contents 'upright'. For certain cases, like post-processing in image space, it may be necessary that the framebuffer receives its contents in the same orientation as the back buffer. This can be achieved by calling this method with IEnums::ORIENTATION_DEFAULT.

Boolean SetRendererOrientation(Murl.IEnums.Orientation orientation)

Parameters
orientationOne of the four values NORMAL, ROTATE_CW, FLIP or ROTATE_CCW to define a fixed framebuffer orientation, or DEFAULT to select the main back buffer's orientation.
Returns
Boolean true if successful.

GetRendererOrientation()

Get the framebuffer's orientation.

Murl.IEnums.Orientation GetRendererOrientation()

Returns
Murl.IEnums.Orientation One of the four values NORMAL, ROTATE_CW, FLIP or ROTATE_CCW if the framebuffer has a fixed orientation, or DEFAULT if the main back buffer's orientation is used.

SetDelinearizationEnabled(enabled)

Enable/disable color de-linearization when writing to the color buffer, if available. By default, a fragment shader's color output RGB values are written to the output color buffer without any conversion. If the shader performs operations on linear color values and the target color buffer is a regular integer RGB(A) texture or render buffer, the output will be too dark, as the target color buffer expects gamma-corrected values. In this case, de-linearization should be enabled on the frame buffer, so that the usual gamma value of 2.2 is applied to the output pixels. Note, that floating point color buffers are always linear, so this has no effect.

Boolean SetDelinearizationEnabled(Boolean enabled)

Parameters
enabledIf true, color de-linearization is enabled.
Returns
Boolean true if successful.

IsDelinearizationEnabled()

Check if color de-linearization during rendering is enabled.

Boolean IsDelinearizationEnabled()

Returns
Boolean true if enabled.

SetMipMapGenerationEnabled(enabled)

Enable/disable automatic MIP map generation.

Boolean SetMipMapGenerationEnabled(Boolean enabled)

Parameters
enabledIf true, automatic MIP map generation is enabled.
Returns
Boolean true if successful.

IsMipMapGenerationEnabled()

Check if automatic MIP map generation is enabled.

Boolean IsMipMapGenerationEnabled()

Returns
Boolean true if automatic MIP map generation is enabled.

SetTargetLayer(layer)

Set the target texture layer when rendering to an array texture. By default, the output is rendered to layer 0. This value is ignored for non-array textures.

Boolean SetTargetLayer(Integer layer)

Parameters
layerThe target layer.
Returns
Boolean true if successful.

GetTargetLayer()

Get the target texture layer for rendering.

Integer GetTargetLayer()

Returns
Integer The MIP level.

SetTargetMipLevel(level)

Set the target MIP level when rendering to (a) mip-mapped texture(s). By default, the output is rendered to a texture's base level, i.e. level=0. This value is ignored if automatic MIP map generation is enabled via SetMipMapGenerationEnabled().

Boolean SetTargetMipLevel(Integer level)

Parameters
levelThe target MIP level.
Returns
Boolean true if successful.

GetTargetMipLevel()

Get the target MIP level for rendering.

Integer GetTargetMipLevel()

Returns
Integer The MIP level.

SetNumberOfSamples(numSamples)

Set the number of samples for multisample anti-aliasing. By default, the number of samples is set to 1, i.e. multisampling is disabled. A value of 0 indicates that the global number of samples is to be used, which can be configured via IEngineConfiguration::SetNumberOfAntiAliasSamples(). A value greater than 1 enables multisampling for this frame buffer, with the given number of samples clamped to the maximum allowed value indicated by the GPU.

Boolean SetNumberOfSamples(Integer numSamples)

Parameters
numSamplesThe number of samples.
Returns
Boolean true if successful.

GetNumberOfSamples()

Get the number of samples for multisample anti-aliasing.

Integer GetNumberOfSamples()

Returns
Integer The number of samples.

SetSortOrder(sortOrder)

Set the frame buffers's absolute sort order. Frame buffers are generally processed in the order in which they receive drawables during rendering. If a frame buffer depends on another frame buffer, which should be updated before it is used, it is often desired to specify an explicit order in which the frame buffers are processed globally. Setting a higher sort order results in the frame buffer always being processed after all frame buffers with a lower order have been updated. Frame buffers with the same sort order are processed in the order in which they get filled with drawables. Note: The back buffer is always processed last.

Boolean SetSortOrder(Integer sortOrder)

Parameters
sortOrderThe global order of this frame buffer.
Returns
Boolean true if successful.

GetSortOrder()

Get the frame buffers's global sort order.

Integer GetSortOrder()

Returns
Integer The global order.

GetSizeX()

Get the frame buffer width.

Integer GetSizeX()

Returns
Integer The frame buffer width in pixels (texels).

GetSizeY()

Get the frame buffer height.

Integer GetSizeY()

Returns
Integer The frame buffer height in pixels (texels).

SetInCoordSize(sizeX, sizeY)

Set the input coordinate reference size. Generally, input coordinates are represented by values ranging from -1.0 to 1.0. As a convenience, this method can be used to set an arbitrary reference size for both dimensions of the frame buffer; this way it is possible to specify integer (pixel) values instead of (quite unreadable) floats. By default, both sizeX and sizeY are set to 1.0. See also Graph::IButton::SetOutCoordSize() as the counterpart providing the actual input coordinates.

Boolean SetInCoordSize(Number sizeX, Number sizeY)

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

SetInCoordSizeX(sizeX)

Set the horizontal input coordinate reference size. See SetInCoordSize().

Boolean SetInCoordSizeX(Number sizeX)

Parameters
sizeXThe horizontal coordinate reference size.
Returns
Boolean true if successful.

SetInCoordSizeY(sizeY)

Set the vertical input coordinate reference size. See SetInCoordSize().

Boolean SetInCoordSizeY(Number sizeY)

Parameters
sizeYThe vertical coordinate reference size.
Returns
Boolean true if successful.

GetInCoordSizeX()

Get the horizontal input coordinate reference size. See SetInCoordSize().

Number GetInCoordSizeX()

Returns
Number The horizontal input coordinate reference size.

GetInCoordSizeY()

Get the vertical input coordinate reference size. See SetInCoordSize().

Number GetInCoordSizeY()

Returns
Number The vertical output coordinate reference size.

SetInCoord(x1, y1, x2, y2)

Set the frame buffer's input coordinate range. This method sets the frame buffer's start and end input coordinates.

Boolean SetInCoord(Number x1, Number y1, Number x2, Number y2)

Parameters
x1The start coordinate in X direction.
y1The start coordinate in Y direction.
x2The end coordinate in X direction.
y2The end coordinate in Y direction.
Returns
Boolean true if successful.

SetInCoord1(x1, y1)

Set the frame buffer's input coordinate start. See SetInCoord().

Boolean SetInCoord1(Number x1, Number y1)

Parameters
x1The start coordinate in X direction.
y1The start coordinate in Y direction.
Returns
Boolean true if successful.

SetInCoord2(x2, y2)

Set the frame buffer's input coordinate end. See SetInCoord().

Boolean SetInCoord2(Number x2, Number y2)

Parameters
x2The end coordinate in X direction.
y2The end coordinate in Y direction.
Returns
Boolean true if successful.

SetInCoordX1(x1)

Set the frame buffer's horizontal start input coordinate. See SetInCoord().

Boolean SetInCoordX1(Number x1)

Parameters
x1The start coordinate in X direction.
Returns
Boolean true if successful.

SetInCoordY1(y1)

Set the frame buffer's vertical start input coordinates. See SetInCoord().

Boolean SetInCoordY1(Number y1)

Parameters
y1The start coordinate in Y direction.
Returns
Boolean true if successful.

SetInCoordX2(x2)

Set the frame buffer's horizontal end input coordinate. See SetInCoord().

Boolean SetInCoordX2(Number x2)

Parameters
x2The end coordinate in X direction.
Returns
Boolean true if successful.

SetInCoordY2(y2)

Set the frame buffer's vertical end input coordinates. See SetInCoord().

Boolean SetInCoordY2(Number y2)

Parameters
y2The end coordinate in Y direction.
Returns
Boolean true if successful.

GetInCoordX1()

Get the frame buffer's horizontal start input coordinate. See SetInCoord().

Number GetInCoordX1()

Returns
Number The start coordinate in X direction.

GetInCoordY1()

Get the frame buffer's vertical start input coordinate. See SetInCoord().

Number GetInCoordY1()

Returns
Number The start coordinate in Y direction.

GetInCoordX2()

Get the frame buffer's horizontal end input coordinate. See SetInCoord().

Number GetInCoordX2()

Returns
Number The end coordinate in X direction.

GetInCoordY2()

Get the frame buffer's vertical end input coordinate. See SetInCoord().

Number GetInCoordY2()

Returns
Number The end coordinate in Y direction.

GetNumberOfStages()

Get the frame buffer's number of stages.

Integer GetNumberOfStages()

Returns
Integer The number of stages.

GetInputScreenAreaObject(stage)

Get the frame buffer's internal input screen area object.

Murl.Input.IScreenArea GetInputScreenAreaObject(Integer stage)

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