Cleanup: move public doc-strings into headers for 'render'

Ref T92709

11 files changed, 49 insertions, 91 deletions

diff --git a/source/blender/render/intern/bake.c b/source/blender/render/intern/bake.c
index 0f893ce8cd5..6794a9cd1ad 100644
--- a/source/blender/render/intern/bake.c
+++ b/source/blender/render/intern/bake.c
@@ -814,10 +814,6 @@ static void normal_compress(float out[3],
   }
 }
 
-/**
- * This function converts an object space normal map
- * to a tangent space normal map for a given low poly mesh.
- */
 void RE_bake_normal_world_to_tangent(const BakePixel pixel_array[],
                                      const size_t num_pixels,
                                      const int depth,
diff --git a/source/blender/render/intern/engine.c b/source/blender/render/intern/engine.c
index cb92b15f873..e1778897777 100644
--- a/source/blender/render/intern/engine.c
+++ b/source/blender/render/intern/engine.c
@@ -784,6 +784,7 @@ void RE_engine_frame_set(RenderEngine *engine, int frame, float subframe)
 }
 
 /* Bake */
+
 void RE_bake_engine_set_engine_parameters(Render *re, Main *bmain, Scene *scene)
 {
   re->scene = scene;
diff --git a/source/blender/render/intern/initrender.c b/source/blender/render/intern/initrender.c
index 2370d8e893b..f696b81cffb 100644
--- a/source/blender/render/intern/initrender.c
+++ b/source/blender/render/intern/initrender.c
@@ -121,7 +121,6 @@ static float filt_mitchell(float x) /* Mitchell & Netravali's two-param cubic */
   return 0.0f;
 }
 
-/* x ranges from -1 to 1 */
 float RE_filter_value(int type, float x)
 {
   float gaussfac = 1.6f;
@@ -163,6 +162,7 @@ float RE_filter_value(int type, float x)
 }
 
 /* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ */
+
 struct Object *RE_GetCamera(Render *re)
 {
   Object *camera = re->camera_override ? re->camera_override : re->scene->camera;
@@ -174,11 +174,6 @@ void RE_SetOverrideCamera(Render *re, Object *cam_ob)
   re->camera_override = cam_ob;
 }
 
-/**
- * Per render, there's one persistent view-plane. Parts will set their own view-planes.
- *
- * \note call this after #RE_InitState().
- */
 void RE_SetCamera(Render *re, Object *cam_ob)
 {
   CameraParams params;
@@ -205,7 +200,6 @@ void RE_GetCameraWindow(struct Render *re, struct Object *camera, float r_winmat
   copy_m4_m4(r_winmat, re->winmat);
 }
 
-/* Must be called after RE_GetCameraWindow(), does not change re->winmat. */
 void RE_GetCameraWindowWithOverscan(struct Render *re, float overscan, float r_winmat[4][4])
 {
   CameraParams params;
diff --git a/source/blender/render/intern/pipeline.c b/source/blender/render/intern/pipeline.c
index 1bf0dfe079c..a800361a41f 100644
--- a/source/blender/render/intern/pipeline.c
+++ b/source/blender/render/intern/pipeline.c
@@ -338,7 +338,6 @@ Render *RE_GetRender(const char *name)
   return re;
 }
 
-/* if you want to know exactly what has been done */
 RenderResult *RE_AcquireResultRead(Render *re)
 {
   if (re) {
@@ -383,7 +382,6 @@ void RE_ReleaseResult(Render *re)
   }
 }
 
-/* displist.c util.... */
 Scene *RE_GetScene(Render *re)
 {
   if (re) {
@@ -399,11 +397,6 @@ void RE_SetScene(Render *re, Scene *sce)
   }
 }
 
-/**
- * Same as #RE_AcquireResultImage but creating the necessary views to store the result
- * fill provided result struct with a copy of thew views of what is done so far the
- * #RenderResult.views #ListBase needs to be freed after with #RE_ReleaseResultImageViews
- */
 void RE_AcquireResultImageViews(Render *re, RenderResult *rr)
 {
   memset(rr, 0, sizeof(RenderResult));
@@ -449,7 +442,6 @@ void RE_AcquireResultImageViews(Render *re, RenderResult *rr)
   }
 }
 
