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 */