fsleyes.gl.textures.rendertexture

This module provides the RenderTexture and GLObjectRenderTexture classes, which are Texture2D sub-classes intended to be used as targets for off-screen rendering.

These classes are used by the SliceCanvas and LightBoxCanvas classes for off-screen rendering, and in various other situations throughout FSLeyes. See also the RenderTextureStack, which uses RenderTexture instances.

class fsleyes.gl.textures.rendertexture.RenderTexture(name, rttype='cds', **kwargs)

Bases: fsleyes.gl.textures.texture2d.Texture2D

The RenderTexture class is a 2D RGBA texture which manages a frame buffer, and a render buffer or a DepthTexture which is used as the depth attachment.

A RenderTexture is intended to be used as a target for off-screen rendering. Using a RenderTexture (tex in the example below) as the rendering target is easy:

# Set the texture size in pixels
tex.shape = 1024, 768

# Bind the texture/frame buffer, and configure
# the viewport for orthoghraphic display.
lo = (0.0, 0.0, 0.0)
hi = (1.0, 1.0, 1.0)

with tex.target(0, 1, lo, hi):
    # ...
    # draw the scene
    # ...

The contents of the RenderTexture can later be drawn to the screen via the Texture2D.draw() or Texture2D.drawOnBounds() methods.

A RenderTexture can be configured in one of three ways:

1. Using a RGBA8 Texture2D (the RenderTexture itself) as the colour attachment, and no depth or stencil attachments.

2. As above for the colour attachment, and a DepthTexture as the depth attachment.

3. As above for the colour attachment, and a DEPTH24_STENCIL8 renderbuffer as the combined depth+stencil attachment.

These are the only available options due to limitations in different GL implementations. You can choose which option you wish to use via the rttype argument to __init__.

If you choose option #2, a DepthTexture instance will be used as the depth attachment. The resulting depth values created after drawing to the RenderTexture may be used in subsequent processing. You can either access the depth texture directly via the depthTexture() method, or you can draw the contents of the RenderTexture, with depth information, by passing the useDepth flag to either the draw() or drawOnBounds() methods.

__init__(name, rttype='cds', **kwargs)

Create a RenderTexture. All keyword arguments are passed through to the Texture2D.__init__() method.

Parameters

• name – Unique name for this texture

• rttype –

  RenderTexture configuration. If provided, must be passed as a keyword argument. Valid values are:

  • 'c': Only a colour attachment is configured

  • 'cd': Colour and depth attachments are

    configured

  • 'cds'Colour, depth, and stencil attachments

    are configured. This is the default.

Note

A rendering target must have been set for the GL context before a frame buffer can be created … in other words, call context.SetCurrent before creating a RenderTexture.

__initShader()

Called by __init__() if this RenderTexture was configured to use a colour and depth texture. Compiles vertex/fragment shader programs which pass the colour and depth values through.

These shaders are used if the draw() or Texture2D.drawOnBounds() methods are used with the useDepth=True argument.

destroy()

Must be called when this RenderTexture is no longer needed. Destroys the frame buffer and render buffer, and calls Texture2D.destroy().

property data

Returns the data that has been passed to the set() method.

property depthTexture

Returns the DepthTexture instance used as the depth buffer. Returns None if this RenderTexture was not configured with 'cd' (see __init__()).

property shape

Return a tuple containing the texture data shape.

renderViewport(xax, yax, lo, hi)

Context manager which sets and restores the viewport via setRenderViewport() and restoreViewport().

setRenderViewport(xax, yax, lo, hi)

Configures the GL viewport for a 2D orthographic display. See the routines.show2D() function.

The existing viewport settings are cached, and can be restored via the restoreViewport() method.

Parameters

• xax – The display coordinate system axis which corresponds to the horizontal screen axis.

• yax – The display coordinate system axis which corresponds to the vertical screen axis.

• lo – A tuple containing the minimum (x, y, z) display coordinates.

• hi – A tuple containing the maximum (x, y, z) display coordinates.

restoreViewport()

Restores the GL viewport settings which were saved via a prior call to setRenderViewport().

target(*args, **kwargs)

Context manager which binds and unbinds this RenderTexture as the render target, via bindAsRenderTarget() and unbindAsRenderTarget().

If any arguments are provided, the viewport is also set and restored via setRenderViewport() and restoreViewport().

bindAsRenderTarget()

Configures the frame buffer and render buffer of this RenderTexture as the targets for rendering.

The existing farme buffer and render buffer are cached, and can be restored via the unbindAsRenderTarget() method.

unbindAsRenderTarget()

Restores the frame buffer and render buffer which were saved via a prior call to bindAsRenderTarget().

doRefresh()

Overrides Texture2D.doRefresh(). Calls the base-class implementation, and ensures that the frame buffer and render buffer of this RenderTexture are configured correctly.

draw(*args, **kwargs)

Overrides Texture2D.draw(). Calls that method, optionally using the information in the depth texture.

Parameters

useDepth – Must be passed as a keyword argument. Defaults to False. If True, and this RenderTexture was configured to use a depth texture, the texture is rendered with depth information using a fragment program

A RuntimeError will be raised if useDepth is True, but this RenderTexture was not configured appropriately (the 'cd' setting in __init__()).

__module__ = 'fsleyes.gl.textures.rendertexture'

class fsleyes.gl.textures.rendertexture.GLObjectRenderTexture(name, globj, xax, yax, maxResolution=2048)

Bases: fsleyes.gl.textures.rendertexture.RenderTexture

The GLObjectRenderTexture is a RenderTexture intended to be used for rendering GLObject instances off-screen.

The advantage of using a GLObjectRenderTexture over a RenderTexture is that a GLObjectRenderTexture will automatically adjust its size to suit the resolution of the GLObject - see the GLObject.getDataResolution() method.

In order to accomplish this, the setAxes() method must be called whenever the display orientation changes, so that the render texture size can be re-calculated.

__init__(name, globj, xax, yax, maxResolution=2048)

Create a GLObjectRenderTexture.

Parameters

• name – A unique name for this GLObjectRenderTexture.

• globj – The GLObject instance which is to be rendered.

• xax – Index of the display coordinate system axis to be used as the horizontal render texture axis.

• yax – Index of the display coordinate system axis to be used as the vertical render texture axis.

• maxResolution – Maximum resolution in pixels, along either the horizontal or vertical axis, for this GLObjectRenderTexture.

destroy()

Must be called when this GLObjectRenderTexture is no longer needed. Removes the update listener from the GLObject, and calls RenderTexture.destroy().

__module__ = 'fsleyes.gl.textures.rendertexture'

setAxes(xax, yax)

This method must be called when the display orientation of the GLObject changes. It updates the size of this GLObjectRenderTexture so that the resolution and aspect ratio of the GLOBject are maintained.

property shape

Return a tuple containing the texture data shape.

__updateShape(*a)

Updates the size of this GLObjectRenderTexture, basing it on the resolution returned by the GLObject.getDataResolution() method. If that method returns None, a default resolution is used.