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