The object oriented OpenGL API (gloo)

Object oriented interface to OpenGL.

This module implements classes for the things that are "objects" 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, activating 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)
...

# Draw 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 still a few known limitations. Most notably:

  • TextureCubeMap is not yet implemented
  • FBOs can only do 2D textures (not 3D textures or cube maps)
  • No support for compressed textures.

Base class

class vispy.gloo.GLObject

Generic GL object that represents an object on the GPU.

When a GLObject is instantiated, it is associated with the currently active Canvas, or with the next Canvas to be created if there is no current Canvas

Methods

delete() Delete the object from GPU memory.
delete()

Delete the object from GPU memory.

Note that the GPU object will also be deleted when this gloo object is about to be deleted. However, sometimes you want to explicitly delete the GPU object explicitly.

glir

The glir queue for this object.

id

The id of this GL object used to reference the GL object in GLIR. id's are unique within a process.

Program class

class vispy.gloo.Program(vert=None, frag=None, count=0)

Shader program object

A Program is an object to which shaders can be attached and linked to create the final program.

Uniforms and attributes can be set using indexing: e.g. program['a_pos'] = pos_data and program['u_color'] = (1, 0, 0).

Parameters:

vert : str

The vertex shader to be used by this program

frag : str

The fragment shader to be used by this program

count : int (optional)

The program will prepare a structured vertex buffer of count vertices. All attributes set using prog['attr'] = X will be combined into a structured vbo with interleaved elements, which is more efficient than having one vbo per attribute.

Notes

If several shaders are specified, only one can contain the main function. OpenGL ES 2.0 does not support a list of shaders.

Methods

bind(data) Bind a VertexBuffer that has structured data
delete() Delete the object from GPU memory.
draw([mode, indices, check_error]) Draw the attribute arrays in the specified mode.
set_shaders(vert, frag) Set the vertex and fragment shaders.
bind(data)

Bind a VertexBuffer that has structured data

Parameters:

data : VertexBuffer

The vertex buffer to bind. The field names of the array are mapped to attribute names in GLSL.

draw(mode='triangles', indices=None, check_error=True)

Draw the attribute arrays in the specified mode.

Parameters:

mode : str | GL_ENUM

'points', 'lines', 'line_strip', 'line_loop', 'triangles', 'triangle_strip', or 'triangle_fan'.

indices : array

Array of indices to draw.

check_error: :

Check error after draw.

set_shaders(vert, frag)

Set the vertex and fragment shaders.

Parameters:

vert : str

Source code for vertex shader.

frag : str

Source code for fragment shaders.

shaders

Source code for vertex and fragment shader

variables

A list of the variables in use by the current program

The list is obtained by parsing the GLSL source code.

Returns:

variables : list

Each variable is represented as a tuple (kind, type, name), where kind is 'attribute', 'uniform', 'uniform_array', 'varying' or 'const'.

Buffer classes

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

Generic GPU buffer.

A generic buffer is an interface used to upload data to a GPU array buffer (ARRAY_BUFFER or ELEMENT_ARRAY_BUFFER). It keeps track of buffer size but does not have any CPU storage. You can consider it as write-only.

The set_data is a deferred operation: you can call it even if an OpenGL context is not available. The update function is responsible to upload pending data to GPU memory and requires an active GL context.

The Buffer class only deals with data in terms of bytes; it is not aware of data type or element size.

Parameters:

data : ndarray | None

Buffer data.

nbytes : int | None

Buffer byte size.

Methods

delete
resize_bytes
set_data
set_subdata
nbytes

Buffer size in bytes

resize_bytes(size)

Resize this buffer (deferred operation).

Parameters:

size : int

New buffer size in bytes.

set_data(data, copy=False)

Set data in the buffer (deferred operation).

This completely resets the size and contents of the buffer.

Parameters:

data : ndarray

Data to be uploaded

copy: bool :

