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

Ref T92709

17 files changed, 71 insertions, 30 deletions

diff --git a/source/blender/gpu/opengl/gl_backend.cc b/source/blender/gpu/opengl/gl_backend.cc
index 27ef75df328..7bb88894b81 100644
--- a/source/blender/gpu/opengl/gl_backend.cc
+++ b/source/blender/gpu/opengl/gl_backend.cc
@@ -421,11 +421,14 @@ static void detect_workarounds()
 }  // namespace blender::gpu
 
 /** Internal capabilities. */
+
 GLint GLContext::max_cubemap_size = 0;
 GLint GLContext::max_texture_3d_size = 0;
 GLint GLContext::max_ubo_binds = 0;
 GLint GLContext::max_ubo_size = 0;
+
 /** Extensions. */
+
 bool GLContext::base_instance_support = false;
 bool GLContext::clear_texture_support = false;
 bool GLContext::copy_image_support = false;
@@ -439,7 +442,9 @@ bool GLContext::texture_cube_map_array_support = false;
 bool GLContext::texture_filter_anisotropic_support = false;
 bool GLContext::texture_gather_support = false;
 bool GLContext::vertex_attrib_binding_support = false;
+
 /** Workarounds. */
+
 bool GLContext::debug_layer_workaround = false;
 bool GLContext::unused_fb_slot_workaround = false;
 bool GLContext::generate_mipmap_workaround = false;
diff --git a/source/blender/gpu/opengl/gl_batch.cc b/source/blender/gpu/opengl/gl_batch.cc
index fc1d1006d0d..90400f85d48 100644
--- a/source/blender/gpu/opengl/gl_batch.cc
+++ b/source/blender/gpu/opengl/gl_batch.cc
@@ -74,7 +74,6 @@ void GLVaoCache::init()
   vao_id_ = 0;
 }
 
-/* Create a new VAO object and store it in the cache. */
 void GLVaoCache::insert(const GLShaderInterface *interface, GLuint vao)
 {
   /* Now insert the cache. */
@@ -191,7 +190,6 @@ void GLVaoCache::clear()
   this->init();
 }
 
-/* Return 0 on cache miss (invalid VAO) */
 GLuint GLVaoCache::lookup(const GLShaderInterface *interface)
 {
   const int count = (is_dynamic_vao_count) ? dynamic_vaos.count : GPU_VAO_STATIC_LEN;
@@ -205,8 +203,6 @@ GLuint GLVaoCache::lookup(const GLShaderInterface *interface)
   return 0;
 }
 