-/* clear temporary renderresult struct */
 void RE_ReleaseResultImageViews(Render *re, RenderResult *rr)
 {
   if (re) {
@@ -460,9 +452,6 @@ void RE_ReleaseResultImageViews(Render *re, RenderResult *rr)
   }
 }
 
-/* fill provided result struct with what's currently active or done */
-/* this RenderResult struct is the only exception to the rule of a RenderResult */
-/* always having at least one RenderView */
 void RE_AcquireResultImage(Render *re, RenderResult *rr, const int view_id)
 {
   memset(rr, 0, sizeof(RenderResult));
@@ -516,7 +505,6 @@ void RE_ReleaseResultImage(Render *re)
   }
 }
 
-/* caller is responsible for allocating rect in correct size! */
 void RE_ResultGet32(Render *re, unsigned int *rect)
 {
   RenderResult rres;
@@ -533,8 +521,6 @@ void RE_ResultGet32(Render *re, unsigned int *rect)
   RE_ReleaseResultImageViews(re, &rres);
 }
 
-/* caller is responsible for allocating rect in correct size! */
-/* Only for acquired results, for lock */
 void RE_AcquiredResultGet32(Render *re,
                             RenderResult *result,
                             unsigned int *rect,
@@ -603,8 +589,6 @@ Render *RE_NewSceneRender(const Scene *scene)
   return RE_NewRender(render_name);
 }
 
-/* called for new renders and when finishing rendering so
- * we always have valid callbacks on a render */
 void RE_InitRenderCB(Render *re)
 {
   /* set default empty callbacks */
@@ -624,7 +608,6 @@ void RE_InitRenderCB(Render *re)
   re->dih = re->dch = re->duh = re->sdh = re->prh = re->tbh = NULL;
 }
 
