Cleanup: use doxy sections for imbuf

6 files changed, 242 insertions, 58 deletions

diff --git a/source/blender/imbuf/intern/cache.c b/source/blender/imbuf/intern/cache.c
index 23ce9bd7818..02d1fe3710a 100644
--- a/source/blender/imbuf/intern/cache.c
+++ b/source/blender/imbuf/intern/cache.c
@@ -32,6 +32,10 @@
 
 #include "imbuf.h"
 
+/* -------------------------------------------------------------------- */
+/** \name Local Structs
+ * \{ */
+
 /* We use a two level cache here. A per-thread cache with limited number of
  * tiles. This can be accessed without locking and so is hoped to lead to most
  * tile access being lock-free. The global cache is shared between all threads
@@ -85,7 +89,11 @@ typedef struct ImGlobalTileCache {
 
 static ImGlobalTileCache GLOBAL_CACHE;
 
-/***************************** Hash Functions ********************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Hash Functions
+ * \{ */
 
 static unsigned int imb_global_tile_hash(const void *gtile_p)
 {
@@ -117,7 +125,11 @@ static bool imb_thread_tile_cmp(const void *a_p, const void *b_p)
   return ((a->ibuf != b->ibuf) || (a->tx != b->tx) || (a->ty != b->ty));
 }
 
-/******************************** Load/Unload ********************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Load/Unload
+ * \{ */
 
 static void imb_global_cache_tile_load(ImGlobalTile *gtile)
 {
@@ -167,7 +179,11 @@ void imb_tile_cache_tile_free(ImBuf *ibuf, int tx, int ty)
   BLI_mutex_unlock(&GLOBAL_CACHE.mutex);
 }
 
-/******************************* Init/Exit ***********************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Init/Exit
+ * \{ */
 
 static void imb_thread_cache_init(ImThreadTileCache *cache)
 {
@@ -265,7 +281,11 @@ void IMB_tile_cache_params(int totthread, int maxmem)
   BLI_mutex_init(&GLOBAL_CACHE.mutex);
 }
 
-/***************************** Global Cache **********************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Global Cache
+ * \{ */
 
 static ImGlobalTile *imb_global_cache_get_tile(ImBuf *ibuf,
                                                int tx,
@@ -353,7 +373,11 @@ static ImGlobalTile *imb_global_cache_get_tile(ImBuf *ibuf,
   return gtile;
 }
 
-/***************************** Per-Thread Cache ******************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Per-Thread Cache
+ * \{ */
 
 static unsigned int *imb_thread_cache_get_tile(ImThreadTileCache *cache,
                                                ImBuf *ibuf,
@@ -465,3 +489,5 @@ void IMB_tiles_to_rect(ImBuf *ibuf)
     }
   }
 }
+
+/** \} */
diff --git a/source/blender/imbuf/intern/colormanagement.c b/source/blender/imbuf/intern/colormanagement.c
index 6dd4d14cbc7..00dbd539410 100644
--- a/source/blender/imbuf/intern/colormanagement.c
+++ b/source/blender/imbuf/intern/colormanagement.c
@@ -60,7 +60,9 @@
 
 #include <ocio_capi.h>
 
-/*********************** Global declarations *************************/
+/* -------------------------------------------------------------------- */
+/** \name Global declarations
+ * \{ */
 
 #define DISPLAY_BUFFER_CHANNELS 4
 
@@ -135,9 +137,14 @@ static struct global_color_picking_state {
   bool failed;
 } global_color_picking_state = {NULL};
 
-/*********************** Color managed cache *************************/
+/** \} */
 
-/* Cache Implementation Notes
+/* -------------------------------------------------------------------- */
+/** \name Color Managed Cache
+ * \{ */
+
+/**
+ * Cache Implementation Notes
  * ==========================
  *
  * All color management cache stuff is stored in two properties of
@@ -459,7 +466,11 @@ static void colormanage_cache_handle_release(void *cache_handle)
   IMB_freeImBuf(cache_ibuf);
 }
 
-/*********************** Initialization / De-initialization *************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Initialization / De-initialization
+ * \{ */
 
 static void colormanage_role_color_space_name_get(OCIO_ConstConfigRcPtr *config,
                                                   char *colorspace_name,
@@ -749,7 +760,11 @@ void colormanagement_exit(void)
   colormanage_free_config();
 }
 
-/*********************** Internal functions *************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Internal functions
+ * \{ */
 
 static bool colormanage_compatible_look(ColorManagedLook *look, const char *view_name)
 {
@@ -1119,7 +1134,11 @@ void colormanage_imbuf_make_linear(ImBuf *ibuf, const char *from_colorspace)
   }
 }
 
