From 4a8bd318255e6fe829a93e8cb8039e8e1896fc72 Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Fri, 11 Mar 2022 09:41:48 +1100 Subject: Cleanup: use doxy sections in image.cc Also minor improvements & clarifications to comments. --- source/blender/blenkernel/intern/image.cc | 105 ++++++++++++++++++++---------- 1 file changed, 72 insertions(+), 33 deletions(-) (limited to 'source/blender/blenkernel/intern/image.cc') diff --git a/source/blender/blenkernel/intern/image.cc b/source/blender/blenkernel/intern/image.cc index ff10f36cc22..b4644b84f1e 100644 --- a/source/blender/blenkernel/intern/image.cc +++ b/source/blender/blenkernel/intern/image.cc @@ -109,7 +109,11 @@ static void image_init(Image *ima, short source, short type); static void image_free_packedfiles(Image *ima); static void copy_image_packedfiles(ListBase *lb_dst, const ListBase *lb_src); -/* Reset runtime image fields when data-block is being initialized. */ +/* -------------------------------------------------------------------- */ +/** \name Image #IDTypeInfo API + * \{ */ + +/** Reset runtime image fields when data-block is being initialized. */ static void image_runtime_reset(struct Image *image) { memset(&image->runtime, 0, sizeof(image->runtime)); @@ -117,7 +121,7 @@ static void image_runtime_reset(struct Image *image) BLI_mutex_init(static_cast(image->runtime.cache_mutex)); } -/* Reset runtime image fields when data-block is being copied. */ +/** Reset runtime image fields when data-block is being copied. */ static void image_runtime_reset_on_copy(struct Image *image) { image->runtime.cache_mutex = MEM_mallocN(sizeof(ThreadMutex), "image runtime cache_mutex"); @@ -479,7 +483,11 @@ static void image_add_view(Image *ima, const char *viewname, const char *filepat # define IMA_INDEX_PASS(index) (index & ~1023) #endif -/* ******** IMAGE CACHE ************* */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Image Cache + * \{ */ typedef struct ImageCacheKey { int index; @@ -548,7 +556,11 @@ static struct ImBuf *imagecache_get(Image *image, int index, bool *r_is_cached_e return nullptr; } -/* ***************** ALLOC & FREE, DATA MANAGING *************** */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Allocate & Free, Data Managing + * \{ */ static void image_free_cached_frames(Image *image) { @@ -666,12 +678,12 @@ static Image *image_alloc(Main *bmain, const char *name, short source, short typ return ima; } -/* Get the ibuf from an image cache by its index and entry. +/** + * Get the ibuf from an image cache by its index and entry. * Local use here only. * - * Returns referenced image buffer if it exists, callee is to - * call IMB_freeImBuf to de-reference the image buffer after - * it's done handling it. + * \returns referenced image buffer if it exists, callee is to call #IMB_freeImBuf + * to de-reference the image buffer after it's done handling it. */ static ImBuf *image_get_cached_ibuf_for_index_entry(Image *ima, int index, @@ -1127,7 +1139,8 @@ Image *BKE_image_add_generated(Main *bmain, int view_id; const char *names[2] = {STEREO_LEFT_NAME, STEREO_RIGHT_NAME}; - // STRNCPY(ima->filepath, name); /* don't do this, this writes in ain invalid filepath! */ + /* NOTE: leave `ima->filepath` unset, + * setting it to a dummy value may write to an invalid file-path. */ ima->gen_x = width; ima->gen_y = height; ima->gen_type = gen_type; @@ -1179,7 +1192,7 @@ Image *BKE_image_add_from_imbuf(Main *bmain, ImBuf *ibuf, const char *name) return ima; } -/* Pack image buffer to memory as PNG or EXR. */ +/** Pack image buffer to memory as PNG or EXR. */ static bool image_memorypack_imbuf(Image *ima, ImBuf *ibuf, const char *filepath) { ibuf->ftype = (ibuf->rect_float) ? IMB_FTYPE_OPENEXR : IMB_FTYPE_PNG; @@ -1472,7 +1485,11 @@ void BKE_image_all_free_anim_ibufs(Main *bmain, int cfra) } } -/* *********** READ AND WRITE ************** */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Read and Write + * \{ */ int BKE_image_imtype_to_ftype(const char imtype, ImbFormatOptions *r_options) { @@ -1607,7 +1624,7 @@ bool BKE_imtype_supports_zbuf(const char imtype) { switch (imtype) { case R_IMF_IMTYPE_IRIZ: - case R_IMF_IMTYPE_OPENEXR: /* but not R_IMF_IMTYPE_MULTILAYER */ + case R_IMF_IMTYPE_OPENEXR: /* But not #R_IMF_IMTYPE_MULTILAYER. */ return true; } return false; @@ -3131,7 +3148,7 @@ void BKE_imbuf_write_prepare(ImBuf *ibuf, const ImageFormatData *imf) } #endif else { - /* R_IMF_IMTYPE_JPEG90, etc. default we save jpegs */ + /* #R_IMF_IMTYPE_JPEG90, etc. fallback to JPEG image. */ if (quality < 10) { quality = 90; } @@ -3278,7 +3295,11 @@ struct anim *openanim(const char *name, int flags, int streamindex, char colorsp return anim; } -/* ************************* New Image API *************** */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name New Image API + * \{ */ /* Notes about Image storage * - packedfile @@ -3290,8 +3311,8 @@ struct anim *openanim(const char *name, int flags, int streamindex, char colorsp * - renderresult * -> comes from packedfile or filename * - listbase - * -> ibufs from exrhandle - * - flipbook array + * -> ibufs from EXR-handle. + * - flip-book array * -> ibufs come from movie, temporary renderresult or sequence * - ibuf * -> comes from packedfile or filename or generated @@ -3834,8 +3855,10 @@ void BKE_image_signal(Main *bmain, Image *ima, ImageUser *iuser, int signal) BKE_ntree_update_main(bmain, nullptr); } -/* return renderpass for a given pass index and active view */ -/* fallback to available if there are missing passes for active view */ +/** + * \return render-pass for a given pass index and active view. + * fallback to available if there are missing passes for active view. + */ static RenderPass *image_render_pass_get(RenderLayer *rl, const int pass, const int view, @@ -4477,7 +4500,11 @@ void BKE_image_backup_render(Scene *scene, Image *ima, bool free_current_slot) ima->last_render_slot = ima->render_slot; } -/**************************** multiview load openexr *********************************/ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Multiview Load OpenEXR + * \{ */ static void image_add_view(Image *ima, const char *viewname, const char *filepath) { @@ -4510,8 +4537,8 @@ static void image_add_view(Image *ima, const char *viewname, const char *filepat } } -/* after imbuf load, openexr type can return with a exrhandle open */ -/* in that case we have to build a render-result */ +/* After imbuf load, OpenEXR type can return with a EXR-handle open + * in that case we have to build a render-result. */ #ifdef WITH_OPENEXR static void image_create_multilayer(Image *ima, ImBuf *ibuf, int framenr) { @@ -4536,7 +4563,7 @@ static void image_create_multilayer(Image *ima, ImBuf *ibuf, int framenr) } #endif /* WITH_OPENEXR */ -/* common stuff to do with images after loading */ +/** Common stuff to do with images after loading. */ static void image_init_after_load(Image *ima, ImageUser *iuser, ImBuf *UNUSED(ibuf)) { /* Preview is null when it has never been used as an icon before. @@ -4571,7 +4598,9 @@ static int imbuf_alpha_flags_for_image(Image *ima) return 0; } -/* the number of files will vary according to the stereo format */ +/** + * \return the number of files will vary according to the stereo format. + */ static int image_num_files(Image *ima) { const bool is_multiview = BKE_image_is_multiview(ima); @@ -5402,30 +5431,30 @@ static ImBuf *image_acquire_ibuf(Image *ima, ImageUser *iuser, void **r_lock) } if (ibuf == nullptr) { - /* we are sure we have to load the ibuf, using source and type */ + /* We are sure we have to load the ibuf, using source and type. */ if (ima->source == IMA_SRC_MOVIE) { - /* source is from single file, use flipbook to store ibuf */ + /* Source is from single file, use flip-book to store ibuf. */ ibuf = image_load_movie_file(ima, iuser, entry); } else if (ima->source == IMA_SRC_SEQUENCE) { if (ima->type == IMA_TYPE_IMAGE) { - /* regular files, ibufs in flipbook, allows saving */ + /* Regular files, ibufs in flip-book, allows saving. */ ibuf = image_load_sequence_file(ima, iuser, entry, entry); } /* no else; on load the ima type can change */ if (ima->type == IMA_TYPE_MULTILAYER) { - /* only 1 layer/pass stored in imbufs, no exrhandle anim storage, no saving */ + /* Only 1 layer/pass stored in imbufs, no EXR-handle anim storage, no saving. */ ibuf = image_load_sequence_multilayer(ima, iuser, entry, entry); } } else if (ima->source == IMA_SRC_TILED) { if (ima->type == IMA_TYPE_IMAGE) { - /* regular files, ibufs in flipbook, allows saving */ + /* Regular files, ibufs in flip-book, allows saving */ ibuf = image_load_sequence_file(ima, iuser, entry, 0); } /* no else; on load the ima type can change */ if (ima->type == IMA_TYPE_MULTILAYER) { - /* only 1 layer/pass stored in imbufs, no exrhandle anim storage, no saving */ + /* Only 1 layer/pass stored in imbufs, no EXR-handle anim storage, no saving. */ ibuf = image_load_sequence_multilayer(ima, iuser, entry, 0); } } @@ -5441,8 +5470,8 @@ static ImBuf *image_acquire_ibuf(Image *ima, ImageUser *iuser, void **r_lock) } } else if (ima->source == IMA_SRC_GENERATED) { - /* generated is: ibuf is allocated dynamically */ - /* UV testgrid or black or solid etc */ + /* Generated is: `ibuf` is allocated dynamically. */ + /* UV test-grid or black or solid etc. */ if (ima->gen_x == 0) { ima->gen_x = 1024; } @@ -5564,7 +5593,11 @@ bool BKE_image_has_ibuf(Image *ima, ImageUser *iuser) return ibuf != nullptr; } -/* ******** Pool for image buffers ******** */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Pool for Image Buffers + * \{ */ struct ImagePoolItem { struct ImagePoolItem *next, *prev; @@ -6274,7 +6307,11 @@ static void image_update_views_format(Image *ima, ImageUser *iuser) } } -/**************************** Render Slots ***************************/ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Render Slots + * \{ */ RenderSlot *BKE_image_add_renderslot(Image *ima, const char *name) { @@ -6392,3 +6429,5 @@ RenderSlot *BKE_image_get_renderslot(Image *ima, int index) /* Can be null for images without render slots. */ return static_cast(BLI_findlink(&ima->renderslots, index)); } + +/** \} */ -- cgit v1.2.3