The object oriented OpenGL API (gloo)

Object oriented interface to OpenGL.

This module implements classes for the things that are “objetcs” in OpenGL, such as textures, FBO’s, VBO’s and shaders. Further, some convenience classes are implemented (like the collection class?).

This set of classes provides a friendly (Pythonic) interface to OpenGL, and is designed to provide OpenGL’s full functionality.

All classes inherit from GLObject, which provide a basic interface, enabling activatinge and deleting the object. Central to each visualization is the Program. Other objects, such as Texture2D and VertexBuffer should be set as uniforms and attributes of the Program object.

Example:

# Init
program = gloo.Program(vertex_source, fragment_source)
program['a_position'] = gloo.VertexBuffer(my_positions_array)
program['s_texture'] = gloo.Texture2D(my_image)
...

# Paint event handler
program['u_color'] = 0.0, 1.0, 0.0
program.draw(gl.GL_TRIANGLES)

Note

With vispy.gloo we strive to offer a Python interface that provides the full functionality of OpenGL. However, this layer is a work in progress and there are yet a few known limitations. Most notably:

  • TextureCubeMap is not yet implemented
  • FBO’s can only do 2D textures (not 3D textures or cube maps)
  • Sharing of Shaders and RenderBuffers (between multiple Program’s and FrameBuffers, respecitively) is not well supported.
  • No support for compressed textures.

Base class

class vispy.gloo.GLObject

Base class for classes that wrap an OpenGL object. All GLObject’s can be used as a context manager to enable them, although some are better used by setting them as a uniform or attribute of a Program.

All GLObject’s apply deferred (a.k.a. lazy) loading, which means that the objects can be created and data can be set even if no OpenGL context is available yet.

There are a few exceptions, most notably when enabling an object by using it as a context manager, and the delete method. In these cases, the called should ensure that the proper OpenGL context is current.

activate()

Activate the object (a GL context must be available). Note that the object can also be activated (and automatically deactivated) by using it as a context manager.

deactivate()

Deactivate the object.

delete()

Delete the object from OpenGl memory.

handle

Name of this object in GPU.

Buffer classes

class vispy.gloo.VertexBuffer(data, client=False)

The VertexBuffer represents any kind of vertex data, and can also represent an array-of-structures approach. Inherits buffer.DataBuffer.

The shape of the given data is interpreted in the following way: If a normal array of one dimension is given, the vector-size (vsize) is considered 1. Otherwise, data.shape[-1] is considered the vsize, and the other dimensions are “collapsed” to get the vertex count. If the data is a structured array, the number of elements in each item is used as the vector-size (vsize).

Parameters :

data : ndarray or dtype

Specify the data, or the type of the data. The dtype can also be something that evaluates to a dtype, such as a ‘uint32’ or np.uint8. If a structured array or dtype is given, and there are more than 1 elements in the structure, this buffer is a “structured” buffer. The corresponding items can be obtained by indexing this buffer using their name. In most cases one can use program.set_vars(structured_buffer) to map the item names to their GLSL attribute names automatically.

client : bool

Should be given as a keyword argument. If True, a ClientVertexBuffer is used instead, which is a lightweight wrapper class for storing vertex data in CPU memory.

class vispy.gloo.ElementBuffer(data, client=False)

The ElementBuffer allows to specify which element of a VertexBuffer are to be used in a shader program. Inherits buffer.DataBuffer.

The given data must be of unsigned integer type. The shape of the data is ignored; each element in the array is simply considered a vertex index.

Parameters :

data : ndarray or dtype

Specify the data, or the type of the data. The dtype can also be something that evaluates to a dtype, such as a ‘uint32’ or np.uint8.

client : bool

Should be given as a keyword argument. If True, a ClientElementBuffer is used instead, which is a lightweight wrapper class for storing element data in CPU memory.

class vispy.gloo.buffer.DataBuffer(target, data)

Interface to upload buffer data to the GPU. This class is based on buffer.Buffer, and adds awareness of shape, dtype and striding.

In general, you will want to use the VertexBuffer or ElementBuffer.

Parameters :

target : GLENUM

gl.GL_ARRAY_BUFFER or gl.GL_ELEMENT_ARRAY_BUFFER

data : ndarray or dtype

The data to set. See docs of VertexBuffer and ElementBuffer for details.

count

The number of vertices in the buffer.

dtype

The buffer data type.

offset

The byte offset in the buffer.

set_count(count)

Set the number of vertices for this buffer. This will allocate data and discard any pending subdata.

Parameters :

count : int

The new size of the buffer; the number of vertices.

set_data(data)

Set the data for this buffer. Any pending data is discarted. The dtype and vsize of this buffer should be respected.

Parameters :

data :: np.ndarray :

The data to upload.

set_subdata(offset, data)

Set subdata. The dtype and vsize of this buffer should be respected. And the data must fit in the current buffer.

Parameters :

offset : int

The offset (in vertex indices) to set the data for.

data : np.ndarray

The data to update.

stride

The number of bytes separating two elements.

vsize

The vector size of each vertex in the buffer. This can be 1, 2, 3 or 4, corresponding with float, vec2, vec3, vec4.

