xref: /third_party/python/Include/pybuffer.h (revision 7db96d56) 
1/* Public Py_buffer API */
2
3#ifndef Py_BUFFER_H
4#define Py_BUFFER_H
5#ifdef __cplusplus
6extern "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
20typedef 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. */
36PyAPI_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. */
43PyAPI_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. */
48PyAPI_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. */
52PyAPI_FUNC(Py_ssize_t) PyBuffer_SizeFromFormat(const char *format);
53
54/* Implementation in memoryobject.c */
55PyAPI_FUNC(int) PyBuffer_ToContiguous(void *buf, const Py_buffer *view,
56                                      Py_ssize_t len, char order);
57
58PyAPI_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. */
74PyAPI_FUNC(int) PyObject_CopyData(PyObject *dest, PyObject *src);
75
76/* Copy the data from the src buffer to the buffer of destination. */
77PyAPI_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. */
83PyAPI_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. */
94PyAPI_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*". */
99PyAPI_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