##### pygame documentation

Pygame Home || Help Contents || Reference Index

Most useful stuff: Color | display | draw | event | font | image | key | locals | mixer | mouse | Rect | Surface | time | music | pygame

Advanced stuff: cursors | joystick | mask | sprite | transform | BufferProxy | freetype | gfxdraw | midi | PixelArray | pixelcopy | sndarray | surfarray | math

Other: camera | controller | examples | fastevent | scrap | tests | touch | version

pygame.BufferProxy
  pygame object to export a surface buffer through an array protocol
  BufferProxy(<parent>) -> BufferProxy

  `BufferProxy` is a pygame support type, designed as the return value of the `Surface.get_buffer()` and `Surface.get_view()` methods. For all Python versions a `BufferProxy` object exports a C struct and Python level array interface on behalf of its parent object's buffer. A new buffer interface is also exported. In pygame, `BufferProxy` is key to implementing the `pygame.surfarray` pygame module for accessing surface pixel data using array interfaces module.

  `BufferProxy` instances can be created directly from Python code, either for a parent that exports an interface, or from a Python `dict` describing an object's buffer layout. The dict entries are based on the Python level array interface mapping. The following keys are recognized:

  > `"shape"`tuple

  >   The length of each array dimension as a tuple of integers. The length of the tuple is the number of dimensions in the array.

  > `"typestr"`string

  >   The array element type as a length 3 string. The first character gives byteorder, '<' for little-endian, '>' for big-endian, and '|' for not applicable. The second character is the element type, 'i' for signed integer, 'u' for unsigned integer, 'f' for floating point, and 'V' for an chunk of bytes. The third character gives the bytesize of the element, from '1' to '9' bytes. So, for example, "<u4" is an unsigned 4 byte little-endian integer, such as a 32 bit pixel on a PC, while "|V3" would represent a 24 bit pixel, which has no integer equivalent.

  > `"data"`tuple

  >   The physical buffer start address and a read-only flag as a length 2 tuple. The address is an integer value, while the read-only flag is a bool—`False` for writable, `True` for read-only.

  > `"strides"`tuple(optional)

  >   Array stride information as a tuple of integers. It is required only of non C-contiguous arrays. The tuple length must match that of `"shape"`.

  > `"parent"`object(optional)

  >   The exporting object. It can be used to keep the parent object alive while its buffer is visible.

  > `"before"`callable(optional)

  >   Callback invoked when the `BufferProxy` instance exports the buffer. The callback is given one argument, the `"parent"` object if given, otherwise `None`. The callback is useful for setting a lock on the parent.

  > `"after"`callable(optional)

  >   Callback invoked when an exported buffer is released. The callback is passed on argument, the `"parent"` object if given, otherwise None. The callback is useful for releasing a lock on the parent.

  The BufferProxy class supports subclassing, instance variables, and weak references.

  New in pygame 1.8.0.

  Extended in pygame 1.9.2.

  parent
    Return wrapped exporting object.
    parent -> Surface
    parent -> <parent>

    The `Surface` which returned the `BufferProxy` object or the object passed to a `BufferProxy` call.

  length
    The size, in bytes, of the exported buffer.
    length -> int

    The number of valid bytes of data exported. For discontinuous data, that is data which is not a single block of memory, the bytes within the gaps are excluded from the count. This property is equivalent to the `Py_buffer` C struct `len` field.

  raw
    A copy of the exported buffer as a single block of bytes.
    raw -> bytes

    The buffer data as a `str`/`bytes` object. Any gaps in the exported data are removed.

  write()
    Write raw bytes to object buffer.
    write(buffer, offset=0)

    Overwrite bytes in the parent object's data. The data must be C or F contiguous, otherwise a ValueError is raised. Argument buffer is a `str`/`bytes` object. An optional offset gives a start position, in bytes, within the buffer where overwriting begins. If the offset is negative or greater that or equal to the buffer proxy's `length` value, an `IndexException` is raised. If `len(buffer) > proxy.length + offset`, a `ValueError` is raised.

Edit on GitHub