d3d11.Buffer

A Buffer is a collection of typed items. See Introduction to Buffers in Direct3D 11.

Methods

class Buffer

Buffer(layout, initializer, bind[, usage=USAGE_DEFAULT, cpuaccess=0, miscflags=0]) → Buffer

Parameters:

• layout – Describes what kind of objects the Buffer will store.
• initializer – If this is a number it will be the maximum size (capacity) of the Buffer. If it is a sequence it will be used to initialize the buffer.
• bind – A combination of Bind-flags.
• usage – One of the Usage-flags.
• cpuaccess – A combination of CPU access-flags.
• miscflags – A combination of Resource misc flags.

Creates a new Buffer.

append(x) → None

Appends a new object at the end of the buffer.

capacity() → int

Returns the maximum size of the buffer.

clear() → None

Clears the Buffer of all it’s elements. This is a very efficient operation and does not even require the buffer to be mapped.

copy(Buffer source) → None

Note

This function does not report certain errors unless Direct3D debug runtime is used.

Performs a hardware copy. Both buffers must be compatible (size and flags) for this to work.

MSDN - CopyResource()

copyRegion(int destoffset, int itemcount, int srcoffset, Buffer source) → None

Note

This function does not report certain errors unless Direct3D debug runtime is used.

Performs a hardware copy to a region.

MSDN - CopySubresourceRegion()

extend(x) → None

Extends the buffer by adding elements from the argument sequence at the end of the buffer.

getDesc() → BufferDesc<layout, capacity, bind, usage, cpuaccess, miscflags>

Returns the state of the buffer (altough semantic names has been stripped from the layout) as a named tuple. You can easily construct other buffers with these values.

b = Buffer(...)
b2 = Buffer(*b.getDesc())
b2.copy(b) #Fill b2

getItemFormat() → str

Returns a format string describing one element. Compatible with the struct-module.

getItemSize() → int

Returns the size of one buffer item in bytes.

map(int maptype) → None

Parameters:

• maptype – One of the Map-flags.

Maps the Buffer for CPU-access. Some Buffer types can’t be mapped or can be mapped only for reading or writing. If MAP_WRITE_DISCARD is used size is set to 0 and all previous content is discarded.

pop() → list

Pops and returns the last object in the buffer as a list of elements.

reformat(list newlayout) → None

Parameters:

• newlayout – New layout for the buffer.

Reformats the buffer using the new layout. A very efficient operation as this only changes how the data is interpreted. Size of the buffer will be 0 after calling this, altough you can use resize() if you know what you are doing.

resize(int newsize) → None

Parameters:

• newsize – New size for the buffer. Must be smaller than or equal to capacity().

Resizes the buffer. Because this bypasses normal initialization it is possible to read undefined data from the buffer, so be careful when using this.

oldsize = len(b) #b is a mapped buffer.
b.resize(oldsize + 1)
v = b.pop() #Oops, v's content is undefined.

unmap() → None

Unmaps a mapped Buffer.

update(sequence source[, int dstoffset=0, int srcoffset=0]) → None

Parameters:

• source – Source sequence to be written to the buffer.
• dstoffset – Destination item offset.
• srcoffset – Source item offset.

Note

This function does not report certain errors unless Direct3D debug runtime is used.

This can be used to update buffers that can’t be mapped. Buffer must have been created with USAGE_DEFAULT-flag.

b = Buffer(...)
source = [...]
b.update(source, 9, 3) #Functionally similar to 'b[9:9+len(source[3:])] = source[3:]'

MSDN - UpdateSubresource()

updateRaw(source[, offset=0]) → None

Parameters:

• offset – Destination item offset.

Updates the buffer by copying raw data from a source object which must support buffer protocol for reading. Layout is ignored, the operation is a raw copy (altough you can receive a warning if byte sizes differ). For example numpy arrays are valid objects. If you are not using a USAGE_DEFAULT-buffer the buffer must be mapped for writing (this method supports other buffer usages unlike update()).

#Store position data (x, y, z).
buffer = Buffer([("", 0, FORMAT_R32G32B32_FLOAT)], 100, BIND_VERTEX_BUFFER)
buffer.resize(100) #Prepare for updates.
data = [(10, 15, 0)] * 50 #Just an example, not very useful data.
numpyArray = numpy.array(data, "3f")
#Fill the first half of the buffer (0 to 49).
buffer.updateRaw(numpyArray)
#Fill the second of the buffer (50 to 99) using an offset.
buffer.updateRaw(numpyArray, 50)

Sequence protocol

Buffer supports several sequence operations.

class d3d11.Buffer

Buffer[int index] -> list

Returns the object at the index as a list of elements.

Buffer[int index] = object -> None

Replaces the object at the index with the given object.

Buffer[start:stop:step] -> list

Returns all objects specified by the slice-argument.

Buffer[start:stop:step] = sequence -> None

Replaces all objects specified by the slice-argument. Unlike lists if the source sequence contains more or less elements than the slice range defines they are either ignored (if more) or an exception is raised (if less).

len(Buffer) → int

Returns the current size of the buffer.

Buffer protocol

Warning

Care should be used when using buffer protocol as it is the responsibility of the programmer to ensure that the memory stays mapped as long as neccesarily and that it was mapped for correct access (read/write). Also the buffer protocol has no concept of a write-only buffer.

Buffer supports Python’s buffer protocol. For example it is possible to directly manipulate buffer’s mapped memory using memoryview or any other similar object.

The following (quite useless) example zeroes out the fifth element of the buffer by directly modifying mapped data.

b = Buffer(...)
with Mapper(b, MAP_WRITE):
    byteSize = b.getItemSize()
    view = memoryview(b)
    view[5*byteSize:5*byteSize+byteSize] = b'\0' * byteSize

See also

Module: struct

Data conversion.

Object: memoryview()

Data processing.

Links

• ID3D11Buffer