diff options
| author | Campbell Barton <ideasman42@gmail.com> | 2021-12-09 12:01:47 +0300 |
|---|---|---|
| committer | Campbell Barton <ideasman42@gmail.com> | 2021-12-09 12:01:47 +0300 |
| commit | 7c76bdca1b7195720a769c4911678d85825907fe (patch) | |
| tree | 003fab9c0a71af49b89f49eda0076b8018b6cfe8 /source | |
| parent | 9f546d690899e05b25a6ef764cc8cf2f5db918b0 (diff) | |
Cleanup: move public doc-strings into headers for 'gpu'
Ref T92709
Diffstat (limited to 'source')
65 files changed, 596 insertions, 387 deletions
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 *buffers, bool fast, bool wires); short GPU_pbvh_buffers_material_index_get(GPU_PBVH_Buffers *buffers); diff --git a/source/blender/gpu/GPU_capabilities.h b/source/blender/gpu/GPU_capabilities.h index 5b5d0f16c9f..9cd1dbd37f1 100644 --- a/source/blender/gpu/GPU_capabilities.h +++ b/source/blender/gpu/GPU_capabilities.h @@ -64,6 +64,9 @@ bool GPU_shader_image_load_store_support(void); bool GPU_mem_stats_supported(void); void GPU_mem_stats_get(int *totalmem, int *freemem); +/** + * Return support for the active context + window. + */ bool GPU_stereo_quadbuffer_support(void); #ifdef __cplusplus diff --git a/source/blender/gpu/GPU_context.h b/source/blender/gpu/GPU_context.h index 82f13424502..5189fa1ae41 100644 --- a/source/blender/gpu/GPU_context.h +++ b/source/blender/gpu/GPU_context.h @@ -44,8 +44,14 @@ void GPU_backend_exit(void); typedef struct GPUContext GPUContext; GPUContext *GPU_context_create(void *ghost_window); +/** + * To be called after #GPU_context_active_set(ctx_to_destroy). + */ void GPU_context_discard(GPUContext *); +/** + * Ctx can be NULL. + */ void GPU_context_active_set(GPUContext *); GPUContext *GPU_context_active_get(void); diff --git a/source/blender/gpu/GPU_debug.h b/source/blender/gpu/GPU_debug.h index f67e850ad80..9796ac63272 100644 --- a/source/blender/gpu/GPU_debug.h +++ b/source/blender/gpu/GPU_debug.h @@ -33,7 +33,14 @@ extern "C" { void GPU_debug_group_begin(const char *name); void GPU_debug_group_end(void); +/** + * Return a formatted string showing the current group hierarchy in this format: + * "Group1 > Group 2 > Group3 > ... > GroupN : " + */ void GPU_debug_get_groups_names(int name_buf_len, char *r_name_buf); +/** + * Return true if inside a debug group with the same name. + */ bool GPU_debug_group_match(const char *ref); #ifdef __cplusplus diff --git a/source/blender/gpu/GPU_framebuffer.h b/source/blender/gpu/GPU_framebuffer.h index bf0ab3dc533..b203c49a7f1 100644 --- a/source/blender/gpu/GPU_framebuffer.h +++ b/source/blender/gpu/GPU_framebuffer.h @@ -62,6 +62,9 @@ typedef struct GPUOffScreen GPUOffScreen; GPUFrameBuffer *GPU_framebuffer_create(const char *name); void GPU_framebuffer_free(GPUFrameBuffer *fb); void GPU_framebuffer_bind(GPUFrameBuffer *fb); +/** + * Workaround for binding a SRGB frame-buffer without doing the SRGB transform. + */ void GPU_framebuffer_bind_no_srgb(GPUFrameBuffer *fb); void GPU_framebuffer_restore(void); @@ -69,6 +72,9 @@ bool GPU_framebuffer_bound(GPUFrameBuffer *fb); bool GPU_framebuffer_check_valid(GPUFrameBuffer *fb, char err_out[256]); GPUFrameBuffer *GPU_framebuffer_active_get(void); +/** + * Returns the default frame-buffer. Will always exists even if it's just a dummy. + */ GPUFrameBuffer *GPU_framebuffer_back_get(void); #define GPU_FRAMEBUFFER_FREE_SAFE(fb) \ @@ -113,6 +119,12 @@ void GPU_framebuffer_texture_detach(GPUFrameBuffer *fb, struct GPUTexture *tex); GPU_framebuffer_config_array(*(_fb), config, (sizeof(config) / sizeof(GPUAttachment))); \ } while (0) +/** + * First #GPUAttachment in *config is always the depth/depth_stencil buffer. + * Following #GPUAttachments are color buffers. + * Setting #GPUAttachment.mip to -1 will leave the texture in this slot. + * Setting #GPUAttachment.tex to NULL will detach the texture in this slot. + */ void GPU_framebuffer_config_array(GPUFrameBuffer *fb, const GPUAttachment *config, int config_len); #define GPU_ATTACHMENT_NONE \ @@ -156,8 +168,16 @@ void GPU_framebuffer_texture_cubeface_attach( /* Frame-buffer operations. */ +/** + * Viewport and scissor size is stored per frame-buffer. + * It is only reset to its original dimensions explicitly OR when binding the frame-buffer after + * modifying its attachments. + */ void GPU_framebuffer_viewport_set(GPUFrameBuffer *fb, int x, int y, int w, int h); void GPU_framebuffer_viewport_get(GPUFrameBuffer *fb, int r_viewport[4]); +/** + * Reset to its attachment(s) size. + */ void GPU_framebuffer_viewport_reset(GPUFrameBuffer *fb); void GPU_framebuffer_clear(GPUFrameBuffer *fb, @@ -184,6 +204,9 @@ void GPU_framebuffer_clear(GPUFrameBuffer *fb, #define GPU_framebuffer_clear_color_depth_stencil(fb, col, depth, stencil) \ GPU_framebuffer_clear(fb, GPU_COLOR_BIT | GPU_DEPTH_BIT | GPU_STENCIL_BIT, col, depth, stencil) +/** + * Clear all textures attached to this frame-buffer with a different color. + */ void GPU_framebuffer_multi_clear(GPUFrameBuffer *fb, const float (*clear_cols)[4]); void GPU_framebuffer_read_depth( @@ -198,6 +221,9 @@ void GPU_framebuffer_read_color(GPUFrameBuffer *fb, eGPUDataFormat format, void *data); +/** + * Read_slot and write_slot are only used for color buffers. + */ void GPU_framebuffer_blit(GPUFrameBuffer *fb_read, int read_slot, GPUFrameBuffer *fb_write, @@ -233,6 +259,9 @@ int GPU_offscreen_width(const GPUOffScreen *ofs); int GPU_offscreen_height(const GPUOffScreen *ofs); struct GPUTexture *GPU_offscreen_color_texture(const GPUOffScreen *ofs); +/** + * \note only to be used by viewport code! + */ void GPU_offscreen_viewport_data_get(GPUOffScreen *ofs, GPUFrameBuffer **r_fb, struct GPUTexture **r_color, diff --git a/source/blender/gpu/GPU_immediate.h b/source/blender/gpu/GPU_immediate.h index edb7c9fe5b5..a175fc65ba4 100644 --- a/source/blender/gpu/GPU_immediate.h +++ b/source/blender/gpu/GPU_immediate.h @@ -39,7 +39,7 @@ extern "C" { /** Returns a cleared vertex format, ready for #add_attr. */ GPUVertFormat *immVertexFormat(void); -/** Every immBegin must have a program bound first. */ +/** Every #immBegin must have a program bound first. */ void immBindShader(GPUShader *shader); /** Call after your last immEnd, or before binding another program. */ void immUnbindProgram(void); @@ -50,10 +50,12 @@ void immBegin(GPUPrimType, uint vertex_len); void immBeginAtMost(GPUPrimType, uint max_vertex_len); void immEnd(void); /* finishes and draws. */ -/* immBegin a batch, then use standard immFunctions as usual. */ -/* immEnd will finalize the batch instead of drawing. */ -/* Then you can draw it as many times as you like! +/* - #immBegin a batch, then use standard `imm*` functions as usual. + * - #immEnd will finalize the batch instead of drawing. + * + * Then you can draw it as many times as you like! * Partially replaces the need for display lists. */ + GPUBatch *immBeginBatch(GPUPrimType, uint vertex_len); GPUBatch *immBeginBatchAtMost(GPUPrimType, uint vertex_len); @@ -81,12 +83,14 @@ void immAttr4ub(uint attr_id, unsigned char r, unsigned char g, unsigned char b, void immAttr3ubv(uint attr_id, const unsigned char data[3]); void immAttr4ubv(uint attr_id, const unsigned char data[4]); -/* Explicitly skip an attribute. */ -/* This advanced option kills automatic value copying for this attr_id. */ +/* Explicitly skip an attribute. + * This advanced option kills automatic value copying for this attr_id. */ + void immAttrSkip(uint attr_id); -/* Provide one last attribute value & end the current vertex. */ -/* This is most often used for 2D or 3D position (similar to glVertex). */ +/* Provide one last attribute value & end the current vertex. + * This is most often used for 2D or 3D position (similar to #glVertex). */ + void immVertex2f(uint attr_id, float x, float y); void immVertex3f(uint attr_id, float x, float y, float z); void immVertex4f(uint attr_id, float x, float y, float z, float w); @@ -101,6 +105,7 @@ void immVertex3fv(uint attr_id, const float data[3]); void immVertex2iv(uint attr_id, const int data[2]); /* Provide uniform values that don't change for the entire draw call. */ + void immUniform1i(const char *name, int x); void immUniform1f(const char *name, float x); void immUniform2f(const char *name, float x, float y); @@ -109,6 +114,9 @@ void immUniform3f(const char *name, float x, float y, float z); void immUniform3fv(const char *name, const float data[3]); void immUniform4f(const char *name, float x, float y, float z, float w); void immUniform4fv(const char *name, const float data[4]); +/** + * Note array index is not supported for name (i.e: "array[0]"). + */ void immUniformArray4fv(const char *bare_name, const float *data, int count); void immUniformMatrix4fv(const char *name, const float data[4][4]); @@ -116,7 +124,8 @@ void immBindTexture(const char *name, GPUTexture *tex); void immBindTextureSampler(const char *name, GPUTexture *tex, eGPUSamplerState state); /* Convenience functions for setting "uniform vec4 color". */ -/* The rgb functions have implicit alpha = 1.0. */ +/* The RGB functions have implicit alpha = 1.0. */ + void immUniformColor4f(float r, float g, float b, float a); void immUniformColor4fv(const float rgba[4]); void immUniformColor3f(float r, float g, float b); @@ -135,7 +144,7 @@ void immUniformColor4ubv(const unsigned char rgba[4]); */ void immBindBuiltinProgram(eGPUBuiltinShader shader_id); -/* Extend immUniformColor to take Blender's themes */ +/** Extend #immUniformColor to take Blender's themes. */ void immUniformThemeColor(int color_id); void immUniformThemeColorAlpha(int color_id, float a); void immUniformThemeColor3(int color_id); diff --git a/source/blender/gpu/GPU_immediate_util.h b/source/blender/gpu/GPU_immediate_util.h index 047c3d3da00..25672489612 100644 --- a/source/blender/gpu/GPU_immediate_util.h +++ b/source/blender/gpu/GPU_immediate_util.h @@ -31,16 +31,50 @@ extern "C" { void immRectf(uint pos, float x1, float y1, float x2, float y2); void immRecti(uint pos, int x1, int y1, int x2, int y2); -/* Same as immRectf/immRecti but does not call immBegin/immEnd. To use with GPU_PRIM_TRIS. */ +/** + * Same as #immRectf / #immRecti but does not call #immBegin / #immEnd. + * To use with #GPU_PRIM_TRIS. + */ void immRectf_fast(uint pos, float x1, float y1, float x2, float y2); void immRectf_fast_with_color( uint pos, uint col, float x1, float y1, float x2, float y2, const float color[4]); void immRecti_fast_with_color( uint pos, uint col, int x1, int y1, int x2, int y2, const float color[4]); +/** + * Pack color into 3 bytes + * + * This define converts a numerical value to the equivalent 24-bit + * color, while not being endian-sensitive. On little-endian, this + * is the same as doing a 'naive' indexing, on big-endian, it is not! + * + * \note BGR format (i.e. 0xBBGGRR)... + * + * \param x: color. + */ void imm_cpack(uint x); +/** + * Draw a circle outline with the given \a radius. + * The circle is centered at \a x, \a y and drawn in the XY plane. + * + * \param shdr_pos: The vertex attribute number for position. + * \param x: Horizontal center. + * \param y: Vertical center. + * \param rad: The circle's radius. + * \param nsegments: The number of segments to use in drawing (more = smoother). + */ void imm_draw_circle_wire_2d(uint shdr_pos, float x, float y, float radius, int nsegments); +/** + * Draw a filled circle with the given \a radius. + * The circle is centered at \a x, \a y and drawn in the XY plane. + * + * \param shdr_pos: The vertex attribute number for position. + * \param x: Horizontal center. + * \param y: Vertical center. + * \param rad: The circle's radius. + * \param nsegments: The number of segments to use in drawing (more = smoother). + */ void imm_draw_circle_fill_2d(uint shdr_pos, float x, float y, float radius, int nsegments); void imm_draw_circle_wire_aspect_2d( @@ -48,15 +82,34 @@ void imm_draw_circle_wire_aspect_2d( void imm_draw_circle_fill_aspect_2d( uint shdr_pos, float x, float y, float rad_x, float rad_y, int nsegments); -/* use this version when GPUVertFormat has a vec3 position */ +/** + * Use this version when #GPUVertFormat has a vec3 position. + */ void imm_draw_circle_wire_3d(uint pos, float x, float y, float radius, int nsegments); void imm_draw_circle_dashed_3d(uint pos, float x, float y, float radius, int nsegments); void imm_draw_circle_fill_3d(uint pos, float x, float y, float radius, int nsegments); -/* same as 'imm_draw_disk_partial_fill_2d', except it draws a wire arc. */ +/** + * Same as 'imm_draw_disk_partial_fill_2d', except it draws a wire arc. + */ void imm_draw_circle_partial_wire_2d( uint pos, float x, float y, float radius, int nsegments, float start, float sweep); +/** + * Draw a filled arc with the given inner and outer radius. + * The circle is centered at \a x, \a y and drawn in the XY plane. + * + * \note Arguments are `gluPartialDisk` compatible. + * + * \param pos: The vertex attribute number for position. + * \param x: Horizontal center. + * \param y: Vertical center. + * \param rad_inner: The inner circle's radius. + * \param rad_outer: The outer circle's radius (can be zero). + * \param nsegments: The number of segments to use in drawing (more = smoother). + * \param start: Specifies the starting angle, in degrees, of the disk portion. + * \param sweep: Specifies the sweep angle, in degrees, of the disk portion. + */ void imm_draw_disk_partial_fill_2d(uint pos, float x, float y, @@ -66,9 +119,21 @@ void imm_draw_disk_partial_fill_2d(uint pos, float start, float sweep); +/** + * Draw a lined box. + * + * \param pos: The vertex attribute number for position. + * \param x1: left. + * \param y1: bottom. + * \param x2: right. + * \param y2: top. + */ void imm_draw_box_wire_2d(uint pos, float x1, float y1, float x2, float y2); void imm_draw_box_wire_3d(uint pos, float x1, float y1, float x2, float y2); +/** + * Draw a standard checkerboard to indicate transparent backgrounds. + */ void imm_draw_box_checker_2d_ex(float x1, float y1, float x2, @@ -85,6 +150,18 @@ void imm_draw_cube_corners_3d(uint pos, const float aspect[3], const float factor); +/** + * Draw a cylinder. Replacement for #gluCylinder. + * \warning Slow, better use it only if you no other choices. + * + * \param pos: The vertex attribute number for position. + * \param nor: The vertex attribute number for normal. + * \param base: Specifies the radius of the cylinder at z = 0. + * \param top: Specifies the radius of the cylinder at z = height. + * \param height: Specifies the height of the cylinder. + * \param slices: Specifies the number of subdivisions around the z axis. + * \param stacks: Specifies the number of subdivisions along the z axis. + */ void imm_draw_cylinder_fill_normal_3d( uint pos, uint nor, float base, float top, float height, int slices, int stacks); void imm_draw_cylinder_wire_3d( diff --git a/source/blender/gpu/GPU_material.h b/source/blender/gpu/GPU_material.h index e64521768f9..ea3028e539b 100644 --- a/source/blender/gpu/GPU_material.h +++ b/source/blender/gpu/GPU_material.h @@ -54,7 +54,7 @@ typedef struct GPUMaterial GPUMaterial; typedef struct GPUNode GPUNode; typedef struct GPUNodeLink GPUNodeLink; -/* Functions to create GPU Materials nodes */ +/* Functions to create GPU Materials nodes. */ typedef enum eGPUType { /* Keep in sync with GPU_DATATYPE_STR */ @@ -180,10 +180,17 @@ struct GPUUniformBuf *GPU_material_sss_profile_get(GPUMaterial *material, int sample_len, struct GPUTexture **tex_profile); -/* High level functions to create and use GPU materials */ +/** + * High level functions to create and use GPU materials. + */ GPUMaterial *GPU_material_from_nodetree_find(struct ListBase *gpumaterials, const void *engine_type, int options); +/** + * \note Caller must use #GPU_material_from_nodetree_find to re-use existing materials, + * This is enforced since constructing other arguments to this function may be expensive + * so only do this when they are needed. + */ GPUMaterial *GPU_material_from_nodetree(struct Scene *scene, struct Material *ma, struct bNodeTree *ntree, @@ -205,10 +212,21 @@ void GPU_materials_free(struct Main *bmain); struct Scene *GPU_material_scene(GPUMaterial *material); struct GPUPass *GPU_material_get_pass(GPUMaterial *material); struct GPUShader *GPU_material_get_shader(GPUMaterial *material); +/** + * Return can be NULL if it's a world material. + */ struct Material *GPU_material_get_material(GPUMaterial *material); +/** + * Return true if the material compilation has not yet begin or begin. + */ eGPUMaterialStatus GPU_material_status(GPUMaterial *mat); struct GPUUniformBuf *GPU_material_uniform_buffer_get(GPUMaterial *material); +/** + * Create dynamic UBO from parameters + * + * \param inputs: Items are #LinkData, data is #GPUInput (`BLI_genericNodeN(GPUInput)`). + */ void GPU_material_uniform_buffer_create(GPUMaterial *material, ListBase *inputs); struct GPUUniformBuf *GPU_material_create_sss_profile_ubo(void); diff --git a/source/blender/gpu/GPU_matrix.h b/source/blender/gpu/GPU_matrix.h index edf16f04349..bfd4a14d112 100644 --- a/source/blender/gpu/GPU_matrix.h +++ b/source/blender/gpu/GPU_matrix.h @@ -31,7 +31,10 @@ extern "C" { struct GPUShader; -void GPU_matrix_reset(void); /* to Identity transform & empty stack */ +/** + * To Identity transform & empty stack. + */ +void GPU_matrix_reset(void); /* ModelView Matrix (2D or 3D) */ @@ -52,9 +55,13 @@ void GPU_matrix_translate_3fv(const float vec[3]); void GPU_matrix_scale_3f(float x, float y, float z); void GPU_matrix_scale_3fv(const float vec[3]); -/* Axis of rotation should be a unit vector. */ +/** + * Axis of rotation should be a unit vector. + */ void GPU_matrix_rotate_3f(float deg, float x, float y, float z); -/* Axis of rotation should be a unit vector. */ +/** + * Axis of rotation should be a unit vector. + */ void GPU_matrix_rotate_3fv(float deg, const float axis[3]); void GPU_matrix_rotate_axis(float deg, char axis); /* TODO: enum for axis? */ @@ -78,12 +85,12 @@ void GPU_matrix_scale_2f(float x, float y); void GPU_matrix_scale_2fv(const float vec[2]); void GPU_matrix_rotate_2d(float deg); -/* Projection Matrix (2D or 3D) */ +/* Projection Matrix (2D or 3D). */ void GPU_matrix_push_projection(void); void GPU_matrix_pop_projection(void); -/* 3D Projection Matrix */ +/* 3D Projection Matrix. */ void GPU_matrix_identity_projection_set(void); void GPU_matrix_projection_set(const float m[4][4]); @@ -136,11 +143,12 @@ bool GPU_matrix_unproject_3fv(const float win[3], const int view[4], float r_world[3]); -/* 2D Projection Matrix */ +/* 2D Projection Matrix. */ void GPU_matrix_ortho_2d_set(float left, float right, float bottom, float top); -/* functions to get matrix values */ +/* Functions to get matrix values. */ + const float (*GPU_matrix_model_view_get(float m[4][4]))[4]; const float (*GPU_matrix_projection_get(float m[4][4]))[4]; const float (*GPU_matrix_model_view_projection_get(float m[4][4]))[4]; @@ -148,12 +156,19 @@ const float (*GPU_matrix_model_view_projection_get(float m[4][4]))[4]; const float (*GPU_matrix_normal_get(float m[3][3]))[3]; const float (*GPU_matrix_normal_inverse_get(float m[3][3]))[3]; -/* set uniform values for currently bound shader */ +/** + * Set uniform values for currently bound shader. + */ void GPU_matrix_bind(struct GPUShader *shader); bool GPU_matrix_dirty_get(void); /* since last bind */ -/* own working polygon offset */ +/** + * Own working polygon offset. + */ float GPU_polygon_offset_calc(const float (*winmat)[4], float viewdist, float dist); +/** + * \note \a viewdist is only for orthographic projections at the moment. + */ void GPU_polygon_offset(float viewdist, float dist); /* Python API needs to be able to inspect the stack so errors raise exceptions diff --git a/source/blender/gpu/GPU_platform.h b/source/blender/gpu/GPU_platform.h index fa7d5d7fba8..0d80c0ed8af 100644 --- a/source/blender/gpu/GPU_platform.h +++ b/source/blender/gpu/GPU_platform.h @@ -66,7 +66,10 @@ typedef enum eGPUSupportLevel { extern "C" { #endif +/* GPU Types */ + bool GPU_type_matches(eGPUDeviceType device, eGPUOSType os, eGPUDriverType driver); + eGPUSupportLevel GPU_platform_support_level(void); const char *GPU_platform_vendor(void); const char *GPU_platform_renderer(void); diff --git a/source/blender/gpu/GPU_select.h b/source/blender/gpu/GPU_select.h index d28363253b1..c02af763311 100644 --- a/source/blender/gpu/GPU_select.h +++ b/source/blender/gpu/GPU_select.h @@ -31,7 +31,7 @@ extern "C" { struct rcti; -/* flags for mode of operation */ +/** Flags for mode of operation. */ enum { GPU_SELECT_ALL = 1, /* gpu_select_query */ @@ -42,21 +42,48 @@ enum { GPU_SELECT_PICK_NEAREST = 5, }; +/** + * Initialize and provide buffer for results. + */ void GPU_select_begin( unsigned int *buffer, unsigned int bufsize, const struct rcti *input, char mode, int oldhits); +/** + * Loads a new selection id and ends previous query, if any. + * In second pass of selection it also returns + * if id has been hit on the first pass already. + * Thus we can skip drawing un-hit objects. + * + * \warning We rely on the order of object rendering on passes to be the same for this to work. + */ bool GPU_select_load_id(unsigned int id); void GPU_select_finalize(void); +/** + * Cleanup and flush selection results to buffer. + * Return number of hits and hits in buffer. + * if \a dopass is true, we will do a second pass with occlusion queries to get the closest hit. + */ unsigned int GPU_select_end(void); -/* cache selection region */ +/* Cache selection region. */ + bool GPU_select_is_cached(void); void GPU_select_cache_begin(void); void GPU_select_cache_load_id(void); void GPU_select_cache_end(void); -/* utilities */ +/* Utilities. */ + +/** + * Helper function, nothing special but avoids doing inline since hits aren't sorted by depth + * and purpose of 4x buffer indices isn't so clear. + * + * Note that comparing depth as uint is fine. + */ const uint *GPU_select_buffer_near(const uint *buffer, int hits); uint GPU_select_buffer_remove_by_id(uint *buffer, int hits, uint select_id); +/** + * Part of the solution copied from `rect_subregion_stride_calc`. + */ void GPU_select_buffer_stride_realign(const struct rcti *src, const struct rcti *dst, uint *r_buf); #ifdef __cplusplus diff --git a/source/blender/gpu/GPU_shader.h b/source/blender/gpu/GPU_shader.h index 614af01b17b..5c373551494 100644 --- a/source/blender/gpu/GPU_shader.h +++ b/source/blender/gpu/GPU_shader.h @@ -70,6 +70,26 @@ GPUShader *GPU_shader_create_ex(const char *vertcode, struct GPU_ShaderCreateFromArray_Params { const char **vert, **geom, **frag, **defs; }; +/** + * Use via #GPU_shader_create_from_arrays macro (avoids passing in param). + * + * Similar to #DRW_shader_create_with_lib with the ability to include libs for each type of shader. + * + * It has the advantage that each item can be conditionally included + * without having to build the string inline, then free it. + * + * \param params: NULL terminated arrays of strings. + * + * Example: + * \code{.c} + * sh = GPU_shader_create_from_arrays({ + * .vert = (const char *[]){shader_lib_glsl, shader_vert_glsl, NULL}, + * .geom = (const char *[]){shader_geom_glsl, NULL}, + * .frag = (const char *[]){shader_frag_glsl, NULL}, + * .defs = (const char *[]){"#define DEFINE\n", test ? "#define OTHER_DEFINE\n" : "", NULL}, + * }); + * \endcode + */ struct GPUShader *GPU_shader_create_from_arrays_impl( const struct GPU_ShaderCreateFromArray_Params *params, const char *func, int line); @@ -88,10 +108,13 @@ void GPU_shader_unbind(void); const char *GPU_shader_get_name(GPUShader *shader); -/* Returns true if transform feedback was successfully enabled. */ +/** + * Returns true if transform feedback was successfully enabled. + */ bool GPU_shader_transform_feedback_enable(GPUShader *shader, struct GPUVertBuf *vertbuf); void GPU_shader_transform_feedback_disable(GPUShader *shader); +/** DEPRECATED: Kept only because of BGL API. */ int GPU_shader_get_program(GPUShader *shader); typedef enum { @@ -134,6 +157,7 @@ void GPU_shader_set_srgb_uniform(GPUShader *shader); int GPU_shader_get_uniform(GPUShader *shader, const char *name); int GPU_shader_get_builtin_uniform(GPUShader *shader, int builtin); int GPU_shader_get_builtin_block(GPUShader *shader, int builtin); +/** DEPRECATED: Kept only because of Python GPU API. */ int GPU_shader_get_uniform_block(GPUShader *shader, const char *name); int GPU_shader_get_ssbo(GPUShader *shader, const char *name); diff --git a/source/blender/gpu/GPU_state.h b/source/blender/gpu/GPU_state.h index 1c1211d2a3e..fa70a8934db 100644 --- a/source/blender/gpu/GPU_state.h +++ b/source/blender/gpu/GPU_state.h @@ -48,8 +48,8 @@ ENUM_OPERATORS(eGPUBarrier, GPU_BARRIER_SHADER_STORAGE) * Defines the fixed pipeline blending equation. * SRC is the output color from the shader. * DST is the color from the frame-buffer. - * The blending equation is : - * (SRC * A) + (DST * B). + * The blending equation is: + * `(SRC * A) + (DST * B)`. * The blend mode will modify the A and B parameters. */ typedef enum eGPUBlend { @@ -124,10 +124,23 @@ void GPU_front_facing(bool invert); void GPU_depth_range(float near, float far); void GPU_scissor_test(bool enable); void GPU_line_smooth(bool enable); +/** + * \note By convention, this is set as needed and not reset back to 1.0. + * This means code that draws lines must always set the line width beforehand, + * but is not expected to restore it's previous value. + */ void GPU_line_width(float width); void GPU_logic_op_xor_set(bool enable); void GPU_point_size(float size); void GPU_polygon_smooth(bool enable); + +/** + * Programmable point size: + * - Shaders set their own point size when enabled + * - Use GPU_point_size when disabled. + * + * TODO: remove and use program point size everywhere. + */ void GPU_program_point_size(bool enable); void GPU_scissor(int x, int y, int width, int height); void GPU_scissor_get(int coords[4]); @@ -158,6 +171,9 @@ eGPUDepthTest GPU_depth_test_get(void); eGPUWriteMask GPU_write_mask_get(void); uint GPU_stencil_mask_get(void); eGPUStencilTest GPU_stencil_test_get(void); +/** + * \note Already pre-multiplied by `U.pixelsize`. + */ float GPU_line_width_get(void); void GPU_flush(void); @@ -165,6 +181,10 @@ void GPU_finish(void); void GPU_apply_state(void); void GPU_bgl_start(void); + +/** + * Just turn off the `bgl` safeguard system. Can be called even without #GPU_bgl_start. + */ void GPU_bgl_end(void); bool GPU_bgl_get(void); diff --git a/source/blender/gpu/GPU_texture.h b/source/blender/gpu/GPU_texture.h index deff9e47871..54e9bde70d8 100644 --- a/source/blender/gpu/GPU_texture.h +++ b/source/blender/gpu/GPU_texture.h @@ -32,7 +32,8 @@ struct GPUVertBuf; /** Opaque type hiding blender::gpu::Texture. */ typedef struct GPUTexture GPUTexture; -/* GPU Samplers state +/** + * GPU Samplers state * - Specify the sampler state to bind a texture with. * - Internally used by textures. * - All states are created at startup to avoid runtime costs. @@ -60,8 +61,9 @@ typedef enum eGPUSamplerState { } \ } while (0) -/* `GPU_SAMPLER_MAX` is not a valid enum value, but only a limit. - * It also creates a bad mask for the `NOT` operator in `ENUM_OPERATORS`. +/** + * #GPU_SAMPLER_MAX is not a valid enum value, but only a limit. + * It also creates a bad mask for the `NOT` operator in #ENUM_OPERATORS. */ static const int GPU_SAMPLER_MAX = (GPU_SAMPLER_ICON + 1); ENUM_OPERATORS(eGPUSamplerState, GPU_SAMPLER_ICON) @@ -70,6 +72,9 @@ ENUM_OPERATORS(eGPUSamplerState, GPU_SAMPLER_ICON) extern "C" { #endif +/** + * Update user defined sampler states. + */ void GPU_samplers_update(void); /* GPU Texture @@ -84,11 +89,13 @@ void GPU_samplers_update(void); * - if created with from_blender, will not free the texture */ -/* Wrapper to supported OpenGL/Vulkan texture internal storage +/** + * Wrapper to supported OpenGL/Vulkan texture internal storage * If you need a type just un-comment it. Be aware that some formats * are not supported by render-buffers. All of the following formats * are part of the OpenGL 3.3 core - * specification. */ + * specification. + */ typedef enum eGPUTextureFormat { /* Formats texture & render-buffer. */ GPU_RGBA8UI, @@ -221,12 +228,19 @@ GPUTexture *GPU_texture_create_cube_array( const char *name, int w, int d, int mip_len, eGPUTextureFormat format, const float *data); /* Special textures. */ + GPUTexture *GPU_texture_create_from_vertbuf(const char *name, struct GPUVertBuf *vert); /** * \a data should hold all the data for all mipmaps. */ +/** + * DDS texture loading. Return NULL if support is not available. + */ GPUTexture *GPU_texture_create_compressed_2d( const char *name, int w, int h, int miplen, eGPUTextureFormat format, const void *data); +/** + * Create an error texture that will bind an invalid texture (pink) at draw time. + */ GPUTexture *GPU_texture_create_error(int dimension, bool array); void GPU_texture_update_mipmap(GPUTexture *tex, @@ -234,6 +248,9 @@ void GPU_texture_update_mipmap(GPUTexture *tex, eGPUDataFormat gpu_data_format, const void *pixels); +/** + * \note Updates only mip 0. + */ void GPU_texture_update(GPUTexture *tex, eGPUDataFormat data_format, const void *data); void GPU_texture_update_sub(GPUTexture *tex, eGPUDataFormat data_format, @@ -244,9 +261,20 @@ void GPU_texture_update_sub(GPUTexture *tex, int width, int height, int depth); +/** + * Makes data interpretation aware of the source layout. + * Skipping pixels correctly when changing rows when doing partial update. + */ void GPU_unpack_row_length_set(uint len); void *GPU_texture_read(GPUTexture *tex, eGPUDataFormat data_format, int miplvl); +/** + * Fills the whole texture with the same data for all pixels. + * \warning Only work for 2D texture for now. + * \warning Only clears the mip 0 of the texture. + * \param data_format: data format of the pixel data. + * \param data: 1 pixel worth of data to fill the texture with. + */ void GPU_texture_clear(GPUTexture *tex, eGPUDataFormat data_format, const void *data); void GPU_texture_free(GPUTexture *tex); @@ -261,6 +289,9 @@ void GPU_texture_image_bind(GPUTexture *tex, int unit); void GPU_texture_image_unbind(GPUTexture *tex); void GPU_texture_image_unbind_all(void); +/** + * Copy a texture content to a similar texture. Only MIP 0 is copied. + */ void GPU_texture_copy(GPUTexture *dst, GPUTexture *src); void GPU_texture_generate_mipmap(GPUTexture *tex); @@ -292,7 +323,8 @@ int GPU_texture_opengl_bindcode(const GPUTexture *tex); void GPU_texture_get_mipmap_size(GPUTexture *tex, int lvl, int *size); -/* utilities */ +/* Utilities. */ + size_t GPU_texture_component_len(eGPUTextureFormat format); size_t GPU_texture_dataformat_size(eGPUDataFormat data_format); diff --git a/source/blender/gpu/GPU_uniform_buffer.h b/source/blender/gpu/GPU_uniform_buffer.h index 4efac0a8c00..c9ea1582ad4 100644 --- a/source/blender/gpu/GPU_uniform_buffer.h +++ b/source/blender/gpu/GPU_uniform_buffer.h @@ -40,6 +40,12 @@ struct ListBase; typedef struct GPUUniformBuf GPUUniformBuf; GPUUniformBuf *GPU_uniformbuf_create_ex(size_t size, const void *data, const char *name); +/** + * Create UBO from inputs list. + * Return NULL if failed to create or if \param inputs: is empty. + * + * \param inputs: ListBase of #BLI_genericNodeN(#GPUInput). + */ GPUUniformBuf *GPU_uniformbuf_create_from_list(struct ListBase *inputs, const char *name); #define GPU_uniformbuf_create(size) GPU_uniformbuf_create_ex(size, NULL, __func__); diff --git a/source/blender/gpu/GPU_vertex_buffer.h b/source/blender/gpu/GPU_vertex_buffer.h index 2c54016daa7..62a495abfb3 100644 --- a/source/blender/gpu/GPU_vertex_buffer.h +++ b/source/blender/gpu/GPU_vertex_buffer.h @@ -79,10 +79,13 @@ GPUVertBuf *GPU_vertbuf_create_with_format_ex(const GPUVertFormat *, GPUUsageTyp */ const void *GPU_vertbuf_read(GPUVertBuf *verts); void *GPU_vertbuf_unmap(const GPUVertBuf *verts, const void *mapped_data); +/** Same as discard but does not free. */ void GPU_vertbuf_clear(GPUVertBuf *verts); void GPU_vertbuf_discard(GPUVertBuf *); -/* Avoid GPUVertBuf datablock being free but not its data. */ +/** + * Avoid GPUVertBuf data-block being free but not its data. + */ void GPU_vertbuf_handle_ref_add(GPUVertBuf *verts); void GPU_vertbuf_handle_ref_remove(GPUVertBuf *verts); @@ -93,25 +96,42 @@ void GPU_vertbuf_init_with_format_ex(GPUVertBuf *, const GPUVertFormat *, GPUUsa GPUVertBuf *GPU_vertbuf_duplicate(GPUVertBuf *verts); +/** + * Create a new allocation, discarding any existing data. + */ void GPU_vertbuf_data_alloc(GPUVertBuf *, uint v_len); +/** + * Resize buffer keeping existing data. + */ void GPU_vertbuf_data_resize(GPUVertBuf *, uint v_len); +/** + * Set vertex count but does not change allocation. + * Only this many verts will be uploaded to the GPU and rendered. + * This is useful for streaming data. + */ void GPU_vertbuf_data_len_set(GPUVertBuf *, uint v_len); -/* The most important #set_attr variant is the untyped one. Get it right first. +/** + * The most important #set_attr variant is the untyped one. Get it right first. * It takes a void* so the app developer is responsible for matching their app data types * to the vertex attribute's type and component count. They're in control of both, so this - * should not be a problem. */ - + * should not be a problem. + */ void GPU_vertbuf_attr_set(GPUVertBuf *, uint a_idx, uint v_idx, const void *data); +/** Fills a whole vertex (all attributes). Data must match packed layout. */ void GPU_vertbuf_vert_set(GPUVertBuf *verts, uint v_idx, const void *data); -/* Tightly packed, non interleaved input data. */ +/** + * Tightly packed, non interleaved input data. + */ void GPU_vertbuf_attr_fill(GPUVertBuf *, uint a_idx, const void *data); void GPU_vertbuf_attr_fill_stride(GPUVertBuf *, uint a_idx, uint stride, const void *data); -/* For low level access only */ +/** + * For low level access only. + */ typedef struct GPUVertBufRaw { uint size; uint stride; @@ -138,18 +158,32 @@ GPU_INLINE uint GPU_vertbuf_raw_used(GPUVertBufRaw *a) void GPU_vertbuf_attr_get_raw_data(GPUVertBuf *, uint a_idx, GPUVertBufRaw *access); +/** + * Returns the data buffer and set it to null internally to avoid freeing. + * \note Be careful when using this. The data needs to match the expected format. + */ void *GPU_vertbuf_steal_data(GPUVertBuf *verts); +/** + * \note Be careful when using this. The data needs to match the expected format. + */ void *GPU_vertbuf_get_data(const GPUVertBuf *verts); const GPUVertFormat *GPU_vertbuf_get_format(const GPUVertBuf *verts); uint GPU_vertbuf_get_vertex_alloc(const GPUVertBuf *verts); uint GPU_vertbuf_get_vertex_len(const GPUVertBuf *verts); GPUVertBufStatus GPU_vertbuf_get_status(const GPUVertBuf *verts); +/** + * Should be rename to #GPU_vertbuf_data_upload. + */ void GPU_vertbuf_use(GPUVertBuf *); void GPU_vertbuf_bind_as_ssbo(struct GPUVertBuf *verts, int binding); -/* XXX do not use. */ +/** + * XXX: do not use! + * This is just a wrapper for the use of the Hair refine workaround. + * To be used with #GPU_vertbuf_use(). + */ void GPU_vertbuf_update_sub(GPUVertBuf *verts, uint start, uint len, void *data); /* Metrics */ diff --git a/source/blender/gpu/GPU_vertex_format.h b/source/blender/gpu/GPU_vertex_format.h index 0d5388c6b82..4af9901a88c 100644 --- a/source/blender/gpu/GPU_vertex_format.h +++ b/source/blender/gpu/GPU_vertex_format.h @@ -113,8 +113,33 @@ uint GPU_vertformat_attr_add( GPUVertFormat *, const char *name, GPUVertCompType, uint comp_len, GPUVertFetchMode); void GPU_vertformat_alias_add(GPUVertFormat *, const char *alias); +/** + * Makes vertex attribute from the next vertices to be accessible in the vertex shader. + * For an attribute named "attr" you can access the next nth vertex using "attr{number}". + * Use this function after specifying all the attributes in the format. + * + * NOTE: This does NOT work when using indexed rendering. + * NOTE: Only works for first attribute name. (this limitation can be changed if needed) + * + * WARNING: this function creates a lot of aliases/attributes, make sure to keep the attribute + * name short to avoid overflowing the name-buffer. + */ void GPU_vertformat_multiload_enable(GPUVertFormat *format, int load_count); +/** + * Make attribute layout non-interleaved. + * Warning! This does not change data layout! + * Use direct buffer access to fill the data. + * This is for advanced usage. + * + * De-interleaved data means all attribute data for each attribute + * is stored continuously like this: + * 000011112222 + * instead of: + * 012012012012 + * + * \note This is per attribute de-interleaving, NOT per component. + */ void GPU_vertformat_deinterleave(GPUVertFormat *format); int GPU_vertformat_attr_id_get(const GPUVertFormat *, const char *name); @@ -126,10 +151,16 @@ BLI_INLINE const char *GPU_vertformat_attr_name_get(const GPUVertFormat *format, return format->names + attr->names[n_idx]; } -/* WARNING: Can only rename using a string with same character count. - * WARNING: This removes all other aliases of this attribute. */ +/** + * \warning Can only rename using a string with same character count. + * \warning This removes all other aliases of this attribute. + */ void GPU_vertformat_attr_rename(GPUVertFormat *format, int attr, const char *new_name); +/** + * \warning Always add a prefix to the result of this function as + * the generated string can start with a number and not be a valid attribute name. + */ void GPU_vertformat_safe_attr_name(const char *attr_name, char *r_safe_name, uint max_len); /* format conversion */ diff --git a/source/blender/gpu/GPU_viewport.h b/source/blender/gpu/GPU_viewport.h index 4d9970dac90..c4948d68298 100644 --- a/source/blender/gpu/GPU_viewport.h +++ b/source/blender/gpu/GPU_viewport.h @@ -49,12 +49,26 @@ GPUViewport *GPU_viewport_create(void); GPUViewport *GPU_viewport_stereo_create(void); void GPU_viewport_bind(GPUViewport *viewport, int view, const rcti *rect); void GPU_viewport_unbind(GPUViewport *viewport); +/** + * Merge and draw the buffers of \a viewport into the currently active framebuffer, performing + * color transform to display space. + * + * \param rect: Coordinates to draw into. By swapping min and max values, drawing can be done + * with inversed axis coordinates (upside down or sideways). + */ void GPU_viewport_draw_to_screen(GPUViewport *viewport, int view, const rcti *rect); +/** + * Version of #GPU_viewport_draw_to_screen() that lets caller decide if display colorspace + * transform should be performed. + */ void GPU_viewport_draw_to_screen_ex(GPUViewport *viewport, int view, const rcti *rect, bool display_colorspace, bool do_overlay_merge); +/** + * Must be executed inside Draw-manager OpenGL Context. + */ void GPU_viewport_free(GPUViewport *viewport); void GPU_viewport_colorspace_set(GPUViewport *viewport, @@ -62,7 +76,13 @@ void GPU_viewport_colorspace_set(GPUViewport *viewport, const ColorManagedDisplaySettings *display_settings, float dither); +/** + * Should be called from DRW after DRW_opengl_context_enable. + */ void GPU_viewport_bind_from_offscreen(GPUViewport *viewport, struct GPUOffScreen *ofs); +/** + * Clear vars assigned from offscreen, so we don't free data owned by `GPUOffScreen`. + */ void GPU_viewport_unbind_from_offscreen(GPUViewport *viewport, struct GPUOffScreen *ofs, bool display_colorspace, @@ -70,6 +90,9 @@ void GPU_viewport_unbind_from_offscreen(GPUViewport *viewport, struct DRWData **GPU_viewport_data_get(GPUViewport *viewport); +/** + * Merge the stereo textures. `color` and `overlay` texture will be modified. + */ void GPU_viewport_stereo_composite(GPUViewport *viewport, Stereo3dFormat *stereo_format); void GPU_viewport_tag_update(GPUViewport *viewport); @@ -82,6 +105,9 @@ GPUTexture *GPU_viewport_color_texture(GPUViewport *viewport, int view); GPUTexture *GPU_viewport_overlay_texture(GPUViewport *viewport, int view); GPUTexture *GPU_viewport_depth_texture(GPUViewport *viewport); +/** + * Overlay frame-buffer for drawing outside of DRW module. + */ GPUFrameBuffer *GPU_viewport_framebuffer_overlay_get(GPUViewport *viewport); #ifdef __cplusplus diff --git a/source/blender/gpu/intern/gpu_batch.cc b/source/blender/gpu/intern/gpu_batch.cc index 6ff67e1f043..2874dea775f 100644 --- a/source/blender/gpu/intern/gpu_batch.cc +++ b/source/blender/gpu/intern/gpu_batch.cc @@ -90,7 +90,6 @@ void GPU_batch_init_ex(GPUBatch *batch, batch->shader = nullptr; } -/* This will share the VBOs with the new batch. */ void GPU_batch_copy(GPUBatch *batch_dst, GPUBatch *batch_src) { GPU_batch_init_ex( @@ -137,7 +136,6 @@ void GPU_batch_discard(GPUBatch *batch) /** \name Buffers Management * \{ */ -/* NOTE: Override ONLY the first instance vbo (and free them if owned). */ void GPU_batch_instbuf_set(GPUBatch *batch, GPUVertBuf *inst, bool own_vbo) { BLI_assert(inst); @@ -151,7 +149,6 @@ void GPU_batch_instbuf_set(GPUBatch *batch, GPUVertBuf *inst, bool own_vbo) SET_FLAG_FROM_TEST(batch->flag, own_vbo, GPU_BATCH_OWNS_INST_VBO); } -/* NOTE: Override any previously assigned elem (and free it if owned). */ void GPU_batch_elembuf_set(GPUBatch *batch, GPUIndexBuf *elem, bool own_ibo) { BLI_assert(elem); @@ -188,7 +185,6 @@ int GPU_batch_instbuf_add_ex(GPUBatch *batch, GPUVertBuf *insts, bool own_vbo) return -1; } -/* Returns the index of verts in the batch. */ int GPU_batch_vertbuf_add_ex(GPUBatch *batch, GPUVertBuf *verts, bool own_vbo) { BLI_assert(verts); @@ -243,7 +239,6 @@ void GPU_batch_draw_range(GPUBatch *batch, int v_first, int v_count) GPU_batch_draw_advanced(batch, v_first, v_count, 0, 0); } -/* Draw multiple instance of a batch without having any instance attributes. */ void GPU_batch_draw_instanced(GPUBatch *batch, int i_count) { BLI_assert(batch->inst[0] == nullptr); @@ -301,9 +296,6 @@ void GPU_batch_program_set_builtin(GPUBatch *batch, eGPUBuiltinShader shader_id) GPU_batch_program_set_builtin_with_config(batch, shader_id, GPU_SHADER_CFG_DEFAULT); } -/* 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) { GPU_batch_set_shader(batch, immGetShader()); diff --git a/source/blender/gpu/intern/gpu_batch_presets.c b/source/blender/gpu/intern/gpu_batch_presets.c index 6a1645a71d8..b97378ad638 100644 --- a/source/blender/gpu/intern/gpu_batch_presets.c +++ b/source/blender/gpu/intern/gpu_batch_presets.c @@ -154,7 +154,6 @@ GPUBatch *GPU_batch_preset_sphere_wire(int lod) /** \name Create Sphere (3D) * \{ */ -/* Replacement for gluSphere */ GPUBatch *gpu_batch_sphere(int lat_res, int lon_res) { const float lon_inc = 2 * M_PI / lon_res; @@ -331,7 +330,6 @@ GPUBatch *GPU_batch_preset_panel_drag_widget(const float pixelsize, return g_presets_2d.batch.panel_drag_widget; } -/* To be used with procedural placement inside shader. */ GPUBatch *GPU_batch_preset_quad(void) { if (!g_presets_2d.batch.quad) { diff --git a/source/blender/gpu/intern/gpu_batch_utils.c b/source/blender/gpu/intern/gpu_batch_utils.c index e2d03d27035..a381df5974a 100644 --- a/source/blender/gpu/intern/gpu_batch_utils.c +++ b/source/blender/gpu/intern/gpu_batch_utils.c @@ -33,15 +33,6 @@ /** \name Polygon Creation (2D) * \{ */ -/** - * 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. - */ GPUBatch *GPU_batch_tris_from_poly_2d_encoded(const uchar *polys_flat, uint polys_flat_len, const rctf *rect) diff --git a/source/blender/gpu/intern/gpu_buffers.c b/source/blender/gpu/intern/gpu_buffers.c index 43483916236..fdc3eed87d9 100644 --- a/source/blender/gpu/intern/gpu_buffers.c +++ b/source/blender/gpu/intern/gpu_buffers.c @@ -204,7 +204,6 @@ static bool gpu_pbvh_is_looptri_visible(const MLoopTri *lt, sculpt_face_sets[lt->poly] > SCULPT_FACE_SET_NONE); } -/* Threaded - do not call any functions that use OpenGL calls! */ void GPU_pbvh_mesh_buffers_update(GPU_PBVH_Buffers *buffers, const MVert *mvert, const float *vmask, @@ -337,7 +336,6 @@ void GPU_pbvh_mesh_buffers_update(GPU_PBVH_Buffers *buffers, buffers->mvert = mvert; } -/* Threaded - do not call any functions that use OpenGL calls! */ GPU_PBVH_Buffers *GPU_pbvh_mesh_buffers_build(const MPoly *mpoly, const MLoop *mloop, const MLoopTri *looptri, @@ -584,7 +582,6 @@ void GPU_pbvh_grid_buffers_update_free(GPU_PBVH_Buffers *buffers, } } -/* Threaded - do not call any functions that use OpenGL calls! */ void GPU_pbvh_grid_buffers_update(GPU_PBVH_Buffers *buffers, SubdivCCG *subdiv_ccg, CCGElem **grids, @@ -764,7 +761,6 @@ void GPU_pbvh_grid_buffers_update(GPU_PBVH_Buffers *buffers, buffers->show_overlay = !empty_mask || !default_face_set; } -/* Threaded - do not call any functions that use OpenGL calls! */ GPU_PBVH_Buffers *GPU_pbvh_grid_buffers_build(int totgrid, BLI_bitmap **grid_hidden) { GPU_PBVH_Buffers *buffers; @@ -878,9 +874,6 @@ void GPU_pbvh_bmesh_buffers_update_free(GPU_PBVH_Buffers *buffers) } } -/* 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, BMesh *bm, GSet *bm_faces, @@ -1048,7 +1041,6 @@ void GPU_pbvh_bmesh_buffers_update(GPU_PBVH_Buffers *buffers, /** \name Generic * \{ */ -/* Threaded - do not call any functions that use OpenGL calls! */ GPU_PBVH_Buffers *GPU_pbvh_bmesh_buffers_build(bool smooth_shading) { GPU_PBVH_Buffers *buffers; diff --git a/source/blender/gpu/intern/gpu_capabilities.cc b/source/blender/gpu/intern/gpu_capabilities.cc index fe04d1db03c..f12fd96d1ba 100644 --- a/source/blender/gpu/intern/gpu_capabilities.cc +++ b/source/blender/gpu/intern/gpu_capabilities.cc @@ -189,7 +189,6 @@ void GPU_mem_stats_get(int *totalmem, int *freemem) Context::get()->memory_statistics_get(totalmem, freemem); } -/* Return support for the active context + window. */ bool GPU_stereo_quadbuffer_support() { return Context::get()->front_right != nullptr; diff --git a/source/blender/gpu/intern/gpu_context.cc b/source/blender/gpu/intern/gpu_context.cc index 85be7b593eb..5af15d1bc3d 100644 --- a/source/blender/gpu/intern/gpu_context.cc +++ b/source/blender/gpu/intern/gpu_context.cc @@ -109,7 +109,6 @@ GPUContext *GPU_context_create(void *ghost_window) return wrap(ctx); } -/* to be called after GPU_context_active_set(ctx_to_destroy) */ void GPU_context_discard(GPUContext *ctx_) { Context *ctx = unwrap(ctx_); @@ -117,7 +116,6 @@ void GPU_context_discard(GPUContext *ctx_) active_ctx = nullptr; } -/* ctx can be NULL */ void GPU_context_active_set(GPUContext *ctx_) { Context *ctx = unwrap(ctx_); diff --git a/source/blender/gpu/intern/gpu_debug.cc b/source/blender/gpu/intern/gpu_debug.cc index 5f061bd1bee..85cec67d2a7 100644 --- a/source/blender/gpu/intern/gpu_debug.cc +++ b/source/blender/gpu/intern/gpu_debug.cc @@ -55,10 +55,6 @@ void GPU_debug_group_end() ctx->debug_group_end(); } -/** - * Return a formatted string showing the current group hierarchy in this format: - * "Group1 > Group 2 > Group3 > ... > GroupN : " - */ void GPU_debug_get_groups_names(int name_buf_len, char *r_name_buf) { Context *ctx = Context::get(); @@ -77,7 +73,6 @@ void GPU_debug_get_groups_names(int name_buf_len, char *r_name_buf) r_name_buf[sz - 3] = '\0'; } -/* Return true if inside a debug group with the same name. */ bool GPU_debug_group_match(const char *ref) { /* Otherwise there will be no names. */ diff --git a/source/blender/gpu/intern/gpu_framebuffer.cc b/source/blender/gpu/intern/gpu_framebuffer.cc index ea37afd2885..3404eb67e28 100644 --- a/source/blender/gpu/intern/gpu_framebuffer.cc +++ b/source/blender/gpu/intern/gpu_framebuffer.cc @@ -216,18 +216,12 @@ void GPU_framebuffer_bind(GPUFrameBuffer *gpu_fb) unwrap(gpu_fb)->bind(enable_srgb); } -/** - * Workaround for binding a SRGB frame-buffer without doing the SRGB transform. - */ void GPU_framebuffer_bind_no_srgb(GPUFrameBuffer *gpu_fb) { const bool enable_srgb = false; unwrap(gpu_fb)->bind(enable_srgb); } -/** - * For stereo rendering. - */ void GPU_backbuffer_bind(eGPUBackBuffer buffer) { Context *ctx = Context::get(); @@ -251,7 +245,6 @@ GPUFrameBuffer *GPU_framebuffer_active_get() return wrap(ctx ? ctx->active_fb : nullptr); } -/* Returns the default frame-buffer. Will always exists even if it's just a dummy. */ GPUFrameBuffer *GPU_framebuffer_back_get() { Context *ctx = Context::get(); @@ -302,12 +295,6 @@ void GPU_framebuffer_texture_detach(GPUFrameBuffer *fb, GPUTexture *tex) unwrap(tex)->detach_from(unwrap(fb)); } -/** - * First GPUAttachment in *config is always the depth/depth_stencil buffer. - * Following GPUAttachments are color buffers. - * Setting GPUAttachment.mip to -1 will leave the texture in this slot. - * Setting GPUAttachment.tex to NULL will detach the texture in this slot. - */ void GPU_framebuffer_config_array(GPUFrameBuffer *gpu_fb, const GPUAttachment *config, int config_len) @@ -341,11 +328,6 @@ void GPU_framebuffer_config_array(GPUFrameBuffer *gpu_fb, /* ---------- Viewport & Scissor Region ----------- */ -/** - * Viewport and scissor size is stored per frame-buffer. - * It is only reset to its original dimensions explicitly OR when binding the frame-buffer after - * modifying its attachments. - */ void GPU_framebuffer_viewport_set(GPUFrameBuffer *gpu_fb, int x, int y, int width, int height) { int viewport_rect[4] = {x, y, width, height}; @@ -357,9 +339,6 @@ void GPU_framebuffer_viewport_get(GPUFrameBuffer *gpu_fb, int r_viewport[4]) unwrap(gpu_fb)->viewport_get(r_viewport); } -/** - * Reset to its attachment(s) size. - */ void GPU_framebuffer_viewport_reset(GPUFrameBuffer *gpu_fb) { unwrap(gpu_fb)->viewport_reset(); @@ -376,9 +355,6 @@ void GPU_framebuffer_clear(GPUFrameBuffer *gpu_fb, unwrap(gpu_fb)->clear(buffers, clear_col, clear_depth, clear_stencil); } -/** - * Clear all textures attached to this frame-buffer with a different color. - */ void GPU_framebuffer_multi_clear(GPUFrameBuffer *gpu_fb, const float (*clear_cols)[4]) { unwrap(gpu_fb)->clear_multi(clear_cols); @@ -425,7 +401,6 @@ void GPU_frontbuffer_read_pixels( Context::get()->front_left->read(GPU_COLOR_BIT, format, rect, channels, 0, data); } -/* read_slot and write_slot are only used for color buffers. */ /* TODO(fclem): port as texture operation. */ void GPU_framebuffer_blit(GPUFrameBuffer *gpufb_read, int read_slot, @@ -466,11 +441,6 @@ void GPU_framebuffer_blit(GPUFrameBuffer *gpufb_read, prev_fb->bind(true); } -/** - * Use this if you need to custom down-sample your texture and use the previous mip-level as - * input. This function only takes care of the correct texture handling. It execute the callback - * for each texture level. - */ void GPU_framebuffer_recursive_downsample(GPUFrameBuffer *gpu_fb, int max_lvl, void (*callback)(void *userData, int level), @@ -704,9 +674,6 @@ GPUTexture *GPU_offscreen_color_texture(const GPUOffScreen *ofs) return ofs->color; } -/** - * \note only to be used by viewport code! - */ void GPU_offscreen_viewport_data_get(GPUOffScreen *ofs, GPUFrameBuffer **r_fb, GPUTexture **r_color, diff --git a/source/blender/gpu/intern/gpu_immediate.cc b/source/blender/gpu/intern/gpu_immediate.cc index cdd56a117db..7ca93252683 100644 --- a/source/blender/gpu/intern/gpu_immediate.cc +++ b/source/blender/gpu/intern/gpu_immediate.cc @@ -89,7 +89,6 @@ void immUnbindProgram() imm->shader = nullptr; } -/* XXX do not use it. Special hack to use OCIO with batch API. */ GPUShader *immGetShader() { return imm->shader; @@ -603,7 +602,6 @@ void immUniform4fv(const char *name, const float data[4]) GPU_shader_uniform_4fv(imm->shader, name, data); } -/* Note array index is not supported for name (i.e: "array[0]"). */ void immUniformArray4fv(const char *name, const float *data, int count) { GPU_shader_uniform_4fv_array(imm->shader, name, count, (const float(*)[4])data); diff --git a/source/blender/gpu/intern/gpu_immediate_util.c b/source/blender/gpu/intern/gpu_immediate_util.c index df18b89bd67..4ef7492428e 100644 --- a/source/blender/gpu/intern/gpu_immediate_util.c +++ b/source/blender/gpu/intern/gpu_immediate_util.c @@ -143,17 +143,6 @@ void immRecti_complete(int x1, int y1, int x2, int y2, const float color[4]) } #endif -/** - * Pack color into 3 bytes - * - * This define converts a numerical value to the equivalent 24-bit - * color, while not being endian-sensitive. On little-endian, this - * is the same as doing a 'naive' indexing, on big-endian, it is not! - * - * \note BGR format (i.e. 0xBBGGRR)... - * - * \param x: color. - */ void imm_cpack(uint x) { immUniformColor3ub(((x)&0xFF), (((x) >> 8) & 0xFF), (((x) >> 16) & 0xFF)); @@ -175,31 +164,11 @@ static void imm_draw_circle(GPUPrimType prim_type, immEnd(); } -/** - * Draw a circle outline with the given \a radius. - * The circle is centered at \a x, \a y and drawn in the XY plane. - * - * \param shdr_pos: The vertex attribute number for position. - * \param x: Horizontal center. - * \param y: Vertical center. - * \param rad: The circle's radius. - * \param nsegments: The number of segments to use in drawing (more = smoother). - */ void imm_draw_circle_wire_2d(uint shdr_pos, float x, float y, float rad, int nsegments) { imm_draw_circle(GPU_PRIM_LINE_LOOP, shdr_pos, x, y, rad, rad, nsegments); } -/** - * Draw a filled circle with the given \a radius. - * The circle is centered at \a x, \a y and drawn in the XY plane. - * - * \param shdr_pos: The vertex attribute number for position. - * \param x: Horizontal center. - * \param y: Vertical center. - * \param rad: The circle's radius. - * \param nsegments: The number of segments to use in drawing (more = smoother). - */ void imm_draw_circle_fill_2d(uint shdr_pos, float x, float y, float rad, int nsegments) { imm_draw_circle(GPU_PRIM_TRI_FAN, shdr_pos, x, y, rad, rad, nsegments); @@ -274,21 +243,6 @@ static void imm_draw_disk_partial(GPUPrimType prim_type, immEnd(); } -/** - * Draw a filled arc with the given inner and outer radius. - * The circle is centered at \a x, \a y and drawn in the XY plane. - * - * \note Arguments are `gluPartialDisk` compatible. - * - * \param pos: The vertex attribute number for position. - * \param x: Horizontal center. - * \param y: Vertical center. - * \param rad_inner: The inner circle's radius. - * \param rad_outer: The outer circle's radius (can be zero). - * \param nsegments: The number of segments to use in drawing (more = smoother). - * \param start: Specifies the starting angle, in degrees, of the disk portion. - * \param sweep: Specifies the sweep angle, in degrees, of the disk portion. - */ void imm_draw_disk_partial_fill_2d(uint pos, float x, float y, @@ -328,15 +282,6 @@ void imm_draw_circle_fill_3d(uint pos, float x, float y, float rad, int nsegment imm_draw_circle_3D(GPU_PRIM_TRI_FAN, pos, x, y, rad, nsegments); } -/** - * Draw a lined box. - * - * \param pos: The vertex attribute number for position. - * \param x1: left. - * \param y1: bottom. - * \param x2: right. - * \param y2: top. - */ void imm_draw_box_wire_2d(uint pos, float x1, float y1, float x2, float y2) { immBegin(GPU_PRIM_LINE_LOOP, 4); @@ -358,9 +303,6 @@ void imm_draw_box_wire_3d(uint pos, float x1, float y1, float x2, float y2) immEnd(); } -/** - * Draw a standard checkerboard to indicate transparent backgrounds. - */ void imm_draw_box_checker_2d_ex(float x1, float y1, float x2, @@ -458,18 +400,6 @@ void imm_draw_cube_corners_3d(uint pos, immEnd(); } -/** - * Draw a cylinder. Replacement for gluCylinder. - * _warning_ : Slow, better use it only if you no other choices. - * - * \param pos: The vertex attribute number for position. - * \param nor: The vertex attribute number for normal. - * \param base: Specifies the radius of the cylinder at z = 0. - * \param top: Specifies the radius of the cylinder at z = height. - * \param height: Specifies the height of the cylinder. - * \param slices: Specifies the number of subdivisions around the z axis. - * \param stacks: Specifies the number of subdivisions along the z axis. - */ void imm_draw_cylinder_fill_normal_3d( uint pos, uint nor, float base, float top, float height, int slices, int stacks) { diff --git a/source/blender/gpu/intern/gpu_material.c b/source/blender/gpu/intern/gpu_material.c index 6872a08e854..3804f2f0dd1 100644 --- a/source/blender/gpu/intern/gpu_material.c +++ b/source/blender/gpu/intern/gpu_material.c @@ -115,7 +115,6 @@ enum { /* Functions */ -/* Returns the address of the future pointer to coba_tex */ GPUTexture **gpu_material_ramp_texture_row_set(GPUMaterial *mat, int size, float *pixels, @@ -212,7 +211,6 @@ GPUShader *GPU_material_get_shader(GPUMaterial *material) return material->pass ? GPU_pass_shader_get(material->pass) : NULL; } -/* Return can be NULL if it's a world material. */ Material *GPU_material_get_material(GPUMaterial *material) { return material->ma; @@ -223,11 +221,6 @@ GPUUniformBuf *GPU_material_uniform_buffer_get(GPUMaterial *material) return material->ubo; } -/** - * Create dynamic UBO from parameters - * - * \param inputs: Items are #LinkData, data is #GPUInput (`BLI_genericNodeN(GPUInput)`). - */ void GPU_material_uniform_buffer_create(GPUMaterial *material, ListBase *inputs) { #ifndef NDEBUG @@ -545,7 +538,6 @@ GSet *gpu_material_used_libraries(GPUMaterial *material) return material->used_libraries; } -/* Return true if the material compilation has not yet begin or begin. */ eGPUMaterialStatus GPU_material_status(GPUMaterial *mat) { return mat->status; @@ -592,11 +584,6 @@ GPUMaterial *GPU_material_from_nodetree_find(ListBase *gpumaterials, return NULL; } -/** - * \note Caller must use #GPU_material_from_nodetree_find to re-use existing materials, - * This is enforced since constructing other arguments to this function may be expensive - * so only do this when they are needed. - */ GPUMaterial *GPU_material_from_nodetree(Scene *scene, struct Material *ma, struct bNodeTree *ntree, diff --git a/source/blender/gpu/intern/gpu_matrix.cc b/source/blender/gpu/intern/gpu_matrix.cc index 0cc0e944301..8004455fbdc 100644 --- a/source/blender/gpu/intern/gpu_matrix.cc +++ b/source/blender/gpu/intern/gpu_matrix.cc @@ -733,9 +733,6 @@ float GPU_polygon_offset_calc(const float (*winmat)[4], float viewdist, float di return winmat[3][2] * -0.0025f * dist; } -/** - * \note \a viewdist is only for ortho at the moment. - */ void GPU_polygon_offset(float viewdist, float dist) { static float winmat[4][4], offset = 0.0f; diff --git a/source/blender/gpu/intern/gpu_node_graph.c b/source/blender/gpu/intern/gpu_node_graph.c index 585cb296bac..50ff450ac79 100644 --- a/source/blender/gpu/intern/gpu_node_graph.c +++ b/source/blender/gpu/intern/gpu_node_graph.c @@ -791,7 +791,6 @@ static void gpu_node_free(GPUNode *node) MEM_freeN(node); } -/* Free intermediate node graph. */ void gpu_node_graph_free_nodes(GPUNodeGraph *graph) { GPUNode *node; @@ -803,7 +802,6 @@ void gpu_node_graph_free_nodes(GPUNodeGraph *graph) graph->outlink = NULL; } -/* Free both node graph and requested attributes and textures. */ void gpu_node_graph_free(GPUNodeGraph *graph) { BLI_freelistN(&graph->outlink_aovs); diff --git a/source/blender/gpu/intern/gpu_node_graph.h b/source/blender/gpu/intern/gpu_node_graph.h index 929191cff73..8a112ac9c4d 100644 --- a/source/blender/gpu/intern/gpu_node_graph.h +++ b/source/blender/gpu/intern/gpu_node_graph.h @@ -167,12 +167,21 @@ typedef struct GPUNodeGraph { void gpu_node_graph_prune_unused(GPUNodeGraph *graph); void gpu_node_graph_finalize_uniform_attrs(GPUNodeGraph *graph); +/** + * Free intermediate node graph. + */ void gpu_node_graph_free_nodes(GPUNodeGraph *graph); +/** + * Free both node graph and requested attributes and textures. + */ void gpu_node_graph_free(GPUNodeGraph *graph); /* Material calls */ struct GPUNodeGraph *gpu_material_node_graph(struct GPUMaterial *material); +/** + * Returns the address of the future pointer to coba_tex. + */ struct GPUTexture **gpu_material_ramp_texture_row_set(struct GPUMaterial *mat, int size, float *pixels, diff --git a/source/blender/gpu/intern/gpu_platform.cc b/source/blender/gpu/intern/gpu_platform.cc index 907dfa0fc1a..34834a62268 100644 --- a/source/blender/gpu/intern/gpu_platform.cc +++ b/source/blender/gpu/intern/gpu_platform.cc @@ -157,7 +157,6 @@ const char *GPU_platform_gpu_name() return GPG.gpu_name; } -/* GPU Types */ bool GPU_type_matches(eGPUDeviceType device, eGPUOSType os, eGPUDriverType driver) { BLI_assert(GPG.initialized); diff --git a/source/blender/gpu/intern/gpu_select.c b/source/blender/gpu/intern/gpu_select.c index 3c89f082e9b..aadb52fb49c 100644 --- a/source/blender/gpu/intern/gpu_select.c +++ b/source/blender/gpu/intern/gpu_select.c @@ -71,9 +71,6 @@ static GPUSelectState g_select_state = {0}; /** \name Public API * \{ */ -/** - * initialize and provide buffer for results - */ void GPU_select_begin(uint *buffer, uint bufsize, const rcti *input, char mode, int oldhits) { if (mode == GPU_SELECT_NEAREST_SECOND_PASS) { @@ -107,14 +104,6 @@ void GPU_select_begin(uint *buffer, uint bufsize, const rcti *input, char mode, } } -/** - * loads a new selection id and ends previous query, if any. - * In second pass of selection it also returns - * if id has been hit on the first pass already. - * Thus we can skip drawing un-hit objects. - * - * \warning We rely on the order of object rendering on passes to be the same for this to work. - */ bool GPU_select_load_id(uint id) { /* if no selection mode active, ignore */ @@ -133,11 +122,6 @@ bool GPU_select_load_id(uint id) } } -/** - * Cleanup and flush selection results to buffer. - * Return number of hits and hits in buffer. - * if \a dopass is true, we will do a second pass with occlusion queries to get the closest hit. - */ uint GPU_select_end(void) { uint hits = 0; @@ -205,12 +189,6 @@ bool GPU_select_is_cached(void) /** \name Utilities * \{ */ -/** - * Helper function, nothing special but avoids doing inline since hits aren't sorted by depth - * and purpose of 4x buffer indices isn't so clear. - * - * Note that comparing depth as uint is fine. - */ const uint *GPU_select_buffer_near(const uint *buffer, int hits) { const uint *buffer_near = NULL; @@ -244,7 +222,6 @@ uint GPU_select_buffer_remove_by_id(uint *buffer, int hits, uint select_id) return hits_final; } -/* Part of the solution copied from `rect_subregion_stride_calc`. */ void GPU_select_buffer_stride_realign(const rcti *src, const rcti *dst, uint *r_buf) { const int x = dst->xmin - src->xmin; diff --git a/source/blender/gpu/intern/gpu_select_pick.c b/source/blender/gpu/intern/gpu_select_pick.c index a8907859bf4..737e4c6e874 100644 --- a/source/blender/gpu/intern/gpu_select_pick.c +++ b/source/blender/gpu/intern/gpu_select_pick.c @@ -730,7 +730,6 @@ void gpu_select_pick_cache_end(void) BLI_freelistN(&g_pick_state.cache.bufs); } -/* is drawing needed? */ bool gpu_select_pick_is_cached(void) { return g_pick_state.is_cached; diff --git a/source/blender/gpu/intern/gpu_select_private.h b/source/blender/gpu/intern/gpu_select_private.h index e49feb3fc50..e5a84a037a6 100644 --- a/source/blender/gpu/intern/gpu_select_private.h +++ b/source/blender/gpu/intern/gpu_select_private.h @@ -30,16 +30,21 @@ extern "C" { #endif /* gpu_select_pick */ + void gpu_select_pick_begin(uint (*buffer)[4], uint bufsize, const rcti *input, char mode); bool gpu_select_pick_load_id(uint id, bool end); uint gpu_select_pick_end(void); void gpu_select_pick_cache_begin(void); void gpu_select_pick_cache_end(void); +/** + * \return true if drawing is not needed. + */ bool gpu_select_pick_is_cached(void); void gpu_select_pick_cache_load_id(void); /* gpu_select_sample_query */ + void gpu_select_query_begin( uint (*buffer)[4], uint bufsize, const rcti *input, char mode, int oldhits); bool gpu_select_query_load_id(uint id); diff --git a/source/blender/gpu/intern/gpu_shader.cc b/source/blender/gpu/intern/gpu_shader.cc index 9340d311472..1b6cb196534 100644 --- a/source/blender/gpu/intern/gpu_shader.cc +++ b/source/blender/gpu/intern/gpu_shader.cc @@ -284,26 +284,6 @@ static const char *string_join_array_maybe_alloc(const char **str_arr, bool *r_i return str_arr[0]; } -/** - * Use via #GPU_shader_create_from_arrays macro (avoids passing in param). - * - * Similar to #DRW_shader_create_with_lib with the ability to include libs for each type of shader. - * - * It has the advantage that each item can be conditionally included - * without having to build the string inline, then free it. - * - * \param params: NULL terminated arrays of strings. - * - * Example: - * \code{.c} - * sh = GPU_shader_create_from_arrays({ - * .vert = (const char *[]){shader_lib_glsl, shader_vert_glsl, NULL}, - * .geom = (const char *[]){shader_geom_glsl, NULL}, - * .frag = (const char *[]){shader_frag_glsl, NULL}, - * .defs = (const char *[]){"#define DEFINE\n", test ? "#define OTHER_DEFINE\n" : "", NULL}, - * }); - * \endcode - */ struct GPUShader *GPU_shader_create_from_arrays_impl( const struct GPU_ShaderCreateFromArray_Params *params, const char *func, int line) { @@ -431,7 +411,6 @@ int GPU_shader_get_ssbo(GPUShader *shader, const char *name) return ssbo ? ssbo->location : -1; } -/* DEPRECATED. */ int GPU_shader_get_uniform_block(GPUShader *shader, const char *name) { ShaderInterface *interface = unwrap(shader)->interface; @@ -466,7 +445,6 @@ int GPU_shader_get_attribute(GPUShader *shader, const char *name) /** \name Getters * \{ */ -/* DEPRECATED: Kept only because of BGL API */ int GPU_shader_get_program(GPUShader *shader) { return unwrap(shader)->program_handle_get(); diff --git a/source/blender/gpu/intern/gpu_shader_interface.cc b/source/blender/gpu/intern/gpu_shader_interface.cc index ae94112b17b..1648446d21b 100644 --- a/source/blender/gpu/intern/gpu_shader_interface.cc +++ b/source/blender/gpu/intern/gpu_shader_interface.cc @@ -65,11 +65,12 @@ static void sort_input_list(MutableSpan<ShaderInput> dst) } } -/* Sorts all inputs inside their respective array. - * This is to allow fast hash collision detection. - * See ShaderInterface::input_lookup for more details. */ void ShaderInterface::sort_inputs() { + /* Sorts all inputs inside their respective array. + * This is to allow fast hash collision detection. + * See `ShaderInterface::input_lookup` for more details. */ + sort_input_list(MutableSpan<ShaderInput>(inputs_, attr_len_)); sort_input_list(MutableSpan<ShaderInput>(inputs_ + attr_len_, ubo_len_)); sort_input_list(MutableSpan<ShaderInput>(inputs_ + attr_len_ + ubo_len_, uniform_len_)); diff --git a/source/blender/gpu/intern/gpu_shader_interface.hh b/source/blender/gpu/intern/gpu_shader_interface.hh index ebed7b15170..12a7ffabcc6 100644 --- a/source/blender/gpu/intern/gpu_shader_interface.hh +++ b/source/blender/gpu/intern/gpu_shader_interface.hh @@ -130,7 +130,9 @@ class ShaderInterface { inline uint32_t set_input_name(ShaderInput *input, char *name, uint32_t name_len) const; - /* Finalize interface construction by sorting the ShaderInputs for faster lookups. */ + /** + * Finalize interface construction by sorting the #ShaderInputs for faster lookups. + */ void sort_inputs(void); private: diff --git a/source/blender/gpu/intern/gpu_state.cc b/source/blender/gpu/intern/gpu_state.cc index 9ee8a8b8d32..a43ddb09ff8 100644 --- a/source/blender/gpu/intern/gpu_state.cc +++ b/source/blender/gpu/intern/gpu_state.cc @@ -165,11 +165,6 @@ void GPU_depth_range(float near, float far) copy_v2_fl2(state.depth_range, near, far); } -/** - * \note By convention, this is set as needed and not reset back to 1.0. - * This means code that draws lines must always set the line width beforehand, - * but is not expected to restore it's previous value. - */ void GPU_line_width(float width) { width = max_ff(1.0f, width * PIXELSIZE); @@ -184,10 +179,6 @@ void GPU_point_size(float size) state.point_size = size * ((state.point_size > 0.0) ? 1.0f : -1.0f); } -/* Programmable point size - * - shaders set their own point size when enabled - * - use GPU_point_size when disabled */ -/* TODO: remove and use program point size everywhere. */ void GPU_program_point_size(bool enable) { StateManager *stack = Context::get()->state_manager; @@ -264,7 +255,6 @@ eGPUStencilTest GPU_stencil_test_get() return (eGPUStencilTest)state.stencil_test; } -/* NOTE: Already premultiplied by U.pixelsize. */ float GPU_line_width_get() { const GPUStateMutable &state = Context::get()->state_manager->mutable_state; @@ -363,7 +353,6 @@ void GPU_bgl_start() } } -/* Just turn off the bgl safeguard system. Can be called even without GPU_bgl_start. */ void GPU_bgl_end() { Context *ctx = Context::get(); diff --git a/source/blender/gpu/intern/gpu_texture.cc b/source/blender/gpu/intern/gpu_texture.cc index 2744c0c5e17..c7e2043b790 100644 --- a/source/blender/gpu/intern/gpu_texture.cc +++ b/source/blender/gpu/intern/gpu_texture.cc @@ -298,7 +298,6 @@ GPUTexture *GPU_texture_create_cube_array( name, w, w, d, GPU_TEXTURE_CUBE_ARRAY, mip_len, format, GPU_DATA_FLOAT, data); } -/* DDS texture loading. Return NULL if support is not available. */ GPUTexture *GPU_texture_create_compressed_2d( const char *name, int w, int h, int miplen, eGPUTextureFormat tex_format, const void *data) { @@ -337,7 +336,6 @@ GPUTexture *GPU_texture_create_from_vertbuf(const char *name, GPUVertBuf *vert) return reinterpret_cast<GPUTexture *>(tex); } -/* Create an error texture that will bind an invalid texture (pink) at draw time. */ GPUTexture *GPU_texture_create_error(int dimension, bool is_array) { float pixel[4] = {1.0f, 0.0f, 1.0f, 1.0f}; @@ -386,27 +384,17 @@ void *GPU_texture_read(GPUTexture *tex_, eGPUDataFormat data_format, int miplvl) return tex->read(miplvl, data_format); } -/** - * Fills the whole texture with the same data for all pixels. - * \warning Only work for 2D texture for now. - * \warning Only clears the mip 0 of the texture. - * \param data_format: data format of the pixel data. - * \param data: 1 pixel worth of data to fill the texture with. - */ void GPU_texture_clear(GPUTexture *tex, eGPUDataFormat data_format, const void *data) { BLI_assert(data != nullptr); /* Do not accept NULL as parameter. */ reinterpret_cast<Texture *>(tex)->clear(data_format, data); } -/* NOTE: Updates only mip 0. */ void GPU_texture_update(GPUTexture *tex, eGPUDataFormat data_format, const void *data) { reinterpret_cast<Texture *>(tex)->update(data_format, data); } -/* Makes data interpretation aware of the source layout. - * Skipping pixels correctly when changing rows when doing partial update. */ void GPU_unpack_row_length_set(uint len) { Context::get()->state_manager->texture_unpack_row_length_set(len); @@ -461,7 +449,6 @@ void GPU_texture_generate_mipmap(GPUTexture *tex) reinterpret_cast<Texture *>(tex)->generate_mipmap(); } -/* Copy a texture content to a similar texture. Only MIP 0 is copied. */ void GPU_texture_copy(GPUTexture *dst_, GPUTexture *src_) { Texture *src = reinterpret_cast<Texture *>(src_); @@ -626,7 +613,6 @@ void GPU_texture_get_mipmap_size(GPUTexture *tex, int lvl, int *r_size) * Override texture sampler state for one sampler unit only. * \{ */ -/* Update user defined sampler states. */ void GPU_samplers_update(void) { GPUBackend::get()->samplers_update(); diff --git a/source/blender/gpu/intern/gpu_uniform_buffer.cc b/source/blender/gpu/intern/gpu_uniform_buffer.cc index 6f2e9838955..332875ba81f 100644 --- a/source/blender/gpu/intern/gpu_uniform_buffer.cc +++ b/source/blender/gpu/intern/gpu_uniform_buffer.cc @@ -201,12 +201,6 @@ GPUUniformBuf *GPU_uniformbuf_create_ex(size_t size, const void *data, const cha return wrap(ubo); } -/** - * Create UBO from inputs list. - * Return NULL if failed to create or if \param inputs: is empty. - * - * \param inputs: ListBase of #BLI_genericNodeN(#GPUInput). - */ GPUUniformBuf *GPU_uniformbuf_create_from_list(ListBase *inputs, const char *name) { /* There is no point on creating an UBO if there is no arguments. */ diff --git a/source/blender/gpu/intern/gpu_vertex_buffer.cc b/source/blender/gpu/intern/gpu_vertex_buffer.cc index 7ff68242c17..5ed9648387f 100644 --- a/source/blender/gpu/intern/gpu_vertex_buffer.cc +++ b/source/blender/gpu/intern/gpu_vertex_buffer.cc @@ -159,7 +159,6 @@ void *GPU_vertbuf_unmap(const GPUVertBuf *verts, const void *mapped_data) return unwrap(verts)->unmap(mapped_data); } -/** Same as discard but does not free. */ void GPU_vertbuf_clear(GPUVertBuf *verts) { unwrap(verts)->clear(); @@ -183,21 +182,16 @@ void GPU_vertbuf_handle_ref_remove(GPUVertBuf *verts) /* -------- Data update -------- */ -/* create a new allocation, discarding any existing data */ void GPU_vertbuf_data_alloc(GPUVertBuf *verts, uint v_len) { unwrap(verts)->allocate(v_len); } -/* resize buffer keeping existing data */ void GPU_vertbuf_data_resize(GPUVertBuf *verts, uint v_len) { unwrap(verts)->resize(v_len); } -/* Set vertex count but does not change allocation. - * Only this many verts will be uploaded to the GPU and rendered. - * This is useful for streaming data. */ void GPU_vertbuf_data_len_set(GPUVertBuf *verts_, uint v_len) { VertBuf *verts = unwrap(verts_); @@ -229,7 +223,6 @@ void GPU_vertbuf_attr_fill(GPUVertBuf *verts_, uint a_idx, const void *data) GPU_vertbuf_attr_fill_stride(verts_, a_idx, stride, data); } -/** Fills a whole vertex (all attributes). Data must match packed layout. */ void GPU_vertbuf_vert_set(GPUVertBuf *verts_, uint v_idx, const void *data) { VertBuf *verts = unwrap(verts_); @@ -284,15 +277,12 @@ void GPU_vertbuf_attr_get_raw_data(GPUVertBuf *verts_, uint a_idx, GPUVertBufRaw /* -------- Getters -------- */ -/* NOTE: Be careful when using this. The data needs to match the expected format. */ void *GPU_vertbuf_get_data(const GPUVertBuf *verts) { /* TODO: Assert that the format has no padding. */ return unwrap(verts)->data; } -/* Returns the data buffer and set it to null internally to avoid freeing. - * NOTE: Be careful when using this. The data needs to match the expected format. */ void *GPU_vertbuf_steal_data(GPUVertBuf *verts_) { VertBuf *verts = unwrap(verts_); @@ -328,7 +318,6 @@ uint GPU_vertbuf_get_memory_usage() return VertBuf::memory_usage; } -/* Should be rename to GPU_vertbuf_data_upload */ void GPU_vertbuf_use(GPUVertBuf *verts) { unwrap(verts)->upload(); @@ -339,8 +328,6 @@ void GPU_vertbuf_bind_as_ssbo(struct GPUVertBuf *verts, int binding) unwrap(verts)->bind_as_ssbo(binding); } -/* XXX this is just a wrapper for the use of the Hair refine workaround. - * To be used with GPU_vertbuf_use(). */ void GPU_vertbuf_update_sub(GPUVertBuf *verts, uint start, uint len, void *data) { unwrap(verts)->update_sub(start, len, data); diff --git a/source/blender/gpu/intern/gpu_vertex_format.cc b/source/blender/gpu/intern/gpu_vertex_format.cc index 78a119bcec8..ad45f2a4d7b 100644 --- a/source/blender/gpu/intern/gpu_vertex_format.cc +++ b/source/blender/gpu/intern/gpu_vertex_format.cc @@ -190,17 +190,6 @@ void GPU_vertformat_alias_add(GPUVertFormat *format, const char *alias) attr->names[attr->name_len++] = copy_attr_name(format, alias); } -/** - * Makes vertex attribute from the next vertices to be accessible in the vertex shader. - * For an attribute named "attr" you can access the next nth vertex using "attr{number}". - * Use this function after specifying all the attributes in the format. - * - * NOTE: This does NOT work when using indexed rendering. - * NOTE: Only works for first attribute name. (this limitation can be changed if needed) - * - * WARNING: this function creates a lot of aliases/attributes, make sure to keep the attribute - * name short to avoid overflowing the name-buffer. - */ void GPU_vertformat_multiload_enable(GPUVertFormat *format, int load_count) { /* Sanity check. Maximum can be upgraded if needed. */ @@ -271,8 +260,6 @@ static void safe_bytes(char out[11], const char data[8]) } } -/* Warning: Always add a prefix to the result of this function as - * the generated string can start with a number and not be a valid attribute name. */ void GPU_vertformat_safe_attr_name(const char *attr_name, char *r_safe_name, uint UNUSED(max_len)) { char data[8] = {0}; @@ -306,20 +293,6 @@ void GPU_vertformat_safe_attr_name(const char *attr_name, char *r_safe_name, uin #endif } -/** - * Make attribute layout non-interleaved. - * Warning! This does not change data layout! - * Use direct buffer access to fill the data. - * This is for advanced usage. - * - * De-interleaved data means all attribute data for each attribute - * is stored continuously like this: - * 000011112222 - * instead of: - * 012012012012 - * - * \note This is per attribute de-interleaving, NOT per component. - */ void GPU_vertformat_deinterleave(GPUVertFormat *format) { /* Ideally we should change the stride and offset here. This would allow diff --git a/source/blender/gpu/intern/gpu_viewport.c b/source/blender/gpu/intern/gpu_viewport.c index c9dbb94eb87..c604859fa94 100644 --- a/source/blender/gpu/intern/gpu_viewport.c +++ b/source/blender/gpu/intern/gpu_viewport.c @@ -194,7 +194,6 @@ void GPU_viewport_bind(GPUViewport *viewport, int view, const rcti *rect) viewport->active_view = view; } -/* Should be called from DRW after DRW_opengl_context_enable. */ void GPU_viewport_bind_from_offscreen(GPUViewport *viewport, struct GPUOffScreen *ofs) { GPUTexture *color, *depth; @@ -258,7 +257,6 @@ void GPU_viewport_colorspace_set(GPUViewport *viewport, viewport->do_color_management = true; } -/* Merge the stereo textures. `color` and `overlay` texture will be modified. */ void GPU_viewport_stereo_composite(GPUViewport *viewport, Stereo3dFormat *stereo_format) { if (!ELEM(stereo_format->display_mode, S3D_DISPLAY_ANAGLYPH, S3D_DISPLAY_INTERLACE)) { @@ -452,10 +450,6 @@ static void gpu_viewport_draw_colormanaged(GPUViewport *viewport, } } -/** - * Version of #GPU_viewport_draw_to_screen() that lets caller decide if display colorspace - * transform should be performed. - */ void GPU_viewport_draw_to_screen_ex(GPUViewport *viewport, int view, const rcti *rect, @@ -508,21 +502,11 @@ void GPU_viewport_draw_to_screen_ex(GPUViewport *viewport, viewport, view, &pos_rect, &uv_rect, display_colorspace, do_overlay_merge); } -/** - * Merge and draw the buffers of \a viewport into the currently active framebuffer, performing - * color transform to display space. - * - * \param rect: Coordinates to draw into. By swapping min and max values, drawing can be done - * with inversed axis coordinates (upside down or sideways). - */ void GPU_viewport_draw_to_screen(GPUViewport *viewport, int view, const rcti *rect) { GPU_viewport_draw_to_screen_ex(viewport, view, rect, true, true); } -/** - * Clear vars assigned from offscreen, so we don't free data owned by `GPUOffScreen`. - */ void GPU_viewport_unbind_from_offscreen(GPUViewport *viewport, struct GPUOffScreen *ofs, bool display_colorspace, @@ -587,7 +571,6 @@ GPUTexture *GPU_viewport_depth_texture(GPUViewport *viewport) return viewport->depth_tx; } -/* Overlay framebuffer for drawing outside of DRW module. */ GPUFrameBuffer *GPU_viewport_framebuffer_overlay_get(GPUViewport *viewport) { GPU_framebuffer_ensure_config( @@ -599,7 +582,6 @@ GPUFrameBuffer *GPU_viewport_framebuffer_overlay_get(GPUViewport *viewport) return viewport->overlay_fb; } -/* Must be executed inside Draw-manager OpenGL Context. */ void GPU_viewport_free(GPUViewport *viewport) { if (viewport->draw_data) { 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, |