Since the operation is deferred, data may change before data is actually uploaded to GPU memory. Asking explicitly for a copy will prevent this behavior.

set_subdata(data, offset=0, copy=False)

Set a sub-region of the buffer (deferred operation).

Parameters:

data : ndarray

Data to be uploaded

offset: int :

Offset in buffer where to start copying data (in bytes)

copy: bool :

Since the operation is deferred, data may change before data is actually uploaded to GPU memory. Asking explicitly for a copy will prevent this behavior.

class vispy.gloo.buffer.DataBuffer(data=None)

GPU data buffer that is aware of data type and elements size

Parameters:

data : ndarray | None

Buffer data.

Methods

delete
resize_bytes
set_data
set_subdata
dtype

Buffer dtype

glsl_type

GLSL declaration strings required for a variable to hold this data.

itemsize

The total number of bytes required to store the array data

offset

Buffer offset (in bytes) relative to base

resize_bytes(size)

Resize the buffer (in-place, deferred operation)

Parameters:

size : integer

New buffer size in bytes

Notes

This clears any pending operations.

set_data(data, copy=False, **kwargs)

Set data (deferred operation)

Parameters:

data : ndarray

Data to be uploaded

copy: bool :

Since the operation is deferred, data may change before data is actually uploaded to GPU memory. Asking explicitly for a copy will prevent this behavior.

**kwargs : dict

Additional arguments.

set_subdata(data, offset=0, copy=False, **kwargs)

Set a sub-region of the buffer (deferred operation).

Parameters:

data : ndarray

Data to be uploaded

offset: int :

Offset in buffer where to start copying data (in bytes)

copy: bool :

Since the operation is deferred, data may change before data is actually uploaded to GPU memory. Asking explicitly for a copy will prevent this behavior.

**kwargs : dict

Additional keyword arguments.

size

Number of elements in the buffer

stride

Stride of data in memory

class vispy.gloo.VertexBuffer(data=None)

Buffer for vertex attribute data

Parameters:

data : ndarray

Buffer data (optional)

Methods

delete() Delete the object from GPU memory.
resize_bytes(size) Resize the buffer (in-place, deferred operation)
set_data(data[, copy]) Set data (deferred operation)
set_subdata(data[, offset, copy]) Set a sub-region of the buffer (deferred operation).
class vispy.gloo.IndexBuffer(data=None)

Buffer for index data

Parameters:

data : ndarray | None

Buffer data.

Methods

delete() Delete the object from GPU memory.
resize_bytes(size) Resize the buffer (in-place, deferred operation)
set_data(data[, copy]) Set data (deferred operation)
set_subdata(data[, offset, copy]) Set a sub-region of the buffer (deferred operation).

Texture classes

class vispy.gloo.texture.BaseTexture(data=None, format=None, resizable=True, interpolation=None, wrapping=None, shape=None, internalformat=None, resizeable=None)

A Texture is used to represent a topological set of scalar values.

Parameters:

data : ndarray | tuple | None

Texture data in the form of a numpy array (or something that can be turned into one). A tuple with the shape of the texture can also be given.

format : str | enum | None

The format of the texture: 'luminance', 'alpha', 'luminance_alpha', 'rgb', or 'rgba'. If not given the format is chosen automatically based on the number of channels. When the data has one channel, 'luminance' is assumed.

resizable : bool

Indicates whether texture can be resized. Default True.

interpolation : str | None

Interpolation mode, must be one of: 'nearest', 'linear'. Default 'nearest'.

wrapping : str | None

Wrapping mode, must be one of: 'repeat', 'clamp_to_edge', 'mirrored_repeat'. Default 'clamp_to_edge'.

shape : tuple | None

Optional. A tuple with the shape of the texture. If data is also a tuple, it will override the value of shape.

internalformat : str | None

Internal format to use.

resizeable : None

Deprecated version of resizable.

Methods

delete
resize
set_data
format

The texture format (color channels).

interpolation