-/* The GLVaoCache object is only valid for one GLContext.
- * Reset the cache if trying to draw in another context; */
 void GLVaoCache::context_check()
 {
   GLContext *ctx = GLContext::get();
diff --git a/source/blender/gpu/opengl/gl_batch.hh b/source/blender/gpu/opengl/gl_batch.hh
index 704b6471dd5..a2b5f8fc15e 100644
--- a/source/blender/gpu/opengl/gl_batch.hh
+++ b/source/blender/gpu/opengl/gl_batch.hh
@@ -43,9 +43,11 @@ class GLShaderInterface;
 
 #define GPU_VAO_STATIC_LEN 3
 
-/* VAO management: remembers all geometry state (vertex attribute bindings & element buffer)
- * for each shader interface. Start with a static number of vaos and fallback to dynamic count
- * if necessary. Once a batch goes dynamic it does not go back. */
+/**
+ * VAO management: remembers all geometry state (vertex attribute bindings & element buffer)
+ * for each shader interface. Start with a static number of VAO's and fallback to dynamic count
+ * if necessary. Once a batch goes dynamic it does not go back.
+ */
 class GLVaoCache {
  private:
   /** Context for which the vao_cache_ was generated. */
@@ -80,13 +82,23 @@ class GLVaoCache {
   GLuint vao_get(GPUBatch *batch);
   GLuint base_instance_vao_get(GPUBatch *batch, int i_first);
 
+  /**
+   * Return 0 on cache miss (invalid VAO).
+   */
   GLuint lookup(const GLShaderInterface *interface);
+  /**
+   * Create a new VAO object and store it in the cache.
+   */
   void insert(const GLShaderInterface *interface, GLuint vao_id);
   void remove(const GLShaderInterface *interface);
   void clear(void);
 
  private:
   void init(void);
+  /**
+   * The #GLVaoCache object is only valid for one #GLContext.
+   * Reset the cache if trying to draw in another context;.
+   */
   void context_check(void);
 };
 
@@ -100,6 +112,7 @@ class GLBatch : public Batch {
   void bind(int i_first);
 
   /* Convenience getters. */
+
   GLIndexBuf *elem_(void) const
   {
     return static_cast<GLIndexBuf *>(unwrap(elem));
diff --git a/source/blender/gpu/opengl/gl_context.hh b/source/blender/gpu/opengl/gl_context.hh
index 9273bfb9911..40107ca9ef7 100644
--- a/source/blender/gpu/opengl/gl_context.hh
+++ b/source/blender/gpu/opengl/gl_context.hh
@@ -56,11 +56,14 @@ class GLSharedOrphanLists {
 class GLContext : public Context {
  public:
   /** Capabilities. */
+
   static GLint max_cubemap_size;
   static GLint max_texture_3d_size;
   static GLint max_ubo_size;
   static GLint max_ubo_binds;
+
   /** Extensions. */
+
   static bool base_instance_support;
   static bool clear_texture_support;
   static bool copy_image_support;
@@ -74,7 +77,9 @@ class GLContext : public Context {
   static bool texture_filter_anisotropic_support;
   static bool texture_gather_support;
   static bool vertex_attrib_binding_support;
+
   /** Workarounds. */
+
   static bool debug_layer_workaround;
   static bool unused_fb_slot_workaround;
   static bool generate_mipmap_workaround;
diff --git a/source/blender/gpu/opengl/gl_debug.cc b/source/blender/gpu/opengl/gl_debug.cc
index 3e259235515..0a06d9cdb7c 100644
--- a/source/blender/gpu/opengl/gl_debug.cc
+++ b/source/blender/gpu/opengl/gl_debug.cc
@@ -142,7 +142,6 @@ static void APIENTRY debug_callback(GLenum UNUSED(source),
 
 #undef APIENTRY
 
-/* This function needs to be called once per context. */
 void init_gl_callbacks()
 {
   CLOG_ENSURE(&LOG);
diff --git a/source/blender/gpu/opengl/gl_debug.hh b/source/blender/gpu/opengl/gl_debug.hh
index 892fb1d2ddb..3964e5da550 100644
--- a/source/blender/gpu/opengl/gl_debug.hh
+++ b/source/blender/gpu/opengl/gl_debug.hh
@@ -88,8 +88,16 @@ namespace debug {
 void raise_gl_error(const char *info);
 void check_gl_error(const char *info);
 void check_gl_resources(const char *info);
+/**
+ * This function needs to be called once per context.
+ */
 void init_gl_callbacks(void);
 
+/**
+ * Initialize a fallback layer (to KHR_debug) that covers only some functions.
+ * We override the functions pointers by our own implementation that just checks #glGetError.
+ * Some additional functions (not overridable) are covered inside the header using wrappers.
+ */
 void init_debug_layer(void);
 
 void object_label(GLenum type, GLuint object, const char *name);
diff --git a/source/blender/gpu/opengl/gl_debug_layer.cc b/source/blender/gpu/opengl/gl_debug_layer.cc
index a5225f98fd9..e624cb9ee46 100644
--- a/source/blender/gpu/opengl/gl_debug_layer.cc
+++ b/source/blender/gpu/opengl/gl_debug_layer.cc
@@ -105,11 +105,6 @@ DEBUG_FUNC_DECLARE(PFNGLUSEPROGRAMPROC, void, glUseProgram, GLuint, program);
 
 #undef DEBUG_FUNC_DECLARE
 
-/**
- * Initialize a fallback layer (to KHR_debug) that covers only some functions.
- * We override the functions pointers by our own implementation that just checks #glGetError.
- * Some additional functions (not overridable) are covered inside the header using wrappers.
- */
 void init_debug_layer()
 {
 #define DEBUG_WRAP(function) \
diff --git a/source/blender/gpu/opengl/gl_framebuffer.cc b/source/blender/gpu/opengl/gl_framebuffer.cc
index 8da114d9270..13f03195437 100644
--- a/source/blender/gpu/opengl/gl_framebuffer.cc
+++ b/source/blender/gpu/opengl/gl_framebuffer.cc
@@ -110,7 +110,6 @@ void GLFrameBuffer::init()
 /** \name Config
  * \{ */
 
-/* This is a rather slow operation. Don't check in normal cases. */
 bool GLFrameBuffer::check(char err_out[256])
 {
   this->bind(true);
@@ -451,9 +450,6 @@ void GLFrameBuffer::read(eGPUFrameBufferBits plane,
   glReadPixels(UNPACK4(area), format, type, r_data);
 }
 
-/**
- * Copy \a src at the give offset inside \a dst.
- */
 void GLFrameBuffer::blit_to(
     eGPUFrameBufferBits planes, int src_slot, FrameBuffer *dst_, int dst_slot, int x, int y)
 {
diff --git a/source/blender/gpu/opengl/gl_framebuffer.hh b/source/blender/gpu/opengl/gl_framebuffer.hh
index 7b2c73d7042..21b5931440d 100644
--- a/source/blender/gpu/opengl/gl_framebuffer.hh
+++ b/source/blender/gpu/opengl/gl_framebuffer.hh
@@ -79,6 +79,9 @@ class GLFrameBuffer : public FrameBuffer {
 
   void bind(bool enabled_srgb) override;
 
+  /**
+   * This is a rather slow operation. Don't check in normal cases.
+   */
   bool check(char err_out[256]) override;
 
   void clear(eGPUFrameBufferBits buffers,
@@ -97,6 +100,9 @@ class GLFrameBuffer : public FrameBuffer {
             int slot,
             void *r_data) override;
 
+  /**
+   * Copy \a src at the give offset inside \a dst.
+   */
   void blit_to(eGPUFrameBufferBits planes,
                int src_slot,
                FrameBuffer *dst,
diff --git a/source/blender/gpu/opengl/gl_shader.cc b/source/blender/gpu/opengl/gl_shader.cc
index 66a1bd5ceb7..cd2c3caad46 100644
--- a/source/blender/gpu/opengl/gl_shader.cc
+++ b/source/blender/gpu/opengl/gl_shader.cc
@@ -137,7 +137,6 @@ char *GLShader::glsl_patch_get(GLenum gl_stage)
   return glsl_patch_default_get();
 }
 
-/* Create, compile and attach the shader stage to the shader program. */
 GLuint GLShader::create_shader_stage(GLenum gl_stage, MutableSpan<const char *> sources)
 {
   GLuint shader = glCreateShader(gl_stage);
@@ -258,7 +257,6 @@ void GLShader::unbind()
  * TODO(fclem): Should be replaced by compute shaders.
  * \{ */
 
-/* Should be called before linking. */
 void GLShader::transform_feedback_names_set(Span<const char *> name_list,
                                             const eGPUShaderTFBType geom_type)
 {
diff --git a/source/blender/gpu/opengl/gl_shader.hh b/source/blender/gpu/opengl/gl_shader.hh
index 770bc29747e..57e33392d9f 100644
--- a/source/blender/gpu/opengl/gl_shader.hh
+++ b/source/blender/gpu/opengl/gl_shader.hh
@@ -53,13 +53,14 @@ class GLShader : public Shader {
   GLShader(const char *name);
   ~GLShader();
 
-  /* Return true on success. */
+  /** Return true on success. */
   void vertex_shader_from_glsl(MutableSpan<const char *> sources) override;
   void geometry_shader_from_glsl(MutableSpan<const char *> sources) override;
   void fragment_shader_from_glsl(MutableSpan<const char *> sources) override;
   void compute_shader_from_glsl(MutableSpan<const char *> sources) override;
   bool finalize(void) override;
 
+  /** Should be called before linking. */
   void transform_feedback_names_set(Span<const char *> name_list,
                                     const eGPUShaderTFBType geom_type) override;
   bool transform_feedback_enable(GPUVertBuf *buf) override;
@@ -73,12 +74,13 @@ class GLShader : public Shader {
 
   void vertformat_from_shader(GPUVertFormat *format) const override;
 
-  /* DEPRECATED: Kept only because of BGL API. */
+  /** DEPRECATED: Kept only because of BGL API. */
   int program_handle_get(void) const override;
 
  private:
   char *glsl_patch_get(GLenum gl_stage);
 
+  /** Create, compile and attach the shader stage to the shader program. */
   GLuint create_shader_stage(GLenum gl_stage, MutableSpan<const char *> sources);
 
   MEM_CXX_CLASS_ALLOC_FUNCS("GLShader");
diff --git a/source/blender/gpu/opengl/gl_state.cc b/source/blender/gpu/opengl/gl_state.cc
index d737cf88a13..bfc691df4b3 100644
--- a/source/blender/gpu/opengl/gl_state.cc
+++ b/source/blender/gpu/opengl/gl_state.cc
@@ -84,7 +84,6 @@ void GLStateManager::apply_state()
   active_fb->apply_state();
 };
 
-/* Will set all the states regardless of the current ones. */
 void GLStateManager::force_state()
 {
   /* Little exception for clip distances since they need to keep the old count correct. */
@@ -482,7 +481,6 @@ void GLStateManager::texture_bind(Texture *tex_, eGPUSamplerState sampler_type,
   dirty_texture_binds_ |= 1ULL << unit;
 }
 
-/* Bind the texture to slot 0 for editing purpose. Used by legacy pipeline. */
 void GLStateManager::texture_bind_temp(GLTexture *tex)
 {
   glActiveTexture(GL_TEXTURE0);
diff --git a/source/blender/gpu/opengl/gl_state.hh b/source/blender/gpu/opengl/gl_state.hh
index 3b4b40b1d10..979644b41c9 100644
--- a/source/blender/gpu/opengl/gl_state.hh
+++ b/source/blender/gpu/opengl/gl_state.hh
@@ -72,11 +72,17 @@ class GLStateManager : public StateManager {
   GLStateManager();
 
   void apply_state(void) override;
+  /**
+   * Will set all the states regardless of the current ones.
+   */
   void force_state(void) override;
 
   void issue_barrier(eGPUBarrier barrier_bits) override;
 
   void texture_bind(Texture *tex, eGPUSamplerState sampler, int unit) override;
+  /**
+   * Bind the texture to slot 0 for editing purpose. Used by legacy pipeline.
+   */
   void texture_bind_temp(GLTexture *tex);
   void texture_unbind(Texture *tex) override;
   void texture_unbind_all(void) override;
diff --git a/source/blender/gpu/opengl/gl_texture.cc b/source/blender/gpu/opengl/gl_texture.cc
index f9c5a97a0bb..d84d21d3021 100644
--- a/source/blender/gpu/opengl/gl_texture.cc
+++ b/source/blender/gpu/opengl/gl_texture.cc
@@ -62,7 +62,6 @@ GLTexture::~GLTexture()
   GLContext::tex_free(tex_id_);
 }
 
-/* Return true on success. */
 bool GLTexture::init_internal()
 {
   if ((format_ == GPU_DEPTH24_STENCIL8) && GPU_depth_blitting_workaround()) {
@@ -100,7 +99,6 @@ bool GLTexture::init_internal()
   return true;
 }
 
-/* Return true on success. */
 bool GLTexture::init_internal(GPUVertBuf *vbo)
 {
   GLVertBuf *gl_vbo = static_cast<GLVertBuf *>(unwrap(vbo));
@@ -123,7 +121,6 @@ bool GLTexture::init_internal(GPUVertBuf *vbo)
   return true;
 }
 
-/* Will create enough mipmaps up to get to the given level. */
 void GLTexture::ensure_mipmaps(int miplvl)
 {
   int effective_h = (type_ == GPU_TEXTURE_1D_ARRAY) ? 0 : h_;
diff --git a/source/blender/gpu/opengl/gl_texture.hh b/source/blender/gpu/opengl/gl_texture.hh
index 93c6b8d8af0..eb979444f5a 100644
--- a/source/blender/gpu/opengl/gl_texture.hh
+++ b/source/blender/gpu/opengl/gl_texture.hh
@@ -63,6 +63,12 @@ class GLTexture : public Texture {
   void update_sub(
       int mip, int offset[3], int extent[3], eGPUDataFormat type, const void *data) override;
 
+  /**
+   * This will create the mipmap images and populate them with filtered data from base level.
+   *
+   * \warning Depth textures are not populated but they have their mips correctly defined.
+   * \warning This resets the mipmap range.
+   */
   void generate_mipmap(void) override;
   void copy_to(Texture *dst) override;
   void clear(eGPUDataFormat format, const void *data) override;
@@ -80,11 +86,14 @@ class GLTexture : public Texture {
   static void samplers_update(void);
 
  protected:
+  /** Return true on success. */
   bool init_internal(void) override;
+  /** Return true on success. */
   bool init_internal(GPUVertBuf *vbo) override;
 
  private:
   bool proxy_check(int mip);
+  /** Will create enough mipmaps up to get to the given level. */
   void ensure_mipmaps(int mip);
   void update_sub_direct_state_access(
       int mip, int offset[3], int extent[3], GLenum gl_format, GLenum gl_type, const void *data);
@@ -294,7 +303,9 @@ inline GLenum to_gl(eGPUDataFormat format)
   }
 }
 
-/* Definitely not complete, edit according to the gl specification. */
+/**
+ * Definitely not complete, edit according to the OpenGL specification.
+ */
 inline GLenum to_gl_data_format(eGPUTextureFormat format)
 {
   /* You can add any of the available type to this list
@@ -366,7 +377,9 @@ inline GLenum to_gl_data_format(eGPUTextureFormat format)
   }
 }
 
-/* Assume Unorm / Float target. Used with glReadPixels. */
+/**
+ * Assume Unorm / Float target. Used with #glReadPixels.
+ */
 inline GLenum channel_len_to_gl(int channel_len)
 {
   switch (channel_len) {
diff --git a/source/blender/gpu/opengl/gl_vertex_array.cc b/source/blender/gpu/opengl/gl_vertex_array.cc
index e324916b934..282ede5ba9b 100644
--- a/source/blender/gpu/opengl/gl_vertex_array.cc
+++ b/source/blender/gpu/opengl/gl_vertex_array.cc
@@ -108,7 +108,6 @@ static uint16_t vbo_bind(const ShaderInterface *interface,
   return enabled_attrib;
 }
 
-/* Update the Attribute Binding of the currently bound VAO. */
 void GLVertArray::update_bindings(const GLuint vao,
                                   const GPUBatch *batch_, /* Should be GLBatch. */
                                   const ShaderInterface *interface,
@@ -156,7 +155,6 @@ void GLVertArray::update_bindings(const GLuint vao,
   }
 }
 
-/* Another version of update_bindings for Immediate mode. */
 void GLVertArray::update_bindings(const GLuint vao,
                                   const uint v_first,
                                   const GPUVertFormat *format,
diff --git a/source/blender/gpu/opengl/gl_vertex_array.hh b/source/blender/gpu/opengl/gl_vertex_array.hh
index 7037986e31e..0f9b61f9648 100644
--- a/source/blender/gpu/opengl/gl_vertex_array.hh
+++ b/source/blender/gpu/opengl/gl_vertex_array.hh
@@ -33,11 +33,17 @@ namespace gpu {
 
 namespace GLVertArray {
 
+/**
+ * Update the Attribute Binding of the currently bound VAO.
+ */
 void update_bindings(const GLuint vao,
                      const GPUBatch *batch,
                      const ShaderInterface *interface,
                      const int base_instance);
 
+/**
+ * Another version of update_bindings for Immediate mode.
+ */
 void update_bindings(const GLuint vao,
                      const uint v_first,
                      const GPUVertFormat *format,