-/* only call this while you know it will remove the link too */
 void RE_FreeRender(Render *re)
 {
   if (re->engine) {
@@ -655,7 +638,6 @@ void RE_FreeRender(Render *re)
   MEM_freeN(re);
 }
 
-/* exit blender */
 void RE_FreeAllRender(void)
 {
   while (RenderGlobal.renderlist.first) {
@@ -668,7 +650,6 @@ void RE_FreeAllRender(void)
 #endif
 }
 
-/* on file load, free all re */
 void RE_FreeAllRenderResults(void)
 {
   Render *re;
@@ -769,8 +750,6 @@ void render_copy_renderdata(RenderData *to, RenderData *from)
   BKE_curvemapping_copy_data(&to->mblur_shutter_curve, &from->mblur_shutter_curve);
 }
 
-/* what doesn't change during entire render sequence */
-/* disprect is optional, if NULL it assumes full window render */
 void RE_InitState(Render *re,
                   Render *source,
                   RenderData *rd,
@@ -874,8 +853,6 @@ void RE_InitState(Render *re,
   RE_point_density_fix_linking();
 }
 
-/* update some variables that can be animated, and otherwise wouldn't be due to
- * RenderData getting copied once at the start of animation render */
 void render_update_anim_renderdata(Render *re, RenderData *rd, ListBase *render_layers)
 {
   /* filter */
@@ -897,7 +874,6 @@ void render_update_anim_renderdata(Render *re, RenderData *rd, ListBase *render_
   BLI_duplicatelist(&re->r.views, &rd->views);
 }
 
-/* image and movie output has to move to either imbuf or kernel */
 void RE_display_init_cb(Render *re, void *handle, void (*f)(void *handle, RenderResult *rr))
 {
   re->display_init = f;
@@ -1834,7 +1810,6 @@ static void render_pipeline_free(Render *re)
   }
 }
 
-/* general Blender frame render call */
 void RE_RenderFrame(Render *re,
                     Main *bmain,
                     Scene *scene,
@@ -2280,7 +2255,6 @@ static void re_movie_free_all(Render *re, bMovieHandle *mh, int totvideos)
   MEM_SAFE_FREE(re->movie_ctx_arr);
 }
 
-/* saves images to disk */
 void RE_RenderAnim(Render *re,
                    Main *bmain,
                    Scene *scene,
@@ -2583,7 +2557,6 @@ void RE_PreviewRender(Render *re, Main *bmain, Scene *sce)
 
 /* NOTE: repeated win/disprect calc... solve that nicer, also in compo. */
 
-/* only the temp file! */
 bool RE_ReadRenderResult(Scene *scene, Scene *scenode)
 {
   Render *re;
@@ -2635,8 +2608,6 @@ void RE_init_threadcount(Render *re)
   re->r.threads = BKE_render_num_threads(&re->r);
 }
 
-/* loads in image into a result, size must match
- * x/y offsets are only used on a partial copy when dimensions don't match */
 void RE_layer_load_from_file(
     RenderLayer *layer, ReportList *reports, const char *filename, int x, int y)
 {
@@ -2712,7 +2683,6 @@ void RE_result_load_from_file(RenderResult *result, ReportList *reports, const c
   }
 }
 
-/* Used in the interface to decide whether to show layers or passes. */
 bool RE_layers_have_name(struct RenderResult *rr)
 {
   switch (BLI_listbase_count_at_most(&rr->layers, 2)) {
@@ -2754,7 +2724,6 @@ RenderPass *RE_pass_find_by_name(volatile RenderLayer *rl, const char *name, con
   return rp;
 }
 
-/* Only provided for API compatibility, don't use this in new code! */
 RenderPass *RE_pass_find_by_type(volatile RenderLayer *rl, int passtype, const char *viewname)
 {
 #define CHECK_PASS(NAME) \
@@ -2793,7 +2762,6 @@ RenderPass *RE_pass_find_by_type(volatile RenderLayer *rl, int passtype, const c
   return NULL;
 }
 
-/* create a renderlayer and renderpass for grease pencil layer */
 RenderPass *RE_create_gp_pass(RenderResult *rr, const char *layername, const char *viewname)
 {
   RenderLayer *rl = BLI_findstring(&rr->layers, layername, offsetof(RenderLayer, name));
diff --git a/source/blender/render/intern/pipeline.h b/source/blender/render/intern/pipeline.h
index 062df59bfd3..ba2e382619d 100644
--- a/source/blender/render/intern/pipeline.h
+++ b/source/blender/render/intern/pipeline.h
@@ -34,6 +34,10 @@ extern "C" {
 #endif
 
 struct RenderLayer *render_get_active_layer(struct Render *re, struct RenderResult *rr);
+/**
+ * Update some variables that can be animated, and otherwise wouldn't be due to
+ * #RenderData getting copied once at the start of animation render.
+ */
 void render_update_anim_renderdata(struct Render *re,
                                    struct RenderData *rd,
                                    struct ListBase *render_layers);
diff --git a/source/blender/render/intern/render_result.c b/source/blender/render/intern/render_result.c
index 0681bcd9aa5..a21351539f6 100644
--- a/source/blender/render/intern/render_result.c
+++ b/source/blender/render/intern/render_result.c
@@ -126,7 +126,6 @@ void render_result_free(RenderResult *rr)
   MEM_freeN(rr);
 }
 
-/** Version that's compatible with full-sample buffers. */
 void render_result_free_list(ListBase *lb, RenderResult *rr)
 {
   RenderResult *rrnext;
@@ -144,7 +143,6 @@ void render_result_free_list(ListBase *lb, RenderResult *rr)
 
 /********************************* multiview *************************************/
 
-/* create a new views Listbase in rr without duplicating the memory pointers */
 void render_result_views_shallowcopy(RenderResult *dst, RenderResult *src)
 {
   RenderView *rview;
@@ -166,7 +164,6 @@ void render_result_views_shallowcopy(RenderResult *dst, RenderResult *src)
   }
 }
 
-/* free the views created temporarily */
 void render_result_views_shallowdelete(RenderResult *rr)
 {
   if (rr == NULL) {
@@ -286,10 +283,6 @@ RenderPass *render_layer_add_pass(RenderResult *rr,
   return rpass;
 }
 
-/* called by main render as well for parts */
-/* will read info from Render *re to define layers */
-/* called in threads */
-/* re->winx,winy is coordinate space of entire image, partrct the part within */
 RenderResult *render_result_new(Render *re,
                                 rcti *partrct,
                                 const char *layername,
@@ -733,10 +726,6 @@ static int order_render_passes(const void *a, const void *b)
   return (rpa->view_id < rpb->view_id);
 }
 
-/**
- * From imbuf, if a handle was returned and
- * it's not a single-layer multi-view we convert this to render result.
- */
 RenderResult *render_result_new_from_exr(
     void *exrhandle, const char *colorspace, bool predivide, int rectx, int recty)
 {
@@ -837,9 +826,6 @@ static void do_merge_tile(
   }
 }
 
-/* used when rendering to a full buffer, or when reading the exr part-layer-pass file */
-/* no test happens here if it fits... we also assume layers are in sync */
-/* is used within threads */
 void render_result_merge(RenderResult *rr, RenderResult *rrpart)
 {
   RenderLayer *rl, *rlp;
@@ -869,8 +855,6 @@ void render_result_merge(RenderResult *rr, RenderResult *rrpart)
   }
 }
 
-/* Called from the UI and render pipeline, to save multilayer and multiview
- * images, optionally isolating a specific, view, layer or RGBA/Z pass. */
 bool RE_WriteRenderResult(ReportList *reports,
                           RenderResult *rr,
                           const char *filename,
@@ -1040,7 +1024,6 @@ void render_result_single_layer_begin(Render *re)
   re->result = NULL;
 }
 
-/* if scemode is R_SINGLE_LAYER, at end of rendering, merge the both render results */
 void render_result_single_layer_end(Render *re)
 {
   ViewLayer *view_layer;
@@ -1085,7 +1068,6 @@ void render_result_single_layer_end(Render *re)
   re->pushedresult = NULL;
 }
 
-/* called for reading temp files, and for external engines */
 int render_result_exr_file_read_path(RenderResult *rr,
                                      RenderLayer *rl_single,
                                      const char *filepath)
@@ -1184,7 +1166,6 @@ void render_result_exr_file_cache_write(Render *re)
   RE_WriteRenderResult(NULL, rr, str, NULL, NULL, -1);
 }
 
-/* For cache, makes exact copy of render result */
 bool render_result_exr_file_cache_read(Render *re)
 {
   /* File path to cache. */
diff --git a/source/blender/render/intern/render_result.h b/source/blender/render/intern/render_result.h
index 34b8143869c..ede0a0d21ea 100644
--- a/source/blender/render/intern/render_result.h
+++ b/source/blender/render/intern/render_result.h
@@ -46,6 +46,12 @@ extern "C" {
 
 /* New */
 
+/**
+ * Called by main render as well for parts will read info from Render *re to define layers.
+ * \note Called in threads.
+ *
+ * `re->winx`, `re->winy` is coordinate space of entire image, `partrct` the part within.
+ */
 struct RenderResult *render_result_new(struct Render *re,
                                        struct rcti *partrct,
                                        const char *layername,
@@ -53,6 +59,10 @@ struct RenderResult *render_result_new(struct Render *re,
 
 void render_result_passes_allocated_ensure(struct RenderResult *rr);
 
+/**
+ * From imbuf, if a handle was returned and
+ * it's not a single-layer multi-view we convert this to render result.
+ */
 struct RenderResult *render_result_new_from_exr(
     void *exrhandle, const char *colorspace, bool predivide, int rectx, int recty);
 
@@ -61,6 +71,11 @@ void render_result_views_new(struct RenderResult *rr, const struct RenderData *r
 
 /* Merge */
 
+/**
+ * Used when rendering to a full buffer, or when reading the EXR part-layer-pass file.
+ * no test happens here if it fits... we also assume layers are in sync.
+ * \note Is used within threads.
+ */
 void render_result_merge(struct RenderResult *rr, struct RenderResult *rrpart);
 
 /* Add Passes */
@@ -70,14 +85,22 @@ void render_result_clone_passes(struct Render *re, struct RenderResult *rr, cons
 /* Free */
 
 void render_result_free(struct RenderResult *rr);
+/**
+ * Version that's compatible with full-sample buffers.
+ */
 void render_result_free_list(struct ListBase *lb, struct RenderResult *rr);
 
 /* Single Layer Render */
 
 void render_result_single_layer_begin(struct Render *re);
+/**
+ * If #RenderData.scemode is #R_SINGLE_LAYER, at end of rendering, merge the both render results.
+ */
 void render_result_single_layer_end(struct Render *re);
 
-/* render pass wrapper for gpencil */
+/**
+ * Render pass wrapper for grease-pencil.
+ */
 struct RenderPass *render_layer_add_pass(struct RenderResult *rr,
                                          struct RenderLayer *rl,
                                          int channels,
@@ -86,6 +109,9 @@ struct RenderPass *render_layer_add_pass(struct RenderResult *rr,
                                          const char *chan_id,
                                          const bool allocate);
 
+/**
+ * Called for reading temp files, and for external engines.
+ */
 int render_result_exr_file_read_path(struct RenderResult *rr,
                                      struct RenderLayer *rl_single,
                                      const char *filepath);
@@ -93,6 +119,9 @@ int render_result_exr_file_read_path(struct RenderResult *rr,
 /* EXR cache */
 
 void render_result_exr_file_cache_write(struct Render *re);
+/**
+ * For cache, makes exact copy of render result.
+ */
 bool render_result_exr_file_cache_read(struct Render *re);
 
 /* Combined Pixel Rect */
@@ -110,7 +139,13 @@ void render_result_rect_get_pixels(struct RenderResult *rr,
                                    const struct ColorManagedDisplaySettings *display_settings,
                                    const int view_id);
 
+/**
+ * Create a new views #ListBase in rr without duplicating the memory pointers.
+ */
 void render_result_views_shallowcopy(struct RenderResult *dst, struct RenderResult *src);
+/**
+ * Free the views created temporarily.
+ */
 void render_result_views_shallowdelete(struct RenderResult *rr);
 bool render_result_has_views(const struct RenderResult *rr);
 
diff --git a/source/blender/render/intern/texture_pointdensity.c b/source/blender/render/intern/texture_pointdensity.c
index 06dd570ce2c..8ca1decdea7 100644
--- a/source/blender/render/intern/texture_pointdensity.c
+++ b/source/blender/render/intern/texture_pointdensity.c
@@ -928,9 +928,6 @@ static void point_density_sample_func(void *__restrict data_v,
   }
 }
 
-/* NOTE 1: Requires RE_point_density_cache() to be called first.
- * NOTE 2: Frees point density structure after sampling.
- */
 void RE_point_density_sample(Depsgraph *depsgraph,
                              PointDensity *pd,
                              const int resolution,
diff --git a/source/blender/render/intern/texture_procedural.c b/source/blender/render/intern/texture_procedural.c
index 5a94bc09b93..f563cb9f84a 100644
--- a/source/blender/render/intern/texture_procedural.c
+++ b/source/blender/render/intern/texture_procedural.c
@@ -1399,9 +1399,6 @@ static int multitex_nodes_intern(Tex *tex,
                   use_nodes);
 }
 
-/* this is called from the shader and texture nodes
- * Use it from render pipeline only!
- */
 int multitex_nodes(Tex *tex,
                    const float texvec[3],
                    float dxt[3],
@@ -1429,13 +1426,6 @@ int multitex_nodes(Tex *tex,
                                true);
 }
 
-/**
- * \warning if the texres's values are not declared zero,
- * check the return value to be sure the color values are set before using the r/g/b values,
- * otherwise you may use uninitialized values - Campbell
- *
- * Use it for stuff which is out of render pipeline.
- */
 int multitex_ext(Tex *tex,
                  float texvec[3],
                  float dxt[3],
@@ -1463,10 +1453,6 @@ int multitex_ext(Tex *tex,
                                true);
 }
 
-/* extern-tex doesn't support nodes (ntreeBeginExec() can't be called when rendering is going on)\
- *
- * Use it for stuff which is out of render pipeline.
- */
 int multitex_ext_safe(Tex *tex,
                       const float texvec[3],
                       TexResult *texres,
@@ -1492,8 +1478,6 @@ int multitex_ext_safe(Tex *tex,
 
 /* ------------------------------------------------------------------------- */
 
-/* in = destination, tex = texture, out = previous color */
-/* fact = texture strength, facg = button strength value */
 void texture_rgb_blend(
     float in[3], const float tex[3], const float out[3], float fact, float facg, int blendtype)
 {
@@ -1722,11 +1706,6 @@ float texture_value_blend(float tex, float out, float fact, float facg, int blen
 
 /* ------------------------------------------------------------------------- */
 
-/**
- * \param pool: Thread pool, may be NULL.
- *
- * \return True if the texture has color, otherwise false.
- */
 bool RE_texture_evaluate(const MTex *mtex,
                          const float vec[3],
                          const int thread,
diff --git a/source/blender/render/intern/zbuf.c b/source/blender/render/intern/zbuf.c
index 726124871ee..1812a492ac0 100644
--- a/source/blender/render/intern/zbuf.c
+++ b/source/blender/render/intern/zbuf.c
@@ -41,7 +41,6 @@
 
 /* ****************** Spans ******************************* */
 
-/* each zbuffer has coordinates transformed to local rect coordinates, so we can simply clip */
 void zbuf_alloc_span(ZSpan *zspan, int rectx, int recty)
 {
   memset(zspan, 0, sizeof(ZSpan));
@@ -170,9 +169,6 @@ static void zbuf_add_to_span(ZSpan *zspan, const float v1[2], const float v2[2])
 /* Functions                                                 */
 /*-----------------------------------------------------------*/
 
-/* Scan-convert for strand triangles, calls function for each x, y coordinate
- * and gives UV barycentrics and z. */
-
 void zspan_scanconvert(ZSpan *zspan,
                        void *handle,
                        float *v1,
diff --git a/source/blender/render/intern/zbuf.h b/source/blender/render/intern/zbuf.h
index 41fa15c594f..c5108a9d6a7 100644
--- a/source/blender/render/intern/zbuf.h
+++ b/source/blender/render/intern/zbuf.h
@@ -33,9 +33,16 @@ typedef struct ZSpan {
   float *span1, *span2;
 } ZSpan;
 
+/**
+ * Each Z-buffer has coordinates transformed to local rect coordinates, so we can simply clip.
+ */
 void zbuf_alloc_span(struct ZSpan *zspan, int rectx, int recty);
 void zbuf_free_span(struct ZSpan *zspan);
 
+/**
+ * Scan-convert for strand triangles, calls function for each x, y coordinate
+ * and gives UV barycentrics and z.
+ */
 void zspan_scanconvert(struct ZSpan *zspan,
                        void *handle,
                        float *v1,