[Bf-blender-cvs] [7c76bdca1b7] master: Cleanup: move public doc-strings into headers for 'gpu'
Campbell Barton
noreply at git.blender.org
Thu Dec 9 10:04:01 CET 2021
Commit: 7c76bdca1b7195720a769c4911678d85825907fe
Author: Campbell Barton
Date: Thu Dec 9 20:01:47 2021 +1100
Branches: master
https://developer.blender.org/rB7c76bdca1b7195720a769c4911678d85825907fe
Cleanup: move public doc-strings into headers for 'gpu'
Ref T92709
===================================================================
M source/blender/gpu/GPU_batch.h
M source/blender/gpu/GPU_batch_presets.h
M source/blender/gpu/GPU_batch_utils.h
M source/blender/gpu/GPU_buffers.h
M source/blender/gpu/GPU_capabilities.h
M source/blender/gpu/GPU_context.h
M source/blender/gpu/GPU_debug.h
M source/blender/gpu/GPU_framebuffer.h
M source/blender/gpu/GPU_immediate.h
M source/blender/gpu/GPU_immediate_util.h
M source/blender/gpu/GPU_material.h
M source/blender/gpu/GPU_matrix.h
M source/blender/gpu/GPU_platform.h
M source/blender/gpu/GPU_select.h
M source/blender/gpu/GPU_shader.h
M source/blender/gpu/GPU_state.h
M source/blender/gpu/GPU_texture.h
M source/blender/gpu/GPU_uniform_buffer.h
M source/blender/gpu/GPU_vertex_buffer.h
M source/blender/gpu/GPU_vertex_format.h
M source/blender/gpu/GPU_viewport.h
M source/blender/gpu/intern/gpu_batch.cc
M source/blender/gpu/intern/gpu_batch_presets.c
M source/blender/gpu/intern/gpu_batch_utils.c
M source/blender/gpu/intern/gpu_buffers.c
M source/blender/gpu/intern/gpu_capabilities.cc
M source/blender/gpu/intern/gpu_context.cc
M source/blender/gpu/intern/gpu_debug.cc
M source/blender/gpu/intern/gpu_framebuffer.cc
M source/blender/gpu/intern/gpu_immediate.cc
M source/blender/gpu/intern/gpu_immediate_util.c
M source/blender/gpu/intern/gpu_material.c
M source/blender/gpu/intern/gpu_matrix.cc
M source/blender/gpu/intern/gpu_node_graph.c
M source/blender/gpu/intern/gpu_node_graph.h
M source/blender/gpu/intern/gpu_platform.cc
M source/blender/gpu/intern/gpu_select.c
M source/blender/gpu/intern/gpu_select_pick.c
M source/blender/gpu/intern/gpu_select_private.h
M source/blender/gpu/intern/gpu_shader.cc
M source/blender/gpu/intern/gpu_shader_interface.cc
M source/blender/gpu/intern/gpu_shader_interface.hh
M source/blender/gpu/intern/gpu_state.cc
M source/blender/gpu/intern/gpu_texture.cc
M source/blender/gpu/intern/gpu_uniform_buffer.cc
M source/blender/gpu/intern/gpu_vertex_buffer.cc
M source/blender/gpu/intern/gpu_vertex_format.cc
M source/blender/gpu/intern/gpu_viewport.c
M source/blender/gpu/opengl/gl_backend.cc
M source/blender/gpu/opengl/gl_batch.cc
M source/blender/gpu/opengl/gl_batch.hh
M source/blender/gpu/opengl/gl_context.hh
M source/blender/gpu/opengl/gl_debug.cc
M source/blender/gpu/opengl/gl_debug.hh
M source/blender/gpu/opengl/gl_debug_layer.cc
M source/blender/gpu/opengl/gl_framebuffer.cc
M source/blender/gpu/opengl/gl_framebuffer.hh
M source/blender/gpu/opengl/gl_shader.cc
M source/blender/gpu/opengl/gl_shader.hh
M source/blender/gpu/opengl/gl_state.cc
M source/blender/gpu/opengl/gl_state.hh
M source/blender/gpu/opengl/gl_texture.cc
M source/blender/gpu/opengl/gl_texture.hh
M source/blender/gpu/opengl/gl_vertex_array.cc
M source/blender/gpu/opengl/gl_vertex_array.hh
===================================================================
diff --git a/source/blender/gpu/GPU_batch.h b/source/blender/gpu/GPU_batch.h
index 911c8cc2e42..a8bc4f271c9 100644
--- a/source/blender/gpu/GPU_batch.h
+++ b/source/blender/gpu/GPU_batch.h
@@ -102,25 +102,48 @@ void GPU_batch_init_ex(GPUBatch *batch,
GPUVertBuf *vert,
GPUIndexBuf *elem,
eGPUBatchFlag owns_flag);
+/**
+ * This will share the VBOs with the new batch.
+ */
void GPU_batch_copy(GPUBatch *batch_dst, GPUBatch *batch_src);
#define GPU_batch_create(prim, verts, elem) GPU_batch_create_ex(prim, verts, elem, 0)
#define GPU_batch_init(batch, prim, verts, elem) GPU_batch_init_ex(batch, prim, verts, elem, 0)
-/* Same as discard but does not free. (does not call free callback). */
+/**
+ * Same as discard but does not free. (does not call free callback).
+ */
void GPU_batch_clear(GPUBatch *);
-void GPU_batch_discard(GPUBatch *); /* verts & elem are not discarded */
+/**
+ * \note Verts & elem are not discarded.
+ */
+void GPU_batch_discard(GPUBatch *);
+/**
+ * \note Override ONLY the first instance VBO (and free them if owned).
+ */
void GPU_batch_instbuf_set(GPUBatch *, GPUVertBuf *, bool own_vbo); /* Instancing */
+/**
+ * \note Override any previously assigned elem (and free it if owned).
+ */
void GPU_batch_elembuf_set(GPUBatch *batch, GPUIndexBuf *elem, bool own_ibo);
int GPU_batch_instbuf_add_ex(GPUBatch *, GPUVertBuf *, bool own_vbo);
+/**
+ * Returns the index of verts in the batch.
+ */
int GPU_batch_vertbuf_add_ex(GPUBatch *, GPUVertBuf *, bool own_vbo);
#define GPU_batch_vertbuf_add(batch, verts) GPU_batch_vertbuf_add_ex(batch, verts, false)
void GPU_batch_set_shader(GPUBatch *batch, GPUShader *shader);
+/**
+ * Bind program bound to IMM to the batch.
+ *
+ * XXX Use this with much care. Drawing with the #GPUBatch API is not compatible with IMM.
+ * DO NOT DRAW WITH THE BATCH BEFORE CALLING #immUnbindProgram.
+ */
void GPU_batch_program_set_imm_shader(GPUBatch *batch);
void GPU_batch_program_set_builtin(GPUBatch *batch, eGPUBuiltinShader shader_id);
void GPU_batch_program_set_builtin_with_config(GPUBatch *batch,
@@ -129,6 +152,7 @@ void GPU_batch_program_set_builtin_with_config(GPUBatch *batch,
/* Will only work after setting the batch program. */
/* TODO(fclem): These need to be replaced by GPU_shader_uniform_* with explicit shader. */
+
#define GPU_batch_uniform_1i(batch, name, x) GPU_shader_uniform_1i((batch)->shader, name, x);
#define GPU_batch_uniform_1b(batch, name, x) GPU_shader_uniform_1b((batch)->shader, name, x);
#define GPU_batch_uniform_1f(batch, name, x) GPU_shader_uniform_1f((batch)->shader, name, x);
@@ -151,14 +175,19 @@ void GPU_batch_program_set_builtin_with_config(GPUBatch *batch,
void GPU_batch_draw(GPUBatch *batch);
void GPU_batch_draw_range(GPUBatch *batch, int v_first, int v_count);
+/**
+ * Draw multiple instance of a batch without having any instance attributes.
+ */
void GPU_batch_draw_instanced(GPUBatch *batch, int i_count);
-/* This does not bind/unbind shader and does not call GPU_matrix_bind() */
+/**
+ * This does not bind/unbind shader and does not call GPU_matrix_bind().
+ */
void GPU_batch_draw_advanced(GPUBatch *, int v_first, int v_count, int i_first, int i_count);
#if 0 /* future plans */
-/* Can multiple batches share a GPUVertBuf? Use ref count? */
+/* Can multiple batches share a #GPUVertBuf? Use ref count? */
/* We often need a batch with its own data, to be created and discarded together. */
/* WithOwn variants reduce number of system allocations. */
diff --git a/source/blender/gpu/GPU_batch_presets.h b/source/blender/gpu/GPU_batch_presets.h
index 19f200fecbf..73c9172f2ba 100644
--- a/source/blender/gpu/GPU_batch_presets.h
+++ b/source/blender/gpu/GPU_batch_presets.h
@@ -35,7 +35,8 @@ extern "C" {
/* gpu_batch_presets.c */
-/* Replacement for gluSphere */
+/* Replacement for #gluSphere */
+
struct GPUBatch *GPU_batch_preset_sphere(int lod) ATTR_WARN_UNUSED_RESULT;
struct GPUBatch *GPU_batch_preset_sphere_wire(int lod) ATTR_WARN_UNUSED_RESULT;
struct GPUBatch *GPU_batch_preset_panel_drag_widget(const float pixelsize,
@@ -43,6 +44,9 @@ struct GPUBatch *GPU_batch_preset_panel_drag_widget(const float pixelsize,
const float col_dark[4],
const float width) ATTR_WARN_UNUSED_RESULT;
+/**
+ * To be used with procedural placement inside shader.
+ */
struct GPUBatch *GPU_batch_preset_quad(void);
void gpu_batch_presets_init(void);
diff --git a/source/blender/gpu/GPU_batch_utils.h b/source/blender/gpu/GPU_batch_utils.h
index 37dccc4621c..660ae0c8844 100644
--- a/source/blender/gpu/GPU_batch_utils.h
+++ b/source/blender/gpu/GPU_batch_utils.h
@@ -30,6 +30,16 @@ extern "C" {
struct rctf;
/* gpu_batch_utils.c */
+
+/**
+ * Creates triangles from a byte-array of polygons.
+ *
+ * See 'make_shape_2d_from_blend.py' utility to create data to pass to this function.
+ *
+ * \param polys_flat: Pairs of X, Y coordinates (repeating to signify closing the polygon).
+ * \param polys_flat_len: Length of the array (must be an even number).
+ * \param rect: Optional region to map the byte 0..255 coords to. When not set use -1..1.
+ */
struct GPUBatch *GPU_batch_tris_from_poly_2d_encoded(
const uchar *polys_flat, uint polys_flat_len, const struct rctf *rect) ATTR_WARN_UNUSED_RESULT
ATTR_NONNULL(1);
@@ -37,7 +47,11 @@ struct GPUBatch *GPU_batch_wire_from_poly_2d_encoded(
const uchar *polys_flat, uint polys_flat_len, const struct rctf *rect) ATTR_WARN_UNUSED_RESULT
ATTR_NONNULL(1);
-/* Only use by draw manager. Use the presets function instead for interface. */
+/**
+ * Replacement for #gluSphere.
+ *
+ * \note Only use by draw manager. Use the presets function instead for interface.
+ */
struct GPUBatch *gpu_batch_sphere(int lat_res, int lon_res) ATTR_WARN_UNUSED_RESULT;
#ifdef __cplusplus
diff --git a/source/blender/gpu/GPU_buffers.h b/source/blender/gpu/GPU_buffers.h
index b770bde65fc..9ba283bf65f 100644
--- a/source/blender/gpu/GPU_buffers.h
+++ b/source/blender/gpu/GPU_buffers.h
@@ -44,11 +44,17 @@ struct Mesh;
struct PBVH;
struct SubdivCCG;
-/* Buffers for drawing from PBVH grids. */
+/**
+ * Buffers for drawing from PBVH grids.
+ */
typedef struct GPU_PBVH_Buffers GPU_PBVH_Buffers;
-/* Build must be called once before using the other functions, used every time
- * mesh topology changes. Threaded. */
+/**
+ * Build must be called once before using the other functions,
+ * used every time mesh topology changes.
+ *
+ * Threaded: do not call any functions that use OpenGL calls!
+ */
GPU_PBVH_Buffers *GPU_pbvh_mesh_buffers_build(const struct MPoly *mpoly,
const struct MLoop *mloop,
const struct MLoopTri *looptri,
@@ -58,23 +64,36 @@ GPU_PBVH_Buffers *GPU_pbvh_mesh_buffers_build(const struct MPoly *mpoly,
const int face_indices_len,
const struct Mesh *mesh);
+/**
+ * Threaded: do not call any functions that use OpenGL calls!
+ */
GPU_PBVH_Buffers *GPU_pbvh_grid_buffers_build(int totgrid, unsigned int **grid_hidden);
+/**
+ * Threaded: do not call any functions that use OpenGL calls!
+ */
GPU_PBVH_Buffers *GPU_pbvh_bmesh_buffers_build(bool smooth_shading);
-/* Free part of data for update. Not thread safe, must run in OpenGL main thread. */
+/**
+ * Free part of data for update. Not thread safe, must run in OpenGL main thread.
+ */
void GPU_pbvh_bmesh_buffers_update_free(GPU_PBVH_Buffers *buffers);
void GPU_pbvh_grid_buffers_update_free(GPU_PBVH_Buffers *buffers,
const struct DMFlagMat *grid_flag_mats,
const int *grid_indices);
-/* Update mesh buffers without topology changes. Threaded. */
+/**
+ * Update mesh buffers without topology changes. Threaded.
+ */
enum {
GPU_PBVH_BUFFERS_SHOW_MASK = (1 << 1),
GPU_PBVH_BUFFERS_SHOW_VCOL = (1 << 2),
GPU_PBVH_BUFFERS_SHOW_SCULPT_FACE_SETS = (1 << 3),
};
+/**
+ * Threaded: do not call any functions that use OpenGL calls!
+ */
void GPU_pbvh_mesh_buffers_update(GPU_PBVH_Buffers *buffers,
const struct MVert *mvert,
const float *vmask,
@@ -85,6 +104,11 @@ void GPU_pbvh_mesh_buffers_update(GPU_PBVH_Buffers *buffers,
const struct MPropCol *vtcol,
const int update_flags);
+/**
+ * Creates a vertex buffer (coordinate, normal, color) and,
+ * if smooth shading, an element index buffer.
+ * Threaded: do not call any functions that use OpenGL calls!
+ */
void GPU_pbvh_bmesh_buffers_update(GPU_PBVH_Buffers *buffers,
struct BMesh *bm,
struct GSet *bm_faces,
@@ -92,6 +116,9 @@ void GPU_pbvh_bmesh_buffers_update(GPU_PBVH_Buffers *buffers,
struct GSet *bm_other_verts,
const int update_flags);
+/**
+ * Threaded: do not call any functions that use OpenGL calls!
+ */
void GPU_pbvh_grid_buffers_update(GPU_PBVH_Buffers *buffers,
struct SubdivCCG *subdiv_ccg,
struct CCGElem **grids,
@@ -104,13 +131,17 @@ void GPU_pbvh_grid_buffers_update(GPU_PBVH_Buffers *buffers,
const struct CCGKey *key,
const int update_flags);
-/* Finish update. Not thread safe, must run in OpenGL main thread. */
+/**
+ * Finish update. Not thread safe, must run in OpenGL main thread.
+ */
void GPU_pbvh_buffers_update_flush(GPU_PBVH_Buffers *buffers);
-/* Free buffers. Not thread safe, must run in OpenGL main thread. */
+/**
+ * Free buffers. Not thread safe, must run in OpenGL main thread.
+ */
void GPU_pbvh_buffers_free(GPU_PBVH_Buffers *buffers);
-/* draw */
+/** Draw. */
struct GPUBatch *GPU_pbvh_buffers_batch_get(GPU_PBVH_Buffers *b
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-blender-cvs
mailing list