IMB_imbuf.hh

Go to the documentation of this file.

/* SPDX-FileCopyrightText: 2001-2002 NaN Holding BV. All rights reserved.
 * SPDX-FileCopyrightText: 2025 Blender Authors
 *
 * SPDX-License-Identifier: GPL-2.0-or-later */

 
#pragma once
 
#include "../gpu/GPU_texture.hh"
 
#include "BLI_math_matrix_types.hh"
#include "BLI_utildefines.h"
 
#include "IMB_imbuf_types.hh"
 
struct ImBuf;
struct rctf;
struct rcti;
 
struct GSet;
struct ImageFormatData;
struct Stereo3dFormat;

void IMB_init();
void IMB_exit();

ImBuf *IMB_load_image_from_memory(const unsigned char *mem,
                                  const size_t size,
                                  const int flags,
                                  const char *descr,
                                  const char *filepath = nullptr,
                                  char r_colorspace[IM_MAX_SPACE] = nullptr);
 
ImBuf *IMB_load_image_from_file_descriptor(const int file,
                                           const int flags,
                                           const char *filepath = nullptr,
                                           char r_colorspace[IM_MAX_SPACE] = nullptr);
 
ImBuf *IMB_load_image_from_filepath(const char *filepath,
                                    const int flags,
                                    char r_colorspace[IM_MAX_SPACE] = nullptr);

bool IMB_save_image(ImBuf *ibuf, const char *filepath, const int flags);
 
/*
 * Test image file.
 */
bool IMB_test_image(const char *filepath);
bool IMB_test_image_type_matches(const char *filepath, int filetype);
int IMB_test_image_type_from_memory(const unsigned char *buf, size_t buf_size);
int IMB_test_image_type(const char *filepath);
 
/*
 * Load thumbnail image.
 */
enum class IMBThumbLoadFlags {
  Zero = 0,
  LoadLargeFiles = (1 << 0),
};
ENUM_OPERATORS(IMBThumbLoadFlags, IMBThumbLoadFlags::LoadLargeFiles);
 
ImBuf *IMB_thumb_load_image(const char *filepath,
                            const size_t max_thumb_size,
                            char colorspace[IM_MAX_SPACE],
                            const IMBThumbLoadFlags load_flags = IMBThumbLoadFlags::Zero);
 
/*
 * Allocate and free image buffer.
 */
ImBuf *IMB_allocImBuf(unsigned int x, unsigned int y, unsigned char planes, unsigned int flags);
void IMB_freeImBuf(ImBuf *ibuf);

bool IMB_initImBuf(
    ImBuf *ibuf, unsigned int x, unsigned int y, unsigned char planes, unsigned int flags);

ImBuf *IMB_allocFromBufferOwn(uint8_t *byte_buffer,
                              float *float_buffer,
                              unsigned int w,
                              unsigned int h,
                              unsigned int channels);

ImBuf *IMB_allocFromBuffer(const uint8_t *byte_buffer,
                           const float *float_buffer,
                           unsigned int w,
                           unsigned int h,
                           unsigned int channels);

void IMB_assign_byte_buffer(ImBuf *ibuf, uint8_t *buffer_data, ImBufOwnership ownership);
void IMB_assign_float_buffer(ImBuf *ibuf, float *buffer_data, ImBufOwnership ownership);

void IMB_assign_byte_buffer(ImBuf *ibuf, const ImBufByteBuffer &buffer, ImBufOwnership ownership);
void IMB_assign_float_buffer(ImBuf *ibuf,
                             const ImBufFloatBuffer &buffer,
                             ImBufOwnership ownership);
void IMB_assign_dds_data(ImBuf *ibuf, const DDSData &data, ImBufOwnership ownership);

void IMB_make_writable_byte_buffer(ImBuf *ibuf);
void IMB_make_writable_float_buffer(ImBuf *ibuf);

uint8_t *IMB_steal_byte_buffer(ImBuf *ibuf);
float *IMB_steal_float_buffer(ImBuf *ibuf);
uint8_t *IMB_steal_encoded_buffer(ImBuf *ibuf);

 
void IMB_refImBuf(ImBuf *ibuf);
ImBuf *IMB_makeSingleUser(ImBuf *ibuf);
 
ImBuf *IMB_dupImBuf(const ImBuf *ibuf1);

size_t IMB_get_size_in_memory(const ImBuf *ibuf);

size_t IMB_get_pixel_count(const ImBuf *ibuf);
 
enum IMB_BlendMode {
  IMB_BLEND_MIX = 0,
  IMB_BLEND_ADD = 1,
  IMB_BLEND_SUB = 2,
  IMB_BLEND_MUL = 3,
  IMB_BLEND_LIGHTEN = 4,
  IMB_BLEND_DARKEN = 5,
  IMB_BLEND_ERASE_ALPHA = 6,
  IMB_BLEND_ADD_ALPHA = 7,
  IMB_BLEND_OVERLAY = 8,
  IMB_BLEND_HARDLIGHT = 9,
  IMB_BLEND_COLORBURN = 10,
  IMB_BLEND_LINEARBURN = 11,
  IMB_BLEND_COLORDODGE = 12,
  IMB_BLEND_SCREEN = 13,
  IMB_BLEND_SOFTLIGHT = 14,
  IMB_BLEND_PINLIGHT = 15,
  IMB_BLEND_VIVIDLIGHT = 16,
  IMB_BLEND_LINEARLIGHT = 17,
  IMB_BLEND_DIFFERENCE = 18,
  IMB_BLEND_EXCLUSION = 19,
  IMB_BLEND_HUE = 20,
  IMB_BLEND_SATURATION = 21,
  IMB_BLEND_LUMINOSITY = 22,
  IMB_BLEND_COLOR = 23,
  IMB_BLEND_INTERPOLATE = 24,
 
