Byte abstractions of Vertex Buffer Objects and vertex arrays.
Use create_buffer()
or create_mappable_buffer()
to create a
Vertex Buffer Object, or a vertex array if VBOs are not supported by the
current context.
Buffers can optionally be created “mappable” (incorporating the
AbstractMappable
mix-in). In this case the buffer provides a
get_region()
method which provides the most
efficient path for updating partial data within the buffer.
AbstractBuffer
¶Abstract buffer of byte data.
bind
()¶Bind this buffer to its OpenGL target.
delete
()¶Delete this buffer, reducing system resource usage.
map
(invalidate=False)¶Map the entire buffer into system memory.
The mapped region must be subsequently unmapped with unmap before performing any other operations on the buffer.
invalidate (bool) – If True, the initial contents of the mapped block need not reflect the actual contents of the buffer.
POINTER(ctypes.c_ubyte)
Pointer to the mapped block in memory
resize
(size)¶Resize the buffer to a new size.
size (int) – New size of the buffer, in bytes
set_data
(data)¶Set the entire contents of the buffer.
data (sequence of int or ctypes pointer) – The byte array to set.
set_data_region
(data, start, length)¶Set part of the buffer contents.
data (sequence of int or ctypes pointer) – The byte array of data to set
start (int) – Offset to start replacing data
length (int) – Length of region to replace
unbind
()¶Reset the buffer’s OpenGL target.
unmap
()¶Unmap a previously mapped memory block.
ptr
= 0¶size
= 0¶AbstractBufferRegion
¶A mapped region of a buffer.
Buffer regions are obtained using get_region()
.
array (ctypes array) – Array of data, of the type and count requested by
get_region()
.
invalidate
()¶Mark this region as changed.
The buffer may not be updated with the latest contents of the array until this method is called. (However, it may not be updated until the next time the buffer is used, for efficiency).
AbstractMappable
¶get_region
(start, size, ptr_type)¶Map a region of the buffer into a ctypes array of the desired type. This region does not need to be unmapped, but will become invalid if the buffer is resized.
Note that although a pointer type is required, an array is mapped. For example:
get_region(0, ctypes.sizeof(c_int) * 20, ctypes.POINTER(c_int * 20))
will map bytes 0 to 80 of the buffer to an array of 20 ints.
Changes to the array may not be recognised until the region’s
AbstractBufferRegion.invalidate()
method is called.
start (int) – Offset into the buffer to map from, in bytes
size (int) – Size of the buffer region to map, in bytes
ptr_type (ctypes pointer type) – Pointer type describing the array format to create
IndirectArrayRegion
(region, size, component_count, component_stride)¶A mapped region in which data elements are not necessarily contiguous.
This region class is used to wrap buffer regions in which the data must be accessed with some stride. For example, in an interleaved buffer this region can be used to access a single interleaved component as if the data was contiguous.
invalidate
()¶Mark this region as changed.
The buffer may not be updated with the latest contents of the array until this method is called. (However, it may not be updated until the next time the buffer is used, for efficiency).
MappableVertexBufferObject
(size, target, usage)¶A VBO with system-memory backed store.
Updates to the data via set_data()
, set_data_region()
and
map()
will be held in local memory until bind()
is
called. The advantage is that fewer OpenGL calls are needed, increasing
performance.
There may also be less performance penalty for resizing this buffer.
Updates to data via map()
are committed immediately.
bind
()¶Bind this buffer to its OpenGL target.
get_region
(start, size, ptr_type)¶Map a region of the buffer into a ctypes array of the desired type. This region does not need to be unmapped, but will become invalid if the buffer is resized.
Note that although a pointer type is required, an array is mapped. For example:
get_region(0, ctypes.sizeof(c_int) * 20, ctypes.POINTER(c_int * 20))
will map bytes 0 to 80 of the buffer to an array of 20 ints.
Changes to the array may not be recognised until the region’s
AbstractBufferRegion.invalidate()
method is called.
start (int) – Offset into the buffer to map from, in bytes
size (int) – Size of the buffer region to map, in bytes
ptr_type (ctypes pointer type) – Pointer type describing the array format to create
map
(invalidate=False)¶Map the entire buffer into system memory.
The mapped region must be subsequently unmapped with unmap before performing any other operations on the buffer.
invalidate (bool) – If True, the initial contents of the mapped block need not reflect the actual contents of the buffer.
POINTER(ctypes.c_ubyte)
Pointer to the mapped block in memory
resize
(size)¶Resize the buffer to a new size.
size (int) – New size of the buffer, in bytes
set_data
(data)¶Set the entire contents of the buffer.
data (sequence of int or ctypes pointer) – The byte array to set.
set_data_region
(data, start, length)¶Set part of the buffer contents.
data (sequence of int or ctypes pointer) – The byte array of data to set
start (int) – Offset to start replacing data
length (int) – Length of region to replace
unmap
()¶Unmap a previously mapped memory block.
VertexArray
(size)¶A ctypes implementation of a vertex array.
Many of the methods on this class are effectively no-op’s, such as
bind()
, unbind()
, map()
, unmap()
and
delete()
; they exist in order to present
a consistent interface with VertexBufferObject
.
This buffer type is also mappable, and so get_region()
can be used.
bind
()¶Bind this buffer to its OpenGL target.
delete
()¶Delete this buffer, reducing system resource usage.
get_region
(start, size, ptr_type)¶Map a region of the buffer into a ctypes array of the desired type. This region does not need to be unmapped, but will become invalid if the buffer is resized.
Note that although a pointer type is required, an array is mapped. For example:
get_region(0, ctypes.sizeof(c_int) * 20, ctypes.POINTER(c_int * 20))
will map bytes 0 to 80 of the buffer to an array of 20 ints.
Changes to the array may not be recognised until the region’s
AbstractBufferRegion.invalidate()
method is called.
start (int) – Offset into the buffer to map from, in bytes
size (int) – Size of the buffer region to map, in bytes
ptr_type (ctypes pointer type) – Pointer type describing the array format to create
map
(invalidate=False)¶Map the entire buffer into system memory.
The mapped region must be subsequently unmapped with unmap before performing any other operations on the buffer.
invalidate (bool) – If True, the initial contents of the mapped block need not reflect the actual contents of the buffer.
POINTER(ctypes.c_ubyte)
Pointer to the mapped block in memory
resize
(size)¶Resize the buffer to a new size.
size (int) – New size of the buffer, in bytes
set_data
(data)¶Set the entire contents of the buffer.
data (sequence of int or ctypes pointer) – The byte array to set.
set_data_region
(data, start, length)¶Set part of the buffer contents.
data (sequence of int or ctypes pointer) – The byte array of data to set
start (int) – Offset to start replacing data
length (int) – Length of region to replace
unbind
()¶Reset the buffer’s OpenGL target.
unmap
()¶Unmap a previously mapped memory block.
VertexArrayRegion
(array)¶A mapped region of a vertex array.
The invalidate()
method is a no-op but is
provided in order to present a consistent interface with
VertexBufferObjectRegion()
.
VertexBufferObject
(size, target, usage)¶Lightweight representation of an OpenGL VBO.
The data in the buffer is not replicated in any system memory (unless it is done so by the video driver). While this can improve memory usage and possibly performance, updates to the buffer are relatively slow.
This class does not implement AbstractMappable
, and so has no
get_region()
method. See
MappableVertexBufferObject
for a VBO class
that does implement get_region()
.
bind
()¶Bind this buffer to its OpenGL target.
delete
()¶Delete this buffer, reducing system resource usage.
map
(invalidate=False)¶Map the entire buffer into system memory.
The mapped region must be subsequently unmapped with unmap before performing any other operations on the buffer.
invalidate (bool) – If True, the initial contents of the mapped block need not reflect the actual contents of the buffer.
POINTER(ctypes.c_ubyte)
Pointer to the mapped block in memory
resize
(size)¶Resize the buffer to a new size.
size (int) – New size of the buffer, in bytes
set_data
(data)¶Set the entire contents of the buffer.
data (sequence of int or ctypes pointer) – The byte array to set.
set_data_region
(data, start, length)¶Set part of the buffer contents.
data (sequence of int or ctypes pointer) – The byte array of data to set
start (int) – Offset to start replacing data
length (int) – Length of region to replace
unbind
()¶Reset the buffer’s OpenGL target.
unmap
()¶Unmap a previously mapped memory block.
VertexBufferObjectRegion
(buffer, start, end, array)¶A mapped region of a VBO.
invalidate
()¶Mark this region as changed.
The buffer may not be updated with the latest contents of the array until this method is called. (However, it may not be updated until the next time the buffer is used, for efficiency).
create_buffer
(size, target=34962, usage=35048, vbo=True)¶Create a buffer of vertex data.
size (int) – Size of the buffer, in bytes
target (int) – OpenGL target buffer
usage (int) – OpenGL usage constant
vbo (bool) – True if a VertexBufferObject should be created if the driver supports it; otherwise only a VertexArray is created.
AbstractBuffer
create_mappable_buffer
(size, target=34962, usage=35048, vbo=True)¶Create a mappable buffer of vertex data.
size (int) – Size of the buffer, in bytes
target (int) – OpenGL target buffer
usage (int) – OpenGL usage constant
vbo (bool) – True if a VertexBufferObject
should be created if the driver
supports it; otherwise only a VertexArray
is created.