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