-/*********************** Generic functions *************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Generic Functions
+ * \{ */
 
 static void colormanage_check_display_settings(ColorManagedDisplaySettings *display_settings,
                                                const char *what,
@@ -1459,7 +1478,11 @@ const float *IMB_colormangement_get_xyz_to_rgb()
   return &imbuf_xyz_to_rgb[0][0];
 }
 
-/*********************** Threaded display buffer transform routines *************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Threaded Display Buffer Transform Routines
+ * \{ */
 
 typedef struct DisplayBufferThread {
   ColormanageProcessor *cm_processor;
@@ -1827,7 +1850,11 @@ static void colormanage_display_buffer_process(ImBuf *ibuf,
       ibuf, NULL, display_buffer, view_settings, display_settings);
 }
 
-/*********************** Threaded processor transform routines *************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Threaded Processor Transform Routines
+ * \{ */
 
 typedef struct ProcessorTransformThread {
   ColormanageProcessor *cm_processor;
@@ -1955,7 +1982,11 @@ static void processor_transform_apply_threaded(unsigned char *byte_buffer,
                                do_processor_transform_thread);
 }
 
-/*********************** Color space transformation functions *************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Color Space Transformation Functions
+ * \{ */
 
 /* Convert the whole buffer from specified by name color space to another -
  * internal implementation. */
@@ -2667,7 +2698,11 @@ void IMB_colormanagement_buffer_make_display_space(
   IMB_colormanagement_processor_free(cm_processor);
 }
 
-/*********************** Public display buffers interfaces *************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Public Display Buffers Interfaces
+ * \{ */
 
 /* acquire display buffer for given image buffer using specified view and display settings */
 unsigned char *IMB_display_buffer_acquire(ImBuf *ibuf,
@@ -2825,7 +2860,11 @@ void IMB_display_buffer_release(void *cache_handle)
   }
 }
 
-/*********************** Display functions *************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Display Functions
+ * \{ */
 
 const char *colormanage_display_get_default_name(void)
 {
@@ -2945,7 +2984,11 @@ const char *IMB_colormanagement_display_get_default_view_transform_name(
   return colormanage_view_get_default_name(display);
 }
 
-/*********************** View functions *************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name View Functions
+ * \{ */
 
 const char *colormanage_view_get_default_name(const ColorManagedDisplay *display)
 {
@@ -3059,7 +3102,11 @@ const char *IMB_colormanagement_view_get_default_name(const char *display_name)
   return NULL;
 }
 
-/*********************** Color space functions *************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Color Space Functions
+ * \{ */
 
 static void colormanage_description_strip(char *description)
 {
@@ -3203,7 +3250,11 @@ void IMB_colormanagement_colorspace_from_ibuf_ftype(
   }
 }
 
-/*********************** Looks functions *************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Looks Functions
+ * \{ */
 
 ColorManagedLook *colormanage_look_add(const char *name, const char *process_space, bool is_noop)
 {
@@ -3276,7 +3327,11 @@ const char *IMB_colormanagement_look_get_indexed_name(int index)
   return NULL;
 }
 
-/*********************** RNA helper functions *************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name RNA Helper Functions
+ * \{ */
 
 void IMB_colormanagement_display_items_add(EnumPropertyItem **items, int *totitem)
 {
@@ -3372,7 +3427,11 @@ void IMB_colormanagement_colorspace_items_add(EnumPropertyItem **items, int *tot
   }
 }
 
-/*********************** Partial display buffer update  *************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Partial Display Buffer Update
+ * \{ */
 
 /*
  * Partial display update is supposed to be used by such areas as
@@ -3750,7 +3809,11 @@ void IMB_partial_display_buffer_update_delayed(ImBuf *ibuf, int xmin, int ymin,
   }
 }
 
-/*********************** Pixel processor functions *************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Pixel Processor Functions
+ * \{ */
 
 ColormanageProcessor *IMB_colormanagement_display_processor_new(
     const ColorManagedViewSettings *view_settings,
@@ -4172,3 +4235,5 @@ void IMB_colormanagement_finish_glsl_draw(void)
     OCIO_finishGLSLDraw(global_glsl_state.ocio_glsl_state);
   }
 }
+
+/** \} */
diff --git a/source/blender/imbuf/intern/divers.c b/source/blender/imbuf/intern/divers.c
index 798849f2dd4..5f580449e12 100644
--- a/source/blender/imbuf/intern/divers.c
+++ b/source/blender/imbuf/intern/divers.c
@@ -35,7 +35,9 @@
 
 #include "MEM_guardedalloc.h"
 
