Blender V5.3
imbuf_py_api.cc File Reference
#include <Python.h>
#include "BLI_rect.hh"
#include "BLI_utildefines.hh"
#include "DNA_space_enums.h"
#include "py_capi_utils.hh"
#include "python_compat.hh"
#include "imbuf_py_api.hh"
#include "../../imbuf/IMB_imbuf.hh"
#include "../../imbuf/IMB_imbuf_types.hh"
#include "BLI_fileops.hh"
#include <cerrno>
#include <fcntl.h>
#include <optional>

Go to the source code of this file.

Classes

struct  blender::Py_ImBufBuffer
struct  blender::Py_ImBufFileType
struct  blender::Py_ImBuf

Namespaces

namespace  blender
 BMesh Iterators.

Macros

#define IMB_FTYPE_DEFAULT   IMB_FTYPE_PNG
#define PY_IMBUF_BUFFER_TYPE_DOC

Functions

File Type Info

TODO: check on merging this into ImFileType, this is currently private, but could be extended to provide more useful info.

static std::optional< int > blender::py_imbuf_ftype_from_string (const char *str)
Module Functions
 blender::PyDoc_STRVAR (M_imbuf_new_doc, ".. function:: new(size, *, planes=32, buffer_type='BYTE')\n" "\n" " Create a new image.\n" "\n" " :param size: The size of the image in pixels.\n" " :type size: tuple[int, int]\n" " :param planes: Number of bits per pixel.\n" " :type planes: Literal[8, 16, 24, 32]\n" PY_IMBUF_BUFFER_TYPE_DOC " :return: The newly created image.\n" " :rtype: :class:`ImBuf`\n")
static PyObject * blender::M_imbuf_new (PyObject *, PyObject *args, PyObject *kw)
static PyObject * blender::imbuf_load_impl (const char *filepath)
 blender::PyDoc_STRVAR (M_imbuf_load_doc, ".. function:: load(filepath)\n" "\n" " Load an image from a file.\n" "\n" " :param filepath: The filepath of the image.\n" " :type filepath: str | bytes\n" " :return: The newly loaded image.\n" " :rtype: :class:`ImBuf`\n")
static PyObject * blender::M_imbuf_load (PyObject *, PyObject *args, PyObject *kw)
static PyObject * blender::imbuf_load_from_memory_impl (const char *buffer, const size_t buffer_size, ImBufFlags flags)
 blender::PyDoc_STRVAR (M_imbuf_load_from_buffer_doc, ".. function:: load_from_buffer(buffer)\n" "\n" " Load an image from a buffer.\n" "\n" " :param buffer: A buffer containing the image data.\n" " :type buffer: collections.abc.Buffer\n" " :return: The newly loaded image.\n" " :rtype: :class:`ImBuf`\n")
static PyObject * blender::M_imbuf_load_from_buffer (PyObject *, PyObject *args, PyObject *kw)
static PyObject * blender::imbuf_write_impl (ImBuf *ibuf, const char *filepath)
static PyObject * blender::py_imbuf_write_impl (Py_ImBuf *py_imb, const char *filepath_or_null)
 blender::PyDoc_STRVAR (M_imbuf_write_doc, ".. function:: write(image, *, filepath=None)\n" "\n" " Write an image.\n" "\n" " :param image: The image to write.\n" " :type image: :class:`ImBuf`\n" " :param filepath: Optional filepath of the image (fallback to the image's file path).\n" " :type filepath: str | bytes | None\n")
static PyObject * blender::M_imbuf_write (PyObject *, PyObject *args, PyObject *kw)
static PyObject * blender::imbuf_write_to_buffer_impl (ImBuf *ibuf, PyObject *file)
 blender::PyDoc_STRVAR (M_imbuf_write_to_buffer_doc, ".. function:: write_to_buffer(image, file)\n" "\n" " Write an image to a file-like object.\n" "\n" " :param image: The image to write.\n" " :type image: :class:`ImBuf`\n" " :param file: A writable file-like object (e.g. :class:`io.BytesIO`).\n" " :type file: :class:`BinaryIO`\n")
