Buffer

class moderngl.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().

Create

Context.buffer(data: Optional[Any] = None, *, reserve: int = 0, dynamic: bool = False) Buffer

Create a Buffer object.

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 object

Methods

Buffer.assign(index: int) Tuple[Buffer, int]

Helper method for assigning a buffer.

Returns

(self, index) tuple

Buffer.bind(*attribs, layout=None)

Helper method for binding a buffer.

Returns

(self, layout, attribs) tuple

Buffer.write(data: Any, *, offset: int = 0) None

Write the content.

Parameters

data (bytes) – The data.

Keyword Arguments

offset (int) – The offset in bytes.

Buffer.write_chunks(data: Any, start: int, step: int, count: int) None

Split data to count equal parts.

Write the chunks using offsets calculated from start, step and stop.

Parameters
  • data (bytes) – The data.

  • start (int) – First offset in bytes.

  • step (int) – Offset increment in bytes.

  • count (int) – The number of offsets.

Buffer.read(size: int = -1, *, offset: int = 0) bytes

Read the content.

Parameters

size (int) – The size in bytes. Value -1 means all.

Keyword Arguments

offset (int) – The offset in bytes.

Returns

bytes

Buffer.read_into(buffer: Any, size: int = -1, *, offset: int = 0, write_offset: int = 0) None

Read the content into a buffer.

Parameters
  • buffer (bytearray) – The buffer that will receive the content.

  • size (int) – The size in bytes. Value -1 means all.

Keyword Arguments
  • offset (int) – The read offset in bytes.

  • write_offset (int) – The write offset in bytes.

Buffer.read_chunks(chunk_size: int, start: int, step: int, count: int) bytes

Read the content.

Read and concatenate the chunks of size chunk_size using offsets calculated from start, step and stop.

Parameters
  • chunk_size (int) – The chunk size in bytes.

  • start (int) – First offset in bytes.

  • step (int) – Offset increment in bytes.

  • count (int) – The number of offsets.

Returns

bytes

Buffer.read_chunks_into(buffer: Any, chunk_size: int, start: int, step: int, count: int, *, write_offset: int = 0) None

Read the content.

Read and concatenate the chunks of size chunk_size using offsets calculated from start, step and stop.

Parameters
  • buffer (bytearray) – The buffer that will receive the content.

  • chunk_size (int) – The chunk size.

  • start (int) – First offset.

  • step (int) – Offset increment.

  • count (int) – The number of offsets.

Keyword Arguments

write_offset (int) – The write offset.

Buffer.clear(size: int = -1, *, offset: int = 0, chunk: Optional[Any] = None) None

Clear the content.

Parameters

size (int) – The size. Value -1 means all.

Keyword Arguments
  • offset (int) – The offset.

  • chunk (bytes) – The chunk to use repeatedly.

Buffer.bind_to_uniform_block(binding: int = 0, *, offset: int = 0, size: int = -1) None

Bind the buffer to a uniform block.

Parameters

binding (int) – The uniform block binding.

Keyword Arguments
  • offset (int) – The offset.

  • size (int) – The size. Value -1 means all.

Buffer.bind_to_storage_buffer(binding: int = 0, *, offset: int = 0, size: int = -1) None

Bind the buffer to a shader storage buffer.

Parameters

binding (int) – The shader storage binding.

Keyword Arguments
  • offset (int) – The offset.

  • size (int) – The size. Value -1 means all.

Buffer.orphan(size: int = -1) None

Orphan the buffer with the option to specify a new size.

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.

Keyword Arguments

size (int) – The new byte size if the buffer. If not supplied the buffer size will be unchanged.

Example

# For simplicity the VertexArray creation is omitted

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

# Fill the buffer

>>> vbo.write(some_temporary_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_temporary_data)
>>> vao.render(...)

# We can also resize the buffer. In this case we double the size

>> vbo.orphan(vbo.size * 2)
Buffer.release() None

Release the ModernGL object.

Attributes

Buffer.size

The size of the buffer in bytes.

Type

int

Buffer.dynamic

Is the buffer created with the dynamic flag?.

Type

bool

Buffer.glo

The internal OpenGL object.

This values is provided for debug purposes only.

Type

int

Buffer.mglo

Internal representation for debug purposes only.

Buffer.extra

Any - Attribute for storing user defined objects

Buffer.ctx

The context this object belongs to