-/************************* Floyd-Steinberg dithering *************************/
+/* -------------------------------------------------------------------- */
+/** \name Floyd-Steinberg dithering
+ * \{ */
 
 typedef struct DitherContext {
   float dither;
@@ -56,7 +58,11 @@ static void clear_dither_context(DitherContext *di)
   MEM_freeN(di);
 }
 
-/************************* Generic Buffer Conversion *************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Generic Buffer Conversion
+ * \{ */
 
 MINLINE void ushort_to_byte_v4(uchar b[4], const unsigned short us[4])
 {
@@ -705,7 +711,11 @@ void IMB_buffer_byte_from_byte(uchar *rect_to,
   }
 }
 
-/****************************** ImBuf Conversion *****************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name ImBuf Conversion
+ * \{ */
 
 void IMB_rect_from_float(ImBuf *ibuf)
 {
@@ -822,7 +832,11 @@ void IMB_float_from_rect(ImBuf *ibuf)
   }
 }
 
-/**************************** Color to Grayscale *****************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Color to Grayscale
+ * \{ */
 
 /* no profile conversion */
 void IMB_color_to_bw(ImBuf *ibuf)
@@ -864,7 +878,11 @@ void IMB_buffer_float_premultiply(float *buf, int width, int height)
   }
 }
 
-/**************************** alter saturation *****************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Alter Saturation
+ * \{ */
 
 void IMB_saturation(ImBuf *ibuf, float sat)
 {
@@ -890,3 +908,5 @@ void IMB_saturation(ImBuf *ibuf, float sat)
     }
   }
 }
+
+/** \} */
diff --git a/source/blender/imbuf/intern/imageprocess.c b/source/blender/imbuf/intern/imageprocess.c
index bcac140f036..6ad69e72b4f 100644
--- a/source/blender/imbuf/intern/imageprocess.c
+++ b/source/blender/imbuf/intern/imageprocess.c
@@ -76,6 +76,7 @@ void IMB_convert_rgba_to_abgr(struct ImBuf *ibuf)
     }
   }
 }
+
 static void pixel_from_buffer(struct ImBuf *ibuf, unsigned char **outI, float **outF, int x, int y)
 
 {
@@ -90,7 +91,9 @@ static void pixel_from_buffer(struct ImBuf *ibuf, unsigned char **outI, float **
   }
 }
 
-/* BICUBIC Interpolation */
+/* -------------------------------------------------------------------- */
+/** \name Bi-Cubic Interpolation
+ * \{ */
 
 void bicubic_interpolation_color(
     struct ImBuf *in, unsigned char outI[4], float outF[4], float u, float v)
@@ -118,7 +121,12 @@ void bicubic_interpolation(ImBuf *in, ImBuf *out, float u, float v, int xout, in
   bicubic_interpolation_color(in, outI, outF, u, v);
 }
 