Texture interpolation for minification and magnification.

resize(shape, format=None, internalformat=None)

Set the texture size and format

Parameters:

shape : tuple of integers

New texture shape in zyx order. Optionally, an extra dimention may be specified to indicate the number of color channels.

format : str | enum | None

The format of the texture: 'luminance', 'alpha', 'luminance_alpha', 'rgb', or 'rgba'. If not given the format is chosen automatically based on the number of channels. When the data has one channel, 'luminance' is assumed.

internalformat : str | enum | None

The internal (storage) format of the texture: 'luminance', 'alpha', 'r8', 'r16', 'r16f', 'r32f'; 'luminance_alpha', 'rg8', 'rg16', 'rg16f', 'rg32f'; 'rgb', 'rgb8', 'rgb16', 'rgb16f', 'rgb32f'; 'rgba', 'rgba8', 'rgba16', 'rgba16f', 'rgba32f'. If None, the internalformat is chosen automatically based on the number of channels. This is a hint which may be ignored by the OpenGL implementation.

set_data(data, offset=None, copy=False)

Set texture data

Parameters:

data : ndarray

Data to be uploaded

offset: int | tuple of ints :

Offset in texture where to start copying data

copy: bool :

Since the operation is deferred, data may change before data is actually uploaded to GPU memory. Asking explicitly for a copy will prevent this behavior.

Notes

This operation implicitely resizes the texture to the shape of the data if given offset is None.

shape

Data shape (last dimension indicates number of color channels)

wrapping

Texture wrapping mode

class vispy.gloo.Texture2D(data=None, format=None, resizable=True, interpolation=None, wrapping=None, shape=None, internalformat=None, resizeable=None)

Two dimensional texture

Parameters:

data : ndarray

Texture data shaped as W, or a tuple with the shape for the texture (W).

format : str | enum | None

The format of the texture: 'luminance', 'alpha', 'luminance_alpha', 'rgb', or 'rgba'. If not given the format is chosen automatically based on the number of channels. When the data has one channel, 'luminance' is assumed.

resizable : bool

Indicates whether texture can be resized. Default True.

interpolation : str

Interpolation mode, must be one of: 'nearest', 'linear'. Default 'nearest'.

wrapping : str

Wrapping mode, must be one of: 'repeat', 'clamp_to_edge', 'mirrored_repeat'. Default 'clamp_to_edge'.

shape : tuple

Optional. A tuple with the shape HxW. If data is also a tuple, it will override the value of shape.

internalformat : str | None

Internal format to use.

resizeable : None

Deprecated version of resizable.

Methods

delete() Delete the object from GPU memory.
resize(shape[, format, internalformat]) Set the texture size and format
set_data(data[, offset, copy]) Set texture data
glsl_sample

GLSL function that samples the texture.

glsl_sampler_type

GLSL type of the sampler.

glsl_type

GLSL declaration strings required for a variable to hold this data.

height

Texture height

width

Texture width

class vispy.gloo.Texture3D(data=None, format=None, resizable=True, interpolation=None, wrapping=None, shape=None, internalformat=None, resizeable=None)

Three dimensional texture

Parameters:

data : ndarray | tuple | None

Texture data in the form of a numpy array (or something that can be turned into one). A tuple with the shape of the texture can also be given.

format : str | enum | None

The format of the texture: 'luminance', 'alpha', 'luminance_alpha', 'rgb', or 'rgba'. If not given the format is chosen automatically based on the number of channels. When the data has one channel, 'luminance' is assumed.

resizable : bool

Indicates whether texture can be resized. Default True.

interpolation : str | None

Interpolation mode, must be one of: 'nearest', 'linear'. Default 'nearest'.

wrapping : str | None

Wrapping mode, must be one of: 'repeat', 'clamp_to_edge', 'mirrored_repeat'. Default 'clamp_to_edge'.

shape : tuple | None

Optional. A tuple with the shape of the texture. If data is also a tuple, it will override the value of shape.

