← Back to branch summary

~pygame/pygame/trunk

« back to all changes in this revision

Viewing changes to docs/reST/ref/bufferproxy.rst

  • Committer: pygame
  • Date: 2017-01-10 00:31:42 UTC
  • Revision ID: git-v1:2eea4f299a2e791f884608d7ed601558634af73c
commit 1639c41a8cb3433046882ede92c80ce69d59016b
Author: Thomas Kluyver <takowl@gmail.com>
Date:   Sun Jan 8 18:46:46 2017 +0000

    Build newer versions of libogg and libvorbis into Linux base images

    Closes #317
    Closes #323

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/reST/ref/bufferproxy.rst
 
1
.. include:: common.txt
 
2
 
 
3
.. default-domain:: py
 
4
 
 
5
:class:`pygame.BufferProxy`
 
6
===========================
 
7
 
 
8
.. currentmodule:: pygame
 
9
 
 
10
.. class:: BufferProxy
 
11
 
 
12
   | :sl:`pygame object to export a surface buffer through an array protocol`
 
13
   | :sg:`BufferProxy(<parent>) -> BufferProxy`
 
14
 
 
15
   :class:`BufferProxy` is a Pygame support type, designed as the return value
 
16
   of the :meth:`Surface.get_buffer` and :meth:`Surface.get_view` methods.
 
17
   For all Python versions a :class:`BufferProxy` object exports a C struct
 
18
   and Python level array interface on behalf of its parent object's buffer.
 
19
   For CPython 2.6 and later a new buffer interface is also exported.
 
20
   In Pygame, :class:`BufferProxy` is key to implementing the
 
21
   :mod:`pygame.surfarray` module.
 
22
 
 
23
   :class:`BufferProxy` instances can be created directly from Python code,
 
24
   either for a parent that exports an interface, or from a Python ``dict``
 
25
   describing an object's buffer layout. The dict entries are based on the
 
26
   Python level array interface mapping. The following keys are recognized:
 
27
 
 
28
      ``"shape"`` : tuple
 
29
         The length of each array dimension as a tuple of integers. The
 
30
         length of the tuple is the number of dimensions in the array.
 
31
 
 
32
      ``"typestr"`` : string
 
33
         The array element type as a length 3 string. The first character
 
34
         gives byteorder, '<' for little-endian, '>' for big-endian, and
 
35
         '\|' for not applicable. The second character is the element type,
 
36
         'i' for signed integer, 'u' for unsigned integer, 'f' for floating
 
37
         point, and 'V' for an chunk of bytes. The third character gives the
 
38
         bytesize of the element, from '1' to '9' bytes. So, for example,
 
39
         "<u4" is an unsigned 4 byte little-endian integer, such as a
 
40
         32 bit pixel on a PC, while "\|V3" would represent a 24 bit pixel,
 
41
         which has no integer equivalent.
 
42
 
 
43
      ``"data"`` : tuple
 
44
         The physical buffer start address and a read-only flag as a length
 
45
         2 tuple. The address is an integer value, while the read-only flag
 
46
         is a bool—``False`` for writable, ``True`` for read-only.
 
47
 
 
48
      ``"strides"`` : tuple : (optional)
 
49
         Array stride information as a tuple of integers. It is required
 
50
         only of non C-contiguous arrays. The tuple length must match
 
51
         that of ``"shape"``.
 
52
 
 
53
      ``"parent"`` : object : (optional)
 
54
         The exporting object. It can be used to keep the parent object
 
55
         alive while its buffer is visible.
 
56
 
 
57
      ``"before"`` : callable : (optional)
 
58
         Callback invoked when the :class:`BufferProxy` instance
 
59
         exports the buffer. The callback is given one argument, the
 
60
         ``"parent"`` object if given, otherwise ``None``.
 
61
         The callback is useful for setting a lock on the parent.
 
62
 
 
63
      ``"after"`` : callable : (optional)
 
64
         Callback invoked when an exported buffer is released.
 
65
         The callback is passed on argument, the ``"parent"`` object if given,
 
66
         otherwise None. The callback is useful for releasing a lock on the
 
67
         parent.
 
68
      
 
69
   The BufferProxy class supports subclassing, instance variables, and weak
 
70
   references.
 
71
 
 
72
   New in Pygame 1.8.0, extended in Pygame 1.9.2
 
73
 
 
74
   .. attribute:: parent
 
75
 
 
76
      | :sl:`Return wrapped exporting object.`
 
77
      | :sg:`parent -> Surface`
 
78
      | :sg:`parent -> <parent>`
 
79
 
 
80
      The :class:`Surface` which returned the :class:`BufferProxy` object or
 
81
      the object passed to a :class:`BufferProxy` call.
 
82
 
 
83
   .. attribute:: length
 
84
 
 
85
      | :sl:`The size, in bytes, of the exported buffer.`
 
86
      | :sg:`length -> int`
 
87
 
 
88
      The number of valid bytes of data exported. For discontinuous data,
 
89
      that is data which is not a single block of memory, the bytes within
 
90
      the gaps are excluded from the count. This property is equivalent to
 
91
      the ``Py_buffer`` C struct ``len`` field.
 
92
 
 
93
   .. attribute:: raw
 
94
 
 
95
      | :sl:`A copy of the exported buffer as a single block of bytes.`
 
96
      | :sg:`raw -> bytes`
 
97
 
 
98
      The buffer data as a ``str``/``bytes`` object.
 
99
      Any gaps in the exported data are removed.
 
100
 
 
101
   .. method:: write
 
102
 
 
103
      | :sl:`Write raw bytes to object buffer.`
 
104
      | :sg:`write(buffer, offset=0)`
 
105
 
 
106
      Overwrite bytes in the parent object's data. The data must be C or F
 
107
      contiguous, otherwise a ValueError is raised. Argument `buffer` is a
 
108
      ``str``/``bytes`` object. An optional offset gives a
 
109
      start position, in bytes, within the buffer where overwriting begins.
 
110
      If the offset is negative or greater that or equal to the buffer proxy's
 
111
      :attr:`length` value, an ``IndexException`` is raised.
 
112
      If ``len(buffer) > proxy.length + offset``, a ``ValueError`` is raised.