-/* BILINEAR INTERPOLATION */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Bi-Linear Interpolation
+ * \{ */
+
 void bilinear_interpolation_color(
     struct ImBuf *in, unsigned char outI[4], float outF[4], float u, float v)
 {
@@ -224,8 +232,13 @@ void bilinear_interpolation(ImBuf *in, ImBuf *out, float u, float v, int xout, i
   bilinear_interpolation_color(in, outI, outF, u, v);
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Nearest Interpolation
+ * \{ */
+
 /* function assumes out to be zero'ed, only does RGBA */
-/* NEAREST INTERPOLATION */
 void nearest_interpolation_color(
     struct ImBuf *in, unsigned char outI[4], float outF[4], float u, float v)
 {
@@ -336,7 +349,9 @@ void nearest_interpolation(ImBuf *in, ImBuf *out, float u, float v, int xout, in
   nearest_interpolation_color(in, outI, outF, u, v);
 }
 
-/*********************** Threaded image processing *************************/
+/* -------------------------------------------------------------------- */
+/** \name Threaded Image Processing
+ * \{ */
 
 static void processor_apply_func(TaskPool *__restrict pool, void *taskdata)
 {
@@ -431,7 +446,11 @@ void IMB_processor_apply_threaded_scanlines(int total_scanlines,
   BLI_task_pool_free(task_pool);
 }
 
-/* Alpha-under */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Alpha-under
+ * \{ */
 
 void IMB_alpha_under_color_float(float *rect_float, int x, int y, float backcol[3])
 {
@@ -485,6 +504,12 @@ void IMB_alpha_under_color_byte(unsigned char *rect, int x, int y, const float b
   }
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Sample Pixel
+ * \{ */
+
 /* Sample pixel of image using NEAREST method. */
 void IMB_sampleImageAtLocation(ImBuf *ibuf, float x, float y, bool make_linear_rgb, float color[4])
 {
@@ -500,3 +525,5 @@ void IMB_sampleImageAtLocation(ImBuf *ibuf, float x, float y, bool make_linear_r
     }
   }
 }
+
+/** \} */
diff --git a/source/blender/imbuf/intern/stereoimbuf.c b/source/blender/imbuf/intern/stereoimbuf.c
index 247122065de..d3c91b55f22 100644
--- a/source/blender/imbuf/intern/stereoimbuf.c
+++ b/source/blender/imbuf/intern/stereoimbuf.c
@@ -58,6 +58,10 @@ typedef struct Stereo3DData {
   bool is_float;
 } Stereo3DData;
 
+/* -------------------------------------------------------------------- */
+/** \name Local Functions
+ * \{ */
+
 static void imb_stereo3d_write_anaglyph(Stereo3DData *s3d, enum eStereo3dAnaglyphType mode)
 {
   int x, y;
@@ -508,7 +512,11 @@ static void imb_stereo3d_write_topbottom(Stereo3DData *s3d)
   }
 }
 
-/**************************** dimension utils ****************************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Dimension Utils
+ * \{ */
 
 void IMB_stereo3d_write_dimensions(const char mode,
                                    const bool is_squeezed,
@@ -566,7 +574,11 @@ void IMB_stereo3d_read_dimensions(const char mode,
   }
 }
 
-/**************************** un/squeeze frame ****************************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Un/Squeeze Frame
+ * \{ */
 
 static void imb_stereo3d_squeeze_ImBuf(ImBuf *ibuf,
                                        Stereo3dFormat *s3d,
@@ -667,7 +679,11 @@ static void imb_stereo3d_squeeze_rect(
   IMB_freeImBuf(ibuf);
 }
 
-/*************************** preparing to call the write functions **************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Preparing To Call The Write Functions
+ * \{ */
 
 static void imb_stereo3d_data_init(Stereo3DData *s3d_data,
                                    const bool is_float,
@@ -798,7 +814,11 @@ static void imb_stereo3d_write_doit(Stereo3DData *s3d_data, Stereo3dFormat *s3d)
   }
 }
 
-/******************************** reading stereo imbufs **********************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Reading Stereo ImBuf's
+ * \{ */
 
 static void imb_stereo3d_read_anaglyph(Stereo3DData *s3d, enum eStereo3dAnaglyphType mode)
 {
@@ -1249,7 +1269,11 @@ static void imb_stereo3d_read_topbottom(Stereo3DData *s3d)
   }
 }
 
-/*************************** preparing to call the read functions **************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Preparing To Call The Read Functions
+ * \{ */
 
 /* reading a stereo encoded ibuf (*left) and generating two ibufs from it (*left and *right) */
 void IMB_ImBufFromStereo3d(Stereo3dFormat *s3d,
@@ -1351,3 +1375,5 @@ static void imb_stereo3d_read_doit(Stereo3DData *s3d_data, Stereo3dFormat *s3d)
       break;
   }
 }
+
+/** \} */
diff --git a/source/blender/imbuf/intern/tiff.c b/source/blender/imbuf/intern/tiff.c
index 9d5d7f58335..0c235445920 100644
--- a/source/blender/imbuf/intern/tiff.c
+++ b/source/blender/imbuf/intern/tiff.c
@@ -57,9 +57,10 @@
 #  include "utfconv.h"
 #endif
 
-/***********************
- * Local declarations. *
- ***********************/
+/* -------------------------------------------------------------------- */
+/** \name Local Declarations
+ * \{ */
+
 /* Reading and writing of an in-memory TIFF file. */
 static tsize_t imb_tiff_ReadProc(thandle_t handle, tdata_t data, tsize_t n);
 static tsize_t imb_tiff_WriteProc(thandle_t handle, tdata_t data, tsize_t n);
@@ -69,17 +70,22 @@ static toff_t imb_tiff_SizeProc(thandle_t handle);
 static int imb_tiff_DummyMapProc(thandle_t fd, tdata_t *pbase, toff_t *psize);
 static void imb_tiff_DummyUnmapProc(thandle_t fd, tdata_t base, toff_t size);
 
-/* Structure for in-memory TIFF file. */
+/** Structure for in-memory TIFF file. */
 typedef struct ImbTIFFMemFile {
-  const unsigned char *mem; /* Location of first byte of TIFF file. */
-  toff_t offset;            /* Current offset within the file.      */
-  tsize_t size;             /* Size of the TIFF file.               */
+  /** Location of first byte of TIFF file. */
+  const unsigned char *mem;
+  /** Current offset within the file. */
+  toff_t offset;
+  /** Size of the TIFF file. */
+  tsize_t size;
 } ImbTIFFMemFile;
 #define IMB_TIFF_GET_MEMFILE(x) ((ImbTIFFMemFile *)(x))
 
-/*****************************
- * Function implementations. *
- *****************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Function Implementations
+ * \{ */
 
 static void imb_tiff_DummyUnmapProc(
     thandle_t fd,
@@ -111,8 +117,8 @@ static int imb_tiff_DummyMapProc(
  * Reads data from an in-memory TIFF file.
  *
  * \param handle: Handle of the TIFF file (pointer to #ImbTIFFMemFile).
- * \param data:   Buffer to contain data (treat as (void *)).
- * \param n:      Number of bytes to read.
+ * \param data: Buffer to contain data (treat as (void *)).
+ * \param n: Number of bytes to read.
  *
  * \return: Number of bytes actually read.
  *   0 = EOF.
@@ -174,8 +180,8 @@ static tsize_t imb_tiff_WriteProc(thandle_t handle, tdata_t data, tsize_t n)
 /**
  * Seeks to a new location in an in-memory TIFF file.
  *
- * \param handle: Handle of the TIFF file (pointer to ImbTIFFMemFile).
- * \param ofs:    Offset value (interpreted according to whence below).
+ * \param handle: Handle of the TIFF file (pointer to #ImbTIFFMemFile).
+ * \param ofs: Offset value (interpreted according to whence below).
  * \param whence: This can be one of three values:
  * SEEK_SET - The offset is set to ofs bytes.
  * SEEK_CUR - The offset is set to its current location plus ofs bytes.
@@ -226,7 +232,7 @@ static toff_t imb_tiff_SeekProc(thandle_t handle, toff_t ofs, int whence)
  *       are made to access the file after that point.  However, no such
  *       attempts should ever be made (in theory).
  *
- * \param handle: Handle of the TIFF file (pointer to ImbTIFFMemFile).
+ * \param handle: Handle of the TIFF file (pointer to #ImbTIFFMemFile).
  *
  * \return: 0
  */
@@ -288,6 +294,12 @@ static TIFF *imb_tiff_client_open(ImbTIFFMemFile *memFile, const unsigned char *
                         imb_tiff_DummyUnmapProc);
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Load TIFF
+ * \{ */
+
 /**
  * Checks whether a given memory buffer contains a TIFF file.
  *
@@ -539,10 +551,10 @@ void imb_inittiff(void)
 
 /**
  * Loads a TIFF file.
- * \param mem:   Memory containing the TIFF file.
- * \param size:  Size of the mem buffer.
+ * \param mem: Memory containing the TIFF file.
+ * \param size: Size of the mem buffer.
  * \param flags: If flags has IB_test set then the file is not actually loaded,
- *                but all other operations take place.
+ * but all other operations take place.
  *
  * \return: A newly allocated ImBuf structure if successful, otherwise NULL.
  */
@@ -726,17 +738,23 @@ void imb_loadtiletiff(
   TIFFClose(image);
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Save TIFF
+ * \{ */
+
 /**
  * Saves a TIFF file.
  *
- * ImBuf structures with 1, 3 or 4 bytes per pixel (GRAY, RGB, RGBA
+ * #ImBuf structures with 1, 3 or 4 bytes per pixel (GRAY, RGB, RGBA
  * respectively) are accepted, and interpreted correctly.  Note that the TIFF
  * convention is to use pre-multiplied alpha, which can be achieved within
  * Blender by setting "Premul" alpha handling.  Other alpha conventions are
  * not strictly correct, but are permitted anyhow.
  *
- * \param ibuf:  Image buffer.
- * \param name:  Name of the TIFF file to create.
+ * \param ibuf: Image buffer.
+ * \param name: Name of the TIFF file to create.
  * \param flags: Currently largely ignored.
  *
  * \return: 1 if the function is successful, 0 on failure.
@@ -958,3 +976,5 @@ int imb_savetiff(ImBuf *ibuf, const char *filepath, int flags)
   }
   return 1;
 }
+
+/** \} */