BufferList

class BufferList(**kwargs)

Buffer lists are an object containing a list of buffers.

Buffer lists are created with new() and filled with data using insert().

Buffer lists can be pushed on a srcpad with push_list(). This is interesting when multiple buffers need to be pushed in one go because it can reduce the amount of overhead for pushing each buffer individually.

Constructors

class BufferList

classmethod new() → BufferList

Creates a new, empty BufferList.

classmethod new_sized(size: int) → BufferList

Creates a new, empty BufferList. The list will have size space preallocated so that memory reallocations can be avoided.

Parameters:

size – an initial reserved size

Methods

class BufferList

calculate_size() → int

Calculates the size of the data contained in list by adding the size of all buffers.

Added in version 1.14.

foreach(func: Callable[[Buffer | None, int, Any], tuple[bool, Buffer | None]], user_data: Any = None) → bool

Calls func with data for each buffer in list.

func can modify the passed buffer pointer or its contents. The return value of func defines if this function returns or if the remaining buffers in the list should be skipped.

Parameters:

• func – a BufferListFunc to call

• user_data – user data passed to func

get(idx: int) → Buffer

Gets the buffer at idx.

You must make sure that idx does not exceed the number of buffers available.

Parameters:

idx – the index

get_writable(idx: int) → Buffer

Gets the buffer at idx, ensuring it is a writable buffer.

You must make sure that idx does not exceed the number of buffers available.

Added in version 1.14.

Parameters:

idx – the index

insert(idx: int, buffer: Buffer) → None

Inserts buffer at idx in list. Other buffers are moved to make room for this new buffer.

A -1 value for idx will append the buffer at the end.

Parameters:

• idx – the index

• buffer – a Buffer

is_writable() → bool

Tests if you can safely modify list. It is only safe to modify buffer list when there is only one owner of the buffer list - ie, the object is writable.

length() → int

Returns the number of buffers in list.

make_writable() → BufferList

Returns a writable copy of list.

If there is only one reference count on list, the caller must be the owner, and so this function will return the buffer list object unchanged. If on the other hand there is more than one reference on the object, a new buffer list object will be returned. The caller’s reference on list will be removed, and instead the caller will own a reference to the returned object.

In short, this function unrefs the buffer_list in the argument and refs the buffer list that it returns. Don’t access the argument after calling this function. See also: ref().

remove(idx: int, length: int) → None

Removes length buffers starting from idx in list. The following buffers are moved to close the gap.

Parameters:

• idx – the index

• length – the amount to remove

classmethod replace(old_list: BufferList | None = None, new_list: BufferList | None = None) → tuple[bool, BufferList | None]

Modifies a pointer to a BufferList to point to a different BufferList. The modification is done atomically (so this is useful for ensuring thread safety in some cases), and the reference counts are updated appropriately (the old buffer list is unreffed, the new is reffed).

Either new_list or the BufferList pointed to by old_list may be None.

Added in version 1.16.

Parameters:

• old_list – pointer to a pointer to a BufferList to be replaced.

• new_list – pointer to a BufferList that will replace the buffer list pointed to by old_list.

classmethod take(old_list: BufferList, new_list: BufferList | None = None) → tuple[bool, BufferList]

Modifies a pointer to a BufferList to point to a different BufferList. This function is similar to replace() except that it takes ownership of new_list.

Added in version 1.16.

Parameters:

• old_list – pointer to a pointer to a BufferList to be replaced.

• new_list – pointer to a BufferList that will replace the bufferlist pointed to by old_list.