1. Lenard Lindstrom
  2. newbuffer

Commits

Lenard Lindstrom  committed bfa0c88

Add a readme file

  • Participants
  • Parent commits 121e8c0
  • Branches default

Comments (0)

Files changed (1)

File README.rst

View file
  • Ignore whitespace
+==================
+ Module newbuffer
+==================
+
+-------------------
+ Under Development
+-------------------
+
+What is it?
+===========
+
+A module which exports the Python mixin ``BufferMixin``. The mixin adds a
+`new buffer interface`_ to a Python new-style class. The primary use is in
+Pygame_ unit tests to verify the new buffer protocol support added in
+Version 1.9.2.
+
+How it works
+============
+
+The newbuffer module exports BufferMixin, an extension class exporting
+the new buffer interface. Its ``bf_getbuffer`` and bf_releasebuffer slot
+functions in turn call Python level methods _get_buffer(self, view, flags)
+and _release_buffer(self, view) respectively.
+
+The view argument wraps a pointer to a ``Py_buffer`` C struct. ``Py_buffer``
+fields are accessed through object properties. The ``Py_buffer`` pointer's
+lifetime is limited to a ``bf_getbuffer`` or ``bf_releasebuffer`` call.
+Elsewhere, a ``Py_buffer`` field property access raises a Python exception.
+
+TODO
+====
+
+* Work out how to manage memory allocated for the ``Py_buffer.format``,
+  ``Py_buffer.shape``, and ``Py_buffer.strides`` fields.
+
+* Allow a ``BufferMixin._get_buffer`` method to pass on the ``bf_getbuffer``
+  call to another object.
+
+External links
+==============
+
+.. _Pygame:
+
+Pygame repository: https://bitbucket.org/pygame/pygame
+
+.. _`new buffer interface`:
+
+PEP 3118 — Revising the buffer protocol: http://www.python.org/dev/peps/pep-3118/