class vispy.gloo.buffer.Buffer(target, data=None)

Interface to upload buffer data to the GPU. This class is shape and dtype agnostic and considers the arrays as byte data.

In general, you will want to use the VertexBuffer or ElementBuffer.

Parameters :

target : GLENUM

gl.GL_ARRAY_BUFFER or gl.GL_ELEMENT_ARRAY_BUFFER

data : ndarray

The data to set. Optional.

nbytes

The buffer size (in bytes).

set_data(data)

Set the bytes data. This accepts a numpy array, but the data is not checked for dtype or shape.

Parameters :

data : ndarray

The data to set.

set_nbytes(nbytes)

Set how many bytes should be available for the buffer.

set_subdata(offset, data)

Update a region of the buffer.

Parameters :

offset : int

The offset (in bytes) at which to set the given data.

data : ndarray

The data to set.

Texture classes

class vispy.gloo.Texture2D(*args, **kwargs)

Representation of a 2D texture. Inherits texture.Texture.

class vispy.gloo.Texture3D(*args, **kwargs)

Representation of a 3D texture. Note that for this the GL_texture_3D extension needs to be available. Inherits texture.Texture.

class vispy.gloo.TextureCubeMap(*args, **kwargs)

Representation of a cube map, to store texture data for the 6 sided of a cube. Used for instance to create environment mappings. Inherits texture.Texture.

This class is not yet implemented.

class vispy.gloo.texture.Texture(target, data=None, format=None, clim=None)

Representation of an OpenGL texture.

set_data(data, level=0, format=None, clim=None)

Set the data for this texture. This method can be called at any time (even if there is no context yet).

It is relatively cheap to call this function multiple times, only the last data is set right before drawing. If the shape of the given data matches the shape of the current texture, the data is updated in a fast manner.

Parameters :

data : numpy array

The texture data to set.

level : int

The mipmap level. Default 0.

format : str

The format representation of the data. If not given or None, it is decuced from the given data. Can be RGB, RGBA, LUMINANCE, LUMINANCE_ALPHA, ALPHA. The OpenGL enum can also be given.

clim : (min, max)

Contrast limits for the data. If specified, min will end up being 0.0 (black) and max will end up as 1.0 (white). If not given or None, clim is determined automatically. For floats they become (0.0, 1.0). For integers the are mapped to the full range of the type.

set_filter(mag_filter, min_filter)

Set interpolation filters. EIther parameter can be None to not (re)set it.

Parameters :

mag_filter : str

The magnification filter (when texels are larger than screen pixels). Can be NEAREST, LINEAR. The OpenGL enum can also be given.

min_filter : str

The minification filter (when texels are smaller than screen pixels). For this filter, mipmapping can be applied to perform antialiasing (if mipmaps are available for this texture). Can be NEAREST, LINEAR, NEAREST_MIPMAP_NEAREST, NEAREST_MIPMAP_LINEAR, LINEAR_MIPMAP_NEAREST, LINEAR_MIPMAP_LINEAR. The OpenGL enum can also be given.

set_shape(shape, level=0, format=None)

Allocate storage for this texture. This is useful if the texture is used as a render target for an FBO.

A call that only uses the shape argument does not result in an action if the call would not change the shape.

Parameters :

shape : tuple

The shape of the “virtual” data. By specifying e.g. (20,20,3) for a Texture2D, one implicitly sets the format to GL_RGB. Note that shape[0] is height.

level : int

The mipmap level. Default 0.

format : str

The format representation of the data. If not given or None, it is decuced from the given data. Can be RGB, RGBA, LUMINANCE, LUMINANCE_ALPHA, ALPHA. The OpenGL enum can also be given.

set_subdata(offset, data, level=0, format=None, clim=None)

Set a region of data for this texture. This method can be called at any time (even if there is no context yet).

In contrast to set_data(), each call to this method results in an OpenGL api call.

Parameters :

offset : tuple

The offset for each dimension, to update part of the texture.

data : numpy array

The texture data to set. The data (with offset) cannot exceed the boundaries of the current texture.

level : int

The mipmap level. Default 0.

format : OpenGL enum

The format representation of the data. If not given or None, it is decuced from the given data. Can be RGB, RGBA, LUMINANCE, LUMINANCE_ALPHA, ALPHA. The OpenGL enum can also be given.

clim : (min, max)

Contrast limits for the data. If specified, min will end up being 0.0 (black) and max will end up as 1.0 (white). If not given or None, clim is determined automatically. For floats they become (0.0, 1.0). For integers the are mapped to the full range of the type.

set_wrapping(wrapx, wrapy, wrapz=None)

Set texture coordinate wrapping.

Parameters :

wrapx : str

The wrapping mode in the x-direction. Can be GL_REPEAT, GL_CLAMP_TO_EDGE, GL_MIRRORED_REPEAT. The OpenGL enum can also be given.

wrapy : str

Dito for y.

wrapz : str

Dito for z. Only makes sense for 3D textures, and requires the texture_3d extension. Optional.

vispy.gloo.gl - low level GL API

Vispy also exposes a (low level) functional GL API. At this point gloo is not yet fully independenat since it does not cover functions like glClear().