  IMB_BLEND_COPY = 1000,
  IMB_BLEND_COPY_RGB = 1001,
  IMB_BLEND_COPY_ALPHA = 1002,
};
 
void IMB_blend_color_byte(unsigned char dst[4],
                          const unsigned char src1[4],
                          const unsigned char src2[4],
                          IMB_BlendMode mode);
void IMB_blend_color_float(float dst[4],
                           const float src1[4],
                           const float src2[4],
                           IMB_BlendMode mode);

void IMB_rect_crop(ImBuf *ibuf, const rcti *crop);

void IMB_rect_size_set(ImBuf *ibuf, const uint size[2]);
 
void IMB_rectclip(ImBuf *dbuf,
                  const ImBuf *sbuf,
                  int *destx,
                  int *desty,
                  int *srcx,
                  int *srcy,
                  int *width,
                  int *height);
void IMB_rectcpy(ImBuf *dbuf,
                 const ImBuf *sbuf,
                 int destx,
                 int desty,
                 int srcx,
                 int srcy,
                 int width,
                 int height);
void IMB_rectblend(ImBuf *dbuf,
                   const ImBuf *obuf,
                   const ImBuf *sbuf,
                   unsigned short *dmask,
                   const unsigned short *curvemask,
                   const unsigned short *texmask,
                   float mask_max,
                   int destx,
                   int desty,
                   int origx,
                   int origy,
                   int srcx,
                   int srcy,
                   int width,
                   int height,
                   IMB_BlendMode mode,
                   bool accumulate);
void IMB_rectblend_threaded(ImBuf *dbuf,
                            const ImBuf *obuf,
                            const ImBuf *sbuf,
                            unsigned short *dmask,
                            const unsigned short *curvemask,
                            const unsigned short *texmask,
                            float mask_max,
                            int destx,
                            int desty,
                            int origx,
                            int origy,
                            int srcx,
                            int srcy,
                            int width,
                            int height,
                            IMB_BlendMode mode,
                            bool accumulate);
 
enum eIMBInterpolationFilterMode {
  IMB_FILTER_NEAREST,
  IMB_FILTER_BILINEAR,
  IMB_FILTER_CUBIC_BSPLINE,
  IMB_FILTER_CUBIC_MITCHELL,
  IMB_FILTER_BOX,
};
 
#define FILTER_MASK_NULL 0
#define FILTER_MASK_MARGIN 1
#define FILTER_MASK_USED 2
 
void IMB_mask_filter_extend(char *mask, int width, int height);
void IMB_mask_clear(ImBuf *ibuf, const char *mask, int val);
void IMB_filter_extend(ImBuf *ibuf, char *mask, int filter);
 
void IMB_filtery(ImBuf *ibuf);

enum class IMBScaleFilter {
  Nearest,
  Bilinear,
  Box,
};

bool IMB_scale(ImBuf *ibuf,
               unsigned int newx,
               unsigned int newy,
               IMBScaleFilter filter,
               bool threaded = true);

ImBuf *IMB_scale_into_new(const ImBuf *ibuf,
                          unsigned int newx,
                          unsigned int newy,
                          IMBScaleFilter filter,
                          bool threaded = true);

bool IMB_alpha_affects_rgb(const ImBuf *ibuf);

void IMB_byte_from_float(ImBuf *ibuf);
void IMB_float_from_byte_ex(ImBuf *dst, const ImBuf *src, const rcti *region_to_update);
void IMB_float_from_byte(ImBuf *ibuf);
void IMB_color_to_bw(ImBuf *ibuf);
void IMB_saturation(ImBuf *ibuf, float sat);
 
/* Converting pixel buffers. */

void IMB_buffer_byte_from_float(unsigned char *rect_to,
                                const float *rect_from,
                                int channels_from,
                                float dither,
                                int profile_to,
                                int profile_from,
                                bool predivide,
                                int width,
                                int height,
                                int stride_to,
                                int stride_from,
                                int start_y = 0);
void IMB_buffer_byte_from_float_mask(unsigned char *rect_to,
                                     const float *rect_from,
                                     int channels_from,
                                     float dither,
                                     bool predivide,
                                     int width,
                                     int height,
                                     int stride_to,
                                     int stride_from,
                                     char *mask);
void IMB_buffer_float_from_byte(float *rect_to,
                                const unsigned char *rect_from,
                                int profile_to,
                                int profile_from,
                                bool predivide,
                                int width,
                                int height,
                                int stride_to,
                                int stride_from);
