Buffers

Context.buffer(data=None, reserve=0, dynamic=False) → Buffer

Create a Buffer.

Parameters:

data (bytes) – Content of the new buffer.

Keyword Arguments:
 
  • reserve (int) – The number of bytes to reserve.
  • dynamic (bool) – Treat buffer as dynamic.
Returns:

buffer

Return type:

Buffer

class Buffer

Buffer objects are OpenGL objects that store an array of unformatted memory allocated by the OpenGL context, (data allocated on the GPU). These can be used to store vertex data, pixel data retrieved from images or the framebuffer, and a variety of other things.

A Buffer object cannot be instantiated directly, it requires a context. Use Context.buffer() to create one.

Copy buffer content using Context.copy_buffer().

access(size=-1, offset=0, readonly=False) → BufferAccess

Create a BufferAccess object.

Keyword Arguments:
 
  • size (int) – The size. Value -1 means all.
  • offset (int) – The offset.
  • readonly (bool) – The readonly.

Examples

Simple with statement:

# The buffer will be mapped once and accessed multiple times.

>>> with buffer.access() as access:
...     access.read(...)
...     access.write(...)
read(size=-1, offset=0) → bytes

Read the content.

Parameters:size (int) – The size. Value -1 means all.
Keyword Arguments:
 offset (int) – The offset.
Returns:The content of the buffer.
Return type:bytes
read_into(buffer, size=-1, offset=0)

Read the content into a buffer.

Parameters:
  • buffer (bytarray) – The buffer that will receive the content.
  • size (int) – The size. Value -1 means all.
Keyword Arguments:
 

offset (int) – The offset.

Returns:

The content of the buffer.

Return type:

bytes

write(data, offset=0)

Write the content.

Parameters:data (bytes) – The data.
Keyword Arguments:
 offset (int) – The offset.
orphan()

Orphan the buffer.

It is also called buffer re-specification.

Reallocate the buffer object before you start modifying it.

Since allocating storage is likely faster than the implicit synchronization, you gain significant performance advantages over synchronization.

The old storage will still be used by the OpenGL commands that have been sent previously. It is likely that the GL driver will not be doing any allocation at all, but will just be pulling an old free block off the unused buffer queue and use it, so it is likely to be very efficient.

Examples

Simple orphaning example:

# For simplicity the VertexArray creation is omitted

>>> vbo = ctx.buffer(reserve=1024)

# Fill the buffer

>>> vbo.write(some_temorary_data)

# Issue a render call that uses the vbo

>>> vao.render(...)

# Orphan the buffer

>>> vbo.orphan()

# Issue another render call without waiting for the previous one

>>> vbo.write(some_temorary_data)
>>> vao.render(...)
bind_to_uniform_block(binding=0)

Bind the buffer to a uniform block.

Parameters:binding (int) – The uniform block binding.
bind_to_storage_buffer(binding=0)

Bind the buffer to a shader storage buffer.

Parameters:binding (int) – The shader storage binding.
class BufferAccess

BufferAccess objects are designed to access a Buffer object’s content inside a with statement. The buffer is mapped and unmapped only once.

Use Buffer.access() to get a BufferAccess object.

open()

Map the buffer. This method is called by __enter__.

close()

Unmap the buffer. This method is called by __exit__.

read(size=-1, offset=0) → bytes

Read the content.

Parameters:size (int) – The size. Value -1 means all.
Keyword Arguments:
 offset (int) – The offset.
Returns:binary data
Return type:bytes
read_into(buffer, size=-1, offset=0)

Read the content.

Parameters:
  • buffer (bytarray) – The buffer that will receive the content.
  • size (int) – The size. Value -1 means all.
Keyword Arguments:
 

offset (int) – The offset.

Returns:

binary data

Return type:

bytes

write(data, offset=0)

Write the content.

Parameters:size (int) – The data.
Keyword Arguments:
 offset (int) – The offset.