static PyObject * blender::M_imbuf_write_to_buffer (PyObject *, PyObject *args, PyObject *kw)
 blender::PyDoc_STRVAR (M_imbuf_file_type_from_buffer_doc, ".. function:: file_type_from_buffer(buffer)\n" "\n" " Detect the image file type from a buffer.\n" "\n" " :param buffer: A buffer containing image data.\n" " :type buffer: collections.abc.Buffer\n" " :return: The detected file type, or None if unrecognized.\n" " :rtype: :class:`ImBufFileType` | None\n")
static PyObject * blender::M_imbuf_file_type_from_buffer (PyObject *, PyObject *args, PyObject *kw)
Public API
ImBuf * blender::BPy_ImBuf_FromPyObject (PyObject *py_imbuf)

Variables

static const PyC_StringEnumItems blender::py_imbuf_buffer_mode_items []
static const char * blender::py_imbuf_type_none = "NONE"

Type & Utilities

#define PY_IMBUF_CHECK_OBJ(obj)
#define PY_IMBUF_CHECK_INT(obj)
#define PY_IMBUF_CHECK_BUFFER_USERS_OBJ(obj)
#define PY_IMBUF_CHECK_BUFFER_TYPE_OBJ(obj, buffer_type_var)
static int blender::py_imbuf_valid_check (Py_ImBuf *self)
static void blender::py_imbuf_warn_corrupt_ftype (const eImbFileType ftype)
static const char * blender::py_imbuf_ftype_to_id_with_fallback (const eImbFileType ftype)
static bool blender::py_imbuf_region_sanitize (const ImBuf *ibuf, rcti *region)
static std::optional< ImBufFlags > blender::py_imbuf_buffer_type (const ImBuf *ibuf)
static std::optional< ImBufFlags > blender::py_imbuf_buffer_type_or_error (const ImBuf *ibuf)
static ImBufFlags blender::py_imbuf_write_flags (const ImBuf *ibuf)

Buffer, Type & Implementation

PyTypeObject blender::Py_ImBufBuffer_Type
static PyMethodDef blender::Py_ImBufBuffer_methods []
static void blender::py_imbuf_buffer_dealloc (Py_ImBufBuffer *self)
static int blender::py_imbuf_buffer_traverse (Py_ImBufBuffer *self, visitproc visit, void *arg)
static int blender::py_imbuf_buffer_clear (Py_ImBufBuffer *self)
static PyObject * blender::py_imbuf_buffer_repr (Py_ImBufBuffer *self)
static PyObject * blender::py_imbuf_buffer_enter (Py_ImBufBuffer *self)
static PyObject * blender::py_imbuf_buffer_exit (Py_ImBufBuffer *self, PyObject *)

File Type, Type & Implementation

PyTypeObject blender::Py_ImBufFileType_Type
static PyGetSetDef blender::Py_ImBufFileType_getseters []
 blender::PyDoc_STRVAR (py_imbuf_file_type_id_doc, "The identifier for this image file type (e.g. ``\"PNG\"``, ``\"JPEG\"``).\n" "\n" ":type: str\n")
static PyObject * blender::py_imbuf_file_type_id_get (Py_ImBufFileType *self, void *)
 blender::PyDoc_STRVAR (py_imbuf_file_type_file_extensions_doc, "The file extensions associated with this image file type (e.g. ``(\".jpg\", \".jpeg\")``).\n" "\n" ":type: tuple[str, ...]\n")