internalformat : str | None

Internal format to use.

resizeable : None

Deprecated version of resizable.

Methods

delete() Delete the object from GPU memory.
resize(shape[, format, internalformat]) Set the texture size and format
set_data(data[, offset, copy]) Set texture data
depth

Texture depth

glsl_sample

GLSL function that samples the texture.

glsl_sampler_type

GLSL type of the sampler.

glsl_type

GLSL declaration strings required for a variable to hold this data.

height

Texture height

width

Texture width

class vispy.gloo.TextureAtlas(shape=(1024, 1024))

Group multiple small data regions into a larger texture.

The algorithm is based on the article by Jukka Jylänki : "A Thousand Ways to Pack the Bin - A Practical Approach to Two-Dimensional Rectangle Bin Packing", February 27, 2010. More precisely, this is an implementation of the Skyline Bottom-Left algorithm based on C++ sources provided by Jukka Jylänki at: http://clb.demon.fi/files/RectangleBinPack/.

Parameters:

shape : tuple of int

Texture shape (optional).

Notes

This creates a 2D texture that holds 1D float32 data. An example of simple access:

>>> atlas = TextureAtlas()
>>> bounds = atlas.get_free_region(20, 30)
>>> atlas.set_region(bounds, np.random.rand(20, 30).T)

Methods

delete() Delete the object from GPU memory.
get_free_region(width, height) Get a free region of given size and allocate it
resize(shape[, format, internalformat]) Set the texture size and format
set_data(data[, offset, copy]) Set texture data
get_free_region(width, height)

Get a free region of given size and allocate it

Parameters:

width : int

Width of region to allocate

height : int

Height of region to allocate

Returns:

bounds : tuple | None

A newly allocated region as (x, y, w, h) or None (if failed).

State methods

vispy.gloo.wrappers.read_pixels(viewport=None, alpha=True, out_type='unsigned_byte')

Read pixels from the currently selected buffer.

Under most circumstances, this function reads from the front buffer. Unlike all other functions in vispy.gloo, this function directly executes an OpenGL command.

Parameters:

viewport : array-like | None

4-element list of x, y, w, h parameters. If None (default), the current GL viewport will be queried and used.

alpha : bool

If True (default), the returned array has 4 elements (RGBA). If False, it has 3 (RGB).

out_type : str | dtype

Can be 'unsigned_byte' or 'float'. Note that this does not use casting, but instead determines how values are read from the current buffer. Can also be numpy dtypes np.uint8, np.ubyte, or np.float32.

Returns:

pixels : array

3D array of pixels in np.uint8 or np.float32 format. The array shape is (h, w, 3) or (h, w, 4), with the top-left corner of the framebuffer at index [0, 0] in the returned array.

vispy.gloo.wrappers.get_gl_configuration()

Read the current gl configuration

This function uses constants that are not in the OpenGL ES 2.1 namespace, so only use this on desktop systems.

Returns:

config : dict

The currently active OpenGL configuration.

The OpenGL context

Functionality to deal with GL Contexts in vispy. This module is defined in gloo, because gloo (and the layers that depend on it) need to be context aware. The vispy.app module "provides" a context, and therefore depends on this module. Although the GLContext class is aimed for use by vispy.app (for practical reasons), it should be possible to use GLContext without using vispy.app by overloading it in an appropriate manner.

An GLContext object acts as a placeholder on which different parts of vispy (or other systems) can keep track of information related to an OpenGL context.

class vispy.gloo.context.FakeCanvas

Fake canvas to allow using gloo without vispy.app

Instantiate this class to collect GLIR commands from gloo interactions. Call flush() in your draw event handler to execute the commands in the active contect.

Methods

flush() Flush commands.
flush()

Flush commands. Call this after setting to context to current.

class vispy.gloo.context.GLContext(config=None, shared=None)

An object encapsulating data necessary for a OpenGL context

