From 9f546d690899e05b25a6ef764cc8cf2f5db918b0 Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Thu, 9 Dec 2021 20:01:45 +1100 Subject: Cleanup: move public doc-strings into headers for 'imbuf' Ref T92709 --- source/blender/imbuf/IMB_imbuf.h | 161 +++++++++++++++++++++++++++++++++++---- 1 file changed, 147 insertions(+), 14 deletions(-) (limited to 'source/blender/imbuf/IMB_imbuf.h') diff --git a/source/blender/imbuf/IMB_imbuf.h b/source/blender/imbuf/IMB_imbuf.h index 45236033dfe..28e84d3d973 100644 --- a/source/blender/imbuf/IMB_imbuf.h +++ b/source/blender/imbuf/IMB_imbuf.h @@ -152,6 +152,8 @@ bool IMB_initImBuf( * Create a copy of a pixel buffer and wrap it to a new ImBuf * (transferring ownership to the in imbuf). * \attention Defined in allocimbuf.c + * + * \param take_ownership: When true, the buffers become owned by the resulting image. */ struct ImBuf *IMB_allocFromBufferOwn( unsigned int *rect, float *rectf, unsigned int w, unsigned int h, unsigned int channels); @@ -244,8 +246,14 @@ void IMB_blend_color_float(float dst[4], const float src2[4], IMB_BlendMode mode); +/** + * In-place image crop. + */ void IMB_rect_crop(struct ImBuf *ibuf, const struct rcti *crop); +/** + * In-place size setting (caller must fill in buffer contents). + */ void IMB_rect_size_set(struct ImBuf *ibuf, const uint size[2]); void IMB_rectclip(struct ImBuf *dbuf, @@ -342,7 +350,9 @@ typedef enum eIMBInterpolationFilterMode { IMB_FILTER_BILINEAR, } eIMBInterpolationFilterMode; -/* Defaults to BL_proxy within the directory of the animation. */ +/** + * Defaults to BL_proxy within the directory of the animation. + */ void IMB_anim_set_index_dir(struct anim *anim, const char *dir); void IMB_anim_get_fname(struct anim *anim, char *file, int size); @@ -352,7 +362,9 @@ IMB_Proxy_Size IMB_anim_proxy_get_existing(struct anim *anim); struct IndexBuildContext; -/* Prepare context for proxies/time-codes builder. */ +/** + * Prepare context for proxies/time-codes builder + */ struct IndexBuildContext *IMB_anim_index_rebuild_context(struct anim *anim, IMB_Timecode_Type tcs_in_use, IMB_Proxy_Size proxy_sizes_in_use, @@ -360,13 +372,17 @@ struct IndexBuildContext *IMB_anim_index_rebuild_context(struct anim *anim, const bool overwrite, struct GSet *file_list); -/* Will rebuild all used indices and proxies at once. */ +/** + * Will rebuild all used indices and proxies at once. + */ void IMB_anim_index_rebuild(struct IndexBuildContext *context, short *stop, short *do_update, float *progress); -/* Finish rebuilding proxies/time-codes and free temporary contexts used. */ +/** + * Finish rebuilding proxies/time-codes and free temporary contexts used. + */ void IMB_anim_index_rebuild_finish(struct IndexBuildContext *context, short stop); /** @@ -442,8 +458,20 @@ void IMB_free_anim(struct anim *anim); void IMB_filter(struct ImBuf *ibuf); void IMB_mask_filter_extend(char *mask, int width, int height); void IMB_mask_clear(struct ImBuf *ibuf, const char *mask, int val); +/** + * If alpha is zero, it checks surrounding pixels and averages color. sets new alphas to 1.0 + * When a mask is given, the mask will be used instead of the alpha channel, where only + * pixels with a mask value of 0 will be written to, and only pixels with a mask value of 1 + * will be used for the average. The mask will be set to one for the pixels which were written. + */ void IMB_filter_extend(struct ImBuf *ibuf, char *mask, int filter); +/** + * Frees too (if there) and recreates new data. + */ void IMB_makemipmap(struct ImBuf *ibuf, int use_filter); +/** + * Thread-safe version, only recreates existing maps. + */ void IMB_remakemipmap(struct ImBuf *ibuf, int use_filter); struct ImBuf *IMB_getmipmap(struct ImBuf *ibuf, int level); @@ -452,6 +480,9 @@ struct ImBuf *IMB_getmipmap(struct ImBuf *ibuf, int level); * \attention Defined in cache.c */ +/** + * Presumed to be called when no threads are running. + */ void IMB_tile_cache_params(int totthread, int maxmem); unsigned int *IMB_gettile(struct ImBuf *ibuf, int tx, int ty, int thread); void IMB_tiles_to_rect(struct ImBuf *ibuf); @@ -471,6 +502,8 @@ struct ImBuf *IMB_onehalf(struct ImBuf *ibuf1); /** * * \attention Defined in scaling.c + * + * Return true if \a ibuf is modified. */ bool IMB_scaleImBuf(struct ImBuf *ibuf, unsigned int newx, unsigned int newy); @@ -478,6 +511,9 @@ bool IMB_scaleImBuf(struct ImBuf *ibuf, unsigned int newx, unsigned int newy); * * \attention Defined in scaling.c */ +/** + * Return true if \a ibuf is modified. + */ bool IMB_scalefastImBuf(struct ImBuf *ibuf, unsigned int newx, unsigned int newy); /** @@ -520,16 +556,27 @@ int imb_get_anim_type(const char *filepath); */ bool IMB_isfloat(const struct ImBuf *ibuf); -/* Do byte/float and colorspace conversions need to take alpha into account? */ +/** + * Test if color-space conversions of pixels in buffer need to take into account alpha. + */ bool IMB_alpha_affects_rgb(const struct ImBuf *ibuf); -/* create char buffer, color corrected if necessary, for ImBufs that lack one */ +/** + * Create char buffer, color corrected if necessary, for ImBufs that lack one. + */ void IMB_rect_from_float(struct ImBuf *ibuf); void IMB_float_from_rect(struct ImBuf *ibuf); +/** + * No profile conversion. + */ void IMB_color_to_bw(struct ImBuf *ibuf); void IMB_saturation(struct ImBuf *ibuf, float sat); -/* converting pixel buffers */ +/* Converting pixel buffers. */ + +/** + * Float to byte pixels, output 4-channel RGBA. + */ void IMB_buffer_byte_from_float(unsigned char *rect_to, const float *rect_from, int channels_from, @@ -541,6 +588,9 @@ void IMB_buffer_byte_from_float(unsigned char *rect_to, int height, int stride_to, int stride_from); +/** + * Float to byte pixels, output 4-channel RGBA. + */ void IMB_buffer_byte_from_float_mask(unsigned char *rect_to, const float *rect_from, int channels_from, @@ -551,6 +601,9 @@ void IMB_buffer_byte_from_float_mask(unsigned char *rect_to, int stride_to, int stride_from, char *mask); +/** + * Byte to float pixels, input and output 4-channel RGBA. + */ void IMB_buffer_float_from_byte(float *rect_to, const unsigned char *rect_from, int profile_to, @@ -560,6 +613,9 @@ void IMB_buffer_float_from_byte(float *rect_to, int height, int stride_to, int stride_from); +/** + * Float to float pixels, output 4-channel RGBA. + */ void IMB_buffer_float_from_float(float *rect_to, const float *rect_from, int channels_from, @@ -580,6 +636,9 @@ void IMB_buffer_float_from_float_threaded(float *rect_to, int height, int stride_to, int stride_from); +/** + * Float to float pixels, output 4-channel RGBA. + */ void IMB_buffer_float_from_float_mask(float *rect_to, const float *rect_from, int channels_from, @@ -588,6 +647,9 @@ void IMB_buffer_float_from_float_mask(float *rect_to, int stride_to, int stride_from, char *mask); +/** + * Byte to byte pixels, input and output 4-channel RGBA. + */ void IMB_buffer_byte_from_byte(unsigned char *rect_to, const unsigned char *rect_from, int profile_to, @@ -605,6 +667,8 @@ void IMB_buffer_float_premultiply(float *buf, int width, int height); * rgba to abgr. size * 4 color bytes are reordered. * * \attention Defined in imageprocess.c + * + * Only this one is used liberally here, and in imbuf. */ void IMB_convert_rgba_to_abgr(struct ImBuf *ibuf); @@ -624,6 +688,9 @@ typedef void (*InterpolationColorFunction)( const struct ImBuf *in, unsigned char outI[4], float outF[4], float u, float v); void bicubic_interpolation_color( const struct ImBuf *in, unsigned char outI[4], float outF[4], float u, float v); + +/* Functions assumes out to be zero'ed, only does RGBA. */ + void nearest_interpolation_color_char( const struct ImBuf *in, unsigned char outI[4], float outF[4], float u, float v); void nearest_interpolation_color_fl( @@ -638,12 +705,21 @@ void bilinear_interpolation_color_char( const struct ImBuf *in, unsigned char outI[4], float outF[4], float u, float v); void bilinear_interpolation_color_fl( const struct ImBuf *in, unsigned char outI[4], float outF[4], float u, float v); +/** + * Note about wrapping, the u/v still needs to be within the image bounds, + * just the interpolation is wrapped. + * This the same as bilinear_interpolation_color except it wraps + * rather than using empty and emptyI. + */ void bilinear_interpolation_color_wrap( const struct ImBuf *in, unsigned char outI[4], float outF[4], float u, float v); 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]); +/** + * Sample pixel of image using NEAREST method. + */ void IMB_sampleImageAtLocation( struct ImBuf *ibuf, float x, float y, bool make_linear_rgb, float color[4]); @@ -697,7 +773,7 @@ struct ImBuf *IMB_double_y(struct ImBuf *ibuf1); void IMB_flipx(struct ImBuf *ibuf); void IMB_flipy(struct ImBuf *ibuf); -/* Premultiply alpha */ +/* Pre-multiply alpha. */ void IMB_premultiply_alpha(struct ImBuf *ibuf); void IMB_unpremultiply_alpha(struct ImBuf *ibuf); @@ -713,7 +789,27 @@ void IMB_freezbuffloatImBuf(struct ImBuf *ibuf); * * \attention Defined in rectop.c */ +/** + * Replace pixels of entire image with solid color. + * \param ibuf: An image to be filled with color. It must be 4 channel image. + * \param col: RGBA color, which is assigned directly to both byte (via scaling) and float buffers. + */ void IMB_rectfill(struct ImBuf *drect, const float col[4]); +/** + * Blend pixels of image area with solid color. + * + * For images with `uchar` buffer use color matching image color-space. + * For images with float buffer use color display color-space. + * If display color-space can not be referenced, use color in SRGB color-space. + * + * \param ibuf: an image to be filled with color. It must be 4 channel image. + * \param col: RGBA color. + * \param x1, y1, x2, y2: (x1, y1) defines starting point of the rectangular area to be filled, + * (x2, y2) is the end point. Note that values are allowed to be loosely ordered, which means that + * x2 is allowed to be lower than x1, as well as y2 is allowed to be lower than y1. No matter the + * order the area between x1 and x2, and y1 and y2 is filled. + * \param display: color-space reference for display space. + */ void IMB_rectfill_area(struct ImBuf *ibuf, const float col[4], int x1, @@ -721,12 +817,23 @@ void IMB_rectfill_area(struct ImBuf *ibuf, int x2, int y2, struct ColorManagedDisplay *display); +/** + * Replace pixels of image area with solid color. + * \param ibuf: an image to be filled with color. It must be 4 channel image. + * \param col: RGBA color, which is assigned directly to both byte (via scaling) and float buffers. + * \param x1, y1, x2, y2: (x1, y1) defines starting point of the rectangular area to be filled, + * (x2, y2) is the end point. Note that values are allowed to be loosely ordered, which means that + * x2 is allowed to be lower than x1, as well as y2 is allowed to be lower than y1. No matter the + * order the area between x1 and x2, and y1 and y2 is filled. + */ void IMB_rectfill_area_replace( const struct ImBuf *ibuf, const float col[4], int x1, int y1, int x2, int y2); void IMB_rectfill_alpha(struct ImBuf *ibuf, const float value); -/* This should not be here, really, - * we needed it for operating on render data, IMB_rectfill_area calls it. */ +/** + * This should not be here, really, + * we needed it for operating on render data, #IMB_rectfill_area calls it. + */ void buf_rectfill_area(unsigned char *rect, float *rectf, int width, @@ -738,23 +845,34 @@ void buf_rectfill_area(unsigned char *rect, int x2, int y2); -/* exported for image tools in blender, to quickly allocate 32 bits rect */ +/** + * Exported for image tools in blender, to quickly allocate 32 bits rect. + */ void *imb_alloc_pixels( unsigned int x, unsigned int y, unsigned int channels, size_t typesize, const char *name); bool imb_addrectImBuf(struct ImBuf *ibuf); +/** + * Any free `ibuf->rect` frees mipmaps to be sure, creation is in render on first request. + */ void imb_freerectImBuf(struct ImBuf *ibuf); bool imb_addrectfloatImBuf(struct ImBuf *ibuf); +/** + * Any free `ibuf->rect` frees mipmaps to be sure, creation is in render on first request. + */ void imb_freerectfloatImBuf(struct ImBuf *ibuf); void imb_freemipmapImBuf(struct ImBuf *ibuf); bool imb_addtilesImBuf(struct ImBuf *ibuf); void imb_freetilesImBuf(struct ImBuf *ibuf); +/** Free all pixel data (associated with image size). */ void imb_freerectImbuf_all(struct ImBuf *ibuf); -/* threaded processors */ +/** + * Threaded processors. + */ void IMB_processor_apply_threaded( int buffer_lines, int handle_size, @@ -788,7 +906,8 @@ void IMB_transform(const struct ImBuf *src, const float transform_matrix[4][4], const struct rctf *src_crop); -/* ffmpeg */ +/* FFMPEG */ + void IMB_ffmpeg_init(void); const char *IMB_ffmpeg_last_error(void); @@ -801,8 +920,17 @@ struct GPUTexture *IMB_create_gpu_texture(const char *name, bool use_high_bitdepth, bool use_premult, bool limit_gl_texture_size); +/** + * The `ibuf` is only here to detect the storage type. The produced texture will have undefined + * content. It will need to be populated by using #IMB_update_gpu_texture_sub(). + */ struct GPUTexture *IMB_touch_gpu_texture( const char *name, struct ImBuf *ibuf, int w, int h, int layers, bool use_high_bitdepth); +/** + * Will update a #GPUTexture using the content of the #ImBuf. Only one layer will be updated. + * Will resize the ibuf if needed. + * Z is the layer to update. Unused if the texture is 2D. + */ void IMB_update_gpu_texture_sub(struct GPUTexture *tex, struct ImBuf *ibuf, int x, @@ -814,7 +942,6 @@ void IMB_update_gpu_texture_sub(struct GPUTexture *tex, bool use_premult); /** - * * \attention defined in stereoimbuf.c */ void IMB_stereo3d_write_dimensions(const char mode, @@ -841,9 +968,15 @@ float *IMB_stereo3d_from_rectf(struct ImageFormatData *im_format, const size_t channels, float *rectf_left, float *rectf_right); +/** + * Left/right are always float. + */ struct ImBuf *IMB_stereo3d_ImBuf(struct ImageFormatData *im_format, struct ImBuf *ibuf_left, struct ImBuf *ibuf_right); +/** + * Reading a stereo encoded ibuf (*left) and generating two ibufs from it (*left and *right). + */ void IMB_ImBufFromStereo3d(struct Stereo3dFormat *s3d, struct ImBuf *ibuf_stereo, struct ImBuf **r_ibuf_left, -- cgit v1.2.3