static PyObject * blender::py_imbuf_file_type_file_extensions_get (Py_ImBufFileType *self, void *)
static PyObject * blender::py_imbuf_file_type_capability_read_get (Py_ImBufFileType *self, void *flag_p)
static PyObject * blender::py_imbuf_file_type_capability_write_get (Py_ImBufFileType *self, void *flag_p)
 blender::PyDoc_STRVAR (py_imbuf_file_type_has_read_file_doc, "True when images of this file type can be read from a file.\n" "\n" ":type: bool\n")
 blender::PyDoc_STRVAR (py_imbuf_file_type_has_write_file_doc, "True when images of this file type can be written to a file.\n" "\n" ":type: bool\n")
 blender::PyDoc_STRVAR (py_imbuf_file_type_has_read_memory_doc, "True when images of this file type can be read from memory.\n" "\n" ":type: bool\n")
 blender::PyDoc_STRVAR (py_imbuf_file_type_has_write_memory_doc, "True when images of this file type can be written to memory.\n" "\n" ":type: bool\n")
static PyObject * blender::py_imbuf_file_type_repr (Py_ImBufFileType *self)
static Py_hash_t blender::py_imbuf_file_type_hash (Py_ImBufFileType *self)

Methods

static PyMethodDef blender::Py_ImBuf_methods []
 blender::PyDoc_STRVAR (py_imbuf_resize_doc, ".. method:: resize(size, *, method='FAST')\n" "\n" " Resize the image in-place.\n" "\n" " :param size: New size.\n" " :type size: tuple[int, int]\n" " :param method: Method of resizing ('FAST', 'BILINEAR').\n" " :type method: str\n")
static PyObject * blender::py_imbuf_resize (Py_ImBuf *self, PyObject *args, PyObject *kw)
 blender::PyDoc_STRVAR (py_imbuf_crop_doc, ".. method:: crop(min, max)\n" "\n" " Crop the image in-place.\n" "\n" " :param min: Minimum pixel coordinates (X, Y), inclusive.\n" " :type min: tuple[int, int]\n" " :param max: Maximum pixel coordinates (X, Y), inclusive.\n" " :type max: tuple[int, int]\n")
static PyObject * blender::py_imbuf_crop (Py_ImBuf *self, PyObject *args, PyObject *kw)
 blender::PyDoc_STRVAR (py_imbuf_copy_doc, ".. method:: copy()\n" "\n" " Return a copy of the image.\n" "\n" " :return: A copy of the image.\n" " :rtype: :class:`ImBuf`\n")
static PyObject * blender::py_imbuf_copy (Py_ImBuf *self)
static PyObject * blender::py_imbuf_deepcopy (Py_ImBuf *self, PyObject *args)
 blender::PyDoc_STRVAR (py_imbuf_with_buffer_doc, ".. method:: with_buffer(*, write=False, region=None)\n" "\n" " Return a context manager that yields a :class:`memoryview` " "of the image's pixel data, shaped ``(height, width, channels)``.\n" "\n" " Usage::\n" "\n" " with image.with_buffer(write=True) as buf:\n" " buf[0, 0, 0] = 255 # set red channel of pixel (0, 0)\n" "\n" " :param write: When true the buffer is writable.\n" " :type write: bool\n" " :param region: Optional sub-region ``((x_min, y_min), (x_max, y_max))``, " "clamped to image bounds. When set the shape becomes " "``(region_height, region_width, channels)``.\n" " :type region: tuple[tuple[int, int], tuple[int, int]] | None\n" " :return: A context manager yielding a :class:`memoryview` of pixel data.\n" " :rtype: :class:`ImBufBuffer`\n")
static PyObject * blender::py_imbuf_with_buffer (Py_ImBuf *self, PyObject *args, PyObject *kw)
 blender::PyDoc_STRVAR (py_imbuf_convert_buffer_type_doc, ".. method:: convert_buffer_type(buffer_type)\n" "\n" " Convert the image's pixel buffer to the given type.\n" " When the image is already of the given type this is a no-op.\n" " The previous buffer is freed.\n" "\n" PY_IMBUF_BUFFER_TYPE_DOC)