Parameters:

config : dict | None

The requested configuration.

shared : instance of GLContext | None

The shared context.

Methods

clear([color, depth, stencil]) Clear the screen buffers
create_shared(name, ref) For the app backends to create the GLShared object.
finish() Wait for GL commands to to finish
flush() Flush GL commands
flush_commands([event]) Flush
get_state_presets() The available GL state presets
set_blend_color(color) Set the blend color
set_blend_equation(mode_rgb[, mode_alpha]) Specify the equation for RGB and alpha blending
set_blend_func([srgb, drgb, salpha, dalpha]) Specify pixel arithmetic for RGB and alpha
set_clear_color([color, alpha]) Set the screen clear color
set_clear_depth([depth]) Set the clear value for the depth buffer
set_clear_stencil([index]) Set the clear value for the stencil buffer
set_color_mask(red, green, blue, alpha) Toggle writing of frame buffer color components
set_cull_face([mode]) Set front, back, or both faces to be culled
set_depth_func([func]) Specify the value used for depth buffer comparisons
set_depth_mask(flag) Toggle writing into the depth buffer
set_depth_range([near, far]) Set depth values
set_front_face([mode]) Set which faces are front-facing
set_hint(target, mode) Set OpenGL drawing hint
set_line_width([width]) Set line width
set_polygon_offset([factor, units]) Set the scale and units used to calculate depth values
set_sample_coverage([value, invert]) Specify multisample coverage parameters
set_scissor(x, y, w, h) Define the scissor box
set_state([preset]) Set OpenGL rendering state, optionally using a preset
set_stencil_func([func, ref, mask, face]) Set front or back function and reference value
set_stencil_mask([mask, face]) Control the front or back writing of individual bits in the stencil
set_stencil_op([sfail, dpfail, dppass, face]) Set front or back stencil test actions
set_viewport(*args) Set the OpenGL viewport
capabilities

The OpenGL capabilities

config

A dictionary describing the configuration of this GL context.

create_shared(name, ref)

For the app backends to create the GLShared object.

Parameters:

name : str

The name.

ref : object

The reference.

flush_commands(event=None)

Flush

Parameters:

event : instance of Event

The event.

glir

The glir queue for the context. This queue is for objects that can be shared accross canvases (if they share a contex).

shared

Get the object that represents the namespace that can potentially be shared between multiple contexts.

class vispy.gloo.context.GLShared

Representation of a "namespace" that can be shared between different contexts. App backends can associate themselves with this object via add_ref().

This object can be used to establish whether two contexts/canvases share objects, and can be used as a placeholder to store shared information, such as glyph atlasses.

Methods

add_ref(name, ref) Add a reference for the backend object that gives access to the low level context.
add_ref(name, ref)

Add a reference for the backend object that gives access to the low level context. Used in vispy.app.canvas.backends. The given name must match with that of previously added references.

name

The name of the canvas backend that this shared namespace is associated with. Can be None.

parser

The GLIR parser (shared between contexts)

ref

A reference (stored internally via a weakref) to an object that the backend system can use to obtain the low-level information of the "reference context". In Vispy this will typically be the CanvasBackend object.

vispy.gloo.context.forget_canvas(canvas)

Forget about the given canvas. Used by the canvas when closed.

vispy.gloo.context.get_current_canvas()

Get the currently active canvas

Returns None if there is no canvas available. A canvas is made active on initialization and before the draw event is emitted.

When a gloo object is created, it is associated with the currently active Canvas, or with the next Canvas to be created if there is no current Canvas. Use Canvas.set_current() to manually activate a canvas.

vispy.gloo.context.get_default_config()

Get the default OpenGL context configuration

Returns:

config : dict

Dictionary of config values.

vispy.gloo.context.set_current_canvas(canvas)

Make a canvas active. Used primarily by the canvas itself.

vispy.gloo.gl - low level GL API

Vispy also exposes a (low level) functional GL API.