Antoine Pitrou | c663b58 | 2010-09-28 23:59:51 +0000 | [diff] [blame] | 1 | .. highlightlang:: c |
| 2 | |
| 3 | .. _memoryview-objects: |
| 4 | |
| 5 | .. index:: |
| 6 | object: memoryview |
| 7 | |
| 8 | MemoryView objects |
| 9 | ------------------ |
| 10 | |
| 11 | A :class:`memoryview` object exposes the C level :ref:`buffer interface |
| 12 | <bufferobjects>` as a Python object which can then be passed around like |
| 13 | any other object. |
| 14 | |
| 15 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 16 | .. c:function:: PyObject *PyMemoryView_FromObject(PyObject *obj) |
Antoine Pitrou | c663b58 | 2010-09-28 23:59:51 +0000 | [diff] [blame] | 17 | |
| 18 | Create a memoryview object from an object that provides the buffer interface. |
| 19 | If *obj* supports writable buffer exports, the memoryview object will be |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 20 | read/write, otherwise it may be either read-only or read/write at the |
| 21 | discretion of the exporter. |
Antoine Pitrou | c663b58 | 2010-09-28 23:59:51 +0000 | [diff] [blame] | 22 | |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 23 | .. c:function:: PyObject *PyMemoryView_FromMemory(char *mem, Py_ssize_t size, int flags) |
| 24 | |
| 25 | Create a memoryview object using *mem* as the underlying buffer. |
| 26 | *flags* can be one of :c:macro:`PyBUF_READ` or :c:macro:`PyBUF_WRITE`. |
Antoine Pitrou | c663b58 | 2010-09-28 23:59:51 +0000 | [diff] [blame] | 27 | |
Stefan Krah | 95b1ba6 | 2012-02-29 17:27:21 +0100 | [diff] [blame] | 28 | .. versionadded:: 3.3 |
| 29 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 30 | .. c:function:: PyObject *PyMemoryView_FromBuffer(Py_buffer *view) |
Antoine Pitrou | c663b58 | 2010-09-28 23:59:51 +0000 | [diff] [blame] | 31 | |
| 32 | Create a memoryview object wrapping the given buffer structure *view*. |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 33 | For simple byte buffers, :c:func:`PyMemoryView_FromMemory` is the preferred |
| 34 | function. |
Antoine Pitrou | c663b58 | 2010-09-28 23:59:51 +0000 | [diff] [blame] | 35 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 36 | .. c:function:: PyObject *PyMemoryView_GetContiguous(PyObject *obj, int buffertype, char order) |
Antoine Pitrou | c663b58 | 2010-09-28 23:59:51 +0000 | [diff] [blame] | 37 | |
| 38 | Create a memoryview object to a contiguous chunk of memory (in either |
| 39 | 'C' or 'F'ortran *order*) from an object that defines the buffer |
| 40 | interface. If memory is contiguous, the memoryview object points to the |
Eli Bendersky | 5a53f36 | 2011-11-25 15:07:50 +0200 | [diff] [blame] | 41 | original memory. Otherwise, a copy is made and the memoryview points to a |
Antoine Pitrou | c663b58 | 2010-09-28 23:59:51 +0000 | [diff] [blame] | 42 | new bytes object. |
| 43 | |
| 44 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 45 | .. c:function:: int PyMemoryView_Check(PyObject *obj) |
Antoine Pitrou | c663b58 | 2010-09-28 23:59:51 +0000 | [diff] [blame] | 46 | |
| 47 | Return true if the object *obj* is a memoryview object. It is not |
| 48 | currently allowed to create subclasses of :class:`memoryview`. |
| 49 | |
| 50 | |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 51 | .. c:function:: Py_buffer *PyMemoryView_GET_BUFFER(PyObject *mview) |
Antoine Pitrou | c663b58 | 2010-09-28 23:59:51 +0000 | [diff] [blame] | 52 | |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 53 | Return a pointer to the memoryview's private copy of the exporter's buffer. |
| 54 | *mview* **must** be a memoryview instance; this macro doesn't check its type, |
| 55 | you must do it yourself or you will risk crashes. |
| 56 | |
| 57 | .. c:function:: Py_buffer *PyMemoryView_GET_BASE(PyObject *mview) |
| 58 | |
| 59 | Return either a pointer to the exporting object that the memoryview is based |
| 60 | on or *NULL* if the memoryview has been created by one of the functions |
| 61 | :c:func:`PyMemoryView_FromMemory` or :c:func:`PyMemoryView_FromBuffer`. |
| 62 | *mview* **must** be a memoryview instance. |
Antoine Pitrou | c663b58 | 2010-09-28 23:59:51 +0000 | [diff] [blame] | 63 | |