BufferProxy — это вспомогательный тип pygame, предназначенный для использования в качестве возвращаемого значения методов Surface.get_buffer() и Surface.get_view(). Во всех версиях Python объект BufferProxy экспортирует структуру C и интерфейс массивов на уровне Python от имени буфера родительского объекта. Также экспортируется новый интерфейс буфера. В pygame BufferProxy играет ключевую роль в реализации модуля pygame.surfarray.

Экземпляры BufferProxy можно создавать непосредственно из кода Python — как для родительского объекта, экспортирующего интерфейс, так и из объекта Python dict, описывающего структуру буфера объекта. Элементы словаря соответствуют отображению интерфейса массивов на уровне Python. Распознаются следующие ключи:

"shape"tuple

Длина каждого измерения массива в виде кортежа целых чисел. Длина кортежа равна числу измерений массива.

"typestr"string

Тип элементов массива в виде строки длиной 3 символа. Первый символ задаёт порядок байтов: '<' — от младшего к старшему, '>' — от старшего к младшему, а '|' — неприменимо. Второй символ обозначает тип элемента: 'i' — знаковое целое число, 'u' — беззнаковое целое число, 'f' — число с плавающей точкой, а 'V' — блок байтов. Третий символ задаёт размер элемента в байтах — от '1' до '9'. Например, "<u4" — это беззнаковое 4-байтовое целое число с порядком байтов от младшего к старшему, например 32-битный пиксель на ПК, а "|V3" обозначает 24-битный пиксель, которому не соответствует целочисленный тип.

"data"tuple

Начальный адрес физического буфера и флаг только для чтения в виде кортежа из двух элементов. Адрес — целочисленное значение, а флаг только для чтения — значение bool: False для записи, True для чтения.

"strides"tuple(optional)

Информация о шагах массива в виде кортежа целых чисел. Она требуется только для массивов, не расположенных непрерывно в памяти в формате C. Длина кортежа должна совпадать с длиной "shape".

"parent"object(optional)

Экспортирующий объект. Он позволяет сохранить родительский объект, пока его буфер доступен.

"before"callable(optional)

Функция обратного вызова, вызываемая при экспорте буфера экземпляром BufferProxy. Функция получает один аргумент: объект "parent", если он задан, или None в противном случае. Функция обратного вызова полезна для установки блокировки родительского объекта.

"after"callable(optional)

Функция обратного вызова, вызываемая при освобождении экспортированного буфера. Функции передаётся один аргумент: объект "parent", если он задан, или None в противном случае. Функция обратного вызова полезна для снятия блокировки родительского объекта.

Класс BufferProxy поддерживает создание подклассов, переменные экземпляров и слабые ссылки.

parent

Возвращает обёрнутый экспортирующий объект.

parent -> Surface

parent -> <parent>

Surface, вернувший объект BufferProxy, или объект, переданный при вызове BufferProxy.

length

Размер экспортированного буфера в байтах.

length -> int

Количество экспортированных действительных байтов данных. Для разрозненных данных, то есть данных, расположенных не в одном непрерывном блоке памяти, байты в промежутках не учитываются. Это свойство эквивалентно полю len структуры C Py_buffer.

raw

Копия экспортированного буфера в виде единого блока байтов.

raw -> bytes

Данные буфера в виде объекта str/bytes. Все промежутки в экспортированных данных удаляются.

write()

Записывает необработанные байты в буфер объекта.

write(buffer, offset=0)

Перезаписывает байты в данных родительского объекта. Данные должны быть непрерывными в формате C или F, иначе будет вызвано исключение ValueError. Аргумент buffer — это объект str/bytes. Необязательное смещение задаёт начальную позицию в байтах внутри буфера, с которой начинается перезапись. Если смещение отрицательное или больше либо равно значению length прокси буфера, вызывается исключение IndexException. Если len(buffer) > proxy.length + offset, вызывается исключение ValueError.