static PyObject * blender::py_imbuf_convert_buffer_type (Py_ImBuf *self, PyObject *args, PyObject *kw)
 blender::PyDoc_STRVAR (py_imbuf_free_doc, ".. method:: free()\n" "\n" " Clear image data immediately (causing an error on re-use).\n")
static PyObject * blender::py_imbuf_free (Py_ImBuf *self)

Attributes

static PyGetSetDef blender::Py_ImBuf_getseters []
 blender::PyDoc_STRVAR (py_imbuf_size_doc, "Size of the image in pixels.\n" "\n" ":type: tuple[int, int]\n")
static PyObject * blender::py_imbuf_size_get (Py_ImBuf *self, void *)
 blender::PyDoc_STRVAR (py_imbuf_ppm_doc, "Pixels per meter.\n" "\n" ":type: tuple[float, float]\n")
static PyObject * blender::py_imbuf_ppm_get (Py_ImBuf *self, void *)
static int blender::py_imbuf_ppm_set (Py_ImBuf *self, PyObject *value, void *)
 blender::PyDoc_STRVAR (py_imbuf_filepath_doc, "Filepath associated with this image.\n" "\n" ":type: str | bytes\n")
static PyObject * blender::py_imbuf_filepath_get (Py_ImBuf *self, void *)
static int blender::py_imbuf_filepath_set (Py_ImBuf *self, PyObject *value, void *)
 blender::PyDoc_STRVAR (py_imbuf_planes_doc, "Number of bits per pixel for the byte buffer.\n" "Used when reading and writing image files.\n" "\n" "- 8: Gray-scale.\n" "- 16: Gray-scale with alpha.\n" "- 24: RGB.\n" "- 32: RGBA.\n" "\n" ".. note::\n" "\n" " This value may be set by the file format on load,\n" " and determines how many channels are written on save.\n" "\n" ":type: int\n")
static PyObject * blender::py_imbuf_planes_get (Py_ImBuf *self, void *)
 blender::PyDoc_STRVAR (py_imbuf_channels_doc, "Number of color channels.\n" "\n" ":type: int\n")
static PyObject * blender::py_imbuf_channels_get (Py_ImBuf *self, void *)
 blender::PyDoc_STRVAR (py_imbuf_quality_doc, "Quality for formats that support lossy compression (0 - 100, clamped).\n" "\n" ":type: int\n")
static PyObject * blender::py_imbuf_quality_get (Py_ImBuf *self, void *)
static int blender::py_imbuf_quality_set (Py_ImBuf *self, PyObject *value, void *)
 blender::PyDoc_STRVAR (py_imbuf_compress_doc, "Compression level for formats that support lossless compression levels (0 - 100, clamped).\n" "\n" ":type: int\n")
static PyObject * blender::py_imbuf_compress_get (Py_ImBuf *self, void *)
static int blender::py_imbuf_compress_set (Py_ImBuf *self, PyObject *value, void *)
 blender::PyDoc_STRVAR (py_imbuf_file_type_doc, "The file type identifier.\n" "\n" ":type: str\n")
static PyObject * blender::py_imbuf_file_type_get (Py_ImBuf *self, void *)
static int blender::py_imbuf_file_type_set (Py_ImBuf *self, PyObject *value, void *)
 blender::PyDoc_STRVAR (py_imbuf_buffer_type_doc, "Type of the image's pixel buffer (``'BYTE'`` or ``'FLOAT'``).\n" "\n" ":type: str\n")
static PyObject * blender::py_imbuf_buffer_type_get (Py_ImBuf *self, void *)

Type & Implementation

PyTypeObject blender::Py_ImBuf_Type
static PyObject * blender::Py_ImBuf_CreatePyObject (ImBuf *ibuf)
static void blender::py_imbuf_dealloc (Py_ImBuf *self)
static PyObject * blender::py_imbuf_repr (Py_ImBuf *self)
static Py_hash_t blender::py_imbuf_hash (Py_ImBuf *self)

Module Definition (<tt>imbuf</tt>)

