fsleyes.gl.textures.texture

This module provides the Texture and Texture2D classes, which are the base classes for all other texture types. See also the Texture3D class.

class fsleyes.gl.textures.texture.Texture(name, ndims)

Bases: object

The Texture class is the base class for all other texture types in FSLeyes. This class is not intended to be used directly - use one of the sub-classes instead. This class provides a few convenience methods for working with textures:

getTextureName Returns the name of this texture.
getTextureHandle Returns the GL texture handle for this texture.

The bindTexture() and unbindTexture() methods allow you to bind a texture object to a GL texture unit. For example, let’s say we have a texture object called tex, and we want to use it:

import OpenGL.GL as gl


# Bind the texture before doing any configuration -
# we don't need to specify a texture unit here.
tex.bindTexture()

# Use nearest neighbour interpolation
gl.glTexParameteri(gl.GL_TEXTURE_2D,
                   gl.GL_TEXTURE_MIN_FILTER,
                   gl.GL_NEAREST)
gl.glTexParameteri(gl.GL_TEXTURE_2D,
                   gl.GL_TEXTURE_MAG_FILTER,
                   gl.GL_NEAREST)

tex.unbindTexture()

# ...

# When we want to use the texture in a
# scene render, we need to bind it to
# a texture unit.
tex.bindTexture(gl.GL_TEXTURE0)

# ...
# Do the render
# ...

tex.unbindTexture()

Note

Despite what is shown in the example above, you shouldn’t need to manually configure texture objects with calls to glTexParameter - most things can be performed through methods of the Texture sub-classes, for example ImageTexture and Texture2D.

See the resources module for a method of sharing texture resources.

__init__(name, ndims)

Create a Texture.

Parameters:
  • name – The name of this texture - should be unique.
  • ndims – Number of dimensions - must be 1, 2 or 3.

Note

All subclasses must accept a name as the first parameter to their __init__ method, and must pass said name through to the __init__() method.

__del__()

Prints a log message.

destroy()

Must be called when this Texture is no longer needed. Deletes the texture handle.

getTextureName()

Returns the name of this texture. This is not the GL texture name, rather it is the unique name passed into __init__().

getTextureHandle()

Returns the GL texture handle for this texture.

isBound()

Returns True if this texture is currently bound, False otherwise.

Note

This method assumes that the bindTexture() and unbindTexture() methods are called in pairs.

bindTexture(textureUnit=None)

Activates and binds this texture.

Parameters:textureUnit – The texture unit to bind this texture to, e.g. GL_TEXTURE0.
unbindTexture()

Unbinds this texture.

__dict__ = mappingproxy({'__module__': 'fsleyes.gl.textures.texture', '__doc__': "The ``Texture`` class is the base class for all other texture types in\n *FSLeyes*. This class is not intended to be used directly - use one of the\n sub-classes instead. This class provides a few convenience methods for\n working with textures:\n\n .. autosummary::\n :nosignatures:\n\n getTextureName\n getTextureHandle\n\n\n The :meth:`bindTexture` and :meth:`unbindTexture` methods allow you to\n bind a texture object to a GL texture unit. For example, let's say we\n have a texture object called ``tex``, and we want to use it::\n\n import OpenGL.GL as gl\n\n\n # Bind the texture before doing any configuration -\n # we don't need to specify a texture unit here.\n tex.bindTexture()\n\n # Use nearest neighbour interpolation\n gl.glTexParameteri(gl.GL_TEXTURE_2D,\n gl.GL_TEXTURE_MIN_FILTER,\n gl.GL_NEAREST)\n gl.glTexParameteri(gl.GL_TEXTURE_2D,\n gl.GL_TEXTURE_MAG_FILTER,\n gl.GL_NEAREST)\n\n tex.unbindTexture()\n\n # ...\n\n # When we want to use the texture in a\n # scene render, we need to bind it to\n # a texture unit.\n tex.bindTexture(gl.GL_TEXTURE0)\n\n # ...\n # Do the render\n # ...\n\n tex.unbindTexture()\n\n\n .. note:: Despite what is shown in the example above, you shouldn't need\n to manually configure texture objects with calls to\n ``glTexParameter`` - most things can be performed through\n methods of the ``Texture`` sub-classes, for example\n :class:`.ImageTexture` and :class:`.Texture2D`.\n\n\n See the :mod:`.resources` module for a method of sharing texture\n resources.\n ", '__init__': <function Texture.__init__>, '__del__': <function Texture.__del__>, 'destroy': <function Texture.destroy>, 'getTextureName': <function Texture.getTextureName>, 'getTextureHandle': <function Texture.getTextureHandle>, 'isBound': <function Texture.isBound>, 'bindTexture': <function Texture.bindTexture>, 'unbindTexture': <function Texture.unbindTexture>, '__dict__': <attribute '__dict__' of 'Texture' objects>, '__weakref__': <attribute '__weakref__' of 'Texture' objects>})
__module__ = 'fsleyes.gl.textures.texture'
__weakref__

