# 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

  `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.

  `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, geom=None, update_variables=True)

    Set the vertex and fragment shaders.

    Parameters:

    vert : str

    > Source code for vertex shader.

    frag : str

    > Source code for fragment shaders.

    geom : str (optional)

    > Source code for geometry shader.

    update_variables : bool

    > If True, then process any pending variables immediately after setting shader code. Default is True.

  `shaders`

    All currently attached shaders

  `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.

  `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.

  `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)

class `vispy.gloo.``IndexBuffer`(data=None)

  Buffer for index data

  Parameters:

  data : ndarray | None

  > Buffer data.

## 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.

  `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 implicitly 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.

  `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.

  `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), dtype=<class 'numpy.float32'>)

  Group multiple small data regions into a larger texture.

  The algorithm is based on the article by Jukka Jylä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 Jylänki at: http://clb.demon.fi/files/RectangleBinPack/.

  Parameters:

  shape : tuple of int

  > Texture shape (optional).

  dtype : numpy.dtype object

  > Texture starting data type (default: float32)

  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)

  `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).

## Classes related to FBO’s

class `vispy.gloo.``RenderBuffer`(shape=None, format=None, resizeable=True)

  Base class for render buffer object

  A render buffer can be in color, depth or stencil format. If this format is not specified, it is set when attached to the FrameBuffer.

  Parameters:

  shape : tuple

  > The shape of the render buffer.

  format : {None, ‘color’, ‘depth’, ‘stencil’}

  > The format of the render buffer. See resize.

  resizeable : bool

  > Indicates whether texture can be resized

  `format`

    RenderBuffer format

  `resize`(shape, format=None)

    Set the render-buffer size and format

    Parameters:

    shape : tuple of integers

    > New shape in yx order. A render buffer is always 2D. For symmetry with the texture class, a 3-element tuple can also be given, in which case the last dimension is ignored.

    format : {None, ‘color’, ‘depth’, ‘stencil’}

    > The buffer format. If None, the current format is maintained. If that is also None, the format will be set upon attaching it to a framebuffer. One can also specify the explicit enum: GL_RGB565, GL_RGBA4, GL_RGB5_A1, GL_DEPTH_COMPONENT16, or GL_STENCIL_INDEX8

  `shape`

    RenderBuffer shape

class `vispy.gloo.``FrameBuffer`(color=None, depth=None, stencil=None)

  Frame buffer object

  Parameters:

  color : RenderBuffer (optional)

  > The color buffer to attach to this frame buffer

  depth : RenderBuffer (optional)

  > The depth buffer to attach to this frame buffer

  stencil : RenderBuffer (optional)

  > The stencil buffer to attach to this frame buffer

  `activate`()

    Activate/use this frame buffer.

  `color_buffer`

    Color buffer attachment

  `deactivate`()

    Stop using this frame buffer, the previous framebuffer will be made active.

  `depth_buffer`

    Depth buffer attachment

  `read`(mode='color', alpha=True, crop=None)

    Return array of pixel values in an attached buffer

    Parameters:

    mode : str

    > The buffer type to read. May be ‘color’, ‘depth’, or ‘stencil’.

    alpha : bool

    > If True, returns RGBA array. Otherwise, returns RGB.

    crop : array-like

    > If not None, specifies pixels to read from buffer. Format is (x, y, w, h).

    Returns:

    buffer : array

    > 3D array of pixels in np.uint8 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 if crop was not specified. If crop was given, the result will match the offset and dimensions of the crop.

  `resize`(shape)

    Resize all attached buffers with the given shape

    Parameters:

    shape : tuple of two integers

    > New buffer shape (h, w), to be applied to all currently attached buffers. For buffers that are a texture, the number of color channels is preserved.

  `shape`

    The shape of the Texture/RenderBuffer attached to this FrameBuffer

  `stencil_buffer`

    Stencil buffer attachment

## State methods

`vispy.gloo.wrappers.``read_pixels`(viewport=None, alpha=True, mode='color', 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). This only effects the color mode.

  mode : str

  > Type of buffer data to read. Can be one of ‘colors’, ‘depth’, or ‘stencil’. See returns for more information.

  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) for colors mode, with the top-left corner of the framebuffer at index [0, 0] in the returned array. If ‘mode’ is depth or stencil then the last dimension is 1.

`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.

class `vispy.gloo.wrappers.``GlooFunctions`
  `glir`

    The GLIR queue corresponding to the current canvas

## 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.

  `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.

  `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).

  `set_viewport`(*args)

    Set the OpenGL viewport

    This is a wrapper for gl.glViewport.

    Parameters:

    *args : tuple

    > X and Y coordinates, plus width and height. Can be passed in as individual components, or as a single tuple with four values.

  `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.

  `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.

> vispy.gloo.gl docs