static PyMethodDef blender::IMB_methods []
static PyModuleDef blender::IMB_module_def
 blender::PyDoc_STRVAR (IMB_doc, "This module provides access to Blender's image manipulation API.\n" "\n" "It provides access to image buffers outside of Blender's\n" ":class:`bpy.types.Image` data-block context.\n")
PyObject * blender::BPyInit_imbuf ()

Module Definition (<tt>imbuf.types</tt>)

imbuf.types module, only include this to expose access to imbuf.types.ImBuf for docs and the ability to use with built-ins such as isinstance, issubclass.

static PyModuleDef blender::IMB_types_module_def
static PyObject * blender::BPyInit_imbuf_types ()
 blender::PyDoc_STRVAR (IMB_types_doc, "This module provides access to image buffer types.\n" "\n" ".. note::\n" "\n" " Image buffer is also the structure used by :class:`bpy.types.Image`\n" " ID type to store and manipulate image data at runtime.\n")

Detailed Description

This file defines the 'imbuf' image manipulation module.

Definition in file imbuf_py_api.cc.

Macro Definition Documentation

◆ IMB_FTYPE_DEFAULT

#define IMB_FTYPE_DEFAULT   IMB_FTYPE_PNG

Definition at line 33 of file imbuf_py_api.cc.

Referenced by blender::imbuf_write_to_buffer_impl().

◆ PY_IMBUF_BUFFER_TYPE_DOC

#define PY_IMBUF_BUFFER_TYPE_DOC
Value:
" :param buffer_type: The buffer type.\n" \
" :type buffer_type: Literal['BYTE', 'FLOAT']\n"

Definition at line 43 of file imbuf_py_api.cc.

Referenced by blender::PyDoc_STRVAR(), and blender::PyDoc_STRVAR().

◆ PY_IMBUF_CHECK_BUFFER_TYPE_OBJ

#define PY_IMBUF_CHECK_BUFFER_TYPE_OBJ ( obj,
buffer_type_var )
Value:
const std::optional<ImBufFlags> _buffer_type_or_none = py_imbuf_buffer_type_or_error( \
(obj)->ibuf); \
if (_buffer_type_or_none == std::nullopt) [[unlikely]] { \
return nullptr; \
} \
const ImBufFlags buffer_type_var = *(_buffer_type_or_none)
#define PY_IMBUF_CHECK_OBJ(obj)

Ensure #ImBuf has a buffer, it's type assigned to buffer_type_var, or return with an exception set in the unlikely event there is no buffer.

Definition at line 220 of file imbuf_py_api.cc.

Referenced by blender::py_imbuf_buffer_enter(), blender::py_imbuf_buffer_type_get(), and blender::py_imbuf_convert_buffer_type().

◆ PY_IMBUF_CHECK_BUFFER_USERS_OBJ

#define PY_IMBUF_CHECK_BUFFER_USERS_OBJ ( obj)
Value:
if ((obj)->buffer_users > 0) [[unlikely]] { \
PyErr_SetString(PyExc_BufferError, \
"ImBuf cannot be modified while pixel buffers are exported"); \
return nullptr; \
} \
((void)0)

Definition at line 126 of file imbuf_py_api.cc.

Referenced by blender::py_imbuf_convert_buffer_type(), blender::py_imbuf_crop(), blender::py_imbuf_free(), and blender::py_imbuf_resize().

◆ PY_IMBUF_CHECK_INT

#define PY_IMBUF_CHECK_INT ( obj)
Value:
if (py_imbuf_valid_check(obj) == -1) [[unlikely]] { \
return -1; \
} \
((void)0)

Definition at line 120 of file imbuf_py_api.cc.

Referenced by blender::py_imbuf_compress_set(), blender::py_imbuf_file_type_set(), blender::py_imbuf_filepath_set(), blender::py_imbuf_ppm_set(), and blender::py_imbuf_quality_set().

◆ PY_IMBUF_CHECK_OBJ