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

Ref T92709

1 files changed, 216 insertions, 26 deletions

diff --git a/source/blender/draw/intern/DRW_render.h b/source/blender/draw/intern/DRW_render.h
index 6491f5ca411..961aed3f284 100644
--- a/source/blender/draw/intern/DRW_render.h
+++ b/source/blender/draw/intern/DRW_render.h
@@ -147,9 +147,11 @@ typedef enum {
   DRW_TEX_MIPMAP = (1 << 3),
 } DRWTextureFlag;
 
-/* Textures from DRW_texture_pool_query_* have the options
- * DRW_TEX_FILTER for color float textures, and no options
- * for depth textures and integer textures. */
+/**
+ * Textures from `DRW_texture_pool_query_*` have the options
+ * #DRW_TEX_FILTER for color float textures, and no options
+ * for depth textures and integer textures.
+ */
 struct GPUTexture *DRW_texture_pool_query_2d(int w,
                                              int h,
                                              eGPUTextureFormat format,
@@ -288,11 +290,17 @@ void DRW_shader_free(struct GPUShader *shader);
 
 DRWShaderLibrary *DRW_shader_library_create(void);
 
-/* Warning: Each library must be added after all its dependencies. */
+/**
+ * \warning Each library must be added after all its dependencies.
+ */
 void DRW_shader_library_add_file(DRWShaderLibrary *lib, char *lib_code, const char *lib_name);
 #define DRW_SHADER_LIB_ADD(lib, lib_name) \
   DRW_shader_library_add_file(lib, datatoc_##lib_name##_glsl, STRINGIFY(lib_name) ".glsl")
 
+/**
+ * \return an allocN'ed string containing the shader code with its dependencies prepended.
+ * Caller must free the string with #MEM_freeN after use.
+ */
 char *DRW_shader_library_create_shader_string(const DRWShaderLibrary *lib,
                                               const char *shader_code);
 
@@ -306,11 +314,14 @@ void DRW_shader_library_free(DRWShaderLibrary *lib);
   } while (0)
 
 /* Batches */
-/* DRWState is a bitmask that stores the current render state and the desired render state. Based
+
+/**
+ * DRWState is a bit-mask that stores the current render state and the desired render state. Based
  * on the differences the minimum state changes can be invoked to setup the desired render state.
  *
  * The Write Stencil, Stencil test, Depth test and Blend state options are mutual exclusive
- * therefore they aren't ordered as a bit mask. */
+ * therefore they aren't ordered as a bit mask.
+ */
 typedef enum {
   /** Write mask */
   DRW_STATE_WRITE_DEPTH = (1 << 0),
@@ -408,7 +419,9 @@ DRWShadingGroup *DRW_shgroup_transform_feedback_create(struct GPUShader *shader,
 
 void DRW_shgroup_add_material_resources(DRWShadingGroup *grp, struct GPUMaterial *material);
 
-/* return final visibility */
+/**
+ * Return final visibility.
+ */
 typedef bool(DRWCallVisibilityFn)(bool vis_in, void *user_data);
 
 void DRW_shgroup_call_ex(DRWShadingGroup *shgroup,
@@ -418,11 +431,15 @@ void DRW_shgroup_call_ex(DRWShadingGroup *shgroup,
                          bool bypass_culling,
                          void *user_data);
 
-/* If ob is NULL, unit modelmatrix is assumed and culling is bypassed. */
+/**
+ * If ob is NULL, unit modelmatrix is assumed and culling is bypassed.
+ */
 #define DRW_shgroup_call(shgroup, geom, ob) \
   DRW_shgroup_call_ex(shgroup, ob, NULL, geom, false, NULL)
 
-/* Same as DRW_shgroup_call but override the obmat. Not culled. */
+/**
+ * Same as #DRW_shgroup_call but override the `obmat`. Not culled.
+ */
 #define DRW_shgroup_call_obmat(shgroup, geom, obmat) \
   DRW_shgroup_call_ex(shgroup, NULL, obmat, geom, false, NULL)
 
@@ -431,12 +448,17 @@ void DRW_shgroup_call_ex(DRWShadingGroup *shgroup,
 #define DRW_shgroup_call_with_callback(shgroup, geom, ob, user_data) \
   DRW_shgroup_call_ex(shgroup, ob, NULL, geom, false, user_data)
 
-/* Same as DRW_shgroup_call but bypass culling even if ob is not NULL. */
+/**
+ * Same as #DRW_shgroup_call but bypass culling even if ob is not NULL.
+ */
 #define DRW_shgroup_call_no_cull(shgroup, geom, ob) \
   DRW_shgroup_call_ex(shgroup, ob, NULL, geom, true, NULL)
 
 void DRW_shgroup_call_range(
     DRWShadingGroup *shgroup, Object *ob, struct GPUBatch *geom, uint v_sta, uint v_ct);
+/**
+ * A count of 0 instance will use the default number of instance in the batch.
+ */
 void DRW_shgroup_call_instance_range(
     DRWShadingGroup *shgroup, Object *ob, struct GPUBatch *geom, uint i_sta, uint i_ct);
 
@@ -447,12 +469,17 @@ void DRW_shgroup_call_compute(DRWShadingGroup *shgroup,
 void DRW_shgroup_call_procedural_points(DRWShadingGroup *sh, Object *ob, uint point_count);
 void DRW_shgroup_call_procedural_lines(DRWShadingGroup *sh, Object *ob, uint line_count);
 void DRW_shgroup_call_procedural_triangles(DRWShadingGroup *sh, Object *ob, uint tri_count);
-/* Warning: Only use with Shaders that have IN_PLACE_INSTANCES defined. */
+/**
+ * \warning Only use with Shaders that have `IN_PLACE_INSTANCES` defined.
+ * TODO: Should be removed.
+ */
 void DRW_shgroup_call_instances(DRWShadingGroup *shgroup,
                                 Object *ob,
                                 struct GPUBatch *geom,
                                 uint count);
-/* Warning: Only use with Shaders that have INSTANCED_ATTR defined. */
+/**
+ * \warning Only use with Shaders that have INSTANCED_ATTR defined.
+ */
 void DRW_shgroup_call_instances_with_attrs(DRWShadingGroup *shgroup,
                                            Object *ob,
                                            struct GPUBatch *geom,
@@ -477,13 +504,20 @@ void DRW_buffer_add_entry_array(DRWCallBuffer *callbuf, const void *attr[], uint
     DRW_buffer_add_entry_array(buffer, array, (sizeof(array) / sizeof(*array))); \
   } while (0)
 
-/* Can only be called during iter phase. */
+/**
+ * Can only be called during iteration phase.
+ */
 uint32_t DRW_object_resource_id_get(Object *ob);
 
+/**
+ * State is added to #Pass.state while drawing.
+ * Use to temporarily enable draw options.
+ */
 void DRW_shgroup_state_enable(DRWShadingGroup *shgroup, DRWState state);
 void DRW_shgroup_state_disable(DRWShadingGroup *shgroup, DRWState state);
 
-/* Reminders:
+/**
+ * Reminders:
  * - (compare_mask & reference) is what is tested against (compare_mask & stencil_value)
  *   stencil_value being the value stored in the stencil buffer.
  * - (write-mask & reference) is what gets written if the test condition is fulfilled.
@@ -492,10 +526,14 @@ void DRW_shgroup_stencil_set(DRWShadingGroup *shgroup,
                              uint write_mask,
                              uint reference,
                              uint compare_mask);
-/* TODO: remove this function. Obsolete version. mask is actually reference value. */
+/**
+ * TODO: remove this function. Obsolete version. mask is actually reference value.
+ */
 void DRW_shgroup_stencil_mask(DRWShadingGroup *shgroup, uint mask);
 
-/* Issue a clear command. */
+/**
+ * Issue a clear command.
+ */
 void DRW_shgroup_clear_framebuffer(DRWShadingGroup *shgroup,
                                    eGPUFrameBufferBits channels,
                                    uchar r,
@@ -541,7 +579,6 @@ void DRW_shgroup_uniform_vec4(DRWShadingGroup *shgroup,
                               const char *name,
                               const float *value,
                               int arraysize);
-/* Boolean are expected to be 4bytes longs for opengl! */
 void DRW_shgroup_uniform_bool(DRWShadingGroup *shgroup,
                               const char *name,
                               const int *value,
@@ -564,10 +601,14 @@ void DRW_shgroup_uniform_ivec4(DRWShadingGroup *shgroup,
                                int arraysize);
 void DRW_shgroup_uniform_mat3(DRWShadingGroup *shgroup, const char *name, const float (*value)[3]);
 void DRW_shgroup_uniform_mat4(DRWShadingGroup *shgroup, const char *name, const float (*value)[4]);
-/* Only to be used when image load store is supported (GPU_shader_image_load_store_support()). */
+/**
+ * Only to be used when image load store is supported (#GPU_shader_image_load_store_support()).
+ */
 void DRW_shgroup_uniform_image(DRWShadingGroup *shgroup, const char *name, const GPUTexture *tex);
 void DRW_shgroup_uniform_image_ref(DRWShadingGroup *shgroup, const char *name, GPUTexture **tex);
+
 /* Store value instead of referencing it. */
+
 void DRW_shgroup_uniform_int_copy(DRWShadingGroup *shgroup, const char *name, const int value);
 void DRW_shgroup_uniform_ivec2_copy(DRWShadingGroup *shgroup, const char *name, const int *value);
 void DRW_shgroup_uniform_ivec3_copy(DRWShadingGroup *shgroup, const char *name, const int *value);
@@ -587,14 +628,29 @@ void DRW_shgroup_vertex_buffer(DRWShadingGroup *shgroup,
 
 bool DRW_shgroup_is_empty(DRWShadingGroup *shgroup);
 
-/* Passes */
+/* Passes. */
+
 DRWPass *DRW_pass_create(const char *name, DRWState state);
+/**
+ * Create an instance of the original pass that will execute the same drawcalls but with its own
+ * #DRWState.
+ */
 DRWPass *DRW_pass_create_instance(const char *name, DRWPass *original, DRWState state);
+/**
+ * Link two passes so that they are both rendered if the first one is being drawn.
+ */
 void DRW_pass_link(DRWPass *first, DRWPass *second);
 void DRW_pass_foreach_shgroup(DRWPass *pass,
                               void (*callback)(void *userData, DRWShadingGroup *shgroup),
                               void *userData);
+/**
+ * Sort Shading groups by decreasing Z of their first draw call.
+ * This is useful for order dependent effect such as alpha-blending.
+ */
 void DRW_pass_sort_shgroup_z(DRWPass *pass);
+/**
+ * Reverse Shading group submission order.
+ */
 void DRW_pass_sort_shgroup_reverse(DRWPass *pass);
 
 bool DRW_pass_is_empty(DRWPass *pass);
@@ -603,56 +659,113 @@ bool DRW_pass_is_empty(DRWPass *pass);
 #define DRW_PASS_INSTANCE_CREATE(pass, original, state) \
   (pass = DRW_pass_create_instance(#pass, (original), state))
 
-/* Views */
+/* Views. */
+
+/**
+ * Create a view with culling.
+ */
 DRWView *DRW_view_create(const float viewmat[4][4],
                          const float winmat[4][4],
                          const float (*culling_viewmat)[4],
                          const float (*culling_winmat)[4],
                          DRWCallVisibilityFn *visibility_fn);
+/**
+ * Create a view with culling done by another view.
+ */
 DRWView *DRW_view_create_sub(const DRWView *parent_view,
                              const float viewmat[4][4],
                              const float winmat[4][4]);
 
+/**
+ * Update matrices of a view created with #DRW_view_create.
+ */
 void DRW_view_update(DRWView *view,
                      const float viewmat[4][4],
                      const float winmat[4][4],
                      const float (*culling_viewmat)[4],
                      const float (*culling_winmat)[4]);
+/**
+ * Update matrices of a view created with #DRW_view_create_sub.
+ */
 void DRW_view_update_sub(DRWView *view, const float viewmat[4][4], const float winmat[4][4]);
 
+/**
+ * \return default view if it is a viewport render.
+ */
 const DRWView *DRW_view_default_get(void);
+/**
+ * MUST only be called once per render and only in render mode. Sets default view.
+ */
 void DRW_view_default_set(DRWView *view);
+/**
+ * \warning Only use in render AND only if you are going to set view_default again.
+ */
 void DRW_view_reset(void);
+/**
+ * Set active view for rendering.
+ */
 void DRW_view_set_active(DRWView *view);
 const DRWView *DRW_view_get_active(void);
 
+/**
+ * This only works if DRWPasses have been tagged with DRW_STATE_CLIP_PLANES,
+ * and if the shaders have support for it (see usage of gl_ClipDistance).
+ * \note planes must be in world space.
+ */
 void DRW_view_clip_planes_set(DRWView *view, float (*planes)[4], int plane_len);
 void DRW_view_camtexco_set(DRWView *view, float texco[4]);
 
 /* For all getters, if view is NULL, default view is assumed. */
+
 void DRW_view_winmat_get(const DRWView *view, float mat[4][4], bool inverse);
 void DRW_view_viewmat_get(const DRWView *view, float mat[4][4], bool inverse);
 void DRW_view_persmat_get(const DRWView *view, float mat[4][4], bool inverse);
 
+/**
+ * \return world space frustum corners.
+ */
 void DRW_view_frustum_corners_get(const DRWView *view, BoundBox *corners);
+/**
+ * \return world space frustum sides as planes.
+ * See #draw_frustum_culling_planes_calc() for the plane order.
+ */
 void DRW_view_frustum_planes_get(const DRWView *view, float planes[6][4]);
 
-/* These are in view-space, so negative if in perspective.
- * Extract near and far clip distance from the projection matrix. */
+/**
+ * These are in view-space, so negative if in perspective.
+ * Extract near and far clip distance from the projection matrix.
+ */
 float DRW_view_near_distance_get(const DRWView *view);
 float DRW_view_far_distance_get(const DRWView *view);
 bool DRW_view_is_persp_get(const DRWView *view);
 
 /* Culling, return true if object is inside view frustum. */
+
+/**
+ * \return True if the given BoundSphere intersect the current view frustum.
+ * bsphere must be in world space.
+ */
 bool DRW_culling_sphere_test(const DRWView *view, const BoundSphere *bsphere);
+/**
+ * \return True if the given BoundBox intersect the current view frustum.
+ * bbox must be in world space.
+ */
 bool DRW_culling_box_test(const DRWView *view, const BoundBox *bbox);
+/**
+ * \return True if the view frustum is inside or intersect the given plane.
+ * plane must be in world space.
+ */
 bool DRW_culling_plane_test(const DRWView *view, const float plane[4]);
+/**
+ * Return True if the given box intersect the current view frustum.
+ * This function will have to be replaced when world space bb per objects is implemented.
+ */
 bool DRW_culling_min_max_test(const DRWView *view, float obmat[4][4], float min[3], float max[3]);
 
 void DRW_culling_frustum_corners_get(const DRWView *view, BoundBox *corners);
 void DRW_culling_frustum_planes_get(const DRWView *view, float planes[6][4]);
 
-/* Viewport */
+/* Viewport. */
 
 const float *DRW_viewport_size_get(void);
 const float *DRW_viewport_invert_size_get(void);
@@ -672,18 +785,35 @@ void DRW_render_object_iter(void *vedata,
                                              struct Object *ob,
                                              struct RenderEngine *engine,
                                              struct Depsgraph *depsgraph));
+/**
+ * Must run after all instance datas have been added.
+ */
 void DRW_render_instance_buffer_finish(void);
+/**
+ * \warning Changing frame might free the #ViewLayerEngineData.
+ */
 void DRW_render_set_time(struct RenderEngine *engine,
                          struct Depsgraph *depsgraph,
                          int frame,
                          float subframe);
+/**
+ * \warning only use for custom pipeline. 99% of the time, you don't want to use this.
+ */
 void DRW_render_viewport_size_set(const int size[2]);
 
+/**
+ * Assume a valid GL context is bound (and that the gl_context_mutex has been acquired).
+ * This function only setup DST and execute the given function.
+ * \warning similar to DRW_render_to_image you cannot use default lists (dfbl & dtxl).
+ */
 void DRW_custom_pipeline(DrawEngineType *draw_engine_type,
                          struct Depsgraph *depsgraph,
                          void (*callback)(void *vedata, void *user_data),
                          void *user_data);
 
+/**
+ * Used when the render engine want to redo another cache populate inside the same render frame.
+ */
 void DRW_cache_restart(void);
 
 /* ViewLayers */
@@ -701,11 +831,26 @@ DrawData *DRW_drawdata_ensure(ID *id,
                               size_t size,
                               DrawDataInitCb init_cb,
                               DrawDataFreeCb free_cb);
+/**
+ * Return NULL if not a dupli or a pointer of pointer to the engine data.
+ */
 void **DRW_duplidata_get(void *vedata);
 
-/* Settings */
+/* Settings. */
+
 bool DRW_object_is_renderable(const struct Object *ob);
+/**
+ * Does `ob` needs to be rendered in edit mode.
+ *
+ * When using duplicate linked meshes, objects that are not in edit-mode will be drawn as
+ * it is in edit mode, when another object with the same mesh is in edit mode.
+ * This will not be the case when one of the objects are influenced by modifiers.
+ */
 bool DRW_object_is_in_edit_mode(const struct Object *ob);
+/**
+ * Return whether this object is visible depending if
+ * we are rendering or drawing in the viewport.
+ */
 int DRW_object_visibility_in_active_context(const struct Object *ob);
 bool DRW_object_is_flat_normal(const struct Object *ob);
 bool DRW_object_use_hide_faces(const struct Object *ob);
@@ -717,31 +862,76 @@ struct Object *DRW_object_get_dupli_parent(const struct Object *ob);
 struct DupliObject *DRW_object_get_dupli(const struct Object *ob);
 
 /* Draw commands */
+
 void DRW_draw_pass(DRWPass *pass);
+/**
+ * Draw only a subset of shgroups. Used in special situations as grease pencil strokes.
+ */
 void DRW_draw_pass_subset(DRWPass *pass, DRWShadingGroup *start_group, DRWShadingGroup *end_group);
 
 void DRW_draw_callbacks_pre_scene(void);
 void DRW_draw_callbacks_post_scene(void);
 
+/**
+ * Reset state to not interfere with other UI draw-call.
+ */
 void DRW_state_reset_ex(DRWState state);
 void DRW_state_reset(void);
+/**
+ * Use with care, intended so selection code can override passes depth settings,
+ * which is important for selection to work properly.
+ *
+ * Should be set in main draw loop, cleared afterwards
+ */
 void DRW_state_lock(DRWState state);
 
-/* Selection */
+/* Selection. */
+
 void DRW_select_load_id(uint id);
 
-/* Draw State */
+/* Draw State. */
+
+/**
+ * When false, drawing doesn't output to a pixel buffer
+ * eg: Occlusion queries, or when we have setup a context to draw in already.
+ */
 bool DRW_state_is_fbo(void);
+/**
+ * For when engines need to know if this is drawing for selection or not.
+ */
 bool DRW_state_is_select(void);
 bool DRW_state_is_material_select(void);
 bool DRW_state_is_depth(void);
+/**
+ * Whether we are rendering for an image
+ */
 bool DRW_state_is_image_render(void);
+/**
+ * Whether we are rendering only the render engine,
+ * or if we should also render the mode engines.
+ */
 bool DRW_state_is_scene_render(void);
+/**
+ * Whether we are rendering simple opengl render
+ */
 bool DRW_state_is_opengl_render(void);
 bool DRW_state_is_playback(void);
+/**
+ * Is the user navigating the region.
+ */
 bool DRW_state_is_navigating(void);
+/**
+ * Should text draw in this mode?
+ */
 bool DRW_state_show_text(void);
+/**
+ * Should draw support elements
+ * Objects center, selection outline, probe data, ...
+ */
 bool DRW_state_draw_support(void);
+/**
+ * Whether we should render the background
+ */
 bool DRW_state_draw_background(void);
 
 /* Avoid too many lookups while drawing */