include/python3.12/pybuffer.h

0001 /* Public Py_buffer API */
0002
0003 #ifndef Py_BUFFER_H
0004 #define Py_BUFFER_H
0005 #ifdef __cplusplus
0006 extern "C" {
0007 #endif
0008
0009 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030b0000
0010
0011 /* === New Buffer API ============================================
0012  * Limited API and stable ABI since Python 3.11
0013  *
0014  * Py_buffer struct layout and size is now part of the stable abi3. The
0015  * struct layout and size must not be changed in any way, as it would
0016  * break the ABI.
0017  *
0018  */
0019
0020 typedef struct {
0021     void *buf;
0022     PyObject *obj;        /* owned reference */
0023     Py_ssize_t len;
0024     Py_ssize_t itemsize;  /* This is Py_ssize_t so it can be
0025                              pointed to by strides in simple case.*/
0026     int readonly;
0027     int ndim;
0028     char *format;
0029     Py_ssize_t *shape;
0030     Py_ssize_t *strides;
0031     Py_ssize_t *suboffsets;
0032     void *internal;
0033 } Py_buffer;
0034
0035 typedef int (*getbufferproc)(PyObject *, Py_buffer *, int);
0036 typedef void (*releasebufferproc)(PyObject *, Py_buffer *);
0037
0038 /* Return 1 if the getbuffer function is available, otherwise return 0. */
0039 PyAPI_FUNC(int) PyObject_CheckBuffer(PyObject *obj);
0040
0041 /* This is a C-API version of the getbuffer function call.  It checks
0042    to make sure object has the required function pointer and issues the
0043    call.
0044
0045    Returns -1 and raises an error on failure and returns 0 on success. */
0046 PyAPI_FUNC(int) PyObject_GetBuffer(PyObject *obj, Py_buffer *view,
0047                                    int flags);
0048
0049 /* Get the memory area pointed to by the indices for the buffer given.
0050    Note that view->ndim is the assumed size of indices. */
0051 PyAPI_FUNC(void *) PyBuffer_GetPointer(const Py_buffer *view, const Py_ssize_t *indices);
0052
0053 /* Return the implied itemsize of the data-format area from a
0054    struct-style description. */
0055 PyAPI_FUNC(Py_ssize_t) PyBuffer_SizeFromFormat(const char *format);
0056
0057 /* Implementation in memoryobject.c */
0058 PyAPI_FUNC(int) PyBuffer_ToContiguous(void *buf, const Py_buffer *view,
0059                                       Py_ssize_t len, char order);
0060
0061 PyAPI_FUNC(int) PyBuffer_FromContiguous(const Py_buffer *view, const void *buf,
0062                                         Py_ssize_t len, char order);
0063
0064 /* Copy len bytes of data from the contiguous chunk of memory
0065    pointed to by buf into the buffer exported by obj.  Return
0066    0 on success and return -1 and raise a PyBuffer_Error on
0067    error (i.e. the object does not have a buffer interface or
0068    it is not working).
0069
0070    If fort is 'F', then if the object is multi-dimensional,
0071    then the data will be copied into the array in
0072    Fortran-style (first dimension varies the fastest).  If
0073    fort is 'C', then the data will be copied into the array
0074    in C-style (last dimension varies the fastest).  If fort
0075    is 'A', then it does not matter and the copy will be made
0076    in whatever way is more efficient. */
0077 PyAPI_FUNC(int) PyObject_CopyData(PyObject *dest, PyObject *src);
0078
0079 /* Copy the data from the src buffer to the buffer of destination. */
0080 PyAPI_FUNC(int) PyBuffer_IsContiguous(const Py_buffer *view, char fort);
0081
0082 /*Fill the strides array with byte-strides of a contiguous
0083   (Fortran-style if fort is 'F' or C-style otherwise)
0084   array of the given shape with the given number of bytes
0085   per element. */
0086 PyAPI_FUNC(void) PyBuffer_FillContiguousStrides(int ndims,
0087                                                Py_ssize_t *shape,
0088                                                Py_ssize_t *strides,
0089                                                int itemsize,
0090                                                char fort);
0091
0092 /* Fills in a buffer-info structure correctly for an exporter
0093    that can only share a contiguous chunk of memory of
0094    "unsigned bytes" of the given length.
0095
0096    Returns 0 on success and -1 (with raising an error) on error. */
0097 PyAPI_FUNC(int) PyBuffer_FillInfo(Py_buffer *view, PyObject *o, void *buf,
0098                                   Py_ssize_t len, int readonly,
0099                                   int flags);
0100
0101 /* Releases a Py_buffer obtained from getbuffer ParseTuple's "s*". */
0102 PyAPI_FUNC(void) PyBuffer_Release(Py_buffer *view);
0103
0104 /* Maximum number of dimensions */
0105 #define PyBUF_MAX_NDIM 64
0106
0107 /* Flags for getting buffers. Keep these in sync with inspect.BufferFlags. */
0108 #define PyBUF_SIMPLE 0
0109 #define PyBUF_WRITABLE 0x0001
0110
0111 #ifndef Py_LIMITED_API
0112 /*  we used to include an E, backwards compatible alias */
0113 #define PyBUF_WRITEABLE PyBUF_WRITABLE
0114 #endif
0115
0116 #define PyBUF_FORMAT 0x0004
0117 #define PyBUF_ND 0x0008
0118 #define PyBUF_STRIDES (0x0010 | PyBUF_ND)
0119 #define PyBUF_C_CONTIGUOUS (0x0020 | PyBUF_STRIDES)
0120 #define PyBUF_F_CONTIGUOUS (0x0040 | PyBUF_STRIDES)
0121 #define PyBUF_ANY_CONTIGUOUS (0x0080 | PyBUF_STRIDES)
0122 #define PyBUF_INDIRECT (0x0100 | PyBUF_STRIDES)
0123
0124 #define PyBUF_CONTIG (PyBUF_ND | PyBUF_WRITABLE)
0125 #define PyBUF_CONTIG_RO (PyBUF_ND)
0126
0127 #define PyBUF_STRIDED (PyBUF_STRIDES | PyBUF_WRITABLE)
0128 #define PyBUF_STRIDED_RO (PyBUF_STRIDES)
0129
0130 #define PyBUF_RECORDS (PyBUF_STRIDES | PyBUF_WRITABLE | PyBUF_FORMAT)
0131 #define PyBUF_RECORDS_RO (PyBUF_STRIDES | PyBUF_FORMAT)
0132
0133 #define PyBUF_FULL (PyBUF_INDIRECT | PyBUF_WRITABLE | PyBUF_FORMAT)
0134 #define PyBUF_FULL_RO (PyBUF_INDIRECT | PyBUF_FORMAT)
0135
0136
0137 #define PyBUF_READ  0x100
0138 #define PyBUF_WRITE 0x200
0139
0140 #endif /* !Py_LIMITED_API || Py_LIMITED_API >= 3.11 */
0141
0142 #ifdef __cplusplus
0143 }
0144 #endif
0145 #endif /* Py_BUFFER_H */