1 /* Public Py_buffer API */ 2 3 #ifndef Py_BUFFER_H 4 #define Py_BUFFER_H 5 #ifdef __cplusplus 6 extern "C" { 7 #endif 8 9 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030b0000 10 11 /* === New Buffer API ============================================ 12 * Limited API and stable ABI since Python 3.11 13 * 14 * Py_buffer struct layout and size is now part of the stable abi3. The 15 * struct layout and size must not be changed in any way, as it would 16 * break the ABI. 17 * 18 */ 19 20 typedef struct { 21 void *buf; 22 PyObject *obj; /* owned reference */ 23 Py_ssize_t len; 24 Py_ssize_t itemsize; /* This is Py_ssize_t so it can be 25 pointed to by strides in simple case.*/ 26 int readonly; 27 int ndim; 28 char *format; 29 Py_ssize_t *shape; 30 Py_ssize_t *strides; 31 Py_ssize_t *suboffsets; 32 void *internal; 33 } Py_buffer; 34 35 typedef int (*getbufferproc)(PyObject *, Py_buffer *, int); 36 typedef void (*releasebufferproc)(PyObject *, Py_buffer *); 37 38 /* Return 1 if the getbuffer function is available, otherwise return 0. */ 39 PyAPI_FUNC(int) PyObject_CheckBuffer(PyObject *obj); 40 41 /* This is a C-API version of the getbuffer function call. It checks 42 to make sure object has the required function pointer and issues the 43 call. 44 45 Returns -1 and raises an error on failure and returns 0 on success. */ 46 PyAPI_FUNC(int) PyObject_GetBuffer(PyObject *obj, Py_buffer *view, 47 int flags); 48 49 /* Get the memory area pointed to by the indices for the buffer given. 50 Note that view->ndim is the assumed size of indices. */ 51 PyAPI_FUNC(void *) PyBuffer_GetPointer(const Py_buffer *view, const Py_ssize_t *indices); 52 53 /* Return the implied itemsize of the data-format area from a 54 struct-style description. */ 55 PyAPI_FUNC(Py_ssize_t) PyBuffer_SizeFromFormat(const char *format); 56 57 /* Implementation in memoryobject.c */ 58 PyAPI_FUNC(int) PyBuffer_ToContiguous(void *buf, const Py_buffer *view, 59 Py_ssize_t len, char order); 60 61 PyAPI_FUNC(int) PyBuffer_FromContiguous(const Py_buffer *view, const void *buf, 62 Py_ssize_t len, char order); 63 64 /* Copy len bytes of data from the contiguous chunk of memory 65 pointed to by buf into the buffer exported by obj. Return 66 0 on success and return -1 and raise a PyBuffer_Error on 67 error (i.e. the object does not have a buffer interface or 68 it is not working). 69 70 If fort is 'F', then if the object is multi-dimensional, 71 then the data will be copied into the array in 72 Fortran-style (first dimension varies the fastest). If 73 fort is 'C', then the data will be copied into the array 74 in C-style (last dimension varies the fastest). If fort 75 is 'A', then it does not matter and the copy will be made 76 in whatever way is more efficient. */ 77 PyAPI_FUNC(int) PyObject_CopyData(PyObject *dest, PyObject *src); 78 79 /* Copy the data from the src buffer to the buffer of destination. */ 80 PyAPI_FUNC(int) PyBuffer_IsContiguous(const Py_buffer *view, char fort); 81 82 /*Fill the strides array with byte-strides of a contiguous 83 (Fortran-style if fort is 'F' or C-style otherwise) 84 array of the given shape with the given number of bytes 85 per element. */ 86 PyAPI_FUNC(void) PyBuffer_FillContiguousStrides(int ndims, 87 Py_ssize_t *shape, 88 Py_ssize_t *strides, 89 int itemsize, 90 char fort); 91 92 /* Fills in a buffer-info structure correctly for an exporter 93 that can only share a contiguous chunk of memory of 94 "unsigned bytes" of the given length. 95 96 Returns 0 on success and -1 (with raising an error) on error. */ 97 PyAPI_FUNC(int) PyBuffer_FillInfo(Py_buffer *view, PyObject *o, void *buf, 98 Py_ssize_t len, int readonly, 99 int flags); 100 101 /* Releases a Py_buffer obtained from getbuffer ParseTuple's "s*". */ 102 PyAPI_FUNC(void) PyBuffer_Release(Py_buffer *view); 103 104 /* Maximum number of dimensions */ 105 #define PyBUF_MAX_NDIM 64 106 107 /* Flags for getting buffers. Keep these in sync with inspect.BufferFlags. */ 108 #define PyBUF_SIMPLE 0 109 #define PyBUF_WRITABLE 0x0001 110 111 #ifndef Py_LIMITED_API 112 /* we used to include an E, backwards compatible alias */ 113 #define PyBUF_WRITEABLE PyBUF_WRITABLE 114 #endif 115 116 #define PyBUF_FORMAT 0x0004 117 #define PyBUF_ND 0x0008 118 #define PyBUF_STRIDES (0x0010 | PyBUF_ND) 119 #define PyBUF_C_CONTIGUOUS (0x0020 | PyBUF_STRIDES) 120 #define PyBUF_F_CONTIGUOUS (0x0040 | PyBUF_STRIDES) 121 #define PyBUF_ANY_CONTIGUOUS (0x0080 | PyBUF_STRIDES) 122 #define PyBUF_INDIRECT (0x0100 | PyBUF_STRIDES) 123 124 #define PyBUF_CONTIG (PyBUF_ND | PyBUF_WRITABLE) 125 #define PyBUF_CONTIG_RO (PyBUF_ND) 126 127 #define PyBUF_STRIDED (PyBUF_STRIDES | PyBUF_WRITABLE) 128 #define PyBUF_STRIDED_RO (PyBUF_STRIDES) 129 130 #define PyBUF_RECORDS (PyBUF_STRIDES | PyBUF_WRITABLE | PyBUF_FORMAT) 131 #define PyBUF_RECORDS_RO (PyBUF_STRIDES | PyBUF_FORMAT) 132 133 #define PyBUF_FULL (PyBUF_INDIRECT | PyBUF_WRITABLE | PyBUF_FORMAT) 134 #define PyBUF_FULL_RO (PyBUF_INDIRECT | PyBUF_FORMAT) 135 136 137 #define PyBUF_READ 0x100 138 #define PyBUF_WRITE 0x200 139 140 #endif /* !Py_LIMITED_API || Py_LIMITED_API >= 3.11 */ 141 142 #ifdef __cplusplus 143 } 144 #endif 145 #endif /* Py_BUFFER_H */ 146