list of weak references to the object (if defined)

class fsleyes.gl.textures.texture.Texture2D(name, interp=<MagicMock name='mock.GL.GL_NEAREST' id='140655046643896'>, dtype=None)

Bases: fsleyes.gl.textures.texture.Texture

The Texture2D class represents a two-dimensional RGBA texture. A Texture2D instance can be used in one of two ways:

  • Setting the texture data via the setData() method, and then drawing it to a scene via draw() or drawOnBounds().
  • Setting the texture size via setSize(), and then drawing to it by some other means (see e.g. the RenderTexture class, a sub-class of Texture2D).
__init__(name, interp=<MagicMock name='mock.GL.GL_NEAREST' id='140655046643896'>, dtype=None)

Create a Texture2D instance.

Parameters:
  • name – Unique name for this Texture2D.
  • interp – Initial interpolation - GL_NEAREST (the default) or GL_LINEAR. This can be changed later on via the setInterpolation() method.
  • dtype – Sized internal GL data format to use for the texture. Currently only gl.GL_RGBA8 (the default) and gl.GL_DEPTH_COMPONENT24 are supported.
setInterpolation(interp)

Change the texture interpolation - valid values are GL_NEAREST or GL_LINEAR.

setBorder(border)

Change the border colour - set to a tuple of four values in the range 0 to 1, or None for no border (in which case the texture coordinates will be clamped to edges).

setSize(width, height)

Sets the width/height for this texture.

This method also clears the data for this texture, if it has been previously set via the setData() method.

classmethod getDataTypeParams(dtype)

Returns a tuple containing information about the given sized internal GL texture data format: - The base GL internal format - The GL external data format - The equivalent numpy data type - The number of channels

dtype

Returns the internal GL data format to use for this texture.

getSize()

Return the current (width, height) of this Texture2D.

setData(data)

Sets the data for this texture - the width and height are determined from data shape, which is assumed to be 4*width*height.

getData()

Returns the data stored in this Texture2D as a numpy.uint8 array of shape (height, width, 4).

refresh()

Configures this Texture2D. This includes setting up interpolation, and setting the texture size and data.

draw(vertices=None, xform=None, textureUnit=None)

Draw the contents of this Texture2D to a region specified by the given vertices. The texture is bound to texture unit 0.

Parameters:
  • vertices – A numpy array of shape 6 * 3 specifying the region, made up of two triangles, to which this Texture2D should be drawn. If None, it is assumed that the vertices and texture coordinates have already been configured (e.g. via a shader program).
  • xform – A transformation to be applied to the vertices. Ignored if vertices is None.
  • textureUnit – Texture unit to bind to. Defaults to gl.GL_TEXTURE0.
drawOnBounds(zpos, xmin, xmax, ymin, ymax, xax, yax, *args, **kwargs)

Draws the contents of this Texture2D to a rectangle. This is a convenience method which creates a set of vertices, and passes them to the draw() method.

Parameters:
  • zpos – Position along the Z axis, in the display coordinate system.
  • xmin – Minimum X axis coordinate.
  • xmax – Maximum X axis coordinate.
  • ymin – Minimum Y axis coordinate.
  • ymax – Maximum Y axis coordinate.
  • xax – Display space axis which maps to the horizontal screen axis.
  • yax – Display space axis which maps to the vertical screen axis.

All other arguments are passed to the draw() method.

_Texture2D__prepareCoords(vertices, xform=None)

Called by draw(). Prepares vertices, texture coordinates and indices for drawing the texture.

If vertices is None, it is assumed that the caller has already assigned vertices and texture coordinates, either via a shader, or via vertex/texture coordinate pointers. In this case,

Returns:A tuple containing the vertices, texture coordinates, and indices, or (None, None, indices) if vertices is None
_Texture2D__setSize(width, height)

Sets the width/height attributes for this texture, and saves a reference to the old width/height - see comments in the refresh method.

__module__ = 'fsleyes.gl.textures.texture'
classmethod generateVertices(zpos, xmin, xmax, ymin, ymax, xax, yax, xform=None)

Generates a set of vertices suitable for passing to the Texture2D.draw() method, for drawing a Texture2D to a 2D canvas.

Parameters:
  • zpos – Position along the Z axis, in the display coordinate system.
  • xmin – Minimum X axis coordinate.
  • xmax – Maximum X axis coordinate.
  • ymin – Minimum Y axis coordinate.
  • ymax – Maximum Y axis coordinate.
  • xax – Display space axis which maps to the horizontal screen axis.
  • yax – Display space axis which maps to the vertical screen axis.
  • xform – Transformation matrix to appply to vertices.
classmethod generateTextureCoords()

Generates a set of texture coordinates for drawing a Texture2D. This function is used by the Texture2D.draw() method.