void IMB_buffer_float_from_float(float *rect_to,
                                 const float *rect_from,
                                 int channels_from,
                                 int profile_to,
                                 int profile_from,
                                 bool predivide,
                                 int width,
                                 int height,
                                 int stride_to,
                                 int stride_from);
void IMB_buffer_float_from_float_threaded(float *rect_to,
                                          const float *rect_from,
                                          int channels_from,
                                          int profile_to,
                                          int profile_from,
                                          bool predivide,
                                          int width,
                                          int height,
                                          int stride_to,
                                          int stride_from);
void IMB_buffer_float_from_float_mask(float *rect_to,
                                      const float *rect_from,
                                      int channels_from,
                                      int width,
                                      int height,
                                      int stride_to,
                                      int stride_from,
                                      char *mask);
void IMB_buffer_byte_from_byte(unsigned char *rect_to,
                               const unsigned char *rect_from,
                               int profile_to,
                               int profile_from,
                               bool predivide,
                               int width,
                               int height,
                               int stride_to,
                               int stride_from);
 
void IMB_alpha_under_color_float(float *rect_float, int x, int y, float backcol[3]);
void IMB_alpha_under_color_byte(unsigned char *rect, int x, int y, const float backcol[3]);
 
void IMB_flipx(ImBuf *ibuf);
void IMB_flipy(ImBuf *ibuf);
 
/* Rotate by 90 degree increments. Returns true if the ImBuf is altered. */
bool IMB_rotate_orthogonal(ImBuf *ibuf, int degrees);
 
/* Pre-multiply alpha. */
 
void IMB_premultiply_alpha(ImBuf *ibuf);
void IMB_unpremultiply_alpha(ImBuf *ibuf);

void IMB_rectfill(ImBuf *drect, const float col[4]);
void IMB_rectfill_area(
    ImBuf *ibuf, const float scene_linear_color[4], int x1, int y1, int x2, int y2);
void IMB_rectfill_alpha(ImBuf *ibuf, float value);

void *imb_alloc_pixels(unsigned int x,
                       unsigned int y,
                       unsigned int channels,
                       size_t typesize,
                       bool initialize_pixels,
                       const char *alloc_name);

bool IMB_alloc_byte_pixels(ImBuf *ibuf, bool initialize_pixels = true);

void IMB_free_byte_pixels(ImBuf *ibuf);

bool IMB_alloc_float_pixels(ImBuf *ibuf,
                            const unsigned int channels,
                            bool initialize_pixels = true);
void IMB_free_float_pixels(ImBuf *ibuf);

void IMB_free_all_data(ImBuf *ibuf);
 
/* Free the GPU textures of the given image buffer, leaving the CPU buffers unchanged.
 * The ibuf can be nullptr, in which case the function does nothing. */
void IMB_free_gpu_textures(ImBuf *ibuf);

enum eIMBTransformMode {
  IMB_TRANSFORM_MODE_REGULAR = 0,
  IMB_TRANSFORM_MODE_CROP_SRC = 1,
  IMB_TRANSFORM_MODE_WRAP_REPEAT = 2,
};

void IMB_transform(const ImBuf *src,
                   ImBuf *dst,
                   eIMBTransformMode mode,
                   eIMBInterpolationFilterMode filter,
                   const blender::float3x3 &transform_matrix,
                   const rctf *src_crop);
 
blender::gpu::Texture *IMB_create_gpu_texture(const char *name,
                                              ImBuf *ibuf,
                                              bool use_high_bitdepth,
                                              bool use_premult);
 
blender::gpu::TextureFormat IMB_gpu_get_texture_format(const ImBuf *ibuf,
                                                       bool high_bitdepth,
                                                       bool use_grayscale);
 
bool IMB_gpu_get_compressed_format(const ImBuf *ibuf,
                                   blender::gpu::TextureFormat *r_texture_format);

void IMB_gpu_clamp_half_float(ImBuf *image_buffer);

blender::gpu::Texture *IMB_touch_gpu_texture(const char *name,
                                             ImBuf *ibuf,
                                             int w,
                                             int h,
                                             int layers,
                                             bool use_high_bitdepth,
                                             bool use_grayscale);

void IMB_update_gpu_texture_sub(blender::gpu::Texture *tex,
                                ImBuf *ibuf,
                                int x,
                                int y,
                                int z,
                                int w,
                                int h,
                                bool use_high_bitdepth,
                                bool use_grayscale,
                                bool use_premult);
 
void IMB_stereo3d_write_dimensions(
    char mode, bool is_squeezed, size_t width, size_t height, size_t *r_width, size_t *r_height);
void IMB_stereo3d_read_dimensions(
    char mode, bool is_squeezed, size_t width, size_t height, size_t *r_width, size_t *r_height);
ImBuf *IMB_stereo3d_ImBuf(const ImageFormatData *im_format, ImBuf *ibuf_left, ImBuf *ibuf_right);
void IMB_ImBufFromStereo3d(const Stereo3dFormat *s3d,
                           ImBuf *ibuf_stereo3d,
                           ImBuf **r_ibuf_left,
                           ImBuf **r_ibuf_right);