From ffc4c126f5416b04a01653e7a03451797b98aba4 Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Tue, 7 Dec 2021 17:19:15 +1100 Subject: Cleanup: move public doc-strings into headers for 'blenkernel' - Added space below non doc-string comments to make it clear these aren't comments for the symbols directly below them. - Use doxy sections for some headers. - Minor improvements to doc-strings. Ref T92709 --- source/blender/blenkernel/BKE_DerivedMesh.h | 80 +++- source/blender/blenkernel/BKE_action.h | 182 +++++++-- source/blender/blenkernel/BKE_anim_data.h | 63 +++- source/blender/blenkernel/BKE_anim_path.h | 11 +- source/blender/blenkernel/BKE_anim_visualization.h | 21 ++ source/blender/blenkernel/BKE_animsys.h | 60 ++- source/blender/blenkernel/BKE_appdir.h | 100 ++++- source/blender/blenkernel/BKE_armature.h | 193 +++++++++- source/blender/blenkernel/BKE_asset.h | 3 + source/blender/blenkernel/BKE_asset_catalog.hh | 3 + source/blender/blenkernel/BKE_attribute_access.hh | 9 + source/blender/blenkernel/BKE_autoexec.h | 4 + source/blender/blenkernel/BKE_blender.h | 11 + source/blender/blenkernel/BKE_blender_copybuffer.h | 40 +- source/blender/blenkernel/BKE_blendfile.h | 43 ++- .../blender/blenkernel/BKE_blendfile_link_append.h | 106 +++++- source/blender/blenkernel/BKE_boids.h | 6 + source/blender/blenkernel/BKE_brush.h | 71 +++- source/blender/blenkernel/BKE_bvhutils.h | 63 +++- source/blender/blenkernel/BKE_cachefile.h | 6 + source/blender/blenkernel/BKE_callbacks.h | 3 + source/blender/blenkernel/BKE_camera.h | 27 +- source/blender/blenkernel/BKE_cloth.h | 2 + source/blender/blenkernel/BKE_collection.h | 112 ++++++ source/blender/blenkernel/BKE_collision.h | 20 +- source/blender/blenkernel/BKE_colortools.h | 73 +++- source/blender/blenkernel/BKE_constraint.h | 109 +++++- source/blender/blenkernel/BKE_context.h | 33 +- source/blender/blenkernel/BKE_crazyspace.h | 8 + source/blender/blenkernel/BKE_cryptomatte.h | 3 + source/blender/blenkernel/BKE_cryptomatte.hh | 20 +- source/blender/blenkernel/BKE_curve.h | 104 ++++++ source/blender/blenkernel/BKE_curve_to_mesh.hh | 14 + source/blender/blenkernel/BKE_curveprofile.h | 83 ++++- source/blender/blenkernel/BKE_customdata.h | 313 +++++++++++----- source/blender/blenkernel/BKE_data_transfer.h | 10 + source/blender/blenkernel/BKE_deform.h | 101 +++++ source/blender/blenkernel/BKE_displist.h | 6 + source/blender/blenkernel/BKE_duplilist.h | 3 + source/blender/blenkernel/BKE_dynamicpaint.h | 40 +- source/blender/blenkernel/BKE_editmesh.h | 20 + source/blender/blenkernel/BKE_editmesh_bvh.h | 10 +- source/blender/blenkernel/BKE_editmesh_tangent.h | 7 + source/blender/blenkernel/BKE_effect.h | 11 + source/blender/blenkernel/BKE_fcurve.h | 247 +++++++++++-- source/blender/blenkernel/BKE_fcurve_driver.h | 50 +++ source/blender/blenkernel/BKE_fluid.h | 4 + source/blender/blenkernel/BKE_freestyle.h | 4 + source/blender/blenkernel/BKE_geometry_set.hh | 177 +++++++++ .../blenkernel/BKE_geometry_set_instances.hh | 13 + source/blender/blenkernel/BKE_gpencil.h | 408 ++++++++++++++++++++- source/blender/blenkernel/BKE_gpencil_curve.h | 29 ++ source/blender/blenkernel/BKE_gpencil_geom.h | 270 +++++++++++++- source/blender/blenkernel/BKE_gpencil_modifier.h | 130 ++++++- source/blender/blenkernel/BKE_icons.h | 104 +++++- source/blender/blenkernel/BKE_idprop.h | 139 ++++++- source/blender/blenkernel/BKE_idtype.h | 70 ++++ source/blender/blenkernel/BKE_image.h | 217 +++++++++-- source/blender/blenkernel/BKE_ipo.h | 13 + source/blender/blenkernel/BKE_key.h | 83 +++++ source/blender/blenkernel/BKE_keyconfig.h | 12 +- source/blender/blenkernel/BKE_layer.h | 128 ++++++- source/blender/blenkernel/BKE_lib_id.h | 289 ++++++++++++++- source/blender/blenkernel/BKE_lib_override.h | 230 ++++++++++++ source/blender/blenkernel/BKE_lib_query.h | 75 +++- source/blender/blenkernel/BKE_lib_remap.h | 34 +- source/blender/blenkernel/BKE_linestyle.h | 4 + source/blender/blenkernel/BKE_main.h | 112 +++++- source/blender/blenkernel/BKE_main_idmap.h | 11 + source/blender/blenkernel/BKE_mask.h | 128 ++++++- source/blender/blenkernel/BKE_material.h | 88 ++++- source/blender/blenkernel/BKE_mball.h | 42 +++ source/blender/blenkernel/BKE_mesh.h | 343 ++++++++++++++++- .../blender/blenkernel/BKE_mesh_boolean_convert.hh | 10 + source/blender/blenkernel/BKE_mesh_iterators.h | 5 + source/blender/blenkernel/BKE_mesh_mapping.h | 79 +++- source/blender/blenkernel/BKE_mesh_mirror.h | 4 + source/blender/blenkernel/BKE_mesh_remap.h | 13 + source/blender/blenkernel/BKE_mesh_runtime.h | 26 ++ source/blender/blenkernel/BKE_mesh_tangent.h | 21 ++ source/blender/blenkernel/BKE_modifier.h | 70 +++- source/blender/blenkernel/BKE_movieclip.h | 30 +- source/blender/blenkernel/BKE_multires.h | 72 +++- source/blender/blenkernel/BKE_nla.h | 198 +++++++++- source/blender/blenkernel/BKE_node.h | 199 +++++++++- source/blender/blenkernel/BKE_object.h | 264 ++++++++++++- source/blender/blenkernel/BKE_object_deform.h | 88 ++++- source/blender/blenkernel/BKE_ocean.h | 42 ++- source/blender/blenkernel/BKE_packedFile.h | 44 ++- source/blender/blenkernel/BKE_paint.h | 103 +++++- source/blender/blenkernel/BKE_particle.h | 111 +++++- source/blender/blenkernel/BKE_pbvh.h | 75 +++- source/blender/blenkernel/BKE_pointcache.h | 81 +++- source/blender/blenkernel/BKE_preferences.h | 10 + source/blender/blenkernel/BKE_report.h | 7 +- source/blender/blenkernel/BKE_rigidbody.h | 43 ++- source/blender/blenkernel/BKE_scene.h | 122 +++++- source/blender/blenkernel/BKE_screen.h | 78 +++- source/blender/blenkernel/BKE_shader_fx.h | 22 +- source/blender/blenkernel/BKE_shrinkwrap.h | 76 ++-- source/blender/blenkernel/BKE_softbody.h | 39 +- source/blender/blenkernel/BKE_spline.hh | 48 +++ source/blender/blenkernel/BKE_studiolight.h | 8 + source/blender/blenkernel/BKE_subsurf.h | 18 +- source/blender/blenkernel/BKE_text.h | 48 ++- source/blender/blenkernel/BKE_texture.h | 12 + source/blender/blenkernel/BKE_tracking.h | 267 +++++++++++++- source/blender/blenkernel/BKE_undo_system.h | 98 ++++- source/blender/blenkernel/BKE_unit.h | 54 ++- source/blender/blenkernel/BKE_vfont.h | 3 + source/blender/blenkernel/BKE_vfontdata.h | 6 + source/blender/blenkernel/BKE_volume.h | 5 + source/blender/blenkernel/BKE_workspace.h | 59 ++- source/blender/blenkernel/BKE_writeavi.h | 4 + source/blender/blenkernel/intern/CCGSubSurf.c | 4 - source/blender/blenkernel/intern/CCGSubSurf.h | 17 + .../blender/blenkernel/intern/CCGSubSurf_legacy.c | 4 - source/blender/blenkernel/intern/DerivedMesh.cc | 35 +- source/blender/blenkernel/intern/action.c | 104 ------ source/blender/blenkernel/intern/anim_data.c | 83 +---- source/blender/blenkernel/intern/anim_path.c | 8 - source/blender/blenkernel/intern/anim_sys.c | 71 ---- .../blender/blenkernel/intern/anim_visualization.c | 14 - source/blender/blenkernel/intern/appdir.c | 93 +---- source/blender/blenkernel/intern/armature.c | 190 ---------- source/blender/blenkernel/intern/armature_deform.c | 1 - source/blender/blenkernel/intern/asset.cc | 3 - source/blender/blenkernel/intern/asset_catalog.cc | 5 - .../blenkernel/intern/asset_catalog_path.cc | 2 - .../blenkernel/intern/asset_library_service.cc | 3 - .../blender/blenkernel/intern/attribute_access.cc | 13 - source/blender/blenkernel/intern/autoexec.c | 4 - source/blender/blenkernel/intern/blender.c | 9 - .../blender/blenkernel/intern/blender_copybuffer.c | 33 -- source/blender/blenkernel/intern/blendfile.c | 38 -- .../blenkernel/intern/blendfile_link_append.c | 78 ---- source/blender/blenkernel/intern/boids.c | 2 - source/blender/blenkernel/intern/brush.c | 23 -- source/blender/blenkernel/intern/bvhutils.cc | 56 --- source/blender/blenkernel/intern/cachefile.c | 6 - source/blender/blenkernel/intern/callbacks.c | 1 - source/blender/blenkernel/intern/camera.c | 5 - source/blender/blenkernel/intern/cloth.c | 3 +- source/blender/blenkernel/intern/collection.c | 110 ------ source/blender/blenkernel/intern/collision.c | 8 - source/blender/blenkernel/intern/colortools.c | 28 +- source/blender/blenkernel/intern/constraint.c | 55 --- source/blender/blenkernel/intern/context.c | 13 - source/blender/blenkernel/intern/crazyspace.c | 5 - source/blender/blenkernel/intern/cryptomatte.cc | 16 - source/blender/blenkernel/intern/curve.c | 75 ---- source/blender/blenkernel/intern/curve_deform.c | 6 - .../blenkernel/intern/curve_to_mesh_convert.cc | 14 - source/blender/blenkernel/intern/curveprofile.cc | 79 ---- source/blender/blenkernel/intern/customdata.c | 105 +----- source/blender/blenkernel/intern/data_transfer.c | 10 - .../blenkernel/intern/data_transfer_intern.h | 4 + source/blender/blenkernel/intern/deform.c | 104 +----- source/blender/blenkernel/intern/displist.cc | 6 - source/blender/blenkernel/intern/dynamicpaint.c | 20 - source/blender/blenkernel/intern/editmesh.c | 16 - source/blender/blenkernel/intern/editmesh_bvh.c | 6 - .../blender/blenkernel/intern/editmesh_tangent.c | 7 - source/blender/blenkernel/intern/effect.c | 34 +- source/blender/blenkernel/intern/fcurve.c | 108 ------ source/blender/blenkernel/intern/fcurve_cache.c | 5 - source/blender/blenkernel/intern/fcurve_driver.c | 24 -- source/blender/blenkernel/intern/fluid.c | 2 - source/blender/blenkernel/intern/fmodifier.c | 56 --- source/blender/blenkernel/intern/freestyle.c | 4 - .../blenkernel/intern/geometry_component_curve.cc | 5 - .../intern/geometry_component_instances.cc | 16 - .../blenkernel/intern/geometry_component_mesh.cc | 8 - .../intern/geometry_component_pointcloud.cc | 9 - .../blenkernel/intern/geometry_component_volume.cc | 7 - source/blender/blenkernel/intern/geometry_set.cc | 44 --- .../blenkernel/intern/geometry_set_instances.cc | 18 - source/blender/blenkernel/intern/gpencil.c | 399 -------------------- source/blender/blenkernel/intern/gpencil_curve.c | 29 -- source/blender/blenkernel/intern/gpencil_geom.cc | 269 +------------- .../blender/blenkernel/intern/gpencil_modifier.c | 130 ------- source/blender/blenkernel/intern/hair.c | 1 + source/blender/blenkernel/intern/icons.cc | 30 -- source/blender/blenkernel/intern/idprop.c | 121 ------ source/blender/blenkernel/intern/idtype.c | 71 ---- source/blender/blenkernel/intern/image.c | 70 +--- source/blender/blenkernel/intern/image_gpu.cc | 12 - source/blender/blenkernel/intern/ipo.c | 11 - source/blender/blenkernel/intern/key.c | 70 +--- source/blender/blenkernel/intern/keyconfig.c | 5 - source/blender/blenkernel/intern/layer.c | 105 ------ source/blender/blenkernel/intern/layer_utils.c | 7 - source/blender/blenkernel/intern/lib_id.c | 219 +---------- source/blender/blenkernel/intern/lib_id_delete.c | 49 --- source/blender/blenkernel/intern/lib_id_eval.c | 5 - source/blender/blenkernel/intern/lib_override.c | 196 +--------- source/blender/blenkernel/intern/lib_query.c | 70 ---- source/blender/blenkernel/intern/lib_remap.c | 34 +- source/blender/blenkernel/intern/linestyle.c | 4 - source/blender/blenkernel/intern/main.c | 104 ------ source/blender/blenkernel/intern/main_idmap.c | 12 - source/blender/blenkernel/intern/mask.c | 30 +- source/blender/blenkernel/intern/mask_evaluate.c | 5 - source/blender/blenkernel/intern/mask_rasterize.c | 3 - source/blender/blenkernel/intern/material.c | 23 -- source/blender/blenkernel/intern/mball.c | 70 +--- source/blender/blenkernel/intern/mesh.cc | 60 --- .../blenkernel/intern/mesh_boolean_convert.cc | 10 - source/blender/blenkernel/intern/mesh_convert.cc | 5 - source/blender/blenkernel/intern/mesh_evaluate.cc | 78 ---- source/blender/blenkernel/intern/mesh_iterators.c | 9 - source/blender/blenkernel/intern/mesh_mapping.c | 77 ---- source/blender/blenkernel/intern/mesh_merge.c | 32 -- source/blender/blenkernel/intern/mesh_mirror.c | 4 - source/blender/blenkernel/intern/mesh_normals.cc | 62 ---- source/blender/blenkernel/intern/mesh_remap.c | 13 - source/blender/blenkernel/intern/mesh_runtime.c | 28 +- source/blender/blenkernel/intern/mesh_tangent.c | 21 -- source/blender/blenkernel/intern/mesh_tessellate.c | 22 -- source/blender/blenkernel/intern/mesh_validate.c | 53 +-- source/blender/blenkernel/intern/mesh_validate.cc | 3 - source/blender/blenkernel/intern/modifier.c | 50 --- source/blender/blenkernel/intern/movieclip.c | 15 - source/blender/blenkernel/intern/multires.c | 15 - .../blender/blenkernel/intern/multires_reshape.c | 4 - .../blender/blenkernel/intern/multires_reshape.h | 123 +++++-- .../blenkernel/intern/multires_reshape_util.c | 7 - .../blenkernel/intern/multires_reshape_vertcos.c | 1 - source/blender/blenkernel/intern/nla.c | 140 ------- source/blender/blenkernel/intern/node.cc | 96 +---- source/blender/blenkernel/intern/object.cc | 234 ------------ source/blender/blenkernel/intern/object_deform.c | 81 +--- source/blender/blenkernel/intern/object_dupli.cc | 3 - source/blender/blenkernel/intern/object_update.c | 12 +- source/blender/blenkernel/intern/ocean.c | 12 - source/blender/blenkernel/intern/ocean_spectrum.c | 17 - source/blender/blenkernel/intern/packedFile.c | 21 -- source/blender/blenkernel/intern/paint.c | 35 -- source/blender/blenkernel/intern/paint_toolslots.c | 4 - source/blender/blenkernel/intern/particle.c | 38 +- source/blender/blenkernel/intern/particle_system.c | 22 +- source/blender/blenkernel/intern/pbvh.c | 16 - source/blender/blenkernel/intern/pbvh_bmesh.c | 6 - source/blender/blenkernel/intern/pbvh_intern.h | 9 + source/blender/blenkernel/intern/pointcache.c | 26 +- source/blender/blenkernel/intern/pointcloud.cc | 1 + source/blender/blenkernel/intern/preferences.c | 8 - source/blender/blenkernel/intern/report.c | 5 - source/blender/blenkernel/intern/rigidbody.c | 3 - source/blender/blenkernel/intern/scene.c | 71 ---- source/blender/blenkernel/intern/screen.c | 49 +-- source/blender/blenkernel/intern/shader_fx.c | 14 - source/blender/blenkernel/intern/shrinkwrap.c | 30 -- source/blender/blenkernel/intern/softbody.c | 19 - source/blender/blenkernel/intern/spline_base.cc | 35 -- source/blender/blenkernel/intern/spline_bezier.cc | 6 - source/blender/blenkernel/intern/spline_nurbs.cc | 3 - source/blender/blenkernel/intern/spline_poly.cc | 6 - source/blender/blenkernel/intern/studiolight.c | 6 +- source/blender/blenkernel/intern/subsurf_ccg.c | 5 - source/blender/blenkernel/intern/text.c | 40 +- source/blender/blenkernel/intern/texture.c | 7 - source/blender/blenkernel/intern/tracking.c | 121 ------ source/blender/blenkernel/intern/tracking_auto.c | 2 +- source/blender/blenkernel/intern/tracking_detect.c | 2 - .../blenkernel/intern/tracking_plane_tracker.c | 1 - .../blenkernel/intern/tracking_region_tracker.c | 6 - source/blender/blenkernel/intern/tracking_solver.c | 22 -- .../blender/blenkernel/intern/tracking_stabilize.c | 34 -- source/blender/blenkernel/intern/tracking_util.c | 17 - source/blender/blenkernel/intern/undo_system.c | 88 ----- source/blender/blenkernel/intern/unit.c | 17 - source/blender/blenkernel/intern/vfont.c | 5 - .../blender/blenkernel/intern/vfontdata_freetype.c | 8 - source/blender/blenkernel/intern/volume.cc | 2 - source/blender/blenkernel/intern/workspace.c | 44 --- source/blender/blenkernel/intern/writeavi.c | 1 - source/blender/blenkernel/nla_private.h | 33 +- source/blender/blenkernel/tracking_private.h | 38 +- 279 files changed, 8003 insertions(+), 6522 deletions(-) (limited to 'source/blender/blenkernel') diff --git a/source/blender/blenkernel/BKE_DerivedMesh.h b/source/blender/blenkernel/BKE_DerivedMesh.h index c95190d2c83..22b43cd19ea 100644 --- a/source/blender/blenkernel/BKE_DerivedMesh.h +++ b/source/blender/blenkernel/BKE_DerivedMesh.h @@ -242,8 +242,17 @@ struct DerivedMesh { void (*release)(DerivedMesh *dm); }; +/** + * Utility function to initialize a #DerivedMesh's function pointers to + * the default implementation (for those functions which have a default). + */ void DM_init_funcs(DerivedMesh *dm); +/** + * Utility function to initialize a #DerivedMesh for the desired number + * of vertices, edges and faces (doesn't allocate memory for them, just + * sets up the custom data layers)> + */ void DM_init(DerivedMesh *dm, DerivedMeshType type, int numVerts, @@ -252,6 +261,10 @@ void DM_init(DerivedMesh *dm, int numLoops, int numPolys); +/** + * Utility function to initialize a DerivedMesh for the desired number + * of vertices, edges and faces, with a layer setup copied from source + */ void DM_from_template_ex(DerivedMesh *dm, DerivedMesh *source, DerivedMeshType type, @@ -276,43 +289,61 @@ void DM_from_template(DerivedMesh *dm, */ bool DM_release(DerivedMesh *dm); +/** + * set the #CD_FLAG_NOCOPY flag in custom data layers where the mask is + * zero for the layer type, so only layer types specified by the mask + * will be copied + */ void DM_set_only_copy(DerivedMesh *dm, const struct CustomData_MeshMasks *mask); -/* adds a vertex/edge/face custom data layer to a DerivedMesh, optionally +/* Adds a vertex/edge/face custom data layer to a DerivedMesh, optionally * backed by an external data array * alloctype defines how the layer is allocated or copied, and how it is - * freed, see BKE_customdata.h for the different options - */ + * freed, see BKE_customdata.h for the different options. */ + void DM_add_vert_layer(struct DerivedMesh *dm, int type, eCDAllocType alloctype, void *layer); void DM_add_edge_layer(struct DerivedMesh *dm, int type, eCDAllocType alloctype, void *layer); void DM_add_tessface_layer(struct DerivedMesh *dm, int type, eCDAllocType alloctype, void *layer); void DM_add_loop_layer(DerivedMesh *dm, int type, eCDAllocType alloctype, void *layer); void DM_add_poly_layer(struct DerivedMesh *dm, int type, eCDAllocType alloctype, void *layer); -/* custom data access functions - * return pointer to data from first layer which matches type - * if they return NULL for valid indices, data doesn't exist - * note these return pointers - any change modifies the internals of the mesh - */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Custom Data Access Functions + * + * \return pointer to data from first layer which matches type + * if they return NULL for valid indices, data doesn't exist. + * \note these return pointers - any change modifies the internals of the mesh. + * \{ */ + void *DM_get_vert_data(struct DerivedMesh *dm, int index, int type); void *DM_get_edge_data(struct DerivedMesh *dm, int index, int type); void *DM_get_tessface_data(struct DerivedMesh *dm, int index, int type); void *DM_get_poly_data(struct DerivedMesh *dm, int index, int type); -/* custom data layer access functions - * return pointer to first data layer which matches type (a flat array) - * if they return NULL, data doesn't exist - * note these return pointers - any change modifies the internals of the mesh - */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Custom Data Layer Access Functions + * + * \return pointer to first data layer which matches type (a flat array) + * if they return NULL, data doesn't exist. + * \note these return pointers - any change modifies the internals of the mesh. + * \{ */ + void *DM_get_vert_data_layer(struct DerivedMesh *dm, int type); void *DM_get_edge_data_layer(struct DerivedMesh *dm, int type); void *DM_get_tessface_data_layer(struct DerivedMesh *dm, int type); void *DM_get_poly_data_layer(struct DerivedMesh *dm, int type); void *DM_get_loop_data_layer(struct DerivedMesh *dm, int type); -/* custom data copy functions +/** \} */ + +/** + * Custom data copy functions * copy count elements from source_index in source to dest_index in dest - * these copy all layers for which the CD_FLAG_NOCOPY flag is not set + * these copy all layers for which the CD_FLAG_NOCOPY flag is not set. */ void DM_copy_vert_data(struct DerivedMesh *source, struct DerivedMesh *dest, @@ -320,13 +351,26 @@ void DM_copy_vert_data(struct DerivedMesh *source, int dest_index, int count); -/* Sets up mpolys for a DM based on face iterators in source. */ +/** + * Sets up mpolys for a DM based on face iterators in source. + */ void DM_DupPolys(DerivedMesh *source, DerivedMesh *target); void DM_ensure_normals(DerivedMesh *dm); +/** + * Ensure the array is large enough. + * + * \note This function must always be thread-protected by caller. + * It should only be used by internal code. + */ void DM_ensure_looptri_data(DerivedMesh *dm); +/** + * Interpolates vertex data from the vertices indexed by `src_indices` in the + * source mesh using the given weights and stores the result in the vertex + * indexed by `dest_index` in the `dest` mesh. + */ void DM_interp_vert_data(struct DerivedMesh *source, struct DerivedMesh *dest, int *src_indices, @@ -336,7 +380,9 @@ void DM_interp_vert_data(struct DerivedMesh *source, void mesh_get_mapped_verts_coords(struct Mesh *me_eval, float (*r_cos)[3], const int totcos); -/* same as above but won't use render settings */ +/** + * Same as above but won't use render settings. + */ struct Mesh *editbmesh_get_eval_cage(struct Depsgraph *depsgraph, struct Scene *scene, struct Object *, diff --git a/source/blender/blenkernel/BKE_action.h b/source/blender/blenkernel/BKE_action.h index b5e94793658..ea8ee3f93b1 100644 --- a/source/blender/blenkernel/BKE_action.h +++ b/source/blender/blenkernel/BKE_action.h @@ -79,57 +79,86 @@ typedef enum eAction_TransformFlags { ACT_TRANS_ALL = (ACT_TRANS_ONLY | ACT_TRANS_PROP), } eAction_TransformFlags; -/* Return flags indicating which transforms the given object/posechannel has +/** + * Return flags indicating which transforms the given object/posechannel has * - if 'curves' is provided, a list of links to these curves are also returned - * whose nodes WILL NEED FREEING + * whose nodes WILL NEED FREEING. */ short action_get_item_transforms(struct bAction *act, struct Object *ob, struct bPoseChannel *pchan, ListBase *curves); -/* Some kind of bounding box operation on the action */ +/** + * Calculate the extents of given action. + */ void calc_action_range(const struct bAction *act, float *start, float *end, short incl_modifiers); /* Retrieve the intended playback frame range, using the manually set range if available, * or falling back to scanning F-Curves for their first & last frames otherwise. */ void BKE_action_get_frame_range(const struct bAction *act, float *r_start, float *r_end); -/* Does action have any motion data at all? */ +/** + * Check if the given action has any keyframes. + */ bool action_has_motion(const struct bAction *act); -/* Is the action configured as cyclic. */ +/** + * Is the action configured as cyclic. + */ bool BKE_action_is_cyclic(const struct bAction *act); /* Action Groups API ----------------- */ -/* Get the active action-group for an Action */ +/** + * Get the active action-group for an Action. + */ struct bActionGroup *get_active_actiongroup(struct bAction *act); -/* Make the given Action Group the active one */ +/** + * Make the given Action-Group the active one. + */ void set_active_action_group(struct bAction *act, struct bActionGroup *agrp, short select); -/* Sync colors used for action/bone group with theme settings */ +/** + * Sync colors used for action/bone group with theme settings. + */ void action_group_colors_sync(struct bActionGroup *grp, const struct bActionGroup *ref_grp); -/* Add a new action group with the given name to the action */ +/** + * Add a new action group with the given name to the action> + */ struct bActionGroup *action_groups_add_new(struct bAction *act, const char name[]); -/* Add given channel into (active) group */ +/** + * Add given channel into (active) group + * - assumes that channel is not linked to anything anymore + * - always adds at the end of the group + */ void action_groups_add_channel(struct bAction *act, struct bActionGroup *agrp, struct FCurve *fcurve); -/* Remove the given channel from all groups */ +/** + * Remove the given channel from all groups. + */ void action_groups_remove_channel(struct bAction *act, struct FCurve *fcu); -/* Reconstruct group channel pointers. */ +/** + * Reconstruct group channel pointers. + * Assumes that the groups referred to by the FCurves are already in act->groups. + * Reorders the main channel list to match group order. + */ void BKE_action_groups_reconstruct(struct bAction *act); -/* Find a group with the given name */ +/** + * Find a group with the given name. + */ struct bActionGroup *BKE_action_group_find_name(struct bAction *act, const char name[]); -/* Clear all 'temp' flags on all groups */ +/** + * Clear all 'temp' flags on all groups. + */ void action_groups_clear_tempflags(struct bAction *act); /** @@ -146,21 +175,47 @@ bool BKE_action_has_single_frame(const struct bAction *act); /* Pose API ----------------- */ void BKE_pose_channel_free(struct bPoseChannel *pchan); +/** + * Deallocates a pose channel. + * Does not free the pose channel itself. + */ void BKE_pose_channel_free_ex(struct bPoseChannel *pchan, bool do_id_user); +/** + * Clears the runtime cache of a pose channel without free. + */ void BKE_pose_channel_runtime_reset(struct bPoseChannel_Runtime *runtime); +/** + * Reset all non-persistent fields. + */ void BKE_pose_channel_runtime_reset_on_copy(struct bPoseChannel_Runtime *runtime); +/** + * Deallocates runtime cache of a pose channel + */ void BKE_pose_channel_runtime_free(struct bPoseChannel_Runtime *runtime); +/** + * Deallocates runtime cache of a pose channel's B-Bone shape. + */ void BKE_pose_channel_free_bbone_cache(struct bPoseChannel_Runtime *runtime); void BKE_pose_channels_free(struct bPose *pose); +/** + * Removes and deallocates all channels from a pose. + * Does not free the pose itself. + */ void BKE_pose_channels_free_ex(struct bPose *pose, bool do_id_user); +/** + * Removes the hash for quick lookup of channels, must be done when adding/removing channels. + */ void BKE_pose_channels_hash_ensure(struct bPose *pose); void BKE_pose_channels_hash_free(struct bPose *pose); +/** + * Selectively remove pose channels. + */ void BKE_pose_channels_remove(struct Object *ob, bool (*filter_fn)(const char *bone_name, void *user_data), void *user_data); @@ -168,18 +223,63 @@ void BKE_pose_channels_remove(struct Object *ob, void BKE_pose_free_data_ex(struct bPose *pose, bool do_id_user); void BKE_pose_free_data(struct bPose *pose); void BKE_pose_free(struct bPose *pose); +/** + * Removes and deallocates all data from a pose, and also frees the pose. + */ void BKE_pose_free_ex(struct bPose *pose, bool do_id_user); +/** + * Allocate a new pose on the heap, and copy the src pose and its channels + * into the new pose. *dst is set to the newly allocated structure, and assumed to be NULL. + * + * \param dst: Should be freed already, makes entire duplicate. + */ void BKE_pose_copy_data_ex(struct bPose **dst, const struct bPose *src, const int flag, const bool copy_constraints); void BKE_pose_copy_data(struct bPose **dst, const struct bPose *src, const bool copy_constraints); +/** + * Copy the internal members of each pose channel including constraints + * and ID-Props, used when duplicating bones in edit-mode. + * (unlike copy_pose_channel_data which only does posing-related stuff). + * + * \note use when copying bones in edit-mode (on returned value from #BKE_pose_channel_ensure) + */ void BKE_pose_channel_copy_data(struct bPoseChannel *pchan, const struct bPoseChannel *pchan_from); void BKE_pose_channel_session_uuid_generate(struct bPoseChannel *pchan); +/** + * Return a pointer to the pose channel of the given name + * from this pose. + */ struct bPoseChannel *BKE_pose_channel_find_name(const struct bPose *pose, const char *name); +/** + * Find the active pose-channel for an object + * (we can't just use pose, as layer info is in armature) + * + * \note #Object, not #bPose is used here, as we need layer info from Armature. + */ struct bPoseChannel *BKE_pose_channel_active(struct Object *ob); +/** + * Use this when detecting the "other selected bone", + * when we have multiple armatures in pose mode. + * + * In this case the active-selected is an obvious choice when finding the target for a + * constraint for eg. however from the users perspective the active pose bone of the + * active object is the _real_ active bone, so any other non-active selected bone + * is a candidate for being the other selected bone, see: T58447. + */ struct bPoseChannel *BKE_pose_channel_active_or_first_selected(struct Object *ob); +/** + * Looks to see if the channel with the given name already exists + * in this pose - if not a new one is allocated and initialized. + * + * \note Use with care, not on Armature poses but for temporal ones. + * \note (currently used for action constraints and in rebuild_pose). + */ struct bPoseChannel *BKE_pose_channel_ensure(struct bPose *pose, const char *name); +/** + * \see #ED_armature_ebone_get_mirrored (edit-mode, matching function) + */ struct bPoseChannel *BKE_pose_channel_get_mirrored(const struct bPose *pose, const char *name); void BKE_pose_check_uuids_unique_and_report(const struct bPose *pose); @@ -188,37 +288,60 @@ void BKE_pose_check_uuids_unique_and_report(const struct bPose *pose); bool BKE_pose_channels_is_valid(const struct bPose *pose); #endif -/* sets constraint flags */ +/** + * Checks for IK constraint, Spline IK, and also for Follow-Path constraint. + * can do more constraints flags later. pose should be entirely OK. + */ void BKE_pose_update_constraint_flags(struct bPose *pose); -/* tag constraint flags for update */ +/** + * Tag constraint flags for update. + */ void BKE_pose_tag_update_constraint_flags(struct bPose *pose); -/* return the name of structure pointed by pose->ikparam */ +/** + * Return the name of structure pointed by `pose->ikparam`. + */ const char *BKE_pose_ikparam_get_name(struct bPose *pose); -/* allocate and initialize pose->ikparam according to pose->iksolver */ +/** + * Allocate and initialize `pose->ikparam` according to `pose->iksolver`. + */ void BKE_pose_ikparam_init(struct bPose *pose); -/* initialize a bItasc structure with default value */ +/** + * Initialize a #bItasc structure with default value. + */ void BKE_pose_itasc_init(struct bItasc *itasc); -/* Checks if a bone is part of an IK chain or not */ +/** + * Checks if a bone is part of an IK chain or not. + */ bool BKE_pose_channel_in_IK_chain(struct Object *ob, struct bPoseChannel *pchan); /* Bone Groups API --------------------- */ -/* Adds a new bone-group */ +/** + * Adds a new bone-group (name may be NULL). + */ struct bActionGroup *BKE_pose_add_group(struct bPose *pose, const char *name); -/* Remove a bone-group */ +/** + * Remove the given bone-group (expects 'virtual' index (+1 one, used by active_group etc.)) + * index might be invalid ( < 1), in which case it will be find from grp. + */ void BKE_pose_remove_group(struct bPose *pose, struct bActionGroup *grp, const int index); -/* Remove the matching bone-group from its index */ +/** + * Remove the indexed bone-group (expects 'virtual' index (+1 one, used by active_group etc.)). + */ void BKE_pose_remove_group_index(struct bPose *pose, const int index); /* Assorted Evaluation ----------------- */ -/* Used for the Action Constraint */ +/** + * For the calculation of the effects of an Action at the given frame on an object + * This is currently only used for the Action Constraint + */ void what_does_obaction(struct Object *ob, struct Object *workob, struct bPose *pose, @@ -229,11 +352,18 @@ void what_does_obaction(struct Object *ob, /* for proxy */ void BKE_pose_copy_pchan_result(struct bPoseChannel *pchanto, const struct bPoseChannel *pchanfrom); +/** + * Both poses should be in sync. + */ bool BKE_pose_copy_result(struct bPose *to, struct bPose *from); -/* Clear transforms. */ +/** + * Zero the pose transforms for the entire pose or only for selected bones. + */ void BKE_pose_rest(struct bPose *pose, bool selected_bones_only); -/* Tag pose for recalc. Also tag all related data to be recalc. */ +/** + * Tag pose for recalculation. Also tag all related data to be recalculated. + */ void BKE_pose_tag_recalc(struct Main *bmain, struct bPose *pose); void BKE_pose_blend_write(struct BlendWriter *writer, struct bPose *pose, struct bArmature *arm); diff --git a/source/blender/blenkernel/BKE_anim_data.h b/source/blender/blenkernel/BKE_anim_data.h index 14ab9f21424..a65efbd707c 100644 --- a/source/blender/blenkernel/BKE_anim_data.h +++ b/source/blender/blenkernel/BKE_anim_data.h @@ -43,43 +43,81 @@ struct bAction; /* ************************************* */ /* AnimData API */ -/* Check if the given ID-block can have AnimData */ +/** + * Check if the given ID-block can have AnimData. + */ bool id_type_can_have_animdata(const short id_type); bool id_can_have_animdata(const struct ID *id); -/* Get AnimData from the given ID-block */ +/** + * Get #AnimData from the given ID-block. + */ struct AnimData *BKE_animdata_from_id(struct ID *id); -/* Ensure AnimData is present in the ID-block (when supported). */ +/** + * Ensure #AnimData exists in the given ID-block (when supported). + */ struct AnimData *BKE_animdata_ensure_id(struct ID *id); -/* Set active action used by AnimData from the given ID-block */ +/** + * Set active action used by AnimData from the given ID-block. + * + * Called when user tries to change the active action of an #AnimData block + * (via RNA, Outliner, etc.) + * + * \param reports: Can be NULL. + * \param id: The owner of the animation data + * \param act: The Action to set, or NULL to clear. + * + * \return true when the action was successfully updated, false otherwise. + */ bool BKE_animdata_set_action(struct ReportList *reports, struct ID *id, struct bAction *act); bool BKE_animdata_action_editable(const struct AnimData *adt); -/* Ensure that the action's idroot is set correctly given the ID type of the owner. - * Return true if it is, false if it was already set to an incompatible type. */ +/** + * Ensure that the action's idroot is set correctly given the ID type of the owner. + * Return true if it is, false if it was already set to an incompatible type. + */ bool BKE_animdata_action_ensure_idroot(const struct ID *owner, struct bAction *action); -/* Free AnimData */ +/** + * Free AnimData used by the nominated ID-block, and clear ID-block's AnimData pointer. + */ void BKE_animdata_free(struct ID *id, const bool do_id_user); -/* Return true if the ID-block has non-empty AnimData. */ +/** + * Return true if the ID-block has non-empty AnimData. + */ bool BKE_animdata_id_is_animated(const struct ID *id); +/** + * Callback used by lib_query to walk over all ID usages + * (mimics `foreach_id` callback of #IDTypeInfo structure). + */ void BKE_animdata_foreach_id(struct AnimData *adt, struct LibraryForeachIDData *data); -/* Copy AnimData */ +/** + * Make a copy of the given AnimData - to be used when copying data-blocks. + * \param flag: Control ID pointers management, + * see LIB_ID_CREATE_.../LIB_ID_COPY_... flags in BKE_lib_id.h + * \return The copied animdata. + */ struct AnimData *BKE_animdata_copy(struct Main *bmain, struct AnimData *adt, const int flag); -/* Copy AnimData */ +/** + * \param flag: Control ID pointers management, + * see LIB_ID_CREATE_.../LIB_ID_COPY_... flags in BKE_lib_id.h + * \return true is successfully copied. + */ bool BKE_animdata_copy_id(struct Main *bmain, struct ID *id_to, struct ID *id_from, const int flag); -/* Copy AnimData Actions */ +/** + * Copy AnimData Actions. + */ void BKE_animdata_copy_id_action(struct Main *bmain, struct ID *id); void BKE_animdata_duplicate_id_action(struct Main *bmain, @@ -98,6 +136,9 @@ typedef enum eAnimData_MergeCopy_Modes { ADT_MERGECOPY_SRC_REF = 2, } eAnimData_MergeCopy_Modes; +/** + * Merge copies of the data from the src AnimData into the destination AnimData. + */ void BKE_animdata_merge_copy(struct Main *bmain, struct ID *dst_id, struct ID *src_id, diff --git a/source/blender/blenkernel/BKE_anim_path.h b/source/blender/blenkernel/BKE_anim_path.h index 9db63080fd9..6bc09eb35ed 100644 --- a/source/blender/blenkernel/BKE_anim_path.h +++ b/source/blender/blenkernel/BKE_anim_path.h @@ -35,12 +35,21 @@ struct Object; int BKE_anim_path_get_array_size(const struct CurveCache *curve_cache); float BKE_anim_path_get_length(const struct CurveCache *curve_cache); -/* This function populates the 'ob->runtime.curve_cache->anim_path_accum_length' data. +/** + * This function populates the 'ob->runtime.curve_cache->anim_path_accum_length' data. * You should never have to call this manually as it should already have been called by * 'BKE_displist_make_curveTypes'. Do not call this manually unless you know what you are doing. */ void BKE_anim_path_calc_data(struct Object *ob); +/** + * Calculate the deformation implied by the curve path at a given parametric position, + * and returns whether this operation succeeded. + * + * \param ctime: Time is normalized range <0-1>. + * + * \return success. + */ bool BKE_where_on_path(const struct Object *ob, float ctime, float r_vec[4], diff --git a/source/blender/blenkernel/BKE_anim_visualization.h b/source/blender/blenkernel/BKE_anim_visualization.h index 4e86abeed8d..3b8c91b7fd2 100644 --- a/source/blender/blenkernel/BKE_anim_visualization.h +++ b/source/blender/blenkernel/BKE_anim_visualization.h @@ -38,13 +38,34 @@ struct bPoseChannel; /* ---------------------------------------------------- */ /* Animation Visualization */ +/** + * Initialize the default settings for animation visualization. + */ void animviz_settings_init(struct bAnimVizSettings *avs); +/** + * Make a copy of motion-path data, so that viewing with copy on write works. + */ struct bMotionPath *animviz_copy_motionpath(const struct bMotionPath *mpath_src); +/** + * Free the given motion path's cache. + */ void animviz_free_motionpath_cache(struct bMotionPath *mpath); +/** + * Free the given motion path instance and its data. + * \note this frees the motion path given! + */ void animviz_free_motionpath(struct bMotionPath *mpath); +/** + * Setup motion paths for the given data. + * \note Only used when explicitly calculating paths on bones which may/may not be consider already + * + * \param scene: Current scene (for frame ranges, etc.) + * \param ob: Object to add paths for (must be provided) + * \param pchan: Posechannel to add paths for (optional; if not provided, object-paths are assumed) + */ struct bMotionPath *animviz_verify_motionpaths(struct ReportList *reports, struct Scene *scene, struct Object *ob, diff --git a/source/blender/blenkernel/BKE_animsys.h b/source/blender/blenkernel/BKE_animsys.h index 07da9d75e59..6197cb93c95 100644 --- a/source/blender/blenkernel/BKE_animsys.h +++ b/source/blender/blenkernel/BKE_animsys.h @@ -69,12 +69,17 @@ AnimationEvalContext BKE_animsys_eval_context_construct_at( /* ************************************* */ /* KeyingSets API */ -/* Used to create a new 'custom' KeyingSet for the user, - * that will be automatically added to the stack */ +/** + * Used to create a new 'custom' KeyingSet for the user, + * that will be automatically added to the stack. + */ struct KeyingSet *BKE_keyingset_add( struct ListBase *list, const char idname[], const char name[], short flag, short keyingflag); -/* Add a path to a KeyingSet */ +/** + * Add a path to a KeyingSet. Nothing is returned for now. + * Checks are performed to ensure that destination is appropriate for the KeyingSet in question + */ struct KS_Path *BKE_keyingset_add_path(struct KeyingSet *ks, struct ID *id, const char group_name[], @@ -83,7 +88,10 @@ struct KS_Path *BKE_keyingset_add_path(struct KeyingSet *ks, short flag, short groupmode); -/* Find the destination matching the criteria given */ +/** + * Find the destination matching the criteria given. + * TODO: do we want some method to perform partial matches too? + */ struct KS_Path *BKE_keyingset_find_path(struct KeyingSet *ks, struct ID *id, const char group_name[], @@ -208,11 +216,32 @@ void BKE_fcurves_id_cb(struct ID *id, ID_FCurve_Edit_Callback func, void *user_d typedef struct NlaKeyframingContext NlaKeyframingContext; +/** + * Prepare data necessary to compute correct keyframe values for NLA strips + * with non-Replace mode or influence different from 1. + * + * \param cache: List used to cache contexts for reuse when keying + * multiple channels in one operation. + * \param ptr: RNA pointer to the Object with the animation. + * \return Keyframing context, or NULL if not necessary. + */ struct NlaKeyframingContext *BKE_animsys_get_nla_keyframing_context( struct ListBase *cache, struct PointerRNA *ptr, struct AnimData *adt, const struct AnimationEvalContext *anim_eval_context); +/** + * Apply correction from the NLA context to the values about to be keyframed. + * + * \param context: Context to use (may be NULL). + * \param prop_ptr: Property about to be keyframed. + * \param[in,out] values: Array of property values to adjust. + * \param count: Number of values in the array. + * \param index: Index of the element about to be updated, or -1. + * \param[out] r_force_all: Set to true if all channels must be inserted. May be NULL. + * \return False if correction fails due to a division by zero, + * or null r_force_all when all channels are required. + */ bool BKE_animsys_nla_remap_keyframe_values(struct NlaKeyframingContext *context, struct PointerRNA *prop_ptr, struct PropertyRNA *prop, @@ -220,6 +249,9 @@ bool BKE_animsys_nla_remap_keyframe_values(struct NlaKeyframingContext *context, int count, int index, bool *r_force_all); +/** + * Free all cached contexts from the list. + */ void BKE_animsys_free_nla_keyframing_context_cache(struct ListBase *cache); /* ************************************* */ @@ -240,16 +272,32 @@ bool BKE_animsys_rna_path_resolve(struct PointerRNA *ptr, const int array_index, struct PathResolvedRNA *r_result); bool BKE_animsys_read_from_rna_path(struct PathResolvedRNA *anim_rna, float *r_value); +/** + * Write the given value to a setting using RNA, and return success. + */ bool BKE_animsys_write_to_rna_path(struct PathResolvedRNA *anim_rna, const float value); -/* Evaluation loop for evaluating animation data. */ +/** + * Evaluation loop for evaluation animation data + * + * This assumes that the animation-data provided belongs to the ID block in question, + * and that the flags for which parts of the animation-data settings need to be recalculated + * have been set already by the depsgraph. Now, we use the recalculate. + */ void BKE_animsys_evaluate_animdata(struct ID *id, struct AnimData *adt, const struct AnimationEvalContext *anim_eval_context, eAnimData_Recalc recalc, const bool flush_to_original); -/* Evaluation of all ID-blocks with Animation Data blocks - Animation Data Only */ +/** + * Evaluation of all ID-blocks with Animation Data blocks - Animation Data Only + * + * This will evaluate only the animation info available in the animation data-blocks + * encountered. In order to enforce the system by which some settings controlled by a + * 'local' (i.e. belonging in the nearest ID-block that setting is related to, not a + * standard 'root') block are overridden by a larger 'user' + */ void BKE_animsys_evaluate_all_animation(struct Main *main, struct Depsgraph *depsgraph, float ctime); diff --git a/source/blender/blenkernel/BKE_appdir.h b/source/blender/blenkernel/BKE_appdir.h index 65485058dd7..dd589282bdd 100644 --- a/source/blender/blenkernel/BKE_appdir.h +++ b/source/blender/blenkernel/BKE_appdir.h @@ -17,6 +17,9 @@ /** \file * \ingroup bke + * + * \note on naming: typical _get() suffix is omitted here, + * since its the main purpose of the API. */ #include @@ -29,54 +32,139 @@ extern "C" { struct ListBase; +/** + * Sanity check to ensure correct API use in debug mode. + * + * Run this once the first level of arguments has been passed so we can be sure + * `--env-system-datafiles`, and other `--env-*` arguments has been passed. + * + * Without this any callers to this module that run early on, + * will miss out on changes from parsing arguments. + */ void BKE_appdir_init(void); void BKE_appdir_exit(void); -/* note on naming: typical _get() suffix is omitted here, - * since its the main purpose of the API. */ +/** + * Get the folder that's the "natural" starting point for browsing files on an OS. + * - Unix: `$HOME` + * - Windows: `%userprofile%/Documents` + * + * \note On Windows `Users/{MyUserName}/Documents` is used as it's the default location to save + * documents. + */ const char *BKE_appdir_folder_default(void) ATTR_WARN_UNUSED_RESULT; const char *BKE_appdir_folder_root(void) ATTR_WARN_UNUSED_RESULT ATTR_RETURNS_NONNULL; const char *BKE_appdir_folder_default_or_root(void) ATTR_WARN_UNUSED_RESULT ATTR_RETURNS_NONNULL; +/** + * Get the user's home directory, i.e. + * - Unix: `$HOME` + * - Windows: `%userprofile%` + */ const char *BKE_appdir_folder_home(void); +/** + * Get the user's document directory, i.e. + * - Linux: `$HOME/Documents` + * - Windows: `%userprofile%/Documents` + * + * If this can't be found using OS queries (via Ghost), try manually finding it. + * + * \returns True if the path is valid and points to an existing directory. + */ bool BKE_appdir_folder_documents(char *dir); +/** + * Get the user's cache directory, i.e. + * - Linux: `$HOME/.cache/blender/` + * - Windows: `%USERPROFILE%\AppData\Local\Blender Foundation\Blender\` + * - MacOS: `/Library/Caches/Blender` + * + * \returns True if the path is valid. It doesn't create or checks format + * if the `blender` folder exists. It does check if the parent of the path exists. + */ bool BKE_appdir_folder_caches(char *r_path, size_t path_len); +/** + * Get a folder out of the \a folder_id presets for paths. + * + * \param subfolder: The name of a directory to check for, + * this may contain path separators but must resolve to a directory, checked with #BLI_is_dir. + * \return The path if found, NULL string if not. + */ bool BKE_appdir_folder_id_ex(const int folder_id, const char *subfolder, char *path, size_t path_len); const char *BKE_appdir_folder_id(const int folder_id, const char *subfolder); +/** + * Returns the path to a folder in the user area, creating it if it doesn't exist. + */ const char *BKE_appdir_folder_id_create(const int folder_id, const char *subfolder); +/** + * Returns the path to a folder in the user area without checking that it actually exists first. + */ const char *BKE_appdir_folder_id_user_notest(const int folder_id, const char *subfolder); +/** + * Returns the path of the top-level version-specific local, user or system directory. + * If check_is_dir, then the result will be NULL if the directory doesn't exist. + */ const char *BKE_appdir_folder_id_version(const int folder_id, const int version, const bool check_is_dir); +/** + * Check if this is an install with user files kept together + * with the Blender executable and its installation files. + */ bool BKE_appdir_app_is_portable_install(void); +/** + * Return true if templates exist + */ bool BKE_appdir_app_template_any(void); bool BKE_appdir_app_template_id_search(const char *app_template, char *path, size_t path_len); bool BKE_appdir_app_template_has_userpref(const char *app_template); void BKE_appdir_app_templates(struct ListBase *templates); -/* Initialize path to program executable */ +/** + * Initialize path to program executable. + */ void BKE_appdir_program_path_init(const char *argv0); +/** + * Path to executable + */ const char *BKE_appdir_program_path(void); +/** + * Path to directory of executable + */ const char *BKE_appdir_program_dir(void); -/* Return OS fonts directory. */ +/** + * Gets a good default directory for fonts. + */ bool BKE_appdir_font_folder_default(char *dir); -/* find python executable */ +/** + * Find Python executable. + */ bool BKE_appdir_program_python_search(char *fullpath, const size_t fullpath_len, const int version_major, const int version_minor); -/* Initialize path to temporary directory. */ +/** + * Initialize path to temporary directory. + */ void BKE_tempdir_init(const char *userdir); +/** + * Path to persistent temporary directory (with trailing slash) + */ const char *BKE_tempdir_base(void); +/** + * Path to temporary directory (with trailing slash) + */ const char *BKE_tempdir_session(void); +/** + * Delete content of this instance's temp dir. + */ void BKE_tempdir_session_purge(void); /* folder_id */ diff --git a/source/blender/blenkernel/BKE_armature.h b/source/blender/blenkernel/BKE_armature.h index e13475fd78c..aaf6c540878 100644 --- a/source/blender/blenkernel/BKE_armature.h +++ b/source/blender/blenkernel/BKE_armature.h @@ -166,8 +166,20 @@ struct BoundBox *BKE_armature_boundbox_get(struct Object *ob); bool BKE_pose_minmax( struct Object *ob, float r_min[3], float r_max[3], bool use_hidden, bool use_select); +/** + * Finds the best possible extension to the name on a particular axis. + * (For renaming, check for unique names afterwards) + * \param strip_number: removes number extensions (TODO: not used). + * \param axis: The axis to name on. + * \param head: The head co-ordinate of the bone on the specified axis. + * \param tail: The tail co-ordinate of the bone on the specified axis. + */ bool bone_autoside_name(char name[64], int strip_number, short axis, float head, float tail); +/** + * Walk the list until the bone is found (slow!), + * use #BKE_armature_bone_from_name_map for multiple lookups. + */ struct Bone *BKE_armature_find_bone_name(struct bArmature *arm, const char *name); void BKE_armature_bone_hash_make(struct bArmature *arm); @@ -177,40 +189,87 @@ bool BKE_armature_bone_flag_test_recursive(const struct Bone *bone, int flag); void BKE_armature_refresh_layer_used(struct Depsgraph *depsgraph, struct bArmature *arm); +/** + * Using `vec` with dist to bone `b1 - b2`. + */ float distfactor_to_bone( const float vec[3], const float b1[3], const float b2[3], float rad1, float rad2, float rdist); +/** + * Updates vectors and matrices on rest-position level, only needed + * after editing armature itself, now only on reading file. + */ void BKE_armature_where_is(struct bArmature *arm); +/** + * Recursive part, calculates rest-position of entire tree of children. + * \note Used when exiting edit-mode too. + */ void BKE_armature_where_is_bone(struct Bone *bone, const struct Bone *bone_parent, const bool use_recursion); +/** + * Clear pointers of object's pose + * (needed in remap case, since we cannot always wait for a complete pose rebuild). + */ void BKE_pose_clear_pointers(struct bPose *pose); void BKE_pose_remap_bone_pointers(struct bArmature *armature, struct bPose *pose); +/** + * Update the links for the B-Bone handles from Bone data. + */ void BKE_pchan_rebuild_bbone_handles(struct bPose *pose, struct bPoseChannel *pchan); void BKE_pose_channels_clear_with_null_bone(struct bPose *pose, const bool do_id_user); +/** + * Only after leave edit-mode, duplicating, validating older files, library syncing. + * + * \note pose->flag is set for it. + * + * \param bmain: May be NULL, only used to tag depsgraph as being dirty. + */ void BKE_pose_rebuild(struct Main *bmain, struct Object *ob, struct bArmature *arm, const bool do_id_user); +/** + * Ensures object's pose is rebuilt if needed. + * + * \param bmain: May be NULL, only used to tag depsgraph as being dirty. + */ void BKE_pose_ensure(struct Main *bmain, struct Object *ob, struct bArmature *arm, const bool do_id_user); +/** + * \note This is the only function adding poses. + * \note This only reads anim data from channels, and writes to channels. + */ void BKE_pose_where_is(struct Depsgraph *depsgraph, struct Scene *scene, struct Object *ob); +/** + * The main armature solver, does all constraints excluding IK. + * + * \param pchan: pose-channel - validated, as having bone and parent pointer. + * \param do_extra: when zero skips loc/size/rot, constraints and strip modifiers. + */ void BKE_pose_where_is_bone(struct Depsgraph *depsgraph, struct Scene *scene, struct Object *ob, struct bPoseChannel *pchan, float ctime, bool do_extra); +/** + * Calculate tail of pose-channel. + */ void BKE_pose_where_is_bone_tail(struct bPoseChannel *pchan); -/* Evaluate the action and apply it to the pose. If any pose bones are selected, only FCurves that - * relate to those bones are evaluated. */ +/** + * Evaluate the action and apply it to the pose. If any pose bones are selected, only FCurves that + * relate to those bones are evaluated. + */ void BKE_pose_apply_action_selected_bones(struct Object *ob, struct bAction *action, struct AnimationEvalContext *anim_eval_context); -/* Evaluate the action and apply it to the pose. Ignore selection state of the bones. */ +/** + * Evaluate the action and apply it to the pose. Ignore selection state of the bones. + */ void BKE_pose_apply_action_all_bones(struct Object *ob, struct bAction *action, struct AnimationEvalContext *anim_eval_context); @@ -221,24 +280,63 @@ void BKE_pose_apply_action_blend(struct Object *ob, float blend_factor); void vec_roll_to_mat3(const float vec[3], const float roll, float r_mat[3][3]); + +/** + * Calculates the rest matrix of a bone based on its vector and a roll around that vector. + */ void vec_roll_to_mat3_normalized(const float nor[3], const float roll, float r_mat[3][3]); +/** + * Computes vector and roll based on a rotation. + * "mat" must contain only a rotation, and no scaling. + */ void mat3_to_vec_roll(const float mat[3][3], float r_vec[3], float *r_roll); +/** + * Computes roll around the vector that best approximates the matrix. + * If `vec` is the Y vector from purely rotational `mat`, result should be exact. + */ void mat3_vec_to_roll(const float mat[3][3], const float vec[3], float *r_roll); /* Common Conversions Between Co-ordinate Spaces */ + +/** + * Convert World-Space Matrix to Pose-Space Matrix. + */ void BKE_armature_mat_world_to_pose(struct Object *ob, const float inmat[4][4], float outmat[4][4]); +/** + * Convert World-Space Location to Pose-Space Location + * \note this cannot be used to convert to pose-space location of the supplied + * pose-channel into its local space (i.e. 'visual'-keyframing). + */ void BKE_armature_loc_world_to_pose(struct Object *ob, const float inloc[3], float outloc[3]); +/** + * Convert Pose-Space Matrix to Bone-Space Matrix. + * \note this cannot be used to convert to pose-space transforms of the supplied + * pose-channel into its local space (i.e. 'visual'-keyframing). + */ void BKE_armature_mat_pose_to_bone(struct bPoseChannel *pchan, const float inmat[4][4], float outmat[4][4]); +/** + * Convert Pose-Space Location to Bone-Space Location + * \note this cannot be used to convert to pose-space location of the supplied + * pose-channel into its local space (i.e. 'visual'-keyframing). + */ void BKE_armature_loc_pose_to_bone(struct bPoseChannel *pchan, const float inloc[3], float outloc[3]); +/** + * Convert Bone-Space Matrix to Pose-Space Matrix. + */ void BKE_armature_mat_bone_to_pose(struct bPoseChannel *pchan, const float inmat[4][4], float outmat[4][4]); +/** + * Remove rest-position effects from pose-transform for obtaining + * 'visual' transformation of pose-channel. + * (used by the Visual-Keyframing stuff). + */ void BKE_armature_mat_pose_to_delta(float delta_mat[4][4], float pose_mat[4][4], float arm_mat[4][4]); @@ -249,13 +347,34 @@ void BKE_armature_mat_pose_to_bone_ex(struct Depsgraph *depsgraph, const float inmat[4][4], float outmat[4][4]); +/** + * Same as #BKE_object_mat3_to_rot(). + */ void BKE_pchan_mat3_to_rot(struct bPoseChannel *pchan, const float mat[3][3], bool use_compat); +/** + * Same as #BKE_object_rot_to_mat3(). + */ void BKE_pchan_rot_to_mat3(const struct bPoseChannel *pchan, float r_mat[3][3]); +/** + * Apply a 4x4 matrix to the pose bone, + * similar to #BKE_object_apply_mat4(). + */ void BKE_pchan_apply_mat4(struct bPoseChannel *pchan, const float mat[4][4], bool use_compat); +/** + * Convert the loc/rot/size to \a r_chanmat (typically #bPoseChannel.chan_mat). + */ void BKE_pchan_to_mat4(const struct bPoseChannel *pchan, float r_chanmat[4][4]); + +/** + * Convert the loc/rot/size to mat4 (`pchan.chan_mat`), + * used in `constraint.c` too. + */ void BKE_pchan_calc_mat(struct bPoseChannel *pchan); -/* Simple helper, computes the offset bone matrix. */ +/** + * Simple helper, computes the offset bone matrix: + * `offs_bone = yoffs(b-1) + root(b) + bonemat(b)`. + */ void BKE_bone_offset_matrix_get(const struct Bone *bone, float offs_bone[4][4]); /* Transformation inherited from the parent bone. These matrices apply the effects of @@ -277,9 +396,38 @@ void BKE_bone_parent_transform_apply(const struct BoneParentTransform *bpt, const float inmat[4][4], float outmat[4][4]); -/* Get the current parent transformation for the given pose bone. */ +/** + * Get the current parent transformation for the given pose bone. + * + * Construct the matrices (rot/scale and loc) + * to apply the PoseChannels into the armature (object) space. + * I.e. (roughly) the "pose_mat(b-1) * yoffs(b-1) * d_root(b) * bone_mat(b)" in the + * pose_mat(b)= pose_mat(b-1) * yoffs(b-1) * d_root(b) * bone_mat(b) * chan_mat(b) + * ...function. + * + * This allows to get the transformations of a bone in its object space, + * *before* constraints (and IK) get applied (used by pose evaluation code). + * And reverse: to find pchan transformations needed to place a bone at a given loc/rot/scale + * in object space (used by interactive transform, and snapping code). + * + * Note that, with the HINGE/NO_SCALE/NO_LOCAL_LOCATION options, the location matrix + * will differ from the rotation/scale matrix... + * + * \note This cannot be used to convert to pose-space transforms of the supplied + * pose-channel into its local space (i.e. 'visual'-keyframing). + * (NOTE(@mont29): I don't understand that, so I keep it :p). + */ void BKE_bone_parent_transform_calc_from_pchan(const struct bPoseChannel *pchan, struct BoneParentTransform *r_bpt); +/** + * Compute the parent transform using data decoupled from specific data structures. + * + * \param bone_flag: #Bone.flag containing settings. + * \param offs_bone: delta from parent to current arm_mat (or just arm_mat if no parent). + * \param parent_arm_mat: arm_mat of parent, or NULL. + * \param parent_pose_mat: pose_mat of parent, or NULL. + * \param r_bpt: OUTPUT parent transform. + */ void BKE_bone_parent_transform_calc_from_matrices(int bone_flag, int inherit_scale_mode, const float offs_bone[4][4], @@ -287,7 +435,13 @@ void BKE_bone_parent_transform_calc_from_matrices(int bone_flag, const float parent_pose_mat[4][4], struct BoneParentTransform *r_bpt); -/* Rotation Mode Conversions - Used for PoseChannels + Objects... */ +/** + * Rotation Mode Conversions - Used for Pose-Channels + Objects. + * + * Called from RNA when rotation mode changes + * - the result should be that the rotations given in the provided pointers have had conversions + * applied (as appropriate), such that the rotation of the element hasn't 'visually' changed. + */ void BKE_rotMode_change_values( float quat[4], float eul[3], float axis[3], float *angle, short oldMode, short newMode); @@ -320,18 +474,31 @@ typedef struct BBoneSplineParameters { float curve_in_x, curve_in_z, curve_out_x, curve_out_z; } BBoneSplineParameters; +/** + * Get "next" and "prev" bones - these are used for handle calculations. + */ void BKE_pchan_bbone_handles_get(struct bPoseChannel *pchan, struct bPoseChannel **r_prev, struct bPoseChannel **r_next); +/** + * Compute B-Bone spline parameters for the given channel. + */ void BKE_pchan_bbone_spline_params_get(struct bPoseChannel *pchan, const bool rest, struct BBoneSplineParameters *r_param); +/** + * Fills the array with the desired amount of bone->segments elements. + * This calculation is done within unit bone space. + */ void BKE_pchan_bbone_spline_setup(struct bPoseChannel *pchan, const bool rest, const bool for_deform, Mat4 *result_array); +/** + * Computes the bezier handle vectors and rolls coming from custom handles. + */ void BKE_pchan_bbone_handles_compute(const BBoneSplineParameters *param, float h1[3], float *r_roll1, @@ -339,14 +506,28 @@ void BKE_pchan_bbone_handles_compute(const BBoneSplineParameters *param, float *r_roll2, bool ease, bool offsets); +/** + * Fills the array with the desired amount of `bone->segments` elements. + * This calculation is done within unit bone space. + */ int BKE_pchan_bbone_spline_compute(struct BBoneSplineParameters *param, const bool for_deform, Mat4 *result_array); +/** + * Compute and cache the B-Bone shape in the channel runtime struct. + */ void BKE_pchan_bbone_segments_cache_compute(struct bPoseChannel *pchan); +/** + * Copy cached B-Bone segments from one channel to another. + */ void BKE_pchan_bbone_segments_cache_copy(struct bPoseChannel *pchan, struct bPoseChannel *pchan_from); +/** + * Calculate index and blend factor for the two B-Bone segment nodes + * affecting the point at 0 <= pos <= 1. + */ void BKE_pchan_bbone_deform_segment_index(const struct bPoseChannel *pchan, float pos, int *r_index, diff --git a/source/blender/blenkernel/BKE_asset.h b/source/blender/blenkernel/BKE_asset.h index 722d142b56c..58c50fb736f 100644 --- a/source/blender/blenkernel/BKE_asset.h +++ b/source/blender/blenkernel/BKE_asset.h @@ -57,6 +57,9 @@ struct AssetTagEnsureResult { }; struct AssetTag *BKE_asset_metadata_tag_add(struct AssetMetaData *asset_data, const char *name); +/** + * Make sure there is a tag with name \a name, create one if needed. + */ struct AssetTagEnsureResult BKE_asset_metadata_tag_ensure(struct AssetMetaData *asset_data, const char *name); void BKE_asset_metadata_tag_remove(struct AssetMetaData *asset_data, struct AssetTag *tag); diff --git a/source/blender/blenkernel/BKE_asset_catalog.hh b/source/blender/blenkernel/BKE_asset_catalog.hh index d071f782bd6..ecc839050b7 100644 --- a/source/blender/blenkernel/BKE_asset_catalog.hh +++ b/source/blender/blenkernel/BKE_asset_catalog.hh @@ -377,6 +377,9 @@ class AssetCatalogDefinitionFile { /* For now this is the only version of the catalog definition files that is supported. * Later versioning code may be added to handle older files. */ const static int SUPPORTED_VERSION; + /* String that's matched in the catalog definition file to know that the line is the version + * declaration. It has to start with a space to ensure it won't match any hypothetical future + * field that starts with "VERSION". */ const static std::string VERSION_MARKER; const static std::string HEADER; diff --git a/source/blender/blenkernel/BKE_attribute_access.hh b/source/blender/blenkernel/BKE_attribute_access.hh index b39d3c69bfd..fd30813a506 100644 --- a/source/blender/blenkernel/BKE_attribute_access.hh +++ b/source/blender/blenkernel/BKE_attribute_access.hh @@ -155,6 +155,10 @@ using fn::GVMutableArray; const CPPType *custom_data_type_to_cpp_type(const CustomDataType type); CustomDataType cpp_type_to_custom_data_type(const CPPType &type); CustomDataType attribute_data_type_highest_complexity(Span data_types); +/** + * Domains with a higher "information density" have a higher priority, + * in order to choose a domain that will not lose data through domain conversion. + */ AttributeDomain attribute_domain_highest_priority(Span domains); /** @@ -349,6 +353,11 @@ class CustomDataAttributes { std::optional get_for_read(const AttributeIDRef &attribute_id) const; + /** + * Return a virtual array for a stored attribute, or a single value virtual array with the + * default value if the attribute doesn't exist. If no default value is provided, the default + * value for the type will be used. + */ blender::fn::GVArray get_for_read(const AttributeIDRef &attribute_id, const CustomDataType data_type, const void *default_value) const; diff --git a/source/blender/blenkernel/BKE_autoexec.h b/source/blender/blenkernel/BKE_autoexec.h index 84d83ae5d30..55bb3e8877f 100644 --- a/source/blender/blenkernel/BKE_autoexec.h +++ b/source/blender/blenkernel/BKE_autoexec.h @@ -23,6 +23,10 @@ extern "C" { #endif +/** + * \param path: The path to check against. + * \return Success + */ bool BKE_autoexec_match(const char *path); #ifdef __cplusplus diff --git a/source/blender/blenkernel/BKE_blender.h b/source/blender/blenkernel/BKE_blender.h index 813472715fa..8c0512edb1d 100644 --- a/source/blender/blenkernel/BKE_blender.h +++ b/source/blender/blenkernel/BKE_blender.h @@ -29,6 +29,9 @@ extern "C" { struct UserDef; +/** + * Only to be called on exit Blender. + */ void BKE_blender_free(void); void BKE_blender_globals_init(void); @@ -38,11 +41,19 @@ void BKE_blender_userdef_data_swap(struct UserDef *userdef_a, struct UserDef *us void BKE_blender_userdef_data_set(struct UserDef *userdef); void BKE_blender_userdef_data_set_and_free(struct UserDef *userdef); +/** + * Write U from userdef. + * This function defines which settings a template will override for the user preferences. + */ void BKE_blender_userdef_app_template_data_swap(struct UserDef *userdef_a, struct UserDef *userdef_b); void BKE_blender_userdef_app_template_data_set(struct UserDef *userdef); void BKE_blender_userdef_app_template_data_set_and_free(struct UserDef *userdef); +/** + * When loading a new userdef from file, + * or when exiting Blender. + */ void BKE_blender_userdef_data_free(struct UserDef *userdef, bool clear_fonts); /* Blenders' own atexit (avoids leaking) */ diff --git a/source/blender/blenkernel/BKE_blender_copybuffer.h b/source/blender/blenkernel/BKE_blender_copybuffer.h index 4dd7145e66d..abfb37ef959 100644 --- a/source/blender/blenkernel/BKE_blender_copybuffer.h +++ b/source/blender/blenkernel/BKE_blender_copybuffer.h @@ -30,16 +30,54 @@ struct Main; struct ReportList; struct bContext; -/* copybuffer (wrapper for BKE_blendfile_write_partial) */ +/* Copy-buffer (wrapper for BKE_blendfile_write_partial). */ + +/** + * Initialize a copy operation. + */ void BKE_copybuffer_copy_begin(struct Main *bmain_src); +/** + * Mark an ID to be copied. Should only be called after a call to #BKE_copybuffer_copy_begin. + */ void BKE_copybuffer_copy_tag_ID(struct ID *id); +/** + * Finalize a copy operation into given .blend file 'buffer'. + * + * \param filename: Full path to the .blend file used as copy/paste buffer. + * + * \return true on success, false otherwise. + */ bool BKE_copybuffer_copy_end(struct Main *bmain_src, const char *filename, struct ReportList *reports); +/** + * Paste data-blocks from the given .blend file 'buffer' (i.e. append them). + * + * Unlike #BKE_copybuffer_paste, it does not perform any instantiation of collections/objects/etc. + * + * \param libname: Full path to the .blend file used as copy/paste buffer. + * \param id_types_mask: Only directly link IDs of those types from the given .blend file buffer. + * + * \return true on success, false otherwise. + */ bool BKE_copybuffer_read(struct Main *bmain_dst, const char *libname, struct ReportList *reports, const uint64_t id_types_mask); +/** + * Paste data-blocks from the given .blend file 'buffer' (i.e. append them). + * + * Similar to #BKE_copybuffer_read, but also handles instantiation of collections/objects/etc. + * + * \param libname: Full path to the .blend file used as copy/paste buffer. + * \param flag: A combination of #eBLOLibLinkFlags and ##eFileSel_Params_Flag to control + * link/append behavior. + * \note Ignores #FILE_LINK flag, since it always appends IDs. + * \param id_types_mask: Only directly link IDs of those types from the given .blend file buffer. + * + * \return Number of IDs directly pasted from the buffer + * (does not includes indirectly linked ones). + */ int BKE_copybuffer_paste(struct bContext *C, const char *libname, const int flag, diff --git a/source/blender/blenkernel/BKE_blendfile.h b/source/blender/blenkernel/BKE_blendfile.h index 3e0a343a766..b3211b1dbbc 100644 --- a/source/blender/blenkernel/BKE_blendfile.h +++ b/source/blender/blenkernel/BKE_blendfile.h @@ -33,6 +33,14 @@ struct ReportList; struct UserDef; struct bContext; +/** + * Shared setup function that makes the data from `bfd` into the current blend file, + * replacing the contents of #G.main. + * This uses the bfd #BKE_blendfile_read and similarly named functions. + * + * This is done in a separate step so the caller may perform actions after it is known the file + * loaded correctly but before the file replaces the existing blend file contents. + */ void BKE_blendfile_read_setup_ex(struct bContext *C, struct BlendFileData *bfd, const struct BlendFileReadParams *params, @@ -46,28 +54,56 @@ void BKE_blendfile_read_setup(struct bContext *C, const struct BlendFileReadParams *params, struct BlendFileReadReport *reports); +/** + * \return Blend file data, this must be passed to #BKE_blendfile_read_setup when non-NULL. + */ struct BlendFileData *BKE_blendfile_read(const char *filepath, const struct BlendFileReadParams *params, struct BlendFileReadReport *reports); +/** + * \return Blend file data, this must be passed to #BKE_blendfile_read_setup when non-NULL. + */ struct BlendFileData *BKE_blendfile_read_from_memory(const void *filebuf, int filelength, const struct BlendFileReadParams *params, struct ReportList *reports); +/** + * \return Blend file data, this must be passed to #BKE_blendfile_read_setup when non-NULL. + * \note `memfile` is the undo buffer. + */ struct BlendFileData *BKE_blendfile_read_from_memfile(struct Main *bmain, struct MemFile *memfile, const struct BlendFileReadParams *params, struct ReportList *reports); +/** + * Utility to make a file 'empty' used for startup to optionally give an empty file. + * Handy for tests. + */ void BKE_blendfile_read_make_empty(struct bContext *C); +/** + * Only read the #UserDef from a .blend. + */ struct UserDef *BKE_blendfile_userdef_read(const char *filepath, struct ReportList *reports); struct UserDef *BKE_blendfile_userdef_read_from_memory(const void *filebuf, int filelength, struct ReportList *reports); struct UserDef *BKE_blendfile_userdef_from_defaults(void); +/** + * Only write the #UserDef in a `.blend`. + * \return success. + */ bool BKE_blendfile_userdef_write(const char *filepath, struct ReportList *reports); +/** + * Only write the #UserDef in a `.blend`, merging with the existing blend file. + * \return success. + * + * \note In the future we should re-evaluate user preferences, + * possibly splitting out system/hardware specific preferences. + */ bool BKE_blendfile_userdef_write_app_template(const char *filepath, struct ReportList *reports); bool BKE_blendfile_userdef_write_all(struct ReportList *reports); @@ -81,9 +117,14 @@ bool BKE_blendfile_workspace_config_write(struct Main *bmain, struct ReportList *reports); void BKE_blendfile_workspace_config_data_free(struct WorkspaceConfigFileData *workspace_config); -/* partial blend file writing */ +/* Partial blend file writing. */ + void BKE_blendfile_write_partial_tag_ID(struct ID *id, bool set); void BKE_blendfile_write_partial_begin(struct Main *bmain_src); +/** + * \param remap_mode: Choose the kind of path remapping or none #eBLO_WritePathRemap. + * \return Success. + */ bool BKE_blendfile_write_partial(struct Main *bmain_src, const char *filepath, const int write_flags, diff --git a/source/blender/blenkernel/BKE_blendfile_link_append.h b/source/blender/blenkernel/BKE_blendfile_link_append.h index f8db1b2c435..52b8cc8c6f2 100644 --- a/source/blender/blenkernel/BKE_blendfile_link_append.h +++ b/source/blender/blenkernel/BKE_blendfile_link_append.h @@ -36,23 +36,65 @@ struct View3D; typedef struct BlendfileLinkAppendContext BlendfileLinkAppendContext; typedef struct BlendfileLinkAppendContextItem BlendfileLinkAppendContextItem; +/** + * Allocate and initialize a new context to link/append data-blocks. + * + * \param flag: A combination of #eFileSel_Params_Flag from DNA_space_types.h & #eBLOLibLinkFlags + * from BLO_readfile.h + */ BlendfileLinkAppendContext *BKE_blendfile_link_append_context_new( struct LibraryLink_Params *params); +/** + * Free a link/append context. + */ void BKE_blendfile_link_append_context_free(struct BlendfileLinkAppendContext *lapp_context); +/** + * Set or clear flags in given \a lapp_context. + * + * \param do_set: Set the given \a flag if true, clear it otherwise. + */ void BKE_blendfile_link_append_context_flag_set(struct BlendfileLinkAppendContext *lapp_context, const int flag, const bool do_set); +/** + * Store reference to a Blender's embedded memfile into the context. + * + * \note This is required since embedded startup blender file is handled in `ED` module, which + * cannot be linked in BKE code. + */ void BKE_blendfile_link_append_context_embedded_blendfile_set( struct BlendfileLinkAppendContext *lapp_context, const void *blendfile_mem, int blendfile_memsize); +/** Clear reference to Blender's embedded startup file into the context. */ void BKE_blendfile_link_append_context_embedded_blendfile_clear( struct BlendfileLinkAppendContext *lapp_context); +/** + * Add a new source library to search for items to be linked to the given link/append context. + * + * \param libname: the absolute path to the library blend file. + * \param blo_handle: the blend file handle of the library, NULL is not available. Note that this + * is only borrowed for linking purpose, no releasing or other management will + * be performed by #BKE_blendfile_link_append code on it. + * + * \note *Never* call #BKE_blendfile_link_append_context_library_add() + * after having added some items. + */ void BKE_blendfile_link_append_context_library_add(struct BlendfileLinkAppendContext *lapp_context, const char *libname, struct BlendHandle *blo_handle); +/** + * Add a new item (data-block name and `idcode`) to be searched and linked/appended from libraries + * associated to the given context. + * + * \param userdata: an opaque user-data pointer stored in generated link/append item. + * + * TODO: Add a more friendly version of this that combines it with the call to + * #BKE_blendfile_link_append_context_item_library_index_enable to enable the added item for all + * added library sources. + */ struct BlendfileLinkAppendContextItem *BKE_blendfile_link_append_context_item_add( struct BlendfileLinkAppendContext *lapp_context, const char *idname, @@ -60,16 +102,37 @@ struct BlendfileLinkAppendContextItem *BKE_blendfile_link_append_context_item_ad void *userdata); #define BLENDFILE_LINK_APPEND_INVALID -1 +/** + * Search for all ID matching given `id_types_filter` in given `library_index`, and add them to + * the list of items to process. + * + * \note #BKE_blendfile_link_append_context_library_add should never be called on the same + *`lapp_context` after this function. + * + * \param id_types_filter: A set of `FILTER_ID` bitflags, the types of IDs to add to the items + * list. + * \param library_index: The index of the library to look into, in given `lapp_context`. + * + * \return The number of items found and added to the list, or `BLENDFILE_LINK_APPEND_INVALID` if + * it could not open the .blend file. + */ int BKE_blendfile_link_append_context_item_idtypes_from_library_add( struct BlendfileLinkAppendContext *lapp_context, struct ReportList *reports, const uint64_t id_types_filter, const int library_index); +/** + * Enable search of the given \a item into the library stored at given index in the link/append + * context. + */ void BKE_blendfile_link_append_context_item_library_index_enable( struct BlendfileLinkAppendContext *lapp_context, struct BlendfileLinkAppendContextItem *item, const int library_index); +/** + * Check if given link/append context is empty (has no items to process) or not. + */ bool BKE_blendfile_link_append_context_is_empty(struct BlendfileLinkAppendContext *lapp_context); void *BKE_blendfile_link_append_context_item_userdata_get( @@ -89,27 +152,66 @@ typedef enum eBlendfileLinkAppendForeachItemFlag { * See comments in #foreach_libblock_link_append_callback. */ BKE_BLENDFILE_LINK_APPEND_FOREACH_ITEM_FLAG_DO_INDIRECT = 1 << 0, } eBlendfileLinkAppendForeachItemFlag; -/** Callback called by #BKE_blendfile_link_append_context_item_foreach over each (or a subset of +/** + * Callback called by #BKE_blendfile_link_append_context_item_foreach over each (or a subset of * each) of the items in given #BlendfileLinkAppendContext. * * \param userdata: An opaque void pointer passed to the `callback_function`. * - * \return `true` if iteration should continue, `false` otherwise. */ + * \return `true` if iteration should continue, `false` otherwise. + */ typedef bool (*BKE_BlendfileLinkAppendContexteItemFunction)( struct BlendfileLinkAppendContext *lapp_context, struct BlendfileLinkAppendContextItem *item, void *userdata); +/** + * Iterate over all (or a subset) of the items listed in given #BlendfileLinkAppendContext, + * and call the `callback_function` on them. + * + * \param flag: Control which type of items to process (see + * #eBlendfileLinkAppendForeachItemFlag enum flags). + * \param userdata: An opaque void pointer passed to the `callback_function`. + */ void BKE_blendfile_link_append_context_item_foreach( struct BlendfileLinkAppendContext *lapp_context, BKE_BlendfileLinkAppendContexteItemFunction callback_function, const eBlendfileLinkAppendForeachItemFlag flag, void *userdata); +/** + * Perform append operation, using modern ID usage looper to detect which ID should be kept + * linked, made local, duplicated as local, re-used from local etc. + * + * The IDs processed by this functions are the one that have been linked by a previous call to + * #BKE_blendfile_link on the same `lapp_context`. + */ void BKE_blendfile_append(struct BlendfileLinkAppendContext *lapp_context, struct ReportList *reports); +/** + * Perform linking operation on all items added to given `lapp_context`. + */ void BKE_blendfile_link(struct BlendfileLinkAppendContext *lapp_context, struct ReportList *reports); +/** + * Try to relocate all linked IDs added to `lapp_context`, belonging to the given `library`. + * + * This function searches for matching IDs (type and name) in all libraries added to the given + * `lapp_context`. + * + * Typical usages include: + * - Relocating a library: + * - Add the new target library path to `lapp_context`. + * - Add all IDs from the library to relocate to `lapp_context` + * - Mark the new target library to be considered for each ID. + * - Call this function. + * + * - Searching for (e.g.missing) linked IDs in a set or sub-set of libraries: + * - Add all potential library sources paths to `lapp_context`. + * - Add all IDs to search for to `lapp_context`. + * - Mark which libraries should be considered for each ID. + * - Call this function. + */ void BKE_blendfile_library_relocate(struct BlendfileLinkAppendContext *lapp_context, struct ReportList *reports, struct Library *library, diff --git a/source/blender/blenkernel/BKE_boids.h b/source/blender/blenkernel/BKE_boids.h index 71a4d35767f..a9c8ad6422f 100644 --- a/source/blender/blenkernel/BKE_boids.h +++ b/source/blender/blenkernel/BKE_boids.h @@ -51,7 +51,13 @@ typedef struct BoidBrainData { } BoidBrainData; void boids_precalc_rules(struct ParticleSettings *part, float cfra); +/** + * Determines the velocity the boid wants to have. + */ void boid_brain(BoidBrainData *bbd, int p, struct ParticleData *pa); +/** + * Tries to realize the wanted velocity taking all constraints into account. + */ void boid_body(BoidBrainData *bbd, struct ParticleData *pa); void boid_default_settings(struct BoidSettings *boids); struct BoidRule *boid_new_rule(int type); diff --git a/source/blender/blenkernel/BKE_brush.h b/source/blender/blenkernel/BKE_brush.h index c5f1af4c755..a0f3733588a 100644 --- a/source/blender/blenkernel/BKE_brush.h +++ b/source/blender/blenkernel/BKE_brush.h @@ -39,49 +39,93 @@ struct UnifiedPaintSettings; // enum eCurveMappingPreset; -/* globals for brush execution */ +/* Globals for brush execution. */ + void BKE_brush_system_init(void); void BKE_brush_system_exit(void); -/* datablock functions */ +/* Data-block functions. */ + +/** + * \note Resulting brush will have two users: one as a fake user, + * another is assumed to be used by the caller. + */ struct Brush *BKE_brush_add(struct Main *bmain, const char *name, const eObjectMode ob_mode); +/** + * Add a new gp-brush. + */ struct Brush *BKE_brush_add_gpencil(struct Main *bmain, struct ToolSettings *ts, const char *name, eObjectMode mode); +/** + * Delete a Brush. + */ bool BKE_brush_delete(struct Main *bmain, struct Brush *brush); +/** + * Add grease pencil settings. + */ void BKE_brush_init_gpencil_settings(struct Brush *brush); struct Brush *BKE_brush_first_search(struct Main *bmain, const eObjectMode ob_mode); void BKE_brush_sculpt_reset(struct Brush *brush); +/** + * Create a set of grease pencil Drawing presets. + */ void BKE_brush_gpencil_paint_presets(struct Main *bmain, struct ToolSettings *ts, const bool reset); +/** + * Create a set of grease pencil Vertex Paint presets. + */ void BKE_brush_gpencil_vertex_presets(struct Main *bmain, struct ToolSettings *ts, const bool reset); +/** + * Create a set of grease pencil Sculpt Paint presets. + */ void BKE_brush_gpencil_sculpt_presets(struct Main *bmain, struct ToolSettings *ts, const bool reset); +/** + * Create a set of grease pencil Weight Paint presets. + */ void BKE_brush_gpencil_weight_presets(struct Main *bmain, struct ToolSettings *ts, const bool reset); void BKE_gpencil_brush_preset_set(struct Main *bmain, struct Brush *brush, const short type); -/* jitter */ void BKE_brush_jitter_pos(const struct Scene *scene, struct Brush *brush, const float pos[2], float jitterpos[2]); void BKE_brush_randomize_texture_coords(struct UnifiedPaintSettings *ups, bool mask); -/* brush curve */ +/* Brush curve. */ + +/** + * Library Operations + */ void BKE_brush_curve_preset(struct Brush *b, enum eCurveMappingPreset preset); +/** + * Uses the brush curve control to find a strength value between 0 and 1. + */ float BKE_brush_curve_strength_clamped(const struct Brush *br, float p, const float len); +/** + * Uses the brush curve control to find a strength value. + */ float BKE_brush_curve_strength(const struct Brush *br, float p, const float len); -/* sampling */ +/* Sampling. */ + +/** + * Generic texture sampler for 3D painting systems. + * point has to be either in region space mouse coordinates, + * or 3d world coordinates for 3D mapping. + * + * RGBA outputs straight alpha. + */ float BKE_brush_sample_tex_3d(const struct Scene *scene, const struct Brush *br, const float point[3], @@ -94,15 +138,18 @@ float BKE_brush_sample_masktex(const struct Scene *scene, const int thread, struct ImagePool *pool); -/* texture */ +/* Texture. */ + unsigned int *BKE_brush_gen_texture_cache(struct Brush *br, int half_side, bool use_secondary); -/* radial control */ +/** + * Radial control. + */ struct ImBuf *BKE_brush_gen_radial_control_imbuf(struct Brush *br, bool secondary, bool display_gradient); -/* unified strength size and color */ +/* Unified strength size and color. */ const float *BKE_brush_color_get(const struct Scene *scene, const struct Brush *brush); const float *BKE_brush_secondary_color_get(const struct Scene *scene, const struct Brush *brush); @@ -127,12 +174,16 @@ bool BKE_brush_use_size_pressure(const struct Brush *brush); bool BKE_brush_sculpt_has_secondary_color(const struct Brush *brush); -/* scale unprojected radius to reflect a change in the brush's 2D size */ +/** + * Scale unprojected radius to reflect a change in the brush's 2D size. + */ void BKE_brush_scale_unprojected_radius(float *unprojected_radius, int new_brush_size, int old_brush_size); -/* scale brush size to reflect a change in the brush's unprojected radius */ +/** + * Scale brush size to reflect a change in the brush's unprojected radius. + */ void BKE_brush_scale_size(int *r_brush_size, float new_unprojected_radius, float old_unprojected_radius); diff --git a/source/blender/blenkernel/BKE_bvhutils.h b/source/blender/blenkernel/BKE_bvhutils.h index bb95985ef4c..50fef9149ad 100644 --- a/source/blender/blenkernel/BKE_bvhutils.h +++ b/source/blender/blenkernel/BKE_bvhutils.h @@ -48,7 +48,7 @@ struct BVHCache; typedef struct BVHTreeFromEditMesh { struct BVHTree *tree; - /** Default callbacks to bvh nearest and ray-cast. */ + /** Default callbacks to BVH nearest and ray-cast. */ BVHTree_NearestPointCallback nearest_callback; BVHTree_RayCastCallback raycast_callback; @@ -65,7 +65,7 @@ typedef struct BVHTreeFromEditMesh { typedef struct BVHTreeFromMesh { struct BVHTree *tree; - /** Default callbacks to bvh nearest and ray-cast. */ + /** Default callbacks to BVH nearest and ray-cast. */ BVHTree_NearestPointCallback nearest_callback; BVHTree_RayCastCallback raycast_callback; @@ -105,7 +105,7 @@ typedef enum BVHCacheType { } BVHCacheType; /** - * Builds a bvh tree where nodes are the relevant elements of the given mesh. + * Builds a BVH tree where nodes are the relevant elements of the given mesh. * Configures #BVHTreeFromMesh. * * The tree is build in mesh space coordinates, this means special care must be made on queries @@ -113,11 +113,14 @@ typedef enum BVHCacheType { * Reason for this is that bvh_from_mesh_* can use a cache in some cases and so it * becomes possible to reuse a #BVHTree. * - * free_bvhtree_from_mesh should be called when the tree is no longer needed. + * #free_bvhtree_from_mesh should be called when the tree is no longer needed. */ BVHTree *bvhtree_from_editmesh_verts( BVHTreeFromEditMesh *data, struct BMEditMesh *em, float epsilon, int tree_type, int axis); +/** + * Builds a BVH-tree where nodes are the vertices of the given `em`. + */ BVHTree *bvhtree_from_editmesh_verts_ex(BVHTreeFromEditMesh *data, struct BMEditMesh *em, const BLI_bitmap *mask, @@ -129,6 +132,13 @@ BVHTree *bvhtree_from_editmesh_verts_ex(BVHTreeFromEditMesh *data, struct BVHCache **bvh_cache_p, ThreadMutex *mesh_eval_mutex); +/** + * Builds a BVH-tree where nodes are the given vertices (NOTE: does not copy given `vert`!). + * \param vert_allocated: if true, vert freeing will be done when freeing data. + * \param verts_mask: if not null, true elements give which vert to add to BVH-tree. + * \param verts_num_active: if >= 0, number of active verts to add to BVH-tree + * (else will be computed from mask). + */ BVHTree *bvhtree_from_mesh_verts_ex(struct BVHTreeFromMesh *data, const struct MVert *vert, const int verts_num, @@ -145,6 +155,9 @@ BVHTree *bvhtree_from_mesh_verts_ex(struct BVHTreeFromMesh *data, BVHTree *bvhtree_from_editmesh_edges( BVHTreeFromEditMesh *data, struct BMEditMesh *em, float epsilon, int tree_type, int axis); +/** + * Builds a BVH-tree where nodes are the edges of the given `em`. + */ BVHTree *bvhtree_from_editmesh_edges_ex(BVHTreeFromEditMesh *data, struct BMEditMesh *em, const BLI_bitmap *edges_mask, @@ -156,6 +169,14 @@ BVHTree *bvhtree_from_editmesh_edges_ex(BVHTreeFromEditMesh *data, struct BVHCache **bvh_cache_p, ThreadMutex *mesh_eval_mutex); +/** + * Builds a BVH-tree where nodes are the given edges. + * \param vert, vert_allocated: if true, elem freeing will be done when freeing data. + * \param edge, edge_allocated: if true, elem freeing will be done when freeing data. + * \param edges_mask: if not null, true elements give which vert to add to BVH-tree. + * \param edges_num_active: if >= 0, number of active edges to add to BVH-tree + * (else will be computed from mask). + */ BVHTree *bvhtree_from_mesh_edges_ex(struct BVHTreeFromMesh *data, const struct MVert *vert, const bool vert_allocated, @@ -171,6 +192,15 @@ BVHTree *bvhtree_from_mesh_edges_ex(struct BVHTreeFromMesh *data, struct BVHCache **bvh_cache_p, ThreadMutex *mesh_eval_mutex); +/** + * Builds a BVH-tree where nodes are the given tessellated faces + * (NOTE: does not copy given mfaces!). + * \param vert_allocated: if true, vert freeing will be done when freeing data. + * \param face_allocated: if true, face freeing will be done when freeing data. + * \param faces_mask: if not null, true elements give which faces to add to BVH-tree. + * \param faces_num_active: if >= 0, number of active faces to add to BVH-tree + * (else will be computed from mask). + */ BVHTree *bvhtree_from_mesh_faces_ex(struct BVHTreeFromMesh *data, const struct MVert *vert, const bool vert_allocated, @@ -189,6 +219,9 @@ BVHTree *bvhtree_from_mesh_faces_ex(struct BVHTreeFromMesh *data, BVHTree *bvhtree_from_editmesh_looptri( BVHTreeFromEditMesh *data, struct BMEditMesh *em, float epsilon, int tree_type, int axis); +/** + * Builds a BVH-tree where nodes are the `looptri` faces of the given `bm`. + */ BVHTree *bvhtree_from_editmesh_looptri_ex(BVHTreeFromEditMesh *data, struct BMEditMesh *em, const BLI_bitmap *mask, @@ -200,6 +233,11 @@ BVHTree *bvhtree_from_editmesh_looptri_ex(BVHTreeFromEditMesh *data, struct BVHCache **bvh_cache_p, ThreadMutex *mesh_eval_mutex); +/** + * Builds a BVH-tree where nodes are the looptri faces of the given mesh. + * + * \note for edit-mesh this is currently a duplicate of #bvhtree_from_mesh_faces_ex + */ BVHTree *bvhtree_from_mesh_looptri_ex(struct BVHTreeFromMesh *data, const struct MVert *vert, const bool vert_allocated, @@ -217,11 +255,20 @@ BVHTree *bvhtree_from_mesh_looptri_ex(struct BVHTreeFromMesh *data, struct BVHCache **bvh_cache_p, ThreadMutex *mesh_eval_mutex); +/** + * Builds or queries a BVH-cache for the cache BVH-tree of the request type. + * + * \note This function only fills a cache, and therefore the mesh argument can + * be considered logically const. Concurrent access is protected by a mutex. + */ BVHTree *BKE_bvhtree_from_mesh_get(struct BVHTreeFromMesh *data, const struct Mesh *mesh, const BVHCacheType bvh_cache_type, const int tree_type); +/** + * Builds or queries a BVH-cache for the cache BVH-tree of the request type. + */ BVHTree *BKE_bvhtree_from_editmesh_get(BVHTreeFromEditMesh *data, struct BMEditMesh *em, const int tree_type, @@ -230,9 +277,12 @@ BVHTree *BKE_bvhtree_from_editmesh_get(BVHTreeFromEditMesh *data, ThreadMutex *mesh_eval_mutex); /** - * Frees data allocated by a call to bvhtree_from_mesh_*. + * Frees data allocated by a call to `bvhtree_from_editmesh_*`. */ void free_bvhtree_from_editmesh(struct BVHTreeFromEditMesh *data); +/** + * Frees data allocated by a call to `bvhtree_from_mesh_*`. + */ void free_bvhtree_from_mesh(struct BVHTreeFromMesh *data); /** @@ -272,6 +322,9 @@ void free_bvhtree_from_pointcloud(struct BVHTreeFromPointCloud *data); bool bvhcache_has_tree(const struct BVHCache *bvh_cache, const BVHTree *tree); struct BVHCache *bvhcache_init(void); +/** + * Frees a BVH-cache. + */ void bvhcache_free(struct BVHCache *bvh_cache); #ifdef __cplusplus diff --git a/source/blender/blenkernel/BKE_cachefile.h b/source/blender/blenkernel/BKE_cachefile.h index 836597f95da..ac621bfdcb9 100644 --- a/source/blender/blenkernel/BKE_cachefile.h +++ b/source/blender/blenkernel/BKE_cachefile.h @@ -61,6 +61,12 @@ void BKE_cachefile_reader_open(struct CacheFile *cache_file, const char *object_path); void BKE_cachefile_reader_free(struct CacheFile *cache_file, struct CacheReader **reader); +/** + * Determine whether the #CacheFile should use a render engine procedural. If so, data is not read + * from the file and bounding boxes are used to represent the objects in the Scene. + * Render engines will receive the bounding box as a placeholder but can instead + * load the data directly if they support it. + */ bool BKE_cache_file_uses_render_procedural(const struct CacheFile *cache_file, struct Scene *scene, const int dag_eval_mode); diff --git a/source/blender/blenkernel/BKE_callbacks.h b/source/blender/blenkernel/BKE_callbacks.h index 7c518f33c89..c125b081b49 100644 --- a/source/blender/blenkernel/BKE_callbacks.h +++ b/source/blender/blenkernel/BKE_callbacks.h @@ -133,6 +133,9 @@ void BKE_callback_add(bCallbackFuncStore *funcstore, eCbEvent evt); void BKE_callback_remove(bCallbackFuncStore *funcstore, eCbEvent evt); void BKE_callback_global_init(void); +/** + * Call on application exit. + */ void BKE_callback_global_finalize(void); #ifdef __cplusplus diff --git a/source/blender/blenkernel/BKE_camera.h b/source/blender/blenkernel/BKE_camera.h index b42fcbe7808..d91b6505672 100644 --- a/source/blender/blenkernel/BKE_camera.h +++ b/source/blender/blenkernel/BKE_camera.h @@ -37,22 +37,26 @@ struct Scene; struct View3D; struct rctf; -/* Camera Datablock */ +/* Camera Data-block */ void *BKE_camera_add(struct Main *bmain, const char *name); /* Camera Usage */ +/** + * Get the camera's DOF value, takes the DOF object into account. + */ float BKE_camera_object_dof_distance(struct Object *ob); int BKE_camera_sensor_fit(int sensor_fit, float sizex, float sizey); float BKE_camera_sensor_size(int sensor_fit, float sensor_x, float sensor_y); -/* Camera Parameters: +/** + * Camera Parameters: * * Intermediate struct for storing camera parameters from various sources, - * to unify computation of viewplane, window matrix, ... */ - + * to unify computation of view-plane, window matrix, ... etc. + */ typedef struct CameraParams { /* lens */ bool is_ortho; @@ -84,7 +88,7 @@ typedef struct CameraParams { float winmat[4][4]; } CameraParams; -/* values for CameraParams.zoom, need to be taken into account for some operations */ +/* Values for CameraParams.zoom, need to be taken into account for some operations. */ #define CAMERA_PARAM_ZOOM_INIT_CAMOB 1.0f #define CAMERA_PARAM_ZOOM_INIT_PERSP 2.0f @@ -97,6 +101,9 @@ void BKE_camera_params_from_view3d(CameraParams *params, void BKE_camera_params_compute_viewplane( CameraParams *params, int winx, int winy, float aspx, float aspy); +/** + * View-plane is assumed to be already computed. + */ void BKE_camera_params_compute_matrix(CameraParams *params); /* Camera View Frame */ @@ -114,6 +121,9 @@ void BKE_camera_view_frame(const struct Scene *scene, const struct Camera *camera, float r_vec[4][3]); +/** + * \param r_scale: only valid/useful for orthographic cameras. + */ bool BKE_camera_view_frame_fit_to_scene(struct Depsgraph *depsgraph, const struct Scene *scene, struct Object *camera_ob, @@ -128,9 +138,15 @@ bool BKE_camera_view_frame_fit_to_coords(const struct Depsgraph *depsgraph, /* Camera multi-view API */ +/** + * Returns the camera to be used for render. + */ struct Object *BKE_camera_multiview_render(const struct Scene *scene, struct Object *camera, const char *viewname); +/** + * The view matrix is used by the viewport drawing, it is basically the inverted model matrix. + */ void BKE_camera_multiview_view_matrix(const struct RenderData *rd, const struct Object *camera, const bool is_left, @@ -158,6 +174,7 @@ bool BKE_camera_multiview_spherical_stereo(const struct RenderData *rd, const struct Object *camera); /* Camera background image API */ + struct CameraBGImage *BKE_camera_background_image_new(struct Camera *cam); void BKE_camera_background_image_remove(struct Camera *cam, struct CameraBGImage *bgpic); void BKE_camera_background_image_clear(struct Camera *cam); diff --git a/source/blender/blenkernel/BKE_cloth.h b/source/blender/blenkernel/BKE_cloth.h index dbf285feb92..ee73b926886 100644 --- a/source/blender/blenkernel/BKE_cloth.h +++ b/source/blender/blenkernel/BKE_cloth.h @@ -235,7 +235,9 @@ int cloth_bvh_collision(struct Depsgraph *depsgraph, /* cloth.c */ /* Needed for modifier.c */ +/** Frees all. */ void cloth_free_modifier_extern(struct ClothModifierData *clmd); +/** Frees all. */ void cloth_free_modifier(struct ClothModifierData *clmd); void clothModifier_do(struct ClothModifierData *clmd, struct Depsgraph *depsgraph, diff --git a/source/blender/blenkernel/BKE_collection.h b/source/blender/blenkernel/BKE_collection.h index 2c7143be60e..46c1fe0d33d 100644 --- a/source/blender/blenkernel/BKE_collection.h +++ b/source/blender/blenkernel/BKE_collection.h @@ -54,20 +54,51 @@ typedef struct CollectionParent { /* Collections */ +/** + * Add a collection to a collection ListBase and synchronize all render layers + * The ListBase is NULL when the collection is to be added to the master collection + */ struct Collection *BKE_collection_add(struct Main *bmain, struct Collection *parent, const char *name); +/** + * Add \a collection_dst to all scene collections that reference object \a ob_src is in. + * Used to replace an instance object with a collection (library override operator). + * + * Logic is very similar to #BKE_collection_object_add_from(). + */ void BKE_collection_add_from_object(struct Main *bmain, struct Scene *scene, const struct Object *ob_src, struct Collection *collection_dst); +/** + * Add \a collection_dst to all scene collections that reference collection \a collection_src is + * in. + * + * Logic is very similar to #BKE_collection_object_add_from(). + */ void BKE_collection_add_from_collection(struct Main *bmain, struct Scene *scene, struct Collection *collection_src, struct Collection *collection_dst); +/** + * Free (or release) any data used by this collection (does not free the collection itself). + */ void BKE_collection_free_data(struct Collection *collection); +/** + * Remove a collection, optionally removing its child objects or moving + * them to parent collections. + */ bool BKE_collection_delete(struct Main *bmain, struct Collection *collection, bool hierarchy); +/** + * Make a deep copy (aka duplicate) of the given collection and all of its children, recursively. + * + * \warning This functions will clear all \a bmain #ID.idnew pointers, unless \a + * #LIB_ID_DUPLICATE_IS_SUBPROCESS duplicate option is passed on, in which case caller is + * responsible to reconstruct collection dependencies information's + * (i.e. call #BKE_main_collection_sync). + */ struct Collection *BKE_collection_duplicate(struct Main *bmain, struct Collection *parent, struct Collection *collection, @@ -91,28 +122,60 @@ struct Collection *BKE_collection_object_find(struct Main *bmain, struct Object *ob); bool BKE_collection_is_empty(const struct Collection *collection); +/** + * Add object to collection + */ bool BKE_collection_object_add(struct Main *bmain, struct Collection *collection, struct Object *ob); +/** + * Add \a ob_dst to all scene collections that reference object \a ob_src is in. + * Used for copying objects. + * + * Logic is very similar to #BKE_collection_add_from_object() + */ void BKE_collection_object_add_from(struct Main *bmain, struct Scene *scene, struct Object *ob_src, struct Object *ob_dst); +/** + * Remove object from collection. + */ bool BKE_collection_object_remove(struct Main *bmain, struct Collection *collection, struct Object *object, const bool free_us); +/** + * Move object from a collection into another + * + * If source collection is NULL move it from all the existing collections. + */ void BKE_collection_object_move(struct Main *bmain, struct Scene *scene, struct Collection *collection_dst, struct Collection *collection_src, struct Object *ob); +/** + * Remove object from all collections of scene + */ bool BKE_scene_collections_object_remove(struct Main *bmain, struct Scene *scene, struct Object *object, const bool free_us); void BKE_collections_object_remove_nulls(struct Main *bmain); +/** + * Remove all NULL children from parent collections of changed \a collection. + * This is used for library remapping, where these pointers have been set to NULL. + * Otherwise this should never happen. + * + * \note caller must ensure #BKE_main_collection_sync_remap() is called afterwards! + * + * \param parent_collection: The collection owning the pointers that were remapped. May be \a NULL, + * in which case whole \a bmain database of collections is checked. + * \param child_collection: The collection that was remapped to another pointer. May be \a NULL, + * in which case whole \a bmain database of collections is checked. + */ void BKE_collections_child_remove_nulls(struct Main *bmain, struct Collection *parent_collection, struct Collection *child_collection); @@ -136,9 +199,24 @@ struct Base *BKE_collection_or_layer_objects(const struct ViewLayer *view_layer, /* Editing. */ +/** + * Return Scene Collection for a given index. + * + * The index is calculated from top to bottom counting the children before the siblings. + */ struct Collection *BKE_collection_from_index(struct Scene *scene, const int index); +/** + * The automatic/fallback name of a new collection. + */ void BKE_collection_new_name_get(struct Collection *collection_parent, char *rname); +/** + * The name to show in the interface. + */ const char *BKE_collection_ui_name_get(struct Collection *collection); +/** + * Select all the objects in this Collection (and its nested collections) for this ViewLayer. + * Return true if any object was selected. + */ bool BKE_collection_objects_select(struct ViewLayer *view_layer, struct Collection *collection, bool deselect); @@ -162,13 +240,36 @@ bool BKE_collection_move(struct Main *bmain, bool relative_after, struct Collection *collection); +/** + * Find potential cycles in collections. + * + * \param new_ancestor: the potential new owner of given \a collection, + * or the collection to check if the later is NULL. + * \param collection: the collection we want to add to \a new_ancestor, + * may be NULL if we just want to ensure \a new_ancestor does not already have cycles. + * \return true if a cycle is found. + */ bool BKE_collection_cycle_find(struct Collection *new_ancestor, struct Collection *collection); +/** + * Find and fix potential cycles in collections. + * + * \param collection: The collection to check for existing cycles. + * \return true if cycles are found and fixed. + */ bool BKE_collection_cycles_fix(struct Main *bmain, struct Collection *collection); bool BKE_collection_has_collection(const struct Collection *parent, const struct Collection *collection); +/** + * Rebuild parent relationships from child ones, for all children of given \a collection. + * + * \note Given collection is assumed to already have valid parents. + */ void BKE_collection_parent_relations_rebuild(struct Collection *collection); +/** + * Rebuild parent relationships from child ones, for all collections in given \a bmain. + */ void BKE_main_collections_parent_relations_rebuild(struct Main *bmain); /* .blend file I/O */ @@ -224,6 +325,10 @@ typedef void (*BKE_scene_collections_Cb)(struct Collection *ob, void *data); /* Iteration over collections in scene. */ +/** + * Only use this in non-performance critical situations + * (it iterates over all scene collections twice) + */ void BKE_scene_collections_iterator_begin(struct BLI_Iterator *iter, void *data_in); void BKE_scene_collections_iterator_next(struct BLI_Iterator *iter); void BKE_scene_collections_iterator_end(struct BLI_Iterator *iter); @@ -232,6 +337,13 @@ void BKE_scene_objects_iterator_begin(struct BLI_Iterator *iter, void *data_in); void BKE_scene_objects_iterator_next(struct BLI_Iterator *iter); void BKE_scene_objects_iterator_end(struct BLI_Iterator *iter); +/** + * Generate a new #GSet (or extend given `objects_gset` if not NULL) with all objects referenced by + * all collections of given `scene`. + * + * \note This will include objects without a base currently + * (because they would belong to excluded collections only e.g.). + */ struct GSet *BKE_scene_objects_as_gset(struct Scene *scene, struct GSet *objects_gset); #define FOREACH_SCENE_COLLECTION_BEGIN(scene, _instance) \ diff --git a/source/blender/blenkernel/BKE_collision.h b/source/blender/blenkernel/BKE_collision.h index 2c21b7355d6..71929d1797c 100644 --- a/source/blender/blenkernel/BKE_collision.h +++ b/source/blender/blenkernel/BKE_collision.h @@ -116,8 +116,11 @@ void bvhtree_update_from_mvert(struct BVHTree *bvhtree, ///////////////////////////////////////////////// -/* move Collision modifier object inter-frame with step = [0,1] - * defined in collisions.c */ +/** + * Move Collision modifier object inter-frame with step = [0,1] + * + * \param step: is limited from 0 (frame start position) to 1 (frame end position). + */ void collision_move_object(struct CollisionModifierData *collmd, const float step, const float prevstep, @@ -135,6 +138,11 @@ typedef struct CollisionRelation { struct Object *ob; } CollisionRelation; +/** + * Create list of collision relations in the collection or entire scene. + * This is used by the depsgraph to build relations, as well as faster + * lookup of colliders during evaluation. + */ struct ListBase *BKE_collision_relations_create(struct Depsgraph *depsgraph, struct Collection *collection, unsigned int modifier_type); @@ -142,6 +150,10 @@ void BKE_collision_relations_free(struct ListBase *relations); /* Collision object lists for physics simulation evaluation. */ +/** + * Create effective list of colliders from relations built beforehand. + * Self will be excluded. + */ struct Object **BKE_collision_objects_create(struct Depsgraph *depsgraph, struct Object *self, struct Collection *collection, @@ -155,6 +167,10 @@ typedef struct ColliderCache { struct CollisionModifierData *collmd; } ColliderCache; +/** + * Create effective list of colliders from relations built beforehand. + * Self will be excluded. + */ struct ListBase *BKE_collider_cache_create(struct Depsgraph *depsgraph, struct Object *self, struct Collection *collection); diff --git a/source/blender/blenkernel/BKE_colortools.h b/source/blender/blenkernel/BKE_colortools.h index 109947cece4..62d0afa4901 100644 --- a/source/blender/blenkernel/BKE_colortools.h +++ b/source/blender/blenkernel/BKE_colortools.h @@ -59,40 +59,85 @@ enum { CURVEMAP_SLOPE_POS_NEG = 2, }; +/** + * Reset the view for current curve. + */ void BKE_curvemapping_reset_view(struct CurveMapping *cumap); void BKE_curvemap_reset(struct CurveMap *cuma, const struct rctf *clipr, int preset, int slope); +/** + * Removes with flag set. + */ void BKE_curvemap_remove(struct CurveMap *cuma, const short flag); +/** + * Remove specified point. + */ bool BKE_curvemap_remove_point(struct CurveMap *cuma, struct CurveMapPoint *cmp); struct CurveMapPoint *BKE_curvemap_insert(struct CurveMap *cuma, float x, float y); +/** + * \param type: #eBezTriple_Handle + */ void BKE_curvemap_handle_set(struct CurveMap *cuma, int type); +/** + * \note only does current curvemap!. + */ void BKE_curvemapping_changed(struct CurveMapping *cumap, const bool rem_doubles); void BKE_curvemapping_changed_all(struct CurveMapping *cumap); -/* call before _all_ evaluation functions */ +/** + * Call before _all_ evaluation functions. + */ void BKE_curvemapping_init(struct CurveMapping *cumap); -/* keep these (const CurveMap) - to help with thread safety */ -/* single curve, no table check */ +/** + * Keep these `const CurveMap` - to help with thread safety. + * \note Single curve, no table check. + * \note Table should be verified. + */ float BKE_curvemap_evaluateF(const struct CurveMapping *cumap, const struct CurveMap *cuma, float value); -/* single curve, with table check */ +/** + * Single curve, with table check. + * Works with curve 'cur'. + */ float BKE_curvemapping_evaluateF(const struct CurveMapping *cumap, int cur, float value); +/** + * Vector case. + */ void BKE_curvemapping_evaluate3F(const struct CurveMapping *cumap, float vecout[3], const float vecin[3]); +/** + * RGB case, no black/white points, no pre-multiply. + */ void BKE_curvemapping_evaluateRGBF(const struct CurveMapping *cumap, float vecout[3], const float vecin[3]); +/** + * Byte version of #BKE_curvemapping_evaluateRGBF. + */ void BKE_curvemapping_evaluate_premulRGB(const struct CurveMapping *cumap, unsigned char vecout_byte[3], const unsigned char vecin_byte[3]); +/** + * Same as #BKE_curvemapping_evaluate_premulRGBF + * but black/bwmul are passed as args for the compositor + * where they can change per pixel. + * + * Use in conjunction with #BKE_curvemapping_set_black_white_ex + * + * \param black: Use instead of cumap->black + * \param bwmul: Use instead of cumap->bwmul + */ void BKE_curvemapping_evaluate_premulRGBF_ex(const struct CurveMapping *cumap, float vecout[3], const float vecin[3], const float black[3], const float bwmul[3]); +/** + * RGB with black/white points and pre-multiply. tables are checked. + */ void BKE_curvemapping_evaluate_premulRGBF(const struct CurveMapping *cumap, float vecout[3], const float vecin[3]); @@ -100,12 +145,18 @@ bool BKE_curvemapping_RGBA_does_something(const struct CurveMapping *cumap); void BKE_curvemapping_table_F(const struct CurveMapping *cumap, float **array, int *size); void BKE_curvemapping_table_RGBA(const struct CurveMapping *cumap, float **array, int *size); -/* non-const, these modify the curve */ +/** + * Call when you do images etc, needs restore too. also verifies tables. + * non-const (these modify the curve). + */ void BKE_curvemapping_premultiply(struct CurveMapping *cumap, int restore); void BKE_curvemapping_blend_write(struct BlendWriter *writer, const struct CurveMapping *cumap); void BKE_curvemapping_curves_blend_write(struct BlendWriter *writer, const struct CurveMapping *cumap); +/** + * \note `cumap` itself has been read already. + */ void BKE_curvemapping_blend_read(struct BlendDataReader *reader, struct CurveMapping *cumap); void BKE_histogram_update_sample_line(struct Histogram *hist, @@ -123,16 +174,20 @@ void BKE_color_managed_display_settings_init(struct ColorManagedDisplaySettings void BKE_color_managed_display_settings_copy(struct ColorManagedDisplaySettings *new_settings, const struct ColorManagedDisplaySettings *settings); -/* Initialize view settings to be best suitable for render type of viewing. +/** + * Initialize view settings to be best suitable for render type of viewing. * This will use default view transform from the OCIO configuration if none - * is specified. */ + * is specified. + */ void BKE_color_managed_view_settings_init_render( struct ColorManagedViewSettings *settings, const struct ColorManagedDisplaySettings *display_settings, const char *view_transform); -/* Initialize view settings which are best suitable for viewing non-render - * images. For example,s movie clips while tracking. */ +/** + * Initialize view settings which are best suitable for viewing non-render images. + * For example,s movie clips while tracking. + */ void BKE_color_managed_view_settings_init_default( struct ColorManagedViewSettings *settings, const struct ColorManagedDisplaySettings *display_settings); diff --git a/source/blender/blenkernel/BKE_constraint.h b/source/blender/blenkernel/BKE_constraint.h index 784b395dfa5..1f59efbb0f3 100644 --- a/source/blender/blenkernel/BKE_constraint.h +++ b/source/blender/blenkernel/BKE_constraint.h @@ -45,7 +45,7 @@ extern "C" { typedef struct bConstraintOb { /** to get evaluated armature. */ struct Depsgraph *depsgraph; - /** for system time, part of deglobalization, code nicer later with local time (ton) */ + /** for system time, part of de-globalization, code nicer later with local time (ton) */ struct Scene *scene; /** if pchan, then armature that it comes from, otherwise constraint owner */ struct Object *ob; @@ -61,7 +61,7 @@ typedef struct bConstraintOb { /** type of owner. */ short type; - /** rotation order for constraint owner (as defined in eEulerRotationOrders in BLI_math.h) */ + /** rotation order for constraint owner (as defined in #eEulerRotationOrders in BLI_math.h) */ short rotOrder; } bConstraintOb; @@ -76,7 +76,7 @@ typedef void (*ConstraintIDFunc)(struct bConstraint *con, /* ....... */ /** - * Constraint Type-Info (shorthand in code = cti): + * Constraint Type-Info (shorthand in code = `cti`): * This struct provides function pointers for runtime, so that functions can be * written more generally (with fewer/no special exceptions for various constraints). * @@ -138,49 +138,107 @@ typedef struct bConstraintTypeInfo { } bConstraintTypeInfo; /* Function Prototypes for bConstraintTypeInfo's */ + +/** + * This function should always be used to get the appropriate type-info, as it + * has checks which prevent segfaults in some weird cases. + */ const bConstraintTypeInfo *BKE_constraint_typeinfo_get(struct bConstraint *con); +/** + * This function should be used for getting the appropriate type-info when only + * a constraint type is known. + */ const bConstraintTypeInfo *BKE_constraint_typeinfo_from_type(int type); /* ---------------------------------------------------------------------------- */ /* Constraint function prototypes */ + +/** + * Find the first available, non-duplicate name for a given constraint. + */ void BKE_constraint_unique_name(struct bConstraint *con, struct ListBase *list); +/** + * Allocate and duplicate a single constraint, outside of any object/pose context. + */ struct bConstraint *BKE_constraint_duplicate_ex(struct bConstraint *src, const int flag, const bool do_extern); +/** + * Add a copy of the given constraint for the given bone. + */ struct bConstraint *BKE_constraint_copy_for_pose(struct Object *ob, struct bPoseChannel *pchan, struct bConstraint *src); +/** + * Add a copy of the given constraint for the given object. + */ struct bConstraint *BKE_constraint_copy_for_object(struct Object *ob, struct bConstraint *src); void BKE_constraints_free(struct ListBase *list); +/** + * Free all constraints from a constraint-stack. + */ void BKE_constraints_free_ex(struct ListBase *list, bool do_id_user); void BKE_constraints_copy(struct ListBase *dst, const struct ListBase *src, bool do_extern); +/** + * Duplicate all of the constraints in a constraint stack. + */ void BKE_constraints_copy_ex(struct ListBase *dst, const struct ListBase *src, const int flag, bool do_extern); +/** + * Run the given callback on all ID-blocks in list of constraints. + */ void BKE_constraints_id_loop(struct ListBase *list, ConstraintIDFunc func, void *userdata); void BKE_constraint_free_data(struct bConstraint *con); +/** + * Free data of a specific constraint if it has any info. + * Be sure to run #BIK_clear_data() when freeing an IK constraint, + * unless #DAG_relations_tag_update is called. + */ void BKE_constraint_free_data_ex(struct bConstraint *con, bool do_id_user); bool BKE_constraint_target_uses_bbone(struct bConstraint *con, struct bConstraintTarget *ct); /* Constraint API function prototypes */ + +/** + * Finds the 'active' constraint in a constraint stack. + */ struct bConstraint *BKE_constraints_active_get(struct ListBase *list); +/** + * Set the given constraint as the active one (clearing all the others). + */ void BKE_constraints_active_set(ListBase *list, struct bConstraint *con); struct bConstraint *BKE_constraints_find_name(struct ListBase *list, const char *name); +/** + * Finds the constraint that owns the given target within the object. + */ struct bConstraint *BKE_constraint_find_from_target(struct Object *ob, struct bConstraintTarget *tgt, struct bPoseChannel **r_pchan); +/** + * Check whether given constraint is not local (i.e. from linked data) when the object is a library + * override. + * + * \param con: May be NULL, in which case we consider it as a non-local constraint case. + */ bool BKE_constraint_is_nonlocal_in_liboverride(const struct Object *ob, const struct bConstraint *con); +/** + * Add new constraint for the given object. + */ struct bConstraint *BKE_constraint_add_for_object(struct Object *ob, const char *name, short type); +/** + * Add new constraint for the given bone. + */ struct bConstraint *BKE_constraint_add_for_pose(struct Object *ob, struct bPoseChannel *pchan, const char *name, @@ -190,8 +248,14 @@ bool BKE_constraint_remove_ex(ListBase *list, struct Object *ob, struct bConstraint *con, bool clear_dep); +/** + * Remove the specified constraint from the given constraint stack. + */ bool BKE_constraint_remove(ListBase *list, struct bConstraint *con); +/** + * Apply the specified constraint in the given constraint stack. + */ bool BKE_constraint_apply_for_object(struct Depsgraph *depsgraph, struct Scene *scene, struct Object *ob, @@ -217,17 +281,38 @@ bool BKE_constraint_apply_and_remove_for_pose(struct Depsgraph *depsgraph, void BKE_constraint_panel_expand(struct bConstraint *con); /* Constraints + Proxies function prototypes */ + +/** + * Rescue all constraints tagged as being #CONSTRAINT_PROXY_LOCAL + * (i.e. added to bone that's proxy-synced in this file). + */ void BKE_constraints_proxylocal_extract(struct ListBase *dst, struct ListBase *src); +/** + * Returns if the owner of the constraint is proxy-protected. + */ bool BKE_constraints_proxylocked_owner(struct Object *ob, struct bPoseChannel *pchan); /* Constraint Evaluation function prototypes */ + +/** + * This function MEM_calloc's a #bConstraintOb struct, + * that will need to be freed after evaluation. + */ struct bConstraintOb *BKE_constraints_make_evalob(struct Depsgraph *depsgraph, struct Scene *scene, struct Object *ob, void *subdata, short datatype); +/** + * Cleanup after constraint evaluation. + */ void BKE_constraints_clear_evalob(struct bConstraintOb *cob); +/** + * This function is responsible for the correct transformations/conversions + * of a matrix from one space to another for constraint evaluation. + * For now, this is only implemented for objects and pose-channels. + */ void BKE_constraint_mat_convertspace(struct Object *ob, struct bPoseChannel *pchan, struct bConstraintOb *cob, @@ -236,6 +321,14 @@ void BKE_constraint_mat_convertspace(struct Object *ob, short to, const bool keep_scale); +/** + * This function is a relic from the prior implementations of the constraints system, when all + * constraints either had one or no targets. It used to be called during the main constraint + * solving loop, but is now only used for the remaining cases for a few constraints. + * + * None of the actual calculations of the matrices should be done here! Also, this function is + * not to be used by any new constraints, particularly any that have multiple targets. + */ void BKE_constraint_target_matrix_get(struct Depsgraph *depsgraph, struct Scene *scene, struct bConstraint *con, @@ -244,12 +337,22 @@ void BKE_constraint_target_matrix_get(struct Depsgraph *depsgraph, void *ownerdata, float mat[4][4], float ctime); +/** + * Get the list of targets required for solving a constraint. + */ void BKE_constraint_targets_for_solving_get(struct Depsgraph *depsgraph, struct bConstraint *con, struct bConstraintOb *ob, struct ListBase *targets, float ctime); void BKE_constraint_custom_object_space_get(float r_mat[4][4], struct bConstraint *con); +/** + * This function is called whenever constraints need to be evaluated. Currently, all + * constraints that can be evaluated are every time this gets run. + * + * #BKE_constraints_make_evalob and #BKE_constraints_clear_evalob should be called before and + * after running this function, to sort out cob. + */ void BKE_constraints_solve(struct Depsgraph *depsgraph, struct ListBase *conlist, struct bConstraintOb *cob, diff --git a/source/blender/blenkernel/BKE_context.h b/source/blender/blenkernel/BKE_context.h index b0705ff411f..ac864c7f82c 100644 --- a/source/blender/blenkernel/BKE_context.h +++ b/source/blender/blenkernel/BKE_context.h @@ -247,6 +247,12 @@ PointerRNA CTX_data_pointer_get_type_silent(const bContext *C, const char *member, StructRNA *type); ListBase CTX_data_collection_get(const bContext *C, const char *member); +/** + * \param C: Context. + * \param use_store: Use 'C->wm.store'. + * \param use_rna: Use Include the properties from 'RNA_Context'. + * \param use_all: Don't skip values (currently only "scene"). + */ ListBase CTX_data_dir_get_ex(const bContext *C, const bool use_store, const bool use_rna, @@ -297,6 +303,13 @@ int ctx_data_list_count(const bContext *C, int (*func)(const bContext *, ListBas struct Main *CTX_data_main(const bContext *C); struct Scene *CTX_data_scene(const bContext *C); +/** + * This is tricky. Sometimes the user overrides the render_layer + * but not the scene_collection. In this case what to do? + * + * If the scene_collection is linked to the #ViewLayer we use it. + * Otherwise we fallback to the active one of the #ViewLayer. + */ struct LayerCollection *CTX_data_layer_collection(const bContext *C); struct Collection *CTX_data_collection(const bContext *C); struct ViewLayer *CTX_data_view_layer(const bContext *C); @@ -367,28 +380,34 @@ struct AssetHandle CTX_wm_asset_handle(const bContext *C, bool *r_is_valid); bool CTX_wm_interface_locked(const bContext *C); -/* Gets pointer to the dependency graph. +/** + * Gets pointer to the dependency graph. * If it doesn't exist yet, it will be allocated. * * The result dependency graph is NOT guaranteed to be up-to-date neither from relation nor from * evaluated data points of view. * - * NOTE: Can not be used if access to a fully evaluated datablock is needed. */ + * \note Can not be used if access to a fully evaluated data-block is needed. + */ struct Depsgraph *CTX_data_depsgraph_pointer(const bContext *C); -/* Get dependency graph which is expected to be fully evaluated. +/** + * Get dependency graph which is expected to be fully evaluated. * * In the release builds it is the same as CTX_data_depsgraph_pointer(). In the debug builds extra * sanity checks are done. Additionally, this provides more semantic meaning to what is exactly - * expected to happen. */ + * expected to happen. + */ struct Depsgraph *CTX_data_expect_evaluated_depsgraph(const bContext *C); -/* Gets fully updated and evaluated dependency graph. +/** + * Gets fully updated and evaluated dependency graph. * * All the relations and evaluated objects are guaranteed to be up to date. * - * NOTE: Will be expensive if there are relations or objects tagged for update. - * NOTE: If there are pending updates depsgraph hooks will be invoked. */ + * \note Will be expensive if there are relations or objects tagged for update. + * \note If there are pending updates depsgraph hooks will be invoked. + */ struct Depsgraph *CTX_data_ensure_evaluated_depsgraph(const bContext *C); /* Will Return NULL if depsgraph is not allocated yet. diff --git a/source/blender/blenkernel/BKE_crazyspace.h b/source/blender/blenkernel/BKE_crazyspace.h index b95be70379f..f5266ed7a10 100644 --- a/source/blender/blenkernel/BKE_crazyspace.h +++ b/source/blender/blenkernel/BKE_crazyspace.h @@ -33,6 +33,10 @@ struct Object; struct Scene; /* crazyspace.c */ + +/** + * Disable subdivision-surface temporal, get mapped coordinates, and enable it. + */ float (*BKE_crazyspace_get_mapped_editverts(struct Depsgraph *depsgraph, struct Object *obedit))[3]; void BKE_crazyspace_set_quats_editmesh(struct BMEditMesh *em, @@ -44,6 +48,10 @@ void BKE_crazyspace_set_quats_mesh(struct Mesh *me, float (*origcos)[3], float (*mappedcos)[3], float (*quats)[4]); +/** + * Returns an array of deform matrices for crazy-space correction, + * and the number of modifiers left. + */ int BKE_crazyspace_get_first_deform_matrices_editbmesh(struct Depsgraph *depsgraph, struct Scene *, struct Object *, diff --git a/source/blender/blenkernel/BKE_cryptomatte.h b/source/blender/blenkernel/BKE_cryptomatte.h index e98a9b2b1fd..329046ad494 100644 --- a/source/blender/blenkernel/BKE_cryptomatte.h +++ b/source/blender/blenkernel/BKE_cryptomatte.h @@ -55,6 +55,9 @@ uint32_t BKE_cryptomatte_asset_hash(struct CryptomatteSession *session, const char *layer_name, const struct Object *object); float BKE_cryptomatte_hash_to_float(uint32_t cryptomatte_hash); +/** + * Find an ID in the given main that matches the given encoded float. + */ bool BKE_cryptomatte_find_name(const struct CryptomatteSession *session, const float encoded_hash, char *r_name, diff --git a/source/blender/blenkernel/BKE_cryptomatte.hh b/source/blender/blenkernel/BKE_cryptomatte.hh index 9e205d01765..08536ecccbd 100644 --- a/source/blender/blenkernel/BKE_cryptomatte.hh +++ b/source/blender/blenkernel/BKE_cryptomatte.hh @@ -37,7 +37,8 @@ struct ID; namespace blender::bke::cryptomatte { -/* Format to a cryptomatte meta data key. +/** + * Format to a cryptomatte meta data key. * * Cryptomatte stores meta data. The keys are formatted containing a hash that * is generated from its layer name. @@ -48,7 +49,8 @@ namespace blender::bke::cryptomatte { std::string BKE_cryptomatte_meta_data_key(const StringRef layer_name, const StringRefNull key_name); -/* Extract the cryptomatte layer name from the given `render_pass_name`. +/** + * Extract the cryptomatte layer name from the given `render_pass_name`. * * Cryptomatte passes are formatted with a trailing number for storing multiple samples that belong * to the same cryptomatte layer. This function would remove the trailing numbers to determine the @@ -59,7 +61,7 @@ std::string BKE_cryptomatte_meta_data_key(const StringRef layer_name, * A render_pass_name could be 'View Layer.CryptoMaterial02'. The cryptomatte layer would be 'View * Layer.CryptoMaterial'. * - * NOTE: The return type is a sub-string of `render_pass_name` and therefore cannot outlive the + * \note The return type is a sub-string of `render_pass_name` and therefore cannot outlive the * `render_pass_name` internal data. */ StringRef BKE_cryptomatte_extract_layer_name(const StringRef render_pass_name); @@ -72,6 +74,18 @@ struct CryptomatteHash { static CryptomatteHash from_hex_encoded(blender::StringRef hex_encoded); std::string hex_encoded() const; + /** + Convert a cryptomatte hash to a float. + * + * Cryptomatte hashes are stored in float textures and images. The conversion is taken from the + * cryptomatte specification. See Floating point conversion section in + * https://github.com/Psyop/Cryptomatte/blob/master/specification/cryptomatte_specification.pdf. + * + * The conversion uses as many 32 bit floating point values as possible to minimize hash + * collisions. Unfortunately not all 32 bits can be used as NaN and Inf can be problematic. + * + * Note that this conversion assumes to be running on a L-endian system. + */ float float_encoded() const; }; diff --git a/source/blender/blenkernel/BKE_curve.h b/source/blender/blenkernel/BKE_curve.h index 2f7569b1f03..713ee8cac01 100644 --- a/source/blender/blenkernel/BKE_curve.h +++ b/source/blender/blenkernel/BKE_curve.h @@ -86,6 +86,9 @@ typedef struct CVKeyIndex { #define CU_DO_2DFILL(cu) (CU_IS_2D(cu) && (((cu)->flag & (CU_FRONT | CU_BACK)) != 0)) /* ** Curve ** */ +/** + * Frees edit-curve entirely. + */ void BKE_curve_editfont_free(struct Curve *cu); void BKE_curve_init(struct Curve *cu, const short curve_type); struct Curve *BKE_curve_add(struct Main *bmain, const char *name, int type); @@ -98,6 +101,8 @@ struct BoundBox *BKE_curve_boundbox_get(struct Object *ob); void BKE_curve_texspace_calc(struct Curve *cu); void BKE_curve_texspace_ensure(struct Curve *cu); +/* Basic vertex data functions. */ + bool BKE_curve_minmax(struct Curve *cu, bool use_radius, float min[3], float max[3]); bool BKE_curve_center_median(struct Curve *cu, float cent[3]); bool BKE_curve_center_bounds(struct Curve *cu, float cent[3]); @@ -119,14 +124,26 @@ void BKE_curve_material_remap(struct Curve *cu, const unsigned int *remap, unsig void BKE_curve_smooth_flag_set(struct Curve *cu, const bool use_smooth); +/** + * \return edit-nurbs or normal nurbs list. + */ ListBase *BKE_curve_nurbs_get(struct Curve *cu); const ListBase *BKE_curve_nurbs_get_for_read(const struct Curve *cu); int BKE_curve_nurb_vert_index_get(const struct Nurb *nu, const void *vert); void BKE_curve_nurb_active_set(struct Curve *cu, const struct Nurb *nu); struct Nurb *BKE_curve_nurb_active_get(struct Curve *cu); +/** + * Get active vert for curve. + */ void *BKE_curve_vert_active_get(struct Curve *cu); +/** + * Set active nurb and active vert for curve. + */ void BKE_curve_nurb_vert_active_set(struct Curve *cu, const struct Nurb *nu, const void *vert); +/** + * Get points to the active nurb and active vert for curve. + */ bool BKE_curve_nurb_vert_active_get(struct Curve *cu, struct Nurb **r_nu, void **r_vert); void BKE_curve_nurb_vert_active_validate(struct Curve *cu); @@ -152,6 +169,9 @@ void BKE_curve_nurbs_key_vert_tilts_apply(struct ListBase *lb, const float *key) void BKE_curve_editNurb_keyIndex_delCV(struct GHash *keyindex, const void *cv); void BKE_curve_editNurb_keyIndex_free(struct GHash **keyindex); void BKE_curve_editNurb_free(struct Curve *cu); +/** + * Get list of nurbs from edit-nurbs structure. + */ struct ListBase *BKE_curve_editNurbs_get(struct Curve *cu); const struct ListBase *BKE_curve_editNurbs_get_for_read(const struct Curve *cu); @@ -159,8 +179,14 @@ void BKE_curve_bevelList_free(struct ListBase *bev); void BKE_curve_bevelList_make(struct Object *ob, const struct ListBase *nurbs, bool for_render); ListBase BKE_curve_bevel_make(const struct Curve *curve); +/** + * Forward differencing method for bezier curve. + */ void BKE_curve_forward_diff_bezier( float q0, float q1, float q2, float q3, float *p, int it, int stride); +/** + * Forward differencing method for first derivative of cubic bezier curve. + */ void BKE_curve_forward_diff_tangent_bezier( float q0, float q1, float q2, float q3, float *p, int it, int stride); @@ -168,6 +194,10 @@ void BKE_curve_rect_from_textbox(const struct Curve *cu, const struct TextBox *tb, struct rctf *r_rect); +/** + * This function is almost the same as #BKE_fcurve_correct_bezpart, + * but doesn't allow as large a tangent. + */ void BKE_curve_correct_bezpart(const float v1[2], float v2[2], float v3[2], const float v4[2]); /* ** Nurbs ** */ @@ -179,6 +209,15 @@ int BKE_nurbList_verts_count_without_handles(const struct ListBase *nurb); void BKE_nurbList_free(struct ListBase *lb); void BKE_nurbList_duplicate(struct ListBase *lb1, const struct ListBase *lb2); +/** + * \param code: + * - 1 (#HD_AUTO): set auto-handle. + * - 2 (#HD_VECT): set vector-handle. + * - 3 (#HD_ALIGN) it toggle, vector-handles become #HD_FREE. + * + * - 5: Set align, like 3 but no toggle. + * - 6: Clear align (setting #HD_FREE), like 3 but no toggle. + */ void BKE_nurbList_handles_set(struct ListBase *editnurb, const char code); void BKE_nurbList_handles_recalculate(struct ListBase *editnurb, const bool calc_length, @@ -186,18 +225,36 @@ void BKE_nurbList_handles_recalculate(struct ListBase *editnurb, void BKE_nurbList_handles_autocalc(ListBase *editnurb, uint8_t flag); void BKE_nurbList_flag_set(ListBase *editnurb, uint8_t flag, bool set); +/** + * Set \a flag for every point that already has \a from_flag set. + */ bool BKE_nurbList_flag_set_from_flag(ListBase *editnurb, uint8_t from_flag, uint8_t flag); void BKE_nurb_free(struct Nurb *nu); struct Nurb *BKE_nurb_duplicate(const struct Nurb *nu); +/** + * Copy the nurb but allow for different number of points (to be copied after this). + */ struct Nurb *BKE_nurb_copy(struct Nurb *src, int pntsu, int pntsv); void BKE_nurb_project_2d(struct Nurb *nu); +/** + * if use_radius is truth, minmax will take points' radius into account, + * which will make bound-box closer to beveled curve. + */ void BKE_nurb_minmax(const struct Nurb *nu, bool use_radius, float min[3], float max[3]); float BKE_nurb_calc_length(const struct Nurb *nu, int resolution); +/** + * \param coord_array: has to be `(3 * 4 * resolu * resolv)` in size, and zero-ed. + */ void BKE_nurb_makeFaces( const struct Nurb *nu, float *coord_array, int rowstride, int resolu, int resolv); +/** + * \param coord_array: Has to be `(3 * 4 * pntsu * resolu)` in size and zero-ed + * \param tilt_array: set when non-NULL + * \param radius_array: set when non-NULL + */ void BKE_nurb_makeCurve(const struct Nurb *nu, float *coord_array, float *tilt_array, @@ -206,10 +263,19 @@ void BKE_nurb_makeCurve(const struct Nurb *nu, int resolu, int stride); +/** + * Calculate the length for arrays filled in by #BKE_curve_calc_coords_axis. + */ unsigned int BKE_curve_calc_coords_axis_len(const unsigned int bezt_array_len, const unsigned int resolu, const bool is_cyclic, const bool use_cyclic_duplicate_endpoint); +/** + * Calculate an array for the entire curve (cyclic or non-cyclic). + * \note Call for each axis. + * + * \param use_cyclic_duplicate_endpoint: Duplicate values at the beginning & end of the array. + */ void BKE_curve_calc_coords_axis(const struct BezTriple *bezt_array, const unsigned int bezt_array_len, const unsigned int resolu, @@ -232,11 +298,17 @@ bool BKE_nurb_order_clamp_u(struct Nurb *nu); bool BKE_nurb_order_clamp_v(struct Nurb *nu); void BKE_nurb_direction_switch(struct Nurb *nu); +/** + * \note caller must ensure active vertex remains valid. + */ bool BKE_nurb_type_convert(struct Nurb *nu, const short type, const bool use_handles, const char **r_err_msg); +/** + * Be sure to call #BKE_nurb_knot_calc_u / #BKE_nurb_knot_calc_v after this. + */ void BKE_nurb_points_add(struct Nurb *nu, int number); void BKE_nurb_bezierPoints_add(struct Nurb *nu, int number); @@ -254,17 +326,31 @@ void BKE_nurb_bezt_calc_plane(struct Nurb *nu, struct BezTriple *bezt, float r_p void BKE_nurb_bpoint_calc_normal(struct Nurb *nu, struct BPoint *bp, float r_normal[3]); void BKE_nurb_bpoint_calc_plane(struct Nurb *nu, struct BPoint *bp, float r_plane[3]); +/** + * Recalculate the handles of a nurb bezier-triple. Acts based on handle selection with `SELECT` + * flag. To use a different flag, use #BKE_nurb_handle_calc_ex(). + */ void BKE_nurb_handle_calc(struct BezTriple *bezt, struct BezTriple *prev, struct BezTriple *next, const bool is_fcurve, const char smoothing); +/** + * Variant of #BKE_nurb_handle_calc() that allows calculating based on a different select flag. + * + * \param handle_sel_flag: The flag (bezt.f1/2/3) value to use to determine selection. + * Usually #SELECT, but may want to use a different one at times + * (if caller does not operate on selection). + */ void BKE_nurb_handle_calc_ex(struct BezTriple *bezt, struct BezTriple *prev, struct BezTriple *next, const eBezTriple_Flag__Alias handle_sel_flag, const bool is_fcurve, const char smoothing); +/** + * Similar to #BKE_nurb_handle_calc but for curves and figures out the previous and next for us. + */ void BKE_nurb_handle_calc_simple(struct Nurb *nu, struct BezTriple *bezt); void BKE_nurb_handle_calc_simple_auto(struct Nurb *nu, struct BezTriple *bezt); @@ -272,6 +358,18 @@ void BKE_nurb_handle_smooth_fcurve(struct BezTriple *bezt, int total, bool cycli void BKE_nurb_handles_calc(struct Nurb *nu); void BKE_nurb_handles_autocalc(struct Nurb *nu, uint8_t flag); +/** + * Update selected handle types to ensure valid state, e.g. deduce "Auto" types to concrete ones. + * Thereby \a sel_flag defines what qualifies as selected. + * Use when something has changed handle positions. + * + * The caller needs to recalculate handles. + * + * \param sel_flag: The flag (bezt.f1/2/3) value to use to determine selection. Usually `SELECT`, + * but may want to use a different one at times (if caller does not operate on * selection). + * \param use_handle: Check selection state of individual handles, otherwise always update both + * handles if the key is selected. + */ void BKE_nurb_bezt_handle_test(struct BezTriple *bezt, const eBezTriple_Flag__Alias sel_flag, const bool use_handle, @@ -337,6 +435,12 @@ void BKE_curve_deform_coords_with_editmesh(const struct Object *ob_curve, const short defaxis, struct BMEditMesh *em_target); +/** + * \param orco: Input vec and orco = local coord in curve space + * orco is original not-animated or deformed reference point. + * + * The result written to `vec` and `r_mat`. + */ void BKE_curve_deform_co(const struct Object *ob_curve, const struct Object *ob_target, const float orco[3], diff --git a/source/blender/blenkernel/BKE_curve_to_mesh.hh b/source/blender/blenkernel/BKE_curve_to_mesh.hh index fb077425336..cf5c8b87ede 100644 --- a/source/blender/blenkernel/BKE_curve_to_mesh.hh +++ b/source/blender/blenkernel/BKE_curve_to_mesh.hh @@ -25,7 +25,21 @@ struct CurveEval; namespace blender::bke { +/** + * Extrude all splines in the profile curve along the path of every spline in the curve input. + * Transfer curve attributes to the mesh. + * + * \note Normal calculation is by far the slowest part of calculations relating to the result mesh. + * Although it would be a sensible decision to use the better topology information available while + * generating the mesh to also generate the normals, that work may wasted if the output mesh is + * changed anyway in a way that affects the normals. So currently this code uses the safer / + * simpler solution of deferring normal calculation to the rest of Blender. + */ Mesh *curve_to_mesh_sweep(const CurveEval &curve, const CurveEval &profile, bool fill_caps); +/** + * Create a loose-edge mesh based on the evaluated path of the curve's splines. + * Transfer curve attributes to the mesh. + */ Mesh *curve_to_wire_mesh(const CurveEval &curve); } // namespace blender::bke diff --git a/source/blender/blenkernel/BKE_curveprofile.h b/source/blender/blenkernel/BKE_curveprofile.h index 5a948f0d844..ee8bf99a216 100644 --- a/source/blender/blenkernel/BKE_curveprofile.h +++ b/source/blender/blenkernel/BKE_curveprofile.h @@ -34,8 +34,15 @@ struct BlendWriter; struct CurveProfile; struct CurveProfilePoint; +/** + * Sets the default settings and clip range for the profile widget. + * Does not generate either table. + */ void BKE_curveprofile_set_defaults(struct CurveProfile *profile); +/** + * Returns a pointer to a newly allocated curve profile, using the given preset. + */ struct CurveProfile *BKE_curveprofile_add(eCurveProfilePresets preset); void BKE_curveprofile_free_data(struct CurveProfile *profile); @@ -46,32 +53,90 @@ void BKE_curveprofile_copy_data(struct CurveProfile *target, const struct CurveP struct CurveProfile *BKE_curveprofile_copy(const struct CurveProfile *profile); +/** + * Move a point's handle, accounting for the alignment of handles with the #HD_ALIGN type. + * + * \param handle_1: Whether to move the 1st or 2nd control point. + * \param delta: The *relative* change in the handle's position. + * \note Requires #BKE_curveprofile_update call after. + * \return Whether the handle moved from its start position. + */ bool BKE_curveprofile_move_handle(struct CurveProfilePoint *point, const bool handle_1, const bool snap, const float delta[2]); +/** + * Moves a control point, accounting for clipping and snapping, and moving free handles. + * + * \param snap: Whether to snap the point to the grid + * \param delta: The *relative* change of the point's location. + * \return Whether the point moved from its start position. + * \note Requires #BKE_curveprofile_update call after. + */ bool BKE_curveprofile_move_point(struct CurveProfile *profile, struct CurveProfilePoint *point, const bool snap, const float delta[2]); +/** + * Removes a specific point from the path of control points. + * \note Requires #BKE_curveprofile_update call after. + */ bool BKE_curveprofile_remove_point(struct CurveProfile *profile, struct CurveProfilePoint *point); +/** + * Removes every point in the widget with the supplied flag set, except for the first and last. + * + * \param flag: #CurveProfilePoint.flag. + * + * \note Requires #BKE_curveprofile_update call after. + */ void BKE_curveprofile_remove_by_flag(struct CurveProfile *profile, const short flag); +/** + * Adds a new point at the specified location. The choice for which points to place the new vertex + * between is made by checking which control point line segment is closest to the new point and + * placing the new vertex in between that segment's points. + * + * \note Requires #BKE_curveprofile_update call after. + */ struct CurveProfilePoint *BKE_curveprofile_insert(struct CurveProfile *profile, float x, float y); +/** + * Sets the handle type of the selected control points. + * \param type_1, type_2: Handle type for the first handle. HD_VECT, HD_AUTO, HD_FREE, or HD_ALIGN. + * \note Requires #BKE_curveprofile_update call after. + */ void BKE_curveprofile_selected_handle_set(struct CurveProfile *profile, int type_1, int type_2); +/** + * Flips the profile across the diagonal so that its orientation is reversed. + * + * \note Requires #BKE_curveprofile_update call after. + */ void BKE_curveprofile_reverse(struct CurveProfile *profile); +/** + * Reset the view to the clipping rectangle. + */ void BKE_curveprofile_reset_view(struct CurveProfile *profile); +/** + * Resets the profile to the current preset. + * + * \note Requires #BKE_curveprofile_update call after. + */ void BKE_curveprofile_reset(struct CurveProfile *profile); int BKE_curveprofile_table_size(const struct CurveProfile *profile); +/** + * Refreshes the higher resolution table sampled from the input points. A call to this or + * #BKE_curveprofile_update is needed before evaluation functions that use the table. + * Also sets the number of segments used for the display preview of the locations + * of the sampled points. + */ void BKE_curveprofile_init(struct CurveProfile *profile, short segments_len); /* Called for a complete update of the widget after modifications */ @@ -80,15 +145,31 @@ enum { PROF_UPDATE_REMOVE_DOUBLES = (1 << 0), PROF_UPDATE_CLIP = (1 << 1), }; +/** + * Should be called after the widget is changed. Does profile and remove double checks and more + * importantly, recreates the display / evaluation and segments tables. + * \param update_flags: Bit-field with fields defined in header file. + * Controls removing doubles and clipping. + */ void BKE_curveprofile_update(struct CurveProfile *profile, const int update_flags); -/* Length portion is the fraction of the total path length where we want the location */ +/** + * Does a single evaluation along the profile's path. + * Travels down (length_portion * path) length and returns the position at that point. + * Where length portion is the fraction of the total path length where we want the location. + * + * \param length_portion: The portion (0 to 1) of the path's full length to sample at. + * \note Requires #BKE_curveprofile_init or #BKE_curveprofile_update call before to fill table. + */ void BKE_curveprofile_evaluate_length_portion(const struct CurveProfile *profile, float length_portion, float *x_out, float *y_out); void BKE_curveprofile_blend_write(struct BlendWriter *writer, const struct CurveProfile *profile); +/** + * Expects that the curve profile itself has been read already. + */ void BKE_curveprofile_blend_read(struct BlendDataReader *reader, struct CurveProfile *profile); #ifdef __cplusplus diff --git a/source/blender/blenkernel/BKE_customdata.h b/source/blender/blenkernel/BKE_customdata.h index 0732f1e5190..68d29235469 100644 --- a/source/blender/blenkernel/BKE_customdata.h +++ b/source/blender/blenkernel/BKE_customdata.h @@ -86,8 +86,14 @@ typedef void (*cd_interp)( typedef void (*cd_copy)(const void *source, void *dest, int count); typedef bool (*cd_validate)(void *item, const uint totitems, const bool do_fixes); +/** + * Update mask_dst with layers defined in mask_src (equivalent to a bit-wise OR). + */ void CustomData_MeshMasks_update(CustomData_MeshMasks *mask_dst, const CustomData_MeshMasks *mask_src); +/** + * Return True if all layers set in \a mask_required are also set in \a mask_ref + */ bool CustomData_MeshMasks_are_matching(const CustomData_MeshMasks *mask_ref, const CustomData_MeshMasks *mask_required); @@ -99,39 +105,50 @@ bool CustomData_layer_has_math(const struct CustomData *data, int layer_n); bool CustomData_layer_has_interp(const struct CustomData *data, int layer_n); /** - * Checks if any of the customdata layers has math. + * Checks if any of the custom-data layers has math. */ bool CustomData_has_math(const struct CustomData *data); bool CustomData_has_interp(const struct CustomData *data); +/** + * A non bmesh version would have to check `layer->data`. + */ bool CustomData_bmesh_has_free(const struct CustomData *data); /** - * Checks if any of the customdata layers is referenced. + * Checks if any of the custom-data layers is referenced. */ bool CustomData_has_referenced(const struct CustomData *data); -/* Copies the "value" (e.g. mloopuv uv or mloopcol colors) from one block to +/** + * Copies the "value" (e.g. mloopuv uv or mloopcol colors) from one block to * another, while not overwriting anything else (e.g. flags). probably only - * implemented for mloopuv/mloopcol, for now. */ + * implemented for mloopuv/mloopcol, for now. + */ void CustomData_data_copy_value(int type, const void *source, void *dest); -/* Same as above, but doing advanced mixing. - * Only available for a few types of data (like colors...). */ +/** + * Mixes the "value" (e.g. mloopuv uv or mloopcol colors) from one block into + * another, while not overwriting anything else (e.g. flags). + */ void CustomData_data_mix_value( int type, const void *source, void *dest, const int mixmode, const float mixfactor); -/* compares if data1 is equal to data2. type is a valid CustomData type - * enum (e.g. CD_MLOOPUV). the layer type's equal function is used to compare - * the data, if it exists, otherwise memcmp is used. */ +/** + * Compares if data1 is equal to data2. type is a valid CustomData type + * enum (e.g. #CD_MLOOPUV). the layer type's equal function is used to compare + * the data, if it exists, otherwise #memcmp is used. + */ bool CustomData_data_equals(int type, const void *data1, const void *data2); void CustomData_data_initminmax(int type, void *min, void *max); void CustomData_data_dominmax(int type, const void *data, void *min, void *max); void CustomData_data_multiply(int type, void *data, float fac); void CustomData_data_add(int type, void *data1, const void *data2); -/* initializes a CustomData object with the same layer setup as source. - * mask is a bitfield where (mask & (1 << (layer type))) indicates - * if a layer should be copied or not. alloctype must be one of the above. */ +/** + * Initializes a CustomData object with the same layer setup as source. + * mask is a bitfield where `(mask & (1 << (layer type)))` indicates + * if a layer should be copied or not. alloctype must be one of the above. + */ void CustomData_copy(const struct CustomData *source, struct CustomData *dest, CustomDataMask mask, @@ -141,25 +158,30 @@ void CustomData_copy(const struct CustomData *source, /* BMESH_TODO, not really a public function but readfile.c needs it */ void CustomData_update_typemap(struct CustomData *data); -/* same as the above, except that this will preserve existing layers, and only - * add the layers that were not there yet */ +/** + * Same as the above, except that this will preserve existing layers, and only + * add the layers that were not there yet. + */ bool CustomData_merge(const struct CustomData *source, struct CustomData *dest, CustomDataMask mask, eCDAllocType alloctype, int totelem); -/* Reallocate custom data to a new element count. +/** + * Reallocate custom data to a new element count. * Only affects on data layers which are owned by the CustomData itself, * referenced data is kept unchanged, * - * NOTE: Take care of referenced layers by yourself! + * \note Take care of referenced layers by yourself! */ void CustomData_realloc(struct CustomData *data, int totelem); -/* bmesh version of CustomData_merge; merges the layouts of source and dest, - * then goes through the mesh and makes sure all the customdata blocks are - * consistent with the new layout. */ +/** + * BMesh version of CustomData_merge; merges the layouts of source and `dest`, + * then goes through the mesh and makes sure all the custom-data blocks are + * consistent with the new layout. + */ bool CustomData_bmesh_merge(const struct CustomData *source, struct CustomData *dest, CustomDataMask mask, @@ -167,7 +189,9 @@ bool CustomData_bmesh_merge(const struct CustomData *source, struct BMesh *bm, const char htype); -/** NULL's all members and resets the typemap. */ +/** + * NULL's all members and resets the #CustomData.typemap. + */ void CustomData_reset(struct CustomData *data); /** @@ -175,19 +199,26 @@ void CustomData_reset(struct CustomData *data); */ void CustomData_free(struct CustomData *data, int totelem); -/* same as above, but only frees layers which matches the given mask. */ +/** + * Same as above, but only frees layers which matches the given mask. + */ void CustomData_free_typemask(struct CustomData *data, int totelem, CustomDataMask mask); -/* frees all layers with CD_FLAG_TEMPORARY */ +/** + * Frees all layers with #CD_FLAG_TEMPORARY. + */ void CustomData_free_temporary(struct CustomData *data, int totelem); -/* adds a data layer of the given type to the CustomData object, optionally +/** + * Adds a data layer of the given type to the #CustomData object, optionally * backed by an external data array. the different allocation types are * defined above. returns the data of the layer. */ void *CustomData_add_layer( struct CustomData *data, int type, eCDAllocType alloctype, void *layer, int totelem); -/* Same as above but accepts a name. */ +/** + * Same as above but accepts a name. + */ void *CustomData_add_layer_named(struct CustomData *data, int type, eCDAllocType alloctype, @@ -201,32 +232,42 @@ void *CustomData_add_layer_anonymous(struct CustomData *data, int totelem, const struct AnonymousAttributeID *anonymous_id); -/* frees the active or first data layer with the give type. +/** + * Frees the active or first data layer with the give type. * returns 1 on success, 0 if no layer with the given type is found * - * in editmode, use EDBM_data_layer_free instead of this function + * In edit-mode, use #EDBM_data_layer_free instead of this function. */ bool CustomData_free_layer(struct CustomData *data, int type, int totelem, int index); -/* frees the layer index with the give type. - * returns 1 on success, 0 if no layer with the given type is found +/** + * Frees the layer index with the give type. + * returns 1 on success, 0 if no layer with the given type is found. * - * in editmode, use EDBM_data_layer_free instead of this function + * In edit-mode, use #EDBM_data_layer_free instead of this function. */ bool CustomData_free_layer_active(struct CustomData *data, int type, int totelem); -/* same as above, but free all layers with type */ +/** + * Same as above, but free all layers with type. + */ void CustomData_free_layers(struct CustomData *data, int type, int totelem); -/* returns 1 if a layer with the specified type exists */ +/** + * Returns true if a layer with the specified type exists. + */ bool CustomData_has_layer(const struct CustomData *data, int type); -/* returns the number of layers with this type */ +/** + * Returns the number of layers with this type. + */ int CustomData_number_of_layers(const struct CustomData *data, int type); int CustomData_number_of_layers_typemask(const struct CustomData *data, CustomDataMask mask); -/* duplicate data of a layer with flag NOFREE, and remove that flag. - * returns the layer data */ +/** + * Duplicate data of a layer with flag NOFREE, and remove that flag. + * \return the layer data. + */ void *CustomData_duplicate_referenced_layer(struct CustomData *data, const int type, const int totelem); @@ -245,19 +286,21 @@ void *CustomData_duplicate_referenced_layer_anonymous( const int totelem); bool CustomData_is_referenced_layer(struct CustomData *data, int type); -/* Duplicate all the layers with flag NOFREE, and remove the flag from duplicated layers. */ +/** + * Duplicate all the layers with flag NOFREE, and remove the flag from duplicated layers. + */ void CustomData_duplicate_referenced_layers(CustomData *data, int totelem); -/* set the CD_FLAG_NOCOPY flag in custom data layers where the mask is - * zero for the layer type, so only layer types specified by the mask - * will be copied +/** + * Set the #CD_FLAG_NOCOPY flag in custom data layers where the mask is + * zero for the layer type, so only layer types specified by the mask will be copied */ void CustomData_set_only_copy(const struct CustomData *data, CustomDataMask mask); -/* copies data from one CustomData object to another +/** + * Copies data from one CustomData object to another * objects need not be compatible, each source layer is copied to the - * first dest layer of correct type (if there is none, the layer is skipped) - * return 1 on success, 0 on failure + * first dest layer of correct type (if there is none, the layer is skipped). */ void CustomData_copy_data(const struct CustomData *source, struct CustomData *dest, @@ -287,7 +330,9 @@ void CustomData_bmesh_copy_data_exclude_by_type(const struct CustomData *source, void **dest_block, const CustomDataMask mask_exclude); -/* Copies data of a single layer of a given type. */ +/** + * Copies data of a single layer of a given type. + */ void CustomData_copy_layer_type_data(const struct CustomData *source, struct CustomData *destination, int type, @@ -295,22 +340,22 @@ void CustomData_copy_layer_type_data(const struct CustomData *source, int destination_index, int count); -/* frees data in a CustomData object - * return 1 on success, 0 on failure +/** + * Frees data in a #CustomData object. */ void CustomData_free_elem(struct CustomData *data, int index, int count); -/* interpolates data from one CustomData object to another - * objects need not be compatible, each source layer is interpolated to the - * first dest layer of correct type (if there is none, the layer is skipped) - * if weights == NULL or sub_weights == NULL, they default to all 1's +/** + * Interpolate given custom data source items into a single destination one. * - * src_indices gives the source elements to interpolate from - * weights gives the weight for each source element - * sub_weights is an array of matrices of weights for sub-elements (matrices - * should be source->subElems * source->subElems in size) - * count gives the number of source elements to interpolate from - * dest_index gives the dest element to write the interpolated value to + * \param src_indices: Indices of every source items to interpolate into the destination one. + * \param weights: The weight to apply to each source value individually. If NULL, they will be + * averaged. + * \param sub_weights: The weights of sub-items, only used to affect each corners of a + * tessellated face data (should always be and array of four values). + * \param count: The number of source items to interpolate. + * \param dest_index: Index of the destination item, in which to put the result of the + * interpolation. */ void CustomData_interp(const struct CustomData *source, struct CustomData *dest, @@ -319,6 +364,10 @@ void CustomData_interp(const struct CustomData *source, const float *sub_weights, int count, int dest_index); +/** + * \note src_blocks_ofs & dst_block_ofs + * must be pointers to the data, offset by layer->offset already. + */ void CustomData_bmesh_interp_n(struct CustomData *data, const void **src_blocks, const float *weights, @@ -333,30 +382,45 @@ void CustomData_bmesh_interp(struct CustomData *data, int count, void *dst_block); -/* swaps the data in the element corners, to new corners with indices as - * specified in corner_indices. for edges this is an array of length 2, for - * faces an array of length 4 */ +/** + * Swap data inside each item, for all layers. + * This only applies to item types that may store several sub-item data + * (e.g. corner data [UVs, VCol, ...] of tessellated faces). + * + * \param corner_indices: A mapping 'new_index -> old_index' of sub-item data. + */ void CustomData_swap_corners(struct CustomData *data, int index, const int *corner_indices); +/** + * Swap two items of given custom data, in all available layers. + */ void CustomData_swap(struct CustomData *data, const int index_a, const int index_b); -/* gets a pointer to the data element at index from the first layer of type - * returns NULL if there is no layer of type +/** + * Gets a pointer to the data element at index from the first layer of type. + * \return NULL if there is no layer of type. */ void *CustomData_get(const struct CustomData *data, int index, int type); void *CustomData_get_n(const struct CustomData *data, int type, int index, int n); + +/* BMesh Custom Data Functions. + * Should replace edit-mesh ones with these as well, due to more efficient memory alloc. */ + void *CustomData_bmesh_get(const struct CustomData *data, void *block, int type); void *CustomData_bmesh_get_n(const struct CustomData *data, void *block, int type, int n); -/* gets the layer at physical index n, with no type checking. +/** + * Gets from the layer at physical index `n`, + * \note doesn't check type. */ void *CustomData_bmesh_get_layer_n(const struct CustomData *data, void *block, int n); bool CustomData_set_layer_name(const struct CustomData *data, int type, int n, const char *name); const char *CustomData_get_layer_name(const struct CustomData *data, int type, int n); -/* gets a pointer to the active or first layer of type - * returns NULL if there is no layer of type +/** + * Gets a pointer to the active or first layer of type. + * \return NULL if there is no layer of type. */ void *CustomData_get_layer(const struct CustomData *data, int type); void *CustomData_get_layer_n(const struct CustomData *data, int type, int n); @@ -377,9 +441,9 @@ int CustomData_get_render_layer(const struct CustomData *data, int type); int CustomData_get_clone_layer(const struct CustomData *data, int type); int CustomData_get_stencil_layer(const struct CustomData *data, int type); -/* copies the data from source to the data element at index in the first - * layer of type - * no effect if there is no layer of type +/** + * Copies the data from source to the data element at index in the first layer of type + * no effect if there is no layer of type. */ void CustomData_set(const struct CustomData *data, int index, int type, const void *source); @@ -390,42 +454,63 @@ void CustomData_bmesh_set(const struct CustomData *data, void CustomData_bmesh_set_n( struct CustomData *data, void *block, int type, int n, const void *source); -/* sets the data of the block at physical layer n. no real type checking - * is performed. +/** + * Sets the data of the block at physical layer n. + * no real type checking is performed. */ void CustomData_bmesh_set_layer_n(struct CustomData *data, void *block, int n, const void *source); -/* set the pointer of to the first layer of type. the old data is not freed. - * returns the value of ptr if the layer is found, NULL otherwise +/** + * Set the pointer of to the first layer of type. the old data is not freed. + * returns the value of `ptr` if the layer is found, NULL otherwise. */ void *CustomData_set_layer(const struct CustomData *data, int type, void *ptr); void *CustomData_set_layer_n(const struct CustomData *data, int type, int n, void *ptr); -/* sets the nth layer of type as active */ +/** + * Sets the nth layer of type as active. + */ void CustomData_set_layer_active(struct CustomData *data, int type, int n); void CustomData_set_layer_render(struct CustomData *data, int type, int n); void CustomData_set_layer_clone(struct CustomData *data, int type, int n); void CustomData_set_layer_stencil(struct CustomData *data, int type, int n); -/* same as above but works with an index from CustomData_get_layer_index */ +/** + * For using with an index from #CustomData_get_active_layer_index and + * #CustomData_get_render_layer_index. + */ void CustomData_set_layer_active_index(struct CustomData *data, int type, int n); void CustomData_set_layer_render_index(struct CustomData *data, int type, int n); void CustomData_set_layer_clone_index(struct CustomData *data, int type, int n); void CustomData_set_layer_stencil_index(struct CustomData *data, int type, int n); -/* adds flag to the layer flags */ +/** + * Adds flag to the layer flags. + */ void CustomData_set_layer_flag(struct CustomData *data, int type, int flag); void CustomData_clear_layer_flag(struct CustomData *data, int type, int flag); void CustomData_bmesh_set_default(struct CustomData *data, void **block); void CustomData_bmesh_free_block(struct CustomData *data, void **block); +/** + * Same as #CustomData_bmesh_free_block but zero the memory rather than freeing. + */ void CustomData_bmesh_free_block_data(struct CustomData *data, void *block); +/** + * A selective version of #CustomData_bmesh_free_block_data. + */ void CustomData_bmesh_free_block_data_exclude_by_type(struct CustomData *data, void *block, const CustomDataMask mask_exclude); -/* copy custom data to/from layers as in mesh/derivedmesh, to editmesh - * blocks of data. the CustomData's must not be compatible */ +/** + * Copy custom data to/from layers as in mesh/derived-mesh, to edit-mesh + * blocks of data. the CustomData's must not be compatible. + * + * \param use_default_init: initializes data which can't be copied, + * typically you'll want to use this if the BM_xxx create function + * is called with BM_CREATE_SKIP_CD flag + */ void CustomData_to_bmesh_block(const struct CustomData *source, struct CustomData *dest, int src_index, @@ -436,17 +521,34 @@ void CustomData_from_bmesh_block(const struct CustomData *source, void *src_block, int dest_index); -/* query info over types */ +/** + * Query info over types. + */ void CustomData_file_write_info(int type, const char **r_struct_name, int *r_struct_num); int CustomData_sizeof(int type); -/* get the name of a layer type */ +/** + * Get the name of a layer type. + */ const char *CustomData_layertype_name(int type); +/** + * Can only ever be one of these. + */ bool CustomData_layertype_is_singleton(int type); +/** + * Has dynamically allocated members. + * This is useful to know if operations such as #memcmp are + * valid when comparing data from two layers. + */ bool CustomData_layertype_is_dynamic(int type); +/** + * \return Maximum number of layers of given \a type, -1 means 'no limit'. + */ int CustomData_layertype_layers_max(const int type); -/* make sure the name of layer at index is unique */ +/** + * Make sure the name of layer at index is unique. + */ void CustomData_set_layer_unique_name(struct CustomData *data, int index); void CustomData_validate_layer_name(const struct CustomData *data, @@ -454,23 +556,45 @@ void CustomData_validate_layer_name(const struct CustomData *data, const char *name, char *outname); -/* for file reading compatibility, returns false if the layer was freed, - * only after this test passes, layer->data should be assigned */ +/** + * For file reading compatibility, returns false if the layer was freed, + * only after this test passes, `layer->data` should be assigned. + */ bool CustomData_verify_versions(struct CustomData *data, int index); -/* BMesh specific custom-data stuff. */ +/* BMesh specific custom-data stuff. + * + * Needed to convert to/from different face representation (for versioning). */ + void CustomData_to_bmeshpoly(struct CustomData *fdata, struct CustomData *ldata, int totloop); void CustomData_from_bmeshpoly(struct CustomData *fdata, struct CustomData *ldata, int total); void CustomData_bmesh_update_active_layers(struct CustomData *fdata, struct CustomData *ldata); +/** + * Update active indices for active/render/clone/stencil custom data layers + * based on indices from fdata layers + * used by do_versions in `readfile.c` when creating pdata and ldata for pre-bmesh + * meshes and needed to preserve active/render/clone/stencil flags set in pre-bmesh files. + */ void CustomData_bmesh_do_versions_update_active_layers(struct CustomData *fdata, struct CustomData *ldata); void CustomData_bmesh_init_pool(struct CustomData *data, int totelem, const char htype); #ifndef NDEBUG +/** + * Debug check, used to assert when we expect layers to be in/out of sync. + * + * \param fallback: Use when there are no layers to handle, + * since callers may expect success or failure. + */ bool CustomData_from_bmeshpoly_test(CustomData *fdata, CustomData *ldata, bool fallback); #endif -/* Layer data validation. */ +/** + * Validate and fix data of \a layer, + * if possible (needs relevant callback in layer's type to be defined). + * + * \return True if some errors were found. + */ bool CustomData_layer_validate(struct CustomDataLayer *layer, const uint totitems, const bool do_fixes); @@ -587,16 +711,41 @@ typedef struct CustomDataTransferLayerMap { cd_datatransfer_interp interp; } CustomDataTransferLayerMap; -/* Those functions assume src_n and dst_n layers of given type exist in resp. src and dst. */ +/** + * Those functions assume src_n and dst_n layers of given type exist in resp. src and dst. + */ void CustomData_data_transfer(const struct MeshPairRemap *me_remap, const CustomDataTransferLayerMap *laymap); /* .blend file I/O */ + +/** + * Prepare given custom data for file writing. + * + * \param data: the custom-data to tweak for .blend file writing (modified in place). + * \param r_write_layers: contains a reduced set of layers to be written to file, + * use it with #writestruct_at_address() + * (caller must free it if != \a write_layers_buff). + * + * \param write_layers_buff: An optional buffer for r_write_layers (to avoid allocating it). + * \param write_layers_size: The size of pre-allocated \a write_layer_buff. + * + * \warning After this funcion has ran, given custom data is no more valid from Blender POV + * (its `totlayer` is invalid). This function shall always be called with localized data + * (as it is in write_meshes()). + * + * \note `data->typemap` is not updated here, since it is always rebuilt on file read anyway. + * This means written `typemap` does not match written layers (as returned by \a r_write_layers). + * Trivial to fix is ever needed. + */ void CustomData_blend_write_prepare(struct CustomData *data, struct CustomDataLayer **r_write_layers, struct CustomDataLayer *write_layers_buff, size_t write_layers_size); +/** + * \param layers: The layers argument assigned by #CustomData_blend_write_prepare. + */ void CustomData_blend_write(struct BlendWriter *writer, struct CustomData *data, CustomDataLayer *layers, diff --git a/source/blender/blenkernel/BKE_data_transfer.h b/source/blender/blenkernel/BKE_data_transfer.h index a2544e43c3d..a4218ec564b 100644 --- a/source/blender/blenkernel/BKE_data_transfer.h +++ b/source/blender/blenkernel/BKE_data_transfer.h @@ -65,6 +65,10 @@ enum { void BKE_object_data_transfer_dttypes_to_cdmask(const int dtdata_types, struct CustomData_MeshMasks *r_data_masks); +/** + * Check what can do each layer type + * (if it is actually handled by transfer-data, if it supports advanced mixing. + */ bool BKE_object_data_transfer_get_dttypes_capacity(const int dtdata_types, bool *r_advanced_mixing, bool *r_threshold); @@ -122,6 +126,12 @@ enum { #endif }; +/** + * Transfer data *layout* of selected types from source to destination object. + * By default, it only creates new data layers if needed on \a ob_dst. + * If \a use_delete is true, it will also delete data layers on \a ob_dst that do not match those + * from \a ob_src, to get (as much as possible) exact copy of source data layout. + */ void BKE_object_data_transfer_layout(struct Depsgraph *depsgraph, struct Scene *scene, struct Object *ob_src, diff --git a/source/blender/blenkernel/BKE_deform.h b/source/blender/blenkernel/BKE_deform.h index cca99f9d1cd..9870d43b5c2 100644 --- a/source/blender/blenkernel/BKE_deform.h +++ b/source/blender/blenkernel/BKE_deform.h @@ -44,7 +44,13 @@ const struct ListBase *BKE_object_defgroup_list(const struct Object *ob); struct ListBase *BKE_object_defgroup_list_mutable(struct Object *ob); int BKE_object_defgroup_count(const struct Object *ob); +/** + * \note For historical reasons, the index starts at 1 rather than 0. + */ int BKE_object_defgroup_active_index_get(const struct Object *ob); +/** + * \note For historical reasons, the index starts at 1 rather than 0. + */ void BKE_object_defgroup_active_index_set(struct Object *ob, const int new_index); const struct ListBase *BKE_id_defgroup_list_get(const struct ID *id); @@ -59,9 +65,15 @@ struct bDeformGroup *BKE_object_defgroup_new(struct Object *ob, const char *name void BKE_defgroup_copy_list(struct ListBase *outbase, const struct ListBase *inbase); struct bDeformGroup *BKE_defgroup_duplicate(const struct bDeformGroup *ingroup); struct bDeformGroup *BKE_object_defgroup_find_name(const struct Object *ob, const char *name); +/** + * \note caller must free. + */ int *BKE_object_defgroup_flip_map(const struct Object *ob, int *flip_map_len, const bool use_default); +/** + * \note caller must free. + */ int *BKE_object_defgroup_flip_map_single(const struct Object *ob, int *flip_map_len, const bool use_default, @@ -71,11 +83,33 @@ int BKE_object_defgroup_name_index(const struct Object *ob, const char *name); void BKE_object_defgroup_unique_name(struct bDeformGroup *dg, struct Object *ob); struct MDeformWeight *BKE_defvert_find_index(const struct MDeformVert *dv, const int defgroup); +/** + * Ensures that `dv` has a deform weight entry for the specified defweight group. + * + * \note this function is mirrored in editmesh_tools.c, for use for edit-vertices. + */ struct MDeformWeight *BKE_defvert_ensure_index(struct MDeformVert *dv, const int defgroup); +/** + * Adds the given vertex to the specified vertex group, with given weight. + * + * \warning this does NOT check for existing, assume caller already knows its not there. + */ void BKE_defvert_add_index_notest(struct MDeformVert *dv, int defgroup, const float weight); +/** + * Removes the given vertex from the vertex group. + * + * \warning This function frees the given #MDeformWeight, do not use it afterward! + */ void BKE_defvert_remove_group(struct MDeformVert *dvert, struct MDeformWeight *dw); void BKE_defvert_clear(struct MDeformVert *dvert); +/** + * \return The first group index shared by both deform verts + * or -1 if none are found. + */ int BKE_defvert_find_shared(const struct MDeformVert *dvert_a, const struct MDeformVert *dvert_b); +/** + * \return true if has no weights. + */ bool BKE_defvert_is_weight_zero(const struct MDeformVert *dvert, const int defgroup_tot); void BKE_defvert_array_free_elems(struct MDeformVert *dvert, int totvert); @@ -83,14 +117,32 @@ void BKE_defvert_array_free(struct MDeformVert *dvert, int totvert); void BKE_defvert_array_copy(struct MDeformVert *dst, const struct MDeformVert *src, int totvert); float BKE_defvert_find_weight(const struct MDeformVert *dvert, const int defgroup); +/** + * Take care with this the rationale is: + * - if the object has no vertex group. act like vertex group isn't set and return 1.0. + * - if the vertex group exists but the 'defgroup' isn't found on this vertex, _still_ return 0.0. + * + * This is a bit confusing, just saves some checks from the caller. + */ float BKE_defvert_array_find_weight_safe(const struct MDeformVert *dvert, const int index, const int defgroup); +/** + * \return The total weight in all groups marked in the selection mask. + */ float BKE_defvert_total_selected_weight(const struct MDeformVert *dv, int defbase_tot, const bool *defbase_sel); +/** + * \return The representative weight of a multi-paint group, used for + * viewport colors and actual painting. + * + * Result equal to sum of weights with auto normalize, and average otherwise. + * Value is not clamped, since painting relies on multiplication being always + * commutative with the collective weight function. + */ float BKE_defvert_multipaint_collective_weight(const struct MDeformVert *dv, int defbase_tot, const bool *defbase_sel, @@ -100,9 +152,19 @@ float BKE_defvert_multipaint_collective_weight(const struct MDeformVert *dv, /* This much unlocked weight is considered equivalent to none. */ #define VERTEX_WEIGHT_LOCK_EPSILON 1e-6f +/** + * Computes the display weight for the lock relative weight paint mode. + * + * \return weight divided by 1-locked_weight with division by zero check + */ float BKE_defvert_calc_lock_relative_weight(float weight, float locked_weight, float unlocked_weight); +/** + * Computes the display weight for the lock relative weight paint mode, using weight data. + * + * \return weight divided by unlocked, or 1-locked_weight with division by zero check. + */ float BKE_defvert_lock_relative_weight(float weight, const struct MDeformVert *dv, int defbase_tot, @@ -110,41 +172,75 @@ float BKE_defvert_lock_relative_weight(float weight, const bool *defbase_unlocked); void BKE_defvert_copy(struct MDeformVert *dvert_dst, const struct MDeformVert *dvert_src); +/** + * Overwrite weights filtered by vgroup_subset. + * - do nothing if neither are set. + * - add destination weight if needed + */ void BKE_defvert_copy_subset(struct MDeformVert *dvert_dst, const struct MDeformVert *dvert_src, const bool *vgroup_subset, const int vgroup_tot); +/** + * Overwrite weights filtered by vgroup_subset and with mirroring specified by the flip map + * - do nothing if neither are set. + * - add destination weight if needed + */ void BKE_defvert_mirror_subset(struct MDeformVert *dvert_dst, const struct MDeformVert *dvert_src, const bool *vgroup_subset, const int vgroup_tot, const int *flip_map, const int flip_map_len); +/** + * Copy an index from one #MDeformVert to another. + * - do nothing if neither are set. + * - add destination weight if needed. + */ void BKE_defvert_copy_index(struct MDeformVert *dvert_dst, const int defgroup_dst, const struct MDeformVert *dvert_src, const int defgroup_src); +/** + * Only sync over matching weights, don't add or remove groups + * warning, loop within loop. + */ void BKE_defvert_sync(struct MDeformVert *dvert_dst, const struct MDeformVert *dvert_src, const bool use_ensure); +/** + * be sure all flip_map values are valid + */ void BKE_defvert_sync_mapped(struct MDeformVert *dvert_dst, const struct MDeformVert *dvert_src, const int *flip_map, const int flip_map_len, const bool use_ensure); +/** + * be sure all flip_map values are valid + */ void BKE_defvert_remap(struct MDeformVert *dvert, const int *map, const int map_len); void BKE_defvert_flip(struct MDeformVert *dvert, const int *flip_map, const int flip_map_len); void BKE_defvert_flip_merged(struct MDeformVert *dvert, const int *flip_map, const int flip_map_len); void BKE_defvert_normalize(struct MDeformVert *dvert); +/** + * Same as #BKE_defvert_normalize but takes a bool array. + */ void BKE_defvert_normalize_subset(struct MDeformVert *dvert, const bool *vgroup_subset, const int vgroup_tot); +/** + * Same as BKE_defvert_normalize() if the locked vgroup is not a member of the subset + */ void BKE_defvert_normalize_lock_single(struct MDeformVert *dvert, const bool *vgroup_subset, const int vgroup_tot, const uint def_nr_lock); +/** + * Same as BKE_defvert_normalize() if no locked vgroup is a member of the subset + */ void BKE_defvert_normalize_lock_map(struct MDeformVert *dvert, const bool *vgroup_subset, const int vgroup_tot, @@ -153,11 +249,16 @@ void BKE_defvert_normalize_lock_map(struct MDeformVert *dvert, /* Utilities to 'extract' a given vgroup into a simple float array, * for verts, but also edges/polys/loops. */ + void BKE_defvert_extract_vgroup_to_vertweights(struct MDeformVert *dvert, const int defgroup, const int num_verts, float *r_weights, const bool invert_vgroup); +/** + * The following three make basic interpolation, + * using temp vert_weights array to avoid looking up same weight several times. + */ void BKE_defvert_extract_vgroup_to_edgeweights(struct MDeformVert *dvert, const int defgroup, const int num_verts, diff --git a/source/blender/blenkernel/BKE_displist.h b/source/blender/blenkernel/BKE_displist.h index 8fb596a8096..12af80c2e30 100644 --- a/source/blender/blenkernel/BKE_displist.h +++ b/source/blender/blenkernel/BKE_displist.h @@ -98,6 +98,12 @@ void BKE_curve_calc_modifiers_pre(struct Depsgraph *depsgraph, bool BKE_displist_surfindex_get( const struct DispList *dl, int a, int *b, int *p1, int *p2, int *p3, int *p4); +/** + * \param normal_proj: Optional normal that's used to project the scan-fill verts into 2D coords. + * Pass this along if known since it saves time calculating the normal. + * This is also used to initialize #DispList.nors (one normal per display list). + * \param flipnormal: Flip the normal (same as passing \a normal_proj negated). + */ void BKE_displist_fill(const struct ListBase *dispbase, struct ListBase *to, const float normal_proj[3], diff --git a/source/blender/blenkernel/BKE_duplilist.h b/source/blender/blenkernel/BKE_duplilist.h index 989b68f4ccb..5eff84b8c9e 100644 --- a/source/blender/blenkernel/BKE_duplilist.h +++ b/source/blender/blenkernel/BKE_duplilist.h @@ -36,6 +36,9 @@ struct ID; /* ---------------------------------------------------- */ /* Dupli-Geometry */ +/** + * \return a #ListBase of #DupliObject. + */ struct ListBase *object_duplilist(struct Depsgraph *depsgraph, struct Scene *sce, struct Object *ob); diff --git a/source/blender/blenkernel/BKE_dynamicpaint.h b/source/blender/blenkernel/BKE_dynamicpaint.h index 31f48be2c27..4b34a9490c4 100644 --- a/source/blender/blenkernel/BKE_dynamicpaint.h +++ b/source/blender/blenkernel/BKE_dynamicpaint.h @@ -64,41 +64,79 @@ typedef struct PaintWavePoint { short state; } PaintWavePoint; +/** + * Modifier call. Processes dynamic paint modifier step. + */ struct Mesh *dynamicPaint_Modifier_do(struct DynamicPaintModifierData *pmd, struct Depsgraph *depsgraph, struct Scene *scene, struct Object *ob, struct Mesh *me); +/** + * Free whole dynamic-paint modifier. + */ void dynamicPaint_Modifier_free(struct DynamicPaintModifierData *pmd); void dynamicPaint_Modifier_free_runtime(struct DynamicPaintRuntime *runtime); void dynamicPaint_Modifier_copy(const struct DynamicPaintModifierData *pmd, struct DynamicPaintModifierData *tpmd, int flag); +/** + * Initialize modifier data. + */ bool dynamicPaint_createType(struct DynamicPaintModifierData *pmd, int type, struct Scene *scene); +/** + * Creates a new surface and adds it to the list + * If scene is null, frame range of 1-250 is used + * A pointer to this surface is returned. + */ struct DynamicPaintSurface *dynamicPaint_createNewSurface( struct DynamicPaintCanvasSettings *canvas, struct Scene *scene); +/** + * Clears surface data back to zero. + */ void dynamicPaint_clearSurface(const struct Scene *scene, struct DynamicPaintSurface *surface); +/** + * Completely (re)initializes surface (only for point cache types). + */ bool dynamicPaint_resetSurface(const struct Scene *scene, struct DynamicPaintSurface *surface); void dynamicPaint_freeSurface(const struct DynamicPaintModifierData *pmd, struct DynamicPaintSurface *surface); +/** + * Free canvas data. + */ void dynamicPaint_freeCanvas(struct DynamicPaintModifierData *pmd); +/* Free brush data */ void dynamicPaint_freeBrush(struct DynamicPaintModifierData *pmd); void dynamicPaint_freeSurfaceData(struct DynamicPaintSurface *surface); +/** + * Update cache frame range. + */ void dynamicPaint_cacheUpdateFrames(struct DynamicPaintSurface *surface); bool dynamicPaint_outputLayerExists(struct DynamicPaintSurface *surface, struct Object *ob, int output); +/** + * Change surface data to defaults on new type. + */ void dynamicPaintSurface_updateType(struct DynamicPaintSurface *surface); void dynamicPaintSurface_setUniqueName(struct DynamicPaintSurface *surface, const char *basename); +/** + * Get currently active surface (in user interface). + */ struct DynamicPaintSurface *get_activeSurface(struct DynamicPaintCanvasSettings *canvas); -/* image sequence baking */ +/** + * Image sequence baking. + */ int dynamicPaint_createUVSurface(struct Scene *scene, struct DynamicPaintSurface *surface, float *progress, short *do_update); +/** + * Calculate a single frame and included sub-frames for surface. + */ int dynamicPaint_calculateFrame(struct DynamicPaintSurface *surface, struct Depsgraph *depsgraph, struct Scene *scene, diff --git a/source/blender/blenkernel/BKE_editmesh.h b/source/blender/blenkernel/BKE_editmesh.h index 2c24b1a5487..32cc5961e4a 100644 --- a/source/blender/blenkernel/BKE_editmesh.h +++ b/source/blender/blenkernel/BKE_editmesh.h @@ -102,12 +102,29 @@ void BKE_editmesh_looptri_calc_with_partial(BMEditMesh *em, struct BMPartialUpda void BKE_editmesh_looptri_and_normals_calc_with_partial(BMEditMesh *em, struct BMPartialUpdate *bmpinfo); +/** + * Performing the face normal calculation at the same time as tessellation + * gives a reasonable performance boost (approx ~20% faster). + */ void BKE_editmesh_looptri_and_normals_calc(BMEditMesh *em); +/** + * \note The caller is responsible for ensuring triangulation data, + * typically by calling #BKE_editmesh_looptri_calc. + */ BMEditMesh *BKE_editmesh_create(BMesh *bm); BMEditMesh *BKE_editmesh_copy(BMEditMesh *em); +/** + * \brief Return the #BMEditMesh for a given object + * + * \note this function assumes this is a mesh object, + * don't add NULL data check here. caller must do that + */ BMEditMesh *BKE_editmesh_from_object(struct Object *ob); void BKE_editmesh_free_derived_caches(BMEditMesh *em); +/** + * \note Does not free the #BMEditMesh struct itself. + */ void BKE_editmesh_free_data(BMEditMesh *em); float (*BKE_editmesh_vert_coords_alloc(struct Depsgraph *depsgraph, @@ -124,6 +141,9 @@ const float (*BKE_editmesh_vert_coords_when_deformed(struct Depsgraph *depsgraph bool *r_is_alloc))[3]; void BKE_editmesh_lnorspace_update(BMEditMesh *em, struct Mesh *me); +/** + * If auto-smooth not already set, set it. + */ void BKE_editmesh_ensure_autosmooth(BMEditMesh *em, struct Mesh *me); struct BoundBox *BKE_editmesh_cage_boundbox_get(BMEditMesh *em); diff --git a/source/blender/blenkernel/BKE_editmesh_bvh.h b/source/blender/blenkernel/BKE_editmesh_bvh.h index 69d1b4819f8..fc274b4ffd1 100644 --- a/source/blender/blenkernel/BKE_editmesh_bvh.h +++ b/source/blender/blenkernel/BKE_editmesh_bvh.h @@ -78,7 +78,9 @@ struct BMFace *BKE_bmbvh_ray_cast_filter(BMBVHTree *tree, BMBVHTree_FaceFilter filter_cb, void *filter_userdata); -/* find a vert closest to co in a sphere of radius dist_max */ +/** + * Find a vert closest to co in a sphere of radius dist_max. + */ struct BMVert *BKE_bmbvh_find_vert_closest(BMBVHTree *tree, const float co[3], const float dist_max); @@ -86,10 +88,16 @@ struct BMFace *BKE_bmbvh_find_face_closest(BMBVHTree *tree, const float co[3], const float dist_max); +/** + * Overlap indices reference the looptri's. + */ struct BVHTreeOverlap *BKE_bmbvh_overlap(const BMBVHTree *bmtree_a, const BMBVHTree *bmtree_b, unsigned int *r_overlap_tot); +/** + * Overlap indices reference the looptri's. + */ struct BVHTreeOverlap *BKE_bmbvh_overlap_self(const BMBVHTree *bmtree, unsigned int *r_overlap_tot); diff --git a/source/blender/blenkernel/BKE_editmesh_tangent.h b/source/blender/blenkernel/BKE_editmesh_tangent.h index 0e3f063ae44..b76db11348e 100644 --- a/source/blender/blenkernel/BKE_editmesh_tangent.h +++ b/source/blender/blenkernel/BKE_editmesh_tangent.h @@ -24,6 +24,13 @@ extern "C" { #endif +/** + * \see #BKE_mesh_calc_loop_tangent, same logic but used arrays instead of #BMesh data. + * + * \note This function is not so normal, its using #BMesh.ldata as input, + * but output's to #Mesh.ldata. + * This is done because #CD_TANGENT is cache data used only for drawing. + */ void BKE_editmesh_loop_tangent_calc(BMEditMesh *em, bool calc_active_tangent, const char (*tangent_names)[MAX_NAME], diff --git a/source/blender/blenkernel/BKE_effect.h b/source/blender/blenkernel/BKE_effect.h index 3a964ddb1aa..030b351f926 100644 --- a/source/blender/blenkernel/BKE_effect.h +++ b/source/blender/blenkernel/BKE_effect.h @@ -113,16 +113,27 @@ struct PartDeflect *BKE_partdeflect_new(int type); struct PartDeflect *BKE_partdeflect_copy(const struct PartDeflect *pd_src); void BKE_partdeflect_free(struct PartDeflect *pd); +/** + * Create list of effector relations in the collection or entire scene. + * This is used by the depsgraph to build relations, as well as faster + * lookup of effectors during evaluation. + */ struct ListBase *BKE_effector_relations_create(struct Depsgraph *depsgraph, struct ViewLayer *view_layer, struct Collection *collection); void BKE_effector_relations_free(struct ListBase *lb); +/** + * Create effective list of effectors from relations built beforehand. + */ struct ListBase *BKE_effectors_create(struct Depsgraph *depsgraph, struct Object *ob_src, struct ParticleSystem *psys_src, struct EffectorWeights *weights, bool use_rotation); +/** + * Generic force/speed system, now used for particles, soft-bodies & dynamic-paint. + */ void BKE_effectors_apply(struct ListBase *effectors, struct ListBase *colliders, struct EffectorWeights *weights, diff --git a/source/blender/blenkernel/BKE_fcurve.h b/source/blender/blenkernel/BKE_fcurve.h index f494c2e30cc..1537d14ab01 100644 --- a/source/blender/blenkernel/BKE_fcurve.h +++ b/source/blender/blenkernel/BKE_fcurve.h @@ -133,20 +133,56 @@ typedef enum eFMI_Requirement_Flags { } eFMI_Requirement_Flags; /* Function Prototypes for FModifierTypeInfo's */ + +/** + * This function should always be used to get the appropriate type-info, + * as it has checks which prevent segfaults in some weird cases. + */ const FModifierTypeInfo *fmodifier_get_typeinfo(const struct FModifier *fcm); +/** + * This function should be used for getting the appropriate type-info when only + * a F-Curve modifier type is known. + */ const FModifierTypeInfo *get_fmodifier_typeinfo(const int type); /* ---------------------- */ +/** + * Add a new F-Curve Modifier to the given F-Curve of a certain type. + */ struct FModifier *add_fmodifier(ListBase *modifiers, int type, struct FCurve *owner_fcu); +/** + * Make a copy of the specified F-Modifier. + */ struct FModifier *copy_fmodifier(const struct FModifier *src); +/** + * Duplicate all of the F-Modifiers in the Modifier stacks. + */ void copy_fmodifiers(ListBase *dst, const ListBase *src); +/** + * Remove and free the given F-Modifier from the given stack. + */ bool remove_fmodifier(ListBase *modifiers, struct FModifier *fcm); +/** + * Remove all of a given F-Curve's modifiers. + */ void free_fmodifiers(ListBase *modifiers); +/** + * Find the active F-Modifier. + */ struct FModifier *find_active_fmodifier(ListBase *modifiers); +/** + * Set the active F-Modifier. + */ void set_active_fmodifier(ListBase *modifiers, struct FModifier *fcm); +/** + * Do we have any modifiers which match certain criteria. + * + * \param mtype: Type of modifier (if 0, doesn't matter). + * \param acttype: Type of action to perform (if -1, doesn't matter). + */ bool list_has_suitable_fmodifier(ListBase *modifiers, int mtype, short acttype); typedef struct FModifiersStackStorage { @@ -156,17 +192,38 @@ typedef struct FModifiersStackStorage { } FModifiersStackStorage; uint evaluate_fmodifiers_storage_size_per_modifier(ListBase *modifiers); +/** + * Evaluate time modifications imposed by some F-Curve Modifiers. + * + * - This step acts as an optimization to prevent the F-Curve stack being evaluated + * several times by modifiers requesting the time be modified, as the final result + * would have required using the modified time + * - Modifiers only ever receive the unmodified time, as subsequent modifiers should be + * working on the 'global' result of the modified curve, not some localized segment, + * so \a evaltime gets set to whatever the last time-modifying modifier likes. + * - We start from the end of the stack, as only the last one matters for now. + * + * \param fcu: Can be NULL. + */ float evaluate_time_fmodifiers(FModifiersStackStorage *storage, ListBase *modifiers, struct FCurve *fcu, float cvalue, float evaltime); +/** + * Evaluates the given set of F-Curve Modifiers using the given data + * Should only be called after evaluate_time_fmodifiers() has been called. + */ void evaluate_value_fmodifiers(FModifiersStackStorage *storage, ListBase *modifiers, struct FCurve *fcu, float *cvalue, float evaltime); +/** + * Bake modifiers for given F-Curve to curve sample data, in the frame range defined + * by start and end (inclusive). + */ void fcurve_bake_modifiers(struct FCurve *fcu, int start, int end); int BKE_fcm_envelope_find_index(struct FCM_EnvelopeData *array, @@ -182,30 +239,64 @@ int BKE_fcm_envelope_find_index(struct FCM_EnvelopeData *array, /* -------- Data Management -------- */ struct FCurve *BKE_fcurve_create(void); +/** + * Frees the F-Curve itself too, so make sure #BLI_remlink is called before calling this. + */ void BKE_fcurve_free(struct FCurve *fcu); +/** + * Duplicate a F-Curve. + */ struct FCurve *BKE_fcurve_copy(const struct FCurve *fcu); - +/** + * Frees a list of F-Curves. + */ void BKE_fcurves_free(ListBase *list); +/** + * Duplicate a list of F-Curves. + */ void BKE_fcurves_copy(ListBase *dst, ListBase *src); +/** + * Callback used by lib_query to walk over all ID usages + * (mimics `foreach_id` callback of #IDTypeInfo structure). + */ void BKE_fcurve_foreach_id(struct FCurve *fcu, struct LibraryForeachIDData *data); -/* find matching F-Curve in the given list of F-Curves */ +/** + * Find the F-Curve affecting the given RNA-access path + index, + * in the list of F-Curves provided. + */ struct FCurve *BKE_fcurve_find(ListBase *list, const char rna_path[], const int array_index); +/** + * Quick way to loop over all f-curves of a given 'path'. + */ struct FCurve *BKE_fcurve_iter_step(struct FCurve *fcu_iter, const char rna_path[]); -/* high level function to get an fcurve from C without having the rna */ +/** + * High level function to get an f-curve from C without having the RNA. + */ struct FCurve *id_data_find_fcurve( ID *id, void *data, struct StructRNA *type, const char *prop_name, int index, bool *r_driven); -/* Get list of LinkData's containing pointers to the F-Curves which control the types of data - * indicated - * e.g. numMatches = BKE_fcurves_filter(matches, &act->curves, "pose.bones[", "MyFancyBone"); +/** + * Get list of LinkData's containing pointers to the F-curves + * which control the types of data indicated. + * e.g. `numMatches = BKE_fcurves_filter(matches, &act->curves, "pose.bones[", "MyFancyBone");` + * + * Lists: + * \param dst: list of LinkData's matching the criteria returned. + * List must be freed after use, and is assumed to be empty when passed. + * \param src: list of F-Curves to search through + * Filters: + * \param dataPrefix: i.e. `pose.bones[` or `nodes[`. + * \param dataName: name of entity within "" immediately following the prefix. */ int BKE_fcurves_filter(ListBase *dst, ListBase *src, const char *dataPrefix, const char *dataName); -/* Find an f-curve based on an rna property. */ +/** + * Find an f-curve based on an rna property. + */ struct FCurve *BKE_fcurve_find_by_rna(struct PointerRNA *ptr, struct PropertyRNA *prop, int rnaindex, @@ -213,8 +304,10 @@ struct FCurve *BKE_fcurve_find_by_rna(struct PointerRNA *ptr, struct bAction **r_action, bool *r_driven, bool *r_special); -/* Same as above, but takes a context data, - * temp hack needed for complex paths like texture ones. */ +/** + * Same as above, but takes a context data, + * temp hack needed for complex paths like texture ones. + */ struct FCurve *BKE_fcurve_find_by_rna_context_ui(struct bContext *C, struct PointerRNA *ptr, struct PropertyRNA *prop, @@ -224,7 +317,8 @@ struct FCurve *BKE_fcurve_find_by_rna_context_ui(struct bContext *C, bool *r_driven, bool *r_special); -/* Binary search algorithm for finding where to 'insert' BezTriple with given frame number. +/** + * Binary search algorithm for finding where to 'insert' #BezTriple with given frame number. * Returns the index to insert at (data already at that index will be offset if replace is 0) */ int BKE_fcurve_bezt_binarysearch_index(const struct BezTriple array[], @@ -233,23 +327,35 @@ int BKE_fcurve_bezt_binarysearch_index(const struct BezTriple array[], bool *r_replace); /* fcurve_cache.c */ -/* Cached f-curve look-ups, use when this needs to be done many times. */ + +/** + * Cached f-curve look-ups, use when this needs to be done many times. + */ struct FCurvePathCache; struct FCurvePathCache *BKE_fcurve_pathcache_create(ListBase *list); void BKE_fcurve_pathcache_destroy(struct FCurvePathCache *fcache); struct FCurve *BKE_fcurve_pathcache_find(struct FCurvePathCache *fcache, const char rna_path[], const int array_index); +/** + * Fill in an array of F-Curve, leave NULL when not found. + * + * \return The number of F-Curves found. + */ int BKE_fcurve_pathcache_find_array(struct FCurvePathCache *fcache, const char *rna_path, struct FCurve **fcurve_result, int fcurve_result_len); -/* get the time extents for F-Curve */ +/** + * Calculate the extents of F-Curve's keyframes. + */ bool BKE_fcurve_calc_range( struct FCurve *fcu, float *min, float *max, const bool do_sel_only, const bool do_min_length); -/* get the bounding-box extents for F-Curve */ +/** + * Calculate the extents of F-Curve's data. + */ bool BKE_fcurve_calc_bounds(struct FCurve *fcu, float *xmin, float *xmax, @@ -258,6 +364,14 @@ bool BKE_fcurve_calc_bounds(struct FCurve *fcu, const bool do_sel_only, const bool include_handles); +/** + * Return an array of keyed frames, rounded to `interval`. + * + * \param interval: Set to 1.0 to round to whole keyframes, 0.5 for in-between key-frames, etc. + * + * \note An interval of zero could be supported (this implies no rounding at all), + * however this risks very small differences in float values being treated as separate keyframes. + */ float *BKE_fcurves_calc_keyed_frames_ex(struct FCurve **fcurve_array, const int fcurve_array_len, const float interval, @@ -266,23 +380,42 @@ float *BKE_fcurves_calc_keyed_frames(struct FCurve **fcurve_array, const int fcurve_array_len, int *r_frames_len); +/** + * Set the index that stores the FCurve's active keyframe, assuming that \a active_bezt + * is already part of `fcu->bezt`. If NULL, set active keyframe index to "none." + */ void BKE_fcurve_active_keyframe_set(struct FCurve *fcu, const struct BezTriple *active_bezt); +/** + * Get the active keyframe index, with sanity checks for point bounds. + */ int BKE_fcurve_active_keyframe_index(const struct FCurve *fcu); -/* Move the indexed keyframe to the given value, and move the handles with it to ensure the slope - * remains the same. */ +/** + * Move the indexed keyframe to the given value, + * and move the handles with it to ensure the slope remains the same. + */ void BKE_fcurve_keyframe_move_value_with_handles(struct BezTriple *keyframe, float new_value); /* .............. */ -/* Are keyframes on F-Curve of any use (to final result, and to show in editors)? */ +/** + * Are keyframes on F-Curve of any use (to final result, and to show in editors)? + * Usability of keyframes refers to whether they should be displayed, + * and also whether they will have any influence on the final result. + */ bool BKE_fcurve_are_keyframes_usable(struct FCurve *fcu); -/* Can keyframes be added to F-Curve? */ +/** + * Can keyframes be added to F-Curve? + * Keyframes can only be added if they are already visible. + */ bool BKE_fcurve_is_keyframable(struct FCurve *fcu); bool BKE_fcurve_is_protected(struct FCurve *fcu); -/* The curve is an infinite cycle via Cycles modifier */ +/** + * Checks if the F-Curve has a Cycles modifier with simple settings + * that warrant transition smoothing. + */ bool BKE_fcurve_is_cyclic(struct FCurve *fcu); /* Type of infinite cycle for a curve. */ @@ -294,9 +427,19 @@ typedef enum eFCU_Cycle_Type { FCU_CYCLE_OFFSET, } eFCU_Cycle_Type; +/** + * Checks if the F-Curve has a Cycles modifier, and returns the type of the cycle behavior. + */ eFCU_Cycle_Type BKE_fcurve_get_cycle_type(struct FCurve *fcu); -/* Recompute handles to neatly subdivide the prev-next range at bezt. */ +/** + * Recompute bezier handles of all three given BezTriples, so that `bezt` can be inserted between + * `prev` and `next` without changing the resulting curve shape. + * + * \param r_pdelta: return Y difference between `bezt` and the original curve value at its X + * position. + * \return Whether the split was successful. + */ bool BKE_fcurve_bezt_subdivide_handles(struct BezTriple *bezt, struct BezTriple *prev, struct BezTriple *next, @@ -304,12 +447,50 @@ bool BKE_fcurve_bezt_subdivide_handles(struct BezTriple *bezt, /* -------- Curve Sanity -------- */ +/** + * This function recalculates the handles of an F-Curve. Acts based on selection with `SELECT` + * flag. To use a different flag, use #calchandles_fcurve_ex(). + * + * If the BezTriples have been rearranged, sort them first before using this. + */ void calchandles_fcurve(struct FCurve *fcu); +/** + * Variant of #calchandles_fcurve() that allows calculating based on a different select flag. + * + * \param handle_sel_flag: The flag (bezt.f1/2/3) value to use to determine selection. + * Usually `SELECT`, but may want to use a different one at times + * (if caller does not operate on selection). + */ void calchandles_fcurve_ex(struct FCurve *fcu, eBezTriple_Flag handle_sel_flag); +/** + * Update handles, making sure the handle-types are valid (e.g. correctly deduced from an "Auto" + * type), and recalculating their position vectors. + * Use when something has changed handle positions. + * + * \param sel_flag: The flag (bezt.f1/2/3) value to use to determine selection. Usually `SELECT`, + * but may want to use a different one at times (if caller does not operate on selection). + * \param use_handle: Check selection state of individual handles, otherwise always update both + * handles if the key is selected. + */ void testhandles_fcurve(struct FCurve *fcu, eBezTriple_Flag sel_flag, const bool use_handle); +/** + * This function sorts BezTriples so that they are arranged in chronological order, + * as tools working on F-Curves expect that the BezTriples are in order. + */ void sort_time_fcurve(struct FCurve *fcu); +/** + * This function tests if any BezTriples are out of order, thus requiring a sort. + */ bool test_time_fcurve(struct FCurve *fcu); +/** + * The length of each handle is not allowed to be more + * than the horizontal distance between (v1-v4). + * This is to prevent curve loops. + * + * This function is very similar to BKE_curve_correct_bezpart(), but allows a steeper tangent for + * more snappy animations. This is not desired for other areas in which curves are used, though. + */ void BKE_fcurve_correct_bezpart(const float v1[2], float v2[2], float v3[2], const float v4[2]); /* -------- Evaluation -------- */ @@ -321,8 +502,14 @@ float evaluate_fcurve_driver(struct PathResolvedRNA *anim_rna, struct FCurve *fcu, struct ChannelDriver *driver_orig, const struct AnimationEvalContext *anim_eval_context); +/** + * Checks if the curve has valid keys, drivers or modifiers that produce an actual curve. + */ bool BKE_fcurve_is_empty(struct FCurve *fcu); -/* evaluate fcurve and store value */ +/** + * Calculate the value of the given F-Curve at the given frame, + * and store it's value in #FCurve.curval. + */ float calculate_fcurve(struct PathResolvedRNA *anim_rna, struct FCurve *fcu, const struct AnimationEvalContext *anim_eval_context); @@ -331,26 +518,34 @@ float calculate_fcurve(struct PathResolvedRNA *anim_rna, /* -------- Defines -------- */ -/* Basic signature for F-Curve sample-creation function - * - fcu: the F-Curve being operated on - * - data: pointer to some specific data that may be used by one of the callbacks +/** + * Basic signature for F-Curve sample-creation function. + * + * \param fcu: the F-Curve being operated on. + * \param data: pointer to some specific data that may be used by one of the callbacks. */ typedef float (*FcuSampleFunc)(struct FCurve *fcu, void *data, float evaltime); /* ----- Sampling Callbacks ------ */ -/* Basic sampling callback which acts as a wrapper for evaluate_fcurve() */ +/** + * Basic sampling callback which acts as a wrapper for #evaluate_fcurve() + * 'data' arg here is unneeded here. + */ float fcurve_samplingcb_evalcurve(struct FCurve *fcu, void *data, float evaltime); /* -------- Main Methods -------- */ -/* Main API function for creating a set of sampled curve data, given some callback function +/** + * Main API function for creating a set of sampled curve data, given some callback function * used to retrieve the values to store. */ void fcurve_store_samples( struct FCurve *fcu, void *data, int start, int end, FcuSampleFunc sample_cb); -/* Convert baked/sampled fcurves into bezt/regular fcurves. */ +/** + * Convert baked/sampled f-curves into bezt/regular f-curves. + */ void fcurve_samples_to_keyframes(struct FCurve *fcu, const int start, const int end); /* ************* F-Curve .blend file API ******************** */ diff --git a/source/blender/blenkernel/BKE_fcurve_driver.h b/source/blender/blenkernel/BKE_fcurve_driver.h index 5b4da4a78a4..af4c970241f 100644 --- a/source/blender/blenkernel/BKE_fcurve_driver.h +++ b/source/blender/blenkernel/BKE_fcurve_driver.h @@ -66,34 +66,84 @@ struct PropertyRNA; /* ---------------------- */ +/** + * This frees the driver itself. + */ void fcurve_free_driver(struct FCurve *fcu); +/** + * This makes a copy of the given driver. + */ struct ChannelDriver *fcurve_copy_driver(const struct ChannelDriver *driver); +/** + * Copy driver variables from src_vars list to dst_vars list. + */ void driver_variables_copy(struct ListBase *dst_vars, const struct ListBase *src_vars); +/** + * Compute channel values for a rotational Transform Channel driver variable. + */ void BKE_driver_target_matrix_to_rot_channels( float mat[4][4], int auto_order, int rotation_mode, int channel, bool angles, float r_buf[4]); +/** + * Perform actual freeing driver variable and remove it from the given list. + */ void driver_free_variable(struct ListBase *variables, struct DriverVar *dvar); +/** + * Free the driver variable and do extra updates. + */ void driver_free_variable_ex(struct ChannelDriver *driver, struct DriverVar *dvar); +/** + * Change the type of driver variable. + */ void driver_change_variable_type(struct DriverVar *dvar, int type); +/** + * Validate driver name (after being renamed). + */ void driver_variable_name_validate(struct DriverVar *dvar); +/** + * Add a new driver variable. + */ struct DriverVar *driver_add_new_variable(struct ChannelDriver *driver); +/** + * Evaluate a Driver Variable to get a value that contributes to the final. + */ float driver_get_variable_value(struct ChannelDriver *driver, struct DriverVar *dvar); +/** + * Same as 'dtar_get_prop_val'. but get the RNA property. + */ bool driver_get_variable_property(struct ChannelDriver *driver, struct DriverTarget *dtar, struct PointerRNA *r_ptr, struct PropertyRNA **r_prop, int *r_index); +/** + * Check if the expression in the driver conforms to the simple subset. + */ bool BKE_driver_has_simple_expression(struct ChannelDriver *driver); +/** + * Check if the expression in the driver may depend on the current frame. + */ bool BKE_driver_expression_depends_on_time(struct ChannelDriver *driver); +/** + * Reset cached compiled expression data. + */ void BKE_driver_invalidate_expression(struct ChannelDriver *driver, bool expr_changed, bool varname_changed); +/** + * Evaluate an Channel-Driver to get a 'time' value to use + * instead of `anim_eval_context->eval_time`. + * + * - `anim_eval_context->eval_time` is the frame at which F-Curve is being evaluated. + * - Has to return a float value. + * - \a driver_orig is where we cache Python expressions, in case of COW + */ float evaluate_driver(struct PathResolvedRNA *anim_rna, struct ChannelDriver *driver, struct ChannelDriver *driver_orig, diff --git a/source/blender/blenkernel/BKE_fluid.h b/source/blender/blenkernel/BKE_fluid.h index 33ff6943514..7bafcf00ce8 100644 --- a/source/blender/blenkernel/BKE_fluid.h +++ b/source/blender/blenkernel/BKE_fluid.h @@ -64,6 +64,10 @@ void BKE_fluid_cache_free_all(struct FluidDomainSettings *fds, struct Object *ob void BKE_fluid_cache_free(struct FluidDomainSettings *fds, struct Object *ob, int cache_map); void BKE_fluid_cache_new_name_for_current_session(int maxlen, char *r_name); +/** + * Get fluid velocity and density at given coordinates. + * \returns fluid density or -1.0f if outside domain. + */ float BKE_fluid_get_velocity_at(struct Object *ob, float position[3], float velocity[3]); int BKE_fluid_get_data_flags(struct FluidDomainSettings *fds); diff --git a/source/blender/blenkernel/BKE_freestyle.h b/source/blender/blenkernel/BKE_freestyle.h index 5e29665d728..ee3517f5b43 100644 --- a/source/blender/blenkernel/BKE_freestyle.h +++ b/source/blender/blenkernel/BKE_freestyle.h @@ -47,6 +47,10 @@ void BKE_freestyle_config_copy(struct FreestyleConfig *new_config, struct FreestyleModuleConfig *BKE_freestyle_module_add(struct FreestyleConfig *config); bool BKE_freestyle_module_delete(struct FreestyleConfig *config, struct FreestyleModuleConfig *module_conf); +/** + * Reinsert \a module_conf offset by \a direction from current position. + * \return if position of \a module_conf changed. + */ bool BKE_freestyle_module_move(struct FreestyleConfig *config, struct FreestyleModuleConfig *module_conf, int direction); diff --git a/source/blender/blenkernel/BKE_geometry_set.hh b/source/blender/blenkernel/BKE_geometry_set.hh index 3fb8da0889b..053b30f4724 100644 --- a/source/blender/blenkernel/BKE_geometry_set.hh +++ b/source/blender/blenkernel/BKE_geometry_set.hh @@ -150,6 +150,10 @@ class GeometryComponent { const AttributeInit &initializer); blender::Set attribute_ids() const; + /** + * \return False if the callback explicitly returned false at any point, otherwise true, + * meaning the callback made it all the way through. + */ bool attribute_foreach(const AttributeForeachCallback callback) const; virtual bool is_empty() const; @@ -266,6 +270,9 @@ struct GeometrySet { std::array components_; public: + /** + * The methods are defaulted here so that they are not instantiated in every translation unit. + */ GeometrySet(); GeometrySet(const GeometrySet &other); GeometrySet(GeometrySet &&other); @@ -273,6 +280,10 @@ struct GeometrySet { GeometrySet &operator=(const GeometrySet &other); GeometrySet &operator=(GeometrySet &&other); + /** + * This method can only be used when the geometry set is mutable. It returns a mutable geometry + * component of the given type. + */ GeometryComponent &get_component_for_write(GeometryComponentType component_type); template Component &get_component_for_write() { @@ -280,6 +291,9 @@ struct GeometrySet { return static_cast(this->get_component_for_write(Component::static_type)); } + /** + * Get the component of the given type. Might return null if the component does not exist yet. + */ const GeometryComponent *get_component_for_read(GeometryComponentType component_type) const; template const Component *get_component_for_read() const { @@ -301,19 +315,32 @@ struct GeometrySet { return this->remove(Component::static_type); } + /** + * Remove all geometry components with types that are not in the provided list. + */ void keep_only(const blender::Span component_types); void add(const GeometryComponent &component); + /** + * Get all geometry components in this geometry set for read-only access. + */ blender::Vector get_components_for_read() const; void compute_boundbox_without_instances(blender::float3 *r_min, blender::float3 *r_max) const; friend std::ostream &operator<<(std::ostream &stream, const GeometrySet &geometry_set); + /** + * Remove all geometry components from the geometry set. + */ void clear(); bool owns_direct_data() const; + /** + * Make sure that the geometry can be cached. This does not ensure ownership of object/collection + * instances. + */ void ensure_owns_direct_data(); using AttributeForeachCallback = @@ -336,46 +363,120 @@ struct GeometrySet { using ForeachSubGeometryCallback = blender::FunctionRef; + /** + * Modify every (recursive) instance separately. This is often more efficient than realizing all + * instances just to change the same thing on all of them. + */ void modify_geometry_sets(ForeachSubGeometryCallback callback); /* Utility methods for creation. */ + /** + * Create a new geometry set that only contains the given mesh. + */ static GeometrySet create_with_mesh( Mesh *mesh, GeometryOwnershipType ownership = GeometryOwnershipType::Owned); + /** + * Create a new geometry set that only contains the given point cloud. + */ static GeometrySet create_with_pointcloud( PointCloud *pointcloud, GeometryOwnershipType ownership = GeometryOwnershipType::Owned); + /** + * Create a new geometry set that only contains the given curve. + */ static GeometrySet create_with_curve( CurveEval *curve, GeometryOwnershipType ownership = GeometryOwnershipType::Owned); /* Utility methods for access. */ + /** + * Returns true when the geometry set has a mesh component that has a mesh. + */ bool has_mesh() const; + /** + * Returns true when the geometry set has a point cloud component that has a point cloud. + */ bool has_pointcloud() const; + /** + * Returns true when the geometry set has an instances component that has at least one instance. + */ bool has_instances() const; + /** + * Returns true when the geometry set has a volume component that has a volume. + */ bool has_volume() const; + /** + * Returns true when the geometry set has a curve component that has a curve. + */ bool has_curve() const; + /** + * Returns true when the geometry set has any data that is not an instance. + */ bool has_realized_data() const; + /** + * Return true if the geometry set has any component that isn't empty. + */ bool is_empty() const; + /** + * Returns a read-only mesh or null. + */ const Mesh *get_mesh_for_read() const; + /** + * Returns a read-only point cloud of null. + */ const PointCloud *get_pointcloud_for_read() const; + /** + * Returns a read-only volume or null. + */ const Volume *get_volume_for_read() const; + /** + * Returns a read-only curve or null. + */ const CurveEval *get_curve_for_read() const; + /** + * Returns a mutable mesh or null. No ownership is transferred. + */ Mesh *get_mesh_for_write(); + /** + * Returns a mutable point cloud or null. No ownership is transferred. + */ PointCloud *get_pointcloud_for_write(); + /** + * Returns a mutable volume or null. No ownership is transferred. + */ Volume *get_volume_for_write(); + /** + * Returns a mutable curve or null. No ownership is transferred. + */ CurveEval *get_curve_for_write(); /* Utility methods for replacement. */ + /** + * Clear the existing mesh and replace it with the given one. + */ void replace_mesh(Mesh *mesh, GeometryOwnershipType ownership = GeometryOwnershipType::Owned); + /** + * Clear the existing point cloud and replace with the given one. + */ void replace_pointcloud(PointCloud *pointcloud, GeometryOwnershipType ownership = GeometryOwnershipType::Owned); + /** + * Clear the existing volume and replace with the given one. + */ void replace_volume(Volume *volume, GeometryOwnershipType ownership = GeometryOwnershipType::Owned); + /** + * Clear the existing curve and replace it with the given one. + */ void replace_curve(CurveEval *curve, GeometryOwnershipType ownership = GeometryOwnershipType::Owned); private: /* Utility to retrieve a mutable component without creating it. */ + /** + * Retrieve the pointer to a component without creating it if it does not exist, + * unlike #get_component_for_write. + */ GeometryComponent *get_component_ptr(GeometryComponentType type); template Component *get_component_ptr() { @@ -397,10 +498,25 @@ class MeshComponent : public GeometryComponent { void clear(); bool has_mesh() const; + /** + * Clear the component and replace it with the new mesh. + */ void replace(Mesh *mesh, GeometryOwnershipType ownership = GeometryOwnershipType::Owned); + /** + * Return the mesh and clear the component. The caller takes over responsibility for freeing the + * mesh (if the component was responsible before). + */ Mesh *release(); + /** + * Get the mesh from this component. This method can be used by multiple threads at the same + * time. Therefore, the returned mesh should not be modified. No ownership is transferred. + */ const Mesh *get_for_read() const; + /** + * Get the mesh from this component. This method can only be used when the component is mutable, + * i.e. it is not shared. The returned mesh can be modified. No ownership is transferred. + */ Mesh *get_for_write(); int attribute_domain_size(const AttributeDomain domain) const final; @@ -434,11 +550,28 @@ class PointCloudComponent : public GeometryComponent { void clear(); bool has_pointcloud() const; + /** + * Clear the component and replace it with the new point cloud. + */ void replace(PointCloud *pointcloud, GeometryOwnershipType ownership = GeometryOwnershipType::Owned); + /** + * Return the point cloud and clear the component. The caller takes over responsibility for + * freeing the point cloud (if the component was responsible before). + */ PointCloud *release(); + /** + * Get the point cloud from this component. This method can be used by multiple threads at the + * same time. Therefore, the returned point cloud should not be modified. No ownership is + * transferred. + */ const PointCloud *get_for_read() const; + /** + * Get the point cloud from this component. This method can only be used when the component is + * mutable, i.e. it is not shared. The returned point cloud can be modified. No ownership is + * transferred. + */ PointCloud *get_for_write(); int attribute_domain_size(const AttributeDomain domain) const final; @@ -476,6 +609,9 @@ class CurveComponent : public GeometryComponent { void clear(); bool has_curve() const; + /** + * Clear the component and replace it with the new curve. + */ void replace(CurveEval *curve, GeometryOwnershipType ownership = GeometryOwnershipType::Owned); CurveEval *release(); @@ -489,6 +625,10 @@ class CurveComponent : public GeometryComponent { bool owns_direct_data() const override; void ensure_owns_direct_data() override; + /** + * Create empty curve data used for rendering the spline's wire edges. + * \note See comment on #curve_for_render_ for further explanation. + */ const Curve *get_curve_for_render() const; static constexpr inline GeometryComponentType static_type = GEO_COMPONENT_TYPE_CURVE; @@ -655,15 +795,36 @@ class InstancesComponent : public GeometryComponent { void clear(); void reserve(int min_capacity); + /** + * Resize the transform, handles, and ID vectors to the specified capacity. + * + * \note This function should be used carefully, only when it's guaranteed + * that the data will be filled. + */ void resize(int capacity); + /** + * Returns a handle for the given reference. + * If the reference exists already, the handle of the existing reference is returned. + * Otherwise a new handle is added. + */ int add_reference(const InstanceReference &reference); void add_instance(int instance_handle, const blender::float4x4 &transform); blender::Span references() const; void remove_unused_references(); + /** + * If references have a collection or object type, convert them into geometry instances + * recursively. After that, the geometry sets can be edited. There may still be instances of + * other types of they can't be converted to geometry sets. + */ void ensure_geometry_instances(); + /** + * With write access to the instances component, the data in the instanced geometry sets can be + * changed. This is a function on the component rather than each reference to ensure `const` + * correctness for that reason. + */ GeometrySet &geometry_set_from_reference(const int reference_index); blender::Span instance_reference_handles() const; @@ -708,10 +869,26 @@ class VolumeComponent : public GeometryComponent { void clear(); bool has_volume() const; + /** + * Clear the component and replace it with the new volume. + */ void replace(Volume *volume, GeometryOwnershipType ownership = GeometryOwnershipType::Owned); + /** + * Return the volume and clear the component. The caller takes over responsibility for freeing + * the volume (if the component was responsible before). + */ Volume *release(); + /** + * Get the volume from this component. This method can be used by multiple threads at the same + * time. Therefore, the returned volume should not be modified. No ownership is transferred. + */ const Volume *get_for_read() const; + /** + * Get the volume from this component. This method can only be used when the component is + * mutable, i.e. it is not shared. The returned volume can be modified. No ownership is + * transferred. + */ Volume *get_for_write(); bool owns_direct_data() const override; diff --git a/source/blender/blenkernel/BKE_geometry_set_instances.hh b/source/blender/blenkernel/BKE_geometry_set_instances.hh index e5b28e4fbab..414cb750937 100644 --- a/source/blender/blenkernel/BKE_geometry_set_instances.hh +++ b/source/blender/blenkernel/BKE_geometry_set_instances.hh @@ -20,6 +20,9 @@ namespace blender::bke { +/** + * \note This doesn't extract instances from the "dupli" system for non-geometry-nodes instances. + */ GeometrySet object_get_evaluated_geometry_set(const Object &object); /** @@ -41,6 +44,16 @@ struct GeometryInstanceGroup { Vector transforms; }; +/** + * Return flattened vector of the geometry component's recursive instances. I.e. all collection + * instances and object instances will be expanded into the instances of their geometry components. + * Even the instances in those geometry components' will be included. + * + * \note For convenience (to avoid duplication in the caller), the returned vector also contains + * the argument geometry set. + * + * \note This doesn't extract instances from the "dupli" system for non-geometry-nodes instances. + */ void geometry_set_gather_instances(const GeometrySet &geometry_set, Vector &r_instance_groups); diff --git a/source/blender/blenkernel/BKE_gpencil.h b/source/blender/blenkernel/BKE_gpencil.h index b58317f4815..f1539c98522 100644 --- a/source/blender/blenkernel/BKE_gpencil.h +++ b/source/blender/blenkernel/BKE_gpencil.h @@ -86,65 +86,185 @@ struct bGPdata; /* ------------ Grease-Pencil API ------------------ */ +/* clean vertex groups weights */ void BKE_gpencil_free_point_weights(struct MDeformVert *dvert); void BKE_gpencil_free_stroke_weights(struct bGPDstroke *gps); void BKE_gpencil_free_stroke_editcurve(struct bGPDstroke *gps); +/* free stroke, doesn't unlink from any listbase */ void BKE_gpencil_free_stroke(struct bGPDstroke *gps); +/* Free strokes belonging to a gp-frame */ bool BKE_gpencil_free_strokes(struct bGPDframe *gpf); +/* Free all of a gp-layer's frames */ void BKE_gpencil_free_frames(struct bGPDlayer *gpl); +/* Free all of the gp-layers for a viewport (list should be &gpd->layers or so) */ void BKE_gpencil_free_layers(struct ListBase *list); +/** Free (or release) any data used by this grease pencil (does not free the gpencil itself). */ void BKE_gpencil_free_data(struct bGPdata *gpd, bool free_all); +/** + * Delete grease pencil evaluated data + * \param gpd_eval: Grease pencil data-block + */ void BKE_gpencil_eval_delete(struct bGPdata *gpd_eval); void BKE_gpencil_free_layer_masks(struct bGPDlayer *gpl); +/** + * Tag data-block for depsgraph update. + * Wrapper to avoid include Depsgraph tag functions in other modules. + * \param gpd: Grease pencil data-block. + */ void BKE_gpencil_tag(struct bGPdata *gpd); void BKE_gpencil_batch_cache_dirty_tag(struct bGPdata *gpd); void BKE_gpencil_batch_cache_free(struct bGPdata *gpd); +/** + * Ensure selection status of stroke is in sync with its points. + * \param gps: Grease pencil stroke + */ void BKE_gpencil_stroke_sync_selection(struct bGPdata *gpd, struct bGPDstroke *gps); void BKE_gpencil_curve_sync_selection(struct bGPdata *gpd, struct bGPDstroke *gps); +/* Assign unique stroke ID for selection. */ void BKE_gpencil_stroke_select_index_set(struct bGPdata *gpd, struct bGPDstroke *gps); +/* Reset unique stroke ID for selection. */ void BKE_gpencil_stroke_select_index_reset(struct bGPDstroke *gps); +/** + * Add a new gp-frame to the given layer. + * \param gpl: Grease pencil layer + * \param cframe: Frame number + * \return Pointer to new frame + */ struct bGPDframe *BKE_gpencil_frame_addnew(struct bGPDlayer *gpl, int cframe); +/** + * Add a copy of the active gp-frame to the given layer. + * \param gpl: Grease pencil layer + * \param cframe: Frame number + * \return Pointer to new frame + */ struct bGPDframe *BKE_gpencil_frame_addcopy(struct bGPDlayer *gpl, int cframe); +/** + * Add a new gp-layer and make it the active layer. + * \param gpd: Grease pencil data-block + * \param name: Name of the layer + * \param setactive: Set as active + * \param add_to_header: Used to force the layer added at header + * \return Pointer to new layer + */ struct bGPDlayer *BKE_gpencil_layer_addnew(struct bGPdata *gpd, const char *name, const bool setactive, const bool add_to_header); +/** + * Add a new grease pencil data-block. + * \param bmain: Main pointer + * \param name: Name of the datablock + * \return Pointer to new data-block + */ struct bGPdata *BKE_gpencil_data_addnew(struct Main *bmain, const char name[]); +/** + * Make a copy of a given gpencil frame. + * \param gpf_src: Source grease pencil frame + * \return Pointer to new frame + */ struct bGPDframe *BKE_gpencil_frame_duplicate(const struct bGPDframe *gpf_src, const bool dup_strokes); +/** + * Make a copy of a given gpencil layer. + * \param gpl_src: Source grease pencil layer + * \return Pointer to new layer + */ struct bGPDlayer *BKE_gpencil_layer_duplicate(const struct bGPDlayer *gpl_src, const bool dup_frames, const bool dup_strokes); +/** + * Make a copy of a given gpencil layer settings. + */ void BKE_gpencil_layer_copy_settings(const struct bGPDlayer *gpl_src, struct bGPDlayer *gpl_dst); +/** + * Make a copy of strokes between gpencil frames. + * \param gpf_src: Source grease pencil frame + * \param gpf_dst: Destination grease pencil frame + */ void BKE_gpencil_frame_copy_strokes(struct bGPDframe *gpf_src, struct bGPDframe *gpf_dst); +/* Create a hash with the list of selected frame number. */ void BKE_gpencil_frame_selected_hash(struct bGPdata *gpd, struct GHash *r_list); +/* Make a copy of a given gpencil stroke editcurve */ struct bGPDcurve *BKE_gpencil_stroke_curve_duplicate(struct bGPDcurve *gpc_src); +/** + * Make a copy of a given grease-pencil stroke. + * \param gps_src: Source grease pencil strokes. + * \param dup_points: Duplicate points data. + * \param dup_curve: Duplicate curve data. + * \return Pointer to new stroke. + */ struct bGPDstroke *BKE_gpencil_stroke_duplicate(struct bGPDstroke *gps_src, const bool dup_points, const bool dup_curve); +/** + * Make a copy of a given gpencil data-block. + * + * XXX: Should this be deprecated? + */ struct bGPdata *BKE_gpencil_data_duplicate(struct Main *bmain, const struct bGPdata *gpd, bool internal_copy); +/** + * Delete the last stroke of the given frame. + * \param gpl: Grease pencil layer + * \param gpf: Grease pencil frame + */ void BKE_gpencil_frame_delete_laststroke(struct bGPDlayer *gpl, struct bGPDframe *gpf); /* materials */ +/** + * Reassign strokes using a material. + * \param gpd: Grease pencil data-block + * \param totcol: Total materials + * \param index: Index of the material + */ void BKE_gpencil_material_index_reassign(struct bGPdata *gpd, int totcol, int index); +/** + * Remove strokes using a material. + * \param gpd: Grease pencil data-block + * \param index: Index of the material + * \return True if removed + */ bool BKE_gpencil_material_index_used(struct bGPdata *gpd, int index); +/** + * Remap material + * \param gpd: Grease pencil data-block + * \param remap: Remap index + * \param remap_len: Remap length + */ void BKE_gpencil_material_remap(struct bGPdata *gpd, const unsigned int *remap, unsigned int remap_len); +/** + * Load a table with material conversion index for merged materials. + * \param ob: Grease pencil object. + * \param hue_threshold: Threshold for Hue. + * \param sat_threshold: Threshold for Saturation. + * \param val_threshold: Threshold for Value. + * \param r_mat_table: return material table. + * \return True if done. + */ bool BKE_gpencil_merge_materials_table_get(struct Object *ob, const float hue_threshold, const float sat_threshold, const float val_threshold, struct GHash *r_mat_table); +/** + * Merge similar materials + * \param ob: Grease pencil object + * \param hue_threshold: Threshold for Hue + * \param sat_threshold: Threshold for Saturation + * \param val_threshold: Threshold for Value + * \param r_removed: Number of materials removed + * \return True if done + */ bool BKE_gpencil_merge_materials(struct Object *ob, const float hue_threshold, const float sat_threshold, @@ -152,12 +272,42 @@ bool BKE_gpencil_merge_materials(struct Object *ob, int *r_removed); /* statistics functions */ +/** + * Calc grease pencil statistics functions. + * \param gpd: Grease pencil data-block + */ void BKE_gpencil_stats_update(struct bGPdata *gpd); +/** + * Create a new stroke, with pre-allocated data buffers. + * \param mat_idx: Index of the material + * \param totpoints: Total points + * \param thickness: Stroke thickness + * \return Pointer to new stroke + */ struct bGPDstroke *BKE_gpencil_stroke_new(int mat_idx, int totpoints, short thickness); +/** + * Create a new stroke and add to frame. + * \param gpf: Grease pencil frame + * \param mat_idx: Material index + * \param totpoints: Total points + * \param thickness: Stroke thickness + * \param insert_at_head: Add to the head of the strokes list + * \return Pointer to new stroke + */ struct bGPDstroke *BKE_gpencil_stroke_add( struct bGPDframe *gpf, int mat_idx, int totpoints, short thickness, const bool insert_at_head); +/** + * Add a stroke and copy the temporary drawing color value + * from one of the existing stroke. + * \param gpf: Grease pencil frame + * \param existing: Stroke with the style to copy + * \param mat_idx: Material index + * \param totpoints: Total points + * \param thickness: Stroke thickness + * \return Pointer to new stroke + */ struct bGPDstroke *BKE_gpencil_stroke_add_existing_style(struct bGPDframe *gpf, struct bGPDstroke *existing, int mat_idx, @@ -170,6 +320,11 @@ struct bGPDcurve *BKE_gpencil_stroke_editcurve_new(const int tot_curve_points); #define GPENCIL_ALPHA_OPACITY_THRESH 0.001f #define GPENCIL_STRENGTH_MIN 0.003f +/** + * Check if the given layer is able to be edited or not. + * \param gpl: Grease pencil layer + * \return True if layer is editable + */ bool BKE_gpencil_layer_is_editable(const struct bGPDlayer *gpl); /* How gpencil_layer_getframe() should behave when there @@ -185,28 +340,121 @@ typedef enum eGP_GetFrame_Mode { GP_GETFRAME_ADD_COPY = 2, } eGP_GetFrame_Mode; +/** + * Get the appropriate gp-frame from a given layer + * - this sets the layer's actframe var (if allowed to) + * - extension beyond range (if first gp-frame is after all frame in interest and cannot add) + * + * \param gpl: Grease pencil layer + * \param cframe: Frame number + * \param addnew: Add option + * \return Pointer to new frame + */ struct bGPDframe *BKE_gpencil_layer_frame_get(struct bGPDlayer *gpl, int cframe, eGP_GetFrame_Mode addnew); +/** + * Look up the gp-frame on the requested frame number, but don't add a new one. + * \param gpl: Grease pencil layer + * \param cframe: Frame number + * \return Pointer to frame + */ struct bGPDframe *BKE_gpencil_layer_frame_find(struct bGPDlayer *gpl, int cframe); +/** + * Delete the given frame from a layer. + * \param gpl: Grease pencil layer + * \param gpf: Grease pencil frame + * \return True if delete was done + */ bool BKE_gpencil_layer_frame_delete(struct bGPDlayer *gpl, struct bGPDframe *gpf); +/** + * Get layer by name + * \param gpd: Grease pencil data-block + * \param name: Layer name + * \return Pointer to layer + */ struct bGPDlayer *BKE_gpencil_layer_named_get(struct bGPdata *gpd, const char *name); +/** + * Get the active grease pencil layer for editing. + * \param gpd: Grease pencil data-block + * \return Pointer to layer + */ struct bGPDlayer *BKE_gpencil_layer_active_get(struct bGPdata *gpd); +/** + * Set active grease pencil layer. + * \param gpd: Grease pencil data-block + * \param active: Grease pencil layer to set as active + */ void BKE_gpencil_layer_active_set(struct bGPdata *gpd, struct bGPDlayer *active); +/** + * Delete grease pencil layer. + * \param gpd: Grease pencil data-block + * \param gpl: Grease pencil layer + */ void BKE_gpencil_layer_delete(struct bGPdata *gpd, struct bGPDlayer *gpl); +/** + * Set locked layers for autolock mode. + * \param gpd: Grease pencil data-block + * \param unlock: Unlock flag + */ void BKE_gpencil_layer_autolock_set(struct bGPdata *gpd, const bool unlock); +/** + * Add grease pencil mask layer. + * \param gpl: Grease pencil layer + * \param name: Name of the mask + * \return Pointer to new mask layer + */ struct bGPDlayer_Mask *BKE_gpencil_layer_mask_add(struct bGPDlayer *gpl, const char *name); +/** + * Remove grease pencil mask layer. + * \param gpl: Grease pencil layer + * \param mask: Grease pencil mask layer + */ void BKE_gpencil_layer_mask_remove(struct bGPDlayer *gpl, struct bGPDlayer_Mask *mask); +/** + * Remove any reference to mask layer. + * \param gpd: Grease pencil data-block + * \param name: Name of the mask layer + */ void BKE_gpencil_layer_mask_remove_ref(struct bGPdata *gpd, const char *name); +/** + * Get mask layer by name. + * \param gpl: Grease pencil layer + * \param name: Mask name + * \return Pointer to mask layer + */ struct bGPDlayer_Mask *BKE_gpencil_layer_mask_named_get(struct bGPDlayer *gpl, const char *name); +/** + * Sort grease pencil mask layers. + * \param gpd: Grease pencil data-block + * \param gpl: Grease pencil layer + */ void BKE_gpencil_layer_mask_sort(struct bGPdata *gpd, struct bGPDlayer *gpl); +/** + * Sort all grease pencil mask layer. + * \param gpd: Grease pencil data-block + */ void BKE_gpencil_layer_mask_sort_all(struct bGPdata *gpd); +/** + * Make a copy of a given gpencil mask layers. + */ void BKE_gpencil_layer_mask_copy(const struct bGPDlayer *gpl_src, struct bGPDlayer *gpl_dst); +/** + * Clean any invalid mask layer. + */ void BKE_gpencil_layer_mask_cleanup(struct bGPdata *gpd, struct bGPDlayer *gpl); +/** + * Clean any invalid mask layer for all layers. + */ void BKE_gpencil_layer_mask_cleanup_all_layers(struct bGPdata *gpd); +/** + * Sort grease pencil frames. + * \param gpl: Grease pencil layer + * \param r_has_duplicate_frames: Duplicated frames flag + */ void BKE_gpencil_layer_frames_sort(struct bGPDlayer *gpl, bool *r_has_duplicate_frames); struct bGPDlayer *BKE_gpencil_layer_get_by_name(struct bGPdata *gpd, @@ -214,14 +462,43 @@ struct bGPDlayer *BKE_gpencil_layer_get_by_name(struct bGPdata *gpd, int first_if_not_found); /* Brush */ +/** + * Get grease pencil material from brush. + * \param brush: Brush + * \return Pointer to material + */ struct Material *BKE_gpencil_brush_material_get(struct Brush *brush); +/** + * Set grease pencil brush material. + * \param brush: Brush + * \param ma: Material + */ void BKE_gpencil_brush_material_set(struct Brush *brush, struct Material *material); /* Object */ +/** + * Get active color, and add all default settings if we don't find anything. + * \param ob: Grease pencil object + * \return Material pointer + */ struct Material *BKE_gpencil_object_material_ensure_active(struct Object *ob); +/** + * Adds the pinned material to the object if necessary. + * \param bmain: Main pointer + * \param ob: Grease pencil object + * \param brush: Brush + * \return Pointer to material + */ struct Material *BKE_gpencil_object_material_ensure_from_brush(struct Main *bmain, struct Object *ob, struct Brush *brush); +/** + * Assigns the material to object (if not already present) and returns its index (mat_nr). + * \param bmain: Main pointer + * \param ob: Grease pencil object + * \param material: Material + * \return Index of the material + */ int BKE_gpencil_object_material_ensure(struct Main *bmain, struct Object *ob, struct Material *material); @@ -230,41 +507,140 @@ struct Material *BKE_gpencil_object_material_ensure_by_name(struct Main *bmain, const char *name, int *r_index); +/** + * Creates a new grease-pencil material and assigns it to object. + * \param bmain: Main pointer + * \param ob: Grease pencil object + * \param name: Material name + * \param r_index: value is set to zero based index of the new material if \a r_index is not NULL. + * \return Material pointer. + */ struct Material *BKE_gpencil_object_material_new(struct Main *bmain, struct Object *ob, const char *name, int *r_index); +/** + * Get material index (0-based like mat_nr not actcol). + * \param ob: Grease pencil object + * \param ma: Material + * \return Index of the material + */ int BKE_gpencil_object_material_index_get(struct Object *ob, struct Material *ma); int BKE_gpencil_object_material_index_get_by_name(struct Object *ob, const char *name); +/** + * Returns the material for a brush with respect to its pinned state. + * \param ob: Grease pencil object + * \param brush: Brush + * \return Material pointer + */ struct Material *BKE_gpencil_object_material_from_brush_get(struct Object *ob, struct Brush *brush); +/** + * Returns the material index for a brush with respect to its pinned state. + * \param ob: Grease pencil object + * \param brush: Brush + * \return Material index. + */ int BKE_gpencil_object_material_get_index_from_brush(struct Object *ob, struct Brush *brush); +/** + * Guaranteed to return a material assigned to object. Returns never NULL. + * \param bmain: Main pointer + * \param ob: Grease pencil object + * \return Material pointer. + */ struct Material *BKE_gpencil_object_material_ensure_from_active_input_toolsettings( struct Main *bmain, struct Object *ob, struct ToolSettings *ts); +/** + * Guaranteed to return a material assigned to object. Returns never NULL. + * \param bmain: Main pointer + * \param ob: Grease pencil object. + * \param brush: Brush + * \return Material pointer + */ struct Material *BKE_gpencil_object_material_ensure_from_active_input_brush(struct Main *bmain, struct Object *ob, struct Brush *brush); +/** + * Guaranteed to return a material assigned to object. Returns never NULL. + * Only use this for materials unrelated to user input. + * \param ob: Grease pencil object + * \return Material pointer + */ struct Material *BKE_gpencil_object_material_ensure_from_active_input_material(struct Object *ob); +/** + * Check if stroke has any point selected + * \param gps: Grease pencil stroke + * \return True if selected + */ bool BKE_gpencil_stroke_select_check(const struct bGPDstroke *gps); /* vertex groups */ +/** + * Ensure stroke has vertex group. + * \param gps: Grease pencil stroke + */ void BKE_gpencil_dvert_ensure(struct bGPDstroke *gps); +/** + * Remove a vertex group. + * \param ob: Grease pencil object + * \param defgroup: deform group + */ void BKE_gpencil_vgroup_remove(struct Object *ob, struct bDeformGroup *defgroup); +/** + * Make a copy of a given gpencil weights. + * \param gps_src: Source grease pencil stroke + * \param gps_dst: Destination grease pencil stroke + */ void BKE_gpencil_stroke_weights_duplicate(struct bGPDstroke *gps_src, struct bGPDstroke *gps_dst); /* Set active frame by layer. */ +/** + * Set current grease pencil active frame. + * \param depsgraph: Current depsgraph + * \param gpd: Grease pencil data-block. + */ void BKE_gpencil_frame_active_set(struct Depsgraph *depsgraph, struct bGPdata *gpd); +/** + * Get range of selected frames in layer. + * Always the active frame is considered as selected, so if no more selected the range + * will be equal to the current active frame. + * \param gpl: Layer. + * \param r_initframe: Number of first selected frame. + * \param r_endframe: Number of last selected frame. + */ void BKE_gpencil_frame_range_selected(struct bGPDlayer *gpl, int *r_initframe, int *r_endframe); +/** + * Get Falloff factor base on frame range + * \param gpf: Frame. + * \param actnum: Number of active frame in layer. + * \param f_init: Number of first selected frame. + * \param f_end: Number of last selected frame. + * \param cur_falloff: Curve with falloff factors. + */ float BKE_gpencil_multiframe_falloff_calc( struct bGPDframe *gpf, int actnum, int f_init, int f_end, struct CurveMapping *cur_falloff); +/** + * Create a default palette. + * \param bmain: Main pointer + * \param scene: Scene + */ void BKE_gpencil_palette_ensure(struct Main *bmain, struct Scene *scene); +/** + * Create grease pencil strokes from image + * \param sima: Image + * \param gpd: Grease pencil data-block + * \param gpf: Grease pencil frame + * \param size: Size + * \param mask: Mask + * \return True if done + */ bool BKE_gpencil_from_image(struct SpaceImage *sima, struct bGPdata *gpd, struct bGPDframe *gpf, @@ -272,7 +648,9 @@ bool BKE_gpencil_from_image(struct SpaceImage *sima, const bool mask); /* Iterators */ -/* frame & stroke are NULL if it is a layer callback. */ +/** + * Frame & stroke are NULL if it is a layer callback. + */ typedef void (*gpIterCb)(struct bGPDlayer *layer, struct bGPDframe *frame, struct bGPDstroke *stroke, @@ -294,17 +672,45 @@ void BKE_gpencil_visible_stroke_advanced_iter(struct ViewLayer *view_layer, extern void (*BKE_gpencil_batch_cache_dirty_tag_cb)(struct bGPdata *gpd); extern void (*BKE_gpencil_batch_cache_free_cb)(struct bGPdata *gpd); +/** + * Update original pointers in evaluated frame. + * \param gpf_orig: Original grease-pencil frame. + * \param gpf_eval: Evaluated grease pencil frame. + */ void BKE_gpencil_frame_original_pointers_update(const struct bGPDframe *gpf_orig, const struct bGPDframe *gpf_eval); +/** + * Update pointers of eval data to original data to keep references. + * \param ob_orig: Original grease pencil object + * \param ob_eval: Evaluated grease pencil object + */ void BKE_gpencil_update_orig_pointers(const struct Object *ob_orig, const struct Object *ob_eval); +/** + * Get parent matrix, including layer parenting. + * \param depsgraph: Depsgraph + * \param obact: Grease pencil object + * \param gpl: Grease pencil layer + * \param diff_mat: Result parent matrix + */ void BKE_gpencil_layer_transform_matrix_get(const struct Depsgraph *depsgraph, struct Object *obact, struct bGPDlayer *gpl, float diff_mat[4][4]); +/** + * Update parent matrix and local transforms. + * \param depsgraph: Depsgraph + * \param ob: Grease pencil object + */ void BKE_gpencil_update_layer_transforms(const struct Depsgraph *depsgraph, struct Object *ob); +/** + * Find material by name prefix. + * \param ob: Object pointer + * \param name_prefix: Prefix name of the material + * \return Index + */ int BKE_gpencil_material_find_index_by_name_prefix(struct Object *ob, const char *name_prefix); void BKE_gpencil_blend_read_data(struct BlendDataReader *reader, struct bGPdata *gpd); diff --git a/source/blender/blenkernel/BKE_gpencil_curve.h b/source/blender/blenkernel/BKE_gpencil_curve.h index 9cbe67af9c1..044e2ff2336 100644 --- a/source/blender/blenkernel/BKE_gpencil_curve.h +++ b/source/blender/blenkernel/BKE_gpencil_curve.h @@ -35,6 +35,17 @@ struct bGPDlayer; struct bGPDstroke; struct bGPdata; +/** + * Convert a curve object to grease pencil stroke. + * + * \param bmain: Main thread pointer + * \param scene: Original scene. + * \param ob_gp: Grease pencil object to add strokes. + * \param ob_cu: Curve to convert. + * \param use_collections: Create layers using collection names. + * \param scale_thickness: Scale thickness factor. + * \param sample: Sample distance, zero to disable. + */ void BKE_gpencil_convert_curve(struct Main *bmain, struct Scene *scene, struct Object *ob_gp, @@ -43,24 +54,42 @@ void BKE_gpencil_convert_curve(struct Main *bmain, const float scale_thickness, const float sample); +/** + * Creates a bGPDcurve by doing a cubic curve fitting on the grease pencil stroke points. + */ struct bGPDcurve *BKE_gpencil_stroke_editcurve_generate(struct bGPDstroke *gps, const float error_threshold, const float corner_angle, const float stroke_radius); +/** + * Updates the edit-curve for a stroke. Frees the old curve if one exists and generates a new one. + */ void BKE_gpencil_stroke_editcurve_update(struct bGPdata *gpd, struct bGPDlayer *gpl, struct bGPDstroke *gps); +/** + * Sync the selection from stroke to edit-curve. + */ void BKE_gpencil_editcurve_stroke_sync_selection(struct bGPdata *gpd, struct bGPDstroke *gps, struct bGPDcurve *gpc); +/** + * Sync the selection from edit-curve to stroke. + */ void BKE_gpencil_stroke_editcurve_sync_selection(struct bGPdata *gpd, struct bGPDstroke *gps, struct bGPDcurve *gpc); void BKE_gpencil_strokes_selected_update_editcurve(struct bGPdata *gpd); void BKE_gpencil_strokes_selected_sync_selection_editcurve(struct bGPdata *gpd); +/** + * Recalculate stroke points with the edit-curve of the stroke. + */ void BKE_gpencil_stroke_update_geometry_from_editcurve(struct bGPDstroke *gps, const uint resolution, const bool is_adaptive); +/** + * Recalculate the handles of the edit curve of a grease pencil stroke. + */ void BKE_gpencil_editcurve_recalculate_handles(struct bGPDstroke *gps); void BKE_gpencil_editcurve_subdivide(struct bGPDstroke *gps, const int cuts); diff --git a/source/blender/blenkernel/BKE_gpencil_geom.h b/source/blender/blenkernel/BKE_gpencil_geom.h index 41b1bba10ba..df6dd6eab92 100644 --- a/source/blender/blenkernel/BKE_gpencil_geom.h +++ b/source/blender/blenkernel/BKE_gpencil_geom.h @@ -38,38 +38,130 @@ struct bGPDspoint; struct bGPDstroke; struct bGPdata; -/* Object boundbox. */ +/* Object bound-box. */ + +/** + * Get min/max bounds of all strokes in grease pencil data-block. + * \param gpd: Grease pencil data-block + * \param r_min: Result minimum coordinates + * \param r_max: Result maximum coordinates + * \return True if it was possible to calculate + */ bool BKE_gpencil_data_minmax(const struct bGPdata *gpd, float r_min[3], float r_max[3]); +/** + * Get min/max coordinate bounds for single stroke. + * \param gps: Grease pencil stroke + * \param use_select: Include only selected points + * \param r_min: Result minimum coordinates + * \param r_max: Result maximum coordinates + * \return True if it was possible to calculate + */ bool BKE_gpencil_stroke_minmax(const struct bGPDstroke *gps, const bool use_select, float r_min[3], float r_max[3]); +/** + * Get grease pencil object bounding box. + * \param ob: Grease pencil object + * \return Bounding box + */ struct BoundBox *BKE_gpencil_boundbox_get(struct Object *ob); +/** + * Compute center of bounding box. + * \param gpd: Grease pencil data-block + * \param r_centroid: Location of the center + */ void BKE_gpencil_centroid_3d(struct bGPdata *gpd, float r_centroid[3]); +/** + * Compute stroke bounding box. + * \param gps: Grease pencil Stroke + */ void BKE_gpencil_stroke_boundingbox_calc(struct bGPDstroke *gps); -/* stroke geometry utilities */ +/* Stroke geometry utilities. */ + +/** + * Calculate stroke normals. + * \param gps: Grease pencil stroke + * \param r_normal: Return Normal vector normalized + */ void BKE_gpencil_stroke_normal(const struct bGPDstroke *gps, float r_normal[3]); +/** + * Reduce a series of points to a simplified version, + * but maintains the general shape of the series. + * + * Ramer - Douglas - Peucker algorithm + * by http://en.wikipedia.org/wiki/Ramer-Douglas-Peucker_algorithm + * \param gpd: Grease pencil data-block + * \param gps: Grease pencil stroke + * \param epsilon: Epsilon value to define precision of the algorithm + */ void BKE_gpencil_stroke_simplify_adaptive(struct bGPdata *gpd, struct bGPDstroke *gps, float epsilon); +/** + * Simplify alternate vertex of stroke except extremes. + * \param gpd: Grease pencil data-block + * \param gps: Grease pencil stroke + */ void BKE_gpencil_stroke_simplify_fixed(struct bGPdata *gpd, struct bGPDstroke *gps); +/** + * Subdivide a stroke + * \param gpd: Grease pencil data-block + * \param gps: Stroke + * \param level: Level of subdivision + * \param type: Type of subdivision + */ void BKE_gpencil_stroke_subdivide(struct bGPdata *gpd, struct bGPDstroke *gps, int level, int type); +/** + * Trim stroke to the first intersection or loop. + * \param gps: Stroke data + */ bool BKE_gpencil_stroke_trim(struct bGPdata *gpd, struct bGPDstroke *gps); +/** + * Reduce a series of points when the distance is below a threshold. + * Special case for first and last points (both are kept) for other points, + * the merge point always is at first point. + * + * \param gpd: Grease pencil data-block. + * \param gpf: Grease Pencil frame. + * \param gps: Grease Pencil stroke. + * \param threshold: Distance between points. + * \param use_unselected: Set to true to analyze all stroke and not only selected points. + */ void BKE_gpencil_stroke_merge_distance(struct bGPdata *gpd, struct bGPDframe *gpf, struct bGPDstroke *gps, const float threshold, const bool use_unselected); +/** + * Get points of stroke always flat to view not affected + * by camera view or view position. + * \param points: Array of grease pencil points (3D) + * \param totpoints: Total of points + * \param points2d: Result array of 2D points + * \param r_direction: Return Concave (-1), Convex (1), or Auto-detect (0) + */ void BKE_gpencil_stroke_2d_flat(const struct bGPDspoint *points, int totpoints, float (*points2d)[2], int *r_direction); +/** + * Get points of stroke always flat to view not affected by camera view or view position + * using another stroke as reference. + * \param ref_points: Array of reference points (3D) + * \param ref_totpoints: Total reference points + * \param points: Array of points to flat (3D) + * \param totpoints: Total points + * \param points2d: Result array of 2D points + * \param scale: Scale factor + * \param r_direction: Return Concave (-1), Convex (1), or Auto-detect (0) + */ void BKE_gpencil_stroke_2d_flat_ref(const struct bGPDspoint *ref_points, int ref_totpoints, const struct bGPDspoint *points, @@ -77,10 +169,28 @@ void BKE_gpencil_stroke_2d_flat_ref(const struct bGPDspoint *ref_points, float (*points2d)[2], const float scale, int *r_direction); +/** + * Triangulate stroke to generate data for filling areas. + * \param gps: Grease pencil stroke + */ void BKE_gpencil_stroke_fill_triangulate(struct bGPDstroke *gps); +/** + * Recalc all internal geometry data for the stroke + * \param gpd: Grease pencil data-block + * \param gps: Grease pencil stroke + */ void BKE_gpencil_stroke_geometry_update(struct bGPdata *gpd, struct bGPDstroke *gps); +/** + * Update Stroke UV data. + * \param gps: Grease pencil stroke + */ void BKE_gpencil_stroke_uv_update(struct bGPDstroke *gps); +/** + * Apply grease pencil Transforms. + * \param gpd: Grease pencil data-block + * \param mat: Transformation matrix + */ void BKE_gpencil_transform(struct bGPdata *gpd, const float mat[4][4]); typedef struct GPencilPointCoordinates { @@ -90,27 +200,89 @@ typedef struct GPencilPointCoordinates { float pressure; } GPencilPointCoordinates; +/** + * \note Used for "move only origins" in object_data_transform.c. + */ int BKE_gpencil_stroke_point_count(const struct bGPdata *gpd); +/** + * \note Used for "move only origins" in object_data_transform.c. + */ void BKE_gpencil_point_coords_get(struct bGPdata *gpd, GPencilPointCoordinates *elem_data); +/** + * \note Used for "move only origins" in object_data_transform.c. + */ void BKE_gpencil_point_coords_apply(struct bGPdata *gpd, const GPencilPointCoordinates *elem_data); +/** + * \note Used for "move only origins" in object_data_transform.c. + */ void BKE_gpencil_point_coords_apply_with_mat4(struct bGPdata *gpd, const GPencilPointCoordinates *elem_data, const float mat[4][4]); +/** + * Resample a stroke + * \param gpd: Grease pencil data-block + * \param gps: Stroke to sample + * \param dist: Distance of one segment + */ bool BKE_gpencil_stroke_sample(struct bGPdata *gpd, struct bGPDstroke *gps, const float dist, const bool select); +/** + * Apply smooth position to stroke point. + * \param gps: Stroke to smooth + * \param i: Point index + * \param inf: Amount of smoothing to apply + */ bool BKE_gpencil_stroke_smooth_point(struct bGPDstroke *gps, int i, float inf); +/** + * Apply smooth strength to stroke point. + * \param gps: Stroke to smooth + * \param point_index: Point index + * \param influence: Amount of smoothing to apply + */ bool BKE_gpencil_stroke_smooth_strength(struct bGPDstroke *gps, int point_index, float influence); +/** + * Apply smooth for thickness to stroke point (use pressure). + * \param gps: Stroke to smooth + * \param point_index: Point index + * \param influence: Amount of smoothing to apply + */ bool BKE_gpencil_stroke_smooth_thickness(struct bGPDstroke *gps, int point_index, float influence); +/** + * Apply smooth for UV rotation to stroke point (use pressure). + * \param gps: Stroke to smooth + * \param point_index: Point index + * \param influence: Amount of smoothing to apply + */ bool BKE_gpencil_stroke_smooth_uv(struct bGPDstroke *gps, int point_index, float influence); +/** + * Close grease pencil stroke. + * \param gps: Stroke to close + */ bool BKE_gpencil_stroke_close(struct bGPDstroke *gps); +/** + * Dissolve points in stroke. + * \param gpd: Grease pencil data-block + * \param gpf: Grease pencil frame + * \param gps: Grease pencil stroke + * \param tag: Type of tag for point + */ void BKE_gpencil_dissolve_points(struct bGPdata *gpd, struct bGPDframe *gpf, struct bGPDstroke *gps, const short tag); +/** + * Backbone stretch similar to Freestyle. + * \param gps: Stroke to sample. + * \param dist: Length of the added section. + * \param overshoot_fac: Relative length of the curve which is used to determine the extension. + * \param mode: Affect to Start, End or Both extremes (0->Both, 1->Start, 2->End). + * \param follow_curvature: True for approximating curvature of given overshoot. + * \param extra_point_count: When follow_curvature is true, use this amount of extra points. + */ bool BKE_gpencil_stroke_stretch(struct bGPDstroke *gps, const float dist, const float overshoot_fac, @@ -120,9 +292,20 @@ bool BKE_gpencil_stroke_stretch(struct bGPDstroke *gps, const float segment_influence, const float max_angle, const bool invert_curvature); +/** + * Trim stroke to needed segments. + * \param gps: Target stroke. + * \param index_from: the index of the first point to be used in the trimmed result. + * \param index_to: the index of the last point to be used in the trimmed result. + */ bool BKE_gpencil_stroke_trim_points(struct bGPDstroke *gps, const int index_from, const int index_to); +/** + * Split the given stroke into several new strokes, partitioning + * it based on whether the stroke points have a particular flag + * is set (e.g. #GP_SPOINT_SELECT in most cases, but not always). + */ struct bGPDstroke *BKE_gpencil_stroke_delete_tagged_points(struct bGPdata *gpd, struct bGPDframe *gpf, struct bGPDstroke *gps, @@ -138,33 +321,84 @@ void BKE_gpencil_curve_delete_tagged_points(struct bGPdata *gpd, struct bGPDcurve *gpc, int tag_flags); +/** + * Flip stroke. + */ void BKE_gpencil_stroke_flip(struct bGPDstroke *gps); +/** + * Split stroke. + * \param gpd: Grease pencil data-block. + * \param gpf: Grease pencil frame. + * \param gps: Grease pencil original stroke. + * \param before_index: Position of the point to split. + * \param remaining_gps: Secondary stroke after split. + * \return True if the split was done + */ bool BKE_gpencil_stroke_split(struct bGPdata *gpd, struct bGPDframe *gpf, struct bGPDstroke *gps, const int before_index, struct bGPDstroke **remaining_gps); +/** + * Shrink the stroke by length. + * \param gps: Stroke to shrink + * \param dist: delta length + * \param mode: 1->Start, 2->End + */ bool BKE_gpencil_stroke_shrink(struct bGPDstroke *gps, const float dist, const short mode); +/** + * Calculate grease pencil stroke length. + * \param gps: Grease pencil stroke. + * \param use_3d: Set to true to use 3D points. + * \return Length of the stroke. + */ float BKE_gpencil_stroke_length(const struct bGPDstroke *gps, bool use_3d); +/** Calculate grease pencil stroke length between points. */ float BKE_gpencil_stroke_segment_length(const struct bGPDstroke *gps, const int start_index, const int end_index, bool use_3d); +/** + * Set a random color to stroke using vertex color. + * \param gps: Stroke + */ void BKE_gpencil_stroke_set_random_color(struct bGPDstroke *gps); +/** + * Join two strokes using the shortest distance (reorder stroke if necessary). + */ void BKE_gpencil_stroke_join(struct bGPDstroke *gps_a, struct bGPDstroke *gps_b, const bool leave_gaps, const bool fit_thickness, const bool smooth); +/** + * Copy the stroke of the frame to all frames selected (except current). + */ void BKE_gpencil_stroke_copy_to_keyframes(struct bGPdata *gpd, struct bGPDlayer *gpl, struct bGPDframe *gpf, struct bGPDstroke *gps, const bool tail); +/** + * Convert a mesh object to grease pencil stroke. + * + * \param bmain: Main thread pointer. + * \param depsgraph: Original depsgraph. + * \param scene: Original scene. + * \param ob_gp: Grease pencil object to add strokes. + * \param ob_mesh: Mesh to convert. + * \param angle: Limit angle to consider a edge-loop ends. + * \param thickness: Thickness of the strokes. + * \param offset: Offset along the normals. + * \param matrix: Transformation matrix. + * \param frame_offset: Destination frame number offset. + * \param use_seams: Only export seam edges. + * \param use_faces: Export faces as filled strokes. + */ bool BKE_gpencil_convert_mesh(struct Main *bmain, struct Depsgraph *depsgraph, struct Scene *scene, @@ -179,24 +413,56 @@ bool BKE_gpencil_convert_mesh(struct Main *bmain, const bool use_faces, const bool use_vgroups); +/** + * Subdivide the grease pencil stroke so the number of points is target_number. + * Does not change the shape of the stroke. The new points will be distributed as + * uniformly as possible by repeatedly subdividing the current longest edge. + * + * \param gps: The stroke to be up-sampled. + * \param target_number: The number of points the up-sampled stroke should have. + * \param select: Select/Deselect the stroke. + */ void BKE_gpencil_stroke_uniform_subdivide(struct bGPdata *gpd, struct bGPDstroke *gps, const uint32_t target_number, const bool select); +/** + * Stroke to view space + * Transforms a stroke to view space. + * This allows for manipulations in 2D but also easy conversion back to 3D. + * \note also takes care of parent space transform. + */ void BKE_gpencil_stroke_to_view_space(struct RegionView3D *rv3d, struct bGPDstroke *gps, const float diff_mat[4][4]); +/** + * Stroke from view space + * Transforms a stroke from view space back to world space. + * Inverse of #BKE_gpencil_stroke_to_view_space + * \note also takes care of parent space transform. + */ void BKE_gpencil_stroke_from_view_space(struct RegionView3D *rv3d, struct bGPDstroke *gps, const float diff_mat[4][4]); +/** + * Calculates the perimeter of a stroke projected from the view and returns it as a new stroke. + * \param subdivisions: Number of subdivisions for the start and end caps. + * \return: bGPDstroke pointer to stroke perimeter. + */ struct bGPDstroke *BKE_gpencil_stroke_perimeter_from_view(struct RegionView3D *rv3d, struct bGPdata *gpd, const struct bGPDlayer *gpl, struct bGPDstroke *gps, const int subdivisions, const float diff_mat[4][4]); +/** + * Get average pressure. + */ float BKE_gpencil_stroke_average_pressure_get(struct bGPDstroke *gps); +/** + * Check if the thickness of the stroke is constant. + */ bool BKE_gpencil_stroke_is_pressure_constant(struct bGPDstroke *gps); #ifdef __cplusplus } diff --git a/source/blender/blenkernel/BKE_gpencil_modifier.h b/source/blender/blenkernel/BKE_gpencil_modifier.h index 33524e47473..e7917ffa578 100644 --- a/source/blender/blenkernel/BKE_gpencil_modifier.h +++ b/source/blender/blenkernel/BKE_gpencil_modifier.h @@ -249,36 +249,114 @@ typedef struct GpencilModifierTypeInfo { #define GPENCIL_MODIFIER_TYPE_PANEL_PREFIX "MOD_PT_gpencil_" -/* Initialize modifier's global data (type info and some common global storage). */ +/** + * Initialize modifier's global data (type info and some common global storage). + */ void BKE_gpencil_modifier_init(void); +/** + * Get the idname of the modifier type's panel, which was defined in the #panelRegister callback. + * + * \param type: Type of modifier. + * \param r_idname: ID name. + */ void BKE_gpencil_modifierType_panel_id(GpencilModifierType type, char *r_idname); void BKE_gpencil_modifier_panel_expand(struct GpencilModifierData *md); +/** + * Get grease pencil modifier information. + * \param type: Type of modifier. + * \return Pointer to type + */ const GpencilModifierTypeInfo *BKE_gpencil_modifier_get_info(GpencilModifierType type); +/** + * Create new grease pencil modifier. + * \param type: Type of modifier. + * \return New modifier pointer. + */ struct GpencilModifierData *BKE_gpencil_modifier_new(int type); +/** + * Free grease pencil modifier data + * \param md: Modifier data. + * \param flag: Flags. + */ void BKE_gpencil_modifier_free_ex(struct GpencilModifierData *md, const int flag); +/** + * Free grease pencil modifier data + * \param md: Modifier data. + */ void BKE_gpencil_modifier_free(struct GpencilModifierData *md); +/* check unique name */ bool BKE_gpencil_modifier_unique_name(struct ListBase *modifiers, struct GpencilModifierData *gmd); +/** + * Check if grease pencil modifier depends on time. + * \param md: Modifier data. + * \return True if depends on time. + */ bool BKE_gpencil_modifier_depends_ontime(struct GpencilModifierData *md); struct GpencilModifierData *BKE_gpencil_modifiers_findby_type(struct Object *ob, GpencilModifierType type); +/** + * Find grease pencil modifier by name. + * \param ob: Grease pencil object. + * \param name: Name to find. + * \return Pointer to modifier. + */ struct GpencilModifierData *BKE_gpencil_modifiers_findby_name(struct Object *ob, const char *name); +/** + * Generic grease pencil modifier copy data. + * \param md_src: Source modifier data. + * \param md_dst: Target modifier data. + */ void BKE_gpencil_modifier_copydata_generic(const struct GpencilModifierData *md_src, struct GpencilModifierData *md_dst); +/** + * Copy grease pencil modifier data. + * \param md: Source modifier data. + * \param target: Target modifier data. + */ void BKE_gpencil_modifier_copydata(struct GpencilModifierData *md, struct GpencilModifierData *target); +/** + * Copy grease pencil modifier data. + * \param md: Source modifier data. + * \param target: Target modifier data. + * \param flag: Flags. + */ void BKE_gpencil_modifier_copydata_ex(struct GpencilModifierData *md, struct GpencilModifierData *target, const int flag); +/** + * Set grease pencil modifier error. + * \param md: Modifier data. + * \param _format: Format. + */ void BKE_gpencil_modifier_set_error(struct GpencilModifierData *md, const char *format, ...) ATTR_PRINTF_FORMAT(2, 3); +/** + * Link grease pencil modifier related IDs. + * \param ob: Grease pencil object. + * \param walk: Walk option. + * \param userData: User data. + */ void BKE_gpencil_modifiers_foreach_ID_link(struct Object *ob, GreasePencilIDWalkFunc walk, void *userData); +/** + * Link grease pencil modifier related Texts. + * \param ob: Grease pencil object. + * \param walk: Walk option. + * \param userData: User data. + */ void BKE_gpencil_modifiers_foreach_tex_link(struct Object *ob, GreasePencilTexWalkFunc walk, void *userData); +/** + * Check whether given modifier is not local (i.e. from linked data) when the object is a library + * override. + * + * \param gmd: May be NULL, in which case we consider it as a non-local modifier case. + */ bool BKE_gpencil_modifier_is_nonlocal_in_liboverride(const struct Object *ob, const struct GpencilModifierData *gmd); @@ -287,11 +365,30 @@ typedef struct GpencilVirtualModifierData { LatticeGpencilModifierData lmd; } GpencilVirtualModifierData; +/** + * This is to include things that are not modifiers in the evaluation of the modifier stack, + * for example parenting to an armature or lattice without having a real modifier. + */ struct GpencilModifierData *BKE_gpencil_modifiers_get_virtual_modifierlist( const struct Object *ob, struct GpencilVirtualModifierData *data); +/** + * Check if object has grease pencil Geometry modifiers. + * \param ob: Grease pencil object. + * \return True if exist. + */ bool BKE_gpencil_has_geometry_modifiers(struct Object *ob); +/** + * Check if object has grease pencil Time modifiers. + * \param ob: Grease pencil object. + * \return True if exist. + */ bool BKE_gpencil_has_time_modifiers(struct Object *ob); +/** + * Check if object has grease pencil transform stroke modifiers. + * \param ob: Grease pencil object. + * \return True if exist. + */ bool BKE_gpencil_has_transform_modifiers(struct Object *ob); /* Stores the maximum calculation range in the whole modifier stack for line art so the cache can @@ -310,21 +407,52 @@ void BKE_gpencil_set_lineart_modifier_limits(struct GpencilModifierData *md, bool BKE_gpencil_is_first_lineart_in_stack(const struct Object *ob, const struct GpencilModifierData *md); +/** + * Init grease pencil lattice deform data. + * \param ob: Grease pencil object. + */ void BKE_gpencil_lattice_init(struct Object *ob); +/** + * Clear grease pencil lattice deform data. + * \param ob: Grease pencil object. + */ void BKE_gpencil_lattice_clear(struct Object *ob); +/** + * Calculate grease-pencil modifiers. + * \param depsgraph: Current depsgraph. + * \param scene: Current scene. + * \param ob: Grease pencil object. + */ void BKE_gpencil_modifiers_calc(struct Depsgraph *depsgraph, struct Scene *scene, struct Object *ob); +/** + * Prepare grease pencil eval data for modifiers + * \param depsgraph: Current depsgraph. + * \param scene: Current scene. + * \param ob: Grease pencil object. + */ void BKE_gpencil_prepare_eval_data(struct Depsgraph *depsgraph, struct Scene *scene, struct Object *ob); +/** + * Get the current frame re-timed with time modifiers. + * \param depsgraph: Current depsgraph. + * \param scene: Current scene. + * \param ob: Grease pencil object. + * \param gpl: Grease pencil layer. + * \return New frame number. + */ struct bGPDframe *BKE_gpencil_frame_retime_get(struct Depsgraph *depsgraph, struct Scene *scene, struct Object *ob, struct bGPDlayer *gpl); +/** + * Get Time modifier frame number. + */ int BKE_gpencil_time_modifier_cfra(struct Depsgraph *depsgraph, struct Scene *scene, struct Object *ob, diff --git a/source/blender/blenkernel/BKE_icons.h b/source/blender/blenkernel/BKE_icons.h index 28a6f837f61..c96a37e0d09 100644 --- a/source/blender/blenkernel/BKE_icons.h +++ b/source/blender/blenkernel/BKE_icons.h @@ -97,76 +97,135 @@ enum eIconSizes; void BKE_icons_init(int first_dyn_id); -/* return icon id for library object or create new icon if not found */ +/** + * Return icon id for library object or create new icon if not found. + */ int BKE_icon_id_ensure(struct ID *id); -/* return icon id for Grease Pencil layer (color preview) or create new icon if not found */ +/** + * Return icon id for Grease Pencil layer (color preview) or create new icon if not found. + */ int BKE_icon_gplayer_color_ensure(struct bGPDlayer *gpl); +/** + * Return icon id of given preview, or create new icon if not found. + */ int BKE_icon_preview_ensure(struct ID *id, struct PreviewImage *preview); +/** + * Create an icon as owner or \a ibuf. The icon-ID is not stored in \a ibuf, + * it needs to be stored separately. + * \note Transforms ownership of \a ibuf to the newly created icon. + */ int BKE_icon_imbuf_create(struct ImBuf *ibuf) ATTR_WARN_UNUSED_RESULT; struct ImBuf *BKE_icon_imbuf_get_buffer(int icon_id) ATTR_WARN_UNUSED_RESULT; -/* retrieve icon for id */ +/** + * Retrieve icon for id. + */ struct Icon *BKE_icon_get(const int icon_id); -/* set icon for id if not already defined */ -/* used for inserting the internal icons */ +/** + * Set icon for id if not already defined. + * Used for inserting the internal icons. + */ void BKE_icon_set(const int icon_id, struct Icon *icon); -/* remove icon and free data if library object becomes invalid */ +/** + * Remove icon and free data if library object becomes invalid. + */ void BKE_icon_id_delete(struct ID *id); +/** + * Remove icon and free data. + */ bool BKE_icon_delete(const int icon_id); bool BKE_icon_delete_unmanaged(const int icon_id); -/* report changes - icon needs to be recalculated */ +/** + * Report changes - icon needs to be recalculated. + */ void BKE_icon_changed(const int icon_id); -/* free all icons */ +/** + * Free all icons. + */ void BKE_icons_free(void); -/* free all icons marked for deferred deletion */ +/** + * Free all icons marked for deferred deletion. + */ void BKE_icons_deferred_free(void); -/* free the preview image for use in list */ +/** + * Free the preview image for use in list. + */ void BKE_previewimg_freefunc(void *link); -/* free the preview image */ +/** + * Free the preview image. + */ void BKE_previewimg_free(struct PreviewImage **prv); -/* clear the preview image or icon, but does not free it */ +/** + * Clear the preview image or icon, but does not free it. + */ void BKE_previewimg_clear(struct PreviewImage *prv); -/* clear the preview image or icon at a specific size */ +/** + * Clear the preview image or icon at a specific size. + */ void BKE_previewimg_clear_single(struct PreviewImage *prv, enum eIconSizes size); -/* get the preview from any pointer */ +/** + * Get the preview from any pointer. + */ struct PreviewImage **BKE_previewimg_id_get_p(const struct ID *id); struct PreviewImage *BKE_previewimg_id_get(const struct ID *id); bool BKE_previewimg_id_supports_jobs(const struct ID *id); -/* Trigger deferred loading of a custom image file into the preview buffer. */ +/** + * Trigger deferred loading of a custom image file into the preview buffer. + */ void BKE_previewimg_id_custom_set(struct ID *id, const char *path); -/* free the preview image belonging to the id */ +/** + * Free the preview image belonging to the id. + */ void BKE_previewimg_id_free(struct ID *id); -/* create a new preview image */ +/** + * Create a new preview image. + */ struct PreviewImage *BKE_previewimg_create(void); -/* create a copy of the preview image */ +/** + * Create a copy of the preview image. + */ struct PreviewImage *BKE_previewimg_copy(const struct PreviewImage *prv); +/** + * Duplicate preview image from \a id and clear icon_id, + * to be used by data-block copy functions. + */ void BKE_previewimg_id_copy(struct ID *new_id, const struct ID *old_id); -/* retrieve existing or create new preview image */ +/** + * Retrieve existing or create new preview image. + */ struct PreviewImage *BKE_previewimg_id_ensure(struct ID *id); +/** + * Handle deferred (lazy) loading/generation of preview image, if needed. + * For now, only used with file thumbnails. + */ void BKE_previewimg_ensure(struct PreviewImage *prv, const int size); +/** + * Create an #ImBuf holding a copy of the preview image buffer in \a prv. + * \note The returned image buffer has to be free'd (#IMB_freeImBuf()). + */ struct ImBuf *BKE_previewimg_to_imbuf(struct PreviewImage *prv, const int size); void BKE_previewimg_finish(struct PreviewImage *prv, const int size); @@ -174,8 +233,15 @@ bool BKE_previewimg_is_finished(const struct PreviewImage *prv, const int size); struct PreviewImage *BKE_previewimg_cached_get(const char *name); +/** + * Generate an empty #PreviewImage, if not yet existing. + */ struct PreviewImage *BKE_previewimg_cached_ensure(const char *name); +/** + * Generate a #PreviewImage from given file path, using thumbnails management, if not yet existing. + * Does not actually generate the preview, #BKE_previewimg_ensure() must be called for that. + */ struct PreviewImage *BKE_previewimg_cached_thumbnail_read(const char *name, const char *path, const int source, diff --git a/source/blender/blenkernel/BKE_idprop.h b/source/blender/blenkernel/BKE_idprop.h index c28ac63388b..1fb3636e9fd 100644 --- a/source/blender/blenkernel/BKE_idprop.h +++ b/source/blender/blenkernel/BKE_idprop.h @@ -56,11 +56,17 @@ typedef union IDPropertyTemplate { /* ----------- Property Array Type ---------- */ +/** + * \note as a start to move away from the stupid #IDP_New function, + * this type has its own allocation function. + */ struct IDProperty *IDP_NewIDPArray(const char *name) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(); struct IDProperty *IDP_CopyIDPArray(const struct IDProperty *array, const int flag) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(); -/* shallow copies item */ +/** + * Shallow copies item. + */ void IDP_SetIndexArray(struct IDProperty *prop, int index, struct IDProperty *item) ATTR_NONNULL(); struct IDProperty *IDP_GetIndexArray(struct IDProperty *prop, int index) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(); @@ -68,11 +74,20 @@ void IDP_AppendArray(struct IDProperty *prop, struct IDProperty *item); void IDP_ResizeIDPArray(struct IDProperty *prop, int len); /* ----------- Numeric Array Type ----------- */ -/* This function works for strings too! */ + +/** + * This function works for strings too! + */ void IDP_ResizeArray(struct IDProperty *prop, int newlen); void IDP_FreeArray(struct IDProperty *prop); /* ---------- String Type ------------ */ +/** + * \param st: The string to assign. + * \param name: The property name. + * \param maxlen: The size of the new string (including the \0 terminator). + * \return The new string property. + */ struct IDProperty *IDP_NewString(const char *st, const char *name, int maxlen) ATTR_WARN_UNUSED_RESULT @@ -91,38 +106,90 @@ void IDP_AssignID(struct IDProperty *prop, struct ID *id, const int flag); /*-------- Group Functions -------*/ -/** Sync values from one group to another, only where they match */ +/** + * Sync values from one group to another when values name and types match, + * copy the values, else ignore. + * + * \note Use for syncing proxies. + */ void IDP_SyncGroupValues(struct IDProperty *dest, const struct IDProperty *src) ATTR_NONNULL(); void IDP_SyncGroupTypes(struct IDProperty *dest, const struct IDProperty *src, const bool do_arraylen) ATTR_NONNULL(); +/** + * Replaces all properties with the same name in a destination group from a source group. + */ void IDP_ReplaceGroupInGroup(struct IDProperty *dest, const struct IDProperty *src) ATTR_NONNULL(); void IDP_ReplaceInGroup(struct IDProperty *group, struct IDProperty *prop) ATTR_NONNULL(); +/** + * Checks if a property with the same name as prop exists, and if so replaces it. + * Use this to preserve order! + */ void IDP_ReplaceInGroup_ex(struct IDProperty *group, struct IDProperty *prop, struct IDProperty *prop_exist); +/** + * If a property is missing in \a dest, add it. + * Do it recursively. + */ void IDP_MergeGroup(struct IDProperty *dest, const struct IDProperty *src, const bool do_overwrite) ATTR_NONNULL(); +/** + * If a property is missing in \a dest, add it. + * Do it recursively. + */ void IDP_MergeGroup_ex(struct IDProperty *dest, const struct IDProperty *src, const bool do_overwrite, const int flag) ATTR_NONNULL(); +/** + * This function has a sanity check to make sure ID properties with the same name don't + * get added to the group. + * + * The sanity check just means the property is not added to the group if another property + * exists with the same name; the client code using ID properties then needs to detect this + * (the function that adds new properties to groups, #IDP_AddToGroup, + * returns false if a property can't be added to the group, and true if it can) + * and free the property. + */ bool IDP_AddToGroup(struct IDProperty *group, struct IDProperty *prop) ATTR_NONNULL(); +/** + * This is the same as IDP_AddToGroup, only you pass an item + * in the group list to be inserted after. + */ bool IDP_InsertToGroup(struct IDProperty *group, struct IDProperty *previous, struct IDProperty *pnew) ATTR_NONNULL(1 /* group */, 3 /* pnew */); +/** + * \note this does not free the property! + * + * To free the property, you have to do: + * #IDP_FreeProperty(prop); + */ void IDP_RemoveFromGroup(struct IDProperty *group, struct IDProperty *prop) ATTR_NONNULL(); +/** + * Removes the property from the group and frees it. + */ void IDP_FreeFromGroup(struct IDProperty *group, struct IDProperty *prop) ATTR_NONNULL(); struct IDProperty *IDP_GetPropertyFromGroup(const struct IDProperty *prop, const char *name) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(); +/** + * Same as above but ensure type match. + */ struct IDProperty *IDP_GetPropertyTypeFromGroup(const struct IDProperty *prop, const char *name, const char type) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(); /*-------- Main Functions --------*/ +/** + * Get the Group property that contains the id properties for ID id. + * + * \param create_if_needed: Set to create the group property and attach it to id if it doesn't + * exist; otherwise the function will return NULL if there's no Group property attached to the ID. + */ struct IDProperty *IDP_GetProperties(struct ID *id, const bool create_if_needed) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(); @@ -130,8 +197,15 @@ struct IDProperty *IDP_CopyProperty(const struct IDProperty *prop) ATTR_WARN_UNU ATTR_NONNULL(); struct IDProperty *IDP_CopyProperty_ex(const struct IDProperty *prop, const int flag) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(); +/** + * Copy content from source #IDProperty into destination one, + * freeing destination property's content first. + */ void IDP_CopyPropertyContent(struct IDProperty *dst, struct IDProperty *src) ATTR_NONNULL(); +/** + * \param is_strict: When false treat missing items as a match. + */ bool IDP_EqualsProperties_ex(struct IDProperty *prop1, struct IDProperty *prop2, const bool is_strict) ATTR_WARN_UNUSED_RESULT; @@ -139,10 +213,41 @@ bool IDP_EqualsProperties_ex(struct IDProperty *prop1, bool IDP_EqualsProperties(struct IDProperty *prop1, struct IDProperty *prop2) ATTR_WARN_UNUSED_RESULT; +/** + * Allocate a new ID. + * + * This function takes three arguments: the ID property type, a union which defines + * its initial value, and a name. + * + * The union is simple to use; see the top of BKE_idprop.h for its definition. + * An example of using this function: + * + * \code{.c} + * IDPropertyTemplate val; + * IDProperty *group, *idgroup, *color; + * group = IDP_New(IDP_GROUP, val, "group1"); // groups don't need a template. + * + * val.array.len = 4 + * val.array.type = IDP_FLOAT; + * color = IDP_New(IDP_ARRAY, val, "color1"); + * + * idgroup = IDP_GetProperties(some_id, 1); + * IDP_AddToGroup(idgroup, color); + * IDP_AddToGroup(idgroup, group); + * \endcode + * + * Note that you MUST either attach the id property to an id property group with + * IDP_AddToGroup or MEM_freeN the property, doing anything else might result in + * a memory leak. + */ struct IDProperty *IDP_New(const char type, const IDPropertyTemplate *val, const char *name) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(); +/** + * \note This will free allocated data, all child properties of arrays and groups, and unlink IDs! + * But it does not free the actual #IDProperty struct itself. + */ void IDP_FreePropertyContent_ex(struct IDProperty *prop, const bool do_id_user); void IDP_FreePropertyContent(struct IDProperty *prop); void IDP_FreeProperty_ex(struct IDProperty *prop, const bool do_id_user); @@ -184,16 +289,35 @@ void IDP_Reset(struct IDProperty *prop, const struct IDProperty *reference); # define IDP_Id(prop) ((ID *)(prop)->data.pointer) #endif +/** + * Return an int from an #IDProperty with a compatible type. This should be avoided, but + * it's sometimes necessary, for example when legacy files have incorrect property types. + */ int IDP_coerce_to_int_or_zero(const struct IDProperty *prop); +/** + * Return a float from an #IDProperty with a compatible type. This should be avoided, but + * it's sometimes necessary, for example when legacy files have incorrect property types. + */ float IDP_coerce_to_float_or_zero(const struct IDProperty *prop); +/** + * Return a double from an #IDProperty with a compatible type. This should be avoided, but + * it's sometimes necessary, for example when legacy files have incorrect property types. + */ double IDP_coerce_to_double_or_zero(const struct IDProperty *prop); /** - * Call a callback for each idproperty in the hierarchy under given root one (included). - * + * Call a callback for each #IDproperty in the hierarchy under given root one (included). */ typedef void (*IDPForeachPropertyCallback)(struct IDProperty *id_property, void *user_data); +/** + * Loop through all ID properties in hierarchy of given \a id_property_root included. + * + * \note Container types (groups and arrays) are processed after applying the callback on them. + * + * \param type_filter: If not 0, only apply callback on properties of matching types, see + * IDP_TYPE_FILTER_ enum in DNA_ID.h. + */ void IDP_foreach_property(struct IDProperty *id_property_root, const int type_filter, IDPForeachPropertyCallback callback, @@ -230,6 +354,11 @@ typedef enum eIDPropertyUIDataType { bool IDP_ui_data_supported(const struct IDProperty *prop); eIDPropertyUIDataType IDP_ui_data_type(const struct IDProperty *prop); void IDP_ui_data_free(struct IDProperty *prop); +/** + * Free allocated pointers in the UI data that isn't shared with the UI data in the `other` + * argument. Useful for returning early on failure when updating UI data in place, or when + * replacing a subset of the UI data's allocated pointers. + */ void IDP_ui_data_free_unique_contents(struct IDPropertyUIData *ui_data, eIDPropertyUIDataType type, const struct IDPropertyUIData *other); diff --git a/source/blender/blenkernel/BKE_idtype.h b/source/blender/blenkernel/BKE_idtype.h index 7a7f32fe838..0f63ff8a315 100644 --- a/source/blender/blenkernel/BKE_idtype.h +++ b/source/blender/blenkernel/BKE_idtype.h @@ -283,6 +283,7 @@ extern IDTypeInfo IDType_ID_PT; extern IDTypeInfo IDType_ID_VO; extern IDTypeInfo IDType_ID_SIM; +/** Empty shell mostly, but needed for read code. */ extern IDTypeInfo IDType_ID_LINK_PLACEHOLDER; /* ********** Helpers/Utils API. ********** */ @@ -294,32 +295,101 @@ void BKE_idtype_init(void); const struct IDTypeInfo *BKE_idtype_get_info_from_idcode(const short id_code); const struct IDTypeInfo *BKE_idtype_get_info_from_id(const struct ID *id); +/** + * Convert an \a idcode into a name. + * + * \param idcode: The code to convert. + * \return A static string representing the name of the code. + */ const char *BKE_idtype_idcode_to_name(const short idcode); +/** + * Convert an \a idcode into a name (plural). + * + * \param idcode: The code to convert. + * \return A static string representing the name of the code. + */ const char *BKE_idtype_idcode_to_name_plural(const short idcode); +/** + * Convert an \a idcode into its translations' context. + * + * \param idcode: The code to convert. + * \return A static string representing the i18n context of the code. + */ const char *BKE_idtype_idcode_to_translation_context(const short idcode); +/** + * Return if the ID code is a valid ID code. + * + * \param idcode: The code to check. + * \return Boolean, 0 when invalid. + */ bool BKE_idtype_idcode_is_valid(const short idcode); +/** + * Check if an ID type is linkable. + * + * \param idcode: The IDType code to check. + * \return Boolean, false when non linkable, true otherwise. + */ bool BKE_idtype_idcode_is_linkable(const short idcode); +/** + * Check if an ID type is only appendable. + * + * \param idcode: The IDType code to check. + * \return Boolean, false when also linkable, true when only appendable. + */ bool BKE_idtype_idcode_is_only_appendable(const short idcode); +/** + * Check if an ID type can try to reuse and existing matching local one when being appended again. + * + * \param idcode: The IDType code to check. + * \return Boolean, false when it cannot be re-used, true otherwise. + */ bool BKE_idtype_idcode_append_is_reusable(const short idcode); /* Macro currently, since any linkable IDtype should be localizable. */ #define BKE_idtype_idcode_is_localizable BKE_idtype_idcode_is_linkable +/** + * Convert an ID-type name into an \a idcode (ie. #ID_SCE) + * + * \param idtype_name: The ID-type's "user visible name" to convert. + * \return The \a idcode for the name, or 0 if invalid. + */ short BKE_idtype_idcode_from_name(const char *idtype_name); +/** + * Convert an \a idcode into an \a idfilter (e.g. #ID_OB -> #FILTER_ID_OB). + */ uint64_t BKE_idtype_idcode_to_idfilter(const short idcode); +/** + * Convert an \a idfilter into an \a idcode (e.g. #FILTER_ID_OB -> #ID_OB). + */ short BKE_idtype_idcode_from_idfilter(const uint64_t idfilter); +/** + * Convert an \a idcode into an index (e.g. #ID_OB -> #INDEX_ID_OB). + */ int BKE_idtype_idcode_to_index(const short idcode); +/** + * Get an \a idcode from an index (e.g. #INDEX_ID_OB -> #ID_OB). + */ short BKE_idtype_idcode_from_index(const int index); +/** + * Return an ID code and steps the index forward 1. + * + * \param index: start as 0. + * \return the code, 0 when all codes have been returned. + */ short BKE_idtype_idcode_iter_step(int *index); /* Some helpers/wrappers around callbacks defined in #IDTypeInfo, dealing e.g. with embedded IDs. * XXX Ideally those would rather belong to #BKE_lib_id, but using callback function pointers makes * this hard to do properly if we want to avoid headers includes in headers. */ +/** + * Wrapper around #IDTypeInfo foreach_cache that also handles embedded IDs. + */ void BKE_idtype_id_foreach_cache(struct ID *id, IDTypeForeachCacheFunctionCallback function_callback, void *user_data); diff --git a/source/blender/blenkernel/BKE_image.h b/source/blender/blenkernel/BKE_image.h index 77f1d197844..4db6da4b3ea 100644 --- a/source/blender/blenkernel/BKE_image.h +++ b/source/blender/blenkernel/BKE_image.h @@ -50,9 +50,16 @@ struct anim; void BKE_image_free_packedfiles(struct Image *image); void BKE_image_free_views(struct Image *image); void BKE_image_free_buffers(struct Image *image); +/** + * Simply free the image data from memory, + * on display the image can load again (except for render buffers). + */ void BKE_image_free_buffers_ex(struct Image *image, bool do_lock); void BKE_image_free_gputextures(struct Image *ima); -/* call from library */ +/** + * Free (or release) any data used by this image (does not free the image itself). + * \note Call from library. + */ void BKE_image_free_data(struct Image *image); typedef void(StampCallback)(void *data, const char *propname, char *propvalue, int len); @@ -66,6 +73,9 @@ void BKE_render_result_stamp_info(struct Scene *scene, * The caller is responsible for freeing the allocated memory. */ struct StampData *BKE_stamp_info_from_scene_static(const struct Scene *scene); +/** + * Check whether the given metadata field name translates to a known field of a stamp. + */ bool BKE_stamp_is_known_field(const char *field_name); void BKE_imbuf_stamp_info(struct RenderResult *rr, struct ImBuf *ibuf); void BKE_stamp_info_from_imbuf(struct RenderResult *rr, struct ImBuf *ibuf); @@ -90,8 +100,15 @@ int BKE_imbuf_write_stamp(struct Scene *scene, struct ImBuf *ibuf, const char *name, const struct ImageFormatData *imf); +/** + * \note imf->planes is ignored here, its assumed the image channels are already set. + */ void BKE_imbuf_write_prepare(struct ImBuf *ibuf, const struct ImageFormatData *imf); int BKE_imbuf_write(struct ImBuf *ibuf, const char *name, const struct ImageFormatData *imf); +/** + * Same as #BKE_imbuf_write() but crappy workaround not to permanently modify _some_, + * values in the imbuf. + */ int BKE_imbuf_write_as(struct ImBuf *ibuf, const char *name, struct ImageFormatData *imf, @@ -125,11 +142,18 @@ bool BKE_imtype_requires_linear_float(const char imtype); char BKE_imtype_valid_channels(const char imtype, bool write_file); char BKE_imtype_valid_depths(const char imtype); +/** + * String is from command line `--render-format` argument, + * keep in sync with `creator_args.c` help info. + */ char BKE_imtype_from_arg(const char *arg); void BKE_imformat_defaults(struct ImageFormatData *im_format); void BKE_imbuf_to_image_format(struct ImageFormatData *im_format, const struct ImBuf *imbuf); +/** + * Used by sequencer too. + */ struct anim *openanim(const char *name, int flags, int streamindex, @@ -164,11 +188,18 @@ struct RenderResult; #define IMA_CHAN_FLAG_RGB 2 #define IMA_CHAN_FLAG_ALPHA 4 -/* checks whether there's an image buffer for given image and user */ +/** + * Checks whether there's an image buffer for given image and user. + */ bool BKE_image_has_ibuf(struct Image *ima, struct ImageUser *iuser); -/* same as above, but can be used to retrieve images being rendered in - * a thread safe way, always call both acquire and release */ +/** + * Return image buffer for given image and user: + * - will lock render result if image type is render result and lock is not NULL + * - will return NULL if image is NULL or image type is render or composite result and lock is NULL + * + * References the result, #BKE_image_release_ibuf should be used to de-reference. + */ struct ImBuf *BKE_image_acquire_ibuf(struct Image *ima, struct ImageUser *iuser, void **r_lock); void BKE_image_release_ibuf(struct Image *ima, struct ImBuf *ibuf, void *lock); @@ -179,17 +210,28 @@ struct ImBuf *BKE_image_pool_acquire_ibuf(struct Image *ima, struct ImagePool *pool); void BKE_image_pool_release_ibuf(struct Image *ima, struct ImBuf *ibuf, struct ImagePool *pool); -/* set an alpha mode based on file extension */ +/** + * Set an alpha mode based on file extension. + */ char BKE_image_alpha_mode_from_extension_ex(const char *filepath); void BKE_image_alpha_mode_from_extension(struct Image *image); -/* returns a new image or NULL if it can't load */ +/** + * Returns a new image or NULL if it can't load. + */ struct Image *BKE_image_load(struct Main *bmain, const char *filepath); -/* returns existing Image when filename/type is same (frame optional) */ +/** + * Returns existing Image when filename/type is same. + * + * Checks if image was already loaded, then returns same image otherwise creates new + * (does not load ibuf itself). + */ struct Image *BKE_image_load_exists_ex(struct Main *bmain, const char *filepath, bool *r_exists); struct Image *BKE_image_load_exists(struct Main *bmain, const char *filepath); -/* adds image, adds ibuf, generates color or pattern */ +/** + * Adds new image block, creates ImBuf and initializes color. + */ struct Image *BKE_image_add_generated(struct Main *bmain, unsigned int width, unsigned int height, @@ -201,10 +243,15 @@ struct Image *BKE_image_add_generated(struct Main *bmain, const bool stereo3d, const bool is_data, const bool tiled); -/* adds image from imbuf, owns imbuf */ +/** + * Create an image from ibuf. The reference-count of ibuf is increased, + * caller should take care to drop its reference by calling #IMB_freeImBuf if needed. + */ struct Image *BKE_image_add_from_imbuf(struct Main *bmain, struct ImBuf *ibuf, const char *name); -/* for reload, refresh, pack */ +/** + * For reload, refresh, pack. + */ void BKE_imageuser_default(struct ImageUser *iuser); void BKE_image_init_imageuser(struct Image *ima, struct ImageUser *iuser); void BKE_image_signal(struct Main *bmain, struct Image *ima, struct ImageUser *iuser, int signal); @@ -216,61 +263,100 @@ void BKE_image_walk_all_users(const struct Main *mainp, struct ImageUser *iuser, void *customdata)); -/* ensures an Image exists for viewing nodes or render */ +/** + * Ensures an Image exists for viewing nodes or render + * forces existence of 1 Image for render-output or nodes, returns Image. + * + * \param name: Only for default, when making new one. + */ struct Image *BKE_image_ensure_viewer(struct Main *bmain, int type, const char *name); -/* ensures the view node cache is compatible with the scene views */ +/** + * Ensures the view node cache is compatible with the scene views. + * Reset the image cache and views when the Viewer Nodes views don't match the scene views. + */ void BKE_image_ensure_viewer_views(const struct RenderData *rd, struct Image *ima, struct ImageUser *iuser); -/* called on frame change or before render */ +/** + * Called on frame change or before render. + */ void BKE_image_user_frame_calc(struct Image *ima, struct ImageUser *iuser, int cfra); int BKE_image_user_frame_get(const struct ImageUser *iuser, int cfra, bool *r_is_in_range); void BKE_image_user_file_path(struct ImageUser *iuser, struct Image *ima, char *path); void BKE_image_editors_update_frame(const struct Main *bmain, int cfra); -/* dependency graph update for image user users */ +/** + * Dependency graph update for image user users. + */ bool BKE_image_user_id_has_animation(struct ID *id); void BKE_image_user_id_eval_animation(struct Depsgraph *depsgraph, struct ID *id); -/* sets index offset for multilayer files */ +/** + * Sets index offset for multi-layer files and because rendered results use fake layer/passes, + * don't correct for wrong indices here. + */ struct RenderPass *BKE_image_multilayer_index(struct RenderResult *rr, struct ImageUser *iuser); -/* sets index offset for multiview files */ +/** + * Sets index offset for multi-view files. + */ void BKE_image_multiview_index(struct Image *ima, struct ImageUser *iuser); -/* for multilayer images as well as for render-viewer */ +/** + * For multi-layer images as well as for render-viewer + * and because rendered results use fake layer/passes, don't correct for wrong indices here. + */ bool BKE_image_is_multilayer(struct Image *ima); bool BKE_image_is_multiview(struct Image *ima); bool BKE_image_is_stereo(struct Image *ima); struct RenderResult *BKE_image_acquire_renderresult(struct Scene *scene, struct Image *ima); void BKE_image_release_renderresult(struct Scene *scene, struct Image *ima); -/* For multi-layer images as well as for single-layer. */ +/** + * For multi-layer images as well as for single-layer. + */ bool BKE_image_is_openexr(struct Image *ima); -/* For multiple slot render, call this before render. */ +/** + * For multiple slot render, call this before render. + */ void BKE_image_backup_render(struct Scene *scene, struct Image *ima, bool free_current_slot); -/* For single-layer OpenEXR saving */ +/** + * For single-layer OpenEXR saving. + */ bool BKE_image_save_openexr_multiview(struct Image *ima, struct ImBuf *ibuf, const char *filepath, const int flags); -/* goes over all textures that use images */ +/** + * Goes over all textures that use images. + */ void BKE_image_free_all_textures(struct Main *bmain); -/* does one image! */ +/** + * Operates on one image only! + * \param except_frame: This is weak, only works for sequences without offset. + */ void BKE_image_free_anim_ibufs(struct Image *ima, int except_frame); -/* does all images with type MOVIE or SEQUENCE */ +/** + * Does all images with type MOVIE or SEQUENCE. + */ void BKE_image_all_free_anim_ibufs(struct Main *bmain, int cfra); void BKE_image_free_all_gputextures(struct Main *bmain); +/** + * Same as above but only free animated images. + */ void BKE_image_free_anim_gputextures(struct Main *bmain); void BKE_image_free_old_gputextures(struct Main *bmain); +/** + * Pack image to memory. + */ bool BKE_image_memorypack(struct Image *ima); void BKE_image_packfiles(struct ReportList *reports, struct Image *ima, const char *basepath); void BKE_image_packfiles_from_mem(struct ReportList *reports, @@ -278,22 +364,34 @@ void BKE_image_packfiles_from_mem(struct ReportList *reports, char *data, const size_t data_len); -/* Prints memory statistics for images. */ +/** + * Prints memory statistics for images. + */ void BKE_image_print_memlist(struct Main *bmain); -/* Merge source into dest, and free source. */ +/** + * Merge source into `dest`, and free `source`. + */ void BKE_image_merge(struct Main *bmain, struct Image *dest, struct Image *source); -/* Scale the image. */ +/** + * Scale the image. + */ bool BKE_image_scale(struct Image *image, int width, int height); -/* Check if texture has alpha (depth=32). */ +/** + * Check if texture has alpha (depth=32). + */ bool BKE_image_has_alpha(struct Image *image); -/* Check if texture has GPU texture code. */ +/** + * Check if texture has GPU texture code. + */ bool BKE_image_has_opengl_texture(struct Image *ima); -/* Get tile index for tiled images. */ +/** + * Get tile index for tiled images. + */ void BKE_image_get_tile_label(struct Image *ima, struct ImageTile *tile, char *label, @@ -320,6 +418,9 @@ int BKE_image_get_tile_from_pos(struct Image *ima, const float uv[2], float r_uv[2], float r_ofs[2]); +/** + * Return the tile_number for the closest UDIM tile. + */ int BKE_image_find_nearest_tile(const struct Image *image, const float co[2]); void BKE_image_get_size(struct Image *image, struct ImageUser *iuser, int *r_width, int *r_height); @@ -327,6 +428,7 @@ void BKE_image_get_size_fl(struct Image *image, struct ImageUser *iuser, float r void BKE_image_get_aspect(struct Image *image, float *r_aspx, float *r_aspy); /* image_gen.c */ + void BKE_image_buf_fill_color( unsigned char *rect, float *rect_float, int width, int height, const float color[4]); void BKE_image_buf_fill_checker(unsigned char *rect, float *rect_float, int width, int height); @@ -336,36 +438,64 @@ void BKE_image_buf_fill_checker_color(unsigned char *rect, int height); /* Cycles hookup */ + unsigned char *BKE_image_get_pixels_for_frame(struct Image *image, int frame, int tile); float *BKE_image_get_float_pixels_for_frame(struct Image *image, int frame, int tile); /* Image modifications */ + bool BKE_image_is_dirty(struct Image *image); void BKE_image_mark_dirty(struct Image *image, struct ImBuf *ibuf); bool BKE_image_buffer_format_writable(struct ImBuf *ibuf); + bool BKE_image_is_dirty_writable(struct Image *image, bool *is_format_writable); -/* Guess offset for the first frame in the sequence */ +/** + * Guess offset for the first frame in the sequence. + */ int BKE_image_sequence_guess_offset(struct Image *image); bool BKE_image_has_anim(struct Image *image); bool BKE_image_has_packedfile(const struct Image *image); bool BKE_image_has_filepath(struct Image *ima); +/** + * Checks the image buffer changes with time (not keyframed values). + */ bool BKE_image_is_animated(struct Image *image); +/** + * Checks whether the image consists of multiple buffers. + */ bool BKE_image_has_multiple_ibufs(struct Image *image); void BKE_image_file_format_set(struct Image *image, int ftype, const struct ImbFormatOptions *options); bool BKE_image_has_loaded_ibuf(struct Image *image); +/** + * References the result, #BKE_image_release_ibuf is to be called to de-reference. + * Use lock=NULL when calling #BKE_image_release_ibuf(). + */ struct ImBuf *BKE_image_get_ibuf_with_name(struct Image *image, const char *name); +/** + * References the result, #BKE_image_release_ibuf is to be called to de-reference. + * Use lock=NULL when calling #BKE_image_release_ibuf(). + * + * TODO(sergey): This is actually "get first item from the cache", which is + * not so much predictable. But using first loaded image buffer + * was also malicious logic and all the areas which uses this + * function are to be re-considered. + */ struct ImBuf *BKE_image_get_first_ibuf(struct Image *image); -/* Not to be use directly. */ +/** + * Not to be use directly. + */ struct GPUTexture *BKE_image_create_gpu_texture_from_ibuf(struct Image *image, struct ImBuf *ibuf); -/* Get the #GPUTexture for a given `Image`. +/** + * Get the #GPUTexture for a given `Image`. * * `iuser` and `ibuf` are mutual exclusive parameters. The caller can pass the `ibuf` when already - * available. It is also required when requesting the #GPUTexture for a render result. */ + * available. It is also required when requesting the #GPUTexture for a render result. + */ struct GPUTexture *BKE_image_get_gpu_texture(struct Image *image, struct ImageUser *iuser, struct ImBuf *ibuf); @@ -375,14 +505,33 @@ struct GPUTexture *BKE_image_get_gpu_tiles(struct Image *image, struct GPUTexture *BKE_image_get_gpu_tilemap(struct Image *image, struct ImageUser *iuser, struct ImBuf *ibuf); +/** + * Is the alpha of the `GPUTexture` for a given image/ibuf premultiplied. + */ bool BKE_image_has_gpu_texture_premultiplied_alpha(struct Image *image, struct ImBuf *ibuf); +/** + * Partial update of texture for texture painting. + * This is often much quicker than fully updating the texture for high resolution images. + */ void BKE_image_update_gputexture( struct Image *ima, struct ImageUser *iuser, int x, int y, int w, int h); +/** + * Mark areas on the #GPUTexture that needs to be updated. The areas are marked in chunks. + * The next time the #GPUTexture is used these tiles will be refreshes. This saves time + * when writing to the same place multiple times This happens for during foreground rendering. + */ void BKE_image_update_gputexture_delayed( struct Image *ima, struct ImBuf *ibuf, int x, int y, int w, int h); +/** + * Called on entering and exiting texture paint mode, + * temporary disabling/enabling mipmapping on all images for quick texture + * updates with glTexSubImage2D. images that didn't change don't have to be re-uploaded to OpenGL. + */ void BKE_image_paint_set_mipmap(struct Main *bmain, bool mipmap); -/* Delayed free of OpenGL buffers by main thread */ +/** + * Delayed free of OpenGL buffers by main thread. + */ void BKE_image_free_unused_gpu_textures(void); struct RenderSlot *BKE_image_add_renderslot(struct Image *ima, const char *name); diff --git a/source/blender/blenkernel/BKE_ipo.h b/source/blender/blenkernel/BKE_ipo.h index f4871c83caf..5899db6c6ce 100644 --- a/source/blender/blenkernel/BKE_ipo.h +++ b/source/blender/blenkernel/BKE_ipo.h @@ -28,6 +28,19 @@ extern "C" { struct Main; +/** + * Called from #do_versions() in `readfile.c` to convert the old 'IPO/adrcode' system + * to the new 'Animato/RNA' system. + * + * The basic method used here, is to loop over data-blocks which have IPO-data, + * and add those IPO's to new AnimData blocks as Actions. + * Action/NLA data only works well for Objects, so these only need to be checked for there. + * + * Data that has been converted should be freed immediately, which means that it is immediately + * clear which data-blocks have yet to be converted, and also prevent freeing errors when we exit. + * + * \note Currently done after all file reading. + */ void do_versions_ipos_to_animato(struct Main *main); /* --------------------- xxx stuff ------------------------ */ diff --git a/source/blender/blenkernel/BKE_key.h b/source/blender/blenkernel/BKE_key.h index cb4fc607703..305cb62179d 100644 --- a/source/blender/blenkernel/BKE_key.h +++ b/source/blender/blenkernel/BKE_key.h @@ -36,21 +36,44 @@ struct Object; extern "C" { #endif +/** + * Free (or release) any data used by this shapekey (does not free the key itself). + */ void BKE_key_free_data(struct Key *key); void BKE_key_free_nolib(struct Key *key); struct Key *BKE_key_add(struct Main *bmain, struct ID *id); +/** + * Sort shape keys after a change. + * This assumes that at most one key was moved, + * which is a valid assumption for the places it's currently being called. + */ void BKE_key_sort(struct Key *key); void key_curve_position_weights(float t, float data[4], int type); +/** + * First derivative. + */ void key_curve_tangent_weights(float t, float data[4], int type); +/** + * Second derivative. + */ void key_curve_normal_weights(float t, float data[4], int type); +/** + * Returns key coordinates (+ tilt) when key applied, NULL otherwise. + */ float *BKE_key_evaluate_object_ex(struct Object *ob, int *r_totelem, float *arr, size_t arr_size); float *BKE_key_evaluate_object(struct Object *ob, int *r_totelem); +/** + * \param shape_index: The index to use or all (when -1). + */ int BKE_keyblock_element_count_from_shape(const struct Key *key, const int shape_index); int BKE_keyblock_element_count(const struct Key *key); +/** + * \param shape_index: The index to use or all (when -1). + */ size_t BKE_keyblock_element_calc_size_from_shape(const struct Key *key, const int shape_index); size_t BKE_keyblock_element_calc_size(const struct Key *key); @@ -60,18 +83,43 @@ struct Key **BKE_key_from_id_p(struct ID *id); struct Key *BKE_key_from_id(struct ID *id); struct Key **BKE_key_from_object_p(const struct Object *ob); struct Key *BKE_key_from_object(const struct Object *ob); +/** + * Only the active key-block. + */ struct KeyBlock *BKE_keyblock_from_object(struct Object *ob); struct KeyBlock *BKE_keyblock_from_object_reference(struct Object *ob); struct KeyBlock *BKE_keyblock_add(struct Key *key, const char *name); +/** + * \note sorting is a problematic side effect in some cases, + * better only do this explicitly by having its own function, + * + * \param key: The key datablock to add to. + * \param name: Optional name for the new keyblock. + * \param do_force: always use ctime even for relative keys. + */ struct KeyBlock *BKE_keyblock_add_ctime(struct Key *key, const char *name, const bool do_force); +/** + * Get the appropriate #KeyBlock given an index. + */ struct KeyBlock *BKE_keyblock_from_key(struct Key *key, int index); +/** + * Get the appropriate #KeyBlock given a name to search for. + */ struct KeyBlock *BKE_keyblock_find_name(struct Key *key, const char name[]); +/** + * \brief copy shape-key attributes, but not key data.or name/UID + */ void BKE_keyblock_copy_settings(struct KeyBlock *kb_dst, const struct KeyBlock *kb_src); +/** + * Get RNA-Path for 'value' setting of the given shape-key. + * \note the user needs to free the returned string once they're finish with it. + */ char *BKE_keyblock_curval_rnapath_get(struct Key *key, struct KeyBlock *kb); /* conversion functions */ /* NOTE: 'update_from' versions do not (re)allocate mem in kb, while 'convert_from' do. */ + void BKE_keyblock_update_from_lattice(struct Lattice *lt, struct KeyBlock *kb); void BKE_keyblock_convert_from_lattice(struct Lattice *lt, struct KeyBlock *kb); void BKE_keyblock_convert_to_lattice(struct KeyBlock *kb, struct Lattice *lt); @@ -88,6 +136,15 @@ void BKE_keyblock_convert_to_curve(struct KeyBlock *kb, struct Curve *cu, struct void BKE_keyblock_update_from_mesh(struct Mesh *me, struct KeyBlock *kb); void BKE_keyblock_convert_from_mesh(struct Mesh *me, struct Key *key, struct KeyBlock *kb); void BKE_keyblock_convert_to_mesh(struct KeyBlock *kb, struct Mesh *me); +/** + * Computes normals (vertices, polygons and/or loops ones) of given mesh for given shape key. + * + * \param kb: the KeyBlock to use to compute normals. + * \param mesh: the Mesh to apply key-block to. + * \param r_vertnors: if non-NULL, an array of vectors, same length as number of vertices. + * \param r_polynors: if non-NULL, an array of vectors, same length as number of polygons. + * \param r_loopnors: if non-NULL, an array of vectors, same length as number of loops. + */ void BKE_keyblock_mesh_calc_normals(struct KeyBlock *kb, struct Mesh *mesh, float (*r_vertnors)[3], @@ -107,28 +164,54 @@ void BKE_keyblock_update_from_offset(struct Object *ob, const float (*ofs)[3]); /* other management */ + +/** + * Move shape key from org_index to new_index. Safe, clamps index to valid range, + * updates reference keys, the object's active shape index, + * the 'frame' value in case of absolute keys, etc. + * Note indices are expected in real values (not 'fake' shapenr +1 ones). + * + * \param org_index: if < 0, current object's active shape will be used as skey to move. + * \return true if something was done, else false. + */ bool BKE_keyblock_move(struct Object *ob, int org_index, int new_index); +/** + * Check if given key-block (as index) is used as basis by others in given key. + */ bool BKE_keyblock_is_basis(struct Key *key, const int index); /* -------------------------------------------------------------------- */ /** \name Key-Block Data Access * \{ */ +/** + * \param shape_index: The index to use or all (when -1). + */ void BKE_keyblock_data_get_from_shape(const struct Key *key, float (*arr)[3], const int shape_index); void BKE_keyblock_data_get(const struct Key *key, float (*arr)[3]); +/** + * Set the data to all key-blocks (or shape_index if != -1). + */ void BKE_keyblock_data_set_with_mat4(struct Key *key, const int shape_index, const float (*coords)[3], const float mat[4][4]); +/** + * Set the data for all key-blocks (or shape_index if != -1), + * transforming by \a mat. + */ void BKE_keyblock_curve_data_set_with_mat4(struct Key *key, const struct ListBase *nurb, const int shape_index, const void *data, const float mat[4][4]); +/** + * Set the data for all key-blocks (or shape_index if != -1). + */ void BKE_keyblock_data_set(struct Key *key, const int shape_index, const void *data); /** \} */ diff --git a/source/blender/blenkernel/BKE_keyconfig.h b/source/blender/blenkernel/BKE_keyconfig.h index 1cacbf61976..132994ede3a 100644 --- a/source/blender/blenkernel/BKE_keyconfig.h +++ b/source/blender/blenkernel/BKE_keyconfig.h @@ -43,10 +43,12 @@ typedef struct wmKeyConfigPrefType_Runtime { typedef struct wmKeyConfigPrefType_Runtime wmKeyConfigPrefType_Runtime; #endif -/* KeyConfig preferences (UserDef). */ +/* KeyConfig preferences (#UserDef). */ + struct wmKeyConfigPref *BKE_keyconfig_pref_ensure(struct UserDef *userdef, const char *kc_idname); /* KeyConfig preferences (RNA). */ + struct wmKeyConfigPrefType_Runtime *BKE_keyconfig_pref_type_find(const char *idname, bool quiet); void BKE_keyconfig_pref_type_add(struct wmKeyConfigPrefType_Runtime *kpt_rt); void BKE_keyconfig_pref_type_remove(const struct wmKeyConfigPrefType_Runtime *kpt_rt); @@ -55,6 +57,10 @@ void BKE_keyconfig_pref_type_init(void); void BKE_keyconfig_pref_type_free(void); /* Versioning. */ + +/** + * Set select mouse, for versioning code. + */ void BKE_keyconfig_pref_set_select_mouse(struct UserDef *userdef, int value, bool override); struct wmKeyConfigFilterItemParams { @@ -67,6 +73,10 @@ void BKE_keyconfig_keymap_filter_item(struct wmKeyMap *keymap, const struct wmKeyConfigFilterItemParams *params, bool (*filter_fn)(struct wmKeyMapItem *kmi, void *user_data), void *user_data); +/** + * Filter & optionally remove key-map items, + * intended for versioning, but may be used in other situations too. + */ void BKE_keyconfig_pref_filter_items(struct UserDef *userdef, const struct wmKeyConfigFilterItemParams *params, bool (*filter_fn)(struct wmKeyMapItem *kmi, void *user_data), diff --git a/source/blender/blenkernel/BKE_layer.h b/source/blender/blenkernel/BKE_layer.h index 08b44959096..b2fa464aedc 100644 --- a/source/blender/blenkernel/BKE_layer.h +++ b/source/blender/blenkernel/BKE_layer.h @@ -52,23 +52,57 @@ typedef enum eViewLayerCopyMethod { VIEWLAYER_ADD_COPY = 2, } eViewLayerCopyMethod; +/** + * Returns the default view layer to view in work-spaces if there is + * none linked to the workspace yet. + */ struct ViewLayer *BKE_view_layer_default_view(const struct Scene *scene); +/** + * Returns the default view layer to render if we need to render just one. + */ struct ViewLayer *BKE_view_layer_default_render(const struct Scene *scene); +/** + * Returns view layer with matching name, or NULL if not found. + */ struct ViewLayer *BKE_view_layer_find(const struct Scene *scene, const char *layer_name); +/** + * Add a new view layer by default, a view layer has the master collection. + */ struct ViewLayer *BKE_view_layer_add(struct Scene *scene, const char *name, struct ViewLayer *view_layer_source, const int type); /* DEPRECATED */ +/** + * This is a placeholder to know which areas of the code need to be addressed + * for the Workspace changes. Never use this, you should typically get the + * active layer from the context or window. + */ struct ViewLayer *BKE_view_layer_context_active_PLACEHOLDER(const struct Scene *scene); void BKE_view_layer_free(struct ViewLayer *view_layer); +/** + * Free (or release) any data used by this #ViewLayer. + */ void BKE_view_layer_free_ex(struct ViewLayer *view_layer, const bool do_id_user); +/** + * Tag all the selected objects of a render-layer. + */ void BKE_view_layer_selected_objects_tag(struct ViewLayer *view_layer, const int tag); +/** + * Fallback for when a Scene has no camera to use. + * + * \param view_layer: in general you want to use the same #ViewLayer that is used for depsgraph. + * If rendering you pass the scene active layer, when viewing in the viewport + * you want to get #ViewLayer from context. + */ struct Object *BKE_view_layer_camera_find(struct ViewLayer *view_layer); +/** + * Find the #ViewLayer a #LayerCollection belongs to. + */ struct ViewLayer *BKE_view_layer_find_from_collection(const struct Scene *scene, struct LayerCollection *lc); struct Base *BKE_view_layer_base_find(struct ViewLayer *view_layer, struct Object *ob); @@ -76,6 +110,11 @@ void BKE_view_layer_base_deselect_all(struct ViewLayer *view_layer); void BKE_view_layer_base_select_and_set_active(struct ViewLayer *view_layer, struct Base *selbase); +/** + * Only copy internal data of #ViewLayer from source to already allocated/initialized destination. + * + * \param flag: Copying options (see BKE_lib_id.h's LIB_ID_COPY_... flags for more). + */ void BKE_view_layer_copy_data(struct Scene *scene_dst, const struct Scene *scene_src, struct ViewLayer *view_layer_dst, @@ -87,15 +126,33 @@ void BKE_view_layer_rename(struct Main *bmain, struct ViewLayer *view_layer, const char *name); +/** + * Get the active collection + */ struct LayerCollection *BKE_layer_collection_get_active(struct ViewLayer *view_layer); +/** + * Activate collection + */ bool BKE_layer_collection_activate(struct ViewLayer *view_layer, struct LayerCollection *lc); +/** + * Activate first parent collection. + */ struct LayerCollection *BKE_layer_collection_activate_parent(struct ViewLayer *view_layer, struct LayerCollection *lc); +/** + * Get the total number of collections (including all the nested collections) + */ int BKE_layer_collection_count(const struct ViewLayer *view_layer); +/** + * Get the collection for a given index. + */ struct LayerCollection *BKE_layer_collection_from_index(struct ViewLayer *view_layer, const int index); +/** + * \return -1 if not found. + */ int BKE_layer_collection_findindex(struct ViewLayer *view_layer, const struct LayerCollection *lc); void BKE_layer_collection_resync_forbid(void); @@ -103,20 +160,43 @@ void BKE_layer_collection_resync_allow(void); void BKE_main_collection_sync(const struct Main *bmain); void BKE_scene_collection_sync(const struct Scene *scene); +/** + * Update view layer collection tree from collections used in the scene. + * This is used when collections are removed or added, both while editing + * and on file loaded in case linked data changed or went missing. + */ void BKE_layer_collection_sync(const struct Scene *scene, struct ViewLayer *view_layer); void BKE_layer_collection_local_sync(struct ViewLayer *view_layer, const struct View3D *v3d); +/** + * Sync the local collection for all the 3D Viewports. + */ void BKE_layer_collection_local_sync_all(const struct Main *bmain); void BKE_main_collection_sync_remap(const struct Main *bmain); +/** + * Return the first matching #LayerCollection in the #ViewLayer for the Collection. + */ struct LayerCollection *BKE_layer_collection_first_from_scene_collection( const struct ViewLayer *view_layer, const struct Collection *collection); +/** + * See if view layer has the scene collection linked directly, or indirectly (nested). + */ bool BKE_view_layer_has_collection(const struct ViewLayer *view_layer, const struct Collection *collection); +/** + * See if the object is in any of the scene layers of the scene. + */ bool BKE_scene_has_object(struct Scene *scene, struct Object *ob); -/* selection and hiding */ +/* Selection and hiding. */ +/** + * Select all the objects of this layer collection + * + * It also select the objects that are in nested collections. + * \note Recursive. + */ bool BKE_layer_collection_objects_select(struct ViewLayer *view_layer, struct LayerCollection *lc, bool deselect); @@ -125,28 +205,54 @@ bool BKE_layer_collection_has_selected_objects(struct ViewLayer *view_layer, bool BKE_layer_collection_has_layer_collection(struct LayerCollection *lc_parent, struct LayerCollection *lc_child); +/** + * Update after toggling visibility of an object base. + */ void BKE_base_set_visible(struct Scene *scene, struct ViewLayer *view_layer, struct Base *base, bool extend); bool BKE_base_is_visible(const struct View3D *v3d, const struct Base *base); bool BKE_object_is_visible_in_viewport(const struct View3D *v3d, const struct Object *ob); +/** + * Isolate the collection - hide all other collections but this one. + * Make sure to show all the direct parents and all children of the layer collection as well. + * When extending we simply show the collections and its direct family. + * + * If the collection or any of its parents is disabled, make it enabled. + * Don't change the children disable state though. + */ void BKE_layer_collection_isolate_global(struct Scene *scene, struct ViewLayer *view_layer, struct LayerCollection *lc, bool extend); +/** + * Isolate the collection locally + * + * Same as #BKE_layer_collection_isolate_local but for a viewport + */ void BKE_layer_collection_isolate_local(struct ViewLayer *view_layer, const struct View3D *v3d, struct LayerCollection *lc, bool extend); +/** + * Hide/show all the elements of a collection. + * Don't change the collection children enable/disable state, + * but it may change it for the collection itself. + */ void BKE_layer_collection_set_visible(struct ViewLayer *view_layer, struct LayerCollection *lc, const bool visible, const bool hierarchy); void BKE_layer_collection_set_flag(struct LayerCollection *lc, const int flag, const bool value); -/* evaluation */ +/* Evaluation. */ +/** + * Applies object's restrict flags on top of flags coming from the collection + * and stores those in `base->flag`. #BASE_VISIBLE_DEPSGRAPH ignores viewport flags visibility + * (i.e., restriction and local collection). + */ void BKE_base_eval_flags(struct Base *base); void BKE_layer_eval_view_layer_indexed(struct Depsgraph *depsgraph, @@ -380,6 +486,13 @@ struct Object **BKE_view_layer_array_selected_objects_params( uint *r_len, const struct ObjectsInViewLayerParams *params); +/** + * Use this in rare cases we need to detect a pair of objects (active, selected). + * This returns the other non-active selected object. + * + * Returns NULL with it finds multiple other selected objects + * as behavior in this case would be random from the user perspective. + */ struct Object *BKE_view_layer_non_active_selected_object(struct ViewLayer *view_layer, const struct View3D *v3d); @@ -451,9 +564,20 @@ bool BKE_view_layer_filter_edit_mesh_has_edges(const struct Object *ob, void *us struct ViewLayerAOV *BKE_view_layer_add_aov(struct ViewLayer *view_layer); void BKE_view_layer_remove_aov(struct ViewLayer *view_layer, struct ViewLayerAOV *aov); void BKE_view_layer_set_active_aov(struct ViewLayer *view_layer, struct ViewLayerAOV *aov); +/** + * Update the naming and conflicts of the AOVs. + * + * Name must be unique between all AOVs. + * Conflicts with render passes will show a conflict icon. Reason is that switching a render + * engine or activating a render pass could lead to other conflicts that wouldn't be that clear + * for the user. + */ void BKE_view_layer_verify_aov(struct RenderEngine *engine, struct Scene *scene, struct ViewLayer *view_layer); +/** + * Check if the given view layer has at least one valid AOV. + */ bool BKE_view_layer_has_valid_aov(struct ViewLayer *view_layer); struct ViewLayer *BKE_view_layer_find_with_aov(struct Scene *scene, struct ViewLayerAOV *view_layer_aov); diff --git a/source/blender/blenkernel/BKE_lib_id.h b/source/blender/blenkernel/BKE_lib_id.h index 359fb72534a..34339c4ff9f 100644 --- a/source/blender/blenkernel/BKE_lib_id.h +++ b/source/blender/blenkernel/BKE_lib_id.h @@ -62,21 +62,65 @@ struct PointerRNA; struct PropertyRNA; struct bContext; +/** + * Get allocation size of a given data-block type and optionally allocation name. + */ size_t BKE_libblock_get_alloc_info(short type, const char **name); +/** + * Allocates and returns memory of the right size for the specified block type, + * initialized to zero. + */ void *BKE_libblock_alloc_notest(short type) ATTR_WARN_UNUSED_RESULT; +/** + * Allocates and returns a block of the specified type, with the specified name + * (adjusted as necessary to ensure uniqueness), and appended to the specified list. + * The user count is set to 1, all other content (apart from name and links) being + * initialized to zero. + */ void *BKE_libblock_alloc(struct Main *bmain, short type, const char *name, const int flag) ATTR_WARN_UNUSED_RESULT; +/** + * Initialize an ID of given type, such that it has valid 'empty' data. + * ID is assumed to be just calloc'ed. + */ void BKE_libblock_init_empty(struct ID *id) ATTR_NONNULL(1); /* *** ID's session_uuid management. *** */ -/* When an ID's uuid is of that value, it is unset/invalid (e.g. for runtime IDs, etc.). */ +/** + * When an ID's uuid is of that value, it is unset/invalid (e.g. for runtime IDs, etc.). + */ #define MAIN_ID_SESSION_UUID_UNSET 0 +/** + * Generate a session-wise uuid for the given \a id. + * + * \note "session-wise" here means while editing a given .blend file. Once a new .blend file is + * loaded or created, undo history is cleared/reset, and so is the uuid counter. + */ void BKE_lib_libblock_session_uuid_ensure(struct ID *id); +/** + * Re-generate a new session-wise uuid for the given \a id. + * + * \warning This has a few very specific use-cases, no other usage is expected currently: + * - To handle UI-related data-blocks that are kept across new file reading, when we do keep + * existing UI. + * - For IDs that are made local without needing any copying. + */ void BKE_lib_libblock_session_uuid_renew(struct ID *id); +/** + * Generic helper to create a new empty data-block of given type in given \a bmain database. + * + * \param name: can be NULL, in which case we get default name for this ID type. + */ void *BKE_id_new(struct Main *bmain, const short type, const char *name); +/** + * Generic helper to create a new temporary empty data-block of given type, + * *outside* of any Main database. + * + * \param name: can be NULL, in which case we get default name for this ID type. + */ void *BKE_id_new_nomain(const short type, const char *name); /** @@ -159,10 +203,20 @@ void BKE_libblock_copy_ex(struct Main *bmain, const struct ID *id, struct ID **r_newid, const int orig_flag); +/** + * Used everywhere in blenkernel. + */ void *BKE_libblock_copy(struct Main *bmain, const struct ID *id) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(); +/** + * Sets the name of a block to name, suitably adjusted for uniqueness. + */ void BKE_libblock_rename(struct Main *bmain, struct ID *id, const char *name) ATTR_NONNULL(); +/** + * Use after setting the ID's name + * When name exists: call 'new_id' + */ void BLI_libblock_ensure_unique_name(struct Main *bmain, const char *name) ATTR_NONNULL(); struct ID *BKE_libblock_find_name(struct Main *bmain, @@ -216,17 +270,70 @@ enum { void BKE_libblock_free_datablock(struct ID *id, const int flag) ATTR_NONNULL(); void BKE_libblock_free_data(struct ID *id, const bool do_id_user) ATTR_NONNULL(); +/** + * In most cases #BKE_id_free_ex handles this, when lower level functions are called directly + * this function will need to be called too, if Python has access to the data. + * + * ID data-blocks such as #Material.nodetree are not stored in #Main. + */ void BKE_libblock_free_data_py(struct ID *id); +/** + * Complete ID freeing, extended version for corner cases. + * Can override default (and safe!) freeing process, to gain some speed up. + * + * At that point, given id is assumed to not be used by any other data-block already + * (might not be actually true, in case e.g. several inter-related IDs get freed together...). + * However, they might still be using (referencing) other IDs, this code takes care of it if + * #LIB_TAG_NO_USER_REFCOUNT is not defined. + * + * \param bmain: #Main database containing the freed #ID, + * can be NULL in case it's a temp ID outside of any #Main. + * \param idv: Pointer to ID to be freed. + * \param flag: Set of \a LIB_ID_FREE_... flags controlling/overriding usual freeing process, + * 0 to get default safe behavior. + * \param use_flag_from_idtag: Still use freeing info flags from given #ID datablock, + * even if some overriding ones are passed in \a flag parameter. + */ void BKE_id_free_ex(struct Main *bmain, void *idv, int flag, const bool use_flag_from_idtag); +/** + * Complete ID freeing, should be usable in most cases (even for out-of-Main IDs). + * + * See #BKE_id_free_ex description for full details. + * + * \param bmain: Main database containing the freed ID, + * can be NULL in case it's a temp ID outside of any Main. + * \param idv: Pointer to ID to be freed. + */ void BKE_id_free(struct Main *bmain, void *idv); +/** + * Not really a freeing function by itself, + * it decrements usercount of given id, and only frees it if it reaches 0. + */ void BKE_id_free_us(struct Main *bmain, void *idv) ATTR_NONNULL(); +/** + * Properly delete a single ID from given \a bmain database. + */ void BKE_id_delete(struct Main *bmain, void *idv) ATTR_NONNULL(); +/** + * Properly delete all IDs tagged with \a LIB_TAG_DOIT, in given \a bmain database. + * + * This is more efficient than calling #BKE_id_delete repetitively on a large set of IDs + * (several times faster when deleting most of the IDs at once). + * + * \warning Considered experimental for now, seems to be working OK but this is + * risky code in a complicated area. + * \return Number of deleted datablocks. + */ size_t BKE_id_multi_tagged_delete(struct Main *bmain) ATTR_NONNULL(); +/** + * Add a 'NO_MAIN' data-block to given main (also sets usercounts of its IDs if needed). + */ void BKE_libblock_management_main_add(struct Main *bmain, void *idv); +/** Remove a data-block from given main (set it to 'NO_MAIN' status). */ void BKE_libblock_management_main_remove(struct Main *bmain, void *idv); void BKE_libblock_management_usercounts_set(struct Main *bmain, void *idv); @@ -234,10 +341,23 @@ void BKE_libblock_management_usercounts_clear(struct Main *bmain, void *idv); void id_lib_extern(struct ID *id); void id_lib_indirect_weak_link(struct ID *id); +/** + * Ensure we have a real user + * + * \note Now that we have flags, we could get rid of the 'fake_user' special case, + * flags are enough to ensure we always have a real user. + * However, #ID_REAL_USERS is used in several places outside of core lib.c, + * so think we can wait later to make this change. + */ void id_us_ensure_real(struct ID *id); void id_us_clear_real(struct ID *id); +/** + * Same as \a id_us_plus, but does not handle lib indirect -> extern. + * Only used by readfile.c so far, but simpler/safer to keep it here nonetheless. + */ void id_us_plus_no_lib(struct ID *id); void id_us_plus(struct ID *id); +/* decrements the user count for *id. */ void id_us_min(struct ID *id); void id_fake_user_set(struct ID *id); void id_fake_user_clear(struct ID *id); @@ -262,66 +382,212 @@ enum { LIB_ID_MAKELOCAL_OBJECT_NO_PROXY_CLEARING = 1 << 16, }; +/** + * Generic 'make local' function, works for most of data-block types. + */ void BKE_lib_id_make_local_generic(struct Main *bmain, struct ID *id, const int flags); +/** + * Calls the appropriate make_local method for the block, unless test is set. + * + * \note Always set #ID.newid pointer in case it gets duplicated. + * + * \param flags: Special flag used when making a whole library's content local, + * it needs specific handling. + * \return true is the ID has successfully been made local. + */ bool BKE_lib_id_make_local(struct Main *bmain, struct ID *id, const int flags); +/** + * \note Does *not* set #ID.newid pointer. + */ bool id_single_user(struct bContext *C, struct ID *id, struct PointerRNA *ptr, struct PropertyRNA *prop); bool BKE_id_copy_is_allowed(const struct ID *id); +/** + * Invokes the appropriate copy method for the block and returns the result in + * #ID.newid, unless test. Returns true if the block can be copied. + */ struct ID *BKE_id_copy(struct Main *bmain, const struct ID *id); +/** + * Generic entry point for copying a data-block (new API). + * + * \note Copy is generally only affecting the given data-block + * (no ID used by copied one will be affected, besides user-count). + * + * There are exceptions though: + * - Embedded IDs (root node trees and master collections) are always copied with their owner. + * - If #LIB_ID_COPY_ACTIONS is defined, actions used by animdata will be duplicated. + * - If #LIB_ID_COPY_SHAPEKEY is defined, shape-keys will be duplicated. + * - If #LIB_ID_CREATE_LOCAL is defined, root node trees will be deep-duplicated recursively. + * + * \note User-count of new copy is always set to 1. + * + * \param bmain: Main database, may be NULL only if LIB_ID_CREATE_NO_MAIN is specified. + * \param id: Source data-block. + * \param r_newid: Pointer to new (copied) ID pointer, may be NULL. + * Used to allow copying into already allocated memory. + * \param flag: Set of copy options, see `DNA_ID.h` enum for details + * (leave to zero for default, full copy). + * \return NULL when copying that ID type is not supported, the new copy otherwise. + */ struct ID *BKE_id_copy_ex(struct Main *bmain, const struct ID *id, struct ID **r_newid, const int flag); +/** + * Invokes the appropriate copy method for the block and returns the result in + * newid, unless test. Returns true if the block can be copied. + */ struct ID *BKE_id_copy_for_duplicate(struct Main *bmain, struct ID *id, const uint duplicate_flags, const int copy_flags); +/** + * Does a mere memory swap over the whole IDs data (including type-specific memory). + * \note Most internal ID data itself is not swapped (only IDProperties are). + * + * \param bmain: May be NULL, in which case there will be no remapping of internal pointers to + * itself. + */ void BKE_lib_id_swap(struct Main *bmain, struct ID *id_a, struct ID *id_b); +/** + * Does a mere memory swap over the whole IDs data (including type-specific memory). + * \note All internal ID data itself is also swapped. + * + * \param bmain: May be NULL, in which case there will be no remapping of internal pointers to + * itself. + */ void BKE_lib_id_swap_full(struct Main *bmain, struct ID *id_a, struct ID *id_b); +/** + * Sort given \a id into given \a lb list, using case-insensitive comparison of the id names. + * + * \note All other IDs beside given one are assumed already properly sorted in the list. + * + * \param id_sorting_hint: Ignored if NULL. Otherwise, used to check if we can insert \a id + * immediately before or after that pointer. It must always be into given \a lb list. + */ void id_sort_by_name(struct ListBase *lb, struct ID *id, struct ID *id_sorting_hint); +/** + * Expand ID usages of given id as 'extern' (and no more indirect) linked data. + * Used by ID copy/make_local functions. + */ void BKE_lib_id_expand_local(struct Main *bmain, struct ID *id, const int flags); +/** + * Ensures given ID has a unique name in given listbase. + * + * Only for local IDs (linked ones already have a unique ID in their library). + * + * \param do_linked_data: if true, also ensure a unique name in case the given \a id is linked + * (otherwise, just ensure that it is properly sorted). + * + * \return true if a new name had to be created. + */ bool BKE_id_new_name_validate(struct ListBase *lb, struct ID *id, const char *name, const bool do_linked_data) ATTR_NONNULL(1, 2); +/** + * Pull an ID out of a library (make it local). Only call this for IDs that + * don't have other library users. + * + * \param flags: Same set of `LIB_ID_MAKELOCAL_` flags as passed to #BKE_lib_id_make_local. + */ void BKE_lib_id_clear_library_data(struct Main *bmain, struct ID *id, const int flags); -/* Affect whole Main database. */ +/** + * Clear or set given tags for all ids of given type in `bmain` (runtime tags). + * + * \note Affect whole Main database. + */ void BKE_main_id_tag_idcode(struct Main *mainvar, const short type, const int tag, const bool value); +/** + * Clear or set given tags for all ids in listbase (runtime tags). + */ void BKE_main_id_tag_listbase(struct ListBase *lb, const int tag, const bool value); +/** + * Clear or set given tags for all ids in bmain (runtime tags). + */ void BKE_main_id_tag_all(struct Main *mainvar, const int tag, const bool value); +/** + * Clear or set given flags for all ids in listbase (persistent flags). + */ void BKE_main_id_flag_listbase(struct ListBase *lb, const int flag, const bool value); +/** + * Clear or set given flags for all ids in bmain (persistent flags). + */ void BKE_main_id_flag_all(struct Main *bmain, const int flag, const bool value); +/** + * Next to indirect usage in `readfile.c/writefile.c` also in `editobject.c`, `scene.c`. + */ void BKE_main_id_newptr_and_tag_clear(struct Main *bmain); void BKE_main_id_refcount_recompute(struct Main *bmain, const bool do_linked_only); void BKE_main_lib_objects_recalc_all(struct Main *bmain); -/* Only for repairing files via versioning, avoid for general use. */ +/** + * Only for repairing files via versioning, avoid for general use. + */ void BKE_main_id_repair_duplicate_names_listbase(struct ListBase *lb); #define MAX_ID_FULL_NAME (64 + 64 + 3 + 1) /* 64 is MAX_ID_NAME - 2 */ #define MAX_ID_FULL_NAME_UI (MAX_ID_FULL_NAME + 3) /* Adds 'keycode' two letters at beginning. */ +/** + * Generate full name of the data-block (without ID code, but with library if any). + * + * \note Result is unique to a given ID type in a given Main database. + * + * \param name: An allocated string of minimal length #MAX_ID_FULL_NAME, + * will be filled with generated string. + * \param separator_char: Character to use for separating name and library name. + * Can be 0 to use default (' '). + */ void BKE_id_full_name_get(char name[MAX_ID_FULL_NAME], const struct ID *id, char separator_char); +/** + * Generate full name of the data-block (without ID code, but with library if any), + * with a 2 to 3 character prefix prepended indicating whether it comes from a library, + * is overriding, has a fake or no user, etc. + * + * \note Result is unique to a given ID type in a given Main database. + * + * \param name: An allocated string of minimal length #MAX_ID_FULL_NAME_UI, + * will be filled with generated string. + * \param separator_char: Character to use for separating name and library name. + * Can be 0 to use default (' '). + * \param r_prefix_len: The length of the prefix added. + */ void BKE_id_full_name_ui_prefix_get(char name[MAX_ID_FULL_NAME_UI], const struct ID *id, const bool add_lib_hint, char separator_char, int *r_prefix_len); +/** + * Generate a concatenation of ID name (including two-chars type code) and its lib name, if any. + * + * \return A unique allocated string key for any ID in the whole Main database. + */ char *BKE_id_to_unique_string_key(const struct ID *id); +/** + * Make linked data-blocks local. + * + * \param bmain: Almost certainly global main. + * \param lib: If not NULL, only make local data-blocks from this library. + * \param untagged_only: If true, only make local data-blocks not tagged with + * #LIB_TAG_PRE_EXISTING. + * \param set_fake: If true, set fake user on all localized data-blocks + * (except group and objects ones). + */ void BKE_library_make_local(struct Main *bmain, const struct Library *lib, struct GHash *old_to_new_ids, @@ -331,11 +597,22 @@ void BKE_library_make_local(struct Main *bmain, void BKE_id_tag_set_atomic(struct ID *id, int tag); void BKE_id_tag_clear_atomic(struct ID *id, int tag); +/** + * Check that given ID pointer actually is in G_MAIN. + * Main intended use is for debug asserts in places we cannot easily get rid of #G_Main. + */ bool BKE_id_is_in_global_main(struct ID *id); bool BKE_id_can_be_asset(const struct ID *id); +/** + * Returns ordered list of data-blocks for display in the UI. + * Result is list of #LinkData of IDs that must be freed. + */ void BKE_id_ordered_list(struct ListBase *ordered_lb, const struct ListBase *lb); +/** + * Reorder ID in the list, before or after the "relative" ID. + */ void BKE_id_reorder(const struct ListBase *lb, struct ID *id, struct ID *relative, bool after); void BKE_id_blend_write(struct BlendWriter *writer, struct ID *id); @@ -343,6 +620,12 @@ void BKE_id_blend_write(struct BlendWriter *writer, struct ID *id); #define IS_TAGGED(_id) ((_id) && (((ID *)_id)->tag & LIB_TAG_DOIT)) /* lib_id_eval.c */ + +/** + * Copy relatives parameters, from `id` to `id_cow`. + * Use handle the #ID_RECALC_PARAMETERS tag. + * \note Keep in sync with #ID_TYPE_SUPPORTS_PARAMS_WITHOUT_COW. + */ void BKE_id_eval_properties_copy(struct ID *id_cow, struct ID *id); #ifdef __cplusplus diff --git a/source/blender/blenkernel/BKE_lib_override.h b/source/blender/blenkernel/BKE_lib_override.h index b94a1b33606..636d7842154 100644 --- a/source/blender/blenkernel/BKE_lib_override.h +++ b/source/blender/blenkernel/BKE_lib_override.h @@ -57,35 +57,120 @@ struct ReportList; struct Scene; struct ViewLayer; +/** + * Initialize empty overriding of \a reference_id by \a local_id. + */ struct IDOverrideLibrary *BKE_lib_override_library_init(struct ID *local_id, struct ID *reference_id); +/** + * Shallow or deep copy of a whole override from \a src_id to \a dst_id. + */ void BKE_lib_override_library_copy(struct ID *dst_id, const struct ID *src_id, const bool do_full_copy); +/** + * Clear any overriding data from given \a override. + */ void BKE_lib_override_library_clear(struct IDOverrideLibrary *override, const bool do_id_user); +/** + * Free given \a override. + */ void BKE_lib_override_library_free(struct IDOverrideLibrary **override, const bool do_id_user); +/** + * Check if given ID has some override rules that actually indicate the user edited it. + */ bool BKE_lib_override_library_is_user_edited(struct ID *id); +/** + * Create an overridden local copy of linked reference. + */ struct ID *BKE_lib_override_library_create_from_id(struct Main *bmain, struct ID *reference_id, const bool do_tagged_remap); +/** + * Create overridden local copies of all tagged data-blocks in given Main. + * + * \note Set `id->newid` of overridden libs with newly created overrides, + * caller is responsible to clean those pointers before/after usage as needed. + * + * \note By default, it will only remap newly created local overriding data-blocks between + * themselves, to avoid 'enforcing' those overrides into all other usages of the linked data in + * main. You can add more local IDs to be remapped to use new overriding ones by setting their + * LIB_TAG_DOIT tag. + * + * \param reference_library: the library from which the linked data being overridden come from + * (i.e. the library of the linked reference ID). + * + * \param do_no_main: Create the new override data outside of Main database. + * Used for resyncing of linked overrides. + * + * \return \a true on success, \a false otherwise. + */ bool BKE_lib_override_library_create_from_tag(struct Main *bmain, const struct Library *reference_library, const bool do_no_main); +/** + * Advanced 'smart' function to create fully functional overrides. + * + * \note Currently it only does special things if given \a id_root is an object or collection, more + * specific behaviors may be added in the future for other ID types. + * + * \note It will override all IDs tagged with \a LIB_TAG_DOIT, and it does not clear that tag at + * its beginning, so caller code can add extra data-blocks to be overridden as well. + * + * \param view_layer: the active view layer to search instantiated collections in, can be NULL (in + * which case \a scene's master collection children hierarchy is used instead). + * \param id_root: The root ID to create an override from. + * \param id_reference: Some reference ID used to do some post-processing after overrides have been + * created, may be NULL. Typically, the Empty object instantiating the linked collection we + * override, currently. + * \param r_id_root_override: if not NULL, the override generated for the given \a id_root. + * \return true if override was successfully created. + */ bool BKE_lib_override_library_create(struct Main *bmain, struct Scene *scene, struct ViewLayer *view_layer, struct ID *id_root, struct ID *id_reference, struct ID **r_id_root_override); +/** + * Create a library override template. + */ bool BKE_lib_override_library_template_create(struct ID *id); +/** + * Convert a given proxy object into a library override. + * + * \note This is a thin wrapper around \a BKE_lib_override_library_create, only extra work is to + * actually convert the proxy itself into an override first. + * + * \param view_layer: the active view layer to search instantiated collections in, can be NULL (in + * which case \a scene's master collection children hierarchy is used instead). + * \return true if override was successfully created. + */ bool BKE_lib_override_library_proxy_convert(struct Main *bmain, struct Scene *scene, struct ViewLayer *view_layer, struct Object *ob_proxy); +/** + * Convert all proxy objects into library overrides. + * + * \note Only affects local proxies, linked ones are not affected. + * + * \param view_layer: the active view layer to search instantiated collections in, can be NULL (in + * which case \a scene's master collection children hierarchy is used instead). + */ void BKE_lib_override_library_main_proxy_convert(struct Main *bmain, struct BlendFileReadReport *reports); +/** + * Advanced 'smart' function to resync, re-create fully functional overrides up-to-date with linked + * data, from an existing override hierarchy. + * + * \param id_root: The root liboverride ID to resync from. + * \param view_layer: the active view layer to search instantiated collections in, can be NULL (in + * which case \a scene's master collection children hierarchy is used instead). + * \return true if override was successfully resynced. + */ bool BKE_lib_override_library_resync(struct Main *bmain, struct Scene *scene, struct ViewLayer *view_layer, @@ -94,26 +179,76 @@ bool BKE_lib_override_library_resync(struct Main *bmain, const bool do_hierarchy_enforce, const bool do_post_process, struct BlendFileReadReport *reports); +/** + * Detect and handle required resync of overrides data, when relations between reference linked IDs + * have changed. + * + * This is a fairly complex and costly operation, typically it should be called after + * #BKE_lib_override_library_main_update, which would already detect and tag a lot of cases. + * + * This function will first detect the remaining cases requiring a resync (namely, either when an + * existing linked ID that did not require to be overridden before now would be, or when new IDs + * are added to the hierarchy). + * + * Then it will handle the resync of necessary IDs (through calls to + * #BKE_lib_override_library_resync). + * + * \param view_layer: the active view layer to search instantiated collections in, can be NULL (in + * which case \a scene's master collection children hierarchy is used instead). + */ void BKE_lib_override_library_main_resync(struct Main *bmain, struct Scene *scene, struct ViewLayer *view_layer, struct BlendFileReadReport *reports); +/** + * Advanced 'smart' function to delete library overrides (including their existing override + * hierarchy) and remap their usages to their linked reference IDs. + * + * \note All IDs tagged with #LIB_TAG_DOIT will be deleted. + * + * \param id_root: The root liboverride ID to delete. + */ void BKE_lib_override_library_delete(struct Main *bmain, struct ID *id_root); +/** + * Make given ID fully local. + * + * \note Only differs from lower-level #BKE_lib_override_library_free in infamous embedded ID + * cases. + */ void BKE_lib_override_library_make_local(struct ID *id); +/** + * Find override property from given RNA path, if it exists. + */ struct IDOverrideLibraryProperty *BKE_lib_override_library_property_find( struct IDOverrideLibrary *override, const char *rna_path); +/** + * Find override property from given RNA path, or create it if it does not exist. + */ struct IDOverrideLibraryProperty *BKE_lib_override_library_property_get( struct IDOverrideLibrary *override, const char *rna_path, bool *r_created); +/** + * Remove and free given \a override_property from given ID \a override. + */ void BKE_lib_override_library_property_delete(struct IDOverrideLibrary *override, struct IDOverrideLibraryProperty *override_property); +/** + * Get the RNA-property matching the \a library_prop override property. Used for UI to query + * additional data about the overridden property (e.g. UI name). + * + * \param idpoin: Pointer to the override ID. + * \param library_prop: The library override property to find the matching RNA property for. + */ bool BKE_lib_override_rna_property_find(struct PointerRNA *idpoin, const struct IDOverrideLibraryProperty *library_prop, struct PointerRNA *r_override_poin, struct PropertyRNA **r_override_prop); +/** + * Find override property operation from given sub-item(s), if it exists. + */ struct IDOverrideLibraryPropertyOperation *BKE_lib_override_library_property_operation_find( struct IDOverrideLibraryProperty *override_property, const char *subitem_refname, @@ -122,6 +257,9 @@ struct IDOverrideLibraryPropertyOperation *BKE_lib_override_library_property_ope const int subitem_locindex, const bool strict, bool *r_strict); +/** + * Find override property operation from given sub-item(s), or create it if it does not exist. + */ struct IDOverrideLibraryPropertyOperation *BKE_lib_override_library_property_operation_get( struct IDOverrideLibraryProperty *override_property, const short operation, @@ -132,10 +270,16 @@ struct IDOverrideLibraryPropertyOperation *BKE_lib_override_library_property_ope const bool strict, bool *r_strict, bool *r_created); +/** + * Remove and free given \a override_property_operation from given ID \a override_property. + */ void BKE_lib_override_library_property_operation_delete( struct IDOverrideLibraryProperty *override_property, struct IDOverrideLibraryPropertyOperation *override_property_operation); +/** + * Validate that required data for a given operation are available. + */ bool BKE_lib_override_library_property_operation_operands_validate( struct IDOverrideLibraryPropertyOperation *override_property_operation, struct PointerRNA *ptr_dst, @@ -145,34 +289,107 @@ bool BKE_lib_override_library_property_operation_operands_validate( struct PropertyRNA *prop_src, struct PropertyRNA *prop_storage); +/** + * Check against potential \a bmain. + */ void BKE_lib_override_library_validate(struct Main *bmain, struct ID *id, struct ReportList *reports); +/** + * Check against potential \a bmain. + */ void BKE_lib_override_library_main_validate(struct Main *bmain, struct ReportList *reports); +/** + * Check that status of local data-block is still valid against current reference one. + * + * It means that all overridable, but not overridden, properties' local values must be equal to + * reference ones. Clears #LIB_TAG_OVERRIDE_OK if they do not. + * + * This is typically used to detect whether some property has been changed in local and a new + * #IDOverrideProperty (of #IDOverridePropertyOperation) has to be added. + * + * \return true if status is OK, false otherwise. */ bool BKE_lib_override_library_status_check_local(struct Main *bmain, struct ID *local); +/** + * Check that status of reference data-block is still valid against current local one. + * + * It means that all non-overridden properties' local values must be equal to reference ones. + * Clears LIB_TAG_OVERRIDE_OK if they do not. + * + * This is typically used to detect whether some reference has changed and local + * needs to be updated against it. + * + * \return true if status is OK, false otherwise. */ bool BKE_lib_override_library_status_check_reference(struct Main *bmain, struct ID *local); +/** + * Compare local and reference data-blocks and create new override operations as needed, + * or reset to reference values if overriding is not allowed. + * + * \note Defining override operations is only mandatory before saving a `.blend` file on disk + * (not for undo!). + * Knowing that info at runtime is only useful for UI/UX feedback. + * + * \note This is by far the biggest operation (the more time-consuming) of the three so far, + * since it has to go over all properties in depth (all overridable ones at least). + * Generating differential values and applying overrides are much cheaper. + * + * \return true if any library operation was created. + */ bool BKE_lib_override_library_operations_create(struct Main *bmain, struct ID *local); +/** + * Check all overrides from given \a bmain and create/update overriding operations as needed. + */ bool BKE_lib_override_library_main_operations_create(struct Main *bmain, const bool force_auto); +/** + * Reset all overrides in given \a id_root, while preserving ID relations. + */ void BKE_lib_override_library_id_reset(struct Main *bmain, struct ID *id_root); +/** + * Reset all overrides in given \a id_root and its dependencies, while preserving ID relations. + */ void BKE_lib_override_library_id_hierarchy_reset(struct Main *bmain, struct ID *id_root); +/** + * Set or clear given tag in all operations in that override property data. + */ void BKE_lib_override_library_operations_tag(struct IDOverrideLibraryProperty *override_property, const short tag, const bool do_set); +/** + * Set or clear given tag in all properties and operations in that override data. + */ void BKE_lib_override_library_properties_tag(struct IDOverrideLibrary *override, const short tag, const bool do_set); +/** + * Set or clear given tag in all properties and operations in that Main's ID override data. + */ void BKE_lib_override_library_main_tag(struct Main *bmain, const short tag, const bool do_set); +/** + * Remove all tagged-as-unused properties and operations from that ID override data. + */ void BKE_lib_override_library_id_unused_cleanup(struct ID *local); +/** + * Remove all tagged-as-unused properties and operations from that Main's ID override data. + */ void BKE_lib_override_library_main_unused_cleanup(struct Main *bmain); +/** + * Update given override from its reference (re-applying overridden properties). + */ void BKE_lib_override_library_update(struct Main *bmain, struct ID *local); +/** + * Update all overrides from given \a bmain. + */ void BKE_lib_override_library_main_update(struct Main *bmain); +/** + * In case an ID is used by another liboverride ID, user may not be allowed to delete it. + */ bool BKE_lib_override_library_id_is_user_deletable(struct Main *bmain, struct ID *id); /* Storage (.blend file writing) part. */ @@ -180,9 +397,22 @@ bool BKE_lib_override_library_id_is_user_deletable(struct Main *bmain, struct ID /* For now, we just use a temp main list. */ typedef struct Main OverrideLibraryStorage; +/** + * Initialize an override storage. + */ OverrideLibraryStorage *BKE_lib_override_library_operations_store_init(void); +/** + * Generate suitable 'write' data (this only affects differential override operations). + * + * Note that \a local ID is no more modified by this call, + * all extra data are stored in its temp \a storage_id copy. + */ struct ID *BKE_lib_override_library_operations_store_start( struct Main *bmain, OverrideLibraryStorage *override_storage, struct ID *local); +/** + * Restore given ID modified by #BKE_lib_override_library_operations_store_start, to its + * original state. + */ void BKE_lib_override_library_operations_store_end(OverrideLibraryStorage *override_storage, struct ID *local); void BKE_lib_override_library_operations_store_finalize(OverrideLibraryStorage *override_storage); diff --git a/source/blender/blenkernel/BKE_lib_query.h b/source/blender/blenkernel/BKE_lib_query.h index 30c742e3af6..91f72cc0762 100644 --- a/source/blender/blenkernel/BKE_lib_query.h +++ b/source/blender/blenkernel/BKE_lib_query.h @@ -143,6 +143,10 @@ enum { typedef struct LibraryForeachIDData LibraryForeachIDData; +/** + * Check whether current iteration over ID usages should be stopped or not. + * \return true if the iteration should be stopped, false otherwise. + */ bool BKE_lib_query_foreachid_iter_stop(struct LibraryForeachIDData *data); void BKE_lib_query_foreachid_process(struct LibraryForeachIDData *data, struct ID **id_pp, @@ -181,25 +185,77 @@ int BKE_lib_query_foreachid_process_callback_flag_override(struct LibraryForeach } \ ((void)0) +/** + * Process embedded ID pointers (root node-trees, master collections, ...). + * + * Those require specific care, since they are technically sub-data of their owner, yet in some + * cases they still behave as regular IDs. + */ void BKE_library_foreach_ID_embedded(struct LibraryForeachIDData *data, struct ID **id_pp); void BKE_lib_query_idpropertiesForeachIDLink_callback(struct IDProperty *id_prop, void *user_data); -/* Loop over all of the ID's this datablock links to. */ +/** + * Loop over all of the ID's this data-block links to. + */ void BKE_library_foreach_ID_link( struct Main *bmain, struct ID *id, LibraryIDLinkCallback callback, void *user_data, int flag); +/** + * Re-usable function, use when replacing ID's. + */ void BKE_library_update_ID_link_user(struct ID *id_dst, struct ID *id_src, const int cb_flag); +/** + * Return the number of times given \a id_user uses/references \a id_used. + * + * \note This only checks for pointer references of an ID, shallow usages + * (like e.g. by RNA paths, as done for FCurves) are not detected at all. + * + * \param id_user: the ID which is supposed to use (reference) \a id_used. + * \param id_used: the ID which is supposed to be used (referenced) by \a id_user. + * \return the number of direct usages/references of \a id_used by \a id_user. + */ int BKE_library_ID_use_ID(struct ID *id_user, struct ID *id_used); +/** + * Say whether given \a id_owner may use (in any way) a data-block of \a id_type_used. + * + * This is a 'simplified' abstract version of #BKE_library_foreach_ID_link() above, + * quite useful to reduce useless iterations in some cases. + */ bool BKE_library_id_can_use_idtype(struct ID *id_owner, const short id_type_used); +/** + * Check whether given ID is used locally (i.e. by another non-linked ID). + */ bool BKE_library_ID_is_locally_used(struct Main *bmain, void *idv); +/** + * Check whether given ID is used indirectly (i.e. by another linked ID). + */ bool BKE_library_ID_is_indirectly_used(struct Main *bmain, void *idv); +/** + * Combine #BKE_library_ID_is_locally_used() and #BKE_library_ID_is_indirectly_used() + * in a single call. + */ void BKE_library_ID_test_usages(struct Main *bmain, void *idv, bool *is_used_local, bool *is_used_linked); +/** + * Tag all unused IDs (a.k.a 'orphaned'). + * + * By default only tag IDs with `0` user count. + * If `do_tag_recursive` is set, it will check dependencies to detect all IDs that are not actually + * used in current file, including 'archipelagos` (i.e. set of IDs referencing each other in + * loops, but without any 'external' valid usages. + * + * Valid usages here are defined as ref-counting usages, which are not towards embedded or + * loop-back data. + * + * \param r_num_tagged: If non-NULL, must be a zero-initialized array of #INDEX_ID_MAX integers. + * Number of tagged-as-unused IDs is then set for each type, and as total in + * #INDEX_ID_NULL item. + */ void BKE_lib_query_unused_ids_tag(struct Main *bmain, const int tag, const bool do_local_ids, @@ -207,7 +263,24 @@ void BKE_lib_query_unused_ids_tag(struct Main *bmain, const bool do_tag_recursive, int *r_num_tagged); +/** + * Detect orphaned linked data blocks (i.e. linked data not used (directly or indirectly) + * in any way by any local data), including complex cases like 'linked archipelagoes', i.e. + * linked data-blocks that use each other in loops, + * which prevents their deletion by 'basic' usage checks. + * + * \param do_init_tag: if \a true, all linked data are checked, if \a false, + * only linked data-blocks already tagged with #LIB_TAG_DOIT are checked. + */ void BKE_library_unused_linked_data_set_tag(struct Main *bmain, const bool do_init_tag); +/** + * Untag linked data blocks used by other untagged linked data-blocks. + * Used to detect data-blocks that we can forcefully make local + * (instead of copying them to later get rid of original): + * All data-blocks we want to make local are tagged by caller, + * after this function has ran caller knows data-blocks still tagged can directly be made local, + * since they are only used by other data-blocks that will also be made fully local. + */ void BKE_library_indirectly_used_data_tag_clear(struct Main *bmain); #ifdef __cplusplus diff --git a/source/blender/blenkernel/BKE_lib_remap.h b/source/blender/blenkernel/BKE_lib_remap.h index 5e154459a6c..f560780424e 100644 --- a/source/blender/blenkernel/BKE_lib_remap.h +++ b/source/blender/blenkernel/BKE_lib_remap.h @@ -97,8 +97,13 @@ enum { ID_REMAP_FORCE_OBDATA_IN_EDITMODE = 1 << 9, }; -/* NOTE: Requiring new_id to be non-null, this *may* not be the case ultimately, - * but makes things simpler for now. */ +/** + * Replace all references in given Main to \a old_id by \a new_id + * (if \a new_id is NULL, it unlinks \a old_id). + * + * \note Requiring new_id to be non-null, this *may* not be the case ultimately, + * but makes things simpler for now. + */ void BKE_libblock_remap_locked(struct Main *bmain, void *old_idv, void *new_idv, @@ -106,17 +111,42 @@ void BKE_libblock_remap_locked(struct Main *bmain, void BKE_libblock_remap(struct Main *bmain, void *old_idv, void *new_idv, const short remap_flags) ATTR_NONNULL(1, 2); +/** + * Unlink given \a id from given \a bmain + * (does not touch to indirect, i.e. library, usages of the ID). + * + * \param do_flag_never_null: If true, all IDs using \a idv in a 'non-NULL' way are flagged by + * #LIB_TAG_DOIT flag (quite obviously, 'non-NULL' usages can never be unlinked by this function). + */ void BKE_libblock_unlink(struct Main *bmain, void *idv, const bool do_flag_never_null, const bool do_skip_indirect) ATTR_NONNULL(); +/** + * Similar to libblock_remap, but only affects IDs used by given \a idv ID. + * + * \param old_idv: Unlike BKE_libblock_remap, can be NULL, + * in which case all ID usages by given \a idv will be cleared. + * \param us_min_never_null: If \a true and new_id is NULL, + * 'NEVER_NULL' ID usages keep their old id, but this one still gets its user count decremented + * (needed when given \a idv is going to be deleted right after being unlinked). + */ void BKE_libblock_relink_ex(struct Main *bmain, void *idv, void *old_idv, void *new_idv, const short remap_flags) ATTR_NONNULL(1, 2); +/** + * Remaps ID usages of given ID to their `id->newid` pointer if not None, and proceeds recursively + * in the dependency tree of IDs for all data-blocks tagged with `LIB_TAG_NEW`. + * + * \note `LIB_TAG_NEW` is cleared. + * + * Very specific usage, not sure we'll keep it on the long run, + * currently only used in Object/Collection duplication code. + */ void BKE_libblock_relink_to_newid(struct Main *bmain, struct ID *id, const int remap_flag) ATTR_NONNULL(); diff --git a/source/blender/blenkernel/BKE_linestyle.h b/source/blender/blenkernel/BKE_linestyle.h index 1236a96c8d9..eb17ff78688 100644 --- a/source/blender/blenkernel/BKE_linestyle.h +++ b/source/blender/blenkernel/BKE_linestyle.h @@ -80,6 +80,10 @@ int BKE_linestyle_thickness_modifier_remove(FreestyleLineStyle *linestyle, int BKE_linestyle_geometry_modifier_remove(FreestyleLineStyle *linestyle, LineStyleModifier *modifier); +/** + * Reinsert \a modifier in modifier list with an offset of \a direction. + * \return if position of \a modifier has changed. + */ bool BKE_linestyle_color_modifier_move(FreestyleLineStyle *linestyle, LineStyleModifier *modifier, int direction); diff --git a/source/blender/blenkernel/BKE_main.h b/source/blender/blenkernel/BKE_main.h index 9ded97e0003..0976671c64c 100644 --- a/source/blender/blenkernel/BKE_main.h +++ b/source/blender/blenkernel/BKE_main.h @@ -201,40 +201,103 @@ typedef struct Main { struct Main *BKE_main_new(void); void BKE_main_free(struct Main *mainvar); +/** + * Check whether given `bmain` is empty or contains some IDs. + */ bool BKE_main_is_empty(struct Main *bmain); void BKE_main_lock(struct Main *bmain); void BKE_main_unlock(struct Main *bmain); +/** Generate the mappings between used IDs and their users, and vice-versa. */ void BKE_main_relations_create(struct Main *bmain, const short flag); void BKE_main_relations_free(struct Main *bmain); +/** Set or clear given `tag` in all relation entries of given `bmain`. */ void BKE_main_relations_tag_set(struct Main *bmain, const eMainIDRelationsEntryTags tag, const bool value); +/** + * Create a #GSet storing all IDs present in given \a bmain, by their pointers. + * + * \param gset: If not NULL, given GSet will be extended with IDs from given \a bmain, + * instead of creating a new one. + */ struct GSet *BKE_main_gset_create(struct Main *bmain, struct GSet *gset); -/* - * Temporary runtime API to allow re-using local (already appended) IDs instead of appending a new - * copy again. - */ +/* Temporary runtime API to allow re-using local (already appended) + * IDs instead of appending a new copy again. */ +/** + * Generate a mapping between 'library path' of an ID + * (as a pair (relative blend file path, id name)), and a current local ID, if any. + * + * This uses the information stored in `ID.library_weak_reference`. + */ struct GHash *BKE_main_library_weak_reference_create(struct Main *bmain) ATTR_NONNULL(); +/** + * Destroy the data generated by #BKE_main_library_weak_reference_create. + */ void BKE_main_library_weak_reference_destroy(struct GHash *library_weak_reference_mapping) ATTR_NONNULL(); +/** + * Search for a local ID matching the given linked ID reference. + * + * \param library_weak_reference_mapping: the mapping data generated by + * #BKE_main_library_weak_reference_create. + * \param library_relative_path: the path of a blend file library (relative to current working + * one). + * \param library_id_name: the full ID name, including the leading two chars encoding the ID + * type. + */ struct ID *BKE_main_library_weak_reference_search_item( struct GHash *library_weak_reference_mapping, const char *library_filepath, const char *library_id_name) ATTR_NONNULL(); +/** + * Add the given ID weak library reference to given local ID and the runtime mapping. + * + * \param library_weak_reference_mapping: the mapping data generated by + * #BKE_main_library_weak_reference_create. + * \param library_relative_path: the path of a blend file library (relative to current working + * one). + * \param library_id_name: the full ID name, including the leading two chars encoding the ID type. + * \param new_id: New local ID matching given weak reference. + */ void BKE_main_library_weak_reference_add_item(struct GHash *library_weak_reference_mapping, const char *library_filepath, const char *library_id_name, struct ID *new_id) ATTR_NONNULL(); +/** + * Update the status of the given ID weak library reference in current local IDs and the runtime + * mapping. + * + * This effectively transfers the 'ownership' of the given weak reference from `old_id` to + * `new_id`. + * + * \param library_weak_reference_mapping: the mapping data generated by + * #BKE_main_library_weak_reference_create. + * \param library_relative_path: the path of a blend file library (relative to current working + * one). + * \param library_id_name: the full ID name, including the leading two chars encoding the ID type. + * \param old_id: Existing local ID matching given weak reference. + * \param new_id: New local ID matching given weak reference. + */ void BKE_main_library_weak_reference_update_item(struct GHash *library_weak_reference_mapping, const char *library_filepath, const char *library_id_name, struct ID *old_id, struct ID *new_id) ATTR_NONNULL(); +/** + * Remove the given ID weak library reference from the given local ID and the runtime mapping. + * + * \param library_weak_reference_mapping: the mapping data generated by + * #BKE_main_library_weak_reference_create. + * \param library_relative_path: the path of a blend file library (relative to current working + * one). + * \param library_id_name: the full ID name, including the leading two chars encoding the ID type. + * \param old_id: Existing local ID matching given weak reference. + */ void BKE_main_library_weak_reference_remove_item(struct GHash *library_weak_reference_mapping, const char *library_filepath, const char *library_id_name, @@ -286,16 +349,57 @@ void BKE_main_library_weak_reference_remove_item(struct GHash *library_weak_refe } \ ((void)0) +/** + * Generates a raw .blend file thumbnail data from given image. + * + * \param bmain: If not NULL, also store generated data in this Main. + * \param img: ImBuf image to generate thumbnail data from. + * \return The generated .blend file raw thumbnail data. + */ struct BlendThumbnail *BKE_main_thumbnail_from_imbuf(struct Main *bmain, struct ImBuf *img); +/** + * Generates an image from raw .blend file thumbnail \a data. + * + * \param bmain: Use this bmain->blen_thumb data if given \a data is NULL. + * \param data: Raw .blend file thumbnail data. + * \return An ImBuf from given data, or NULL if invalid. + */ struct ImBuf *BKE_main_thumbnail_to_imbuf(struct Main *bmain, struct BlendThumbnail *data); +/** + * Generates an empty (black) thumbnail for given Main. + */ void BKE_main_thumbnail_create(struct Main *bmain); +/** + * Return file-path of given \a main. + */ const char *BKE_main_blendfile_path(const struct Main *bmain) ATTR_NONNULL(); +/** + * Return file-path of global main #G_MAIN. + * + * \warning Usage is not recommended, + * you should always try to get a valid Main pointer from context. + */ const char *BKE_main_blendfile_path_from_global(void); +/** + * \return A pointer to the \a ListBase of given \a bmain for requested \a type ID type. + */ struct ListBase *which_libbase(struct Main *bmain, short type); //#define INDEX_ID_MAX 41 +/** + * Put the pointers to all the #ListBase structs in given `bmain` into the `*lb[INDEX_ID_MAX]` + * array, and return the number of those for convenience. + * + * This is useful for generic traversal of all the blocks in a #Main (by traversing all the lists + * in turn), without worrying about block types. + * + * \param lb: Array of lists #INDEX_ID_MAX in length. + * + * \note The order of each ID type #ListBase in the array is determined by the `INDEX_ID_` + * enum definitions in `DNA_ID.h`. See also the #FOREACH_MAIN_ID_BEGIN macro in `BKE_main.h` + */ int set_listbasepointers(struct Main *main, struct ListBase *lb[]); #define MAIN_VERSION_ATLEAST(main, ver, subver) \ diff --git a/source/blender/blenkernel/BKE_main_idmap.h b/source/blender/blenkernel/BKE_main_idmap.h index ff69883f0fb..13ddcaa93ba 100644 --- a/source/blender/blenkernel/BKE_main_idmap.h +++ b/source/blender/blenkernel/BKE_main_idmap.h @@ -44,6 +44,17 @@ enum { MAIN_IDMAP_TYPE_UUID = 1 << 1, }; +/** + * Generate mapping from ID type/name to ID pointer for given \a bmain. + * + * \note When used during undo/redo, there is no guaranty that ID pointers from UI area are not + * pointing to freed memory (when some IDs have been deleted). To avoid crashes in those cases, one + * can provide the 'old' (aka current) Main database as reference. #BKE_main_idmap_lookup_id will + * then check that given ID does exist in \a old_bmain before trying to use it. + * + * \param create_valid_ids_set: If \a true, generate a reference to prevent freed memory accesses. + * \param old_bmain: If not NULL, its IDs will be added the valid references set. + */ struct IDNameLib_Map *BKE_main_idmap_create(struct Main *bmain, const bool create_valid_ids_set, struct Main *old_bmain, diff --git a/source/blender/blenkernel/BKE_mask.h b/source/blender/blenkernel/BKE_mask.h index 8e2f6e6f10c..2a2b080217c 100644 --- a/source/blender/blenkernel/BKE_mask.h +++ b/source/blender/blenkernel/BKE_mask.h @@ -56,16 +56,20 @@ typedef enum { MASK_HANDLE_MODE_INDIVIDUAL_HANDLES = 2, } eMaskhandleMode; -struct MaskSplinePoint *BKE_mask_spline_point_array(struct MaskSpline *spline); -struct MaskSplinePoint *BKE_mask_spline_point_array_from_point( - struct MaskSpline *spline, const struct MaskSplinePoint *point_ref); +/* -------------------------------------------------------------------- */ +/** \name Mask Layers + * \{ */ -/* mask layers */ struct MaskLayer *BKE_mask_layer_new(struct Mask *mask, const char *name); +/** + * \note The returned mask-layer may be hidden, caller needs to check. + */ struct MaskLayer *BKE_mask_layer_active(struct Mask *mask); void BKE_mask_layer_active_set(struct Mask *mask, struct MaskLayer *masklay); void BKE_mask_layer_remove(struct Mask *mask, struct MaskLayer *masklay); +/** \brief Free all animation keys for a mask layer. + */ void BKE_mask_layer_free_shapes(struct MaskLayer *masklay); void BKE_mask_layer_free(struct MaskLayer *masklay); void BKE_mask_layer_free_list(struct ListBase *masklayers); @@ -83,7 +87,16 @@ void BKE_mask_layer_rename(struct Mask *mask, struct MaskLayer *BKE_mask_layer_copy(const struct MaskLayer *masklay); void BKE_mask_layer_copy_list(struct ListBase *masklayers_new, const struct ListBase *masklayers); -/* splines */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Splines + * \{ */ + +struct MaskSplinePoint *BKE_mask_spline_point_array(struct MaskSpline *spline); +struct MaskSplinePoint *BKE_mask_spline_point_array_from_point( + struct MaskSpline *spline, const struct MaskSplinePoint *point_ref); + struct MaskSpline *BKE_mask_spline_add(struct MaskLayer *masklay); bool BKE_mask_spline_remove(struct MaskLayer *mask_layer, struct MaskSpline *spline); void BKE_mask_point_direction_switch(struct MaskSplinePoint *point); @@ -104,7 +117,12 @@ float BKE_mask_spline_project_co(struct MaskSpline *spline, const float co[2], const eMaskSign sign); -/* point */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Point + * \{ */ + eMaskhandleMode BKE_mask_point_handles_mode_get(const struct MaskSplinePoint *point); void BKE_mask_point_handle(const struct MaskSplinePoint *point, eMaskWhichHandle which_handle, @@ -139,7 +157,12 @@ void BKE_mask_point_select_set_handle(struct MaskSplinePoint *point, const eMaskWhichHandle which_handle, const bool do_select); -/* general */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name General + * \{ */ + struct Mask *BKE_mask_new(struct Main *bmain, const char *name); void BKE_mask_coord_from_frame(float r_co[2], const float co[2], const float frame_size[2]); @@ -151,6 +174,9 @@ void BKE_mask_coord_from_image(struct Image *image, struct ImageUser *iuser, float r_co[2], const float co[2]); +/** + * Inverse of #BKE_mask_coord_from_image. + */ void BKE_mask_coord_to_frame(float r_co[2], const float co[2], const float frame_size[2]); void BKE_mask_coord_to_movieclip(struct MovieClip *clip, struct MovieClipUser *user, @@ -161,7 +187,11 @@ void BKE_mask_coord_to_image(struct Image *image, float r_co[2], const float co[2]); -/* parenting */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Parenting + * \{ */ void BKE_mask_evaluate(struct Mask *mask, const float ctime, const bool do_newframe); void BKE_mask_layer_evaluate(struct MaskLayer *masklay, const float ctime, const bool do_newframe); @@ -169,10 +199,19 @@ void BKE_mask_parent_init(struct MaskParent *parent); void BKE_mask_calc_handle_adjacent_interp(struct MaskSpline *spline, struct MaskSplinePoint *point, const float u); +/** + * Calculates the tangent of a point by its previous and next + * (ignoring handles - as if its a poly line). + */ void BKE_mask_calc_tangent_polyline(struct MaskSpline *spline, struct MaskSplinePoint *point, float t[2]); void BKE_mask_calc_handle_point(struct MaskSpline *spline, struct MaskSplinePoint *point); +/** + * \brief Resets auto handles even for non-auto bezier points + * + * Useful for giving sane defaults. + */ void BKE_mask_calc_handle_point_auto(struct MaskSpline *spline, struct MaskSplinePoint *point, const bool do_recalc_length); @@ -186,20 +225,40 @@ void BKE_mask_point_parent_matrix_get(struct MaskSplinePoint *point, float ctime, float parent_matrix[3][3]); -/* animation */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Animation + * \{ */ + int BKE_mask_layer_shape_totvert(struct MaskLayer *masklay); +/** + * Inverse of #BKE_mask_layer_shape_to_mask + */ void BKE_mask_layer_shape_from_mask(struct MaskLayer *masklay, struct MaskLayerShape *masklay_shape); +/** + * Inverse of #BKE_mask_layer_shape_from_mask + */ void BKE_mask_layer_shape_to_mask(struct MaskLayer *masklay, struct MaskLayerShape *masklay_shape); +/** + * \note Linear interpolation only. + */ void BKE_mask_layer_shape_to_mask_interp(struct MaskLayer *masklay, struct MaskLayerShape *masklay_shape_a, struct MaskLayerShape *masklay_shape_b, const float fac); struct MaskLayerShape *BKE_mask_layer_shape_find_frame(struct MaskLayer *masklay, const int frame); +/** + * When returning 2 - the frame isn't found but before/after frames are. + */ int BKE_mask_layer_shape_find_frame_range(struct MaskLayer *masklay, const float frame, struct MaskLayerShape **r_masklay_shape_a, struct MaskLayerShape **r_masklay_shape_b); +/** + * \note Does *not* add to the list. + */ struct MaskLayerShape *BKE_mask_layer_shape_alloc(struct MaskLayer *masklay, const int frame); void BKE_mask_layer_shape_free(struct MaskLayerShape *masklay_shape); struct MaskLayerShape *BKE_mask_layer_shape_verify_frame(struct MaskLayer *masklay, @@ -214,19 +273,42 @@ bool BKE_mask_layer_shape_spline_from_index(struct MaskLayer *masklay, int *r_index); int BKE_mask_layer_shape_spline_to_index(struct MaskLayer *masklay, struct MaskSpline *spline); +/** + * When a new points added, resizing all shape-key arrays. + */ void BKE_mask_layer_shape_changed_add(struct MaskLayer *masklay, int index, bool do_init, bool do_init_interpolate); +/** + * Move array elements to account for removed point. + */ void BKE_mask_layer_shape_changed_remove(struct MaskLayer *masklay, int index, int count); int BKE_mask_get_duration(struct Mask *mask); -/* clipboard */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Clipboard + * \{ */ + +/** + * Free the clipboard. + */ void BKE_mask_clipboard_free(void); +/** + * Copy selected visible splines from the given layer to clipboard. + */ void BKE_mask_clipboard_copy_from_layer(struct MaskLayer *mask_layer); +/** + * Check clipboard is empty. + */ bool BKE_mask_clipboard_is_empty(void); +/** + * Paste the contents of clipboard to given mask layer. + */ void BKE_mask_clipboard_paste_to_layer(struct Main *bmain, struct MaskLayer *mask_layer); #define MASKPOINT_ISSEL_ANY(p) ((((p)->bezt.f1 | (p)->bezt.f2 | (p)->bezt.f3) & SELECT) != 0) @@ -260,9 +342,16 @@ void BKE_mask_clipboard_paste_to_layer(struct Main *bmain, struct MaskLayer *mas } \ (void)0 +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Evaluation + * \{ */ + #define MASK_RESOL_MAX 128 /* mask_evaluate.c */ + unsigned int BKE_mask_spline_resolution(struct MaskSpline *spline, int width, int height); unsigned int BKE_mask_spline_feather_resolution(struct MaskSpline *spline, int width, int height); int BKE_mask_spline_differentiate_calc_total(const struct MaskSpline *spline, @@ -276,6 +365,10 @@ void BKE_mask_spline_feather_collapse_inner_loops(struct MaskSpline *spline, const unsigned int tot_feather_point); float (*BKE_mask_spline_differentiate( struct MaskSpline *spline, int width, int height, unsigned int *r_tot_diff_point))[2]; +/** + * values align with #BKE_mask_spline_differentiate_with_resolution + * when \a resol arguments match. + */ float (*BKE_mask_spline_feather_differentiated_points_with_resolution( struct MaskSpline *spline, const unsigned int resol, @@ -283,6 +376,7 @@ float (*BKE_mask_spline_feather_differentiated_points_with_resolution( unsigned int *r_tot_feather_point))[2]; /* *** mask point functions which involve evaluation *** */ + float (*BKE_mask_spline_feather_points(struct MaskSpline *spline, int *tot_feather_point))[2]; float *BKE_mask_point_segment_diff(struct MaskSpline *spline, @@ -291,6 +385,8 @@ float *BKE_mask_point_segment_diff(struct MaskSpline *spline, int height, unsigned int *r_tot_diff_point); +/* *** mask point functions which involve evaluation *** */ + float *BKE_mask_point_segment_feather_diff(struct MaskSpline *spline, struct MaskSplinePoint *point, int width, @@ -303,7 +399,14 @@ void BKE_mask_layer_evaluate_deform(struct MaskLayer *masklay, const float ctime void BKE_mask_eval_animation(struct Depsgraph *depsgraph, struct Mask *mask); void BKE_mask_eval_update(struct Depsgraph *depsgraph, struct Mask *mask); +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Rasterization + * \{ */ + /* mask_rasterize.c */ + struct MaskRasterHandle; typedef struct MaskRasterHandle MaskRasterHandle; @@ -318,11 +421,16 @@ void BKE_maskrasterize_handle_init(MaskRasterHandle *mr_handle, const bool do_feather); float BKE_maskrasterize_handle_sample(MaskRasterHandle *mr_handle, const float xy[2]); +/** + * \brief Rasterize a buffer from a single mask (threaded execution). + */ void BKE_maskrasterize_buffer(MaskRasterHandle *mr_handle, const unsigned int width, const unsigned int height, float *buffer); +/** \} */ + #ifdef __cplusplus } #endif diff --git a/source/blender/blenkernel/BKE_material.h b/source/blender/blenkernel/BKE_material.h index b1eaf7207fa..5f9007c79b0 100644 --- a/source/blender/blenkernel/BKE_material.h +++ b/source/blender/blenkernel/BKE_material.h @@ -34,12 +34,18 @@ struct Object; struct Scene; struct bNode; -/* Module */ +/* -------------------------------------------------------------------- */ +/** \name Module + * \{ */ void BKE_materials_init(void); void BKE_materials_exit(void); -/* Materials */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Materials + * \{ */ void BKE_object_materials_test(struct Main *bmain, struct Object *ob, struct ID *id); void BKE_objects_materials_test_all(struct Main *bmain, struct ID *id); @@ -48,9 +54,18 @@ void BKE_object_material_resize(struct Main *bmain, const short totcol, bool do_id_user); void BKE_object_material_remap(struct Object *ob, const unsigned int *remap); +/** + * Calculate a material remapping from \a ob_src to \a ob_dst. + * + * \param remap_src_to_dst: An array the size of `ob_src->totcol` + * where index values are filled in which map to \a ob_dst materials. + */ void BKE_object_material_remap_calc(struct Object *ob_dst, struct Object *ob_src, short *remap_src_to_dst); +/** + * Copy materials from evaluated geometry to the original geometry of an object. + */ void BKE_object_material_from_eval_data(struct Main *bmain, struct Object *ob_orig, struct ID *data_eval); @@ -61,10 +76,17 @@ void BKE_gpencil_material_attr_init(struct Material *ma); /* UNUSED */ // void automatname(struct Material *); -/* material slots */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Material Slots + * \{ */ struct Material ***BKE_object_material_array_p(struct Object *ob); short *BKE_object_material_len_p(struct Object *ob); +/** + * \note Same as #BKE_object_material_len_p but for ID's. + */ struct Material ***BKE_id_material_array_p(struct ID *id); /* same but for ID's */ short *BKE_id_material_len_p(struct ID *id); @@ -81,6 +103,9 @@ struct Material *BKE_object_material_get(struct Object *ob, short act); void BKE_id_material_assign(struct Main *bmain, struct ID *id, struct Material *ma, short act); void BKE_object_material_assign( struct Main *bmain, struct Object *ob, struct Material *ma, short act, int assign_type); +/** + * \warning this calls many more update calls per object then are needed, could be optimized. + */ void BKE_object_material_array_assign(struct Main *bmain, struct Object *ob, struct Material ***matar, @@ -99,7 +124,12 @@ void BKE_texpaint_slot_refresh_cache(struct Scene *scene, struct Material *ma); void BKE_texpaint_slots_refresh_object(struct Scene *scene, struct Object *ob); struct bNode *BKE_texpaint_slot_material_find_node(struct Material *ma, short texpaint_slot); -/* rna api */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name RNA API + * \{ */ + void BKE_id_materials_copy(struct Main *bmain, struct ID *id_src, struct ID *id_dst); void BKE_id_material_resize(struct Main *bmain, struct ID *id, short totcol, bool do_id_user); void BKE_id_material_append(struct Main *bmain, struct ID *id, struct Material *ma); @@ -109,23 +139,57 @@ struct Material *BKE_id_material_pop(struct Main *bmain, int index); void BKE_id_material_clear(struct Main *bmain, struct ID *id); -/* eval api */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Evaluation API + * \{ */ + +/** + * On evaluated objects the number of materials on an object and its data might go out of sync. + * This is because during evaluation materials can be added/removed on the object data. + * + * For rendering or exporting we generally use the materials on the object data. However, some + * material indices might be overwritten by the object. + */ struct Material *BKE_object_material_get_eval(struct Object *ob, short act); int BKE_object_material_count_eval(struct Object *ob); void BKE_id_material_eval_assign(struct ID *id, int slot, struct Material *material); +/** + * Add an empty material slot if the id has no material slots. This material slot allows the + * material to be overwritten by object-linked materials. + */ void BKE_id_material_eval_ensure_default_slot(struct ID *id); -/* rendering */ +/** \} */ +/* -------------------------------------------------------------------- */ +/** \name Rendering + * \{ */ + +/** + * \param r_col: current value. + * \param col: new value. + * \param fac: Zero for is no change. + */ void ramp_blend(int type, float r_col[3], const float fac, const float col[3]); -/* copy/paste */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Copy/Paste + * \{ */ + void BKE_material_copybuf_clear(void); void BKE_material_copybuf_free(void); void BKE_material_copybuf_copy(struct Main *bmain, struct Material *ma); void BKE_material_copybuf_paste(struct Main *bmain, struct Material *ma); -/* Default Materials */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Default Materials + * \{ */ struct Material *BKE_material_default_empty(void); struct Material *BKE_material_default_holdout(void); @@ -135,12 +199,18 @@ struct Material *BKE_material_default_gpencil(void); void BKE_material_defaults_free_gpu(void); -/* Dependency graph evaluation. */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Dependency graph evaluation + * \{ */ struct Depsgraph; void BKE_material_eval(struct Depsgraph *depsgraph, struct Material *material); +/** \} */ + #ifdef __cplusplus } #endif diff --git a/source/blender/blenkernel/BKE_mball.h b/source/blender/blenkernel/BKE_mball.h index db4dca14535..895fe5a28f9 100644 --- a/source/blender/blenkernel/BKE_mball.h +++ b/source/blender/blenkernel/BKE_mball.h @@ -41,13 +41,45 @@ bool BKE_mball_is_any_selected(const struct MetaBall *mb); bool BKE_mball_is_any_selected_multi(struct Base **bases, int bases_len); bool BKE_mball_is_any_unselected(const struct MetaBall *mb); bool BKE_mball_is_basis_for(struct Object *ob1, struct Object *ob2); +/** + * Test, if \a ob is a basis meta-ball. + * + * It test last character of Object ID name. + * If last character is digit it return 0, else it return 1. + */ bool BKE_mball_is_basis(struct Object *ob); +/** + * This function finds the basis meta-ball. + * + * Basis meta-ball doesn't include any number at the end of + * its name. All meta-balls with same base of name can be + * blended. meta-balls with different basic name can't be blended. + * + * \warning #BKE_mball_is_basis() can fail on returned object, see function docs for details. + */ struct Object *BKE_mball_basis_find(struct Scene *scene, struct Object *ob); +/** + * Compute bounding box of all meta-elements / meta-ball. + * + * Bounding box is computed from polygonized surface. \a ob is + * basic meta-balls (with name `Meta` for example). All other meta-ball objects + * (with names `Meta.001`, `Meta.002`, etc) are included in this bounding-box. + */ void BKE_mball_texspace_calc(struct Object *ob); +/** + * Return or compute bounding-box for given meta-ball object. + */ struct BoundBox *BKE_mball_boundbox_get(struct Object *ob); float *BKE_mball_make_orco(struct Object *ob, struct ListBase *dispbase); +/** + * Copy some properties from object to other meta-ball object with same base name. + * + * When some properties (wire-size, threshold, update flags) of meta-ball are changed, then this + * properties are copied to all meta-balls in same "group" (meta-balls with same base name: + * `MBall`, `MBall.001`, `MBall.002`, etc). The most important is to copy properties to the base + * meta-ball, because this meta-ball influence polygonization of meta-balls. */ void BKE_mball_properties_copy(struct Scene *scene, struct Object *active_object); bool BKE_mball_minmax_ex(const struct MetaBall *mb, @@ -55,14 +87,24 @@ bool BKE_mball_minmax_ex(const struct MetaBall *mb, float max[3], const float obmat[4][4], const short flag); + +/* Basic vertex data functions. */ + bool BKE_mball_minmax(const struct MetaBall *mb, float min[3], float max[3]); bool BKE_mball_center_median(const struct MetaBall *mb, float r_cent[3]); bool BKE_mball_center_bounds(const struct MetaBall *mb, float r_cent[3]); void BKE_mball_transform(struct MetaBall *mb, const float mat[4][4], const bool do_props); void BKE_mball_translate(struct MetaBall *mb, const float offset[3]); +/** + * Most simple meta-element adding function. + * + * \note don't do context manipulation here (rna uses). + */ struct MetaElem *BKE_mball_element_add(struct MetaBall *mb, const int type); +/* *** select funcs *** */ + int BKE_mball_select_count(const struct MetaBall *mb); int BKE_mball_select_count_multi(struct Base **bases, int bases_len); bool BKE_mball_select_all(struct MetaBall *mb); diff --git a/source/blender/blenkernel/BKE_mesh.h b/source/blender/blenkernel/BKE_mesh.h index 135f8128b9a..1e7262248d5 100644 --- a/source/blender/blenkernel/BKE_mesh.h +++ b/source/blender/blenkernel/BKE_mesh.h @@ -84,21 +84,51 @@ struct Mesh *BKE_mesh_from_bmesh_for_eval_nomain(struct BMesh *bm, const struct CustomData_MeshMasks *cd_mask_extra, const struct Mesh *me_settings); +/** + * Find the index of the loop in 'poly' which references vertex, + * returns -1 if not found + */ int poly_find_loop_from_vert(const struct MPoly *poly, const struct MLoop *loopstart, uint vert); +/** + * Fill \a r_adj with the loop indices in \a poly adjacent to the + * vertex. Returns the index of the loop matching vertex, or -1 if the + * vertex is not in \a poly + */ int poly_get_adj_loops_from_vert(const struct MPoly *poly, const struct MLoop *mloop, unsigned int vert, unsigned int r_adj[2]); +/** + * Return the index of the edge vert that is not equal to \a v. If + * neither edge vertex is equal to \a v, returns -1. + */ int BKE_mesh_edge_other_vert(const struct MEdge *e, int v); +/** + * Sets each output array element to the edge index if it is a real edge, or -1. + */ void BKE_mesh_looptri_get_real_edges(const struct Mesh *mesh, const struct MLoopTri *looptri, int r_edges[3]); +/** + * Free (or release) any data used by this mesh (does not free the mesh itself). + * Only use for undo, in most cases `BKE_id_free(nullptr, me)` should be used. + */ void BKE_mesh_free_data_for_undo(struct Mesh *me); void BKE_mesh_clear_geometry(struct Mesh *me); struct Mesh *BKE_mesh_add(struct Main *bmain, const char *name); +/** + * A version of #BKE_mesh_copy_parameters that is intended for evaluated output + * (the modifier stack for example). + * + * \warning User counts are not handled for ID's. + */ void BKE_mesh_copy_parameters_for_eval(struct Mesh *me_dst, const struct Mesh *me_src); +/** + * Copy user editable settings that we want to preserve + * when a new mesh is based on an existing mesh. + */ void BKE_mesh_copy_parameters(struct Mesh *me_dst, const struct Mesh *me_src); void BKE_mesh_update_customdata_pointers(struct Mesh *me, const bool do_ensure_tess_cd); void BKE_mesh_ensure_skin_customdata(struct Mesh *me); @@ -121,12 +151,16 @@ struct Mesh *BKE_mesh_new_nomain_from_template_ex(const struct Mesh *me_src, void BKE_mesh_eval_delete(struct Mesh *mesh_eval); -/* Performs copy for use during evaluation, - * optional referencing original arrays to reduce memory. */ +/** + * Performs copy for use during evaluation, + * optional referencing original arrays to reduce memory. + */ struct Mesh *BKE_mesh_copy_for_eval(const struct Mesh *source, bool reference); -/* These functions construct a new Mesh, - * contrary to BKE_mesh_to_curve_nurblist which modifies ob itself. */ +/** + * These functions construct a new Mesh, + * contrary to #BKE_mesh_to_curve_nurblist which modifies ob itself. + */ struct Mesh *BKE_mesh_new_nomain_from_curve(const struct Object *ob); struct Mesh *BKE_mesh_new_nomain_from_curve_displist(const struct Object *ob, const struct ListBase *dispbase); @@ -137,9 +171,15 @@ bool BKE_mesh_clear_facemap_customdata(struct Mesh *me); float (*BKE_mesh_orco_verts_get(struct Object *ob))[3]; void BKE_mesh_orco_verts_transform(struct Mesh *me, float (*orco)[3], int totvert, int invert); -/* Add a CD_ORCO layer to the Mesh if there is none already. */ +/** + * Add a #CD_ORCO layer to the Mesh if there is none already. + */ void BKE_mesh_orco_ensure(struct Object *ob, struct Mesh *mesh); +/** + * Rotates the vertices of a face in case v[2] or v[3] (vertex index) is = 0. + * this is necessary to make the if #MFace.v4 check for quads work. + */ int BKE_mesh_mface_index_validate(struct MFace *mface, struct CustomData *mfdata, int mfindex, @@ -170,9 +210,17 @@ void BKE_mesh_material_index_clear(struct Mesh *me); void BKE_mesh_material_remap(struct Mesh *me, const unsigned int *remap, unsigned int remap_len); void BKE_mesh_smooth_flag_set(struct Mesh *me, const bool use_smooth); -/* Needed after converting a mesh with subsurf optimal display to mesh. */ +/** + * Needed after converting a mesh with subsurf optimal display to mesh. + */ void BKE_mesh_edges_set_draw_render(struct Mesh *me); +/** + * Used for unit testing; compares two meshes, checking only + * differences we care about. should be usable with leaf's + * testing framework I get RNA work done, will use hackish + * testing code for now. + */ const char *BKE_mesh_cmp(struct Mesh *me1, struct Mesh *me2, float thresh); struct BoundBox *BKE_mesh_boundbox_get(struct Object *ob); @@ -186,29 +234,44 @@ void BKE_mesh_texspace_get_reference(struct Mesh *me, float **r_size); void BKE_mesh_texspace_copy_from_object(struct Mesh *me, struct Object *ob); +/** + * Split faces based on the edge angle and loop normals. + * Matches behavior of face splitting in render engines. + * + * \note Will leave #CD_NORMAL loop data layer which is used by render engines to set shading up. + */ void BKE_mesh_split_faces(struct Mesh *mesh, bool free_loop_normals); -/* Create new mesh from the given object at its current state. +/** + * Create new mesh from the given object at its current state. * The owner of this mesh is unknown, it is up to the caller to decide. * * If preserve_all_data_layers is truth then the modifier stack is re-evaluated to ensure it * preserves all possible custom data layers. * - * NOTE: Dependency graph argument is required when preserve_all_data_layers is truth, and is - * ignored otherwise. */ + * \note Dependency graph argument is required when preserve_all_data_layers is truth, and is + * ignored otherwise. + */ struct Mesh *BKE_mesh_new_from_object(struct Depsgraph *depsgraph, struct Object *object, const bool preserve_all_data_layers, const bool preserve_origindex); -/* This is a version of BKE_mesh_new_from_object() which stores mesh in the given main database. +/** + * This is a version of BKE_mesh_new_from_object() which stores mesh in the given main database. * However, that function enforces object type to be a geometry one, and ensures a mesh is always - * generated, be it empty. */ + * generated, be it empty. + */ struct Mesh *BKE_mesh_new_from_object_to_bmain(struct Main *bmain, struct Depsgraph *depsgraph, struct Object *object, bool preserve_all_data_layers); +/** + * \param use_virtual_modifiers: When enabled calculate virtual-modifiers before applying `md_eval` + * support this since virtual-modifiers are not modifiers from a user perspective, + * allowing shape keys to be included with the modifier being applied, see: T91923. + */ struct Mesh *BKE_mesh_create_derived_for_modifier(struct Depsgraph *depsgraph, struct Scene *scene, struct Object *ob_eval, @@ -216,7 +279,9 @@ struct Mesh *BKE_mesh_create_derived_for_modifier(struct Depsgraph *depsgraph, const bool use_virtual_modifiers, const bool build_shapekey_layers); -/* Copies a nomain-Mesh into an existing Mesh. */ +/** + * Copies a nomain-Mesh into an existing Mesh. + */ void BKE_mesh_nomain_to_mesh(struct Mesh *mesh_src, struct Mesh *mesh_dst, struct Object *ob, @@ -226,6 +291,7 @@ void BKE_mesh_nomain_to_meshkey(struct Mesh *mesh_src, struct Mesh *mesh_dst, st /* vertex level transformations & checks (no derived mesh) */ +/* basic vertex data functions */ bool BKE_mesh_minmax(const struct Mesh *me, float r_min[3], float r_max[3]); void BKE_mesh_transform(struct Mesh *me, const float mat[4][4], bool do_keys); void BKE_mesh_translate(struct Mesh *me, const float offset[3], const bool do_keys); @@ -237,7 +303,13 @@ void BKE_mesh_do_versions_cd_flag_init(struct Mesh *mesh); void BKE_mesh_mselect_clear(struct Mesh *me); void BKE_mesh_mselect_validate(struct Mesh *me); +/** + * \return the index within `me->mselect`, or -1 + */ int BKE_mesh_mselect_find(struct Mesh *me, int index, int type); +/** + * \return The index of the active element. + */ int BKE_mesh_mselect_active_get(struct Mesh *me, int type); void BKE_mesh_mselect_active_set(struct Mesh *me, int index, int type); @@ -254,6 +326,17 @@ void BKE_mesh_vert_normals_apply(struct Mesh *mesh, const short (*vert_normals)[ /* *** mesh_tessellate.c *** */ +/** + * Recreate #MFace Tessellation. + * + * \param do_face_nor_copy: Controls whether the normals from the poly + * are copied to the tessellated faces. + * + * \return number of tessellation faces. + * + * \note This doesn't use multi-threading like #BKE_mesh_recalc_looptri since + * it's not used in many places and #MFace should be phased out. + */ int BKE_mesh_tessface_calc_ex(struct CustomData *fdata, struct CustomData *ldata, struct CustomData *pdata, @@ -264,12 +347,23 @@ int BKE_mesh_tessface_calc_ex(struct CustomData *fdata, const bool do_face_nor_copy); void BKE_mesh_tessface_calc(struct Mesh *mesh); +/** + * Calculate tessellation into #MLoopTri which exist only for this purpose. + */ void BKE_mesh_recalc_looptri(const struct MLoop *mloop, const struct MPoly *mpoly, const struct MVert *mvert, int totloop, int totpoly, struct MLoopTri *mlooptri); +/** + * A version of #BKE_mesh_recalc_looptri which takes pre-calculated polygon normals + * (used to avoid having to calculate the face normal for NGON tessellation). + * + * \note Only use this function if normals have already been calculated, there is no need + * to calculate normals just to use this function as it will cause the normals for triangles + * to be calculated which aren't needed for tessellation. + */ void BKE_mesh_recalc_looptri_with_normals(const struct MLoop *mloop, const struct MPoly *mpoly, const struct MVert *mvert, @@ -296,8 +390,15 @@ void BKE_mesh_calc_normals_poly_and_vertex(struct MVert *mvert, int mpoly_len, float (*r_poly_normals)[3], float (*r_vert_normals)[3]); +/** + * \note this does not update the #CD_NORMAL layer, + * but does update the normals in the #CD_MVERT layer. + */ void BKE_mesh_calc_normals(struct Mesh *me); void BKE_mesh_ensure_normals(struct Mesh *me); +/** + * Called after calculating all modifiers. + */ void BKE_mesh_ensure_normals_for_display(struct Mesh *mesh); void BKE_mesh_calc_normals_looptri(struct MVert *mverts, int numVerts, @@ -315,6 +416,12 @@ void BKE_mesh_loop_manifold_fan_around_vert_next(const struct MLoop *mloops, int *r_mlfan_vert_index, int *r_mpfan_curr_index); +/** + * Define sharp edges as needed to mimic 'autosmooth' from angle threshold. + * + * Used when defining an empty custom loop normals data layer, + * to keep same shading as with auto-smooth! + */ void BKE_edges_sharp_from_angle_set(const struct MVert *mverts, const int numVerts, struct MEdge *medges, @@ -383,17 +490,42 @@ void BKE_lnor_spacearr_init(MLoopNorSpaceArray *lnors_spacearr, void BKE_lnor_spacearr_clear(MLoopNorSpaceArray *lnors_spacearr); void BKE_lnor_spacearr_free(MLoopNorSpaceArray *lnors_spacearr); +/** + * Utility for multi-threaded calculation that ensures + * `lnors_spacearr_tls` doesn't share memory with `lnors_spacearr` + * that would cause it not to be thread safe. + * + * \note This works as long as threads never operate on the same loops at once. + */ void BKE_lnor_spacearr_tls_init(MLoopNorSpaceArray *lnors_spacearr, MLoopNorSpaceArray *lnors_spacearr_tls); +/** + * Utility for multi-threaded calculation + * that merges `lnors_spacearr_tls` into `lnors_spacearr`. + */ void BKE_lnor_spacearr_tls_join(MLoopNorSpaceArray *lnors_spacearr, MLoopNorSpaceArray *lnors_spacearr_tls); MLoopNorSpace *BKE_lnor_space_create(MLoopNorSpaceArray *lnors_spacearr); +/** + * Should only be called once. + * Beware, this modifies ref_vec and other_vec in place! + * In case no valid space can be generated, ref_alpha and ref_beta are set to zero + * (which means 'use auto lnors'). + */ void BKE_lnor_space_define(MLoopNorSpace *lnor_space, const float lnor[3], float vec_ref[3], float vec_other[3], struct BLI_Stack *edge_vectors); +/** + * Add a new given loop to given lnor_space. + * Depending on \a lnor_space->data_type, we expect \a bm_loop to be a pointer to BMLoop struct + * (in case of BMLOOP_PTR), or nullptr (in case of LOOP_INDEX), loop index is then stored in + * pointer. If \a is_single is set, the BMLoop or loop index is directly stored in \a + * lnor_space->loops pointer (since there is only one loop in this fan), else it is added to the + * linked list of loops in the fan. + */ void BKE_lnor_space_add_loop(MLoopNorSpaceArray *lnors_spacearr, MLoopNorSpace *lnor_space, const int ml_index, @@ -407,6 +539,12 @@ void BKE_lnor_space_custom_normal_to_data(MLoopNorSpace *lnor_space, short r_clnor_data[2]); /* Medium-level custom normals functions. */ + +/** + * Compute split normals, i.e. vertex normals associated with each poly (hence 'loop normals'). + * Useful to materialize sharp edges (or non-smooth faces) without actually modifying the geometry + * (splitting edges). + */ void BKE_mesh_normals_loop_split(const struct MVert *mverts, const int numVerts, struct MEdge *medges, @@ -446,20 +584,49 @@ void BKE_mesh_normals_loop_custom_from_vertices_set(const struct MVert *mverts, const int numPolys, short (*r_clnors_data)[2]); +/** + * Computes average per-vertex normals from given custom loop normals. + * + * \param clnors: The computed custom loop normals. + * \param r_vert_clnors: The (already allocated) array where to store averaged per-vertex normals. + */ void BKE_mesh_normals_loop_to_vertex(const int numVerts, const struct MLoop *mloops, const int numLoops, const float (*clnors)[3], float (*r_vert_clnors)[3]); -/* High-level custom normals functions. */ +/** + * High-level custom normals functions. + */ bool BKE_mesh_has_custom_loop_normals(struct Mesh *me); void BKE_mesh_calc_normals_split(struct Mesh *mesh); +/** + * Compute 'split' (aka loop, or per face corner's) normals. + * + * \param r_lnors_spacearr: Allows to get computed loop normal space array. + * That data, among other things, contains 'smooth fan' info, useful e.g. + * to split geometry along sharp edges. + */ void BKE_mesh_calc_normals_split_ex(struct Mesh *mesh, struct MLoopNorSpaceArray *r_lnors_spacearr); +/** + * Higher level functions hiding most of the code needed around call to + * #BKE_mesh_normals_loop_custom_set(). + * + * \param r_custom_loopnors: is not const, since code will replace zero_v3 normals there + * with automatically computed vectors. + */ void BKE_mesh_set_custom_normals(struct Mesh *mesh, float (*r_custom_loopnors)[3]); +/** + * Higher level functions hiding most of the code needed around call to + * #BKE_mesh_normals_loop_custom_from_vertices_set(). + * + * \param r_custom_vertnors: is not const, since code will replace zero_v3 normals there + * with automatically computed vectors. + */ void BKE_mesh_set_custom_normals_from_vertices(struct Mesh *mesh, float (*r_custom_vertnors)[3]); /* *** mesh_evaluate.cc *** */ @@ -476,6 +643,7 @@ void BKE_mesh_calc_poly_center(const struct MPoly *mpoly, const struct MLoop *loopstart, const struct MVert *mvarray, float r_cent[3]); +/* NOTE: passing poly-normal is only a speedup so we can skip calculating it. */ float BKE_mesh_calc_poly_area(const struct MPoly *mpoly, const struct MLoop *loopstart, const struct MVert *mvarray); @@ -494,11 +662,25 @@ void BKE_mesh_poly_edgebitmap_insert(unsigned int *edge_bitmap, const struct MLoop *mloop); bool BKE_mesh_center_median(const struct Mesh *me, float r_cent[3]); +/** + * Calculate the center from polygons, + * use when we want to ignore vertex locations that don't have connected faces. + */ bool BKE_mesh_center_median_from_polys(const struct Mesh *me, float r_cent[3]); bool BKE_mesh_center_bounds(const struct Mesh *me, float r_cent[3]); bool BKE_mesh_center_of_surface(const struct Mesh *me, float r_cent[3]); +/** + * \note Mesh must be manifold with consistent face-winding, + * see #mesh_calc_poly_volume_centroid for details. + */ bool BKE_mesh_center_of_volume(const struct Mesh *me, float r_cent[3]); +/** + * Calculate the volume and center. + * + * \param r_volume: Volume (unsigned). + * \param r_center: Center of mass. + */ void BKE_mesh_calc_volume(const struct MVert *mverts, const int mverts_num, const struct MLoopTri *mlooptri, @@ -509,6 +691,19 @@ void BKE_mesh_calc_volume(const struct MVert *mverts, /* tessface */ void BKE_mesh_convert_mfaces_to_mpolys(struct Mesh *mesh); +/** + * The same as #BKE_mesh_convert_mfaces_to_mpolys + * but oriented to be used in #do_versions from `readfile.c` + * the difference is how active/render/clone/stencil indices are handled here. + * + * normally they're being set from `pdata` which totally makes sense for meshes which are already + * converted to #BMesh structures, but when loading older files indices shall be updated in other + * way around, so newly added `pdata` and `ldata` would have this indices set + * based on `fdata` layer. + * + * this is normally only needed when reading older files, + * in all other cases #BKE_mesh_convert_mfaces_to_mpolys shall be always used. + */ void BKE_mesh_do_versions_convert_mfaces_to_mpolys(struct Mesh *mesh); void BKE_mesh_convert_mfaces_to_mpolys_ex(struct ID *id, struct CustomData *fdata, @@ -525,8 +720,20 @@ void BKE_mesh_convert_mfaces_to_mpolys_ex(struct ID *id, struct MLoop **r_mloop, struct MPoly **r_mpoly); +/** + * Flip a single MLoop's #MDisps structure, + * low level function to be called from face-flipping code which re-arranged the mdisps themselves. + */ void BKE_mesh_mdisp_flip(struct MDisps *md, const bool use_loop_mdisp_flip); +/** + * Flip (invert winding of) the given \a mpoly, i.e. reverse order of its loops + * (keeping the same vertex as 'start point'). + * + * \param mpoly: the polygon to flip. + * \param mloop: the full loops array. + * \param ldata: the loops custom data. + */ void BKE_mesh_polygon_flip_ex(struct MPoly *mpoly, struct MLoop *mloop, struct CustomData *ldata, @@ -534,6 +741,11 @@ void BKE_mesh_polygon_flip_ex(struct MPoly *mpoly, struct MDisps *mdisp, const bool use_loop_mdisp_flip); void BKE_mesh_polygon_flip(struct MPoly *mpoly, struct MLoop *mloop, struct CustomData *ldata); +/** + * Flip (invert winding of) all polygons (used to inverse their normals). + * + * \note Invalidates tessellation, caller must handle that. + */ void BKE_mesh_polygons_flip(struct MPoly *mpoly, struct MLoop *mloop, struct CustomData *ldata, @@ -546,12 +758,48 @@ enum { MESH_MERGE_VERTS_DUMP_IF_MAPPED, MESH_MERGE_VERTS_DUMP_IF_EQUAL, }; +/** + * Merge Verts + * + * This frees the given mesh and returns a new mesh. + * + * \param vtargetmap: The table that maps vertices to target vertices. a value of -1 + * indicates a vertex is a target, and is to be kept. + * This array is aligned with 'mesh->totvert' + * \warning \a vtargetmap must **not** contain any chained mapping (v1 -> v2 -> v3 etc.), + * this is not supported and will likely generate corrupted geometry. + * + * \param tot_vtargetmap: The number of non '-1' values in vtargetmap. (not the size) + * + * \param merge_mode: enum with two modes. + * - #MESH_MERGE_VERTS_DUMP_IF_MAPPED + * When called by the Mirror Modifier, + * In this mode it skips any faces that have all vertices merged (to avoid creating pairs + * of faces sharing the same set of vertices) + * - #MESH_MERGE_VERTS_DUMP_IF_EQUAL + * When called by the Array Modifier, + * In this mode, faces where all vertices are merged are double-checked, + * to see whether all target vertices actually make up a poly already. + * Indeed it could be that all of a poly's vertices are merged, + * but merged to vertices that do not make up a single poly, + * in which case the original poly should not be dumped. + * Actually this later behavior could apply to the Mirror Modifier as well, + * but the additional checks are costly and not necessary in the case of mirror, + * because each vertex is only merged to its own mirror. + * + * \note #BKE_mesh_tessface_calc_ex has to run on the returned DM + * if you want to access tess-faces. + */ struct Mesh *BKE_mesh_merge_verts(struct Mesh *mesh, const int *vtargetmap, const int tot_vtargetmap, const int merge_mode); -/* flush flags */ +/* Flush flags. */ + +/** + * Update the hide flag for edges and faces from the corresponding flag in verts. + */ void BKE_mesh_flush_hidden_from_verts_ex(const struct MVert *mvert, const struct MLoop *mloop, struct MEdge *medge, @@ -566,6 +814,9 @@ void BKE_mesh_flush_hidden_from_polys_ex(struct MVert *mvert, const struct MPoly *mpoly, const int totpoly); void BKE_mesh_flush_hidden_from_polys(struct Mesh *me); +/** + * simple poly -> vert/edge selection. + */ void BKE_mesh_flush_select_from_polys_ex(struct MVert *mvert, const int totvert, const struct MLoop *mloop, @@ -584,6 +835,17 @@ void BKE_mesh_flush_select_from_verts_ex(const struct MVert *mvert, void BKE_mesh_flush_select_from_verts(struct Mesh *me); /* spatial evaluation */ +/** + * This function takes the difference between 2 vertex-coord-arrays + * (\a vert_cos_src, \a vert_cos_dst), + * and applies the difference to \a vert_cos_new relative to \a vert_cos_org. + * + * \param vert_cos_src: reference deform source. + * \param vert_cos_dst: reference deform destination. + * + * \param vert_cos_org: reference for the output location. + * \param vert_cos_new: resulting coords. + */ void BKE_mesh_calc_relative_deform(const struct MPoly *mpoly, const int totpoly, const struct MLoop *mloop, @@ -597,10 +859,41 @@ void BKE_mesh_calc_relative_deform(const struct MPoly *mpoly, /* *** mesh_validate.c *** */ +/** + * Validates and corrects a Mesh. + * + * \returns true if a change is made. + */ bool BKE_mesh_validate(struct Mesh *me, const bool do_verbose, const bool cddata_check_mask); +/** + * Checks if a Mesh is valid without any modification. This is always verbose. + * + * \see #DM_is_valid to call on derived meshes + * + * \returns is_valid. + */ bool BKE_mesh_is_valid(struct Mesh *me); +/** + * Check all material indices of polygons are valid, invalid ones are set to 0. + * \returns is_valid. + */ bool BKE_mesh_validate_material_indices(struct Mesh *me); +/** + * Validate the mesh, \a do_fixes requires \a mesh to be non-null. + * + * \return false if no changes needed to be made. + * + * Vertex Normals + * ============== + * + * While zeroed normals are checked, these checks aren't comprehensive. + * Technically, to detect errors here a normal recalculation and comparison is necessary. + * However this function is mainly to prevent severe errors in geometry + * (invalid data that will crash Blender, or cause some features to behave incorrectly), + * not to detect subtle differences in the resulting normals which could be caused + * by importers that load normals (for example). + */ bool BKE_mesh_validate_arrays(struct Mesh *me, struct MVert *mverts, unsigned int totvert, @@ -617,6 +910,9 @@ bool BKE_mesh_validate_arrays(struct Mesh *me, const bool do_fixes, bool *r_change); +/** + * \returns is_valid. + */ bool BKE_mesh_validate_all_customdata(struct CustomData *vdata, const uint totvert, struct CustomData *edata, @@ -631,12 +927,31 @@ bool BKE_mesh_validate_all_customdata(struct CustomData *vdata, bool *r_change); void BKE_mesh_strip_loose_faces(struct Mesh *me); +/** + * Works on both loops and polys! + * + * \note It won't try to guess which loops of an invalid poly to remove! + * this is the work of the caller, to mark those loops. + * See e.g. #BKE_mesh_validate_arrays(). + */ void BKE_mesh_strip_loose_polysloops(struct Mesh *me); void BKE_mesh_strip_loose_edges(struct Mesh *me); +/** + * If the mesh is from a very old blender version, + * convert mface->edcode to edge drawflags + */ void BKE_mesh_calc_edges_legacy(struct Mesh *me, const bool use_old); void BKE_mesh_calc_edges_loose(struct Mesh *mesh); +/** + * Calculate edges from polygons. + */ void BKE_mesh_calc_edges(struct Mesh *mesh, bool keep_existing_edges, const bool select_new_edges); +/** + * Calculate/create edges from tessface data + * + * \param mesh: The mesh to add edges into + */ void BKE_mesh_calc_edges_tessface(struct Mesh *mesh); /* In DerivedMesh.cc */ diff --git a/source/blender/blenkernel/BKE_mesh_boolean_convert.hh b/source/blender/blenkernel/BKE_mesh_boolean_convert.hh index 59f6e75183e..a7a7529f217 100644 --- a/source/blender/blenkernel/BKE_mesh_boolean_convert.hh +++ b/source/blender/blenkernel/BKE_mesh_boolean_convert.hh @@ -32,6 +32,16 @@ struct Mesh; namespace blender::meshintersect { +/** + * Do a mesh boolean operation directly on meshes (without going back and forth to BMesh). + * \param meshes: An array of Mesh pointers. + * \param obmats: An array of pointers to the obmat matrices that transform local + * coordinates to global ones. It is allowed for the pointers to be null, meaning the + * transformation is the identity. + * \param material_remaps: An array of pointers to arrays of maps from material slot numbers in the + * corresponding mesh to the material slot in the first mesh. It is OK for material_remaps or any + * of its constituent arrays to be empty. + */ Mesh *direct_mesh_boolean(blender::Span meshes, blender::Span obmats, const float4x4 &target_transform, diff --git a/source/blender/blenkernel/BKE_mesh_iterators.h b/source/blender/blenkernel/BKE_mesh_iterators.h index a65f25ee182..83f0228dc76 100644 --- a/source/blender/blenkernel/BKE_mesh_iterators.h +++ b/source/blender/blenkernel/BKE_mesh_iterators.h @@ -39,6 +39,11 @@ void BKE_mesh_foreach_mapped_vert(struct Mesh *mesh, const short no_s[3]), void *userData, MeshForeachFlag flag); +/** + * Copied from #cdDM_foreachMappedEdge. + * \param tot_edges: Number of original edges. Used to avoid calling the callback with invalid + * edge indices. + */ void BKE_mesh_foreach_mapped_edge( struct Mesh *mesh, int tot_edges, diff --git a/source/blender/blenkernel/BKE_mesh_mapping.h b/source/blender/blenkernel/BKE_mesh_mapping.h index 0518f303744..acc1628de1d 100644 --- a/source/blender/blenkernel/BKE_mesh_mapping.h +++ b/source/blender/blenkernel/BKE_mesh_mapping.h @@ -105,6 +105,11 @@ UvVertMap *BKE_mesh_uv_vert_map_create(const struct MPoly *mpoly, UvMapVert *BKE_mesh_uv_vert_map_get_vert(UvVertMap *vmap, unsigned int v); void BKE_mesh_uv_vert_map_free(UvVertMap *vmap); +/** + * Generates a map where the key is the vertex and the value + * is a list of polys that use that vertex as a corner. + * The lists are allocated from one memory pool. + */ void BKE_mesh_vert_poly_map_create(MeshElemMap **r_map, int **r_mem, const struct MPoly *mpoly, @@ -112,6 +117,11 @@ void BKE_mesh_vert_poly_map_create(MeshElemMap **r_map, int totvert, int totpoly, int totloop); +/** + * Generates a map where the key is the vertex and the value + * is a list of loops that use that vertex as a corner. + * The lists are allocated from one memory pool. + */ void BKE_mesh_vert_loop_map_create(MeshElemMap **r_map, int **r_mem, const struct MPoly *mpoly, @@ -119,6 +129,11 @@ void BKE_mesh_vert_loop_map_create(MeshElemMap **r_map, int totvert, int totpoly, int totloop); +/** + * Generates a map where the key is the edge and the value + * is a list of looptris that use that edge. + * The lists are allocated from one memory pool. + */ void BKE_mesh_vert_looptri_map_create(MeshElemMap **r_map, int **r_mem, const struct MVert *mvert, @@ -127,10 +142,24 @@ void BKE_mesh_vert_looptri_map_create(MeshElemMap **r_map, const int totlooptri, const struct MLoop *mloop, const int totloop); +/** + * Generates a map where the key is the vertex and the value + * is a list of edges that use that vertex as an endpoint. + * The lists are allocated from one memory pool. + */ void BKE_mesh_vert_edge_map_create( MeshElemMap **r_map, int **r_mem, const struct MEdge *medge, int totvert, int totedge); +/** + * A version of #BKE_mesh_vert_edge_map_create that references connected vertices directly + * (not their edges). + */ void BKE_mesh_vert_edge_vert_map_create( MeshElemMap **r_map, int **r_mem, const struct MEdge *medge, int totvert, int totedge); +/** + * Generates a map where the key is the edge and the value is a list of loops that use that edge. + * Loops indices of a same poly are contiguous and in winding order. + * The lists are allocated from one memory pool. + */ void BKE_mesh_edge_loop_map_create(MeshElemMap **r_map, int **r_mem, const struct MEdge *medge, @@ -139,6 +168,11 @@ void BKE_mesh_edge_loop_map_create(MeshElemMap **r_map, const int totpoly, const struct MLoop *mloop, const int totloop); +/** + * Generates a map where the key is the edge and the value + * is a list of polygons that use that edge. + * The lists are allocated from one memory pool. + */ void BKE_mesh_edge_poly_map_create(MeshElemMap **r_map, int **r_mem, const struct MEdge *medge, @@ -147,11 +181,29 @@ void BKE_mesh_edge_poly_map_create(MeshElemMap **r_map, const int totpoly, const struct MLoop *mloop, const int totloop); +/** + * This function creates a map so the source-data (vert/edge/loop/poly) + * can loop over the destination data (using the destination arrays origindex). + * + * This has the advantage that it can operate on any data-types. + * + * \param totsource: The total number of elements that \a final_origindex points to. + * \param totfinal: The size of \a final_origindex + * \param final_origindex: The size of the final array. + * + * \note `totsource` could be `totpoly`, + * `totfinal` could be `tottessface` and `final_origindex` its ORIGINDEX custom-data. + * This would allow an MPoly to loop over its tessfaces. + */ void BKE_mesh_origindex_map_create(MeshElemMap **r_map, int **r_mem, const int totsource, const int *final_origindex, const int totfinal); +/** + * A version of #BKE_mesh_origindex_map_create that takes a looptri array. + * Making a poly -> looptri map. + */ void BKE_mesh_origindex_map_create_looptri(MeshElemMap **r_map, int **r_mem, const struct MPoly *mpoly, @@ -212,7 +264,11 @@ typedef bool (*MeshRemapIslandsCalc)(struct MVert *verts, struct MeshIslandStore *r_island_store); /* Above vert/UV mapping stuff does not do what we need here, but does things we do not need here. - * So better keep them separated for now, I think. + * So better keep them separated for now, I think. */ + +/** + * Calculate 'generic' UV islands, i.e. based only on actual geometry data (edge seams), + * not some UV layers coordinates. */ bool BKE_mesh_calc_islands_loop_poly_edgeseam(struct MVert *verts, const int totvert, @@ -224,6 +280,19 @@ bool BKE_mesh_calc_islands_loop_poly_edgeseam(struct MVert *verts, const int totloop, MeshIslandStore *r_island_store); +/** + * Calculate UV islands. + * + * \note If no MLoopUV layer is passed, we only consider edges tagged as seams as UV boundaries. + * This has the advantages of simplicity, and being valid/common to all UV maps. + * However, it means actual UV islands without matching UV seams will not be handled correctly. + * If a valid UV layer is passed as \a luvs parameter, + * UV coordinates are also used to detect islands boundaries. + * + * \note All this could be optimized. + * Not sure it would be worth the more complex code, though, + * those loops are supposed to be really quick to do. + */ bool BKE_mesh_calc_islands_loop_poly_uvmap(struct MVert *verts, const int totvert, struct MEdge *edges, @@ -235,6 +304,14 @@ bool BKE_mesh_calc_islands_loop_poly_uvmap(struct MVert *verts, const struct MLoopUV *luvs, MeshIslandStore *r_island_store); +/** + * Calculate smooth groups from sharp edges. + * + * \param r_totgroup: The total number of groups, 1 or more. + * \return Polygon aligned array of group index values (bitflags if use_bitflags is true), + * starting at 1 (0 being used as 'invalid' flag). + * Note it's callers's responsibility to MEM_freeN returned array. + */ int *BKE_mesh_calc_smoothgroups(const struct MEdge *medge, const int totedge, const struct MPoly *mpoly, diff --git a/source/blender/blenkernel/BKE_mesh_mirror.h b/source/blender/blenkernel/BKE_mesh_mirror.h index eaa479be867..abb8e4d3e44 100644 --- a/source/blender/blenkernel/BKE_mesh_mirror.h +++ b/source/blender/blenkernel/BKE_mesh_mirror.h @@ -43,6 +43,10 @@ void BKE_mesh_mirror_apply_mirror_on_axis(struct Main *bmain, const int axis, const float dist); +/** + * \warning This should _not_ be used to modify original meshes since + * it doesn't handle shape-keys, use #BKE_mesh_mirror_apply_mirror_on_axis instead. + */ struct Mesh *BKE_mesh_mirror_apply_mirror_on_axis_for_modifier( struct MirrorModifierData *mmd, struct Object *ob, diff --git a/source/blender/blenkernel/BKE_mesh_remap.h b/source/blender/blenkernel/BKE_mesh_remap.h index 7f8f028c26b..c33b3800aa4 100644 --- a/source/blender/blenkernel/BKE_mesh_remap.h +++ b/source/blender/blenkernel/BKE_mesh_remap.h @@ -161,11 +161,24 @@ void BKE_mesh_remap_calc_source_cddata_masks_from_map_modes( const int poly_mode, struct CustomData_MeshMasks *cddata_mask); +/** + * Compute a value of the difference between both given meshes. + * The smaller the result, the better the match. + * + * We return the inverse of the average of the inversed + * shortest distance from each dst vertex to src ones. + * In other words, beyond a certain (relatively small) distance, all differences have more or less + * the same weight in final result, which allows to reduce influence of a few high differences, + * in favor of a global good matching. + */ float BKE_mesh_remap_calc_difference_from_mesh(const struct SpaceTransform *space_transform, const struct MVert *verts_dst, const int numverts_dst, struct Mesh *me_src); +/** + * Set r_space_transform so that best bbox of dst matches best bbox of src. + */ void BKE_mesh_remap_find_best_match_from_mesh(const struct MVert *verts_dst, const int numverts_dst, struct Mesh *me_src, diff --git a/source/blender/blenkernel/BKE_mesh_runtime.h b/source/blender/blenkernel/BKE_mesh_runtime.h index df111360bcd..764241e7f92 100644 --- a/source/blender/blenkernel/BKE_mesh_runtime.h +++ b/source/blender/blenkernel/BKE_mesh_runtime.h @@ -41,18 +41,42 @@ struct Mesh; struct Object; struct Scene; +/** + * \brief Initialize the runtime of the given mesh. + * + * Function expects that the runtime is already cleared. + */ void BKE_mesh_runtime_init_data(struct Mesh *mesh); +/** + * \brief Free all data (and mutexes) inside the runtime of the given mesh. + */ void BKE_mesh_runtime_free_data(struct Mesh *mesh); +/** + * Clear all pointers which we don't want to be shared on copying the datablock. + * However, keep all the flags which defines what the mesh is (for example, that + * it's deformed only, or that its custom data layers are out of date.) + */ void BKE_mesh_runtime_reset_on_copy(struct Mesh *mesh, const int flag); int BKE_mesh_runtime_looptri_len(const struct Mesh *mesh); void BKE_mesh_runtime_looptri_recalc(struct Mesh *mesh); +/** + * \note This function only fills a cache, and therefore the mesh argument can + * be considered logically const. Concurrent access is protected by a mutex. + * \note This is a ported copy of dm_getLoopTriArray(dm). + */ const struct MLoopTri *BKE_mesh_runtime_looptri_ensure(const struct Mesh *mesh); bool BKE_mesh_runtime_ensure_edit_data(struct Mesh *mesh); bool BKE_mesh_runtime_clear_edit_data(struct Mesh *mesh); bool BKE_mesh_runtime_reset_edit_data(struct Mesh *mesh); void BKE_mesh_runtime_clear_geometry(struct Mesh *mesh); +/** + * \brief This function clears runtime cache of the given mesh. + * + * Call this function to recalculate runtime data when used. + */ void BKE_mesh_runtime_clear_cache(struct Mesh *mesh); +/* This is a copy of DM_verttri_from_looptri(). */ void BKE_mesh_runtime_verttri_from_looptri(struct MVertTri *r_verttri, const struct MLoop *mloop, const struct MLoopTri *looptri, @@ -62,6 +86,7 @@ void BKE_mesh_runtime_verttri_from_looptri(struct MVertTri *r_verttri, * to a more suitable location when that file is removed. * They should also be renamed to use conventions from BKE, not old DerivedMesh.cc. * For now keep the names similar to avoid confusion. */ + struct Mesh *mesh_get_eval_final(struct Depsgraph *depsgraph, struct Scene *scene, struct Object *ob, @@ -99,6 +124,7 @@ void BKE_mesh_runtime_eval_to_meshkey(struct Mesh *me_deformed, #ifndef NDEBUG char *BKE_mesh_runtime_debug_info(struct Mesh *me_eval); void BKE_mesh_runtime_debug_print(struct Mesh *me_eval); +/* XXX Should go in customdata file? */ void BKE_mesh_runtime_debug_print_cdlayers(struct CustomData *data); bool BKE_mesh_runtime_is_valid(struct Mesh *me_eval); #endif /* NDEBUG */ diff --git a/source/blender/blenkernel/BKE_mesh_tangent.h b/source/blender/blenkernel/BKE_mesh_tangent.h index 96eaa23ce71..39d4072085c 100644 --- a/source/blender/blenkernel/BKE_mesh_tangent.h +++ b/source/blender/blenkernel/BKE_mesh_tangent.h @@ -25,6 +25,12 @@ extern "C" { struct ReportList; +/** + * Compute simplified tangent space normals, i.e. + * tangent vector + sign of bi-tangent one, which combined with + * split normals can be used to recreate the full tangent space. + * NOTE: * The mesh should be made of only tris and quads! + */ void BKE_mesh_calc_loop_tangent_single_ex(const struct MVert *mverts, const int numVerts, const struct MLoop *mloops, @@ -35,11 +41,20 @@ void BKE_mesh_calc_loop_tangent_single_ex(const struct MVert *mverts, const struct MPoly *mpolys, const int numPolys, struct ReportList *reports); +/** + * Wrapper around BKE_mesh_calc_loop_tangent_single_ex, which takes care of most boiling code. + * \note + * - There must be a valid loop's CD_NORMALS available. + * - The mesh should be made of only tris and quads! + */ void BKE_mesh_calc_loop_tangent_single(struct Mesh *mesh, const char *uvmap, float (*r_looptangents)[4], struct ReportList *reports); +/** + * See: #BKE_editmesh_loop_tangent_calc (matching logic). + */ void BKE_mesh_calc_loop_tangent_ex(const struct MVert *mvert, const struct MPoly *mpoly, const uint mpoly_len, @@ -71,6 +86,12 @@ void BKE_mesh_add_loop_tangent_named_layer_for_uv(struct CustomData *uv_data, const char *layer_name); #define DM_TANGENT_MASK_ORCO (1 << 9) +/** + * Here we get some useful information such as active uv layer name and + * search if it is already in tangent_names. + * Also, we calculate tangent_mask that works as a descriptor of tangents state. + * If tangent_mask has changed, then recalculate tangents. + */ void BKE_mesh_calc_loop_tangent_step_0(const struct CustomData *loopData, bool calc_active_tangent, const char (*tangent_names)[64], diff --git a/source/blender/blenkernel/BKE_modifier.h b/source/blender/blenkernel/BKE_modifier.h index eca6bc38da6..278189633a6 100644 --- a/source/blender/blenkernel/BKE_modifier.h +++ b/source/blender/blenkernel/BKE_modifier.h @@ -403,6 +403,10 @@ void BKE_modifier_init(void); const ModifierTypeInfo *BKE_modifier_get_info(ModifierType type); /* For modifier UI panels. */ + +/** + * Get the idname of the modifier type's panel, which was defined in the #panelRegister callback. + */ void BKE_modifier_type_panel_id(ModifierType type, char *r_idname); void BKE_modifier_panel_expand(struct ModifierData *md); @@ -413,6 +417,9 @@ struct ModifierData *BKE_modifier_new(int type); void BKE_modifier_free_ex(struct ModifierData *md, const int flag); void BKE_modifier_free(struct ModifierData *md); +/** + * Use instead of `BLI_remlink` when the object's active modifier should change. + */ void BKE_modifier_remove_from_list(struct Object *ob, struct ModifierData *md); /* Generate new UUID for the given modifier. */ @@ -420,6 +427,9 @@ void BKE_modifier_session_uuid_generate(struct ModifierData *md); bool BKE_modifier_unique_name(struct ListBase *modifiers, struct ModifierData *md); +/** + * Callback's can use this to avoid copying every member. + */ void BKE_modifier_copydata_generic(const struct ModifierData *md, struct ModifierData *md_dst, const int flag); @@ -434,9 +444,21 @@ bool BKE_modifier_couldbe_cage(struct Scene *scene, struct ModifierData *md); bool BKE_modifier_is_correctable_deformed(struct ModifierData *md); bool BKE_modifier_is_same_topology(ModifierData *md); bool BKE_modifier_is_non_geometrical(ModifierData *md); +/** + * Check whether is enabled. + * + * \param scene: Current scene, may be NULL, + * in which case `isDisabled` callback of the modifier is never called. + */ bool BKE_modifier_is_enabled(const struct Scene *scene, struct ModifierData *md, int required_mode); +/** + * Check whether given modifier is not local (i.e. from linked data) when the object is a library + * override. + * + * \param md: May be NULL, in which case we consider it as a non-local modifier case. + */ bool BKE_modifier_is_nonlocal_in_liboverride(const struct Object *ob, const struct ModifierData *md); void BKE_modifier_set_error(const struct Object *ob, @@ -451,6 +473,12 @@ void BKE_modifiers_foreach_tex_link(struct Object *ob, TexWalkFunc walk, void *u struct ModifierData *BKE_modifiers_findby_type(const struct Object *ob, ModifierType type); struct ModifierData *BKE_modifiers_findby_name(const struct Object *ob, const char *name); void BKE_modifiers_clear_errors(struct Object *ob); +/** + * used for buttons, to find out if the 'draw deformed in edit-mode option is there. + * + * Also used in transform_conversion.c, to detect crazy-space (2nd arg then is NULL). + * Also used for some mesh tools to give warnings. + */ int BKE_modifiers_get_cage_index(const struct Scene *scene, struct Object *ob, int *r_lastPossibleCageIndex, @@ -461,9 +489,21 @@ bool BKE_modifiers_is_softbody_enabled(struct Object *ob); bool BKE_modifiers_is_cloth_enabled(struct Object *ob); bool BKE_modifiers_is_particle_enabled(struct Object *ob); +/** + * Takes an object and returns its first selected armature, else just its armature. + * This should work for multiple armatures per object. + */ struct Object *BKE_modifiers_is_deformed_by_armature(struct Object *ob); struct Object *BKE_modifiers_is_deformed_by_meshdeform(struct Object *ob); +/** + * Takes an object and returns its first selected lattice, else just its lattice. + * This should work for multiple lattices per object. + */ struct Object *BKE_modifiers_is_deformed_by_lattice(struct Object *ob); +/** + * Takes an object and returns its first selected curve, else just its curve. + * This should work for multiple curves per object. + */ struct Object *BKE_modifiers_is_deformed_by_curve(struct Object *ob); bool BKE_modifiers_uses_multires(struct Object *ob); bool BKE_modifiers_uses_armature(struct Object *ob, struct bArmature *arm); @@ -500,23 +540,36 @@ typedef struct VirtualModifierData { ShapeKeyModifierData smd; } VirtualModifierData; +/** + * This is to include things that are not modifiers in the evaluation of the modifier stack, + * for example parenting to an armature. + */ struct ModifierData *BKE_modifiers_get_virtual_modifierlist(const struct Object *ob, struct VirtualModifierData *data); -/** Ensure modifier correctness when changing ob->data. */ +/** + * Ensure modifier correctness when changing `ob->data`. + */ void BKE_modifiers_test_object(struct Object *ob); -/* here for do_versions */ +/** + * Here for #do_versions. + */ void BKE_modifier_mdef_compact_influences(struct ModifierData *md); +/** + * Initializes `path` with either the blend file or temporary directory. + */ void BKE_modifier_path_init(char *path, int path_maxlen, const char *name); const char *BKE_modifier_path_relbase(struct Main *bmain, struct Object *ob); const char *BKE_modifier_path_relbase_from_global(struct Object *ob); /* Accessors of original/evaluated modifiers. */ -/* For a given modifier data, get corresponding original one. - * If the modifier data is already original, return it as-is. */ +/** + * For a given modifier data, get corresponding original one. + * If the modifier data is already original, return it as-is. + */ struct ModifierData *BKE_modifier_get_original(struct ModifierData *md); struct ModifierData *BKE_modifier_get_evaluated(struct Depsgraph *depsgraph, struct Object *object, @@ -541,6 +594,15 @@ void BKE_modifier_deform_vertsEM(ModifierData *md, float (*vertexCos)[3], int numVerts); +/** + * Get evaluated mesh for other evaluated object, which is used as an operand for the modifier, + * e.g. second operand for boolean modifier. + * Note that modifiers in stack always get fully evaluated COW ID pointers, + * never original ones. Makes things simpler. + * + * \param get_cage_mesh: Return evaluated mesh with only deforming modifiers applied + * (i.e. mesh topology remains the same as original one, a.k.a. 'cage' mesh). + */ struct Mesh *BKE_modifier_get_evaluated_mesh_from_evaluated_object(struct Object *ob_eval, const bool get_cage_mesh); diff --git a/source/blender/blenkernel/BKE_movieclip.h b/source/blender/blenkernel/BKE_movieclip.h index 73c7494b8fa..9148d5b760f 100644 --- a/source/blender/blenkernel/BKE_movieclip.h +++ b/source/blender/blenkernel/BKE_movieclip.h @@ -35,6 +35,10 @@ struct MovieClipScopes; struct MovieClipUser; struct MovieDistortion; +/** + * Checks if image was already loaded, then returns same image otherwise creates new. + * does not load ibuf itself pass on optional frame for #name images. + */ struct MovieClip *BKE_movieclip_file_add(struct Main *bmain, const char *name); struct MovieClip *BKE_movieclip_file_add_exists_ex(struct Main *bmain, const char *filepath, @@ -44,6 +48,11 @@ void BKE_movieclip_reload(struct Main *bmain, struct MovieClip *clip); void BKE_movieclip_clear_cache(struct MovieClip *clip); void BKE_movieclip_clear_proxy_cache(struct MovieClip *clip); +/** + * Will try to make image buffer usable when originating from the multi-layer source. + * Internally finds a first combined pass and uses that as a buffer. + * Not ideal, but is better than a complete empty buffer. + */ void BKE_movieclip_convert_multilayer_ibuf(struct ImBuf *ibuf); struct ImBuf *BKE_movieclip_get_ibuf(struct MovieClip *clip, struct MovieClipUser *user); @@ -75,11 +84,18 @@ void BKE_movieclip_update_scopes(struct MovieClip *clip, struct MovieClipUser *user, struct MovieClipScopes *scopes); +/** + * Get segments of cached frames. useful for debugging cache policies. + */ void BKE_movieclip_get_cache_segments(struct MovieClip *clip, struct MovieClipUser *user, int *r_totseg, int **r_points); +/** + * \note currently used by proxy job for movies, threading happens within single frame + * (meaning scaling shall be threaded). + */ void BKE_movieclip_build_proxy_frame(struct MovieClip *clip, int clip_flag, struct MovieDistortion *distortion, @@ -88,6 +104,10 @@ void BKE_movieclip_build_proxy_frame(struct MovieClip *clip, int build_count, bool undistorted); +/** + * \note currently used by proxy job for sequences, threading happens within sequence + * (different threads handles different frames, no threading within frame is needed) + */ void BKE_movieclip_build_proxy_frame_for_ibuf(struct MovieClip *clip, struct ImBuf *ibuf, struct MovieDistortion *distortion, @@ -104,8 +124,10 @@ void BKE_movieclip_filename_for_frame(struct MovieClip *clip, struct MovieClipUser *user, char *name); -/* Read image buffer from the given movie clip without acquiring the `LOCK_MOVIECLIP` lock. - * Used by a prefetch job which takes care of creating a local copy of the clip. */ +/** + * Read image buffer from the given movie clip without acquiring the #LOCK_MOVIECLIP lock. + * Used by a prefetch job which takes care of creating a local copy of the clip. + */ struct ImBuf *BKE_movieclip_anim_ibuf_for_frame_no_lock(struct MovieClip *clip, struct MovieClipUser *user); @@ -126,10 +148,10 @@ void BKE_movieclip_eval_update(struct Depsgraph *depsgraph, struct MovieClip *clip); void BKE_movieclip_eval_selection_update(struct Depsgraph *depsgraph, struct MovieClip *clip); -/* caching flags */ +/** Caching flags. */ #define MOVIECLIP_CACHE_SKIP (1 << 0) -/* postprocessing flags */ +/** Post-processing flags. */ #define MOVIECLIP_DISABLE_RED (1 << 0) #define MOVIECLIP_DISABLE_GREEN (1 << 1) #define MOVIECLIP_DISABLE_BLUE (1 << 2) diff --git a/source/blender/blenkernel/BKE_multires.h b/source/blender/blenkernel/BKE_multires.h index 11bfc4b2b3a..c83022c4658 100644 --- a/source/blender/blenkernel/BKE_multires.h +++ b/source/blender/blenkernel/BKE_multires.h @@ -45,7 +45,9 @@ struct MLoopTri; struct MPoly; struct MVert; -/* Delete mesh mdisps and grid paint masks */ +/** + * Delete mesh mdisps and grid paint masks. + */ void multires_customdata_delete(struct Mesh *me); void multires_set_tot_level(struct Object *ob, struct MultiresModifierData *mmd, int lvl); @@ -62,6 +64,9 @@ void multires_force_external_reload(struct Object *object); void multires_modifier_update_mdisps(struct DerivedMesh *dm, struct Scene *scene); void multires_modifier_update_hidden(struct DerivedMesh *dm); +/** + * Reset the multi-res levels to match the number of mdisps. + */ void multiresModifier_set_levels_from_disps(struct MultiresModifierData *mmd, struct Object *ob); typedef enum { @@ -79,6 +84,10 @@ struct DerivedMesh *multires_make_derived_from_derived(struct DerivedMesh *dm, struct MultiresModifierData *find_multires_modifier_before(struct Scene *scene, struct ModifierData *lastmd); +/** + * used for applying scale on mdisps layer and syncing subdivide levels when joining objects. + * \param use_first: return first multi-res modifier if all multi-res'es are disabled. + */ struct MultiresModifierData *get_multires_modifier(struct Scene *scene, struct Object *ob, bool use_first); @@ -88,18 +97,25 @@ int multires_get_level(const struct Scene *scene, bool render, bool ignore_simplify); -/* Creates mesh with multires modifier applied on current object's deform mesh. */ +/** + * Creates mesh with multi-res modifier applied on current object's deform mesh. + */ struct Mesh *BKE_multires_create_mesh(struct Depsgraph *depsgraph, struct Object *object, struct MultiresModifierData *mmd); -/* Get coordinates of a deformed base mesh which is an input to the given multires modifier. - * NOTE: The modifiers will be re-evaluated. */ +/** + * Get coordinates of a deformed base mesh which is an input to the given multi-res modifier. + * \note The modifiers will be re-evaluated. + */ float (*BKE_multires_create_deformed_base_mesh_vert_coords(struct Depsgraph *depsgraph, struct Object *object, struct MultiresModifierData *mmd, int *r_num_deformed_verts))[3]; +/** + * \param direction: 1 for delete higher, 0 for lower (not implemented yet). + */ void multiresModifier_del_levels(struct MultiresModifierData *mmd, struct Scene *scene, struct Object *object, @@ -112,6 +128,10 @@ int multiresModifier_rebuild_subdiv(struct Depsgraph *depsgraph, struct MultiresModifierData *mmd, int rebuild_limit, bool switch_view_to_lower_level); +/** + * If `ob_src` and `ob_dst` both have multi-res modifiers, + * synchronize them such that `ob_dst` has the same total number of levels as `ob_src`. + */ void multiresModifier_sync_levels_ex(struct Object *ob_dst, struct MultiresModifierData *mmd_src, struct MultiresModifierData *mmd_dst); @@ -128,15 +148,29 @@ void multiresModifier_prepare_join(struct Depsgraph *depsgraph, int multires_mdisp_corners(struct MDisps *s); -/* update multires data after topology changing */ +/** + * Update multi-res data after topology changing. + */ void multires_topology_changed(struct Mesh *me); +/** + * Makes sure data from an external file is fully read. + * + * Since the multi-res data files only contain displacement vectors without knowledge about + * subdivision level some extra work is needed. Namely make is to all displacement grids have + * proper level and number of displacement vectors set. + */ void multires_ensure_external_read(struct Mesh *mesh, int top_level); void multiresModifier_ensure_external_read(struct Mesh *mesh, const struct MultiresModifierData *mmd); /**** interpolation stuff ****/ +/* Adapted from `sculptmode.c` */ + void old_mdisps_bilinear(float out[3], float (*disps)[3], const int st, float u, float v); +/** + * Find per-corner coordinate with given per-face UV coord. + */ int mdisp_rot_face_to_crn(struct MVert *mvert, struct MPoly *mpoly, struct MLoop *mloop, @@ -154,6 +188,12 @@ bool multiresModifier_reshapeFromVertcos(struct Depsgraph *depsgraph, struct MultiresModifierData *mmd, const float (*vert_coords)[3], const int num_vert_coords); +/** + * Returns truth on success, false otherwise. + * + * This function might fail in cases like source and destination not having + * matched amount of vertices. + */ bool multiresModifier_reshapeFromObject(struct Depsgraph *depsgraph, struct MultiresModifierData *mmd, struct Object *dst, @@ -166,7 +206,7 @@ bool multiresModifier_reshapeFromCCG(const int tot_level, struct Mesh *coarse_mesh, struct SubdivCCG *subdiv_ccg); -/* Subdivide multires displacement once. */ +/* Subdivide multi-res displacement once. */ typedef enum eMultiresSubdivideModeType { MULTIRES_SUBDIVIDE_CATMULL_CLARK, @@ -180,8 +220,10 @@ void multiresModifier_subdivide(struct Object *object, void multires_subdivide_create_tangent_displacement_linear_grids(struct Object *object, struct MultiresModifierData *mmd); -/* Subdivide displacement to the given level. - * If level is lower than the current top level nothing happens. */ +/** + * Subdivide displacement to the given level. + * If level is lower than the current top level nothing happens. + */ void multiresModifier_subdivide_to_level(struct Object *object, struct MultiresModifierData *mmd, const int top_level, @@ -206,12 +248,12 @@ void BKE_multires_subdiv_mesh_settings_init(struct SubdivToMeshSettings *mesh_se /* General helpers. */ -/* For a given partial derivatives of a ptex face get tangent matrix for - * displacement. +/** + * For a given partial derivatives of a PTEX face get tangent matrix for displacement. * * Corner needs to be known to properly "rotate" partial derivatives when the - * matrix is being constructed for quad. For non-quad the corner is to be set - * to 0. */ + * matrix is being constructed for quad. For non-quad the corner is to be set to 0. + */ BLI_INLINE void BKE_multires_construct_tangent_matrix(float tangent_matrix[3][3], const float dPdu[3], const float dPdv[3], @@ -219,8 +261,10 @@ BLI_INLINE void BKE_multires_construct_tangent_matrix(float tangent_matrix[3][3] /* Versioning. */ -/* Convert displacement which is stored for simply-subdivided mesh to a Catmull-Clark - * subdivided mesh. */ +/** + * Convert displacement which is stored for simply-subdivided mesh to a Catmull-Clark + * subdivided mesh. + */ void multires_do_versions_simple_to_catmull_clark(struct Object *object, struct MultiresModifierData *mmd); diff --git a/source/blender/blenkernel/BKE_nla.h b/source/blender/blenkernel/BKE_nla.h index cf8848fe607..b53f8dbac68 100644 --- a/source/blender/blenkernel/BKE_nla.h +++ b/source/blender/blenkernel/BKE_nla.h @@ -46,106 +46,291 @@ struct PropertyRNA; /* ----------------------------- */ /* Data Management */ +/** + * Remove the given NLA strip from the NLA track it occupies, free the strip's data, + * and the strip itself. + */ void BKE_nlastrip_free(ListBase *strips, struct NlaStrip *strip, bool do_id_user); +/** + * Remove the given NLA track from the set of NLA tracks, free the track's data, + * and the track itself. + */ void BKE_nlatrack_free(ListBase *tracks, struct NlaTrack *nlt, bool do_id_user); +/** + * Free the elements of type NLA Tracks provided in the given list, but do not free + * the list itself since that is not free-standing + */ void BKE_nla_tracks_free(ListBase *tracks, bool do_id_user); +/** + * Copy NLA strip + * + * \param use_same_action: When true, the existing action is used (instead of being duplicated) + * \param flag: Control ID pointers management, see LIB_ID_CREATE_.../LIB_ID_COPY_... + * flags in BKE_lib_id.h + */ struct NlaStrip *BKE_nlastrip_copy(struct Main *bmain, struct NlaStrip *strip, const bool use_same_action, const int flag); +/** + * Copy a single NLA Track. + * \param flag: Control ID pointers management, see LIB_ID_CREATE_.../LIB_ID_COPY_... + * flags in BKE_lib_id.h + */ struct NlaTrack *BKE_nlatrack_copy(struct Main *bmain, struct NlaTrack *nlt, const bool use_same_actions, const int flag); +/** + * Copy all NLA data. + * \param flag: Control ID pointers management, see LIB_ID_CREATE_.../LIB_ID_COPY_... + * flags in BKE_lib_id.h + */ void BKE_nla_tracks_copy(struct Main *bmain, ListBase *dst, const ListBase *src, const int flag); -/* Copy NLA tracks from #adt_source to #adt_dest, and update the active track/strip pointers to - * point at those copies. */ +/** + * Copy NLA tracks from #adt_source to #adt_dest, and update the active track/strip pointers to + * point at those copies. + */ void BKE_nla_tracks_copy_from_adt(struct Main *bmain, struct AnimData *adt_dest, const struct AnimData *adt_source, int flag); +/** + * Add a NLA Track to the given AnimData. + * \param prev: NLA-Track to add the new one after. + */ struct NlaTrack *BKE_nlatrack_add(struct AnimData *adt, struct NlaTrack *prev, bool is_liboverride); +/** + * Create a NLA Strip referencing the given Action. + */ struct NlaStrip *BKE_nlastrip_new(struct bAction *act); +/** + * Add new NLA-strip to the top of the NLA stack - i.e. + * into the last track if space, or a new one otherwise. + */ struct NlaStrip *BKE_nlastack_add_strip(struct AnimData *adt, struct bAction *act, const bool is_liboverride); +/** + * Add a NLA Strip referencing the given speaker's sound. + */ struct NlaStrip *BKE_nla_add_soundstrip(struct Main *bmain, struct Scene *scene, struct Speaker *speaker); +/** + * Callback used by lib_query to walk over all ID usages + * (mimics `foreach_id` callback of #IDTypeInfo structure). + */ void BKE_nla_strip_foreach_id(struct NlaStrip *strip, struct LibraryForeachIDData *data); /* ----------------------------- */ /* API */ +/** + * Check if there is any space in the given list to add the given strip. + */ bool BKE_nlastrips_has_space(ListBase *strips, float start, float end); +/** + * Rearrange the strips in the track so that they are always in order + * (usually only needed after a strip has been moved) + */ void BKE_nlastrips_sort_strips(ListBase *strips); +/** + * Add the given NLA-Strip to the given list of strips, assuming that it + * isn't currently a member of another list + */ bool BKE_nlastrips_add_strip(ListBase *strips, struct NlaStrip *strip); +/** + * Convert 'islands' (i.e. continuous string of) selected strips to be + * contained within 'Meta-Strips' which act as strips which contain strips. + * + * \param temp: are the meta-strips to be created 'temporary' ones used for transforms? + */ void BKE_nlastrips_make_metas(ListBase *strips, bool is_temp); +/** + * Remove meta-strips (i.e. flatten the list of strips) from the top-level of the list of strips. + * + * \param sel: only consider selected meta-strips, otherwise all meta-strips are removed + * \param onlyTemp: only remove the 'temporary' meta-strips used for transforms + */ void BKE_nlastrips_clear_metas(ListBase *strips, bool only_sel, bool only_temp); +/** + * Split a meta-strip into a set of normal strips. + */ void BKE_nlastrips_clear_metastrip(ListBase *strips, struct NlaStrip *strip); +/** + * Add the given NLA-Strip to the given Meta-Strip, assuming that the + * strip isn't attached to any list of strips + */ bool BKE_nlameta_add_strip(struct NlaStrip *mstrip, struct NlaStrip *strip); +/** + * Adjust the settings of NLA-Strips contained within a Meta-Strip (recursively), + * until the Meta-Strips children all fit within the Meta-Strip's new dimensions + */ void BKE_nlameta_flush_transforms(struct NlaStrip *mstrip); /* ............ */ +/** + * Find the active NLA-track for the given stack. + */ struct NlaTrack *BKE_nlatrack_find_active(ListBase *tracks); +/** + * Make the given NLA-track the active one for the given stack. If no track is provided, + * this function can be used to simply deactivate all the NLA tracks in the given stack too. + */ void BKE_nlatrack_set_active(ListBase *tracks, struct NlaTrack *nlt); +/** + * Get the NLA Track that the active action/action strip comes from, + * since this info is not stored in AnimData. It also isn't as simple + * as just using the active track, since multiple tracks may have been + * entered at the same time. + */ struct NlaTrack *BKE_nlatrack_find_tweaked(struct AnimData *adt); +/** + * Toggle the 'solo' setting for the given NLA-track, making sure that it is the only one + * that has this status in its AnimData block. + */ void BKE_nlatrack_solo_toggle(struct AnimData *adt, struct NlaTrack *nlt); +/** + * Check if there is any space in the given track to add a strip of the given length. + */ bool BKE_nlatrack_has_space(struct NlaTrack *nlt, float start, float end); +/** + * Rearrange the strips in the track so that they are always in order + * (usually only needed after a strip has been moved). + */ void BKE_nlatrack_sort_strips(struct NlaTrack *nlt); +/** + * Add the given NLA-Strip to the given NLA-Track, assuming that it + * isn't currently attached to another one. + */ bool BKE_nlatrack_add_strip(struct NlaTrack *nlt, struct NlaStrip *strip, const bool is_liboverride); +/** + * Get the extents of the given NLA-Track including gaps between strips, + * returning whether this succeeded or not + */ bool BKE_nlatrack_get_bounds(struct NlaTrack *nlt, float bounds[2]); - +/** + * Check whether given NLA track is not local (i.e. from linked data) when the object is a library + * override. + * + * \param nlt: May be NULL, in which case we consider it as a non-local track case. + */ bool BKE_nlatrack_is_nonlocal_in_liboverride(const struct ID *id, const struct NlaTrack *nlt); /* ............ */ +/** + * Find the active NLA-strip within the given track. + */ struct NlaStrip *BKE_nlastrip_find_active(struct NlaTrack *nlt); +/** + * Make the given NLA-Strip the active one within the given block. + */ void BKE_nlastrip_set_active(struct AnimData *adt, struct NlaStrip *strip); +/** + * Does the given NLA-strip fall within the given bounds (times)?. + */ bool BKE_nlastrip_within_bounds(struct NlaStrip *strip, float min, float max); +/** + * Recalculate the start and end frames for the current strip, after changing + * the extents of the action or the mapping (repeats or scale factor) info. + */ void BKE_nlastrip_recalculate_bounds(struct NlaStrip *strip); +/** + * Recalculate the start and end frames for the strip to match the bounds of its action such that + * the overall NLA animation result is unchanged. + */ void BKE_nlastrip_recalculate_bounds_sync_action(struct NlaStrip *strip); +/** + * Find (and set) a unique name for a strip from the whole AnimData block + * Uses a similar method to the BLI method, but is implemented differently + * as we need to ensure that the name is unique over several lists of tracks, + * not just a single track. + */ void BKE_nlastrip_validate_name(struct AnimData *adt, struct NlaStrip *strip); /* ............ */ +/** + * Check if the given NLA-Track has any strips with own F-Curves. + */ bool BKE_nlatrack_has_animated_strips(struct NlaTrack *nlt); +/** + * Check if given NLA-Tracks have any strips with own F-Curves. + */ bool BKE_nlatracks_have_animated_strips(ListBase *tracks); +/** + * Validate the NLA-Strips 'control' F-Curves based on the flags set. + */ void BKE_nlastrip_validate_fcurves(struct NlaStrip *strip); +/** + * Check if the given RNA pointer + property combo should be handled by + * NLA strip curves or not. + */ bool BKE_nlastrip_has_curves_for_property(const struct PointerRNA *ptr, const struct PropertyRNA *prop); +/** + * Ensure that auto-blending and other settings are set correctly. + */ void BKE_nla_validate_state(struct AnimData *adt); /* ............ */ +/** + * Check if an action is "stashed" in the NLA already + * + * The criteria for this are: + * 1) The action in question lives in a "stash" track. + * 2) We only check first-level strips. That is, we will not check inside meta strips. + */ bool BKE_nla_action_is_stashed(struct AnimData *adt, struct bAction *act); +/** + * "Stash" an action (i.e. store it as a track/layer in the NLA, but non-contributing) + * to retain it in the file for future uses. + */ bool BKE_nla_action_stash(struct AnimData *adt, const bool is_liboverride); /* ............ */ +/** + * For the given AnimData block, add the active action to the NLA + * stack (i.e. 'push-down' action). The UI should only allow this + * for normal editing only (i.e. not in edit-mode for some strip's action), + * so no checks for this are performed. + * + * TODO: maybe we should have checks for this too. + */ void BKE_nla_action_pushdown(struct AnimData *adt, const bool is_liboverride); +/** + * Find the active strip + track combination, and set them up as the tweaking track, + * and return if successful or not. + */ bool BKE_nla_tweakmode_enter(struct AnimData *adt); +/** + * Exit tweak-mode for this AnimData block. + */ void BKE_nla_tweakmode_exit(struct AnimData *adt); /* ----------------------------- */ @@ -163,6 +348,13 @@ enum eNlaTime_ConvertModes { NLATIME_CONVERT_MAP, }; +/** + * Non clipped mapping for strip-time <-> global time: + * `mode = eNlaTime_ConvertModes -> NLATIME_CONVERT_*` + * + * Public API method - perform this mapping using the given AnimData block + * and perform any necessary sanity checks on the value + */ float BKE_nla_tweakedit_remap(struct AnimData *adt, float cframe, short mode); /* ----------------------------- */ diff --git a/source/blender/blenkernel/BKE_node.h b/source/blender/blenkernel/BKE_node.h index f925834beac..57eab4f76cf 100644 --- a/source/blender/blenkernel/BKE_node.h +++ b/source/blender/blenkernel/BKE_node.h @@ -436,20 +436,44 @@ struct GHashIterator *ntreeTypeGetIterator(void); } \ (void)0 +/** + * Try to initialize all type-info in a node tree. + * + * \note In general undefined type-info is a perfectly valid case, + * the type may just be registered later. + * In that case the update_typeinfo function will set type-info on registration + * and do necessary updates. + */ void ntreeSetTypes(const struct bContext *C, struct bNodeTree *ntree); struct bNodeTree *ntreeAddTree(struct Main *bmain, const char *name, const char *idname); /* copy/free funcs, need to manage ID users */ + +/** + * Free (or release) any data used by this node-tree. + * Does not free the node-tree itself and does no ID user counting. + */ void ntreeFreeTree(struct bNodeTree *ntree); -/* Free tree which is embedded into another datablock. */ +/** + * Free tree which is embedded into another data-block. + */ void ntreeFreeEmbeddedTree(struct bNodeTree *ntree); struct bNodeTree *ntreeCopyTree_ex(const struct bNodeTree *ntree, struct Main *bmain, const bool do_id_user); struct bNodeTree *ntreeCopyTree(struct Main *bmain, const struct bNodeTree *ntree); +/** + * Get address of potential node-tree pointer of given ID. + * + * \warning Using this function directly is potentially dangerous, if you don't know or are not + * sure, please use `ntreeFromID()` instead. + */ struct bNodeTree **BKE_ntree_ptr_from_id(struct ID *id); +/** + * Returns the private NodeTree object of the data-block, if it has one. + */ struct bNodeTree *ntreeFromID(struct ID *id); void ntreeFreeLocalNode(struct bNodeTree *ntree, struct bNode *node); @@ -459,13 +483,17 @@ bool ntreeHasType(const struct bNodeTree *ntree, int type); bool ntreeHasTree(const struct bNodeTree *ntree, const struct bNodeTree *lookup); void ntreeUpdateTree(struct Main *main, struct bNodeTree *ntree); void ntreeUpdateAllNew(struct Main *main); +/** + * \param tree_update_flag: #eNodeTreeUpdate enum. + */ void ntreeUpdateAllUsers(struct Main *main, struct ID *id, int tree_update_flag); void ntreeGetDependencyList(struct bNodeTree *ntree, struct bNode ***r_deplist, int *r_deplist_len); -/* XXX old trees handle output flags automatically based on special output +/** + * XXX: old trees handle output flags automatically based on special output * node types and last active selection. * New tree types have a per-output socket flag to indicate the final output to use explicitly. */ @@ -476,11 +504,31 @@ void ntreeFreeCache(struct bNodeTree *ntree); bool ntreeNodeExists(const struct bNodeTree *ntree, const struct bNode *testnode); bool ntreeOutputExists(const struct bNode *node, const struct bNodeSocket *testsock); void ntreeNodeFlagSet(const bNodeTree *ntree, const int flag, const bool enable); +/** + * Returns localized tree for execution in threads. + */ struct bNodeTree *ntreeLocalize(struct bNodeTree *ntree); +/** + * Sync local composite with real tree. + * The local tree is supposed to be running, be careful moving previews! + * + * Is called by jobs manager, outside threads, so it doesn't happen during draw. + */ void ntreeLocalSync(struct bNodeTree *localtree, struct bNodeTree *ntree); +/** + * Merge local tree results back, and free local tree. + * + * We have to assume the editor already changed completely. + */ void ntreeLocalMerge(struct Main *bmain, struct bNodeTree *localtree, struct bNodeTree *ntree); +/** + * This is only direct data, tree itself should have been written. + */ void ntreeBlendWrite(struct BlendWriter *writer, struct bNodeTree *ntree); +/** + * \note `ntree` itself has been read! + */ void ntreeBlendReadData(struct BlendDataReader *reader, struct bNodeTree *ntree); void ntreeBlendReadLib(struct BlendLibReader *reader, struct bNodeTree *ntree); void ntreeBlendReadExpand(struct BlendExpander *expander, struct bNodeTree *ntree); @@ -614,27 +662,42 @@ void nodeModifySocketTypeStatic( struct bNode *nodeAddNode(const struct bContext *C, struct bNodeTree *ntree, const char *idname); struct bNode *nodeAddStaticNode(const struct bContext *C, struct bNodeTree *ntree, int type); +/** + * \note Goes over entire tree. + */ void nodeUnlinkNode(struct bNodeTree *ntree, struct bNode *node); +/** + * Find the first available, non-duplicate name for a given node. + */ void nodeUniqueName(struct bNodeTree *ntree, struct bNode *node); -/* Delete node, associated animation data and ID user count. */ +/** + * Delete node, associated animation data and ID user count. + */ void nodeRemoveNode(struct Main *bmain, struct bNodeTree *ntree, struct bNode *node, bool do_id_user); +/** + * \param ntree: is the target tree. + * + * \note keep socket list order identical, for copying links. + * \note `unique_name` needs to be true. It's only disabled for speed when doing GPUnodetrees. + */ struct bNode *BKE_node_copy_ex(struct bNodeTree *ntree, const struct bNode *node_src, const int flag, const bool unique_name); -/* Same as BKE_node_copy_ex() but stores pointers to a new node and its sockets in the source - * node. +/** + * Same as #BKE_node_copy_ex but stores pointers to a new node and its sockets in the source node. * * NOTE: DANGER ZONE! * * TODO(sergey): Maybe it's better to make BKE_node_copy_ex() return a mapping from old node and - * sockets to new one. */ + * sockets to new one. + */ struct bNode *BKE_node_copy_store_new_pointers(struct bNodeTree *ntree, struct bNode *node_src, const int flag); @@ -642,6 +705,9 @@ struct bNodeTree *ntreeCopyTree_ex_new_pointers(const struct bNodeTree *ntree, struct Main *bmain, const bool do_id_user); +/** + * Also used via RNA API, so we check for proper input output direction. + */ struct bNodeLink *nodeAddLink(struct bNodeTree *ntree, struct bNode *fromnode, struct bNodeSocket *fromsock, @@ -665,25 +731,62 @@ void nodePositionRelative(struct bNode *from_node, struct bNodeSocket *to_sock); void nodePositionPropagate(struct bNode *node); +/** + * Finds a node based on its name. + */ struct bNode *nodeFindNodebyName(struct bNodeTree *ntree, const char *name); +/** + * Finds a node based on given socket and returns true on success. + */ bool nodeFindNode(struct bNodeTree *ntree, struct bNodeSocket *sock, struct bNode **r_node, int *r_sockindex); +/** + * \note Recursive. + */ struct bNode *nodeFindRootParent(bNode *node); +/** + * \returns true if \a child has \a parent as a parent/grandparent/... etc. + * \note Recursive + */ bool nodeIsChildOf(const bNode *parent, const bNode *child); +/** + * Iterate over a chain of nodes, starting with \a node_start, executing + * \a callback for each node (which can return false to end iterator). + * + * \param reversed: for backwards iteration + * \note Recursive + */ void nodeChainIter(const bNodeTree *ntree, const bNode *node_start, bool (*callback)(bNode *, bNode *, void *, const bool), void *userdata, const bool reversed); +/** + * Iterate over a chain of nodes, starting with \a node_start, executing + * \a callback for each node (which can return false to end iterator). + * + * Faster than nodeChainIter. Iter only once per node. + * Can be called recursively (using another nodeChainIterBackwards) by + * setting the recursion_lvl accordingly. + * + * \note Needs updated socket links (ntreeUpdateTree). + * \note Recursive + */ void nodeChainIterBackwards(const bNodeTree *ntree, const bNode *node_start, bool (*callback)(bNode *, bNode *, void *), void *userdata, int recursion_lvl); +/** + * Iterate over all parents of \a node, executing \a callback for each parent + * (which can return false to end iterator) + * + * \note Recursive + */ void nodeParentsIter(bNode *node, bool (*callback)(bNode *, void *), void *userdata); struct bNodeLink *nodeFindLink(struct bNodeTree *ntree, @@ -692,11 +795,20 @@ struct bNodeLink *nodeFindLink(struct bNodeTree *ntree, int nodeCountSocketLinks(const struct bNodeTree *ntree, const struct bNodeSocket *sock); void nodeSetSelected(struct bNode *node, bool select); +/** + * Two active flags, ID nodes have special flag for buttons display. + */ void nodeSetActive(struct bNodeTree *ntree, struct bNode *node); struct bNode *nodeGetActive(struct bNodeTree *ntree); +/** + * Two active flags, ID nodes have special flag for buttons display. + */ struct bNode *nodeGetActiveID(struct bNodeTree *ntree, short idtype); bool nodeSetActiveID(struct bNodeTree *ntree, short idtype, struct ID *id); void nodeClearActive(struct bNodeTree *ntree); +/** + * Two active flags, ID nodes have special flag for buttons display. + */ void nodeClearActiveID(struct bNodeTree *ntree, short idtype); struct bNode *nodeGetActiveTexture(struct bNodeTree *ntree); @@ -712,14 +824,31 @@ void nodeSetSocketAvailability(struct bNodeTree *ntree, int nodeSocketLinkLimit(const struct bNodeSocket *sock); +/** + * If the node implements a `declare` function, this function makes sure that `node->declaration` + * is up to date. It is expected that the sockets of the node are up to date already. + */ bool nodeDeclarationEnsure(struct bNodeTree *ntree, struct bNode *node); +/** + * Just update `node->declaration` if necessary. This can also be called on nodes that may not be + * up to date (e.g. because the need versioning or are dynamic). + */ bool nodeDeclarationEnsureOnOutdatedNode(struct bNodeTree *ntree, struct bNode *node); +/** + * Update `socket->declaration` for all sockets in the node. This assumes that the node declaration + * and sockets are up to date already. + */ void nodeSocketDeclarationsUpdate(struct bNode *node); -/* Node Clipboard */ +/** + * Node Clipboard. + */ void BKE_node_clipboard_init(const struct bNodeTree *ntree); void BKE_node_clipboard_clear(void); void BKE_node_clipboard_free(void); +/** + * Return false when one or more ID's are lost. + */ bool BKE_node_clipboard_validate(void); void BKE_node_clipboard_add_node(struct bNode *node); void BKE_node_clipboard_add_link(struct bNodeLink *link); @@ -727,7 +856,9 @@ const struct ListBase *BKE_node_clipboard_get_nodes(void); const struct ListBase *BKE_node_clipboard_get_links(void); int BKE_node_clipboard_get_type(void); -/* Node Instance Hash */ +/** + * Node Instance Hash. + */ typedef struct bNodeInstanceHash { /** XXX should be made a direct member, #GHash allocation needs to support it */ GHash *ghash; @@ -735,6 +866,9 @@ typedef struct bNodeInstanceHash { typedef void (*bNodeInstanceValueFP)(void *value); +/** + * Magic number for initial hash key. + */ extern const bNodeInstanceKey NODE_INSTANCE_KEY_BASE; extern const bNodeInstanceKey NODE_INSTANCE_KEY_NONE; @@ -819,6 +953,11 @@ void BKE_node_preview_merge_tree(struct bNodeTree *to_ntree, struct bNodeTree *from_ntree, bool remove_old); +/** + * Hack warning! this function is only used for shader previews, + * and since it gets called multiple times per pixel for Z-transparency we only add the color once. + * Preview gets cleared before it starts render though. + */ void BKE_node_preview_set_pixel( struct bNodePreview *preview, const float col[4], int x, int y, bool do_manage); @@ -829,13 +968,18 @@ void BKE_node_preview_set_pixel( * \{ */ void nodeLabel(struct bNodeTree *ntree, struct bNode *node, char *label, int maxlen); +/** + * Get node socket label if it is set. + */ const char *nodeSocketLabel(const struct bNodeSocket *sock); bool nodeGroupPoll(struct bNodeTree *nodetree, struct bNodeTree *grouptree, const char **r_disabled_hint); -/* Init a new node type struct with default values and callbacks */ +/** + * Initialize a new node type struct with default values and callbacks. + */ void node_type_base(struct bNodeType *ntype, int type, const char *name, short nclass, short flag); void node_type_base_custom( struct bNodeType *ntype, const char *idname, const char *name, short nclass, short flag); @@ -846,6 +990,10 @@ void node_type_size(struct bNodeType *ntype, int width, int minwidth, int maxwid void node_type_size_preset(struct bNodeType *ntype, eNodeSizePreset size); void node_type_init(struct bNodeType *ntype, void (*initfunc)(struct bNodeTree *ntree, struct bNode *node)); +/** + * \warning Nodes defining a storage type _must_ allocate this for new nodes. + * Otherwise nodes will reload as undefined (T46619). + */ void node_type_storage(struct bNodeType *ntype, const char *storagename, void (*freefunc)(struct bNode *node), @@ -1095,8 +1243,18 @@ void BKE_nodetree_remove_layer_n(struct bNodeTree *ntree, struct bNodeTreeExec *ntreeShaderBeginExecTree(struct bNodeTree *ntree); void ntreeShaderEndExecTree(struct bNodeTreeExec *exec); +/** + Find an output node of the shader tree. + * + * \note it will only return output which is NOT in the group, which isn't how + * render engines works but it's how the GPU shader compilation works. This we + * can change in the future and make it a generic function, but for now it stays + * private here. + */ struct bNode *ntreeShaderOutputNode(struct bNodeTree *ntree, int target); - +/** + * This one needs to work on a local tree. + */ void ntreeGPUMaterialNodes(struct bNodeTree *localtree, struct GPUMaterial *mat, bool *has_surface_output, @@ -1288,7 +1446,22 @@ void ntreeCompositExecTree(struct Scene *scene, const struct ColorManagedViewSettings *view_settings, const struct ColorManagedDisplaySettings *display_settings, const char *view_name); + +/** + * Called from render pipeline, to tag render input and output. + * need to do all scenes, to prevent errors when you re-render 1 scene. + */ void ntreeCompositTagRender(struct Scene *scene); +/** + * Update the outputs of the render layer nodes. + * Since the outputs depend on the render engine, this part is a bit complex: + * - #ntreeCompositUpdateRLayers is called and loops over all render layer nodes. + * - Each render layer node calls the update function of the + * render engine that's used for its scene. + * - The render engine calls RE_engine_register_pass for each pass. + * - #RE_engine_register_pass calls #ntreeCompositRegisterPass, + * which calls #node_cmp_rlayers_register_pass for every render layer node. + */ void ntreeCompositUpdateRLayers(struct bNodeTree *ntree); void ntreeCompositRegisterPass(struct bNodeTree *ntree, struct Scene *scene, @@ -1329,8 +1502,10 @@ void ntreeCompositCryptomatteLayerPrefix(const Scene *scene, const bNode *node, char *r_prefix, size_t prefix_len); -/* Update the runtime layer names with the crypto-matte layer names of the references - * render layer or image. */ +/** + * Update the runtime layer names with the crypto-matte layer names of the references render layer + * or image. + */ void ntreeCompositCryptomatteUpdateLayerNames(const Scene *scene, bNode *node); struct CryptomatteSession *ntreeCompositCryptomatteSession(const Scene *scene, bNode *node); diff --git a/source/blender/blenkernel/BKE_object.h b/source/blender/blenkernel/BKE_object.h index 6e1486be0be..3f4268f2169 100644 --- a/source/blender/blenkernel/BKE_object.h +++ b/source/blender/blenkernel/BKE_object.h @@ -52,6 +52,14 @@ struct View3D; struct ViewLayer; void BKE_object_workob_clear(struct Object *workob); +/** + * For calculation of the inverse parent transform, only used for editor. + * + * It assumes the object parent is already in the depsgraph. + * Otherwise, after changing ob->parent you need to call: + * - #DEG_relations_tag_update(bmain); + * - #BKE_scene_graph_update_tagged(depsgraph, bmain); + */ void BKE_object_workob_calc_parent(struct Depsgraph *depsgraph, struct Scene *scene, struct Object *ob, @@ -67,6 +75,9 @@ void BKE_object_free_particlesystems(struct Object *ob); void BKE_object_free_softbody(struct Object *ob); void BKE_object_free_curve_cache(struct Object *ob); +/** + * Free data derived from mesh, called when mesh changes or is freed. + */ void BKE_object_free_derived_caches(struct Object *ob); void BKE_object_free_caches(struct Object *object); @@ -77,19 +88,55 @@ bool BKE_object_modifier_gpencil_use_time(struct Object *ob, struct GpencilModif bool BKE_object_shaderfx_use_time(struct Object *ob, struct ShaderFxData *fx); +/** + * \return True if the object's type supports regular modifiers (not grease pencil modifiers). + */ bool BKE_object_supports_modifiers(const struct Object *ob); bool BKE_object_support_modifier_type_check(const struct Object *ob, int modifier_type); /* Active modifier. */ + +/** + * Set the object's active modifier. + * + * \param md: If nullptr, only clear the active modifier, otherwise + * it must be in the #Object.modifiers list. + */ void BKE_object_modifier_set_active(struct Object *ob, struct ModifierData *md); struct ModifierData *BKE_object_active_modifier(const struct Object *ob); +/** + * Copy a single modifier. + * + * \note *Do not* use this function to copy a whole modifier stack (see note below too). Use + * `BKE_object_modifier_stack_copy` instead. + * + * \note Complex modifiers relaying on other data (like e.g. dynamic paint or fluid using particle + * systems) are not always 100% 'correctly' copied here, since we have to use heuristics to decide + * which particle system to use or add in `ob_dst`, and it's placement in the stack, etc. If used + * more than once, this function should preferably be called in stack order. + */ bool BKE_object_copy_modifier(struct Main *bmain, struct Scene *scene, struct Object *ob_dst, const struct Object *ob_src, struct ModifierData *md); +/** + * Copy a single GPencil modifier. + * + * \note *Do not* use this function to copy a whole modifier stack. Use + * `BKE_object_modifier_stack_copy` instead. + */ bool BKE_object_copy_gpencil_modifier(struct Object *ob_dst, struct GpencilModifierData *gmd_src); +/** + * Copy the whole stack of modifiers from one object into another. + * + * \warning *Does not* clear modifier stack and related data (particle systems, soft-body, + * etc.) in `ob_dst`, if needed calling code must do it. + * + * \param do_copy_all: If true, even modifiers that should not support copying (like Hook one) + * will be duplicated. + */ bool BKE_object_modifier_stack_copy(struct Object *ob_dst, const struct Object *ob_src, const bool do_copy_all, @@ -98,6 +145,12 @@ void BKE_object_link_modifiers(struct Object *ob_dst, const struct Object *ob_sr void BKE_object_free_modifiers(struct Object *ob, const int flag); void BKE_object_free_shaderfx(struct Object *ob, const int flag); +/** + * Proxy rule: + * - `lib_object->proxy_from` == the one we borrow from, set temporally while object_update. + * - `local_object->proxy` == pointer to library object, saved in files and read. + * - `local_object->proxy_group` == pointer to collection dupli-object, saved in files and read. + */ void BKE_object_make_proxy(struct Main *bmain, struct Object *ob, struct Object *target, @@ -105,6 +158,9 @@ void BKE_object_make_proxy(struct Main *bmain, void BKE_object_copy_proxy_drivers(struct Object *ob, struct Object *target); bool BKE_object_exists_check(struct Main *bmain, const struct Object *obtest); +/** + * Actual check for internal data, not context or flags. + */ bool BKE_object_is_in_editmode(const struct Object *ob); bool BKE_object_is_in_editmode_vgroup(const struct Object *ob); bool BKE_object_is_in_wpaint_select_vert(const struct Object *ob); @@ -115,6 +171,9 @@ bool BKE_object_data_is_in_editmode(const struct ID *id); char *BKE_object_data_editmode_flush_ptr_get(struct ID *id); +/** + * Updates select_id of all objects in the given \a bmain. + */ void BKE_object_update_select_id(struct Main *bmain); typedef enum eObjectVisibilityResult { @@ -124,14 +183,33 @@ typedef enum eObjectVisibilityResult { OB_VISIBLE_ALL = (OB_VISIBLE_SELF | OB_VISIBLE_PARTICLES | OB_VISIBLE_INSTANCES), } eObjectVisibilityResult; +/** + * Return which parts of the object are visible, as evaluated by depsgraph. + */ int BKE_object_visibility(const struct Object *ob, const int dag_eval_mode); +/** + * More general add: creates minimum required data, but without vertices etc. + */ struct Object *BKE_object_add_only_object(struct Main *bmain, int type, const char *name) ATTR_NONNULL(1) ATTR_RETURNS_NONNULL; +/** + * General add: to scene, with layer from area and default name. + * + * Object is added to the active #Collection. + * If there is no linked collection to the active #ViewLayer we create a new one. + * + * \note Creates minimum required data, but without vertices etc. + */ struct Object *BKE_object_add(struct Main *bmain, struct ViewLayer *view_layer, int type, const char *name) ATTR_NONNULL(1, 2) ATTR_RETURNS_NONNULL; +/** + * Add a new object, using another one as a reference + * + * \param ob_src: object to use to determine the collections of the new object. + */ struct Object *BKE_object_add_from(struct Main *bmain, struct Scene *scene, struct ViewLayer *view_layer, @@ -139,6 +217,15 @@ struct Object *BKE_object_add_from(struct Main *bmain, const char *name, struct Object *ob_src) ATTR_NONNULL(1, 2, 3, 6) ATTR_RETURNS_NONNULL; +/** + * Add a new object, but assign the given data-block as the `ob->data` + * for the newly created object. + * + * \param data: The data-block to assign as `ob->data` for the new object. + * This is assumed to be of the correct type. + * \param do_id_user: If true, #id_us_plus() will be called on data when + * assigning it to the object. + */ struct Object *BKE_object_add_for_data(struct Main *bmain, struct ViewLayer *view_layer, int type, @@ -147,16 +234,39 @@ struct Object *BKE_object_add_for_data(struct Main *bmain, bool do_id_user) ATTR_RETURNS_NONNULL; void *BKE_object_obdata_add_from_type(struct Main *bmain, int type, const char *name) ATTR_NONNULL(1); +/** + * Return -1 on failure. + */ int BKE_object_obdata_to_type(const struct ID *id) ATTR_NONNULL(1); +/** + * Returns true if the Object is from an external blend file (libdata). + */ bool BKE_object_is_libdata(const struct Object *ob); +/** + * Returns true if the Object data is from an external blend file (libdata). + */ bool BKE_object_obdata_is_libdata(const struct Object *ob); +/** + * Perform deep-copy of object and its 'children' data-blocks (obdata, materials, actions, etc.). + * + * \param dupflag: Controls which sub-data are also duplicated + * (see #eDupli_ID_Flags in DNA_userdef_types.h). + * + * \note This function does not do any remapping to new IDs, caller must do it + * (\a #BKE_libblock_relink_to_newid()). + * \note Caller MUST free \a newid pointers itself (#BKE_main_id_newptr_and_tag_clear()) and call + * updates of DEG too (#DAG_relations_tag_update()). + */ struct Object *BKE_object_duplicate(struct Main *bmain, struct Object *ob, uint dupflag, uint duplicate_options); +/** + * Use with newly created objects to set their size (used to apply scene-scale). + */ void BKE_object_obdata_size_init(struct Object *ob, const float size); void BKE_object_scale_to_mat3(struct Object *ob, float r_mat[3][3]); @@ -168,6 +278,16 @@ void BKE_object_apply_mat4(struct Object *ob, const float mat[4][4], const bool use_compat, const bool use_parent); +/** + * Applies the global transformation \a mat to the \a ob using a relative parent space if + * supplied. + * + * \param mat: the global transformation mat that the object should be set object to. + * \param parent: the parent space in which this object will be set relative to + * (should probably always be parent_eval). + * \param use_compat: true to ensure that rotations are set using the + * min difference between the old and new orientation. + */ void BKE_object_apply_mat4_ex(struct Object *ob, const float mat[4][4], struct Object *parent, @@ -181,6 +301,9 @@ struct Object *BKE_object_pose_armature_get_visible(struct Object *ob, struct ViewLayer *view_layer, struct View3D *v3d); +/** + * Access pose array with special check to get pose object when in weight paint mode. + */ struct Object **BKE_object_pose_array_get_ex(struct ViewLayer *view_layer, struct View3D *v3d, unsigned int *r_objects_len, @@ -205,7 +328,9 @@ struct Base **BKE_object_pose_base_array_get(struct ViewLayer *view_layer, void BKE_object_get_parent_matrix(struct Object *ob, struct Object *par, float r_parentmat[4][4]); -/* Compute object world transform and store it in ob->obmat. */ +/** + * Compute object world transform and store it in `ob->obmat`. + */ void BKE_object_where_is_calc(struct Depsgraph *depsgraph, struct Scene *scene, struct Object *ob); void BKE_object_where_is_calc_ex(struct Depsgraph *depsgraph, struct Scene *scene, @@ -216,9 +341,16 @@ void BKE_object_where_is_calc_time(struct Depsgraph *depsgraph, struct Scene *scene, struct Object *ob, float ctime); +/** + * Calculate object transformation matrix without recalculating dependencies and + * constraints -- assume dependencies are already solved by depsgraph. + * No changes to object and its parent would be done. + * Used for bundles orientation in 3d space relative to parented blender camera. + */ void BKE_object_where_is_calc_mat4(struct Object *ob, float r_obmat[4][4]); /* Possibly belong in own module? */ + struct BoundBox *BKE_boundbox_alloc_unit(void); void BKE_boundbox_init_from_minmax(struct BoundBox *bb, const float min[3], const float max[3]); void BKE_boundbox_calc_center_aabb(const struct BoundBox *bb, float r_cent[3]); @@ -230,6 +362,14 @@ void BKE_boundbox_minmax(const struct BoundBox *bb, struct BoundBox *BKE_object_boundbox_get(struct Object *ob); void BKE_object_dimensions_get(struct Object *ob, float r_vec[3]); +/** + * The original scale and object matrix can be passed in so any difference + * of the objects matrix and the final matrix can be accounted for, + * typically this caused by parenting, constraints or delta-scale. + * + * Re-using these values from the object causes a feedback loop + * when multiple values are modified at once in some situations. see: T69536. + */ void BKE_object_dimensions_set_ex(struct Object *ob, const float value[3], int axis_mask, @@ -238,6 +378,9 @@ void BKE_object_dimensions_set_ex(struct Object *ob, void BKE_object_dimensions_set(struct Object *ob, const float value[3], int axis_mask); void BKE_object_empty_draw_type_set(struct Object *ob, const int value); +/** + * Use this to temporally disable/enable bound-box. + */ void BKE_object_boundbox_flag(struct Object *ob, int flag, const bool set); void BKE_object_boundbox_calc_from_mesh(struct Object *ob, const struct Mesh *me_eval); bool BKE_object_boundbox_calc_from_evaluated_geometry(struct Object *ob); @@ -249,7 +392,9 @@ bool BKE_object_minmax_dupli(struct Depsgraph *depsgraph, float r_max[3], const bool use_hidden); -/* sometimes min-max isn't enough, we need to loop over each point */ +/** + * Sometimes min-max isn't enough, we need to loop over each point. + */ void BKE_object_foreach_display_point(struct Object *ob, const float obmat[4][4], void (*func_cb)(const float[3], void *), @@ -280,9 +425,18 @@ void BKE_object_tfm_protected_restore(struct Object *ob, void BKE_object_tfm_copy(struct Object *object_dst, const struct Object *object_src); +/** + * Restore the object->data to a non-modifier evaluated state. + * + * Some changes done directly in evaluated object require them to be reset + * before being re-evaluated. + * For example, we need to call this before #BKE_mesh_new_from_object(), + * in case we removed/added modifiers in the evaluated object. + */ void BKE_object_eval_reset(struct Object *ob_eval); /* Dependency graph evaluation callbacks. */ + void BKE_object_eval_local_transform(struct Depsgraph *depsgraph, struct Object *ob); void BKE_object_eval_parent(struct Depsgraph *depsgraph, struct Object *ob); void BKE_object_eval_constraints(struct Depsgraph *depsgraph, @@ -295,6 +449,9 @@ void BKE_object_eval_uber_transform(struct Depsgraph *depsgraph, struct Object * void BKE_object_eval_uber_data(struct Depsgraph *depsgraph, struct Scene *scene, struct Object *ob); +/** + * Assign #Object.data after modifier stack evaluation. + */ void BKE_object_eval_assign_data(struct Object *object, struct ID *data, bool is_owned); void BKE_object_sync_to_original(struct Depsgraph *depsgraph, struct Object *object); @@ -320,7 +477,27 @@ void BKE_object_eval_eval_base_flags(struct Depsgraph *depsgraph, void BKE_object_handle_data_update(struct Depsgraph *depsgraph, struct Scene *scene, struct Object *ob); +/** + * \warning "scene" here may not be the scene object actually resides in. + * When dealing with background-sets, "scene" is actually the active scene. + * e.g. "scene" <-- set 1 <-- set 2 ("ob" lives here) <-- set 3 <-- ... <-- set n + * rigid bodies depend on their world so use #BKE_object_handle_update_ex() + * to also pass along the current rigid body world. + */ void BKE_object_handle_update(struct Depsgraph *depsgraph, struct Scene *scene, struct Object *ob); +/** + * Proxy rule: + * - lib_object->proxy_from == the one we borrow from, only set temporal and cleared here. + * - local_object->proxy == pointer to library object, saved in files and read. + * + * Function below is polluted with proxy exceptions, cleanup will follow! + * + * The main object update call, for object matrix, constraints, keys and displist (modifiers) + * requires flags to be set! + * + * Ideally we shouldn't have to pass the rigid body world, + * but need bigger restructuring to avoid id. + */ void BKE_object_handle_update_ex(struct Depsgraph *depsgraph, struct Scene *scene, struct Object *ob, @@ -334,13 +511,28 @@ bool BKE_object_obdata_texspace_get(struct Object *ob, float **r_loc, float **r_size); +/** Get evaluated mesh for given object. */ struct Mesh *BKE_object_get_evaluated_mesh(const struct Object *object); +/** + * Get mesh which is not affected by modifiers: + * - For original objects it will be same as `object->data`, and it is a mesh + * which is in the corresponding #Main. + * - For copied-on-write objects it will give pointer to a copied-on-write + * mesh which corresponds to original object's mesh. + */ struct Mesh *BKE_object_get_pre_modified_mesh(const struct Object *object); +/** + * Get a mesh which corresponds to the very original mesh from #Main. + * - For original objects it will be object->data. + * - For evaluated objects it will be same mesh as corresponding original + * object uses as data. + */ struct Mesh *BKE_object_get_original_mesh(const struct Object *object); /* Lattice accessors. * These functions return either the regular lattice, or the edit-mode lattice, * whichever is currently in use. */ + struct Lattice *BKE_object_get_lattice(const struct Object *object); struct Lattice *BKE_object_get_evaluated_lattice(const struct Object *object); @@ -357,12 +549,38 @@ bool BKE_object_flag_test_recursive(const struct Object *ob, short flag); bool BKE_object_is_child_recursive(const struct Object *ob_parent, const struct Object *ob_child); -/* return ModifierMode flag */ +/** + * Most important if this is modified it should _always_ return true, in certain + * cases false positives are hard to avoid (shape keys for example). + * + * \return #ModifierMode flag. + */ int BKE_object_is_modified(struct Scene *scene, struct Object *ob); +/** + * Test if object is affected by deforming modifiers (for motion blur). again + * most important is to avoid false positives, this is to skip computations + * and we can still if there was actual deformation afterwards. + */ int BKE_object_is_deform_modified(struct Scene *scene, struct Object *ob); +/** + * Check of objects moves in time. + * + * \note This function is currently optimized for usage in combination + * with modifier deformation checks (#eModifierTypeType_OnlyDeform), + * so modifiers can quickly check if their target objects moves + * (causing deformation motion blur) or not. + * + * This makes it possible to give some degree of false-positives here, + * but it's currently an acceptable tradeoff between complexity and check + * speed. In combination with checks of modifier stack and real life usage + * percentage of false-positives shouldn't be that high. + * + * \note This function does not consider physics systems. + */ bool BKE_object_moves_in_time(const struct Object *object, bool recurse_parent); +/** Return the number of scenes using (instantiating) that object in their collections. */ int BKE_object_scenes_users_get(struct Main *bmain, struct Object *ob); struct MovieClip *BKE_object_movieclip_get(struct Scene *scene, @@ -370,7 +588,16 @@ struct MovieClip *BKE_object_movieclip_get(struct Scene *scene, bool use_default); void BKE_object_runtime_reset(struct Object *object); +/** + * Reset all pointers which we don't want to be shared when copying the object. + */ void BKE_object_runtime_reset_on_copy(struct Object *object, const int flag); +/** + * The function frees memory used by the runtime data, but not the runtime field itself. + * + * All runtime data is cleared to ensure it's not used again, + * in keeping with other `_free_data(..)` functions. + */ void BKE_object_runtime_free_data(struct Object *object); void BKE_object_batch_cache_dirty_tag(struct Object *ob); @@ -394,12 +621,31 @@ typedef enum eObjectSet { OB_SET_ALL, /* All Objects. */ } eObjectSet; +/** + * Iterates over all objects of the given scene layer. + * Depending on the #eObjectSet flag: + * collect either #OB_SET_ALL, #OB_SET_VISIBLE or #OB_SET_SELECTED objects. + * If #OB_SET_VISIBLE or#OB_SET_SELECTED are collected, + * then also add related objects according to the given \a includeFilter. + */ struct LinkNode *BKE_object_relational_superset(struct ViewLayer *view_layer, eObjectSet objectSet, eObRelationTypes includeFilter); +/** + * \return All groups this object is a part of, caller must free. + */ struct LinkNode *BKE_object_groups(struct Main *bmain, struct Scene *scene, struct Object *ob); void BKE_object_groups_clear(struct Main *bmain, struct Scene *scene, struct Object *object); +/** + * Return a KDTree_3d from the deformed object (in world-space). + * + * \note Only mesh objects currently support deforming, others are TODO. + * + * \param ob: + * \param r_tot: + * \return The KD-tree or nullptr if it can't be created. + */ struct KDTree_3d *BKE_object_as_kdtree(struct Object *ob, int *r_tot); bool BKE_object_modifier_use_time(struct Scene *scene, @@ -407,6 +653,10 @@ bool BKE_object_modifier_use_time(struct Scene *scene, struct ModifierData *md, int dag_eval_mode); +/** + * \note this function should eventually be replaced by depsgraph functionality. + * Avoid calling this in new code unless there is a very good reason for it! + */ bool BKE_object_modifier_update_subframe(struct Depsgraph *depsgraph, struct Scene *scene, struct Object *ob, @@ -420,7 +670,8 @@ bool BKE_object_empty_image_frame_is_visible_in_view3d(const struct Object *ob, bool BKE_object_empty_image_data_is_visible_in_view3d(const struct Object *ob, const struct RegionView3D *rv3d); -/* This is an utility function for Python's object.to_mesh() (the naming is not very clear though). +/** + * This is an utility function for Python's object.to_mesh() (the naming is not very clear though). * The result is owned by the object. * * The mesh will be freed when object is re-evaluated or is destroyed. It is possible to force to @@ -437,11 +688,12 @@ struct Mesh *BKE_object_to_mesh(struct Depsgraph *depsgraph, void BKE_object_to_mesh_clear(struct Object *object); -/* This is an utility function for Python's object.to_curve(). +/** + * This is an utility function for Python's `object.to_curve()`. * The result is owned by the object. * * The curve will be freed when object is re-evaluated or is destroyed. It is possible to force - * clear memory used by this curve by calling BKE_object_to_curve_clear(). + * clear memory used by this curve by calling #BKE_object_to_curve_clear(). * * If apply_modifiers is true and the object is a curve one, then spline deform modifiers are * applied on the curve control points. diff --git a/source/blender/blenkernel/BKE_object_deform.h b/source/blender/blenkernel/BKE_object_deform.h index a10158254c2..ddbf5178ab0 100644 --- a/source/blender/blenkernel/BKE_object_deform.h +++ b/source/blender/blenkernel/BKE_object_deform.h @@ -31,24 +31,73 @@ struct MDeformVert; struct Object; struct bDeformGroup; -/* General vgroup operations */ +/* General vgroup operations. */ + +/** + * Update users of vgroups from this object, according to given map. + * + * Use it when you remove or reorder vgroups in the object. + * + * \param map: an array mapping old indices to new indices. + */ void BKE_object_defgroup_remap_update_users(struct Object *ob, const int *map); +/** + * Get #MDeformVert vgroup data from given object. Should only be used in Object mode. + * + * \return True if the id type supports weights. + */ bool BKE_object_defgroup_array_get(struct ID *id, struct MDeformVert **dvert_arr, int *dvert_tot); +/** + * Add a vgroup of default name to object. *Does not* handle #MDeformVert data at all! + */ struct bDeformGroup *BKE_object_defgroup_add(struct Object *ob); +/** + * Add a vgroup of given name to object. *Does not* handle #MDeformVert data at all! + */ struct bDeformGroup *BKE_object_defgroup_add_name(struct Object *ob, const char *name); +/** + * Create #MDeformVert data for given ID. Work in Object mode only. + */ struct MDeformVert *BKE_object_defgroup_data_create(struct ID *id); +/** + * Remove all verts (or only selected ones) from given vgroup. Work in Object and Edit modes. + * + * \param use_selection: Only operate on selection. + * \return True if any vertex was removed, false otherwise. + */ bool BKE_object_defgroup_clear(struct Object *ob, struct bDeformGroup *dg, const bool use_selection); +/** + * Remove all verts (or only selected ones) from all vgroups. Work in Object and Edit modes. + * + * \param use_selection: Only operate on selection. + * \return True if any vertex was removed, false otherwise. + */ bool BKE_object_defgroup_clear_all(struct Object *ob, const bool use_selection); +/** + * Remove given vgroup from object. Work in Object and Edit modes. + */ void BKE_object_defgroup_remove(struct Object *ob, struct bDeformGroup *defgroup); +/** + * Remove all vgroups from object. Work in Object and Edit modes. + * When only_unlocked=true, locked vertex groups are not removed. + */ void BKE_object_defgroup_remove_all_ex(struct Object *ob, bool only_unlocked); +/** + * Remove all vgroups from object. Work in Object and Edit modes. + */ void BKE_object_defgroup_remove_all(struct Object *ob); +/** + * Compute mapping for vertex groups with matching name, -1 is used for no remapping. + * Returns null if no remapping is required. + * The returned array has to be freed. + */ int *BKE_object_defgroup_index_map_create(struct Object *ob_src, struct Object *ob_dst, int *r_map_len); @@ -57,34 +106,69 @@ void BKE_object_defgroup_index_map_apply(struct MDeformVert *dvert, const int *map, int map_len); -/* Select helpers */ +/* Select helpers. */ + enum eVGroupSelect; +/** + * Return the subset type of the Vertex Group Selection. + */ bool *BKE_object_defgroup_subset_from_select_type(struct Object *ob, enum eVGroupSelect subset_type, int *r_defgroup_tot, int *r_subset_count); +/** + * Store indices from the defgroup_validmap (faster lookups in some cases). + */ void BKE_object_defgroup_subset_to_index_array(const bool *defgroup_validmap, const int defgroup_tot, int *r_defgroup_subset_map); /* ********** */ +/** + * Gets the status of "flag" for each #bDeformGroup + * in the object data's vertex group list and returns an array containing them + */ bool *BKE_object_defgroup_lock_flags_get(struct Object *ob, const int defbase_tot); bool *BKE_object_defgroup_validmap_get(struct Object *ob, const int defbase_tot); +/** + * Returns total selected vgroups, + * `wpi.defbase_sel` is assumed malloc'd, all values are set. + */ bool *BKE_object_defgroup_selected_get(struct Object *ob, int defbase_tot, int *r_dg_flags_sel_tot); +/** + * Checks if the lock relative mode is applicable. + * + * \return true if an unlocked deform group is active. + */ bool BKE_object_defgroup_check_lock_relative(const bool *lock_flags, const bool *validmap, int index); +/** + * Additional check for whether the lock relative mode is applicable in multi-paint mode. + * + * \return true if none of the selected groups are locked. + */ bool BKE_object_defgroup_check_lock_relative_multi(int defbase_tot, const bool *lock_flags, const bool *selected, int sel_tot); +/** + * Takes a pair of boolean masks of all locked and all deform groups, and computes + * a pair of masks for locked deform and unlocked deform groups. Output buffers may + * reuse the input ones. + */ void BKE_object_defgroup_split_locked_validmap( int defbase_tot, const bool *locked, const bool *deform, bool *r_locked, bool *r_unlocked); +/** + * Marks mirror vgroups in output and counts them. + * Output and counter assumed to be already initialized. + * Designed to be usable after BKE_object_defgroup_selected_get to extend selection to mirror. + */ void BKE_object_defgroup_mirror_selection(struct Object *ob, int defbase_tot, const bool *selection, diff --git a/source/blender/blenkernel/BKE_ocean.h b/source/blender/blenkernel/BKE_ocean.h index 186e0ec174b..4388190221d 100644 --- a/source/blender/blenkernel/BKE_ocean.h +++ b/source/blender/blenkernel/BKE_ocean.h @@ -74,12 +74,21 @@ struct Ocean *BKE_ocean_add(void); void BKE_ocean_free_data(struct Ocean *oc); void BKE_ocean_free(struct Ocean *oc); bool BKE_ocean_ensure(struct OceanModifierData *omd, const int resolution); +/** + * Return true if the ocean data is valid and can be used. + */ bool BKE_ocean_init_from_modifier(struct Ocean *ocean, struct OceanModifierData const *omd, const int resolution); +/** + * Return true if the ocean is valid and can be used. + */ bool BKE_ocean_is_valid(const struct Ocean *o); +/** + * Return true if the ocean data is valid and can be used. + */ bool BKE_ocean_init(struct Ocean *o, int M, int N, @@ -104,15 +113,26 @@ bool BKE_ocean_init(struct Ocean *o, int seed); void BKE_ocean_simulate(struct Ocean *o, float t, float scale, float chop_amount); -/* sampling the ocean surface */ float BKE_ocean_jminus_to_foam(float jminus, float coverage); +/** + * Sampling the ocean surface. + */ void BKE_ocean_eval_uv(struct Ocean *oc, struct OceanResult *ocr, float u, float v); +/** + * Use catmullrom interpolation rather than linear. + */ void BKE_ocean_eval_uv_catrom(struct Ocean *oc, struct OceanResult *ocr, float u, float v); void BKE_ocean_eval_xz(struct Ocean *oc, struct OceanResult *ocr, float x, float z); void BKE_ocean_eval_xz_catrom(struct Ocean *oc, struct OceanResult *ocr, float x, float z); +/** + * Note that this doesn't wrap properly for i, j < 0, but its not really meant for that being + * just a way to get the raw data out to save in some image format. + */ void BKE_ocean_eval_ij(struct Ocean *oc, struct OceanResult *ocr, int i, int j); -/* ocean cache handling */ +/** + * Ocean cache handling. + */ struct OceanCache *BKE_ocean_init_cache(const char *bakepath, const char *relbase, int start, @@ -136,8 +156,26 @@ void BKE_ocean_free_cache(struct OceanCache *och); void BKE_ocean_free_modifier_cache(struct OceanModifierData *omd); /* ocean_spectrum.c */ + +/** + * Pierson-Moskowitz model, 1964, assumes waves reach equilibrium with wind. + * Model is intended for large area 'fully developed' sea, where winds have been steadily blowing + * for days over an area that includes hundreds of wavelengths on a side. + */ float BLI_ocean_spectrum_piersonmoskowitz(const struct Ocean *oc, const float kx, const float kz); +/** + * TMA extends the JONSWAP spectrum. + * This spectral model is best suited to shallow water. + */ float BLI_ocean_spectrum_texelmarsenarsloe(const struct Ocean *oc, const float kx, const float kz); +/** + * Hasselmann et al, 1973. This model extends the Pierson-Moskowitz model with a peak sharpening + * function This enhancement is an artificial construct to address the problem that the wave + * spectrum is never fully developed. + * + * The fetch parameter represents the distance from a lee shore, + * called the fetch, or the distance over which the wind blows with constant velocity. + */ float BLI_ocean_spectrum_jonswap(const struct Ocean *oc, const float kx, const float kz); #ifdef __cplusplus diff --git a/source/blender/blenkernel/BKE_packedFile.h b/source/blender/blenkernel/BKE_packedFile.h index 8ddf77e3d49..e3deff9d8fa 100644 --- a/source/blender/blenkernel/BKE_packedFile.h +++ b/source/blender/blenkernel/BKE_packedFile.h @@ -57,17 +57,32 @@ enum ePF_FileStatus { PF_ASK = 10, }; -/* pack */ +/* Pack. */ + struct PackedFile *BKE_packedfile_duplicate(const struct PackedFile *pf_src); struct PackedFile *BKE_packedfile_new(struct ReportList *reports, const char *filename, const char *basepath); struct PackedFile *BKE_packedfile_new_from_memory(void *mem, int memlen); +/** + * No libraries for now. + */ void BKE_packedfile_pack_all(struct Main *bmain, struct ReportList *reports, bool verbose); void BKE_packedfile_pack_all_libraries(struct Main *bmain, struct ReportList *reports); -/* unpack */ +/* Unpack. */ + +/** + * #BKE_packedfile_unpack_to_file() looks at the existing files (abs_name, local_name) + * and a packed file. + * + * It returns a char *to the existing file name / new file name or NULL when + * there was an error or when the user decides to cancel the operation. + * + * \warning 'abs_name' may be relative still! (use a "//" prefix) + * be sure to run #BLI_path_abs on it first. + */ char *BKE_packedfile_unpack_to_file(struct ReportList *reports, const char *ref_file_name, const char *abs_name, @@ -107,23 +122,38 @@ int BKE_packedfile_write_to_file(struct ReportList *reports, struct PackedFile *pf, const bool guimode); -/* free */ +/* Free. */ + void BKE_packedfile_free(struct PackedFile *pf); -/* info */ +/* Info. */ + int BKE_packedfile_count_all(struct Main *bmain); +/** + * This function compares a packed file to a 'real' file. + * It returns an integer indicating if: + * + * - #PF_EQUAL: the packed file and original file are identical. + * - #PF_DIFFERENT: the packed file and original file differ. + * - #PF_NOFILE: the original file doesn't exist. + */ enum ePF_FileCompare BKE_packedfile_compare_to_file(const char *ref_file_name, const char *filename, struct PackedFile *pf); -/* read */ +/* Read. */ + int BKE_packedfile_seek(struct PackedFile *pf, int offset, int whence); void BKE_packedfile_rewind(struct PackedFile *pf); int BKE_packedfile_read(struct PackedFile *pf, void *data, int size); -/* ID should be not NULL, return true if there's a packed file */ +/** + * ID should be not NULL, return true if there's a packed file. + */ bool BKE_packedfile_id_check(const struct ID *id); -/* ID should be not NULL, throws error when ID is Library */ +/** + * ID should be not NULL, throws error when ID is Library. + */ void BKE_packedfile_id_unpack(struct Main *bmain, struct ID *id, struct ReportList *reports, diff --git a/source/blender/blenkernel/BKE_paint.h b/source/blender/blenkernel/BKE_paint.h index 6fc5ef4d870..40e3ab74fac 100644 --- a/source/blender/blenkernel/BKE_paint.h +++ b/source/blender/blenkernel/BKE_paint.h @@ -111,10 +111,11 @@ typedef enum ePaintOverlayControlFlags { (PAINT_OVERLAY_OVERRIDE_SECONDARY | PAINT_OVERLAY_OVERRIDE_PRIMARY | \ PAINT_OVERLAY_OVERRIDE_CURSOR) -/* Defines 8 areas resulting of splitting the object space by the XYZ axis planes. This is used to +/** + * Defines 8 areas resulting of splitting the object space by the XYZ axis planes. This is used to * flip or mirror transform values depending on where the vertex is and where the transform - * operation started to support XYZ symmetry on those operations in a predictable way. */ - + * operation started to support XYZ symmetry on those operations in a predictable way. + */ #define PAINT_SYMM_AREA_DEFAULT 0 typedef enum ePaintSymmetryAreas { @@ -136,10 +137,14 @@ ePaintOverlayControlFlags BKE_paint_get_overlay_flags(void); void BKE_paint_reset_overlay_invalid(ePaintOverlayControlFlags flag); void BKE_paint_set_overlay_override(enum eOverlayFlags flag); -/* palettes */ +/* Palettes. */ + struct Palette *BKE_palette_add(struct Main *bmain, const char *name); struct PaletteColor *BKE_palette_color_add(struct Palette *palette); bool BKE_palette_is_empty(const struct Palette *palette); +/** + * Remove color from palette. Must be certain color is inside the palette! + */ void BKE_palette_color_remove(struct Palette *palette, struct PaletteColor *color); void BKE_palette_clear(struct Palette *palette); @@ -152,12 +157,21 @@ bool BKE_palette_from_hash(struct Main *bmain, const char *name, const bool linear); -/* paint curves */ +/* Paint curves. */ + struct PaintCurve *BKE_paint_curve_add(struct Main *bmain, const char *name); +/** + * Call when entering each respective paint mode. + */ bool BKE_paint_ensure(struct ToolSettings *ts, struct Paint **r_paint); void BKE_paint_init(struct Main *bmain, struct Scene *sce, ePaintMode mode, const char col[3]); void BKE_paint_free(struct Paint *p); +/** + * Called when copying scene settings, so even if 'src' and 'tar' are the same still do a + * #id_us_plus(), rather than if we were copying between 2 existing scenes where a matching + * value should decrease the existing user count as with #paint_brush_set() + */ void BKE_paint_copy(struct Paint *src, struct Paint *tar, const int flag); void BKE_paint_runtime_init(const struct ToolSettings *ts, struct Paint *paint); @@ -181,26 +195,46 @@ void BKE_paint_palette_set(struct Paint *p, struct Palette *palette); void BKE_paint_curve_set(struct Brush *br, struct PaintCurve *pc); void BKE_paint_curve_clamp_endpoint_add_index(struct PaintCurve *pc, const int add_index); -/* testing face select mode - * Texture paint could be removed since selected faces are not used - * however hiding faces is useful */ +/** + * Return true when in vertex/weight/texture paint + face-select mode? + */ bool BKE_paint_select_face_test(struct Object *ob); +/** + * Return true when in vertex/weight paint + vertex-select mode? + */ bool BKE_paint_select_vert_test(struct Object *ob); +/** + * used to check if selection is possible + * (when we don't care if its face or vert) + */ bool BKE_paint_select_elem_test(struct Object *ob); -/* partial visibility */ +/* Partial visibility. */ + +/** + * Returns non-zero if any of the face's vertices are hidden, zero otherwise. + */ bool paint_is_face_hidden(const struct MLoopTri *lt, const struct MVert *mvert, const struct MLoop *mloop); +/** + * Returns non-zero if any of the corners of the grid + * face whose inner corner is at (x, y) are hidden, zero otherwise. + */ bool paint_is_grid_face_hidden(const unsigned int *grid_hidden, int gridsize, int x, int y); +/** + * Return true if all vertices in the face are visible, false otherwise. + */ bool paint_is_bmesh_face_hidden(struct BMFace *f); -/* paint masks */ +/* Paint masks. */ + float paint_grid_paint_mask(const struct GridPaintMask *gpm, uint level, uint x, uint y); void BKE_paint_face_set_overlay_color_get(const int face_set, const int seed, uchar r_color[4]); -/* stroke related */ +/* Stroke related. */ + bool paint_calculate_rake_rotation(struct UnifiedPaintSettings *ups, struct Brush *brush, const float mouse_pos[2]); @@ -211,14 +245,20 @@ void paint_update_brush_rake_rotation(struct UnifiedPaintSettings *ups, void BKE_paint_stroke_get_average(struct Scene *scene, struct Object *ob, float stroke[3]); /* Tool slot API. */ + void BKE_paint_toolslots_init_from_main(struct Main *bmain); void BKE_paint_toolslots_len_ensure(struct Paint *paint, int len); void BKE_paint_toolslots_brush_update_ex(struct Paint *paint, struct Brush *brush); void BKE_paint_toolslots_brush_update(struct Paint *paint); +/** + * Run this to ensure brush types are set for each slot on entering modes + * (for new scenes for example). + */ void BKE_paint_toolslots_brush_validate(struct Main *bmain, struct Paint *paint); struct Brush *BKE_paint_toolslots_brush_get(struct Paint *paint, int slot_index); /* .blend I/O */ + void BKE_paint_blend_write(struct BlendWriter *writer, struct Paint *paint); void BKE_paint_blend_read_data(struct BlendDataReader *reader, const struct Scene *scene, @@ -229,7 +269,7 @@ void BKE_paint_blend_read_lib(struct BlendLibReader *reader, #define SCULPT_FACE_SET_NONE 0 -/* Used for both vertex color and weight paint */ +/** Used for both vertex color and weight paint. */ struct SculptVertexPaintGeomMap { int *vert_map_mem; struct MeshElemMap *vert_to_loop; @@ -237,7 +277,7 @@ struct SculptVertexPaintGeomMap { struct MeshElemMap *vert_to_poly; }; -/* Pose Brush IK Chain */ +/** Pose Brush IK Chain. */ typedef struct SculptPoseIKChainSegment { float orig[3]; float head[3]; @@ -620,10 +660,15 @@ void BKE_sculptsession_free_vwpaint_data(struct SculptSession *ss); void BKE_sculptsession_bm_to_me(struct Object *ob, bool reorder); void BKE_sculptsession_bm_to_me_for_render(struct Object *object); -/* Create new color layer on object if it doesn't have one and if experimental feature set has - * sculpt vertex color enabled. Returns truth if new layer has been added, false otherwise. */ +/** + * Create new color layer on object if it doesn't have one and if experimental feature set has + * sculpt vertex color enabled. Returns truth if new layer has been added, false otherwise. + */ void BKE_sculpt_color_layer_create_if_needed(struct Object *object); +/** + * \warning Expects a fully evaluated depsgraph. + */ void BKE_sculpt_update_object_for_edit(struct Depsgraph *depsgraph, struct Object *ob_orig, bool need_pmap, @@ -632,6 +677,10 @@ void BKE_sculpt_update_object_for_edit(struct Depsgraph *depsgraph, void BKE_sculpt_update_object_before_eval(struct Object *ob_eval); void BKE_sculpt_update_object_after_eval(struct Depsgraph *depsgraph, struct Object *ob_eval); +/** + * Sculpt mode handles multi-res differently from regular meshes, but only if + * it's the last modifier on the stack and it is not on the first level. + */ struct MultiresModifierData *BKE_sculpt_multires_active(struct Scene *scene, struct Object *ob); int BKE_sculpt_mask_layers_ensure(struct Object *ob, struct MultiresModifierData *mmd); void BKE_sculpt_toolsettings_data_ensure(struct Scene *scene); @@ -640,19 +689,37 @@ struct PBVH *BKE_sculpt_object_pbvh_ensure(struct Depsgraph *depsgraph, struct O void BKE_sculpt_bvh_update_from_ccg(struct PBVH *pbvh, struct SubdivCCG *subdiv_ccg); -/* This ensure that all elements in the mesh (both vertices and grids) have their visibility - * updated according to the face sets. */ +/** + * This ensure that all elements in the mesh (both vertices and grids) have their visibility + * updated according to the face sets. + */ void BKE_sculpt_sync_face_set_visibility(struct Mesh *mesh, struct SubdivCCG *subdiv_ccg); -/* Individual function to sync the Face Set visibility to mesh and grids. */ +/** + * Individual function to sync the Face Set visibility to mesh and grids. + */ void BKE_sculpt_sync_face_sets_visibility_to_base_mesh(struct Mesh *mesh); void BKE_sculpt_sync_face_sets_visibility_to_grids(struct Mesh *mesh, struct SubdivCCG *subdiv_ccg); +/** + * Ensures that a Face Set data-layers exists. If it does not, it creates one respecting the + * visibility stored in the vertices of the mesh. If it does, it copies the visibility from the + * mesh to the Face Sets. */ void BKE_sculpt_face_sets_ensure_from_base_mesh_visibility(struct Mesh *mesh); +/** + * Ensures we do have expected mesh data in original mesh for the sculpt mode. + * + * \note IDs are expected to be original ones here, and calling code should ensure it updates its + * depsgraph properly after calling this function if it needs up-to-date evaluated data. + */ void BKE_sculpt_ensure_orig_mesh_data(struct Scene *scene, struct Object *object); +/** + * Test if PBVH can be used directly for drawing, which is faster than + * drawing the mesh and all updates that come with it. + */ bool BKE_sculptsession_use_pbvh_draw(const struct Object *ob, const struct View3D *v3d); enum { diff --git a/source/blender/blenkernel/BKE_particle.h b/source/blender/blenkernel/BKE_particle.h index 78a6e47ec48..9b262fa6131 100644 --- a/source/blender/blenkernel/BKE_particle.h +++ b/source/blender/blenkernel/BKE_particle.h @@ -286,6 +286,9 @@ BLI_INLINE void psys_frand_vec(ParticleSystem *psys, unsigned int seed, float ve /* ----------- functions needed outside particlesystem ---------------- */ /* particle.c */ + +/* Few helpers for count-all etc. */ + int count_particles(struct ParticleSystem *psys); int count_particles_mod(struct ParticleSystem *psys, int totgr, int cur); @@ -296,8 +299,13 @@ int psys_get_tot_child(struct Scene *scene, struct ParticleSystem *psys, const bool use_render_params); +/** + * Get object's active particle system safely. + */ struct ParticleSystem *psys_get_current(struct Object *ob); -/* for rna */ + +/* For RNA API. */ + short psys_get_current_num(struct Object *ob); void psys_set_current_num(struct Object *ob, int index); /* UNUSED */ @@ -305,14 +313,17 @@ void psys_set_current_num(struct Object *ob, int index); struct LatticeDeformData *psys_create_lattice_deform_data(struct ParticleSimulationData *sim); -/* For a given evaluated particle system get its original. +/** + * For a given evaluated particle system get its original. * - * If this input is an original particle system already, the return value is the - * same as the input. */ + * If this input is an original particle system already, the return value is the same as the input. + */ struct ParticleSystem *psys_orig_get(struct ParticleSystem *psys); -/* For a given original object and its particle system, get evaluated particle - * system within a given dependency graph. */ +/** + * For a given original object and its particle system, + * get evaluated particle system within a given dependency graph. + */ struct ParticleSystem *psys_eval_get(struct Depsgraph *depsgraph, struct Object *object, struct ParticleSystem *psys); @@ -328,11 +339,17 @@ void psys_check_group_weights(struct ParticleSettings *part); int psys_uses_gravity(struct ParticleSimulationData *sim); void BKE_particlesettings_fluid_default_settings(struct ParticleSettings *part); -/* free */ +/** + * Free cache path. + */ void psys_free_path_cache(struct ParticleSystem *psys, struct PTCacheEdit *edit); +/** + * Free everything. + */ void psys_free(struct Object *ob, struct ParticleSystem *psys); - -/* Copy. */ +/** + * Copy. + */ void psys_copy_particles(struct ParticleSystem *psys_dst, struct ParticleSystem *psys_src); bool psys_render_simplify_params(struct ParticleSystem *psys, @@ -379,6 +396,12 @@ void psys_find_parents(struct ParticleSimulationData *sim, const bool use_render void psys_unique_name(struct Object *object, struct ParticleSystem *psys, const char *defname); +/** + * Calculates paths ready for drawing/rendering + * - Useful for making use of opengl vertex arrays for super fast strand drawing. + * - Makes child strands possible and creates them too into the cache. + * - Cached path data is also used to determine cut position for the edit-mode tool. + */ void psys_cache_paths(struct ParticleSimulationData *sim, float cfra, const bool use_render_params); @@ -409,16 +432,24 @@ float psys_get_child_size(struct ParticleSystem *psys, struct ChildParticle *cpa, float cfra, float *pa_time); +/** + * Gets hair (or keyed) particles state at the "path time" specified in `state->time`. + */ void psys_get_particle_on_path(struct ParticleSimulationData *sim, int pa_num, struct ParticleKey *state, const bool vel); +/** + * Gets particle's state at a time. + * \return 1 if particle exists and can be seen and 0 if not. + */ int psys_get_particle_state(struct ParticleSimulationData *sim, int p, struct ParticleKey *state, int always); -/* child paths */ +/* Child paths. */ + void BKE_particlesettings_clump_curve_init(struct ParticleSettings *part); void BKE_particlesettings_rough_curve_init(struct ParticleSettings *part); void BKE_particlesettings_twist_curve_init(struct ParticleSettings *part); @@ -434,9 +465,13 @@ void psys_apply_child_modifiers(struct ParticleThreadContext *ctx, void psys_sph_init(struct ParticleSimulationData *sim, struct SPHData *sphdata); void psys_sph_finalize(struct SPHData *sphdata); +/** + * Sample the density field at a point in space. + */ void psys_sph_density(struct BVHTree *tree, struct SPHData *data, float co[3], float vars[2]); -/* for anim.c */ +/* For anim.c */ + void psys_get_dupli_texture(struct ParticleSystem *psys, struct ParticleSettings *part, struct ParticleSystemModifierData *psmd, @@ -451,6 +486,9 @@ void psys_get_dupli_path_transform(struct ParticleSimulationData *sim, float mat[4][4], float *scale); +/** + * Threaded child particle distribution and path caching. + */ void psys_thread_context_init(struct ParticleThreadContext *ctx, struct ParticleSimulationData *sim); void psys_thread_context_free(struct ParticleThreadContext *ctx); @@ -467,9 +505,16 @@ void psys_apply_hair_lattice(struct Depsgraph *depsgraph, struct ParticleSystem *psys); /* particle_system.c */ + struct ParticleSystem *psys_get_target_system(struct Object *ob, struct ParticleTarget *pt); +/** + * Counts valid keyed targets. + */ void psys_count_keyed_targets(struct ParticleSimulationData *sim); void psys_update_particle_tree(struct ParticleSystem *psys, float cfra); +/** + * System type has changed so set sensible defaults and clear non applicable flags. + */ void psys_changed_type(struct Object *ob, struct ParticleSystem *psys); void psys_make_temp_pointcache(struct Object *ob, struct ParticleSystem *psys); @@ -486,13 +531,19 @@ void psys_get_birth_coords(struct ParticleSimulationData *sim, float dtime, float cfra); +/** + * Main particle update call, checks that things are ok on the large scale and + * then advances in to actual particle calculations depending on particle type. + */ void particle_system_update(struct Depsgraph *depsgraph, struct Scene *scene, struct Object *ob, struct ParticleSystem *psys, const bool use_render_params); -/* Callback format for performing operations on ID-pointers for particle systems */ +/** + * Callback format for performing operations on ID-pointers for particle systems. + */ typedef void (*ParticleSystemIDFunc)(struct ParticleSystem *psys, struct ID **idpoin, void *userdata, @@ -502,11 +553,15 @@ void BKE_particlesystem_id_loop(struct ParticleSystem *psys, ParticleSystemIDFunc func, void *userdata); -/* Reset all particle systems in the given object. */ +/** + * Reset all particle systems in the given object. + */ void BKE_particlesystem_reset_all(struct Object *object); /* ----------- functions needed only inside particlesystem ------------ */ + /* particle.c */ + void psys_disable_all(struct Object *ob); void psys_enable_all(struct Object *ob); @@ -544,6 +599,9 @@ void psys_get_texture(struct ParticleSimulationData *sim, struct ParticleTexture *ptex, int event, float cfra); +/** + * Interpolate a location on a face based on face coordinates. + */ void psys_interpolate_face(struct MVert *mvert, struct MFace *mface, struct MTFace *tface, @@ -561,11 +619,16 @@ float psys_particle_value_from_verts(struct Mesh *mesh, void psys_get_from_key( struct ParticleKey *key, float loc[3], float vel[3], float rot[4], float *time); -/* BLI_bvhtree_ray_cast callback */ +/** + * Callback for #BVHTree near test. + */ void BKE_psys_collision_neartest_cb(void *userdata, int index, const struct BVHTreeRay *ray, struct BVHTreeRayHit *hit); +/** + * Interprets particle data to get a point on a mesh in object space. + */ void psys_particle_on_dm(struct Mesh *mesh_final, int from, int index, @@ -579,18 +642,37 @@ void psys_particle_on_dm(struct Mesh *mesh_final, float orco[3]); /* particle_system.c */ + void distribute_particles(struct ParticleSimulationData *sim, int from); +/** + * Set particle parameters that don't change during particle's life. + */ void init_particle(struct ParticleSimulationData *sim, struct ParticleData *pa); void psys_calc_dmcache(struct Object *ob, struct Mesh *mesh_final, struct Mesh *mesh_original, struct ParticleSystem *psys); +/** + * Find the final derived mesh tessface for a particle, from its original tessface index. + * This is slow and can be optimized but only for many lookups. + * + * \param mesh_final: Final mesh, it may not have the same topology as original mesh. + * \param mesh_original: Original mesh, use for accessing #MPoly to #MFace mapping. + * \param findex_orig: The input tessface index. + * \param fw: Face weights (position of the particle inside the \a findex_orig tessface). + * \param poly_nodes: May be NULL, otherwise an array of linked list, + * one for each final \a mesh_final polygon, containing all its tessfaces indices. + * \return The \a mesh_final tessface index. + */ int psys_particle_dm_face_lookup(struct Mesh *mesh_final, struct Mesh *mesh_original, int findex, const float fw[4], struct LinkNode **poly_nodes); +/** + * Sets particle to the emitter surface with initial velocity & rotation. + */ void reset_particle(struct ParticleSimulationData *sim, struct ParticleData *pa, float dtime, @@ -629,6 +711,7 @@ extern void (*BKE_particle_batch_cache_dirty_tag_cb)(struct ParticleSystem *psys extern void (*BKE_particle_batch_cache_free_cb)(struct ParticleSystem *psys); /* .blend file I/O */ + void BKE_particle_partdeflect_blend_read_data(struct BlendDataReader *reader, struct PartDeflect *pd); void BKE_particle_partdeflect_blend_read_lib(struct BlendLibReader *reader, diff --git a/source/blender/blenkernel/BKE_pbvh.h b/source/blender/blenkernel/BKE_pbvh.h index 3a0e9d48af7..5e7a9883de6 100644 --- a/source/blender/blenkernel/BKE_pbvh.h +++ b/source/blender/blenkernel/BKE_pbvh.h @@ -90,7 +90,9 @@ void BKE_pbvh_get_frustum_planes(PBVH *pbvh, PBVHFrustumPlanes *planes); /* Callbacks */ -/* returns 1 if the search should continue from this node, 0 otherwise */ +/** + * Returns true if the search should continue from this node, false otherwise. + */ typedef bool (*BKE_pbvh_SearchCallback)(PBVHNode *node, void *data); typedef void (*BKE_pbvh_HitCallback)(PBVHNode *node, void *data); @@ -101,6 +103,12 @@ typedef void (*BKE_pbvh_SearchNearestCallback)(PBVHNode *node, void *data, float /* Building */ PBVH *BKE_pbvh_new(void); +/** + * Do a full rebuild with on Mesh data structure. + * + * \note Unlike mpoly/mloop/verts, looptri is *totally owned* by PBVH + * (which means it may rewrite it if needed, see #BKE_pbvh_vert_coords_apply(). + */ void BKE_pbvh_build_mesh(PBVH *pbvh, const struct Mesh *mesh, const struct MPoly *mpoly, @@ -112,6 +120,9 @@ void BKE_pbvh_build_mesh(PBVH *pbvh, struct CustomData *pdata, const struct MLoopTri *looptri, int looptri_num); +/** + * Do a full rebuild with on Grids data structure. + */ void BKE_pbvh_build_grids(PBVH *pbvh, struct CCGElem **grids, int totgrid, @@ -119,6 +130,9 @@ void BKE_pbvh_build_grids(PBVH *pbvh, void **gridfaces, struct DMFlagMat *flagmats, unsigned int **grid_hidden); +/** + * Build a PBVH from a BMesh. + */ void BKE_pbvh_build_bmesh(PBVH *pbvh, struct BMesh *bm, bool smooth_shading, @@ -170,8 +184,10 @@ bool BKE_pbvh_bmesh_node_raycast_detail(PBVHNode *node, float *depth, float *r_edge_length); -/* for orthographic cameras, project the far away ray segment points to the root node so - * we can have better precision. */ +/** + * For orthographic cameras, project the far away ray segment points to the root node so + * we can have better precision. + */ void BKE_pbvh_raycast_project_ray_root( PBVH *pbvh, bool original, float ray_start[3], float ray_end[3], float ray_normal[3]); @@ -215,12 +231,19 @@ typedef enum { PBVHType BKE_pbvh_type(const PBVH *pbvh); bool BKE_pbvh_has_faces(const PBVH *pbvh); -/* Get the PBVH root's bounding box */ +/** + * Get the PBVH root's bounding box. + */ void BKE_pbvh_bounding_box(const PBVH *pbvh, float min[3], float max[3]); -/* multires hidden data, only valid for type == PBVH_GRIDS */ +/** + * Multi-res hidden data, only valid for type == PBVH_GRIDS. + */ unsigned int **BKE_pbvh_grid_hidden(const PBVH *pbvh); +/** + * Returns the number of visible quads in the nodes' grids. + */ int BKE_pbvh_count_grid_quads(BLI_bitmap **grid_hidden, const int *grid_indices, int totgrid, @@ -228,7 +251,9 @@ int BKE_pbvh_count_grid_quads(BLI_bitmap **grid_hidden, void BKE_pbvh_sync_face_sets_to_grids(PBVH *pbvh); -/* multires level, only valid for type == PBVH_GRIDS */ +/** + * Multi-res level, only valid for type == #PBVH_GRIDS. + */ const struct CCGKey *BKE_pbvh_get_grid_key(const PBVH *pbvh); struct CCGElem **BKE_pbvh_get_grids(const PBVH *pbvh); @@ -236,7 +261,9 @@ BLI_bitmap **BKE_pbvh_get_grid_visibility(const PBVH *pbvh); int BKE_pbvh_get_grid_num_vertices(const PBVH *pbvh); int BKE_pbvh_get_grid_num_faces(const PBVH *pbvh); -/* Only valid for type == PBVH_BMESH */ +/** + * Only valid for type == #PBVH_BMESH. + */ struct BMesh *BKE_pbvh_get_bmesh(PBVH *pbvh); void BKE_pbvh_bmesh_detail_size_set(PBVH *pbvh, float detail_size); @@ -244,6 +271,9 @@ typedef enum { PBVH_Subdivide = 1, PBVH_Collapse = 2, } PBVHTopologyUpdateMode; +/** + * Collapse short edges, subdivide long edges. + */ bool BKE_pbvh_bmesh_update_topology(PBVH *pbvh, PBVHTopologyUpdateMode mode, const float center[3], @@ -287,18 +317,28 @@ void BKE_pbvh_node_get_original_BB(PBVHNode *node, float bb_min[3], float bb_max float BKE_pbvh_node_get_tmin(PBVHNode *node); -/* test if AABB is at least partially inside the PBVHFrustumPlanes volume */ +/** + * Test if AABB is at least partially inside the #PBVHFrustumPlanes volume. + */ bool BKE_pbvh_node_frustum_contain_AABB(PBVHNode *node, void *frustum); -/* test if AABB is at least partially outside the PBVHFrustumPlanes volume */ +/** + * Test if AABB is at least partially outside the #PBVHFrustumPlanes volume. + */ bool BKE_pbvh_node_frustum_exclude_AABB(PBVHNode *node, void *frustum); struct GSet *BKE_pbvh_bmesh_node_unique_verts(PBVHNode *node); struct GSet *BKE_pbvh_bmesh_node_other_verts(PBVHNode *node); struct GSet *BKE_pbvh_bmesh_node_faces(PBVHNode *node); +/** + * In order to perform operations on the original node coordinates + * (currently just ray-cast), store the node's triangles and vertices. + * + * Skips triangles that are hidden. + */ void BKE_pbvh_bmesh_node_save_orig(struct BMesh *bm, PBVHNode *node); void BKE_pbvh_bmesh_after_stroke(PBVH *pbvh); -/* Update Bounding Box/Redraw and clear flags */ +/* Update Bounding Box/Redraw and clear flags. */ void BKE_pbvh_update_bounds(PBVH *pbvh, int flags); void BKE_pbvh_update_vertex_data(PBVH *pbvh, int flags); @@ -318,14 +358,15 @@ void BKE_pbvh_face_sets_color_set(PBVH *pbvh, int seed, int color_default); void BKE_pbvh_respect_hide_set(PBVH *pbvh, bool respect_hide); -/* vertex deformer */ +/* Vertex Deformer. */ + float (*BKE_pbvh_vert_coords_alloc(struct PBVH *pbvh))[3]; void BKE_pbvh_vert_coords_apply(struct PBVH *pbvh, const float (*vertCos)[3], const int totvert); bool BKE_pbvh_is_deformed(struct PBVH *pbvh); -/* Vertex Iterator */ +/* Vertex Iterator. */ -/* this iterator has quite a lot of code, but it's designed to: +/* This iterator has quite a lot of code, but it's designed to: * - allow the compiler to eliminate dead code and variables * - spend most of the time in the relatively simple inner loop */ @@ -469,6 +510,11 @@ void BKE_pbvh_node_get_bm_orco_data(PBVHNode *node, int *r_orco_tris_num, float (**r_orco_coords)[3]); +/** + * \note doing a full search on all vertices here seems expensive, + * however this is important to avoid having to recalculate bound-box & sync the buffers to the + * GPU (which is far more expensive!) See: T47232. + */ bool BKE_pbvh_node_vert_update_check_any(PBVH *pbvh, PBVHNode *node); // void BKE_pbvh_node_BB_reset(PBVHNode *node); @@ -480,7 +526,8 @@ void pbvh_show_mask_set(PBVH *pbvh, bool show_mask); bool pbvh_has_face_sets(PBVH *pbvh); void pbvh_show_face_sets_set(PBVH *pbvh, bool show_face_sets); -/* Parallelization */ +/* Parallelization. */ + void BKE_pbvh_parallel_range_settings(struct TaskParallelSettings *settings, bool use_threading, int totnode); diff --git a/source/blender/blenkernel/BKE_pointcache.h b/source/blender/blenkernel/BKE_pointcache.h index c83fca767a1..abd3f09fbb4 100644 --- a/source/blender/blenkernel/BKE_pointcache.h +++ b/source/blender/blenkernel/BKE_pointcache.h @@ -273,19 +273,28 @@ typedef struct PTCacheEdit { int totpoint, totframes, totcached, edited; } PTCacheEdit; -/* Particle functions */ void BKE_ptcache_make_particle_key(struct ParticleKey *key, int index, void **data, float time); /**************** Creating ID's ****************************/ + void BKE_ptcache_id_from_softbody(PTCacheID *pid, struct Object *ob, struct SoftBody *sb); void BKE_ptcache_id_from_particles(PTCacheID *pid, struct Object *ob, struct ParticleSystem *psys); void BKE_ptcache_id_from_cloth(PTCacheID *pid, struct Object *ob, struct ClothModifierData *clmd); +/** + * The fluid modifier does not actually use this anymore, but some parts of Blender expect that it + * still has a point cache currently. For example, the fluid modifier uses + * #DEG_add_collision_relations, which internally creates relations with the point cache. + */ void BKE_ptcache_id_from_smoke(PTCacheID *pid, struct Object *ob, struct FluidModifierData *fmd); void BKE_ptcache_id_from_dynamicpaint(PTCacheID *pid, struct Object *ob, struct DynamicPaintSurface *surface); void BKE_ptcache_id_from_rigidbody(PTCacheID *pid, struct Object *ob, struct RigidBodyWorld *rbw); +/** + * \param ob: Optional, may be NULL. + * \param scene: Optional may be NULL. + */ PTCacheID BKE_ptcache_id_find(struct Object *ob, struct Scene *scene, struct PointCache *cache); void BKE_ptcache_ids_from_object(struct ListBase *lb, struct Object *ob, @@ -294,10 +303,15 @@ void BKE_ptcache_ids_from_object(struct ListBase *lb, /****************** Query funcs ****************************/ -/* Check whether object has a point cache. */ +/** + * Check whether object has a point cache. + */ bool BKE_ptcache_object_has(struct Scene *scene, struct Object *ob, int duplis); /***************** Global funcs ****************************/ +/** + * Use this when quitting Blender, with unsaved files. + */ void BKE_ptcache_remove(void); /************ ID specific functions ************************/ @@ -316,23 +330,35 @@ void BKE_ptcache_update_info(PTCacheID *pid); /*********** General cache reading/writing ******************/ -/* Size of cache data type. */ +/** + * Size of cache data type. + */ int BKE_ptcache_data_size(int data_type); -/* Is point with index in memory cache */ +/** + * Is point with index in memory cache? + * Check to see if point number "index" is in `pm` (uses binary search for index data). + */ int BKE_ptcache_mem_index_find(struct PTCacheMem *pm, unsigned int index); /* Memory cache read/write helpers. */ + void BKE_ptcache_mem_pointers_init(struct PTCacheMem *pm, void *cur[BPHYS_TOT_DATA]); void BKE_ptcache_mem_pointers_incr(void *cur[BPHYS_TOT_DATA]); int BKE_ptcache_mem_pointers_seek(int point_index, struct PTCacheMem *pm, void *cur[BPHYS_TOT_DATA]); -/* Main cache reading call. */ +/** + * Main cache reading call. + * Possible to get old or interpolated result. + */ int BKE_ptcache_read(PTCacheID *pid, float cfra, bool no_extrapolate_old); -/* Main cache writing call. */ +/** + * Main cache writing call. + * Writes cache to disk or memory. + */ int BKE_ptcache_write(PTCacheID *pid, unsigned int cfra); /******************* Allocate & free ***************/ @@ -340,41 +366,56 @@ struct PointCache *BKE_ptcache_add(struct ListBase *ptcaches); void BKE_ptcache_free_mem(struct ListBase *mem_cache); void BKE_ptcache_free(struct PointCache *cache); void BKE_ptcache_free_list(struct ListBase *ptcaches); +/* returns first point cache */ struct PointCache *BKE_ptcache_copy_list(struct ListBase *ptcaches_new, const struct ListBase *ptcaches_old, const int flag); /********************** Baking *********************/ -/* Bakes cache with cache_step sized jumps in time, not accurate but very fast. */ +/** + * Bakes cache with cache_step sized jumps in time, not accurate but very fast. + */ void BKE_ptcache_quick_cache_all(struct Main *bmain, struct Scene *scene, struct ViewLayer *view_layer); -/* Bake cache or simulate to current frame with settings defined in the baker. */ +/** + * Bake cache or simulate to current frame with settings defined in the baker. + * if bake is not given run simulations to current frame. + */ void BKE_ptcache_bake(struct PTCacheBaker *baker); -/* Convert disk cache to memory cache. */ +/** + * Convert disk cache to memory cache. + */ void BKE_ptcache_disk_to_mem(struct PTCacheID *pid); - -/* Convert memory cache to disk cache. */ +/** + * Convert memory cache to disk cache. + */ void BKE_ptcache_mem_to_disk(struct PTCacheID *pid); - -/* Convert disk cache to memory cache and vice versa. Clears the cache that was converted. */ +/** + * Convert disk cache to memory cache and vice versa. Clears the cache that was converted. + */ void BKE_ptcache_toggle_disk_cache(struct PTCacheID *pid); - -/* Rename all disk cache files with a new name. Doesn't touch the actual content of the files. */ +/** + * Rename all disk cache files with a new name. Doesn't touch the actual content of the files. + */ void BKE_ptcache_disk_cache_rename(struct PTCacheID *pid, const char *name_src, const char *name_dst); -/* Loads simulation from external (disk) cache files. */ +/** + * Loads simulation from external (disk) cache files. + */ void BKE_ptcache_load_external(struct PTCacheID *pid); - -/* Set correct flags after successful simulation step */ +/** + * Set correct flags after successful simulation step. + */ void BKE_ptcache_validate(struct PointCache *cache, int framenr); - -/* Set correct flags after unsuccessful simulation step */ +/** + * Set correct flags after unsuccessful simulation step. + */ void BKE_ptcache_invalidate(struct PointCache *cache); /********************** .blend File I/O *********************/ diff --git a/source/blender/blenkernel/BKE_preferences.h b/source/blender/blenkernel/BKE_preferences.h index e9cb024f117..6d6c58e5c1e 100644 --- a/source/blender/blenkernel/BKE_preferences.h +++ b/source/blender/blenkernel/BKE_preferences.h @@ -35,6 +35,10 @@ struct bUserAssetLibrary; struct bUserAssetLibrary *BKE_preferences_asset_library_add(struct UserDef *userdef, const char *name, const char *path) ATTR_NONNULL(1); +/** + * Unlink and free a library preference member. + * \note Free's \a library itself. + */ void BKE_preferences_asset_library_remove(struct UserDef *userdef, struct bUserAssetLibrary *library) ATTR_NONNULL(); @@ -42,6 +46,12 @@ void BKE_preferences_asset_library_name_set(struct UserDef *userdef, struct bUserAssetLibrary *library, const char *name) ATTR_NONNULL(); +/** + * Set the library path, ensuring it is pointing to a directory. + * Single blend files can only act as "Current File" library; libraries on disk + * should always be directories. If the path does not exist, that's fine; it can + * created as directory if necessary later. + */ void BKE_preferences_asset_library_path_set(struct bUserAssetLibrary *library, const char *path) ATTR_NONNULL(); diff --git a/source/blender/blenkernel/BKE_report.h b/source/blender/blenkernel/BKE_report.h index ec2e8d0f875..8b585fd0167 100644 --- a/source/blender/blenkernel/BKE_report.h +++ b/source/blender/blenkernel/BKE_report.h @@ -35,9 +35,14 @@ extern "C" { * These functions also accept NULL in case no error reporting * is needed. */ -/* report structures are stored in DNA */ +/* Report structures are stored in DNA. */ void BKE_reports_init(ReportList *reports, int flag); +/** + * Only frees the list \a reports. + * To make displayed reports disappear, either remove window-manager reports + * (#wmWindowManager.reports, or #CTX_wm_reports()), or use #WM_report_banners_cancel(). + */ void BKE_reports_clear(ReportList *reports); void BKE_report(ReportList *reports, eReportType type, const char *message); diff --git a/source/blender/blenkernel/BKE_rigidbody.h b/source/blender/blenkernel/BKE_rigidbody.h index e28f668d189..6b6bed29245 100644 --- a/source/blender/blenkernel/BKE_rigidbody.h +++ b/source/blender/blenkernel/BKE_rigidbody.h @@ -41,8 +41,17 @@ struct Scene; /* -------------- */ /* Memory Management */ +/** + * Free rigid-body world. + */ void BKE_rigidbody_free_world(struct Scene *scene); +/** + * Free rigid-body settings and simulation instances. + */ void BKE_rigidbody_free_object(struct Object *ob, struct RigidBodyWorld *rbw); +/** + * Free rigid-body constraint and simulation instance. + */ void BKE_rigidbody_free_constraint(struct Object *ob); /* ...... */ @@ -52,7 +61,9 @@ void BKE_rigidbody_object_copy(struct Main *bmain, const struct Object *ob_src, const int flag); -/* Callback format for performing operations on ID-pointers for rigidbody world. */ +/** + * Callback format for performing operations on ID-pointers for rigid-body world. + */ typedef void (*RigidbodyWorldIDFunc)(struct RigidBodyWorld *rbw, struct ID **idpoin, void *userdata, @@ -65,7 +76,9 @@ void BKE_rigidbody_world_id_loop(struct RigidBodyWorld *rbw, /* -------------- */ /* Setup */ -/* create Blender-side settings data - physics objects not initialized yet */ +/** + * Create Blender-side settings data - physics objects not initialized yet. + */ struct RigidBodyWorld *BKE_rigidbody_create_world(struct Scene *scene); struct RigidBodyOb *BKE_rigidbody_create_object(struct Scene *scene, struct Object *ob, @@ -74,21 +87,29 @@ struct RigidBodyCon *BKE_rigidbody_create_constraint(struct Scene *scene, struct Object *ob, short type); -/* Ensure newly set collections' objects all have required data. */ +/** + * Ensure newly set collections' objects all have required data. + */ void BKE_rigidbody_objects_collection_validate(struct Scene *scene, struct RigidBodyWorld *rbw); void BKE_rigidbody_constraints_collection_validate(struct Scene *scene, struct RigidBodyWorld *rbw); -/* Ensure object added to collection gets RB data if that collection is a RB one. */ +/** + * Ensure object added to collection gets RB data if that collection is a RB one. + */ void BKE_rigidbody_main_collection_object_add(struct Main *bmain, struct Collection *collection, struct Object *object); -/* copy */ +/** + * Copy. + */ struct RigidBodyWorld *BKE_rigidbody_world_copy(struct RigidBodyWorld *rbw, const int flag); void BKE_rigidbody_world_groups_relink(struct RigidBodyWorld *rbw); -/* 'validate' (i.e. make new or replace old) Physics-Engine objects */ +/** + * 'validate' (i.e. make new or replace old) Physics-Engine objects. + */ void BKE_rigidbody_validate_sim_world(struct Scene *scene, struct RigidBodyWorld *rbw, bool rebuild); @@ -118,14 +139,18 @@ void BKE_rigidbody_remove_constraint(struct Main *bmain, /* -------------- */ /* Utility Macros */ -/* get mass of Rigid Body Object to supply to RigidBody simulators */ +/** + * Get mass of Rigid Body Object to supply to RigidBody simulators. + */ #define RBO_GET_MASS(rbo) \ (((rbo) && (((rbo)->type == RBO_TYPE_PASSIVE) || ((rbo)->flag & RBO_FLAG_KINEMATIC) || \ ((rbo)->flag & RBO_FLAG_DISABLED))) ? \ (0.0f) : \ ((rbo)->mass)) -/* Get collision margin for Rigid Body Object, triangle mesh and cone shapes cannot embed margin, - * convex hull always uses custom margin. */ +/** + * Get collision margin for Rigid Body Object, triangle mesh and cone shapes cannot embed margin, + * convex hull always uses custom margin. + */ #define RBO_GET_MARGIN(rbo) \ (((rbo)->flag & RBO_FLAG_USE_MARGIN || (rbo)->shape == RB_SHAPE_CONVEXH || \ (rbo)->shape == RB_SHAPE_TRIMESH || (rbo)->shape == RB_SHAPE_CONE) ? \ diff --git a/source/blender/blenkernel/BKE_scene.h b/source/blender/blenkernel/BKE_scene.h index f3edf8e9f64..77cf250471f 100644 --- a/source/blender/blenkernel/BKE_scene.h +++ b/source/blender/blenkernel/BKE_scene.h @@ -46,7 +46,7 @@ typedef enum eSceneCopyMethod { SCE_COPY_FULL = 3, } eSceneCopyMethod; -/* Use as the contents of a 'for' loop: for (SETLOOPER(...)) { ... */ +/** Use as the contents of a 'for' loop: `for (SETLOOPER(...)) { ... }`. */ #define SETLOOPER(_sce_basis, _sce_iter, _base) \ _sce_iter = _sce_basis, \ _base = _setlooper_base_step( \ @@ -64,6 +64,12 @@ typedef enum eSceneCopyMethod { _base; \ _base = _setlooper_base_step(&_sce_iter, NULL, _base) +/** + * Helper function for the #SETLOOPER and #SETLOOPER_VIEW_LAYER macros + * + * It iterates over the bases of the active layer and then the bases + * of the active layer of the background (set) scenes recursively. + */ struct Base *_setlooper_base_step(struct Scene **sce_iter, struct ViewLayer *view_layer, struct Base *base); @@ -77,6 +83,9 @@ void BKE_scene_remove_rigidbody_object(struct Main *bmain, struct Object *ob, const bool free_us); +/** + * Check if there is any instance of the object in the scene. + */ bool BKE_scene_object_find(struct Scene *scene, struct Object *ob); struct Object *BKE_scene_object_find_by_name(const struct Scene *scene, const char *name); @@ -91,6 +100,10 @@ typedef struct SceneBaseIter { int phase; } SceneBaseIter; +/** + * Used by meta-balls, return *all* objects (including duplis) + * existing in the scene (including scene's sets). + */ int BKE_scene_base_iter_next(struct Depsgraph *depsgraph, struct SceneBaseIter *iter, struct Scene **scene, @@ -99,11 +112,33 @@ int BKE_scene_base_iter_next(struct Depsgraph *depsgraph, struct Object **ob); void BKE_scene_base_flag_to_objects(struct ViewLayer *view_layer); +/** + * Synchronize object base flags + * + * This is usually handled by the depsgraph. + * However, in rare occasions we need to use the latest object flags + * before depsgraph is fully updated. + * + * It should (ideally) only run for copy-on-written objects since this is + * runtime data generated per-view-layer. + */ void BKE_scene_object_base_flag_sync_from_base(struct Base *base); +/** + * Sets the active scene, mainly used when running in background mode + * (`--scene` command line argument). + * This is also called to set the scene directly, bypassing windowing code. + * Otherwise #WM_window_set_active_scene is used when changing scenes by the user. + */ void BKE_scene_set_background(struct Main *bmain, struct Scene *sce); +/** + * Called from `creator_args.c`. + */ struct Scene *BKE_scene_set_name(struct Main *bmain, const char *name); +/** + * \param flag: copying options (see BKE_lib_id.h's `LIB_ID_COPY_...` flags for more). + */ struct ToolSettings *BKE_toolsettings_copy(struct ToolSettings *toolsettings, const int flag); void BKE_toolsettings_free(struct ToolSettings *toolsettings); @@ -122,23 +157,49 @@ struct Object *BKE_scene_camera_switch_find(struct Scene *scene); /* DURIAN_CAME bool BKE_scene_camera_switch_update(struct Scene *scene); const char *BKE_scene_find_marker_name(const struct Scene *scene, int frame); +/** + * Return the current marker for this frame, + * we can have more than 1 marker per frame, this just returns the first (unfortunately). + */ const char *BKE_scene_find_last_marker_name(const struct Scene *scene, int frame); int BKE_scene_frame_snap_by_seconds(struct Scene *scene, double interval_in_seconds, int frame); -/* checks for cycle, returns 1 if it's all OK */ +/** + * Checks for cycle, returns true if it's all OK. + */ bool BKE_scene_validate_setscene(struct Main *bmain, struct Scene *sce); +/** + * Return fractional frame number taking into account sub-frames and time + * remapping. This the time value used by animation, modifiers and physics + * evaluation. */ float BKE_scene_ctime_get(const struct Scene *scene); +/** + * Convert integer frame number to fractional frame number taking into account + * sub-frames and time remapping. + */ float BKE_scene_frame_to_ctime(const struct Scene *scene, const int frame); +/** + * Get current fractional frame based on frame and sub-frame. + */ float BKE_scene_frame_get(const struct Scene *scene); +/** + * Set current frame and sub-frame based on a fractional frame. + */ void BKE_scene_frame_set(struct Scene *scene, float frame); struct TransformOrientationSlot *BKE_scene_orientation_slot_get_from_flag(struct Scene *scene, int flag); struct TransformOrientationSlot *BKE_scene_orientation_slot_get(struct Scene *scene, int slot_index); +/** + * Activate a transform orientation in a 3D view based on an enum value. + * + * \param orientation: If this is #V3D_ORIENT_CUSTOM or greater, the custom transform orientation + * with index \a orientation - #V3D_ORIENT_CUSTOM gets activated. + */ void BKE_scene_orientation_slot_set_index(struct TransformOrientationSlot *orient_slot, int orientation); int BKE_scene_orientation_slot_get_index(const struct TransformOrientationSlot *orient_slot); @@ -154,16 +215,29 @@ void BKE_scene_graph_update_tagged(struct Depsgraph *depsgraph, struct Main *bma void BKE_scene_graph_evaluated_ensure(struct Depsgraph *depsgraph, struct Main *bmain); void BKE_scene_graph_update_for_newframe(struct Depsgraph *depsgraph); +/** + * Applies changes right away, does all sets too. + */ void BKE_scene_graph_update_for_newframe_ex(struct Depsgraph *depsgraph, const bool clear_recalc); +/** + * Ensures given scene/view_layer pair has a valid, up-to-date depsgraph. + * + * \warning Sets matching depsgraph as active, + * so should only be called from the active editing context (usually, from operators). + */ void BKE_scene_view_layer_graph_evaluated_ensure(struct Main *bmain, struct Scene *scene, struct ViewLayer *view_layer); +/** + * Return default view. + */ struct SceneRenderView *BKE_scene_add_render_view(struct Scene *sce, const char *name); bool BKE_scene_remove_render_view(struct Scene *scene, struct SceneRenderView *srv); -/* render profile */ +/* Render profile. */ + int get_render_subsurf_level(const struct RenderData *r, int lvl, bool for_render); int get_render_child_particle_number(const struct RenderData *r, int num, bool for_render); @@ -174,8 +248,12 @@ bool BKE_scene_uses_blender_eevee(const struct Scene *scene); bool BKE_scene_uses_blender_workbench(const struct Scene *scene); bool BKE_scene_uses_cycles(const struct Scene *scene); -/* Return whether the Cycles experimental feature is enabled. It is invalid to call without first - * ensuring that Cycles is the active render engine (e.g. with BKE_scene_uses_cycles). */ +/** + * Return whether the Cycles experimental feature is enabled. It is invalid to call without first + * ensuring that Cycles is the active render engine (e.g. with #BKE_scene_uses_cycles). + * + * \note We cannot use `const` as RNA_id_pointer_create is not using a const ID. + */ bool BKE_scene_uses_cycles_experimental_features(struct Scene *scene); void BKE_scene_copy_data_eevee(struct Scene *sce_dst, const struct Scene *sce_src); @@ -191,13 +269,27 @@ int BKE_render_preview_pixel_size(const struct RenderData *r); /**********************************/ +/** + * Apply the needed correction factor to value, based on unit_type + * (only length-related are affected currently) and `unit->scale_length`. + */ double BKE_scene_unit_scale(const struct UnitSettings *unit, const int unit_type, double value); -/* multiview */ +/* Multi-view. */ + bool BKE_scene_multiview_is_stereo3d(const struct RenderData *rd); +/** + * Return whether to render this #SceneRenderView. + */ bool BKE_scene_multiview_is_render_view_active(const struct RenderData *rd, const struct SceneRenderView *srv); +/** + * \return true if `viewname` is the first or if the name is NULL or not found. + */ bool BKE_scene_multiview_is_render_view_first(const struct RenderData *rd, const char *viewname); +/** + * \return true if `viewname` is the last or if the name is NULL or not found. + */ bool BKE_scene_multiview_is_render_view_last(const struct RenderData *rd, const char *viewname); int BKE_scene_multiview_num_views_get(const struct RenderData *rd); struct SceneRenderView *BKE_scene_multiview_render_view_findindex(const struct RenderData *rd, @@ -208,6 +300,12 @@ int BKE_scene_multiview_view_id_get(const struct RenderData *rd, const char *vie void BKE_scene_multiview_filepath_get(struct SceneRenderView *srv, const char *filepath, char *r_filepath); +/** + * When multi-view is not used the `filepath` is as usual (e.g., `Image.jpg`). + * When multi-view is on, even if only one view is enabled the view is incorporated + * into the file name (e.g., `Image_L.jpg`). That allows for the user to re-render + * individual views. + */ void BKE_scene_multiview_view_filepath_get(const struct RenderData *rd, const char *filepath, const char *view, @@ -231,10 +329,14 @@ void BKE_scene_ensure_depsgraph_hash(struct Scene *scene); void BKE_scene_free_depsgraph_hash(struct Scene *scene); void BKE_scene_free_view_layer_depsgraph(struct Scene *scene, struct ViewLayer *view_layer); -/* Do not allocate new depsgraph. */ +/** + * \note Do not allocate new depsgraph. + */ struct Depsgraph *BKE_scene_get_depsgraph(const struct Scene *scene, const struct ViewLayer *view_layer); -/* Allocate new depsgraph if necessary. */ +/** + * \note Allocate new depsgraph if necessary. + */ struct Depsgraph *BKE_scene_ensure_depsgraph(struct Main *bmain, struct Scene *scene, struct ViewLayer *view_layer); @@ -246,6 +348,10 @@ void BKE_scene_transform_orientation_remove(struct Scene *scene, struct TransformOrientation *orientation); struct TransformOrientation *BKE_scene_transform_orientation_find(const struct Scene *scene, const int index); +/** + * \return the index that \a orientation has within \a scene's transform-orientation list + * or -1 if not found. + */ int BKE_scene_transform_orientation_get_index(const struct Scene *scene, const struct TransformOrientation *orientation); diff --git a/source/blender/blenkernel/BKE_screen.h b/source/blender/blenkernel/BKE_screen.h index 5c913ed851f..f5acb810950 100644 --- a/source/blender/blenkernel/BKE_screen.h +++ b/source/blender/blenkernel/BKE_screen.h @@ -396,7 +396,8 @@ typedef struct Menu { struct uiLayout *layout; /* runtime for drawing */ } Menu; -/* spacetypes */ +/* Space-types. */ + struct SpaceType *BKE_spacetype_from_id(int spaceid); struct ARegionType *BKE_regiontype_from_id_or_first(const struct SpaceType *st, int regionid); struct ARegionType *BKE_regiontype_from_id(const struct SpaceType *st, int regionid); @@ -405,11 +406,26 @@ void BKE_spacetype_register(struct SpaceType *st); bool BKE_spacetype_exists(int spaceid); void BKE_spacetypes_free(void); /* only for quitting blender */ -/* spacedata */ +/* Space-data. */ + void BKE_spacedata_freelist(ListBase *lb); +/** + * \param lb1: should be empty. + */ void BKE_spacedata_copylist(ListBase *lb1, ListBase *lb2); + +/** + * Facility to set locks for drawing to survive (render) threads accessing drawing data. + * + * \note Lock can become bit-flag too. + * \note Should be replaced in future by better local data handling for threads. + */ void BKE_spacedata_draw_locks(bool set); +/** + * Version of #BKE_area_find_region_type that also works if \a slink + * is not the active space of \a area. + */ struct ARegion *BKE_spacedata_find_region_type(const struct SpaceLink *slink, const struct ScrArea *area, int region_type) ATTR_WARN_UNUSED_RESULT @@ -417,21 +433,42 @@ struct ARegion *BKE_spacedata_find_region_type(const struct SpaceLink *slink, void BKE_spacedata_callback_id_remap_set(void (*func)( struct ScrArea *area, struct SpaceLink *sl, struct ID *old_id, struct ID *new_id)); +/** + * Currently unused! + */ void BKE_spacedata_id_unref(struct ScrArea *area, struct SpaceLink *sl, struct ID *id); -/* area/regions */ +/* Area/regions. */ + struct ARegion *BKE_area_region_copy(const struct SpaceType *st, const struct ARegion *region); +/** + * Doesn't free the region itself. + */ void BKE_area_region_free(struct SpaceType *st, struct ARegion *region); void BKE_area_region_panels_free(struct ListBase *panels); +/** + * Doesn't free the area itself. + */ void BKE_screen_area_free(struct ScrArea *area); -/* Gizmo-maps of a region need to be freed with the region. - * Uses callback to avoid low-level call. */ +/** + * Gizmo-maps of a region need to be freed with the region. + * Uses callback to avoid low-level call. + */ void BKE_region_callback_free_gizmomap_set(void (*callback)(struct wmGizmoMap *)); void BKE_region_callback_refresh_tag_gizmomap_set(void (*callback)(struct wmGizmoMap *)); +/** + * Find a region of type \a region_type in the currently active space of \a area. + * + * \note This does _not_ work if the region to look up is not in the active space. + * Use #BKE_spacedata_find_region_type if that may be the case. + */ struct ARegion *BKE_area_find_region_type(const struct ScrArea *area, int type); struct ARegion *BKE_area_find_region_active_win(struct ScrArea *area); struct ARegion *BKE_area_find_region_xy(struct ScrArea *area, const int regiontype, int x, int y); +/** + * \note This is only for screen level regions (typically menus/popups). + */ struct ARegion *BKE_screen_find_region_xy(struct bScreen *screen, const int regiontype, int x, @@ -442,9 +479,17 @@ struct ARegion *BKE_screen_find_main_region_at_xy(struct bScreen *screen, const int x, const int y); +/** + * \note Ideally we can get the area from the context, + * there are a few places however where this isn't practical. + */ struct ScrArea *BKE_screen_find_area_from_space(struct bScreen *screen, struct SpaceLink *sl) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1, 2); +/** + * \note Using this function is generally a last resort, you really want to be + * using the context when you can - campbell + */ struct ScrArea *BKE_screen_find_big_area(struct bScreen *screen, const int spacetype, const short min); @@ -462,15 +507,24 @@ bool BKE_screen_is_fullscreen_area(const struct bScreen *screen) ATTR_WARN_UNUSE ATTR_NONNULL(); bool BKE_screen_is_used(const struct bScreen *screen) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(); -/* zoom factor conversion */ +/* Zoom factor conversion. */ + float BKE_screen_view3d_zoom_to_fac(float camzoom); float BKE_screen_view3d_zoom_from_fac(float zoomfac); void BKE_screen_view3d_shading_init(struct View3DShading *shading); -/* screen */ +/* Screen. */ + +/** + * Callback used by lib_query to walk over all ID usages + * (mimics `foreach_id` callback of #IDTypeInfo structure). + */ void BKE_screen_foreach_id_screen_area(struct LibraryForeachIDData *data, struct ScrArea *area); +/** + * Free (or release) any data used by this screen (does not free the screen itself). + */ void BKE_screen_free_data(struct bScreen *screen); void BKE_screen_area_map_free(struct ScrAreaMap *area_map) ATTR_NONNULL(); @@ -486,18 +540,28 @@ void BKE_screen_remove_unused_scrverts(struct bScreen *screen); void BKE_screen_header_alignment_reset(struct bScreen *screen); /* .blend file I/O */ + void BKE_screen_view3d_shading_blend_write(struct BlendWriter *writer, struct View3DShading *shading); void BKE_screen_view3d_shading_blend_read_data(struct BlendDataReader *reader, struct View3DShading *shading); void BKE_screen_area_map_blend_write(struct BlendWriter *writer, struct ScrAreaMap *area_map); +/** + * \return false on error. + */ bool BKE_screen_area_map_blend_read_data(struct BlendDataReader *reader, struct ScrAreaMap *area_map); +/** + * And as patch for 2.48 and older. + */ void BKE_screen_view3d_do_versions_250(struct View3D *v3d, ListBase *regions); void BKE_screen_area_blend_read_lib(struct BlendLibReader *reader, struct ID *parent_id, struct ScrArea *area); +/** + * Cannot use #IDTypeInfo callback yet, because of the return value. + */ bool BKE_screen_blend_read_data(struct BlendDataReader *reader, struct bScreen *screen); #ifdef __cplusplus diff --git a/source/blender/blenkernel/BKE_shader_fx.h b/source/blender/blenkernel/BKE_shader_fx.h index 8d1fe709355..a82112ff967 100644 --- a/source/blender/blenkernel/BKE_shader_fx.h +++ b/source/blender/blenkernel/BKE_shader_fx.h @@ -149,17 +149,34 @@ typedef struct ShaderFxTypeInfo { #define SHADERFX_TYPE_PANEL_PREFIX "FX_PT_" -/* Initialize global data (type info and some common global storage). */ +/** + * Initialize global data (type info and some common global storage). + */ void BKE_shaderfx_init(void); +/** + * Get an effect's panel type, which was defined in the #panelRegister callback. + * + * \note ShaderFx panel types are assumed to be named with the struct name field concatenated to + * the defined prefix. + */ void BKE_shaderfxType_panel_id(ShaderFxType type, char *r_idname); void BKE_shaderfx_panel_expand(struct ShaderFxData *fx); const ShaderFxTypeInfo *BKE_shaderfx_get_info(ShaderFxType type); struct ShaderFxData *BKE_shaderfx_new(int type); void BKE_shaderfx_free_ex(struct ShaderFxData *fx, const int flag); void BKE_shaderfx_free(struct ShaderFxData *fx); +/** + * Check unique name. + */ bool BKE_shaderfx_unique_name(struct ListBase *shaderfx, struct ShaderFxData *fx); bool BKE_shaderfx_depends_ontime(struct ShaderFxData *fx); +/** + * Check whether given shaderfx is not local (i.e. from linked data) when the object is a library + * override. + * + * \param shaderfx: May be NULL, in which case we consider it as a non-local shaderfx case. + */ bool BKE_shaderfx_is_nonlocal_in_liboverride(const struct Object *ob, const struct ShaderFxData *shaderfx); struct ShaderFxData *BKE_shaderfx_findby_type(struct Object *ob, ShaderFxType type); @@ -172,6 +189,9 @@ void BKE_shaderfx_copydata_ex(struct ShaderFxData *fx, void BKE_shaderfx_copy(struct ListBase *dst, const struct ListBase *src); void BKE_shaderfx_foreach_ID_link(struct Object *ob, ShaderFxIDWalkFunc walk, void *userData); +/** + * Check if exist grease pencil effects. + */ bool BKE_shaderfx_has_gpencil(const struct Object *ob); void BKE_shaderfx_blend_write(struct BlendWriter *writer, struct ListBase *fxbase); diff --git a/source/blender/blenkernel/BKE_shrinkwrap.h b/source/blender/blenkernel/BKE_shrinkwrap.h index 70aeb37d995..6ab14628c29 100644 --- a/source/blender/blenkernel/BKE_shrinkwrap.h +++ b/source/blender/blenkernel/BKE_shrinkwrap.h @@ -34,11 +34,11 @@ extern "C" { * Shrinkwrap is composed by a set of functions and options that define the type of shrink. * * 3 modes are available: - * - Nearest vertex - * - Nearest surface - * - Normal projection + * - Nearest vertex. + * - Nearest surface. + * - Normal projection. * - * ShrinkwrapCalcData encapsulates all needed data for shrinkwrap functions. + * #ShrinkwrapCalcData encapsulates all needed data for shrink-wrap functions. * (So that you don't have to pass an enormous amount of arguments to functions) */ @@ -74,6 +74,9 @@ typedef struct ShrinkwrapBoundaryData { const ShrinkwrapBoundaryVertData *boundary_verts; } ShrinkwrapBoundaryData; +/** + * Free boundary data for target project. + */ void BKE_shrinkwrap_discard_boundary_data(struct Mesh *mesh); void BKE_shrinkwrap_compute_boundary_data(struct Mesh *mesh); @@ -89,20 +92,28 @@ typedef struct ShrinkwrapTreeData { ShrinkwrapBoundaryData *boundary; } ShrinkwrapTreeData; -/* Checks if the modifier needs target normals with these settings. */ +/** + * Checks if the modifier needs target normals with these settings. + */ bool BKE_shrinkwrap_needs_normals(int shrinkType, int shrinkMode); -/* Initializes the mesh data structure from the given mesh and settings. */ +/** + * Initializes the mesh data structure from the given mesh and settings. + */ bool BKE_shrinkwrap_init_tree(struct ShrinkwrapTreeData *data, Mesh *mesh, int shrinkType, int shrinkMode, bool force_normals); -/* Frees the tree data if necessary. */ +/** + * Frees the tree data if necessary. + */ void BKE_shrinkwrap_free_tree(struct ShrinkwrapTreeData *data); -/* Implementation of the Shrinkwrap modifier */ +/** + * Main shrink-wrap function (implementation of the shrink-wrap modifier). + */ void shrinkwrapModifier_deform(struct ShrinkwrapModifierData *smd, const struct ModifierEvalContext *ctx, struct Scene *scene, @@ -113,26 +124,36 @@ void shrinkwrapModifier_deform(struct ShrinkwrapModifierData *smd, float (*vertexCos)[3], int numVerts); -/* Used in editmesh_mask_extract.c to shrinkwrap the extracted mesh to the sculpt */ +/** + * Used in `editmesh_mask_extract.c` to shrink-wrap the extracted mesh to the sculpt. + */ void BKE_shrinkwrap_mesh_nearest_surface_deform(struct bContext *C, struct Object *ob_source, struct Object *ob_target); -/* Used in object_remesh.cc to preserve the details and volume in the voxel remesher */ +/** + * Used in `object_remesh.cc` to preserve the details and volume in the voxel remesher. + */ void BKE_shrinkwrap_remesh_target_project(struct Mesh *src_me, struct Mesh *target_me, struct Object *ob_target); -/* - * This function casts a ray in the given BVHTree. - * but it takes into consideration the space_transform, that is: +/** + * This function ray-cast a single vertex and updates the hit if the "hit" is considered valid. * - * if transf was configured with "SPACE_TRANSFORM_SETUP( &transf, ob1, ob2 )" - * then the input (vert, dir, BVHTreeRayHit) must be defined in ob1 coordinates space - * and the BVHTree must be built in ob2 coordinate space. + * \param options: Opts control whether an hit is valid or not. + * Supported options are: + * - #MOD_SHRINKWRAP_CULL_TARGET_FRONTFACE (front faces hits are ignored) + * - #MOD_SHRINKWRAP_CULL_TARGET_BACKFACE (back faces hits are ignored) * + * \param transf: Take into consideration the space_transform, that is: + * if `transf` was configured with `SPACE_TRANSFORM_SETUP( &transf, ob1, ob2)` + * then the input (vert, dir, #BVHTreeRayHit) must be defined in ob1 coordinates space + * and the #BVHTree must be built in ob2 coordinate space. * Thus it provides an easy way to cast the same ray across several trees - * (where each tree was built on its own coords space) + * (where each tree was built on its own coords space). + * + * \return true if "hit" was updated. */ bool BKE_shrinkwrap_project_normal(char options, const float vert[3], @@ -142,14 +163,21 @@ bool BKE_shrinkwrap_project_normal(char options, struct ShrinkwrapTreeData *tree, BVHTreeRayHit *hit); -/* Maps the point to the nearest surface, either by simple nearest, - * or by target normal projection. */ +/** + * Maps the point to the nearest surface, either by simple nearest, or by target normal projection. + */ void BKE_shrinkwrap_find_nearest_surface(struct ShrinkwrapTreeData *tree, struct BVHTreeNearest *nearest, float co[3], int type); -/* Computes a smooth normal of the target (if applicable) at the hit location. */ +/** + * Compute a smooth normal of the target (if applicable) at the hit location. + * + * \param tree: information about the mesh. + * \param transform: transform from the hit coordinate space to the object space; may be null. + * \param r_no: output in hit coordinate space; may be shared with inputs. + */ void BKE_shrinkwrap_compute_smooth_normal(const struct ShrinkwrapTreeData *tree, const struct SpaceTransform *transform, int looptri_idx, @@ -157,7 +185,13 @@ void BKE_shrinkwrap_compute_smooth_normal(const struct ShrinkwrapTreeData *tree, const float hit_no[3], float r_no[3]); -/* Apply the shrink to surface modes to the given original coordinates and nearest point. */ +/** + * Apply the shrink to surface modes to the given original coordinates and nearest point. + * + * \param tree: mesh data for smooth normals. + * \param transform: transform from the hit coordinate space to the object space; may be null. + * \param r_point_co: may be the same memory location as `point_co`, `hit_co`, or `hit_no`. + */ void BKE_shrinkwrap_snap_point_to_surface(const struct ShrinkwrapTreeData *tree, const struct SpaceTransform *transform, int mode, diff --git a/source/blender/blenkernel/BKE_softbody.h b/source/blender/blenkernel/BKE_softbody.h index 58dc90f62dc..5d010fa2155 100644 --- a/source/blender/blenkernel/BKE_softbody.h +++ b/source/blender/blenkernel/BKE_softbody.h @@ -46,16 +46,24 @@ typedef struct BodyPoint { float springweight; } BodyPoint; -/* allocates and initializes general main data */ +/** + * Allocates and initializes general main data. + */ extern struct SoftBody *sbNew(void); -/* frees internal data and soft-body itself */ +/** + * Frees internal data and soft-body itself. + */ extern void sbFree(struct Object *ob); -/* frees simulation data to reset simulation */ +/** + * Frees simulation data to reset simulation. + */ extern void sbFreeSimulation(struct SoftBody *sb); -/* do one simul step, reading and writing vertex locs from given array */ +/** + * Do one simulation step, reading and writing vertex locs from given array. + * */ extern void sbObjectStep(struct Depsgraph *depsgraph, struct Scene *scene, struct Object *ob, @@ -63,13 +71,30 @@ extern void sbObjectStep(struct Depsgraph *depsgraph, float (*vertexCos)[3], int numVerts); -/* makes totally fresh start situation, resets time */ +/** + * Makes totally fresh start situation, resets time. + */ extern void sbObjectToSoftbody(struct Object *ob); -/* links the soft-body module to a 'test for Interrupt' function */ -/* pass NULL to unlink again */ +/** + * Soft-body global visible functions. + * Links the soft-body module to a 'test for Interrupt' function, pass NULL to clear the callback. + */ extern void sbSetInterruptCallBack(int (*f)(void)); +/** + * A precise position vector denoting the motion of the center of mass give a rotation/scale matrix + * using averaging method, that's why estimate and not calculate see: this is kind of reverse + * engineering: having to states of a point cloud and recover what happened our advantage here we + * know the identity of the vertex there are others methods giving other results. + * + * \param ob: Any object that can do soft-body e.g. mesh, lattice, curve. + * \param lloc: Output of the calculated location (or NULL). + * \param lrot: Output of the calculated rotation (or NULL). + * \param lscale: Output for the calculated scale (or NULL). + * + * For velocity & 2nd order stuff see: #vcloud_estimate_transform_v3. + */ extern void SB_estimate_transform(Object *ob, float lloc[3], float lrot[3][3], float lscale[3][3]); #ifdef __cplusplus diff --git a/source/blender/blenkernel/BKE_spline.hh b/source/blender/blenkernel/BKE_spline.hh index b8b18f0b50a..d487bf15e25 100644 --- a/source/blender/blenkernel/BKE_spline.hh +++ b/source/blender/blenkernel/BKE_spline.hh @@ -106,8 +106,17 @@ class Spline { copy_base_settings(other, *this); } + /** + * Return a new spline with the same data, settings, and attributes. + */ SplinePtr copy() const; + /** + * Return a new spline with the same type and settings like "cyclic", but without any data. + */ SplinePtr copy_only_settings() const; + /** + * The same as #copy, but skips copying dynamic attributes to the new spline. + */ SplinePtr copy_without_attributes() const; static void copy_base_settings(const Spline &src, Spline &dst); @@ -147,8 +156,22 @@ class Spline { virtual blender::Span evaluated_positions() const = 0; + /** + * Return non-owning access to the cache of accumulated lengths along the spline. Each item is + * the length of the subsequent segment, i.e. the first value is the length of the first segment + * rather than 0. This calculation is rather trivial, and only depends on the evaluated + * positions. However, the results are used often, and it is necessarily single threaded, so it + * is cached. + */ blender::Span evaluated_lengths() const; + /** + * Return non-owning access to the direction of the curve at each evaluated point. + */ blender::Span evaluated_tangents() const; + /** + * Return non-owning access to the direction vectors perpendicular to the tangents at every + * evaluated point. The method used to generate the normal vectors depends on Spline.normal_mode. + */ blender::Span evaluated_normals() const; void bounds_min_max(blender::float3 &min, blender::float3 &max, const bool use_evaluated) const; @@ -173,11 +196,24 @@ class Spline { float factor; }; LookupResult lookup_evaluated_factor(const float factor) const; + /** + * \note This does not support extrapolation currently. + */ LookupResult lookup_evaluated_length(const float length) const; + /** + * Return an array of evenly spaced samples along the length of the spline. The samples are + * indices and factors to the next index encoded in floats. The logic for converting from the + * float values to interpolation data is in #lookup_data_from_index_factor. + */ blender::Array sample_uniform_index_factors(const int samples_size) const; LookupResult lookup_data_from_index_factor(const float index_factor) const; + /** + * Sample any input data with a value for each evaluated point (already interpolated to evaluated + * points) to arbitrary parameters in between the evaluated points. The interpolation is quite + * simple, but this handles the cyclic and end point special cases. + */ void sample_with_index_factors(const blender::fn::GVArray &src, blender::Span index_factors, blender::fn::GMutableSpan dst) const; @@ -426,6 +462,12 @@ class BezierSpline final : public Spline { const float parameter); private: + /** + * If the spline is not cyclic, the direction for the first and last points is just the + * direction formed by the corresponding handles and control points. In the unlikely situation + * that the handles define a zero direction, fallback to using the direction defined by the + * first and last evaluated segments already calculated in #Spline::evaluated_tangents(). + */ void correct_end_tangents() const final; void copy_settings(Spline &dst) const final; void copy_data(Spline &dst) const final; @@ -599,6 +641,12 @@ class PolySpline final : public Spline { blender::Span evaluated_positions() const final; + /** + * Poly spline interpolation from control points to evaluated points is a special case, since + * the result data is the same as the input data. This function returns a #GVArray that points to + * the original data. Therefore the lifetime of the returned virtual array must not be longer + * than the source data. + */ blender::fn::GVArray interpolate_to_evaluated(const blender::fn::GVArray &src) const final; protected: diff --git a/source/blender/blenkernel/BKE_studiolight.h b/source/blender/blenkernel/BKE_studiolight.h index 59b1c2b28d9..792186dd260 100644 --- a/source/blender/blenkernel/BKE_studiolight.h +++ b/source/blender/blenkernel/BKE_studiolight.h @@ -143,6 +143,8 @@ typedef struct StudioLight { void *free_function_data; } StudioLight; +/* API */ + void BKE_studiolight_init(void); void BKE_studiolight_free(void); void BKE_studiolight_default(SolidLight lights[4], float light_ambient[3]); @@ -151,12 +153,18 @@ struct StudioLight *BKE_studiolight_findindex(int index, int flag); struct StudioLight *BKE_studiolight_find_default(int flag); void BKE_studiolight_preview(uint *icon_buffer, StudioLight *sl, int icon_id_type); struct ListBase *BKE_studiolight_listbase(void); +/** + * Ensure state of studio-lights. + */ void BKE_studiolight_ensure_flag(StudioLight *sl, int flag); void BKE_studiolight_refresh(void); StudioLight *BKE_studiolight_load(const char *path, int type); StudioLight *BKE_studiolight_create(const char *path, const SolidLight light[4], const float light_ambient[3]); +/** + * Only useful for workbench while editing the user-preferences. + */ StudioLight *BKE_studiolight_studio_edit_get(void); void BKE_studiolight_remove(StudioLight *sl); void BKE_studiolight_set_free_function(StudioLight *sl, diff --git a/source/blender/blenkernel/BKE_subsurf.h b/source/blender/blenkernel/BKE_subsurf.h index 3816a822279..db57076082c 100644 --- a/source/blender/blenkernel/BKE_subsurf.h +++ b/source/blender/blenkernel/BKE_subsurf.h @@ -66,18 +66,30 @@ struct DerivedMesh *subsurf_make_derived_from_derived(struct DerivedMesh *dm, void subsurf_calculate_limit_positions(struct Mesh *me, float (*r_positions)[3]); -/* get gridsize from 'level', level must be greater than zero */ +/** + * Get grid-size from 'level', level must be greater than zero. + */ int BKE_ccg_gridsize(int level); -/* x/y grid coordinates at 'low_level' can be multiplied by the result - * of this function to convert to grid coordinates at 'high_level' */ +/** + * X/Y grid coordinates at 'low_level' can be multiplied by the result + * of this function to convert to grid coordinates at 'high_level'. + */ int BKE_ccg_factor(int low_level, int high_level); +/** + * Translate #GridHidden into the #ME_HIDE flag for MVerts. Assumes + * vertices are in the order output by #ccgDM_copyFinalVertArray. + */ void subsurf_copy_grid_hidden(struct DerivedMesh *dm, const struct MPoly *mpoly, struct MVert *mvert, const struct MDisps *mdisps); +/** + * Translate #GridPaintMask into vertex paint masks. Assumes vertices + * are in the order output by #ccgDM_copyFinalVertArray. + */ void subsurf_copy_grid_paint_mask(struct DerivedMesh *dm, const struct MPoly *mpoly, float *paint_mask, diff --git a/source/blender/blenkernel/BKE_text.h b/source/blender/blenkernel/BKE_text.h index c7120c60020..a979ba6d2cc 100644 --- a/source/blender/blenkernel/BKE_text.h +++ b/source/blender/blenkernel/BKE_text.h @@ -30,17 +30,44 @@ struct Main; struct Text; struct TextLine; +/** + * \note caller must handle `compiled` member. + */ void BKE_text_free_lines(struct Text *text); struct Text *BKE_text_add(struct Main *bmain, const char *name); +/** + * Use to a valid UTF-8 sequences. + * this function replaces extended ascii characters. + */ int txt_extended_ascii_as_utf8(char **str); bool BKE_text_reload(struct Text *text); +/** + * Load a text file. + * + * \param is_internal: If \a true, this text data-block only exists in memory, + * not as a file on disk. + * + * \note text data-blocks have no real user but have 'fake user' enabled by default + */ struct Text *BKE_text_load_ex(struct Main *bmain, const char *file, const char *relpath, const bool is_internal); +/** + * Load a text file. + * + * \note Text data-blocks have no user by default, only the 'real user' flag. + */ struct Text *BKE_text_load(struct Main *bmain, const char *file, const char *relpath); void BKE_text_clear(struct Text *text); void BKE_text_write(struct Text *text, const char *str); +/** + * \return codes: + * - 0 if file on disk is the same or Text is in memory only. + * - 1 if file has been modified on disk since last local edit. + * - 2 if file on disk has been deleted. + * - -1 is returned if an error occurs. + */ int BKE_text_file_modified_check(struct Text *text); void BKE_text_file_modified_ignore(struct Text *text); @@ -61,12 +88,20 @@ void txt_move_eof(struct Text *text, const bool sel); void txt_move_bol(struct Text *text, const bool sel); void txt_move_eol(struct Text *text, const bool sel); void txt_move_toline(struct Text *text, unsigned int line, const bool sel); +/** + * Moves to a certain byte in a line, not a certain utf8-character. + */ void txt_move_to(struct Text *text, unsigned int line, unsigned int ch, const bool sel); void txt_pop_sel(struct Text *text); void txt_delete_char(struct Text *text); void txt_delete_word(struct Text *text); void txt_delete_selected(struct Text *text); void txt_sel_all(struct Text *text); +/** + * Reverse of #txt_pop_sel + * Clears the selection and ensures the cursor is located + * at the selection (where the cursor is visually while editing). + */ void txt_sel_clear(struct Text *text); void txt_sel_line(struct Text *text); void txt_sel_set(struct Text *text, int startl, int startc, int endl, int endc); @@ -91,7 +126,9 @@ bool txt_cursor_is_line_end(const struct Text *text); int txt_calc_tab_left(struct TextLine *tl, int ch); int txt_calc_tab_right(struct TextLine *tl, int ch); -/* Utility functions, could be moved somewhere more generic but are python/text related. */ +/** + * Utility functions, could be moved somewhere more generic but are python/text related. + */ int text_check_bracket(const char ch); bool text_check_delim(const char ch); bool text_check_digit(const char ch); @@ -100,7 +137,7 @@ bool text_check_identifier_nodigit(const char ch); bool text_check_whitespace(const char ch); int text_find_identifier_start(const char *str, int i); -/* defined in bpy_interface.c */ +/* EVIL: defined in `bpy_interface.c`. */ extern int text_check_identifier_unicode(const unsigned int ch); extern int text_check_identifier_nodigit_unicode(const unsigned int ch); @@ -110,7 +147,14 @@ enum { }; /* Fast non-validating buffer conversion for undo. */ + +/** + * Create a buffer, the only requirement is #txt_from_buf_for_undo can decode it. + */ char *txt_to_buf_for_undo(struct Text *text, int *r_buf_len); +/** + * Decode a buffer from #txt_to_buf_for_undo. + */ void txt_from_buf_for_undo(struct Text *text, const char *buf, int buf_len); #ifdef __cplusplus diff --git a/source/blender/blenkernel/BKE_texture.h b/source/blender/blenkernel/BKE_texture.h index ef322d0cd31..380b5cf035c 100644 --- a/source/blender/blenkernel/BKE_texture.h +++ b/source/blender/blenkernel/BKE_texture.h @@ -42,6 +42,9 @@ struct TexResult; /** #ColorBand.data length. */ #define MAXCOLORBAND 32 +/** + * Utility for all IDs using those texture slots. + */ void BKE_texture_mtex_foreach_id(struct LibraryForeachIDData *data, struct MTex *mtex); void BKE_texture_default(struct Tex *tex); @@ -50,6 +53,9 @@ void BKE_texture_type_set(struct Tex *tex, int type); void BKE_texture_mtex_default(struct MTex *mtex); struct MTex *BKE_texture_mtex_add(void); +/** + * Slot -1 for first free ID. + */ struct MTex *BKE_texture_mtex_add_id(struct ID *id, int slot); /* UNUSED */ // void autotexname(struct Tex *tex); @@ -79,6 +85,9 @@ struct PointDensity *BKE_texture_pointdensity_add(void); struct PointDensity *BKE_texture_pointdensity_copy(const struct PointDensity *pd, const int flag); bool BKE_texture_dependsOnTime(const struct Tex *texture); +/** + * \returns true if this texture can use its #Texture.ima (even if its NULL). + */ bool BKE_texture_is_image_user(const struct Tex *tex); void BKE_texture_get_value_ex(const struct Scene *scene, @@ -94,6 +103,9 @@ void BKE_texture_get_value(const struct Scene *scene, struct TexResult *texres, bool use_color_management); +/** + * Make sure all images used by texture are loaded into pool. + */ void BKE_texture_fetch_images_for_pool(struct Tex *texture, struct ImagePool *pool); #ifdef __cplusplus diff --git a/source/blender/blenkernel/BKE_tracking.h b/source/blender/blenkernel/BKE_tracking.h index 47145a7d6bd..9caf5d31765 100644 --- a/source/blender/blenkernel/BKE_tracking.h +++ b/source/blender/blenkernel/BKE_tracking.h @@ -46,20 +46,53 @@ struct rcti; /* **** Common functions **** */ +/** + * Free tracking structure, only frees structure contents + * (if structure is allocated in heap, it shall be handled outside). + * + * All the pointers inside structure becomes invalid after this call. + */ void BKE_tracking_free(struct MovieTracking *tracking); +/** + * Copy tracking structure content. + */ void BKE_tracking_copy(struct MovieTracking *tracking_dst, const struct MovieTracking *tracking_src, const int flag); +/** + * Initialize motion tracking settings to default values, + * used when new movie clip data-block is created. + */ void BKE_tracking_settings_init(struct MovieTracking *tracking); +/** + * Get list base of active object's tracks. + */ struct ListBase *BKE_tracking_get_active_tracks(struct MovieTracking *tracking); +/** + * Get list base of active object's plane tracks. + */ struct ListBase *BKE_tracking_get_active_plane_tracks(struct MovieTracking *tracking); +/** + * Get reconstruction data of active object. + */ struct MovieTrackingReconstruction *BKE_tracking_get_active_reconstruction( struct MovieTracking *tracking); -/* matrices for constraints and drawing */ +/* Matrices for constraints and drawing. */ + +/** + * Get transformation matrix for a given object which is used + * for parenting motion tracker reconstruction to 3D world. + */ void BKE_tracking_get_camera_object_matrix(struct Object *camera_object, float mat[4][4]); +/** + * Get projection matrix for camera specified by given tracking object + * and frame number. + * + * \note frame number should be in clip space, not scene space. + */ void BKE_tracking_get_projection_matrix(struct MovieTracking *tracking, struct MovieTrackingObject *object, int framenr, @@ -68,16 +101,45 @@ void BKE_tracking_get_projection_matrix(struct MovieTracking *tracking, float mat[4][4]); /* **** Clipboard **** */ +/** + * Free clipboard by freeing memory used by all tracks in it. + */ void BKE_tracking_clipboard_free(void); +/** + * Copy selected tracks from specified object to the clipboard. + */ void BKE_tracking_clipboard_copy_tracks(struct MovieTracking *tracking, struct MovieTrackingObject *object); +/** + * Check whether there are any tracks in the clipboard. + */ bool BKE_tracking_clipboard_has_tracks(void); +/** + * Paste tracks from clipboard to specified object. + * + * Names of new tracks in object are guaranteed to be unique here. + */ void BKE_tracking_clipboard_paste_tracks(struct MovieTracking *tracking, struct MovieTrackingObject *object); /* **** Track **** */ + +/** + * Add new empty track to the given list of tracks. + * + * It is required that caller will append at least one marker to avoid degenerate tracks. + */ struct MovieTrackingTrack *BKE_tracking_track_add_empty(struct MovieTracking *tracking, struct ListBase *tracks_list); +/** + * Add new track to a specified tracks base. + * + * Coordinates are expected to be in normalized 0..1 space, + * frame number is expected to be in clip space. + * + * Width and height are clip's dimension used to scale track's + * pattern and search regions. + */ struct MovieTrackingTrack *BKE_tracking_track_add(struct MovieTracking *tracking, struct ListBase *tracksbase, float x, @@ -85,14 +147,35 @@ struct MovieTrackingTrack *BKE_tracking_track_add(struct MovieTracking *tracking int framenr, int width, int height); +/** + * Duplicate the specified track, result will no belong to any list. + */ struct MovieTrackingTrack *BKE_tracking_track_duplicate(struct MovieTrackingTrack *track); +/** + * Ensure specified track has got unique name, + * if it's not name of specified track will be changed + * keeping names of all other tracks unchanged. + */ void BKE_tracking_track_unique_name(struct ListBase *tracksbase, struct MovieTrackingTrack *track); +/** + * Free specified track, only frees contents of a structure + * (if track is allocated in heap, it shall be handled outside). + * + * All the pointers inside track becomes invalid after this call. + */ void BKE_tracking_track_free(struct MovieTrackingTrack *track); +/** + * Get frame numbers of the very first and last markers. + * There is no check on whether the marker is enabled or not. + */ void BKE_tracking_track_first_last_frame_get(const struct MovieTrackingTrack *track, int *r_first_frame, int *r_last_frame); +/** + * Find the minimum starting frame and maximum ending frame within given set of tracks. + */ void BKE_tracking_tracks_first_last_frame_minmax(/*const*/ struct MovieTrackingTrack **tracks, const int num_tracks, int *r_first_frame, @@ -101,17 +184,50 @@ void BKE_tracking_tracks_first_last_frame_minmax(/*const*/ struct MovieTrackingT int BKE_tracking_count_selected_tracks_in_list(const struct ListBase *tracks_list); int BKE_tracking_count_selected_tracks_in_active_object(/*const*/ struct MovieTracking *tracking); -/* Get array of selected tracks from the current active object in the tracking structure. - * If nothing is selected then the result is nullptr and `r_num_tracks` is set to 0. */ +/** + * Get array of selected tracks from the current active object in the tracking structure. + * If nothing is selected then the result is nullptr and `r_num_tracks` is set to 0. + */ struct MovieTrackingTrack **BKE_tracking_selected_tracks_in_active_object( struct MovieTracking *tracking, int *r_num_tracks); +/** + * Set flag for all specified track's areas. + * + * \param area: which part of marker should be selected. see TRACK_AREA_* constants. + * \param flag: flag to be set for areas. + */ void BKE_tracking_track_flag_set(struct MovieTrackingTrack *track, int area, int flag); +/** + * Clear flag from all specified track's areas. + * + * \param area: which part of marker should be selected. see TRACK_AREA_* constants. + * \param flag: flag to be cleared for areas. + */ void BKE_tracking_track_flag_clear(struct MovieTrackingTrack *track, int area, int flag); +/** + * Check whether track has got marker at specified frame. + * + * \note frame number should be in clip space, not scene space. + */ bool BKE_tracking_track_has_marker_at_frame(struct MovieTrackingTrack *track, int framenr); +/** + * Check whether track has got enabled marker at specified frame. + * + * \note frame number should be in clip space, not scene space. + */ bool BKE_tracking_track_has_enabled_marker_at_frame(struct MovieTrackingTrack *track, int framenr); +/** + * Clear track's path: + * + * - If action is #TRACK_CLEAR_REMAINED path from `ref_frame+1` up to end will be clear. + * - If action is #TRACK_CLEAR_UPTO path from the beginning up to `ref_frame-1` will be clear. + * - If action is #TRACK_CLEAR_ALL only marker at frame ref_frame will remain. + * + * \note frame number should be in clip space, not scene space. + */ void BKE_tracking_track_path_clear(struct MovieTrackingTrack *track, int ref_frame, int action); void BKE_tracking_tracks_join(struct MovieTracking *tracking, @@ -140,7 +256,11 @@ float BKE_tracking_track_get_weight_for_marker(struct MovieClip *clip, struct MovieTrackingTrack *track, struct MovieTrackingMarker *marker); -/* selection */ +/* Selection */ + +/** + * \param area: which part of marker should be selected. see TRACK_AREA_* constants. + */ void BKE_tracking_track_select(struct ListBase *tracksbase, struct MovieTrackingTrack *track, int area, @@ -155,19 +275,31 @@ void BKE_tracking_marker_delete(struct MovieTrackingTrack *track, int framenr); void BKE_tracking_marker_clamp(struct MovieTrackingMarker *marker, int event); +/** + * Get marker closest to the given frame number. + * + * If there is maker with exact frame number it returned. + * Otherwise, marker with highest frame number but lower than the requested + * frame is returned if such marker exists. Otherwise, the marker with lowest + * frame number greater than the requested frame number is returned. + * + * This function has complexity of `O(log number_of_markers)`. + */ struct MovieTrackingMarker *BKE_tracking_marker_get(struct MovieTrackingTrack *track, int framenr); struct MovieTrackingMarker *BKE_tracking_marker_get_exact(struct MovieTrackingTrack *track, int framenr); struct MovieTrackingMarker *BKE_tracking_marker_ensure(struct MovieTrackingTrack *track, int framenr); -/* Get marker position, possibly interpolating gap between key-framed/tracked markers. +/** + * Get marker position, possibly interpolating gap between key-framed/tracked markers. * * The result marker frame number is set to the requested frame number. Its flags are 0 if the * marker is interpolated, and is set to original marker flag if there were no interpolation * involved. * - * Returns truth if the result is usable. */ + * \returns truth if the result is usable. + */ bool BKE_tracking_marker_get_interpolated(struct MovieTrackingTrack *track, const int framenr, struct MovieTrackingMarker *r_marker); @@ -181,12 +313,21 @@ void BKE_tracking_marker_get_subframe_position(struct MovieTrackingTrack *track, float pos[2]); /* **** Plane Track **** */ +/** + * Creates new plane track out of selected point tracks. + */ struct MovieTrackingPlaneTrack *BKE_tracking_plane_track_add(struct MovieTracking *tracking, struct ListBase *plane_tracks_base, struct ListBase *tracks, int framenr); void BKE_tracking_plane_track_unique_name(struct ListBase *plane_tracks_base, struct MovieTrackingPlaneTrack *plane_track); +/** + * Free specified plane track, only frees contents of a structure + * (if track is allocated in heap, it shall be handled outside). + * + * All the pointers inside track becomes invalid after this call. + */ void BKE_tracking_plane_track_free(struct MovieTrackingPlaneTrack *plane_track); bool BKE_tracking_plane_track_has_marker_at_frame(struct MovieTrackingPlaneTrack *plane_track, @@ -222,10 +363,21 @@ struct MovieTrackingPlaneMarker *BKE_tracking_plane_marker_insert( struct MovieTrackingPlaneTrack *plane_track, struct MovieTrackingPlaneMarker *plane_marker); void BKE_tracking_plane_marker_delete(struct MovieTrackingPlaneTrack *plane_track, int framenr); +/** + * Get a plane marker at given frame, + * If there's no such marker, closest one from the left side will be returned. + */ struct MovieTrackingPlaneMarker *BKE_tracking_plane_marker_get( struct MovieTrackingPlaneTrack *plane_track, int framenr); +/** + * Get a plane marker at exact given frame, if there's no marker at the frame, + * NULL will be returned. + */ struct MovieTrackingPlaneMarker *BKE_tracking_plane_marker_get_exact( struct MovieTrackingPlaneTrack *plane_track, int framenr); +/** + * Ensure there's a marker for the given frame. + */ struct MovieTrackingPlaneMarker *BKE_tracking_plane_marker_ensure( struct MovieTrackingPlaneTrack *plane_track, int framenr); void BKE_tracking_plane_marker_get_subframe_corners(struct MovieTrackingPlaneTrack *plane_track, @@ -255,6 +407,9 @@ struct MovieTrackingReconstruction *BKE_tracking_object_get_reconstruction( struct MovieTracking *tracking, struct MovieTrackingObject *object); /* **** Camera **** */ +/** + * Converts principal offset from center to offset of blender's camera. + */ void BKE_tracking_camera_shift_get( struct MovieTracking *tracking, int winx, int winy, float *shiftx, float *shifty); void BKE_tracking_camera_to_blender(struct MovieTracking *tracking, @@ -346,10 +501,21 @@ struct ImBuf *BKE_tracking_get_search_imbuf(struct ImBuf *ibuf, bool anchored, bool disable_channels); +/** + * Zap channels from the imbuf that are disabled by the user. this can lead to + * better tracks sometimes. however, instead of simply zeroing the channels + * out, do a partial gray-scale conversion so the display is better. + */ void BKE_tracking_disable_channels( struct ImBuf *ibuf, bool disable_red, bool disable_green, bool disable_blue, bool grayscale); /* **** 2D tracking **** */ + +/** + * Refine marker's position using previously known keyframe. + * Direction of searching for a keyframe depends on backwards flag, + * which means if backwards is false, previous keyframe will be as reference. + */ void BKE_tracking_refine_marker(struct MovieClip *clip, struct MovieTrackingTrack *track, struct MovieTrackingMarker *marker, @@ -368,6 +534,9 @@ void BKE_autotrack_context_free(struct AutoTrackContext *context); /* **** Plane tracking **** */ +/** + * \note frame number should be in clip space, not scene space. + */ void BKE_tracking_track_plane_from_existing_motion(struct MovieTrackingPlaneTrack *plane_track, int start_frame); void BKE_tracking_retrack_plane_from_existing_motion_at_segment( @@ -377,11 +546,20 @@ void BKE_tracking_homography_between_two_quads(/*const*/ float reference_corners float H[3][3]); /* **** Camera solving **** */ + +/** + * Perform early check on whether everything is fine to start reconstruction. + */ bool BKE_tracking_reconstruction_check(struct MovieTracking *tracking, struct MovieTrackingObject *object, char *error_msg, int error_size); +/** + * Create context for camera/object motion reconstruction. + * Copies all data needed for reconstruction from movie clip datablock, + * so editing this clip is safe during reconstruction job is in progress. + */ struct MovieReconstructContext *BKE_tracking_reconstruction_context_new( struct MovieClip *clip, struct MovieTrackingObject *object, @@ -389,13 +567,29 @@ struct MovieReconstructContext *BKE_tracking_reconstruction_context_new( int keyframe2, int width, int height); +/** + * Free memory used by a reconstruction process. + */ void BKE_tracking_reconstruction_context_free(struct MovieReconstructContext *context); +/** + * Solve camera/object motion and reconstruct 3D markers position + * from a prepared reconstruction context. + * + * stop is not actually used at this moment, so reconstruction + * job could not be stopped. + * + * do_update, progress and stat_message are set by reconstruction + * callback in libmv side and passing to an interface. + */ void BKE_tracking_reconstruction_solve(struct MovieReconstructContext *context, short *stop, short *do_update, float *progress, char *stats_message, int message_size); +/** + * Finish reconstruction process by copying reconstructed data to an actual movie clip data-block. + */ bool BKE_tracking_reconstruction_finish(struct MovieReconstructContext *context, struct MovieTracking *tracking); @@ -405,9 +599,16 @@ void BKE_tracking_reconstruction_report_error_message(struct MovieReconstructCon const char *BKE_tracking_reconstruction_error_message_get( const struct MovieReconstructContext *context); +/** + * Apply scale on all reconstructed cameras and bundles, used by camera scale apply operator. + */ void BKE_tracking_reconstruction_scale(struct MovieTracking *tracking, float scale[3]); /* **** Feature detection **** */ + +/** + * Detect features using FAST detector. + */ void BKE_tracking_detect_fast(struct MovieTracking *tracking, struct ListBase *tracksbase, struct ImBuf *ibuf, @@ -418,6 +619,9 @@ void BKE_tracking_detect_fast(struct MovieTracking *tracking, struct bGPDlayer *layer, bool place_outside_layer); +/** + * Detect features using Harris detector. + */ void BKE_tracking_detect_harris(struct MovieTracking *tracking, struct ListBase *tracksbase, struct ImBuf *ibuf, @@ -429,6 +633,24 @@ void BKE_tracking_detect_harris(struct MovieTracking *tracking, bool place_outside_layer); /* **** 2D stabilization **** */ + +/** + * Get stabilization data (translation, scaling and angle) for a given frame. + * Returned data describes how to compensate the detected movement, but with any + * chosen scale factor already applied and any target frame position already compensated. + * In case stabilization fails or is disabled, neutral values are returned. + * + * \param framenr: is a frame number, relative to the clip (not relative to the scene timeline). + * \param width: is an effective width of the canvas (square pixels), used to scale the + * determined translation. + * + * Outputs: + * \param translation: of the lateral shift, absolute canvas coordinates (square pixels). + * \param scale: of the scaling to apply. + * \param angle: of the rotation angle, relative to the frame center. + * + * TODO(sergey): Use `r_` prefix for output parameters here. + */ void BKE_tracking_stabilization_data_get(struct MovieClip *clip, int framenr, int width, @@ -436,12 +658,30 @@ void BKE_tracking_stabilization_data_get(struct MovieClip *clip, float translation[2], float *scale, float *angle); +/** + * Stabilize given image buffer using stabilization data for a specified frame number. + * + * \note frame number should be in clip space, not scene space. + * + * TODO(sergey): Use `r_` prefix for output parameters here. + */ struct ImBuf *BKE_tracking_stabilize_frame(struct MovieClip *clip, int framenr, struct ImBuf *ibuf, float translation[2], float *scale, float *angle); +/** + * Build a 4x4 transformation matrix based on the given 2D stabilization data. + * mat is a 4x4 matrix in homogeneous coordinates, adapted to the + * final image buffer size and compensated for pixel aspect ratio, + * ready for direct OpenGL drawing. + * + * TODO(sergey): The signature of this function should be changed. we actually + * don't need the dimensions of the image buffer. Instead we + * should consider to provide the pivot point of the rotation as a + * further stabilization data parameter. + */ void BKE_tracking_stabilization_data_to_mat4(int width, int height, float aspect, @@ -450,17 +690,30 @@ void BKE_tracking_stabilization_data_to_mat4(int width, float angle, float mat[4][4]); -/* Dopesheet */ +/* Dope-sheet */ + +/** + * Tag dope-sheet for update, actual update will happen later when it'll be actually needed. + */ void BKE_tracking_dopesheet_tag_update(struct MovieTracking *tracking); +/** + * Do dope-sheet update, if update is not needed nothing will happen. + */ void BKE_tracking_dopesheet_update(struct MovieTracking *tracking); /* **** Query/search **** */ +/** + * \note Returns NULL if the track comes from camera object,. + */ struct MovieTrackingObject *BKE_tracking_find_object_for_track( const struct MovieTracking *tracking, const struct MovieTrackingTrack *track); struct ListBase *BKE_tracking_find_tracks_list_for_track(struct MovieTracking *tracking, const struct MovieTrackingTrack *track); +/** + * \note Returns NULL if the track comes from camera object,. + */ struct MovieTrackingObject *BKE_tracking_find_object_for_plane_track( const struct MovieTracking *tracking, const struct MovieTrackingPlaneTrack *plane_track); struct ListBase *BKE_tracking_find_tracks_list_for_plane_track( diff --git a/source/blender/blenkernel/BKE_undo_system.h b/source/blender/blenkernel/BKE_undo_system.h index 2a90211f8e0..bd005af8390 100644 --- a/source/blender/blenkernel/BKE_undo_system.h +++ b/source/blender/blenkernel/BKE_undo_system.h @@ -172,6 +172,10 @@ typedef enum eUndoTypeFlags { } eUndoTypeFlags; /* Expose since we need to perform operations on specific undo types (rarely). */ +/** \name Public Undo Types + * + * Unfortunately we need this for a handful of places. + * \{ */ extern const UndoType *BKE_UNDOSYS_TYPE_IMAGE; extern const UndoType *BKE_UNDOSYS_TYPE_MEMFILE; extern const UndoType *BKE_UNDOSYS_TYPE_PAINTCURVE; @@ -185,11 +189,17 @@ UndoStack *BKE_undosys_stack_create(void); void BKE_undosys_stack_destroy(UndoStack *ustack); void BKE_undosys_stack_clear(UndoStack *ustack); void BKE_undosys_stack_clear_active(UndoStack *ustack); +/* name optional */ bool BKE_undosys_stack_has_undo(const UndoStack *ustack, const char *name); void BKE_undosys_stack_init_from_main(UndoStack *ustack, struct Main *bmain); +/* called after 'BKE_undosys_stack_init_from_main' */ void BKE_undosys_stack_init_from_context(UndoStack *ustack, struct bContext *C); UndoStep *BKE_undosys_stack_active_with_type(UndoStack *ustack, const UndoType *ut); UndoStep *BKE_undosys_stack_init_or_active_with_type(UndoStack *ustack, const UndoType *ut); +/** + * \param steps: Limit the number of undo steps. + * \param memory_limit: Limit the amount of memory used by the undo stack. + */ void BKE_undosys_stack_limit_steps_and_memory(UndoStack *ustack, int steps, size_t memory_limit); #define BKE_undosys_stack_limit_steps_and_memory_defaults(ustack) \ BKE_undosys_stack_limit_steps_and_memory(ustack, U.undosteps, (size_t)U.undomemory * 1024 * 1024) @@ -197,13 +207,18 @@ void BKE_undosys_stack_limit_steps_and_memory(UndoStack *ustack, int steps, size void BKE_undosys_stack_group_begin(UndoStack *ustack); void BKE_undosys_stack_group_end(UndoStack *ustack); -/* Only some UndoType's require init. */ +/** + * Only some UndoType's require init. + */ UndoStep *BKE_undosys_step_push_init_with_type(UndoStack *ustack, struct bContext *C, const char *name, const UndoType *ut); UndoStep *BKE_undosys_step_push_init(UndoStack *ustack, struct bContext *C, const char *name); +/** + * \param C: Can be NULL from some callers if their encoding function doesn't need it + */ eUndoPushReturn BKE_undosys_step_push_with_type(UndoStack *ustack, struct bContext *C, const char *name, @@ -216,40 +231,117 @@ UndoStep *BKE_undosys_step_find_by_name_with_type(UndoStack *ustack, UndoStep *BKE_undosys_step_find_by_type(UndoStack *ustack, const UndoType *ut); UndoStep *BKE_undosys_step_find_by_name(UndoStack *ustack, const char *name); +/** + * Return direction of the undo/redo from `us_reference` (or `ustack->step_active` if NULL), and + * `us_target`. + * + * \note If `us_reference` and `us_target` are the same, we consider this is an undo. + * + * \return -1 for undo, 1 for redo, 0 in case of error. + */ eUndoStepDir BKE_undosys_step_calc_direction(const UndoStack *ustack, const UndoStep *us_target, const UndoStep *us_reference); +/** + * Undo/Redo until the given `us_target` step becomes the active (currently loaded) one. + * + * \note Unless `us_target` is a 'skipped' one and `use_skip` is true, `us_target` + * will become the active step. + * + * \note In case `use_skip` is true, the final target will always be **beyond** the given one + * (if the given one has to be skipped). + * + * \param us_reference: If NULL, will be set to current active step in the undo stack. Otherwise, + * it is assumed to match the current state, and will be used as basis for the undo/redo process + * (i.e. all steps in-between `us_reference` and `us_target` will be processed). + */ bool BKE_undosys_step_load_data_ex(UndoStack *ustack, struct bContext *C, UndoStep *us_target, UndoStep *us_reference, const bool use_skip); +/** + * Undo/Redo until the given `us_target` step becomes the active (currently loaded) one. + */ bool BKE_undosys_step_load_data(UndoStack *ustack, struct bContext *C, UndoStep *us_target); +/** + * Undo/Redo until the step matching given `index` in the undo stack becomes the active + * (currently loaded) one. + */ void BKE_undosys_step_load_from_index(UndoStack *ustack, struct bContext *C, const int index); +/** + * Undo until `us_target` step becomes the active (currently loaded) one. + * + * \warning This function assumes that the given target step is _before_ current active one. + * + * \note Unless `us_target` is a 'skipped' one and `use_skip` is true, + * `us_target` will become the active step. + * + * \note In case `use_skip` is true, the final target will always be **before** the given one + * (if the given one has to be skipped). + */ bool BKE_undosys_step_undo_with_data_ex(UndoStack *ustack, struct bContext *C, UndoStep *us, bool use_skip); +/** + * Undo until `us_target` step becomes the active (currently loaded) one. + * + * \note See #BKE_undosys_step_undo_with_data_ex for details. + */ bool BKE_undosys_step_undo_with_data(UndoStack *ustack, struct bContext *C, UndoStep *us_target); +/** + * Undo one step from current active (currently loaded) one. + */ bool BKE_undosys_step_undo(UndoStack *ustack, struct bContext *C); +/** + * Redo until `us_target` step becomes the active (currently loaded) one. + * + * \warning This function assumes that the given target step is _after_ current active one. + * + * \note Unless `us_target` is a 'skipped' one and `use_skip` is true, + * `us_target` will become the active step. + * + * \note In case `use_skip` is true, the final target will always be **after** the given one + * (if the given one has to be skipped). + */ bool BKE_undosys_step_redo_with_data_ex(UndoStack *ustack, struct bContext *C, UndoStep *us, bool use_skip); +/** + * Redo until `us_target` step becomes the active (currently loaded) one. + * + * \note See #BKE_undosys_step_redo_with_data_ex for details. + */ bool BKE_undosys_step_redo_with_data(UndoStack *ustack, struct bContext *C, UndoStep *us_target); +/** + * Redo one step from current active one. + */ bool BKE_undosys_step_redo(UndoStack *ustack, struct bContext *C); +/** + * Useful when we want to diff against previous undo data but can't be sure the types match. + */ UndoStep *BKE_undosys_step_same_type_next(UndoStep *us); +/** + * Useful when we want to diff against previous undo data but can't be sure the types match. + */ UndoStep *BKE_undosys_step_same_type_prev(UndoStep *us); -/* Type System */ +/* Type System. */ + +/** + * Similar to #WM_operatortype_append + */ UndoType *BKE_undosys_type_append(void (*undosys_fn)(UndoType *)); void BKE_undosys_type_free_all(void); -/* ID Accessor */ +/* ID Accessor. */ + #if 0 /* functionality is only used internally for now. */ void BKE_undosys_foreach_ID_ref(UndoStack *ustack, UndoTypeForEachIDRefFn foreach_ID_ref_fn, diff --git a/source/blender/blenkernel/BKE_unit.h b/source/blender/blenkernel/BKE_unit.h index b28215a72d1..505cfee3adf 100644 --- a/source/blender/blenkernel/BKE_unit.h +++ b/source/blender/blenkernel/BKE_unit.h @@ -26,9 +26,11 @@ extern "C" { struct UnitSettings; -/* in all cases the value is assumed to be scaled by the user preference */ +/* In all cases the value is assumed to be scaled by the user-preference. */ -/* humanly readable representation of a value in units (used for button drawing) */ +/** + * Humanly readable representation of a value in units (used for button drawing). + */ size_t BKE_unit_value_as_string_adaptive( char *str, int len_max, double value, int prec, int system, int type, bool split, bool pad); size_t BKE_unit_value_as_string(char *str, @@ -39,29 +41,59 @@ size_t BKE_unit_value_as_string(char *str, const struct UnitSettings *settings, bool pad); -/* replace units with values, used before python button evaluation */ +/** + * Replace units with values, used before python button evaluation. + * + * Make a copy of the string that replaces the units with numbers. + * This is only used when evaluating user input and can afford to be a bit slower + * + * This is to be used before python evaluation so: + * `10.1km -> 10.1*1000.0` + * ...will be resolved by Python. + * + * Values will be split by an add sign: + * `5'2" -> 5*0.3048 + 2*0.0254` + * + * \param str_prev: is optional, when valid it is used to get a base unit when none is set. + * + * \return True of a change was made. + */ bool BKE_unit_replace_string( char *str, int len_max, const char *str_prev, double scale_pref, int system, int type); -/* return true if the string contains any valid unit for the given type */ +/** + * \return true if the string contains any valid unit for the given type. + */ bool BKE_unit_string_contains_unit(const char *str, int type); -/* If user does not specify a unit, this converts it to the unit from the settings. */ +/** + * If user does not specify a unit, this converts it to the unit from the settings. + */ double BKE_unit_apply_preferred_unit(const struct UnitSettings *settings, int type, double value); -/* make string keyboard-friendly: 10µm --> 10um */ +/** + * Make string keyboard-friendly, e.g: `10µm -> 10um`. + */ void BKE_unit_name_to_alt(char *str, int len_max, const char *orig_str, int system, int type); -/* the size of the unit used for this value (used for calculating the ckickstep) */ +/** + * The size of the unit used for this value (used for calculating the click-step). + */ double BKE_unit_closest_scalar(double value, int system, int type); -/* base scale for these units */ +/** + * Base scale for these units. + */ double BKE_unit_base_scalar(int system, int type); -/* return true is the unit system exists */ +/** + * \return true is the unit system exists. + */ bool BKE_unit_is_valid(int system, int type); -/* loop over scales, could add names later */ +/** + * Loop over scales, could add names later. + */ // double bUnit_Iter(void **unit, char **name, int system, int type); void BKE_unit_system_get(int system, int type, const void **r_usys_pt, int *r_len); @@ -73,7 +105,7 @@ const char *BKE_unit_identifier_get(const void *usys_pt, int index); double BKE_unit_scalar_get(const void *usys_pt, int index); bool BKE_unit_is_suppressed(const void *usys_pt, int index); -/* aligned with PropertyUnit */ +/** Aligned with #PropertyUnit. */ enum { B_UNIT_NONE = 0, B_UNIT_LENGTH = 1, diff --git a/source/blender/blenkernel/BKE_vfont.h b/source/blender/blenkernel/BKE_vfont.h index 827ae1b6a0f..cd1b30b9358 100644 --- a/source/blender/blenkernel/BKE_vfont.h +++ b/source/blender/blenkernel/BKE_vfont.h @@ -84,6 +84,9 @@ bool BKE_vfont_to_curve_ex(struct Object *ob, bool *r_text_free, struct CharTrans **r_chartransdata); bool BKE_vfont_to_curve_nubase(struct Object *ob, int mode, struct ListBase *r_nubase); +/** + * \warning Expects to have access to evaluated data (i.e. passed object should be evaluated one). + */ bool BKE_vfont_to_curve(struct Object *ob, int mode); void BKE_vfont_build_char(struct Curve *cu, struct ListBase *nubase, diff --git a/source/blender/blenkernel/BKE_vfontdata.h b/source/blender/blenkernel/BKE_vfontdata.h index b6e57dad934..692857b0458 100644 --- a/source/blender/blenkernel/BKE_vfontdata.h +++ b/source/blender/blenkernel/BKE_vfontdata.h @@ -49,6 +49,12 @@ typedef struct VChar { float width; } VChar; +/** + * Construct a new #VFontData structure from free-type font data in `pf`. + * + * \param pf: The font data. + * \retval A new #VFontData structure, or NULL if unable to load. + */ VFontData *BKE_vfontdata_from_freetypefont(struct PackedFile *pf); VFontData *BKE_vfontdata_copy(const VFontData *vfont_src, const int flag); diff --git a/source/blender/blenkernel/BKE_volume.h b/source/blender/blenkernel/BKE_volume.h index 601e0cf26a9..f4f00844b8d 100644 --- a/source/blender/blenkernel/BKE_volume.h +++ b/source/blender/blenkernel/BKE_volume.h @@ -88,6 +88,7 @@ const char *BKE_volume_grids_frame_filepath(const struct Volume *volume); const VolumeGrid *BKE_volume_grid_get_for_read(const struct Volume *volume, int grid_index); VolumeGrid *BKE_volume_grid_get_for_write(struct Volume *volume, int grid_index); const VolumeGrid *BKE_volume_grid_active_get_for_read(const struct Volume *volume); +/* Tries to find a grid with the given name. Make sure that the volume has been loaded. */ const VolumeGrid *BKE_volume_grid_find_for_read(const struct Volume *volume, const char *name); /* Grid @@ -115,9 +116,13 @@ void BKE_volume_grid_unload(const struct Volume *volume, const struct VolumeGrid bool BKE_volume_grid_is_loaded(const struct VolumeGrid *grid); /* Metadata */ + const char *BKE_volume_grid_name(const struct VolumeGrid *grid); VolumeGridType BKE_volume_grid_type(const struct VolumeGrid *grid); int BKE_volume_grid_channels(const struct VolumeGrid *grid); +/** + * Transformation from index space to object space. + */ void BKE_volume_grid_transform_matrix(const struct VolumeGrid *grid, float mat[4][4]); /* Volume Editing diff --git a/source/blender/blenkernel/BKE_workspace.h b/source/blender/blenkernel/BKE_workspace.h index 82a4e5fe08e..ff4e21732c4 100644 --- a/source/blender/blenkernel/BKE_workspace.h +++ b/source/blender/blenkernel/BKE_workspace.h @@ -31,9 +31,17 @@ struct bScreen; struct bToolRef; /* -------------------------------------------------------------------- */ -/* Create, delete, init */ +/** \name Create, Delete, Initialize + * \{ */ struct WorkSpace *BKE_workspace_add(struct Main *bmain, const char *name); +/** + * Remove \a workspace by freeing itself and its data. This is a higher-level wrapper that + * calls #workspace_free_data (through #BKE_id_free) to free the workspace data, and frees + * other data-blocks owned by \a workspace and its layouts (currently that is screens only). + * + * Always use this to remove (and free) workspaces. Don't free non-ID workspace members here. + */ void BKE_workspace_remove(struct Main *bmain, struct WorkSpace *workspace); struct WorkSpaceInstanceHook *BKE_workspace_instance_hook_create(const struct Main *bmain, @@ -41,6 +49,9 @@ struct WorkSpaceInstanceHook *BKE_workspace_instance_hook_create(const struct Ma void BKE_workspace_instance_hook_free(const struct Main *bmain, struct WorkSpaceInstanceHook *hook); +/** + * Add a new layout to \a workspace for \a screen. + */ struct WorkSpaceLayout *BKE_workspace_layout_add(struct Main *bmain, struct WorkSpace *workspace, struct bScreen *screen, @@ -51,17 +62,36 @@ void BKE_workspace_layout_remove(struct Main *bmain, void BKE_workspace_relations_free(ListBase *relation_list); +/** \} */ + /* -------------------------------------------------------------------- */ -/* General Utils */ +/** \name General Utilities + * \{ */ struct WorkSpaceLayout *BKE_workspace_layout_find(const struct WorkSpace *workspace, const struct bScreen *screen) ATTR_NONNULL() ATTR_WARN_UNUSED_RESULT; +/** + * Find the layout for \a screen without knowing which workspace to look in. + * Can also be used to find the workspace that contains \a screen. + * + * \param r_workspace: Optionally return the workspace that contains the + * looked up layout (if found). + */ struct WorkSpaceLayout *BKE_workspace_layout_find_global(const struct Main *bmain, const struct bScreen *screen, struct WorkSpace **r_workspace) ATTR_NONNULL(1, 2); +/** + * Circular workspace layout iterator. + * + * \param callback: Custom function which gets executed for each layout. + * Can return false to stop iterating. + * \param arg: Custom data passed to each \a callback call. + * + * \return the layout at which \a callback returned false. + */ struct WorkSpaceLayout *BKE_workspace_layout_iter_circular( const struct WorkSpace *workspace, struct WorkSpaceLayout *start, @@ -72,8 +102,11 @@ struct WorkSpaceLayout *BKE_workspace_layout_iter_circular( void BKE_workspace_tool_remove(struct WorkSpace *workspace, struct bToolRef *tref) ATTR_NONNULL(1, 2); +/** \} */ + /* -------------------------------------------------------------------- */ -/* Getters/Setters */ +/** \name Getters/Setters + * \{ */ #define GETTER_ATTRS ATTR_NONNULL() ATTR_WARN_UNUSED_RESULT #define SETTER_ATTRS ATTR_NONNULL(1) @@ -81,8 +114,23 @@ void BKE_workspace_tool_remove(struct WorkSpace *workspace, struct bToolRef *tre struct WorkSpace *BKE_workspace_active_get(struct WorkSpaceInstanceHook *hook) GETTER_ATTRS; void BKE_workspace_active_set(struct WorkSpaceInstanceHook *hook, struct WorkSpace *workspace) SETTER_ATTRS; +/** + * Get the layout that is active for \a hook (which is the visible layout for the active workspace + * in \a hook). + */ struct WorkSpaceLayout *BKE_workspace_active_layout_get(const struct WorkSpaceInstanceHook *hook) GETTER_ATTRS; +/** + * \brief Activate a layout + * + * Sets \a layout as active for \a workspace when activated through or already active in \a hook. + * So when the active workspace of \a hook is \a workspace, \a layout becomes the active layout of + * \a hook too. See #BKE_workspace_active_set(). + * + * \a workspace does not need to be active for this. + * + * #WorkSpaceInstanceHook.act_layout should only be modified directly to update the layout pointer. + */ void BKE_workspace_active_layout_set(struct WorkSpaceInstanceHook *hook, const int winid, struct WorkSpace *workspace, @@ -100,6 +148,9 @@ void BKE_workspace_layout_name_set(struct WorkSpace *workspace, const char *new_name) ATTR_NONNULL(); struct bScreen *BKE_workspace_layout_screen_get(const struct WorkSpaceLayout *layout) GETTER_ATTRS; +/** + * Get the layout to be activated should \a workspace become or be the active workspace in \a hook. + */ struct WorkSpaceLayout *BKE_workspace_active_layout_for_workspace_get( const struct WorkSpaceInstanceHook *hook, const struct WorkSpace *workspace) GETTER_ATTRS; @@ -111,6 +162,8 @@ void BKE_workspace_id_tag_all_visible(struct Main *bmain, int tag) ATTR_NONNULL( #undef GETTER_ATTRS #undef SETTER_ATTRS +/** \} */ + #ifdef __cplusplus } #endif diff --git a/source/blender/blenkernel/BKE_writeavi.h b/source/blender/blenkernel/BKE_writeavi.h index 97f998cc1c1..d2a5100ffad 100644 --- a/source/blender/blenkernel/BKE_writeavi.h +++ b/source/blender/blenkernel/BKE_writeavi.h @@ -64,6 +64,10 @@ typedef struct bMovieHandle { } bMovieHandle; bMovieHandle *BKE_movie_handle_get(const char imtype); + +/** + * \note Similar to #BKE_image_path_from_imformat() + */ void BKE_movie_filepath_get(char *string, const struct RenderData *rd, bool preview, diff --git a/source/blender/blenkernel/intern/CCGSubSurf.c b/source/blender/blenkernel/intern/CCGSubSurf.c index 67e7b890548..74f848ac580 100644 --- a/source/blender/blenkernel/intern/CCGSubSurf.c +++ b/source/blender/blenkernel/intern/CCGSubSurf.c @@ -939,7 +939,6 @@ void ccgSubSurf__effectedFaceNeighbors(CCGSubSurf *ss, *numEdges = numE; } -/* copy face grid coordinates to other places */ CCGError ccgSubSurf_updateFromFaces(CCGSubSurf *ss, int lvl, CCGFace **effectedF, int numEffectedF) { int i, S, x, gridSize, cornerIdx, subdivLevels; @@ -986,7 +985,6 @@ CCGError ccgSubSurf_updateFromFaces(CCGSubSurf *ss, int lvl, CCGFace **effectedF return eCCGError_None; } -/* copy other places to face grid coordinates */ CCGError ccgSubSurf_updateToFaces(CCGSubSurf *ss, int lvl, CCGFace **effectedF, int numEffectedF) { int i, S, x, gridSize, cornerIdx, subdivLevels; @@ -1035,8 +1033,6 @@ CCGError ccgSubSurf_updateToFaces(CCGSubSurf *ss, int lvl, CCGFace **effectedF, return eCCGError_None; } -/* stitch together face grids, averaging coordinates at edges - * and vertices, for multires displacements */ CCGError ccgSubSurf_stitchFaces(CCGSubSurf *ss, int lvl, CCGFace **effectedF, int numEffectedF) { CCGVert **effectedV; diff --git a/source/blender/blenkernel/intern/CCGSubSurf.h b/source/blender/blenkernel/intern/CCGSubSurf.h index a9e0d6882c1..9349c33d72a 100644 --- a/source/blender/blenkernel/intern/CCGSubSurf.h +++ b/source/blender/blenkernel/intern/CCGSubSurf.h @@ -100,13 +100,30 @@ CCGError ccgSubSurf_syncFaceDel(CCGSubSurf *ss, CCGFaceHDL fHDL); CCGError ccgSubSurf_processSync(CCGSubSurf *ss); +/** + * Copy face grid coordinates to other places. + */ CCGError ccgSubSurf_updateFromFaces(CCGSubSurf *ss, int lvl, CCGFace **effectedF, int numEffectedF); +/** + * Copy other places to face grid coordinates. + */ CCGError ccgSubSurf_updateToFaces(CCGSubSurf *ss, int lvl, CCGFace **effectedF, int numEffectedF); +/** + * Update normals for specified faces. + */ CCGError ccgSubSurf_updateNormals(CCGSubSurf *ss, CCGFace **effectedF, int numEffectedF); +/** + * Compute subdivision levels from a given starting point, used by multi-res subdivide/propagate, + * by filling in coordinates at a certain level, and then subdividing that up to the highest level. + */ CCGError ccgSubSurf_updateLevels(CCGSubSurf *ss, int lvl, CCGFace **effectedF, int numEffectedF); +/** + * Stitch together face grids, averaging coordinates at edges and vertices, for multi-res + * displacements. + */ CCGError ccgSubSurf_stitchFaces(CCGSubSurf *ss, int lvl, CCGFace **effectedF, int numEffectedF); CCGError ccgSubSurf_setSubdivisionLevels(CCGSubSurf *ss, int subdivisionLevels); diff --git a/source/blender/blenkernel/intern/CCGSubSurf_legacy.c b/source/blender/blenkernel/intern/CCGSubSurf_legacy.c index 99ea1fb9607..e19e01ec034 100644 --- a/source/blender/blenkernel/intern/CCGSubSurf_legacy.c +++ b/source/blender/blenkernel/intern/CCGSubSurf_legacy.c @@ -1309,7 +1309,6 @@ void ccgSubSurf__sync_legacy(CCGSubSurf *ss) /* ** Public API exposed to other areas which depends on old CCG code. ** */ -/* Update normals for specified faces. */ CCGError ccgSubSurf_updateNormals(CCGSubSurf *ss, CCGFace **effectedF, int numEffectedF) { CCGVert **effectedV; @@ -1344,9 +1343,6 @@ CCGError ccgSubSurf_updateNormals(CCGSubSurf *ss, CCGFace **effectedF, int numEf return eCCGError_None; } -/* compute subdivision levels from a given starting point, used by - * multires subdivide/propagate, by filling in coordinates at a - * certain level, and then subdividing that up to the highest level */ CCGError ccgSubSurf_updateLevels(CCGSubSurf *ss, int lvl, CCGFace **effectedF, int numEffectedF) { CCGVert **effectedV; diff --git a/source/blender/blenkernel/intern/DerivedMesh.cc b/source/blender/blenkernel/intern/DerivedMesh.cc index 09050c66cd6..6c9c5490ca0 100644 --- a/source/blender/blenkernel/intern/DerivedMesh.cc +++ b/source/blender/blenkernel/intern/DerivedMesh.cc @@ -295,10 +295,6 @@ static CustomData *dm_getPolyCData(DerivedMesh *dm) return &dm->polyData; } -/** - * Utility function to initialize a DerivedMesh's function pointers to - * the default implementation (for those functions which have a default) - */ void DM_init_funcs(DerivedMesh *dm) { /* default function implementations */ @@ -335,11 +331,6 @@ void DM_init_funcs(DerivedMesh *dm) dm->getLoopDataArray = DM_get_loop_data_layer; } -/** - * Utility function to initialize a DerivedMesh for the desired number - * of vertices, edges and faces (doesn't allocate memory for them, just - * sets up the custom data layers) - */ void DM_init(DerivedMesh *dm, DerivedMeshType type, int numVerts, @@ -368,10 +359,6 @@ void DM_init(DerivedMesh *dm, copy_vn_i(dm->polyData.typemap, CD_NUMTYPES, -1); } -/** - * Utility function to initialize a DerivedMesh for the desired number - * of vertices, edges and faces, with a layer setup copied from source - */ void DM_from_template_ex(DerivedMesh *dm, DerivedMesh *source, DerivedMeshType type, @@ -485,12 +472,6 @@ void DM_ensure_normals(DerivedMesh *dm) BLI_assert((dm->dirty & DM_DIRTY_NORMALS) == 0); } -/** - * Ensure the array is large enough - * - * \note This function must always be thread-protected by caller. - * It should only be used by internal code. - */ void DM_ensure_looptri_data(DerivedMesh *dm) { const unsigned int totpoly = dm->numPolyData; @@ -519,11 +500,11 @@ void DM_ensure_looptri_data(DerivedMesh *dm) } } -/** Utility function to convert an (evaluated) Mesh to a shape key block. */ -/* Just a shallow wrapper around BKE_keyblock_convert_from_mesh, - * that ensures both evaluated mesh and original one has same number of vertices. */ void BKE_mesh_runtime_eval_to_meshkey(Mesh *me_deformed, Mesh *me, KeyBlock *kb) { + /* Just a shallow wrapper around #BKE_keyblock_convert_from_mesh, + * that ensures both evaluated mesh and original one has same number of vertices. */ + const int totvert = me_deformed->totvert; if (totvert == 0 || me->totvert == 0 || me->totvert != totvert) { @@ -533,11 +514,6 @@ void BKE_mesh_runtime_eval_to_meshkey(Mesh *me_deformed, Mesh *me, KeyBlock *kb) BKE_keyblock_convert_from_mesh(me_deformed, me->key, kb); } -/** - * set the CD_FLAG_NOCOPY flag in custom data layers where the mask is - * zero for the layer type, so only layer types specified by the mask - * will be copied - */ void DM_set_only_copy(DerivedMesh *dm, const CustomData_MeshMasks *mask) { CustomData_set_only_copy(&dm->vertData, mask->vmask); @@ -658,11 +634,6 @@ void DM_copy_vert_data( CustomData_copy_data(&source->vertData, &dest->vertData, source_index, dest_index, count); } -/** - * interpolates vertex data from the vertices indexed by src_indices in the - * source mesh using the given weights and stores the result in the vertex - * indexed by dest_index in the dest mesh - */ void DM_interp_vert_data(DerivedMesh *source, DerivedMesh *dest, int *src_indices, diff --git a/source/blender/blenkernel/intern/action.c b/source/blender/blenkernel/intern/action.c index 95d3b2bf53e..ddba726ba83 100644 --- a/source/blender/blenkernel/intern/action.c +++ b/source/blender/blenkernel/intern/action.c @@ -356,7 +356,6 @@ bAction *BKE_action_add(Main *bmain, const char name[]) /* *************** Action Groups *************** */ -/* Get the active action-group for an Action */ bActionGroup *get_active_actiongroup(bAction *act) { bActionGroup *agrp = NULL; @@ -372,7 +371,6 @@ bActionGroup *get_active_actiongroup(bAction *act) return agrp; } -/* Make the given Action-Group the active one */ void set_active_action_group(bAction *act, bActionGroup *agrp, short select) { bActionGroup *grp; @@ -393,7 +391,6 @@ void set_active_action_group(bAction *act, bActionGroup *agrp, short select) } } -/* Sync colors used for action/bone group with theme settings */ void action_group_colors_sync(bActionGroup *grp, const bActionGroup *ref_grp) { /* Only do color copying if using a custom color (i.e. not default color). */ @@ -424,7 +421,6 @@ void action_group_colors_sync(bActionGroup *grp, const bActionGroup *ref_grp) } } -/* Add a new action group with the given name to the action */ bActionGroup *action_groups_add_new(bAction *act, const char name[]) { bActionGroup *agrp; @@ -450,10 +446,6 @@ bActionGroup *action_groups_add_new(bAction *act, const char name[]) return agrp; } -/* Add given channel into (active) group - * - assumes that channel is not linked to anything anymore - * - always adds at the end of the group - */ void action_groups_add_channel(bAction *act, bActionGroup *agrp, FCurve *fcurve) { /* sanity checks */ @@ -522,10 +514,6 @@ void action_groups_add_channel(bAction *act, bActionGroup *agrp, FCurve *fcurve) fcurve->grp = agrp; } -/* Reconstruct group channel pointers. - * Assumes that the groups referred to by the FCurves are already in act->groups. - * Reorders the main channel list to match group order. - */ void BKE_action_groups_reconstruct(bAction *act) { /* Sanity check. */ @@ -565,7 +553,6 @@ void BKE_action_groups_reconstruct(bAction *act) BLI_movelisttolist(&act->curves, &ungrouped); } -/* Remove the given channel from all groups */ void action_groups_remove_channel(bAction *act, FCurve *fcu) { /* sanity checks */ @@ -606,7 +593,6 @@ void action_groups_remove_channel(bAction *act, FCurve *fcu) BLI_remlink(&act->curves, fcu); } -/* Find a group with the given name */ bActionGroup *BKE_action_group_find_name(bAction *act, const char name[]) { /* sanity checks */ @@ -618,7 +604,6 @@ bActionGroup *BKE_action_group_find_name(bAction *act, const char name[]) return BLI_findstring(&act->groups, name, offsetof(bActionGroup, name)); } -/* Clear all 'temp' flags on all groups */ void action_groups_clear_tempflags(bAction *act) { bActionGroup *agrp; @@ -641,10 +626,6 @@ void BKE_pose_channel_session_uuid_generate(bPoseChannel *pchan) pchan->runtime.session_uuid = BLI_session_uuid_generate(); } -/** - * Return a pointer to the pose channel of the given name - * from this pose. - */ bPoseChannel *BKE_pose_channel_find_name(const bPose *pose, const char *name) { if (ELEM(NULL, pose, name) || (name[0] == '\0')) { @@ -658,14 +639,6 @@ bPoseChannel *BKE_pose_channel_find_name(const bPose *pose, const char *name) return BLI_findstring(&pose->chanbase, name, offsetof(bPoseChannel, name)); } -/** - * Looks to see if the channel with the given name - * already exists in this pose - if not a new one is - * allocated and initialized. - * - * \note Use with care, not on Armature poses but for temporal ones. - * \note (currently used for action constraints and in rebuild_pose). - */ bPoseChannel *BKE_pose_channel_ensure(bPose *pose, const char *name) { bPoseChannel *chan; @@ -732,12 +705,6 @@ bool BKE_pose_channels_is_valid(const bPose *pose) #endif -/** - * Find the active pose-channel for an object - * (we can't just use pose, as layer info is in armature) - * - * \note #Object, not #bPose is used here, as we need layer info from Armature. - */ bPoseChannel *BKE_pose_channel_active(Object *ob) { bArmature *arm = (ob) ? ob->data : NULL; @@ -757,15 +724,6 @@ bPoseChannel *BKE_pose_channel_active(Object *ob) return NULL; } -/** - * Use this when detecting the "other selected bone", - * when we have multiple armatures in pose mode. - * - * In this case the active-selected is an obvious choice when finding the target for a - * constraint for eg. however from the users perspective the active pose bone of the - * active object is the _real_ active bone, so any other non-active selected bone - * is a candidate for being the other selected bone, see: T58447. - */ bPoseChannel *BKE_pose_channel_active_or_first_selected(struct Object *ob) { bArmature *arm = (ob) ? ob->data : NULL; @@ -789,9 +747,6 @@ bPoseChannel *BKE_pose_channel_active_or_first_selected(struct Object *ob) return NULL; } -/** - * \see #ED_armature_ebone_get_mirrored (edit-mode, matching function) - */ bPoseChannel *BKE_pose_channel_get_mirrored(const bPose *pose, const char *name) { char name_flip[MAXBONENAME]; @@ -818,12 +773,6 @@ const char *BKE_pose_ikparam_get_name(bPose *pose) return NULL; } -/** - * Allocate a new pose on the heap, and copy the src pose and its channels - * into the new pose. *dst is set to the newly allocated structure, and assumed to be NULL. - * - * \param dst: Should be freed already, makes entire duplicate. - */ void BKE_pose_copy_data_ex(bPose **dst, const bPose *src, const int flag, @@ -975,10 +924,6 @@ bool BKE_pose_channel_in_IK_chain(Object *ob, bPoseChannel *pchan) return pose_channel_in_IK_chain(ob, pchan, 0); } -/** - * Removes the hash for quick lookup of channels, must - * be done when adding/removing channels. - */ void BKE_pose_channels_hash_ensure(bPose *pose) { if (!pose->chanhash) { @@ -1014,9 +959,6 @@ static void pose_channels_remove_internal_links(Object *ob, bPoseChannel *unlink } } -/** - * Selectively remove pose channels. - */ void BKE_pose_channels_remove(Object *ob, bool (*filter_fn)(const char *bone_name, void *user_data), void *user_data) @@ -1086,10 +1028,6 @@ void BKE_pose_channels_remove(Object *ob, } } -/** - * Deallocates a pose channel. - * Does not free the pose channel itself. - */ void BKE_pose_channel_free_ex(bPoseChannel *pchan, bool do_id_user) { if (pchan->custom) { @@ -1118,13 +1056,11 @@ void BKE_pose_channel_free_ex(bPoseChannel *pchan, bool do_id_user) BKE_pose_channel_runtime_free(&pchan->runtime); } -/** Clears the runtime cache of a pose channel without free. */ void BKE_pose_channel_runtime_reset(bPoseChannel_Runtime *runtime) { memset(runtime, 0, sizeof(*runtime)); } -/* Reset all non-persistent fields. */ void BKE_pose_channel_runtime_reset_on_copy(bPoseChannel_Runtime *runtime) { const SessionUUID uuid = runtime->session_uuid; @@ -1132,13 +1068,11 @@ void BKE_pose_channel_runtime_reset_on_copy(bPoseChannel_Runtime *runtime) runtime->session_uuid = uuid; } -/** Deallocates runtime cache of a pose channel */ void BKE_pose_channel_runtime_free(bPoseChannel_Runtime *runtime) { BKE_pose_channel_free_bbone_cache(runtime); } -/** Deallocates runtime cache of a pose channel's B-Bone shape. */ void BKE_pose_channel_free_bbone_cache(bPoseChannel_Runtime *runtime) { runtime->bbone_segments = 0; @@ -1153,10 +1087,6 @@ void BKE_pose_channel_free(bPoseChannel *pchan) BKE_pose_channel_free_ex(pchan, true); } -/** - * Removes and deallocates all channels from a pose. - * Does not free the pose itself. - */ void BKE_pose_channels_free_ex(bPose *pose, bool do_id_user) { bPoseChannel *pchan; @@ -1203,9 +1133,6 @@ void BKE_pose_free_data(bPose *pose) BKE_pose_free_data_ex(pose, true); } -/** - * Removes and deallocates all data from a pose, and also frees the pose. - */ void BKE_pose_free_ex(bPose *pose, bool do_id_user) { if (pose) { @@ -1220,13 +1147,6 @@ void BKE_pose_free(bPose *pose) BKE_pose_free_ex(pose, true); } -/** - * Copy the internal members of each pose channel including constraints - * and ID-Props, used when duplicating bones in editmode. - * (unlike copy_pose_channel_data which only does posing-related stuff). - * - * \note use when copying bones in editmode (on returned value from #BKE_pose_channel_ensure) - */ void BKE_pose_channel_copy_data(bPoseChannel *pchan, const bPoseChannel *pchan_from) { /* copy transform locks */ @@ -1276,10 +1196,6 @@ void BKE_pose_channel_copy_data(bPoseChannel *pchan, const bPoseChannel *pchan_f pchan->drawflag = pchan_from->drawflag; } -/* checks for IK constraint, Spline IK, and also for Follow-Path constraint. - * can do more constraints flags later - */ -/* pose should be entirely OK */ void BKE_pose_update_constraint_flags(bPose *pose) { bPoseChannel *pchan, *parchan; @@ -1354,7 +1270,6 @@ void BKE_pose_tag_update_constraint_flags(bPose *pose) /* ************************** Bone Groups ************************** */ -/* Adds a new bone-group (name may be NULL) */ bActionGroup *BKE_pose_add_group(bPose *pose, const char *name) { bActionGroup *grp; @@ -1373,8 +1288,6 @@ bActionGroup *BKE_pose_add_group(bPose *pose, const char *name) return grp; } -/* Remove the given bone-group (expects 'virtual' index (+1 one, used by active_group etc.)) - * index might be invalid ( < 1), in which case it will be find from grp. */ void BKE_pose_remove_group(bPose *pose, bActionGroup *grp, const int index) { bPoseChannel *pchan; @@ -1413,7 +1326,6 @@ void BKE_pose_remove_group(bPose *pose, bActionGroup *grp, const int index) } } -/* Remove the indexed bone-group (expects 'virtual' index (+1 one, used by active_group etc.)) */ void BKE_pose_remove_group_index(bPose *pose, const int index) { bActionGroup *grp = NULL; @@ -1427,7 +1339,6 @@ void BKE_pose_remove_group_index(bPose *pose, const int index) /* ************** F-Curve Utilities for Actions ****************** */ -/* Check if the given action has any keyframes */ bool action_has_motion(const bAction *act) { FCurve *fcu; @@ -1486,7 +1397,6 @@ bool BKE_action_has_single_frame(const struct bAction *act) return found_key; } -/* Calculate the extents of given action */ void calc_action_range(const bAction *act, float *start, float *end, short incl_modifiers) { FCurve *fcu; @@ -1574,8 +1484,6 @@ void calc_action_range(const bAction *act, float *start, float *end, short incl_ } } -/* Retrieve the intended playback frame range, using the manually set range if available, - * or falling back to scanning F-Curves for their first & last frames otherwise. */ void BKE_action_get_frame_range(const struct bAction *act, float *r_start, float *r_end) { if (act && (act->flag & ACT_FRAME_RANGE)) { @@ -1592,15 +1500,11 @@ void BKE_action_get_frame_range(const struct bAction *act, float *r_start, float } } -/* Is the action configured as cyclic. */ bool BKE_action_is_cyclic(const struct bAction *act) { return act && (act->flag & ACT_FRAME_RANGE) && (act->flag & ACT_CYCLIC); } -/* Return flags indicating which transforms the given object/posechannel has - * - if 'curves' is provided, a list of links to these curves are also returned - */ short action_get_item_transforms(bAction *act, Object *ob, bPoseChannel *pchan, ListBase *curves) { PointerRNA ptr; @@ -1731,9 +1635,6 @@ short action_get_item_transforms(bAction *act, Object *ob, bPoseChannel *pchan, /* ************** Pose Management Tools ****************** */ -/** - * Zero the pose transforms for the entire pose or only for selected bones. - */ void BKE_pose_rest(bPose *pose, bool selected_bones_only) { bPoseChannel *pchan; @@ -1798,7 +1699,6 @@ void BKE_pose_copy_pchan_result(bPoseChannel *pchanto, const bPoseChannel *pchan pchanto->protectflag = pchanfrom->protectflag; } -/* both poses should be in sync */ bool BKE_pose_copy_result(bPose *to, bPose *from) { bPoseChannel *pchanto, *pchanfrom; @@ -1823,7 +1723,6 @@ bool BKE_pose_copy_result(bPose *to, bPose *from) return true; } -/* Tag pose for recalc. Also tag all related data to be recalc. */ void BKE_pose_tag_recalc(Main *bmain, bPose *pose) { pose->flag |= POSE_RECALC; @@ -1833,9 +1732,6 @@ void BKE_pose_tag_recalc(Main *bmain, bPose *pose) DEG_relations_tag_update(bmain); } -/* For the calculation of the effects of an Action at the given frame on an object - * This is currently only used for the Action Constraint - */ void what_does_obaction(Object *ob, Object *workob, bPose *pose, diff --git a/source/blender/blenkernel/intern/anim_data.c b/source/blender/blenkernel/intern/anim_data.c index 21887d514d9..d93d5c456d8 100644 --- a/source/blender/blenkernel/intern/anim_data.c +++ b/source/blender/blenkernel/intern/anim_data.c @@ -69,7 +69,6 @@ static CLG_LogRef LOG = {"bke.anim_sys"}; /* Getter/Setter -------------------------------------------- */ -/* Check if ID can have AnimData */ bool id_type_can_have_animdata(const short id_type) { const IDTypeInfo *typeinfo = BKE_idtype_get_info_from_idcode(id_type); @@ -89,9 +88,6 @@ bool id_can_have_animdata(const ID *id) return id_type_can_have_animdata(GS(id->name)); } -/** - * Get #AnimData from the given ID-block. - */ AnimData *BKE_animdata_from_id(ID *id) { /* In order for this to work, we assume that the #AnimData pointer is stored @@ -106,9 +102,6 @@ AnimData *BKE_animdata_from_id(ID *id) return NULL; } -/** - * Ensure #AnimData exists in the given ID-block (when supported). - */ AnimData *BKE_animdata_ensure_id(ID *id) { /* In order for this to work, we assume that the #AnimData pointer is stored @@ -137,16 +130,6 @@ AnimData *BKE_animdata_ensure_id(ID *id) /* Action Setter --------------------------------------- */ -/** - * Called when user tries to change the active action of an #AnimData block - * (via RNA, Outliner, etc.) - * - * \param reports: Can be NULL. - * \param id: The owner of the animation data - * \param act: The Action to set, or NULL to clear. - * - * \return true when the action was successfully updated, false otherwise. - */ bool BKE_animdata_set_action(ReportList *reports, ID *id, bAction *act) { AnimData *adt = BKE_animdata_from_id(id); @@ -226,7 +209,6 @@ bool BKE_animdata_action_ensure_idroot(const ID *owner, bAction *action) /* Freeing -------------------------------------------- */ -/* Free AnimData used by the nominated ID-block, and clear ID-block's AnimData pointer */ void BKE_animdata_free(ID *id, const bool do_id_user) { /* Only some ID-blocks have this info for now, so we cast the @@ -287,10 +269,6 @@ bool BKE_animdata_id_is_animated(const struct ID *id) !BLI_listbase_is_empty(&adt->overrides); } -/** - * Callback used by lib_query to walk over all ID usages (mimics `foreach_id` callback of - * `IDTypeInfo` structure). - */ void BKE_animdata_foreach_id(AnimData *adt, LibraryForeachIDData *data) { LISTBASE_FOREACH (FCurve *, fcu, &adt->drivers) { @@ -309,12 +287,6 @@ void BKE_animdata_foreach_id(AnimData *adt, LibraryForeachIDData *data) /* Copying -------------------------------------------- */ -/** - * Make a copy of the given AnimData - to be used when copying data-blocks. - * \param flag: Control ID pointers management, - * see LIB_ID_CREATE_.../LIB_ID_COPY_... flags in BKE_lib_id.h - * \return The copied animdata. - */ AnimData *BKE_animdata_copy(Main *bmain, AnimData *adt, const int flag) { AnimData *dadt; @@ -367,11 +339,6 @@ AnimData *BKE_animdata_copy(Main *bmain, AnimData *adt, const int flag) return dadt; } -/** - * \param flag: Control ID pointers management, - * see LIB_ID_CREATE_.../LIB_ID_COPY_... flags in BKE_lib_id.h - * \return true is successfully copied. - */ bool BKE_animdata_copy_id(Main *bmain, ID *id_to, ID *id_from, const int flag) { AnimData *adt; @@ -432,7 +399,6 @@ void BKE_animdata_duplicate_id_action(struct Main *bmain, } } -/* Merge copies of the data from the src AnimData into the destination AnimData */ void BKE_animdata_merge_copy( Main *bmain, ID *dst_id, ID *src_id, eAnimData_MergeCopy_Modes action_mode, bool fix_drivers) { @@ -647,12 +613,6 @@ static void animdata_move_drivers_by_basepath(AnimData *srcAdt, } } -/* Transfer the animation data from srcID to dstID where the srcID - * animation data is based off "basepath", creating new AnimData and - * associated data as necessary. - * - * basepaths is a list of AnimationBasePathChange. - */ void BKE_animdata_transfer_by_basepath(Main *bmain, ID *srcID, ID *dstID, ListBase *basepaths) { AnimData *srcAdt = NULL, *dstAdt = NULL; @@ -716,17 +676,6 @@ void BKE_animdata_transfer_by_basepath(Main *bmain, ID *srcID, ID *dstID, ListBa } } -/** - * Temporary wrapper for driver operators for buttons to make it easier to create - * such drivers by rerouting all paths through the active object instead so that - * they will get picked up by the dependency system. - * - * \param C: Context pointer - for getting active data - * \param[in,out] ptr: RNA pointer for property's data-block. - * May be modified as result of path remapping. - * \param prop: RNA definition of property to add for - * \return MEM_alloc'd string representing the path to the property from the given #PointerRNA - */ char *BKE_animdata_driver_path_hack(bContext *C, PointerRNA *ptr, PropertyRNA *prop, @@ -956,14 +905,6 @@ static bool nlastrips_path_rename_fix(ID *owner_id, /* Rename Sub-ID Entities in RNA Paths ----------------------- */ -/* Fix up the given RNA-Path - * - * This is just an external wrapper for the RNA-Path fixing function, - * with input validity checks on top of the basic method. - * - * NOTE: it is assumed that the structure we're replacing is <["><"]> - * i.e. pose.bones["Bone"] - */ char *BKE_animsys_fix_rna_path_rename(ID *owner_id, char *old_path, const char *prefix, @@ -1019,14 +960,6 @@ char *BKE_animsys_fix_rna_path_rename(ID *owner_id, return result; } -/* Fix all RNA_Paths in the given Action, relative to the given ID block - * - * This is just an external wrapper for the F-Curve fixing function, - * with input validity checks on top of the basic method. - * - * NOTE: it is assumed that the structure we're replacing is <["><"]> - * i.e. pose.bones["Bone"] - */ void BKE_action_fix_paths_rename(ID *owner_id, bAction *act, const char *prefix, @@ -1070,10 +1003,6 @@ void BKE_action_fix_paths_rename(ID *owner_id, MEM_freeN(newN); } -/* Fix all RNA-Paths in the AnimData block used by the given ID block - * NOTE: it is assumed that the structure we're replacing is <["><"]> - * i.e. pose.bones["Bone"] - */ void BKE_animdata_fix_paths_rename(ID *owner_id, AnimData *adt, ID *ref_id, @@ -1282,7 +1211,6 @@ void BKE_fcurves_id_cb(ID *id, ID_FCurve_Edit_Callback func, void *user_data) } } -/* apply the given callback function on all F-Curves attached to data in main database */ void BKE_fcurves_main_cb(Main *bmain, ID_FCurve_Edit_Callback func, void *user_data) { /* Wrap F-Curve operation stuff to pass to the general AnimData-level func */ @@ -1294,7 +1222,6 @@ void BKE_fcurves_main_cb(Main *bmain, ID_FCurve_Edit_Callback func, void *user_d /* Whole Database Ops -------------------------------------------- */ -/* apply the given callback function on all data in main database */ void BKE_animdata_main_cb(Main *bmain, ID_AnimData_Edit_Callback func, void *user_data) { ID *id; @@ -1405,10 +1332,6 @@ void BKE_animdata_main_cb(Main *bmain, ID_AnimData_Edit_Callback func, void *use ANIMDATA_IDS_CB(bmain->simulations.first); } -/* Fix all RNA-Paths throughout the database (directly access the Global.main version) - * NOTE: it is assumed that the structure we're replacing is <["><"]> - * i.e. pose.bones["Bone"] - */ void BKE_animdata_fix_paths_rename_all(ID *ref_id, const char *prefix, const char *oldName, @@ -1418,11 +1341,6 @@ void BKE_animdata_fix_paths_rename_all(ID *ref_id, BKE_animdata_fix_paths_rename_all_ex(bmain, ref_id, prefix, oldName, newName, 0, 0, 1); } -/* Fix all RNA-Paths throughout the database - * NOTE: it is assumed that the structure we're replacing is <["><"]> - * i.e. pose.bones["Bone"] - */ -/* TODO: use BKE_animdata_main_cb for looping over all data. */ void BKE_animdata_fix_paths_rename_all_ex(Main *bmain, ID *ref_id, const char *prefix, @@ -1432,6 +1350,7 @@ void BKE_animdata_fix_paths_rename_all_ex(Main *bmain, const int newSubscript, const bool verify_paths) { + /* TODO: use BKE_animdata_main_cb for looping over all data. */ ID *id; diff --git a/source/blender/blenkernel/intern/anim_path.c b/source/blender/blenkernel/intern/anim_path.c index ff94a04e75e..43af55e9b6b 100644 --- a/source/blender/blenkernel/intern/anim_path.c +++ b/source/blender/blenkernel/intern/anim_path.c @@ -230,14 +230,6 @@ static bool binary_search_anim_path(const float *accum_len_arr, } } -/** - * Calculate the deformation implied by the curve path at a given parametric position, - * and returns whether this operation succeeded. - * - * \param ctime: Time is normalized range <0-1>. - * - * \return success. - */ bool BKE_where_on_path(const Object *ob, float ctime, float r_vec[4], diff --git a/source/blender/blenkernel/intern/anim_sys.c b/source/blender/blenkernel/intern/anim_sys.c index cbdcf43c039..b5ea68aaadc 100644 --- a/source/blender/blenkernel/intern/anim_sys.c +++ b/source/blender/blenkernel/intern/anim_sys.c @@ -84,8 +84,6 @@ static CLG_LogRef LOG = {"bke.anim_sys"}; /* Finding Tools --------------------------- */ -/* Find the first path that matches the given criteria */ -/* TODO: do we want some method to perform partial matches too? */ KS_Path *BKE_keyingset_find_path(KeyingSet *ks, ID *id, const char group_name[], @@ -138,8 +136,6 @@ KS_Path *BKE_keyingset_find_path(KeyingSet *ks, /* Defining Tools --------------------------- */ -/* Used to create a new 'custom' KeyingSet for the user, - * that will be automatically added to the stack */ KeyingSet *BKE_keyingset_add( ListBase *list, const char idname[], const char name[], short flag, short keyingflag) { @@ -174,9 +170,6 @@ KeyingSet *BKE_keyingset_add( return ks; } -/* Add a path to a KeyingSet. Nothing is returned for now... - * Checks are performed to ensure that destination is appropriate for the KeyingSet in question - */ KS_Path *BKE_keyingset_add_path(KeyingSet *ks, ID *id, const char group_name[], @@ -240,7 +233,6 @@ KS_Path *BKE_keyingset_add_path(KeyingSet *ks, return ksp; } -/* Free the given Keying Set path */ void BKE_keyingset_free_path(KeyingSet *ks, KS_Path *ksp) { /* sanity check */ @@ -257,7 +249,6 @@ void BKE_keyingset_free_path(KeyingSet *ks, KS_Path *ksp) BLI_freelinkN(&ks->paths, ksp); } -/* Copy all KeyingSets in the given list */ void BKE_keyingsets_copy(ListBase *newlist, const ListBase *list) { KeyingSet *ksn; @@ -276,7 +267,6 @@ void BKE_keyingsets_copy(ListBase *newlist, const ListBase *list) /* Freeing Tools --------------------------- */ -/* Free data for KeyingSet but not set itself */ void BKE_keyingset_free(KeyingSet *ks) { KS_Path *ksp, *kspn; @@ -293,7 +283,6 @@ void BKE_keyingset_free(KeyingSet *ks) } } -/* Free all the KeyingSets in the given list */ void BKE_keyingsets_free(ListBase *list) { KeyingSet *ks, *ksn; @@ -490,7 +479,6 @@ bool BKE_animsys_read_from_rna_path(PathResolvedRNA *anim_rna, float *r_value) return true; } -/* Write the given value to a setting using RNA, and return success */ bool BKE_animsys_write_to_rna_path(PathResolvedRNA *anim_rna, const float value) { PropertyRNA *prop = anim_rna->prop; @@ -831,7 +819,6 @@ static void action_idcode_patch_check(ID *id, bAction *act) /* ----------------------------------------- */ -/* Evaluate Action Group */ void animsys_evaluate_action_group(PointerRNA *ptr, bAction *act, bActionGroup *agrp, @@ -864,7 +851,6 @@ void animsys_evaluate_action_group(PointerRNA *ptr, } } -/* Evaluate Action (F-Curve Bag) */ void animsys_evaluate_action(PointerRNA *ptr, bAction *act, const AnimationEvalContext *anim_eval_context, @@ -881,7 +867,6 @@ void animsys_evaluate_action(PointerRNA *ptr, animsys_evaluate_fcurves(ptr, &act->curves, anim_eval_context, flush_to_original); } -/* Evaluate Action and blend it into the current values of the animated properties. */ void animsys_blend_in_action(PointerRNA *ptr, bAction *act, const AnimationEvalContext *anim_eval_context, @@ -960,7 +945,6 @@ static void nlastrip_evaluate_controls(NlaStrip *strip, } } -/* gets the strip active at the current time for a list of strips for evaluation purposes */ NlaEvalStrip *nlastrips_ctime_get_strip(ListBase *list, ListBase *strips, short index, @@ -2402,7 +2386,6 @@ static void nlastrip_evaluate_meta(PointerRNA *ptr, nlaeval_fmodifiers_split_stacks(&strip->modifiers, modifiers); } -/* evaluates the given evaluation strip */ void nlastrip_evaluate(PointerRNA *ptr, NlaEvalData *channels, ListBase *modifiers, @@ -2447,7 +2430,6 @@ void nlastrip_evaluate(PointerRNA *ptr, strip->flag &= ~NLASTRIP_FLAG_EDIT_TOUCHED; } -/* write the accumulated settings to */ void nladata_flush_channels(PointerRNA *ptr, NlaEvalData *channels, NlaEvalSnapshot *snapshot, @@ -2977,14 +2959,6 @@ void nlasnapshot_ensure_channels(NlaEvalData *eval_data, NlaEvalSnapshot *snapsh } } -/** - * Blends the \a lower_snapshot with the \a upper_snapshot into \a r_blended_snapshot according - * to the given \a upper_blendmode and \a upper_influence. - * - * For \a upper_snapshot, blending limited to values in the \a blend_domain. - * For Replace blend-mode, this allows the upper snapshot to have a location XYZ channel - * where only a subset of values are blended. - */ void nlasnapshot_blend(NlaEvalData *eval_data, NlaEvalSnapshot *lower_snapshot, NlaEvalSnapshot *upper_snapshot, @@ -3012,14 +2986,6 @@ void nlasnapshot_blend(NlaEvalData *eval_data, } } -/** - * Using \a blended_snapshot and \a lower_snapshot, we can solve for the \a r_upper_snapshot. - * - * Only channels that exist within \a blended_snapshot are inverted. - * - * For \a r_upper_snapshot, disables \a NlaEvalChannelSnapshot->remap_domain for failed inversions. - * Only values within the \a remap_domain are processed. - */ void nlasnapshot_blend_get_inverted_upper_snapshot(NlaEvalData *eval_data, NlaEvalSnapshot *lower_snapshot, NlaEvalSnapshot *blended_snapshot, @@ -3050,15 +3016,6 @@ void nlasnapshot_blend_get_inverted_upper_snapshot(NlaEvalData *eval_data, /* ---------------------- */ -/** - * Prepare data necessary to compute correct keyframe values for NLA strips - * with non-Replace mode or influence different from 1. - * - * \param cache: List used to cache contexts for reuse when keying - * multiple channels in one operation. - * \param ptr: RNA pointer to the Object with the animation. - * \return Keyframing context, or NULL if not necessary. - */ NlaKeyframingContext *BKE_animsys_get_nla_keyframing_context( struct ListBase *cache, struct PointerRNA *ptr, @@ -3095,18 +3052,6 @@ NlaKeyframingContext *BKE_animsys_get_nla_keyframing_context( return ctx; } -/** - * Apply correction from the NLA context to the values about to be keyframed. - * - * \param context: Context to use (may be NULL). - * \param prop_ptr: Property about to be keyframed. - * \param[in,out] values: Array of property values to adjust. - * \param count: Number of values in the array. - * \param index: Index of the element about to be updated, or -1. - * \param[out] r_force_all: Set to true if all channels must be inserted. May be NULL. - * \return False if correction fails due to a division by zero, - * or null r_force_all when all channels are required. - */ bool BKE_animsys_nla_remap_keyframe_values(struct NlaKeyframingContext *context, struct PointerRNA *prop_ptr, struct PropertyRNA *prop, @@ -3202,9 +3147,6 @@ bool BKE_animsys_nla_remap_keyframe_values(struct NlaKeyframingContext *context, return successful_remap; } -/** - * Free all cached contexts from the list. - */ void BKE_animsys_free_nla_keyframing_context_cache(struct ListBase *cache) { LISTBASE_FOREACH (NlaKeyframingContext *, ctx, cache) { @@ -3270,12 +3212,6 @@ static void animsys_evaluate_overrides(PointerRNA *ptr, AnimData *adt) * However, the code for this is relatively harmless, so is left in the code for now. */ -/* Evaluation loop for evaluation animation data - * - * This assumes that the animation-data provided belongs to the ID block in question, - * and that the flags for which parts of the anim-data settings need to be recalculated - * have been set already by the depsgraph. Now, we use the recalc - */ void BKE_animsys_evaluate_animdata(ID *id, AnimData *adt, const AnimationEvalContext *anim_eval_context, @@ -3329,13 +3265,6 @@ void BKE_animsys_evaluate_animdata(ID *id, animsys_evaluate_overrides(&id_ptr, adt); } -/* Evaluation of all ID-blocks with Animation Data blocks - Animation Data Only - * - * This will evaluate only the animation info available in the animation data-blocks - * encountered. In order to enforce the system by which some settings controlled by a - * 'local' (i.e. belonging in the nearest ID-block that setting is related to, not a - * standard 'root') block are overridden by a larger 'user' - */ void BKE_animsys_evaluate_all_animation(Main *main, Depsgraph *depsgraph, float ctime) { ID *id; diff --git a/source/blender/blenkernel/intern/anim_visualization.c b/source/blender/blenkernel/intern/anim_visualization.c index 56bd8e769bc..fdea52bcd64 100644 --- a/source/blender/blenkernel/intern/anim_visualization.c +++ b/source/blender/blenkernel/intern/anim_visualization.c @@ -39,7 +39,6 @@ /* ******************************************************************** */ /* Animation Visualization */ -/* Initialize the default settings for animation visualization */ void animviz_settings_init(bAnimVizSettings *avs) { /* sanity check */ @@ -62,7 +61,6 @@ void animviz_settings_init(bAnimVizSettings *avs) /* ------------------- */ -/* Free the given motion path's cache */ void animviz_free_motionpath_cache(bMotionPath *mpath) { /* sanity check */ @@ -84,9 +82,6 @@ void animviz_free_motionpath_cache(bMotionPath *mpath) mpath->length = 0; } -/* Free the given motion path instance and its data - * NOTE: this frees the motion path given! - */ void animviz_free_motionpath(bMotionPath *mpath) { /* sanity check */ @@ -103,7 +98,6 @@ void animviz_free_motionpath(bMotionPath *mpath) /* ------------------- */ -/* Make a copy of motionpath data, so that viewing with copy on write works */ bMotionPath *animviz_copy_motionpath(const bMotionPath *mpath_src) { bMotionPath *mpath_dst; @@ -125,14 +119,6 @@ bMotionPath *animviz_copy_motionpath(const bMotionPath *mpath_src) /* ------------------- */ -/** - * Setup motion paths for the given data. - * \note Only used when explicitly calculating paths on bones which may/may not be consider already - * - * \param scene: Current scene (for frame ranges, etc.) - * \param ob: Object to add paths for (must be provided) - * \param pchan: Posechannel to add paths for (optional; if not provided, object-paths are assumed) - */ bMotionPath *animviz_verify_motionpaths(ReportList *reports, Scene *scene, Object *ob, diff --git a/source/blender/blenkernel/intern/appdir.c b/source/blender/blenkernel/intern/appdir.c index d872dc67dcb..a819459f989 100644 --- a/source/blender/blenkernel/intern/appdir.c +++ b/source/blender/blenkernel/intern/appdir.c @@ -99,15 +99,6 @@ static bool is_appdir_init = false; # define ASSERT_IS_INIT() ((void)0) #endif -/** - * Sanity check to ensure correct API use in debug mode. - * - * Run this once the first level of arguments has been passed so we can be sure - * `--env-system-datafiles`, and other `--env-*` arguments has been passed. - * - * Without this any callers to this module that run early on, - * will miss out on changes from parsing arguments. - */ void BKE_appdir_init(void) { #ifndef NDEBUG @@ -147,14 +138,6 @@ static char *blender_version_decimal(const int version) /** \name Default Directories * \{ */ -/** - * Get the folder that's the "natural" starting point for browsing files on an OS. - * - Unix: `$HOME` - * - Windows: `%userprofile%/Documents` - * - * \note On Windows `Users/{MyUserName}/Documents` is used as it's the default location to save - * documents. - */ const char *BKE_appdir_folder_default(void) { #ifndef WIN32 @@ -190,11 +173,6 @@ const char *BKE_appdir_folder_default_or_root(void) return path; } -/** - * Get the user's home directory, i.e. - * - Unix: `$HOME` - * - Windows: `%userprofile%` - */ const char *BKE_appdir_folder_home(void) { #ifndef WIN32 @@ -204,15 +182,6 @@ const char *BKE_appdir_folder_home(void) #endif } -/** - * Get the user's document directory, i.e. - * - Linux: `$HOME/Documents` - * - Windows: `%userprofile%/Documents` - * - * If this can't be found using OS queries (via Ghost), try manually finding it. - * - * \returns True if the path is valid and points to an existing directory. - */ bool BKE_appdir_folder_documents(char *dir) { dir[0] = '\0'; @@ -243,15 +212,6 @@ bool BKE_appdir_folder_documents(char *dir) return true; } -/** - * Get the user's cache directory, i.e. - * - Linux: `$HOME/.cache/blender/` - * - Windows: `%USERPROFILE%\AppData\Local\Blender Foundation\Blender\` - * - MacOS: `/Library/Caches/Blender` - * - * \returns True if the path is valid. It doesn't create or checks format - * if the `blender` folder exists. It does check if the parent of the path exists. - */ bool BKE_appdir_folder_caches(char *r_path, const size_t path_len) { r_path[0] = '\0'; @@ -276,9 +236,6 @@ bool BKE_appdir_folder_caches(char *r_path, const size_t path_len) return true; } -/** - * Gets a good default directory for fonts. - */ bool BKE_appdir_font_folder_default(char *dir) { char test_dir[FILE_MAXDIR]; @@ -458,10 +415,6 @@ static bool get_path_local(char *targetpath, targetpath, targetpath_len, folder_name, subfolder_name, version, check_is_dir); } -/** - * Check if this is an install with user files kept together - * with the Blender executable and its installation files. - */ bool BKE_appdir_app_is_portable_install(void) { /* Detect portable install by the existence of `config` folder. */ @@ -626,13 +579,6 @@ static bool get_path_system(char *targetpath, /** \name Path Presets API * \{ */ -/** - * Get a folder out of the \a folder_id presets for paths. - * - * \param subfolder: The name of a directory to check for, - * this may contain path separators but must resolve to a directory, checked with #BLI_is_dir. - * \return The path if found, NULL string if not. - */ bool BKE_appdir_folder_id_ex(const int folder_id, const char *subfolder, char *path, @@ -746,9 +692,6 @@ const char *BKE_appdir_folder_id(const int folder_id, const char *subfolder) return NULL; } -/** - * Returns the path to a folder in the user area without checking that it actually exists first. - */ const char *BKE_appdir_folder_id_user_notest(const int folder_id, const char *subfolder) { const int version = BLENDER_VERSION; @@ -795,9 +738,6 @@ const char *BKE_appdir_folder_id_user_notest(const int folder_id, const char *su return path; } -/** - * Returns the path to a folder in the user area, creating it if it doesn't exist. - */ const char *BKE_appdir_folder_id_create(const int folder_id, const char *subfolder) { const char *path; @@ -823,10 +763,6 @@ const char *BKE_appdir_folder_id_create(const int folder_id, const char *subfold return path; } -/** - * Returns the path of the top-level version-specific local, user or system directory. - * If check_is_dir, then the result will be NULL if the directory doesn't exist. - */ const char *BKE_appdir_folder_id_version(const int folder_id, const int version, const bool check_is_dir) @@ -942,18 +878,12 @@ void BKE_appdir_program_path_init(const char *argv0) BLI_split_dir_part(g_app.program_filename, g_app.program_dirname, sizeof(g_app.program_dirname)); } -/** - * Path to executable - */ const char *BKE_appdir_program_path(void) { BLI_assert(g_app.program_filename[0]); return g_app.program_filename; } -/** - * Path to directory of executable - */ const char *BKE_appdir_program_dir(void) { BLI_assert(g_app.program_dirname[0]); @@ -1047,9 +977,6 @@ static const int app_template_directory_id[2] = { BLENDER_SYSTEM_SCRIPTS, }; -/** - * Return true if templates exist - */ bool BKE_appdir_app_template_any(void) { char temp_dir[FILE_MAX]; @@ -1217,14 +1144,13 @@ static void tempdir_session_create(char *tempdir_session, BLI_strncpy(tempdir_session, tempdir, tempdir_session_len); } -/** - * Sets #g_app.temp_dirname_base to \a userdir if specified and is a valid directory, - * otherwise chooses a suitable OS-specific temporary directory. - * Sets #g_app.temp_dirname_session to a #mkdtemp - * generated sub-dir of #g_app.temp_dirname_base. - */ void BKE_tempdir_init(const char *userdir) { + /* Sets #g_app.temp_dirname_base to \a userdir if specified and is a valid directory, + * otherwise chooses a suitable OS-specific temporary directory. + * Sets #g_app.temp_dirname_session to a #mkdtemp + * generated sub-dir of #g_app.temp_dirname_base. */ + where_is_temp(g_app.temp_dirname_base, sizeof(g_app.temp_dirname_base), userdir); /* Clear existing temp dir, if needed. */ @@ -1234,25 +1160,16 @@ void BKE_tempdir_init(const char *userdir) g_app.temp_dirname_session, sizeof(g_app.temp_dirname_session), g_app.temp_dirname_base); } -/** - * Path to temporary directory (with trailing slash) - */ const char *BKE_tempdir_session(void) { return g_app.temp_dirname_session[0] ? g_app.temp_dirname_session : BKE_tempdir_base(); } -/** - * Path to persistent temporary directory (with trailing slash) - */ const char *BKE_tempdir_base(void) { return g_app.temp_dirname_base; } -/** - * Delete content of this instance's temp dir. - */ void BKE_tempdir_session_purge(void) { if (g_app.temp_dirname_session[0] && BLI_is_dir(g_app.temp_dirname_session)) { diff --git a/source/blender/blenkernel/intern/armature.c b/source/blender/blenkernel/intern/armature.c index 96524ce78d7..0a91d662c1b 100644 --- a/source/blender/blenkernel/intern/armature.c +++ b/source/blender/blenkernel/intern/armature.c @@ -609,10 +609,6 @@ static Bone *get_named_bone_bonechildren(ListBase *lb, const char *name) return NULL; } -/** - * Walk the list until the bone is found (slow!), - * use #BKE_armature_bone_from_name_map for multiple lookups. - */ Bone *BKE_armature_find_bone_name(bArmature *arm, const char *name) { if (!arm) { @@ -717,10 +713,6 @@ void BKE_armature_refresh_layer_used(struct Depsgraph *depsgraph, struct bArmatu /** \name Armature Layer Refresh Used * \{ */ -/* Finds the best possible extension to the name on a particular axis. (For renaming, check for - * unique names afterwards) strip_number: removes number extensions (TODO: not used) - * axis: the axis to name on - * head/tail: the head/tail co-ordinate of the bone on the specified axis */ bool bone_autoside_name( char name[MAXBONENAME], int UNUSED(strip_number), short axis, float head, float tail) { @@ -932,7 +924,6 @@ static void evaluate_cubic_bezier(const float control[4][3], madd_v3_v3v3fl(r_pos, layer2[0], r_tangent, t); } -/* Get "next" and "prev" bones - these are used for handle calculations. */ void BKE_pchan_bbone_handles_get(bPoseChannel *pchan, bPoseChannel **r_prev, bPoseChannel **r_next) { if (pchan->bone->bbone_prev_type == BBONE_HANDLE_AUTO) { @@ -959,7 +950,6 @@ void BKE_pchan_bbone_handles_get(bPoseChannel *pchan, bPoseChannel **r_prev, bPo } } -/* Compute B-Bone spline parameters for the given channel. */ void BKE_pchan_bbone_spline_params_get(struct bPoseChannel *pchan, const bool rest, struct BBoneSplineParameters *param) @@ -1205,8 +1195,6 @@ void BKE_pchan_bbone_spline_params_get(struct bPoseChannel *pchan, } } -/* Fills the array with the desired amount of bone->segments elements. - * This calculation is done within unit bone space. */ void BKE_pchan_bbone_spline_setup(bPoseChannel *pchan, const bool rest, const bool for_deform, @@ -1219,7 +1207,6 @@ void BKE_pchan_bbone_spline_setup(bPoseChannel *pchan, pchan->bone->segments = BKE_pchan_bbone_spline_compute(¶m, for_deform, result_array); } -/* Computes the bezier handle vectors and rolls coming from custom handles. */ void BKE_pchan_bbone_handles_compute(const BBoneSplineParameters *param, float h1[3], float *r_roll1, @@ -1377,8 +1364,6 @@ static void ease_handle_axis(const float deriv1[3], const float deriv2[3], float } } -/* Fills the array with the desired amount of bone->segments elements. - * This calculation is done within unit bone space. */ int BKE_pchan_bbone_spline_compute(BBoneSplineParameters *param, const bool for_deform, Mat4 *result_array) @@ -1513,7 +1498,6 @@ static void allocate_bbone_cache(bPoseChannel *pchan, int segments) } } -/** Compute and cache the B-Bone shape in the channel runtime struct. */ void BKE_pchan_bbone_segments_cache_compute(bPoseChannel *pchan) { bPoseChannel_Runtime *runtime = &pchan->runtime; @@ -1565,7 +1549,6 @@ void BKE_pchan_bbone_segments_cache_compute(bPoseChannel *pchan) } } -/** Copy cached B-Bone segments from one channel to another */ void BKE_pchan_bbone_segments_cache_copy(bPoseChannel *pchan, bPoseChannel *pchan_from) { bPoseChannel_Runtime *runtime = &pchan->runtime; @@ -1589,10 +1572,6 @@ void BKE_pchan_bbone_segments_cache_copy(bPoseChannel *pchan, bPoseChannel *pcha } } -/** - * Calculate index and blend factor for the two B-Bone segment nodes - * affecting the point at 0 <= pos <= 1. - */ void BKE_pchan_bbone_deform_segment_index(const bPoseChannel *pchan, float pos, int *r_index, @@ -1624,7 +1603,6 @@ void BKE_pchan_bbone_deform_segment_index(const bPoseChannel *pchan, /** \name Bone Space to Space Conversion API * \{ */ -/* Convert World-Space Matrix to Pose-Space Matrix */ void BKE_armature_mat_world_to_pose(Object *ob, const float inmat[4][4], float outmat[4][4]) { float obmat[4][4]; @@ -1641,9 +1619,6 @@ void BKE_armature_mat_world_to_pose(Object *ob, const float inmat[4][4], float o mul_m4_m4m4(outmat, inmat, obmat); } -/* Convert World-Space Location to Pose-Space Location - * NOTE: this cannot be used to convert to pose-space location of the supplied - * pose-channel into its local space (i.e. 'visual'-keyframing) */ void BKE_armature_loc_world_to_pose(Object *ob, const float inloc[3], float outloc[3]) { float xLocMat[4][4]; @@ -1664,8 +1639,6 @@ void BKE_armature_loc_world_to_pose(Object *ob, const float inloc[3], float outl /** \name Bone Matrix Calculation API * \{ */ -/* Simple helper, computes the offset bone matrix. - * offs_bone = yoffs(b-1) + root(b) + bonemat(b). */ void BKE_bone_offset_matrix_get(const Bone *bone, float offs_bone[4][4]) { BLI_assert(bone->parent != NULL); @@ -1680,24 +1653,6 @@ void BKE_bone_offset_matrix_get(const Bone *bone, float offs_bone[4][4]) offs_bone[3][1] += bone->parent->length; } -/* Construct the matrices (rot/scale and loc) - * to apply the PoseChannels into the armature (object) space. - * I.e. (roughly) the "pose_mat(b-1) * yoffs(b-1) * d_root(b) * bone_mat(b)" in the - * pose_mat(b)= pose_mat(b-1) * yoffs(b-1) * d_root(b) * bone_mat(b) * chan_mat(b) - * ...function. - * - * This allows to get the transformations of a bone in its object space, - * *before* constraints (and IK) get applied (used by pose evaluation code). - * And reverse: to find pchan transformations needed to place a bone at a given loc/rot/scale - * in object space (used by interactive transform, and snapping code). - * - * Note that, with the HINGE/NO_SCALE/NO_LOCAL_LOCATION options, the location matrix - * will differ from the rotation/scale matrix... - * - * NOTE: This cannot be used to convert to pose-space transforms of the supplied - * pose-channel into its local space (i.e. 'visual'-keyframing). - * (note: I don't understand that, so I keep it :p --mont29). - */ void BKE_bone_parent_transform_calc_from_pchan(const bPoseChannel *pchan, BoneParentTransform *r_bpt) { @@ -1727,12 +1682,6 @@ void BKE_bone_parent_transform_calc_from_pchan(const bPoseChannel *pchan, } } -/* Compute the parent transform using data decoupled from specific data structures. - * - * bone_flag: Bone->flag containing settings - * offs_bone: delta from parent to current arm_mat (or just arm_mat if no parent) - * parent_arm_mat, parent_pose_mat: arm_mat and pose_mat of parent, or NULL - * r_bpt: OUTPUT parent transform */ void BKE_bone_parent_transform_calc_from_matrices(int bone_flag, int inherit_scale_mode, const float offs_bone[4][4], @@ -1914,9 +1863,6 @@ void BKE_bone_parent_transform_apply(const struct BoneParentTransform *bpt, rescale_m4(outmat, bpt->post_scale); } -/* Convert Pose-Space Matrix to Bone-Space Matrix. - * NOTE: this cannot be used to convert to pose-space transforms of the supplied - * pose-channel into its local space (i.e. 'visual'-keyframing) */ void BKE_armature_mat_pose_to_bone(bPoseChannel *pchan, const float inmat[4][4], float outmat[4][4]) @@ -1928,7 +1874,6 @@ void BKE_armature_mat_pose_to_bone(bPoseChannel *pchan, BKE_bone_parent_transform_apply(&bpt, inmat, outmat); } -/* Convert Bone-Space Matrix to Pose-Space Matrix. */ void BKE_armature_mat_bone_to_pose(bPoseChannel *pchan, const float inmat[4][4], float outmat[4][4]) @@ -1939,9 +1884,6 @@ void BKE_armature_mat_bone_to_pose(bPoseChannel *pchan, BKE_bone_parent_transform_apply(&bpt, inmat, outmat); } -/* Convert Pose-Space Location to Bone-Space Location - * NOTE: this cannot be used to convert to pose-space location of the supplied - * pose-channel into its local space (i.e. 'visual'-keyframing) */ void BKE_armature_loc_pose_to_bone(bPoseChannel *pchan, const float inloc[3], float outloc[3]) { float xLocMat[4][4]; @@ -1984,9 +1926,6 @@ void BKE_armature_mat_pose_to_bone_ex(struct Depsgraph *depsgraph, BKE_armature_mat_pose_to_bone(&work_pchan, inmat, outmat); } -/** - * Same as #BKE_object_mat3_to_rot(). - */ void BKE_pchan_mat3_to_rot(bPoseChannel *pchan, const float mat[3][3], bool use_compat) { BLI_ASSERT_UNIT_M3(mat); @@ -2009,9 +1948,6 @@ void BKE_pchan_mat3_to_rot(bPoseChannel *pchan, const float mat[3][3], bool use_ } } -/** - * Same as #BKE_object_rot_to_mat3(). - */ void BKE_pchan_rot_to_mat3(const bPoseChannel *pchan, float r_mat[3][3]) { /* rotations may either be quats, eulers (with various rotation orders), or axis-angle */ @@ -2036,10 +1972,6 @@ void BKE_pchan_rot_to_mat3(const bPoseChannel *pchan, float r_mat[3][3]) } } -/** - * Apply a 4x4 matrix to the pose bone, - * similar to #BKE_object_apply_mat4(). - */ void BKE_pchan_apply_mat4(bPoseChannel *pchan, const float mat[4][4], bool use_compat) { float rot[3][3]; @@ -2047,11 +1979,6 @@ void BKE_pchan_apply_mat4(bPoseChannel *pchan, const float mat[4][4], bool use_c BKE_pchan_mat3_to_rot(pchan, rot, use_compat); } -/** - * Remove rest-position effects from pose-transform for obtaining - * 'visual' transformation of pose-channel. - * (used by the Visual-Keyframing stuff). - */ void BKE_armature_mat_pose_to_delta(float delta_mat[4][4], float pose_mat[4][4], float arm_mat[4][4]) @@ -2070,11 +1997,6 @@ void BKE_armature_mat_pose_to_delta(float delta_mat[4][4], * Used for Objects and Pose Channels, since both can have multiple rotation representations. * \{ */ -/** - * Called from RNA when rotation mode changes - * - the result should be that the rotations given in the provided pointers have had conversions - * applied (as appropriate), such that the rotation of the element hasn't 'visually' changed. - */ void BKE_rotMode_change_values( float quat[4], float eul[3], float axis[3], float *angle, short oldMode, short newMode) { @@ -2148,8 +2070,6 @@ void BKE_rotMode_change_values( * * \{ */ -/* Computes vector and roll based on a rotation. - * "mat" must contain only a rotation, and no scaling. */ void mat3_to_vec_roll(const float mat[3][3], float r_vec[3], float *r_roll) { if (r_vec) { @@ -2161,8 +2081,6 @@ void mat3_to_vec_roll(const float mat[3][3], float r_vec[3], float *r_roll) } } -/* Computes roll around the vector that best approximates the matrix. - * If vec is the Y vector from purely rotational mat, result should be exact. */ void mat3_vec_to_roll(const float mat[3][3], const float vec[3], float *r_roll) { float vecmat[3][3], vecmatinv[3][3], rollmat[3][3], q[4]; @@ -2178,79 +2096,6 @@ void mat3_vec_to_roll(const float mat[3][3], const float vec[3], float *r_roll) *r_roll = quat_split_swing_and_twist(q, 1, NULL, NULL); } -/* Calculates the rest matrix of a bone based on its vector and a roll around that vector. */ -/** - * Given `v = (v.x, v.y, v.z)` our (normalized) bone vector, we want the rotation matrix M - * from the Y axis (so that `M * (0, 1, 0) = v`). - * - The rotation axis a lays on XZ plane, and it is orthonormal to v, - * hence to the projection of v onto XZ plane. - * - `a = (v.z, 0, -v.x)` - * - * We know a is eigenvector of M (so M * a = a). - * Finally, we have w, such that M * w = (0, 1, 0) - * (i.e. the vector that will be aligned with Y axis once transformed). - * We know w is symmetric to v by the Y axis. - * - `w = (-v.x, v.y, -v.z)` - * - * Solving this, we get (x, y and z being the components of v): - * 
- *     ┌ (x^2 * y + z^2) / (x^2 + z^2),   x,   x * z * (y - 1) / (x^2 + z^2) ┐
- * M = │  x * (y^2 - 1)  / (x^2 + z^2),   y,    z * (y^2 - 1)  / (x^2 + z^2) │
- *     └ x * z * (y - 1) / (x^2 + z^2),   z,   (x^2 + z^2 * y) / (x^2 + z^2) ┘
- *
- * - * This is stable as long as v (the bone) is not too much aligned with +/-Y - * (i.e. x and z components are not too close to 0). - * - * Since v is normalized, we have `x^2 + y^2 + z^2 = 1`, - * hence `x^2 + z^2 = 1 - y^2 = (1 - y)(1 + y)`. - * - * This allows to simplifies M like this: - * 
- *     ┌ 1 - x^2 / (1 + y),   x,     -x * z / (1 + y) ┐
- * M = │                -x,   y,                   -z │
- *     └  -x * z / (1 + y),   z,    1 - z^2 / (1 + y) ┘
- *
- * - * Written this way, we see the case v = +Y is no more a singularity. - * The only one - * remaining is the bone being aligned with -Y. - * - * Let's handle - * the asymptotic behavior when bone vector is reaching the limit of y = -1. - * Each of the four corner elements can vary from -1 to 1, - * depending on the axis a chosen for doing the rotation. - * And the "rotation" here is in fact established by mirroring XZ plane by that given axis, - * then inversing the Y-axis. - * For sufficiently small x and z, and with y approaching -1, - * all elements but the four corner ones of M will degenerate. - * So let's now focus on these corner elements. - * - * We rewrite M so that it only contains its four corner elements, - * and combine the `1 / (1 + y)` factor: - * 
- *                    ┌ 1 + y - x^2,        -x * z ┐
- * M* = 1 / (1 + y) * │                            │
- *                    └      -x * z,   1 + y - z^2 ┘
- *
- * - * When y is close to -1, computing 1 / (1 + y) will cause severe numerical instability, - * so we use a different approach based on x and z as inputs. - * We know `y^2 = 1 - (x^2 + z^2)`, and `y < 0`, hence `y = -sqrt(1 - (x^2 + z^2))`. - * - * Since x and z are both close to 0, we apply the binomial expansion to the second order: - * `y = -sqrt(1 - (x^2 + z^2)) = -1 + (x^2 + z^2) / 2 + (x^2 + z^2)^2 / 8`, which allows - * eliminating the problematic `1` constant. - * - * A first order expansion allows simplifying to this, but second order is more precise: - * 
- *                        ┌  z^2 - x^2,  -2 * x * z ┐
- * M* = 1 / (x^2 + z^2) * │                         │
- *                        └ -2 * x * z,   x^2 - z^2 ┘
- *
- * - * P.S. In the end, this basically is a heavily optimized version of Damped Track +Y. - */ void vec_roll_to_mat3_normalized(const float nor[3], const float roll, float r_mat[3][3]) { const float SAFE_THRESHOLD = 6.1e-3f; /* Theta above this value has good enough precision. */ @@ -2321,10 +2166,6 @@ void vec_roll_to_mat3(const float vec[3], const float roll, float r_mat[3][3]) /** \name Armature Bone Matrix Calculation (Recursive) * \{ */ -/** - * Recursive part, calculates rest-position of entire tree of children. - * \note Used when exiting edit-mode too. - */ void BKE_armature_where_is_bone(Bone *bone, const Bone *bone_parent, const bool use_recursion) { float vec[3]; @@ -2363,8 +2204,6 @@ void BKE_armature_where_is_bone(Bone *bone, const Bone *bone_parent, const bool } } -/* updates vectors and matrices on rest-position level, only needed - * after editing armature itself, now only on reading file */ void BKE_armature_where_is(bArmature *arm) { Bone *bone; @@ -2581,10 +2420,6 @@ static int rebuild_pose_bone( return counter; } -/** - * Clear pointers of object's pose - * (needed in remap case, since we cannot always wait for a complete pose rebuild). - */ void BKE_pose_clear_pointers(bPose *pose) { LISTBASE_FOREACH (bPoseChannel *, pchan, &pose->chanbase) { @@ -2606,7 +2441,6 @@ static bPoseChannel *pose_channel_find_bone(bPose *pose, Bone *bone) return (bone != NULL) ? BKE_pose_channel_find_name(pose, bone->name) : NULL; } -/** Update the links for the B-Bone handles from Bone data. */ void BKE_pchan_rebuild_bbone_handles(bPose *pose, bPoseChannel *pchan) { pchan->bbone_prev = pose_channel_find_bone(pose, pchan->bone->bbone_prev); @@ -2624,13 +2458,6 @@ void BKE_pose_channels_clear_with_null_bone(bPose *pose, const bool do_id_user) } } -/** - * Only after leave editmode, duplicating, validating older files, library syncing. - * - * \note pose->flag is set for it. - * - * \param bmain: May be NULL, only used to tag depsgraph as being dirty... - */ void BKE_pose_rebuild(Main *bmain, Object *ob, bArmature *arm, const bool do_id_user) { Bone *bone; @@ -2698,11 +2525,6 @@ void BKE_pose_rebuild(Main *bmain, Object *ob, bArmature *arm, const bool do_id_ } } -/** - * Ensures object's pose is rebuilt if needed. - * - * \param bmain: May be NULL, only used to tag depsgraph as being dirty... - */ void BKE_pose_ensure(Main *bmain, Object *ob, bArmature *arm, const bool do_id_user) { BLI_assert(!ELEM(NULL, arm, ob)); @@ -2718,9 +2540,6 @@ void BKE_pose_ensure(Main *bmain, Object *ob, bArmature *arm, const bool do_id_u /** \name Pose Solver * \{ */ -/** - * Convert the loc/rot/size to \a r_chanmat (typically #bPoseChannel.chan_mat). - */ void BKE_pchan_to_mat4(const bPoseChannel *pchan, float r_chanmat[4][4]) { float smat[3][3]; @@ -2744,8 +2563,6 @@ void BKE_pchan_to_mat4(const bPoseChannel *pchan, float r_chanmat[4][4]) } } -/* loc/rot/size to mat4 */ -/* used in constraint.c too */ void BKE_pchan_calc_mat(bPoseChannel *pchan) { /* this is just a wrapper around the copy of this function which calculates the matrix @@ -2754,7 +2571,6 @@ void BKE_pchan_calc_mat(bPoseChannel *pchan) BKE_pchan_to_mat4(pchan, pchan->chan_mat); } -/* calculate tail of posechannel */ void BKE_pose_where_is_bone_tail(bPoseChannel *pchan) { float vec[3]; @@ -2764,10 +2580,6 @@ void BKE_pose_where_is_bone_tail(bPoseChannel *pchan) add_v3_v3v3(pchan->pose_tail, pchan->pose_head, vec); } -/* The main armature solver, does all constraints excluding IK */ -/* pchan is validated, as having bone and parent pointer - * 'do_extra': when zero skips loc/size/rot, constraints and strip modifiers. - */ void BKE_pose_where_is_bone(struct Depsgraph *depsgraph, Scene *scene, Object *ob, @@ -2832,8 +2644,6 @@ void BKE_pose_where_is_bone(struct Depsgraph *depsgraph, BKE_pose_where_is_bone_tail(pchan); } -/* This only reads anim data from channels, and writes to channels */ -/* This is the only function adding poses */ void BKE_pose_where_is(struct Depsgraph *depsgraph, Scene *scene, Object *ob) { bArmature *arm; diff --git a/source/blender/blenkernel/intern/armature_deform.c b/source/blender/blenkernel/intern/armature_deform.c index 5f721b49361..a8e74f6b4c3 100644 --- a/source/blender/blenkernel/intern/armature_deform.c +++ b/source/blender/blenkernel/intern/armature_deform.c @@ -121,7 +121,6 @@ static void b_bone_deform(const bPoseChannel *pchan, &quats[index + 1], mats[index + 2].mat, co, weight * blend, vec, dq, defmat); } -/* using vec with dist to bone b1 - b2 */ float distfactor_to_bone( const float vec[3], const float b1[3], const float b2[3], float rad1, float rad2, float rdist) { diff --git a/source/blender/blenkernel/intern/asset.cc b/source/blender/blenkernel/intern/asset.cc index 59e402b6680..eaf06c99f17 100644 --- a/source/blender/blenkernel/intern/asset.cc +++ b/source/blender/blenkernel/intern/asset.cc @@ -78,9 +78,6 @@ AssetTag *BKE_asset_metadata_tag_add(AssetMetaData *asset_data, const char *name return tag; } -/** - * Make sure there is a tag with name \a name, create one if needed. - */ struct AssetTagEnsureResult BKE_asset_metadata_tag_ensure(AssetMetaData *asset_data, const char *name) { diff --git a/source/blender/blenkernel/intern/asset_catalog.cc b/source/blender/blenkernel/intern/asset_catalog.cc index 9ef66d23aea..aec622bb71f 100644 --- a/source/blender/blenkernel/intern/asset_catalog.cc +++ b/source/blender/blenkernel/intern/asset_catalog.cc @@ -36,12 +36,7 @@ namespace blender::bke { const CatalogFilePath AssetCatalogService::DEFAULT_CATALOG_FILENAME = "blender_assets.cats.txt"; -/* For now this is the only version of the catalog definition files that is supported. - * Later versioning code may be added to handle older files. */ const int AssetCatalogDefinitionFile::SUPPORTED_VERSION = 1; -/* String that's matched in the catalog definition file to know that the line is the version - * declaration. It has to start with a space to ensure it won't match any hypothetical future field - * that starts with "VERSION". */ const std::string AssetCatalogDefinitionFile::VERSION_MARKER = "VERSION "; const std::string AssetCatalogDefinitionFile::HEADER = diff --git a/source/blender/blenkernel/intern/asset_catalog_path.cc b/source/blender/blenkernel/intern/asset_catalog_path.cc index 20cac76b40b..d789150dba5 100644 --- a/source/blender/blenkernel/intern/asset_catalog_path.cc +++ b/source/blender/blenkernel/intern/asset_catalog_path.cc @@ -74,8 +74,6 @@ StringRefNull AssetCatalogPath::name() const return StringRefNull(this->path_.c_str() + last_sep_index + 1); } -/* In-class operators, because of the implicit `AssetCatalogPath(StringRef)` constructor. - * Otherwise `string == string` could cast both sides to `AssetCatalogPath`. */ bool AssetCatalogPath::operator==(const AssetCatalogPath &other_path) const { return this->path_ == other_path.path_; diff --git a/source/blender/blenkernel/intern/asset_library_service.cc b/source/blender/blenkernel/intern/asset_library_service.cc index d202d6462cf..6b3f1fa3408 100644 --- a/source/blender/blenkernel/intern/asset_library_service.cc +++ b/source/blender/blenkernel/intern/asset_library_service.cc @@ -125,9 +125,6 @@ static void on_blendfile_load(struct Main * /*bMain*/, AssetLibraryService::destroy(); } -/** - * Ensure the AssetLibraryService instance is destroyed before a new blend file is loaded. - * This makes memory management simple, and ensures a fresh start for every blend file. */ void AssetLibraryService::app_handler_register() { /* The callback system doesn't own `on_load_callback_store_`. */ diff --git a/source/blender/blenkernel/intern/attribute_access.cc b/source/blender/blenkernel/intern/attribute_access.cc index fe32279c431..d510a405b46 100644 --- a/source/blender/blenkernel/intern/attribute_access.cc +++ b/source/blender/blenkernel/intern/attribute_access.cc @@ -183,10 +183,6 @@ static int attribute_domain_priority(const AttributeDomain domain) } } -/** - * Domains with a higher "information density" have a higher priority, in order - * to choose a domain that will not lose data through domain conversion. - */ AttributeDomain attribute_domain_highest_priority(Span domains) { int highest_priority = INT_MIN; @@ -754,11 +750,6 @@ std::optional CustomDataAttributes::get_for_read(const AttributeIDRef &at return {}; } -/** - * Return a virtual array for a stored attribute, or a single value virtual array with the default - * value if the attribute doesn't exist. If no default value is provided, the default value for the - * type will be used. - */ GVArray CustomDataAttributes::get_for_read(const AttributeIDRef &attribute_id, const CustomDataType data_type, const void *default_value) const @@ -1057,10 +1048,6 @@ Set GeometryComponent::attribute_ids() const return attributes; } -/** - * \return False if the callback explicitly returned false at any point, otherwise true, - * meaning the callback made it all the way through. - */ bool GeometryComponent::attribute_foreach(const AttributeForeachCallback callback) const { using namespace blender::bke; diff --git a/source/blender/blenkernel/intern/autoexec.c b/source/blender/blenkernel/intern/autoexec.c index 3aec646b024..ed2b4e4ab1b 100644 --- a/source/blender/blenkernel/intern/autoexec.c +++ b/source/blender/blenkernel/intern/autoexec.c @@ -36,10 +36,6 @@ #include "BKE_autoexec.h" /* own include */ -/** - * \param path: The path to check against. - * \return Success - */ bool BKE_autoexec_match(const char *path) { bPathCompare *path_cmp; diff --git a/source/blender/blenkernel/intern/blender.c b/source/blender/blenkernel/intern/blender.c index fb65a9bec7e..b914b0cdf66 100644 --- a/source/blender/blenkernel/intern/blender.c +++ b/source/blender/blenkernel/intern/blender.c @@ -71,7 +71,6 @@ UserDef U; /** \name Blender Free on Exit * \{ */ -/* only to be called on exit blender */ void BKE_blender_free(void) { /* samples are in a global list..., also sets G_MAIN->sound->sample NULL */ @@ -272,10 +271,6 @@ static void userdef_free_addons(UserDef *userdef) BLI_listbase_clear(&userdef->addons); } -/** - * When loading a new userdef from file, - * or when exiting Blender. - */ void BKE_blender_userdef_data_free(UserDef *userdef, bool clear_fonts) { #define U BLI_STATIC_ASSERT(false, "Global 'U' not allowed, only use arguments passed in!") @@ -310,10 +305,6 @@ void BKE_blender_userdef_data_free(UserDef *userdef, bool clear_fonts) /** \name Blender Preferences (Application Templates) * \{ */ -/** - * Write U from userdef. - * This function defines which settings a template will override for the user preferences. - */ void BKE_blender_userdef_app_template_data_swap(UserDef *userdef_a, UserDef *userdef_b) { /* TODO: diff --git a/source/blender/blenkernel/intern/blender_copybuffer.c b/source/blender/blenkernel/intern/blender_copybuffer.c index f21c09d0adf..211d7f693d4 100644 --- a/source/blender/blenkernel/intern/blender_copybuffer.c +++ b/source/blender/blenkernel/intern/blender_copybuffer.c @@ -58,25 +58,16 @@ /** \name Copy/Paste `.blend`, partial saves. * \{ */ -/** Initialize a copy operation. */ void BKE_copybuffer_copy_begin(Main *bmain_src) { BKE_blendfile_write_partial_begin(bmain_src); } -/** Mark an ID to be copied. Should only be called after a call to #BKE_copybuffer_copy_begin. */ void BKE_copybuffer_copy_tag_ID(ID *id) { BKE_blendfile_write_partial_tag_ID(id, true); } -/** - * Finalize a copy operation into given .blend file 'buffer'. - * - * \param filename: Full path to the .blend file used as copy/paste buffer. - * - * \return true on success, false otherwise. - */ bool BKE_copybuffer_copy_end(Main *bmain_src, const char *filename, ReportList *reports) { const int write_flags = 0; @@ -114,16 +105,6 @@ static void copybuffer_append(BlendfileLinkAppendContext *lapp_context, DEG_relations_tag_update(bmain); } -/** - * Paste datablocks from the given .blend file 'buffer' (i.e. append them). - * - * Unlike #BKE_copybuffer_paste, it does not perform any instantiation of collections/objects/etc. - * - * \param libname: Full path to the .blend file used as copy/paste buffer. - * \param id_types_mask: Only directly link IDs of those types from the given .blend file buffer. - * - * \return true on success, false otherwise. - */ bool BKE_copybuffer_read(Main *bmain_dst, const char *libname, ReportList *reports, @@ -153,20 +134,6 @@ bool BKE_copybuffer_read(Main *bmain_dst, return true; } -/** - * Paste datablocks from the given .blend file 'buffer' (i.e. append them). - * - * Similar to #BKE_copybuffer_read, but also handles instantiation of collections/objects/etc. - * - * \param libname: Full path to the .blend file used as copy/paste buffer. - * \param flag: A combination of #eBLOLibLinkFlags and ##eFileSel_Params_Flag to control - * link/append behavior. - * \note: Ignores #FILE_LINK flag, since it always appends IDs. - * \param id_types_mask: Only directly link IDs of those types from the given .blend file buffer. - * - * \return Number of IDs directly pasted from the buffer (does not includes indirectly linked - * ones). - */ int BKE_copybuffer_paste(bContext *C, const char *libname, const int flag, diff --git a/source/blender/blenkernel/intern/blendfile.c b/source/blender/blenkernel/intern/blendfile.c index dbc418c141c..5ba25d603b8 100644 --- a/source/blender/blenkernel/intern/blendfile.c +++ b/source/blender/blenkernel/intern/blendfile.c @@ -452,14 +452,6 @@ static void handle_subversion_warning(Main *main, BlendFileReadReport *reports) } } -/** - * Shared setup function that makes the data from `bfd` into the current blend file, - * replacing the contents of #G.main. - * This uses the bfd #BKE_blendfile_read and similarly named functions. - * - * This is done in a separate step so the caller may perform actions after it is known the file - * loaded correctly but before the file replaces the existing blend file contents. - */ void BKE_blendfile_read_setup_ex(bContext *C, BlendFileData *bfd, const struct BlendFileReadParams *params, @@ -485,9 +477,6 @@ void BKE_blendfile_read_setup(bContext *C, BKE_blendfile_read_setup_ex(C, bfd, params, reports, false, NULL); } -/** - * \return Blend file data, this must be passed to #BKE_blendfile_read_setup when non-NULL. - */ struct BlendFileData *BKE_blendfile_read(const char *filepath, const struct BlendFileReadParams *params, BlendFileReadReport *reports) @@ -507,9 +496,6 @@ struct BlendFileData *BKE_blendfile_read(const char *filepath, return bfd; } -/** - * \return Blend file data, this must be passed to #BKE_blendfile_read_setup when non-NULL. - */ struct BlendFileData *BKE_blendfile_read_from_memory(const void *filebuf, int filelength, const struct BlendFileReadParams *params, @@ -525,10 +511,6 @@ struct BlendFileData *BKE_blendfile_read_from_memory(const void *filebuf, return bfd; } -/** - * \return Blend file data, this must be passed to #BKE_blendfile_read_setup when non-NULL. - * \note `memfile` is the undo buffer. - */ struct BlendFileData *BKE_blendfile_read_from_memfile(Main *bmain, struct MemFile *memfile, const struct BlendFileReadParams *params, @@ -551,10 +533,6 @@ struct BlendFileData *BKE_blendfile_read_from_memfile(Main *bmain, return bfd; } -/** - * Utility to make a file 'empty' used for startup to optionally give an empty file. - * Handy for tests. - */ void BKE_blendfile_read_make_empty(bContext *C) { Main *bmain = CTX_data_main(C); @@ -573,7 +551,6 @@ void BKE_blendfile_read_make_empty(bContext *C) FOREACH_MAIN_LISTBASE_END; } -/* only read the userdef from a .blend */ UserDef *BKE_blendfile_userdef_read(const char *filepath, ReportList *reports) { BlendFileData *bfd; @@ -676,10 +653,6 @@ UserDef *BKE_blendfile_userdef_from_defaults(void) return userdef; } -/** - * Only write the userdef in a .blend - * \return success - */ bool BKE_blendfile_userdef_write(const char *filepath, ReportList *reports) { Main *mainb = MEM_callocN(sizeof(Main), "empty main"); @@ -700,13 +673,6 @@ bool BKE_blendfile_userdef_write(const char *filepath, ReportList *reports) return ok; } -/** - * Only write the userdef in a .blend, merging with the existing blend file. - * \return success - * - * \note In the future we should re-evaluate user preferences, - * possibly splitting out system/hardware specific prefs. - */ bool BKE_blendfile_userdef_write_app_template(const char *filepath, ReportList *reports) { /* if it fails, overwrite is OK. */ @@ -877,10 +843,6 @@ static void blendfile_write_partial_cb(void *UNUSED(handle), Main *UNUSED(bmain) } } -/** - * \param remap_mode: Choose the kind of path remapping or none #eBLO_WritePathRemap. - * \return Success. - */ bool BKE_blendfile_write_partial(Main *bmain_src, const char *filepath, const int write_flags, diff --git a/source/blender/blenkernel/intern/blendfile_link_append.c b/source/blender/blenkernel/intern/blendfile_link_append.c index 6cb71c48a00..c265a6e2b7d 100644 --- a/source/blender/blenkernel/intern/blendfile_link_append.c +++ b/source/blender/blenkernel/intern/blendfile_link_append.c @@ -186,11 +186,6 @@ static void link_append_context_library_blohandle_release( } } -/** Allocate and initialize a new context to link/append datablocks. - * - * \param flag: A combination of #eFileSel_Params_Flag from DNA_space_types.h & #eBLOLibLinkFlags - * from BLO_readfile.h - */ BlendfileLinkAppendContext *BKE_blendfile_link_append_context_new(LibraryLink_Params *params) { MemArena *ma = BLI_memarena_new(BLI_MEMARENA_STD_BUFSIZE, __func__); @@ -202,7 +197,6 @@ BlendfileLinkAppendContext *BKE_blendfile_link_append_context_new(LibraryLink_Pa return lapp_context; } -/** Free a link/append context. */ void BKE_blendfile_link_append_context_free(BlendfileLinkAppendContext *lapp_context) { if (lapp_context->new_id_to_item != NULL) { @@ -220,10 +214,6 @@ void BKE_blendfile_link_append_context_free(BlendfileLinkAppendContext *lapp_con BLI_memarena_free(lapp_context->memarena); } -/** Set or clear flags in given \a lapp_context. - * - * \param do_set: Set the given \a flag if true, clear it otherwise. - */ void BKE_blendfile_link_append_context_flag_set(BlendfileLinkAppendContext *lapp_context, const int flag, const bool do_set) @@ -236,11 +226,6 @@ void BKE_blendfile_link_append_context_flag_set(BlendfileLinkAppendContext *lapp } } -/** Store reference to a Blender's embedded memfile into the context. - * - * \note This is required since embedded startup blender file is handled in `ED` module, which - * cannot be linked in BKE code. - */ void BKE_blendfile_link_append_context_embedded_blendfile_set( BlendfileLinkAppendContext *lapp_context, const void *blendfile_mem, int blendfile_memsize) { @@ -251,7 +236,6 @@ void BKE_blendfile_link_append_context_embedded_blendfile_set( lapp_context->blendfile_memsize = (size_t)blendfile_memsize; } -/** Clear reference to Blender's embedded startup file into the context. */ void BKE_blendfile_link_append_context_embedded_blendfile_clear( BlendfileLinkAppendContext *lapp_context) { @@ -259,15 +243,6 @@ void BKE_blendfile_link_append_context_embedded_blendfile_clear( lapp_context->blendfile_memsize = 0; } -/** Add a new source library to search for items to be linked to the given link/append context. - * - * \param libname: the absolute path to the library blend file. - * \param blo_handle: the blend file handle of the library, NULL is not available. Note that this - * is only borrowed for linking purpose, no releasing or other management will - * be performed by #BKE_blendfile_link_append code on it. - * - * \note *Never* call BKE_blendfile_link_append_context_library_add() after having added some - * items. */ void BKE_blendfile_link_append_context_library_add(BlendfileLinkAppendContext *lapp_context, const char *libname, BlendHandle *blo_handle) @@ -289,13 +264,6 @@ void BKE_blendfile_link_append_context_library_add(BlendfileLinkAppendContext *l lapp_context->num_libraries++; } -/** Add a new item (datablock name and idcode) to be searched and linked/appended from libraries - * associated to the given context. - * - * \param userdata: an opaque user-data pointer stored in generated link/append item. */ -/* TODO: Add a more friendly version of this that combines it with the call to - * #BKE_blendfile_link_append_context_item_library_index_enable to enable the added item for all - * added library sources. */ BlendfileLinkAppendContextItem *BKE_blendfile_link_append_context_item_add( BlendfileLinkAppendContext *lapp_context, const char *idname, @@ -321,19 +289,6 @@ BlendfileLinkAppendContextItem *BKE_blendfile_link_append_context_item_add( return item; } -/** Search for all ID matching given `id_types_filter` in given `library_index`, and add them to - * the list of items to process. - * - * \note #BKE_blendfile_link_append_context_library_add should never be called on the same - *`lapp_context` after this function. - * - * \param id_types_filter: A set of `FILTER_ID` bitflags, the types of IDs to add to the items - * list. - * \param library_index: The index of the library to look into, in given `lapp_context`. - * - * \return The number of items found and added to the list, or `BLENDFILE_LINK_APPEND_INVALID` if - * it could not open the .blend file. - */ int BKE_blendfile_link_append_context_item_idtypes_from_library_add( BlendfileLinkAppendContext *lapp_context, ReportList *reports, @@ -385,8 +340,6 @@ int BKE_blendfile_link_append_context_item_idtypes_from_library_add( return id_num; } -/** Enable search of the given \a item into the library stored at given index in the link/append - * context. */ void BKE_blendfile_link_append_context_item_library_index_enable( BlendfileLinkAppendContext *UNUSED(lapp_context), BlendfileLinkAppendContextItem *item, @@ -395,7 +348,6 @@ void BKE_blendfile_link_append_context_item_library_index_enable( BLI_BITMAP_ENABLE(item->libraries, library_index); } -/** Check if given link/append context is empty (has no items to process) or not. */ bool BKE_blendfile_link_append_context_is_empty(struct BlendfileLinkAppendContext *lapp_context) { return lapp_context->num_items == 0; @@ -420,13 +372,6 @@ short BKE_blendfile_link_append_context_item_idcode_get( return item->idcode; } -/** Iterate over all (or a subset) of the items listed in given #BlendfileLinkAppendContext, and - * call the `callback_function` on them. - * - * \param flag: Control which type of items to process (see - * #eBlendfileLinkAppendForeachItemFlag enum flags). - * \param userdata: An opaque void pointer passed to the `callback_function`. - */ void BKE_blendfile_link_append_context_item_foreach( struct BlendfileLinkAppendContext *lapp_context, BKE_BlendfileLinkAppendContexteItemFunction callback_function, @@ -1014,11 +959,6 @@ static int foreach_libblock_link_append_callback(LibraryIDLinkCallbackData *cb_d /** \name Library link/append code. * \{ */ -/** Perform append operation, using modern ID usage looper to detect which ID should be kept - * linked, made local, duplicated as local, re-used from local etc. - * - * The IDs processed by this functions are the one that have been linked by a previous call to - * #BKE_blendfile_link on the same `lapp_context`. */ void BKE_blendfile_append(BlendfileLinkAppendContext *lapp_context, ReportList *reports) { if (lapp_context->num_items == 0) { @@ -1287,7 +1227,6 @@ void BKE_blendfile_append(BlendfileLinkAppendContext *lapp_context, ReportList * BKE_main_id_newptr_and_tag_clear(bmain); } -/** Perform linking operation on all items added to given `lapp_context`. */ void BKE_blendfile_link(BlendfileLinkAppendContext *lapp_context, ReportList *reports) { if (lapp_context->num_items == 0) { @@ -1481,23 +1420,6 @@ static void blendfile_library_relocate_remap(Main *bmain, } } -/** Try to relocate all linked IDs added to `lapp_context`, belonging to the given `library`. - * - * This function searches for matching IDs (type and name) in all libraries added to the given - * `lapp_context`. - * - * Typical usages include: - * * Relocating a library: - * - Add the new target library path to `lapp_context`. - * - Add all IDs from the library to relocate to `lapp_context` - * - Mark the new target library to be considered for each ID. - * - Call this function. - * - * * Searching for (e.g.missing) linked IDs in a set or sub-set of libraries: - * - Add all potential library sources paths to `lapp_context`. - * - Add all IDs to search for to `lapp_context`. - * - Mark which libraries should be considered for each ID. - * - Call this function. */ void BKE_blendfile_library_relocate(BlendfileLinkAppendContext *lapp_context, ReportList *reports, Library *library, diff --git a/source/blender/blenkernel/intern/boids.c b/source/blender/blenkernel/intern/boids.c index a7257133821..a9f26d00007 100644 --- a/source/blender/blenkernel/intern/boids.c +++ b/source/blender/blenkernel/intern/boids.c @@ -1061,7 +1061,6 @@ static int boid_condition_is_true(BoidCondition *cond) } #endif -/* determines the velocity the boid wants to have */ void boid_brain(BoidBrainData *bbd, int p, ParticleData *pa) { BoidRule *rule; @@ -1218,7 +1217,6 @@ void boid_brain(BoidBrainData *bbd, int p, ParticleData *pa) } } } -/* tries to realize the wanted velocity taking all constraints into account */ void boid_body(BoidBrainData *bbd, ParticleData *pa) { BoidSettings *boids = bbd->part->boids; diff --git a/source/blender/blenkernel/intern/brush.c b/source/blender/blenkernel/intern/brush.c index e92dd8a5ace..153a65d67db 100644 --- a/source/blender/blenkernel/intern/brush.c +++ b/source/blender/blenkernel/intern/brush.c @@ -514,10 +514,6 @@ static void brush_defaults(Brush *brush) /* Datablock add/copy/free/make_local */ -/** - * \note Resulting brush will have two users: one as a fake user, - * another is assumed to be used by the caller. - */ Brush *BKE_brush_add(Main *bmain, const char *name, const eObjectMode ob_mode) { Brush *brush; @@ -529,7 +525,6 @@ Brush *BKE_brush_add(Main *bmain, const char *name, const eObjectMode ob_mode) return brush; } -/* add grease pencil settings */ void BKE_brush_init_gpencil_settings(Brush *brush) { if (brush->gpencil_settings == NULL) { @@ -557,7 +552,6 @@ void BKE_brush_init_gpencil_settings(Brush *brush) brush->gpencil_settings->curve_rand_value = BKE_curvemapping_add(1, 0.0f, 0.0f, 1.0f, 1.0f); } -/* add a new gp-brush */ Brush *BKE_brush_add_gpencil(Main *bmain, ToolSettings *ts, const char *name, eObjectMode mode) { Paint *paint = NULL; @@ -597,7 +591,6 @@ Brush *BKE_brush_add_gpencil(Main *bmain, ToolSettings *ts, const char *name, eO return brush; } -/* Delete a Brush. */ bool BKE_brush_delete(Main *bmain, Brush *brush) { if (brush->id.tag & LIB_TAG_INDIRECT) { @@ -1331,7 +1324,6 @@ static Brush *gpencil_brush_ensure( return brush; } -/* Create a set of grease pencil Drawing presets. */ void BKE_brush_gpencil_paint_presets(Main *bmain, ToolSettings *ts, const bool reset) { bool r_new = false; @@ -1433,7 +1425,6 @@ void BKE_brush_gpencil_paint_presets(Main *bmain, ToolSettings *ts, const bool r } } -/* Create a set of grease pencil Vertex Paint presets. */ void BKE_brush_gpencil_vertex_presets(Main *bmain, ToolSettings *ts, const bool reset) { bool r_new = false; @@ -1480,7 +1471,6 @@ void BKE_brush_gpencil_vertex_presets(Main *bmain, ToolSettings *ts, const bool } } -/* Create a set of grease pencil Sculpt Paint presets. */ void BKE_brush_gpencil_sculpt_presets(Main *bmain, ToolSettings *ts, const bool reset) { bool r_new = false; @@ -1555,7 +1545,6 @@ void BKE_brush_gpencil_sculpt_presets(Main *bmain, ToolSettings *ts, const bool } } -/* Create a set of grease pencil Weight Paint presets. */ void BKE_brush_gpencil_weight_presets(Main *bmain, ToolSettings *ts, const bool reset) { bool r_new = false; @@ -1957,9 +1946,6 @@ void BKE_brush_sculpt_reset(Brush *br) } } -/** - * Library Operations - */ void BKE_brush_curve_preset(Brush *b, eCurveMappingPreset preset) { CurveMapping *cumap = NULL; @@ -1977,10 +1963,6 @@ void BKE_brush_curve_preset(Brush *b, eCurveMappingPreset preset) BKE_curvemapping_changed(cumap, false); } -/* Generic texture sampler for 3D painting systems. point has to be either in - * region space mouse coordinates, or 3d world coordinates for 3D mapping. - * - * rgba outputs straight alpha. */ float BKE_brush_sample_tex_3d(const Scene *scene, const Brush *br, const float point[3], @@ -2373,7 +2355,6 @@ void BKE_brush_weight_set(const Scene *scene, Brush *brush, float value) } } -/* scale unprojected radius to reflect a change in the brush's 2D size */ void BKE_brush_scale_unprojected_radius(float *unprojected_radius, int new_brush_size, int old_brush_size) @@ -2386,7 +2367,6 @@ void BKE_brush_scale_unprojected_radius(float *unprojected_radius, (*unprojected_radius) *= scale; } -/* scale brush size to reflect a change in the brush's unprojected radius */ void BKE_brush_scale_size(int *r_brush_size, float new_unprojected_radius, float old_unprojected_radius) @@ -2437,7 +2417,6 @@ void BKE_brush_randomize_texture_coords(UnifiedPaintSettings *ups, bool mask) } } -/* Uses the brush curve control to find a strength value */ float BKE_brush_curve_strength(const Brush *br, float p, const float len) { float strength = 1.0f; @@ -2485,7 +2464,6 @@ float BKE_brush_curve_strength(const Brush *br, float p, const float len) return strength; } -/* Uses the brush curve control to find a strength value between 0 and 1 */ float BKE_brush_curve_strength_clamped(const Brush *br, float p, const float len) { float strength = BKE_brush_curve_strength(br, p, len); @@ -2528,7 +2506,6 @@ unsigned int *BKE_brush_gen_texture_cache(Brush *br, int half_side, bool use_sec return texcache; } -/**** Radial Control ****/ struct ImBuf *BKE_brush_gen_radial_control_imbuf(Brush *br, bool secondary, bool display_gradient) { ImBuf *im = MEM_callocN(sizeof(ImBuf), "radial control texture"); diff --git a/source/blender/blenkernel/intern/bvhutils.cc b/source/blender/blenkernel/intern/bvhutils.cc index 1f92f834972..db4782e3952 100644 --- a/source/blender/blenkernel/intern/bvhutils.cc +++ b/source/blender/blenkernel/intern/bvhutils.cc @@ -147,9 +147,6 @@ static void bvhcache_insert(BVHCache *bvh_cache, BVHTree *tree, BVHCacheType typ item->is_filled = true; } -/** - * frees a bvhcache - */ void bvhcache_free(BVHCache *bvh_cache) { for (int index = 0; index < BVHTREE_MAX_ITEM; index++) { @@ -669,9 +666,6 @@ static void bvhtree_from_mesh_verts_setup_data(BVHTreeFromMesh *data, data->vert_allocated = vert_allocated; } -/** - * Builds a BVH-tree where nodes are the vertices of the given `em`. - */ BVHTree *bvhtree_from_editmesh_verts_ex(BVHTreeFromEditMesh *data, BMEditMesh *em, const BLI_bitmap *verts_mask, @@ -727,13 +721,6 @@ BVHTree *bvhtree_from_editmesh_verts( data, em, nullptr, -1, epsilon, tree_type, axis, BVHTREE_FROM_VERTS, nullptr, nullptr); } -/** - * Builds a BVH-tree where nodes are the given vertices (NOTE: does not copy given `vert`!). - * \param vert_allocated: if true, vert freeing will be done when freeing data. - * \param verts_mask: if not null, true elements give which vert to add to BVH-tree. - * \param verts_num_active: if >= 0, number of active verts to add to BVH-tree - * (else will be computed from mask). - */ BVHTree *bvhtree_from_mesh_verts_ex(BVHTreeFromMesh *data, const MVert *vert, const int verts_num, @@ -884,9 +871,6 @@ static void bvhtree_from_mesh_edges_setup_data(BVHTreeFromMesh *data, data->edge_allocated = edge_allocated; } -/** - * Builds a BVH-tree where nodes are the edges of the given `em`. - */ BVHTree *bvhtree_from_editmesh_edges_ex(BVHTreeFromEditMesh *data, BMEditMesh *em, const BLI_bitmap *edges_mask, @@ -941,14 +925,6 @@ BVHTree *bvhtree_from_editmesh_edges( data, em, nullptr, -1, epsilon, tree_type, axis, BVHTREE_FROM_VERTS, nullptr, nullptr); } -/** - * Builds a BVH-tree where nodes are the given edges. - * \param vert, vert_allocated: if true, elem freeing will be done when freeing data. - * \param edge, edge_allocated: if true, elem freeing will be done when freeing data. - * \param edges_mask: if not null, true elements give which vert to add to BVH-tree. - * \param edges_num_active: if >= 0, number of active edges to add to BVH-tree - * (else will be computed from mask). - */ BVHTree *bvhtree_from_mesh_edges_ex(BVHTreeFromMesh *data, const MVert *vert, const bool vert_allocated, @@ -1075,15 +1051,6 @@ static void bvhtree_from_mesh_faces_setup_data(BVHTreeFromMesh *data, data->face_allocated = face_allocated; } -/** - * Builds a BVH-tree where nodes are the given tessellated faces - * (NOTE: does not copy given mfaces!). - * \param vert_allocated: if true, vert freeing will be done when freeing data. - * \param face_allocated: if true, face freeing will be done when freeing data. - * \param faces_mask: if not null, true elements give which faces to add to BVH-tree. - * \param faces_num_active: if >= 0, number of active faces to add to BVH-tree - * (else will be computed from mask). - */ BVHTree *bvhtree_from_mesh_faces_ex(BVHTreeFromMesh *data, const MVert *vert, const bool vert_allocated, @@ -1257,9 +1224,6 @@ static void bvhtree_from_mesh_looptri_setup_data(BVHTreeFromMesh *data, data->looptri_allocated = looptri_allocated; } -/** - * Builds a BVH-tree where nodes are the `looptri` faces of the given `bm`. - */ BVHTree *bvhtree_from_editmesh_looptri_ex(BVHTreeFromEditMesh *data, BMEditMesh *em, const BLI_bitmap *looptri_mask, @@ -1314,11 +1278,6 @@ BVHTree *bvhtree_from_editmesh_looptri( data, em, nullptr, -1, epsilon, tree_type, axis, BVHTREE_FROM_VERTS, nullptr, nullptr); } -/** - * Builds a BVH-tree where nodes are the looptri faces of the given mesh. - * - * \note for edit-mesh this is currently a duplicate of #bvhtree_from_mesh_faces_ex - */ BVHTree *bvhtree_from_mesh_looptri_ex(BVHTreeFromMesh *data, const struct MVert *vert, const bool vert_allocated, @@ -1461,12 +1420,6 @@ static BLI_bitmap *looptri_no_hidden_map_get(const MPoly *mpoly, return looptri_mask; } -/** - * Builds or queries a bvhcache for the cache bvhtree of the request type. - * - * \note This function only fills a cache, and therefore the mesh argument can - * be considered logically const. Concurrent access is protected by a mutex. - */ BVHTree *BKE_bvhtree_from_mesh_get(struct BVHTreeFromMesh *data, const struct Mesh *mesh, const BVHCacheType bvh_cache_type, @@ -1650,9 +1603,6 @@ BVHTree *BKE_bvhtree_from_mesh_get(struct BVHTreeFromMesh *data, return tree; } -/** - * Builds or queries a bvhcache for the cache bvhtree of the request type. - */ BVHTree *BKE_bvhtree_from_editmesh_get(BVHTreeFromEditMesh *data, struct BMEditMesh *em, const int tree_type, @@ -1767,9 +1717,6 @@ BVHTree *BKE_bvhtree_from_editmesh_get(BVHTreeFromEditMesh *data, /** \} */ -/** - * Frees data allocated by a call to `bvhtree_from_editmesh_*`. - */ void free_bvhtree_from_editmesh(struct BVHTreeFromEditMesh *data) { if (data->tree) { @@ -1780,9 +1727,6 @@ void free_bvhtree_from_editmesh(struct BVHTreeFromEditMesh *data) } } -/** - * Frees data allocated by a call to `bvhtree_from_mesh_*`. - */ void free_bvhtree_from_mesh(struct BVHTreeFromMesh *data) { if (data->tree && !data->cached) { diff --git a/source/blender/blenkernel/intern/cachefile.c b/source/blender/blenkernel/intern/cachefile.c index 2e0e95b19c5..8833f3eabe9 100644 --- a/source/blender/blenkernel/intern/cachefile.c +++ b/source/blender/blenkernel/intern/cachefile.c @@ -420,12 +420,6 @@ float BKE_cachefile_time_offset(const CacheFile *cache_file, const float time, c return cache_file->is_sequence ? frame : frame / fps - time_offset; } -/** - * Determine whether the #CacheFile should use a render engine procedural. If so, data is not read - * from the file and bounding boxes are used to represent the objects in the Scene. - * Render engines will receive the bounding box as a placeholder but can instead - * load the data directly if they support it. - */ bool BKE_cache_file_uses_render_procedural(const CacheFile *cache_file, Scene *scene, const int dag_eval_mode) diff --git a/source/blender/blenkernel/intern/callbacks.c b/source/blender/blenkernel/intern/callbacks.c index 72dd51a940d..992eb896d2d 100644 --- a/source/blender/blenkernel/intern/callbacks.c +++ b/source/blender/blenkernel/intern/callbacks.c @@ -115,7 +115,6 @@ void BKE_callback_global_init(void) callbacks_initialized = true; } -/* call on application exit */ void BKE_callback_global_finalize(void) { eCbEvent evt; diff --git a/source/blender/blenkernel/intern/camera.c b/source/blender/blenkernel/intern/camera.c index 0b9de2ddb38..8fa787b2222 100644 --- a/source/blender/blenkernel/intern/camera.c +++ b/source/blender/blenkernel/intern/camera.c @@ -218,7 +218,6 @@ void *BKE_camera_add(Main *bmain, const char *name) return cam; } -/* get the camera's dof value, takes the dof object into account */ float BKE_camera_object_dof_distance(Object *ob) { Camera *cam = (Camera *)ob->data; @@ -427,7 +426,6 @@ void BKE_camera_params_compute_viewplane( params->viewplane = viewplane; } -/* viewplane is assumed to be already computed */ void BKE_camera_params_compute_matrix(CameraParams *params) { rctf viewplane = params->viewplane; @@ -759,7 +757,6 @@ static bool camera_frame_fit_calc_from_data(CameraParams *params, } /* don't move the camera, just yield the fit location */ -/* r_scale only valid/useful for ortho cameras */ bool BKE_camera_view_frame_fit_to_scene( Depsgraph *depsgraph, const Scene *scene, Object *camera_ob, float r_co[3], float *r_scale) { @@ -910,7 +907,6 @@ static void camera_stereo3d_model_matrix(const Object *camera, } } -/* the view matrix is used by the viewport drawing, it is basically the inverted model matrix */ void BKE_camera_multiview_view_matrix(const RenderData *rd, const Object *camera, const bool is_left, @@ -1033,7 +1029,6 @@ static Object *camera_multiview_advanced(const Scene *scene, Object *camera, con return camera; } -/* returns the camera to be used for render */ Object *BKE_camera_multiview_render(const Scene *scene, Object *camera, const char *viewname) { const bool is_multiview = (camera != NULL) && (scene->r.scemode & R_MULTIVIEW) != 0; diff --git a/source/blender/blenkernel/intern/cloth.c b/source/blender/blenkernel/intern/cloth.c index 080a7c90c46..42633ff3809 100644 --- a/source/blender/blenkernel/intern/cloth.c +++ b/source/blender/blenkernel/intern/cloth.c @@ -326,6 +326,7 @@ static int do_step_cloth( /************************************************ * clothModifier_do - main simulation function ************************************************/ + void clothModifier_do(ClothModifierData *clmd, Depsgraph *depsgraph, Scene *scene, @@ -433,7 +434,6 @@ void clothModifier_do(ClothModifierData *clmd, clmd->clothObject->last_frame = framenr; } -/* frees all */ void cloth_free_modifier(ClothModifierData *clmd) { Cloth *cloth = NULL; @@ -504,7 +504,6 @@ void cloth_free_modifier(ClothModifierData *clmd) } } -/* frees all */ void cloth_free_modifier_extern(ClothModifierData *clmd) { Cloth *cloth = NULL; diff --git a/source/blender/blenkernel/intern/collection.c b/source/blender/blenkernel/intern/collection.c index 979e0a91c95..21a9159004f 100644 --- a/source/blender/blenkernel/intern/collection.c +++ b/source/blender/blenkernel/intern/collection.c @@ -431,10 +431,6 @@ static Collection *collection_add(Main *bmain, return collection; } -/** - * Add a collection to a collection ListBase and synchronize all render layers - * The ListBase is NULL when the collection is to be added to the master collection - */ Collection *BKE_collection_add(Main *bmain, Collection *collection_parent, const char *name_custom) { Collection *collection = collection_add(bmain, collection_parent, name_custom); @@ -442,12 +438,6 @@ Collection *BKE_collection_add(Main *bmain, Collection *collection_parent, const return collection; } -/** - * Add \a collection_dst to all scene collections that reference object \a ob_src is in. - * Used to replace an instance object with a collection (library override operator). - * - * Logic is very similar to #BKE_collection_object_add_from(). - */ void BKE_collection_add_from_object(Main *bmain, Scene *scene, const Object *ob_src, @@ -470,12 +460,6 @@ void BKE_collection_add_from_object(Main *bmain, BKE_main_collection_sync(bmain); } -/** - * Add \a collection_dst to all scene collections that reference collection \a collection_src is - * in. - * - * Logic is very similar to #BKE_collection_object_add_from(). - */ void BKE_collection_add_from_collection(Main *bmain, Scene *scene, Collection *collection_src, @@ -509,17 +493,12 @@ void BKE_collection_add_from_collection(Main *bmain, /** \name Free and Delete Collection * \{ */ -/** Free (or release) any data used by this collection (does not free the collection itself). */ void BKE_collection_free_data(Collection *collection) { BKE_libblock_free_data(&collection->id, false); collection_free_data(&collection->id); } -/** - * Remove a collection, optionally removing its child objects or moving - * them to parent collections. - */ bool BKE_collection_delete(Main *bmain, Collection *collection, bool hierarchy) { /* Master collection is not real datablock, can't be removed. */ @@ -680,14 +659,6 @@ static Collection *collection_duplicate_recursive(Main *bmain, return collection_new; } -/** - * Make a deep copy (aka duplicate) of the given collection and all of its children, recursively. - * - * \warning This functions will clear all \a bmain #ID.idnew pointers, unless \a - * #LIB_ID_DUPLICATE_IS_SUBPROCESS duplicate option is passed on, in which case caller is - * responsible to reconstruct collection dependencies information's - * (i.e. call #BKE_main_collection_sync). - */ Collection *BKE_collection_duplicate(Main *bmain, Collection *parent, Collection *collection, @@ -746,9 +717,6 @@ Collection *BKE_collection_duplicate(Main *bmain, /** \name Collection Naming * \{ */ -/** - * The automatic/fallback name of a new collection. - */ void BKE_collection_new_name_get(Collection *collection_parent, char *rname) { char *name; @@ -771,9 +739,6 @@ void BKE_collection_new_name_get(Collection *collection_parent, char *rname) MEM_freeN(name); } -/** - * The name to show in the interface. - */ const char *BKE_collection_ui_name_get(struct Collection *collection) { if (collection->flag & COLLECTION_IS_MASTER) { @@ -1129,9 +1094,6 @@ static bool collection_object_remove(Main *bmain, return true; } -/** - * Add object to collection - */ bool BKE_collection_object_add(Main *bmain, Collection *collection, Object *ob) { if (ELEM(NULL, collection, ob)) { @@ -1160,12 +1122,6 @@ bool BKE_collection_object_add(Main *bmain, Collection *collection, Object *ob) return true; } -/** - * Add \a ob_dst to all scene collections that reference object \a ob_src is in. - * Used for copying objects. - * - * Logic is very similar to #BKE_collection_add_from_object() - */ void BKE_collection_object_add_from(Main *bmain, Scene *scene, Object *ob_src, Object *ob_dst) { bool is_instantiated = false; @@ -1188,9 +1144,6 @@ void BKE_collection_object_add_from(Main *bmain, Scene *scene, Object *ob_src, O BKE_main_collection_sync(bmain); } -/** - * Remove object from collection. - */ bool BKE_collection_object_remove(Main *bmain, Collection *collection, Object *ob, @@ -1238,9 +1191,6 @@ static bool scene_collections_object_remove( return removed; } -/** - * Remove object from all collections of scene - */ bool BKE_scene_collections_object_remove(Main *bmain, Scene *scene, Object *ob, const bool free_us) { return scene_collections_object_remove(bmain, scene, ob, free_us, NULL); @@ -1304,18 +1254,6 @@ static void collection_missing_parents_remove(Collection *collection) } } -/** - * Remove all NULL children from parent collections of changed \a collection. - * This is used for library remapping, where these pointers have been set to NULL. - * Otherwise this should never happen. - * - * \note caller must ensure #BKE_main_collection_sync_remap() is called afterwards! - * - * \param parent_collection: The collection owning the pointers that were remapped. May be \a NULL, - * in which case whole \a bmain database of collections is checked. - * \param child_collection: The collection that was remapped to another pointer. May be \a NULL, - * in which case whole \a bmain database of collections is checked. - */ void BKE_collections_child_remove_nulls(Main *bmain, Collection *parent_collection, Collection *child_collection) @@ -1360,11 +1298,6 @@ void BKE_collections_child_remove_nulls(Main *bmain, } } -/** - * Move object from a collection into another - * - * If source collection is NULL move it from all the existing collections. - */ void BKE_collection_object_move( Main *bmain, Scene *scene, Collection *collection_dst, Collection *collection_src, Object *ob) { @@ -1439,15 +1372,6 @@ static bool collection_instance_find_recursive(Collection *collection, return false; } -/** - * Find potential cycles in collections. - * - * \param new_ancestor: the potential new owner of given \a collection, - * or the collection to check if the later is NULL. - * \param collection: the collection we want to add to \a new_ancestor, - * may be NULL if we just want to ensure \a new_ancestor does not already have cycles. - * \return true if a cycle is found. - */ bool BKE_collection_cycle_find(Collection *new_ancestor, Collection *collection) { if (collection == new_ancestor) { @@ -1511,12 +1435,6 @@ static bool collection_cycle_fix_recursive(Main *bmain, return cycles_found; } -/** - * Find and fix potential cycles in collections. - * - * \param collection: The collection to check for existing cycles. - * \return true if cycles are found and fixed. - */ bool BKE_collection_cycles_fix(Main *bmain, Collection *collection) { return collection_cycle_fix_recursive(bmain, collection, collection) || @@ -1629,11 +1547,6 @@ bool BKE_collection_child_remove(Main *bmain, Collection *parent, Collection *ch return true; } -/** - * Rebuild parent relationships from child ones, for all children of given \a collection. - * - * \note Given collection is assumed to already have valid parents. - */ void BKE_collection_parent_relations_rebuild(Collection *collection) { LISTBASE_FOREACH_MUTABLE (CollectionChild *, child, &collection->children) { @@ -1682,9 +1595,6 @@ static void collection_parents_rebuild_recursive(Collection *collection) } } -/** - * Rebuild parent relationships from child ones, for all collections in given \a bmain. - */ void BKE_main_collections_parent_relations_rebuild(Main *bmain) { /* Only collections not in bmain (master ones in scenes) have no parent... */ @@ -1745,11 +1655,6 @@ static Collection *collection_from_index_recursive(Collection *collection, return NULL; } -/** - * Return Scene Collection for a given index. - * - * The index is calculated from top to bottom counting the children before the siblings. - */ Collection *BKE_collection_from_index(Scene *scene, const int index) { int index_current = 0; @@ -1793,10 +1698,6 @@ static bool collection_objects_select(ViewLayer *view_layer, Collection *collect return changed; } -/** - * Select all the objects in this Collection (and its nested collections) for this ViewLayer. - * Return true if any object was selected. - */ bool BKE_collection_objects_select(ViewLayer *view_layer, Collection *collection, bool deselect) { LayerCollection *layer_collection = BKE_layer_collection_first_from_scene_collection(view_layer, @@ -1922,10 +1823,6 @@ static void scene_collections_array(Scene *scene, scene_collection_callback(collection, scene_collections_build_array, &array); } -/** - * Only use this in non-performance critical situations - * (it iterates over all scene collections twice) - */ void BKE_scene_collections_iterator_begin(BLI_Iterator *iter, void *data_in) { Scene *scene = data_in; @@ -2067,13 +1964,6 @@ void BKE_scene_objects_iterator_end(BLI_Iterator *iter) } } -/** - * Generate a new GSet (or extend given `objects_gset` if not NULL) with all objects referenced by - * all collections of given `scene`. - * - * \note This will include objects without a base currently - * (because they would belong to excluded collections only e.g.). - */ GSet *BKE_scene_objects_as_gset(Scene *scene, GSet *objects_gset) { BLI_Iterator iter; diff --git a/source/blender/blenkernel/intern/collision.c b/source/blender/blenkernel/intern/collision.c index 03957d54629..671c6530685 100644 --- a/source/blender/blenkernel/intern/collision.c +++ b/source/blender/blenkernel/intern/collision.c @@ -78,7 +78,6 @@ typedef struct SelfColDetectData { * Collision modifier code start ***********************************/ -/* step is limited from 0 (frame start position) to 1 (frame end position) */ void collision_move_object(CollisionModifierData *collmd, const float step, const float prevstep, @@ -1261,9 +1260,6 @@ static void add_collision_object(ListBase *relations, } } -/* Create list of collision relations in the collection or entire scene. - * This is used by the depsgraph to build relations, as well as faster - * lookup of colliders during evaluation. */ ListBase *BKE_collision_relations_create(Depsgraph *depsgraph, Collection *collection, unsigned int modifier_type) @@ -1292,8 +1288,6 @@ void BKE_collision_relations_free(ListBase *relations) } } -/* Create effective list of colliders from relations built beforehand. - * Self will be excluded. */ Object **BKE_collision_objects_create(Depsgraph *depsgraph, Object *self, Collection *collection, @@ -1341,8 +1335,6 @@ void BKE_collision_objects_free(Object **objects) } } -/* Create effective list of colliders from relations built beforehand. - * Self will be excluded. */ ListBase *BKE_collider_cache_create(Depsgraph *depsgraph, Object *self, Collection *collection) { ListBase *relations = DEG_get_collision_relations( diff --git a/source/blender/blenkernel/intern/colortools.c b/source/blender/blenkernel/intern/colortools.c index 62b817487fc..6703315a9de 100644 --- a/source/blender/blenkernel/intern/colortools.c +++ b/source/blender/blenkernel/intern/colortools.c @@ -183,7 +183,6 @@ void BKE_curvemapping_set_black_white(CurveMapping *cumap, /* ***************** operations on single curve ************* */ /* ********** NOTE: requires BKE_curvemapping_changed() call after ******** */ -/* remove specified point */ bool BKE_curvemap_remove_point(CurveMap *cuma, CurveMapPoint *point) { CurveMapPoint *cmp; @@ -213,7 +212,6 @@ bool BKE_curvemap_remove_point(CurveMap *cuma, CurveMapPoint *point) return (removed != 0); } -/* removes with flag set */ void BKE_curvemap_remove(CurveMap *cuma, const short flag) { CurveMapPoint *cmp = MEM_mallocN((cuma->totpoint) * sizeof(CurveMapPoint), "curve points"); @@ -439,9 +437,6 @@ void BKE_curvemap_reset(CurveMap *cuma, const rctf *clipr, int preset, int slope } } -/** - * \param type: eBezTriple_Handle - */ void BKE_curvemap_handle_set(CurveMap *cuma, int type) { int a; @@ -800,10 +795,10 @@ static void curvemap_make_table(const CurveMapping *cumap, CurveMap *cuma) cuma->table = cmp; } -/* call when you do images etc, needs restore too. also verifies tables */ -/* it uses a flag to prevent premul or free to happen twice */ void BKE_curvemapping_premultiply(CurveMapping *cumap, int restore) { + /* It uses a flag to prevent pre-multiply or free to happen twice. */ + int a; if (restore) { @@ -873,7 +868,6 @@ static int sort_curvepoints(const void *a1, const void *a2) /* ************************ more CurveMapping calls *************** */ -/* NOTE: only does current curvemap! */ void BKE_curvemapping_changed(CurveMapping *cumap, const bool rem_doubles) { CurveMap *cuma = cumap->cm + cumap->cur; @@ -965,13 +959,11 @@ void BKE_curvemapping_changed_all(CurveMapping *cumap) cumap->cur = cur; } -/* Reset the view for current curve. */ void BKE_curvemapping_reset_view(CurveMapping *cumap) { cumap->curr = cumap->clipr; } -/* table should be verified */ float BKE_curvemap_evaluateF(const CurveMapping *cumap, const CurveMap *cuma, float value) { /* index in table */ @@ -994,7 +986,6 @@ float BKE_curvemap_evaluateF(const CurveMapping *cumap, const CurveMap *cuma, fl return (1.0f - fi) * cuma->table[i].y + (fi)*cuma->table[i + 1].y; } -/* works with curve 'cur' */ float BKE_curvemapping_evaluateF(const CurveMapping *cumap, int cur, float value) { const CurveMap *cuma = cumap->cm + cur; @@ -1013,7 +1004,6 @@ float BKE_curvemapping_evaluateF(const CurveMapping *cumap, int cur, float value return val; } -/* vector case */ void BKE_curvemapping_evaluate3F(const CurveMapping *cumap, float vecout[3], const float vecin[3]) { vecout[0] = BKE_curvemap_evaluateF(cumap, &cumap->cm[0], vecin[0]); @@ -1021,7 +1011,6 @@ void BKE_curvemapping_evaluate3F(const CurveMapping *cumap, float vecout[3], con vecout[2] = BKE_curvemap_evaluateF(cumap, &cumap->cm[2], vecin[2]); } -/* RGB case, no black/white points, no premult */ void BKE_curvemapping_evaluateRGBF(const CurveMapping *cumap, float vecout[3], const float vecin[3]) @@ -1052,16 +1041,6 @@ static void curvemapping_evaluateRGBF_filmlike(const CurveMapping *cumap, vecout[channel_offset[2]] = v2; } -/** - * Same as #BKE_curvemapping_evaluate_premulRGBF - * but black/bwmul are passed as args for the compositor - * where they can change per pixel. - * - * Use in conjunction with #BKE_curvemapping_set_black_white_ex - * - * \param black: Use instead of cumap->black - * \param bwmul: Use instead of cumap->bwmul - */ void BKE_curvemapping_evaluate_premulRGBF_ex(const CurveMapping *cumap, float vecout[3], const float vecin[3], @@ -1127,7 +1106,6 @@ void BKE_curvemapping_evaluate_premulRGBF_ex(const CurveMapping *cumap, } } -/* RGB with black/white points and premult. tables are checked */ void BKE_curvemapping_evaluate_premulRGBF(const CurveMapping *cumap, float vecout[3], const float vecin[3]) @@ -1135,7 +1113,6 @@ void BKE_curvemapping_evaluate_premulRGBF(const CurveMapping *cumap, BKE_curvemapping_evaluate_premulRGBF_ex(cumap, vecout, vecin, cumap->black, cumap->bwmul); } -/* same as above, byte version */ void BKE_curvemapping_evaluate_premulRGB(const CurveMapping *cumap, unsigned char vecout_byte[3], const unsigned char vecin_byte[3]) @@ -1262,7 +1239,6 @@ void BKE_curvemapping_curves_blend_write(BlendWriter *writer, const CurveMapping } } -/* cumap itself has been read already. */ void BKE_curvemapping_blend_read(BlendDataReader *reader, CurveMapping *cumap) { /* flag seems to be able to hang? Maybe old files... not bad to clear anyway */ diff --git a/source/blender/blenkernel/intern/constraint.c b/source/blender/blenkernel/intern/constraint.c index 3455baa9292..d284c32b1df 100644 --- a/source/blender/blenkernel/intern/constraint.c +++ b/source/blender/blenkernel/intern/constraint.c @@ -123,7 +123,6 @@ static bConstraint *constraint_find_original_for_update(bConstraintOb *cob, bCon /* -------------- Naming -------------- */ -/* Find the first available, non-duplicate name for a given constraint */ void BKE_constraint_unique_name(bConstraint *con, ListBase *list) { BLI_uniquename(list, con, DATA_("Const"), '.', offsetof(bConstraint, name), sizeof(con->name)); @@ -132,8 +131,6 @@ void BKE_constraint_unique_name(bConstraint *con, ListBase *list) /* ----------------- Evaluation Loop Preparation --------------- */ /* package an object/bone for use in constraint evaluation */ -/* This function MEM_calloc's a bConstraintOb struct, - * that will need to be freed after evaluation */ bConstraintOb *BKE_constraints_make_evalob( Depsgraph *depsgraph, Scene *scene, Object *ob, void *subdata, short datatype) { @@ -211,7 +208,6 @@ bConstraintOb *BKE_constraints_make_evalob( return cob; } -/* cleanup after constraint evaluation */ void BKE_constraints_clear_evalob(bConstraintOb *cob) { float delta[4][4], imat[4][4]; @@ -261,10 +257,6 @@ void BKE_constraints_clear_evalob(bConstraintOb *cob) /* -------------- Space-Conversion API -------------- */ -/* This function is responsible for the correct transformations/conversions - * of a matrix from one space to another for constraint evaluation. - * For now, this is only implemented for Objects and PoseChannels. - */ void BKE_constraint_mat_convertspace(Object *ob, bPoseChannel *pchan, bConstraintOb *cob, @@ -5556,9 +5548,6 @@ static void constraints_init_typeinfo(void) constraintsTypeInfo[30] = &CTI_ARMATURE; /* Armature Constraint */ } -/* This function should be used for getting the appropriate type-info when only - * a constraint type is known - */ const bConstraintTypeInfo *BKE_constraint_typeinfo_from_type(int type) { /* initialize the type-info list? */ @@ -5578,9 +5567,6 @@ const bConstraintTypeInfo *BKE_constraint_typeinfo_from_type(int type) return NULL; } -/* This function should always be used to get the appropriate type-info, as it - * has checks which prevent segfaults in some weird cases. - */ const bConstraintTypeInfo *BKE_constraint_typeinfo_get(bConstraint *con) { /* only return typeinfo for valid constraints */ @@ -5611,11 +5597,6 @@ static void con_unlink_refs_cb(bConstraint *UNUSED(con), } } -/** - * Free data of a specific constraint if it has any info. - * be sure to run #BIK_clear_data() when freeing an IK constraint, - * unless DAG_relations_tag_update is called. - */ void BKE_constraint_free_data_ex(bConstraint *con, bool do_id_user) { if (con->data) { @@ -5643,7 +5624,6 @@ void BKE_constraint_free_data(bConstraint *con) BKE_constraint_free_data_ex(con, true); } -/* Free all constraints from a constraint-stack */ void BKE_constraints_free_ex(ListBase *list, bool do_id_user) { /* Free constraint data and also any extra data */ @@ -5660,7 +5640,6 @@ void BKE_constraints_free(ListBase *list) BKE_constraints_free_ex(list, true); } -/* Remove the specified constraint from the given constraint stack */ bool BKE_constraint_remove(ListBase *list, bConstraint *con) { if (con) { @@ -5686,7 +5665,6 @@ bool BKE_constraint_remove_ex(ListBase *list, Object *ob, bConstraint *con, bool return false; } -/* Apply the specified constraint in the given constraint stack */ bool BKE_constraint_apply_for_object(Depsgraph *depsgraph, Scene *scene, Object *ob, @@ -5920,7 +5898,6 @@ bool BKE_constraint_target_uses_bbone(struct bConstraint *con, /* ......... */ -/* Add new constraint for the given bone */ bConstraint *BKE_constraint_add_for_pose(Object *ob, bPoseChannel *pchan, const char *name, @@ -5933,7 +5910,6 @@ bConstraint *BKE_constraint_add_for_pose(Object *ob, return add_new_constraint(ob, pchan, name, type); } -/* Add new constraint for the given object */ bConstraint *BKE_constraint_add_for_object(Object *ob, const char *name, short type) { return add_new_constraint(ob, NULL, name, type); @@ -5941,7 +5917,6 @@ bConstraint *BKE_constraint_add_for_object(Object *ob, const char *name, short t /* ......... */ -/* Run the given callback on all ID-blocks in list of constraints */ void BKE_constraints_id_loop(ListBase *conlist, ConstraintIDFunc func, void *userdata) { LISTBASE_FOREACH (bConstraint *, con, conlist) { @@ -6016,7 +5991,6 @@ static void constraint_copy_data_ex(bConstraint *dst, } } -/** Allocate and duplicate a single constraint, outside of any object/pose context. */ bConstraint *BKE_constraint_duplicate_ex(bConstraint *src, const int flag, const bool do_extern) { bConstraint *dst = MEM_dupallocN(src); @@ -6025,7 +5999,6 @@ bConstraint *BKE_constraint_duplicate_ex(bConstraint *src, const int flag, const return dst; } -/* Add a copy of the given constraint for the given bone */ bConstraint *BKE_constraint_copy_for_pose(Object *ob, bPoseChannel *pchan, bConstraint *src) { if (pchan == NULL) { @@ -6037,7 +6010,6 @@ bConstraint *BKE_constraint_copy_for_pose(Object *ob, bPoseChannel *pchan, bCons return new_con; } -/* Add a copy of the given constraint for the given object */ bConstraint *BKE_constraint_copy_for_object(Object *ob, bConstraint *src) { bConstraint *new_con = BKE_constraint_duplicate_ex(src, 0, !ID_IS_LINKED(ob)); @@ -6045,7 +6017,6 @@ bConstraint *BKE_constraint_copy_for_object(Object *ob, bConstraint *src) return new_con; } -/* duplicate all of the constraints in a constraint stack */ void BKE_constraints_copy_ex(ListBase *dst, const ListBase *src, const int flag, bool do_extern) { bConstraint *con, *srccon; @@ -6074,7 +6045,6 @@ bConstraint *BKE_constraints_find_name(ListBase *list, const char *name) return BLI_findstring(list, name, offsetof(bConstraint, name)); } -/* finds the 'active' constraint in a constraint stack */ bConstraint *BKE_constraints_active_get(ListBase *list) { @@ -6091,7 +6061,6 @@ bConstraint *BKE_constraints_active_get(ListBase *list) return NULL; } -/* Set the given constraint as the active one (clearing all the others) */ void BKE_constraints_active_set(ListBase *list, bConstraint *con) { @@ -6127,7 +6096,6 @@ static bConstraint *constraint_list_find_from_target(ListBase *constraints, bCon return NULL; } -/* Finds the constraint that owns the given target within the object. */ bConstraint *BKE_constraint_find_from_target(Object *ob, bConstraintTarget *tgt, bPoseChannel **r_pchan) @@ -6225,12 +6193,6 @@ static bConstraint *constraint_find_original_for_update(bConstraintOb *cob, bCon return orig_con; } -/** - * Check whether given constraint is not local (i.e. from linked data) when the object is a library - * override. - * - * \param con: May be NULL, in which case we consider it as a non-local constraint case. - */ bool BKE_constraint_is_nonlocal_in_liboverride(const Object *ob, const bConstraint *con) { return (ID_IS_OVERRIDE_LIBRARY(ob) && @@ -6239,8 +6201,6 @@ bool BKE_constraint_is_nonlocal_in_liboverride(const Object *ob, const bConstrai /* -------- Constraints and Proxies ------- */ -/* Rescue all constraints tagged as being CONSTRAINT_PROXY_LOCAL - * (i.e. added to bone that's proxy-synced in this file) */ void BKE_constraints_proxylocal_extract(ListBase *dst, ListBase *src) { bConstraint *con, *next; @@ -6257,7 +6217,6 @@ void BKE_constraints_proxylocal_extract(ListBase *dst, ListBase *src) } } -/* Returns if the owner of the constraint is proxy-protected */ bool BKE_constraints_proxylocked_owner(Object *ob, bPoseChannel *pchan) { /* Currently, constraints can only be on object or bone level */ @@ -6281,13 +6240,6 @@ bool BKE_constraints_proxylocked_owner(Object *ob, bPoseChannel *pchan) /* -------- Target-Matrix Stuff ------- */ -/* This function is a relic from the prior implementations of the constraints system, when all - * constraints either had one or no targets. It used to be called during the main constraint - * solving loop, but is now only used for the remaining cases for a few constraints. - * - * None of the actual calculations of the matrices should be done here! Also, this function is - * not to be used by any new constraints, particularly any that have multiple targets. - */ void BKE_constraint_target_matrix_get(struct Depsgraph *depsgraph, Scene *scene, bConstraint *con, @@ -6364,7 +6316,6 @@ void BKE_constraint_target_matrix_get(struct Depsgraph *depsgraph, } } -/* Get the list of targets required for solving a constraint */ void BKE_constraint_targets_for_solving_get(struct Depsgraph *depsgraph, bConstraint *con, bConstraintOb *cob, @@ -6434,12 +6385,6 @@ void BKE_constraint_custom_object_space_get(float r_mat[4][4], bConstraint *con) /* ---------- Evaluation ----------- */ -/* This function is called whenever constraints need to be evaluated. Currently, all - * constraints that can be evaluated are every time this gets run. - * - * BKE_constraints_make_evalob and BKE_constraints_clear_evalob should be called before and - * after running this function, to sort out cob - */ void BKE_constraints_solve(struct Depsgraph *depsgraph, ListBase *conlist, bConstraintOb *cob, diff --git a/source/blender/blenkernel/intern/context.c b/source/blender/blenkernel/intern/context.c index c235a1bbb6a..ceaed5d2bba 100644 --- a/source/blender/blenkernel/intern/context.c +++ b/source/blender/blenkernel/intern/context.c @@ -547,12 +547,6 @@ static void data_dir_add(ListBase *lb, const char *member, const bool use_all) BLI_addtail(lb, link); } -/** - * \param C: Context - * \param use_store: Use 'C->wm.store' - * \param use_rna: Use Include the properties from 'RNA_Context' - * \param use_all: Don't skip values (currently only "scene") - */ ListBase CTX_data_dir_get_ex(const bContext *C, const bool use_store, const bool use_rna, @@ -1127,13 +1121,6 @@ RenderEngineType *CTX_data_engine_type(const bContext *C) return RE_engines_find(scene->r.engine); } -/** - * This is tricky. Sometimes the user overrides the render_layer - * but not the scene_collection. In this case what to do? - * - * If the scene_collection is linked to the ViewLayer we use it. - * Otherwise we fallback to the active one of the ViewLayer. - */ LayerCollection *CTX_data_layer_collection(const bContext *C) { ViewLayer *view_layer = CTX_data_view_layer(C); diff --git a/source/blender/blenkernel/intern/crazyspace.c b/source/blender/blenkernel/intern/crazyspace.c index 26894495777..6bbb9957b03 100644 --- a/source/blender/blenkernel/intern/crazyspace.c +++ b/source/blender/blenkernel/intern/crazyspace.c @@ -98,7 +98,6 @@ static bool modifiers_disable_subsurf_temporary(struct Scene *scene, Object *ob) return disabled; } -/* disable subsurf temporal, get mapped cos, and enable it */ float (*BKE_crazyspace_get_mapped_editverts(struct Depsgraph *depsgraph, Object *obedit))[3] { Scene *scene = DEG_get_input_scene(depsgraph); @@ -243,10 +242,6 @@ void BKE_crazyspace_set_quats_mesh(Mesh *me, } } -/** - * Returns an array of deform matrices for crazy-space correction, - * and the number of modifiers left. - */ int BKE_crazyspace_get_first_deform_matrices_editbmesh(struct Depsgraph *depsgraph, Scene *scene, Object *ob, diff --git a/source/blender/blenkernel/intern/cryptomatte.cc b/source/blender/blenkernel/intern/cryptomatte.cc index 1ff0ca92306..02fba2aa5a4 100644 --- a/source/blender/blenkernel/intern/cryptomatte.cc +++ b/source/blender/blenkernel/intern/cryptomatte.cc @@ -212,7 +212,6 @@ float BKE_cryptomatte_hash_to_float(uint32_t cryptomatte_hash) return blender::bke::cryptomatte::CryptomatteHash(cryptomatte_hash).float_encoded(); } -/* Find an ID in the given main that matches the given encoded float. */ bool BKE_cryptomatte_find_name(const CryptomatteSession *session, const float encoded_hash, char *r_name, @@ -489,10 +488,6 @@ std::string BKE_cryptomatte_meta_data_key(const StringRef layer_name, const Stri return "cryptomatte/" + cryptomatte_layer_name_hash(layer_name) + "/" + key_name; } -/* Extracts the cryptomatte name from a render pass name. - * - * Example: A render pass could be named `CryptoObject00`. This - * function would remove the trailing digits and return `CryptoObject`. */ StringRef BKE_cryptomatte_extract_layer_name(const StringRef render_pass_name) { int64_t last_token = render_pass_name.size(); @@ -525,16 +520,6 @@ std::string CryptomatteHash::hex_encoded() const return encoded.str(); } -/* Convert a cryptomatte hash to a float. - * - * Cryptomatte hashes are stored in float textures and images. The conversion is taken from the - * cryptomatte specification. See Floating point conversion section in - * https://github.com/Psyop/Cryptomatte/blob/master/specification/cryptomatte_specification.pdf. - * - * The conversion uses as many 32 bit floating point values as possible to minimize hash - * collisions. Unfortunately not all 32 bits can be used as NaN and Inf can be problematic. - * - * Note that this conversion assumes to be running on a L-endian system. */ float CryptomatteHash::float_encoded() const { uint32_t mantissa = hash & ((1 << 23) - 1); @@ -626,7 +611,6 @@ void CryptomatteStampDataCallbackData::extract_layer_names(void *_data, data->hash_to_layer_name.add(layer_hash, propvalue); } -/* C type callback function (StampCallback). */ void CryptomatteStampDataCallbackData::extract_layer_manifest(void *_data, const char *propname, char *propvalue, diff --git a/source/blender/blenkernel/intern/curve.c b/source/blender/blenkernel/intern/curve.c index e82773a0074..2f1b01316a1 100644 --- a/source/blender/blenkernel/intern/curve.c +++ b/source/blender/blenkernel/intern/curve.c @@ -333,7 +333,6 @@ IDTypeInfo IDType_ID_CU = { .lib_override_apply_post = NULL, }; -/* frees editcurve entirely */ void BKE_curve_editfont_free(Curve *cu) { if (cu->editfont) { @@ -424,7 +423,6 @@ Curve *BKE_curve_add(Main *bmain, const char *name, int type) return cu; } -/* Get list of nurbs from editnurbs structure */ ListBase *BKE_curve_editNurbs_get(Curve *cu) { if (cu->editnurb) { @@ -697,7 +695,6 @@ Nurb *BKE_nurb_duplicate(const Nurb *nu) return newnu; } -/* copy the nurb but allow for different number of points (to be copied after this) */ Nurb *BKE_nurb_copy(Nurb *src, int pntsu, int pntsv) { Nurb *newnu = (Nurb *)MEM_mallocN(sizeof(Nurb), "copyNurb"); @@ -759,10 +756,6 @@ void BKE_nurb_project_2d(Nurb *nu) } } -/** - * if use_radius is truth, minmax will take points' radius into account, - * which will make boundbox closer to beveled curve. - */ void BKE_nurb_minmax(const Nurb *nu, bool use_radius, float min[3], float max[3]) { BezTriple *bezt; @@ -916,7 +909,6 @@ float BKE_nurb_calc_length(const Nurb *nu, int resolution) return length; } -/* be sure to call makeknots after this */ void BKE_nurb_points_add(Nurb *nu, int number) { nu->bp = MEM_recallocN(nu->bp, (nu->pntsu + number) * sizeof(BPoint)); @@ -1376,9 +1368,6 @@ static void basisNurb( } } -/** - * \param coord_array: has to be (3 * 4 * resolu * resolv) in size, and zero-ed. - */ void BKE_nurb_makeFaces(const Nurb *nu, float *coord_array, int rowstride, int resolu, int resolv) { BPoint *bp; @@ -1571,11 +1560,6 @@ void BKE_nurb_makeFaces(const Nurb *nu, float *coord_array, int rowstride, int r MEM_freeN(jend); } -/** - * \param coord_array: Has to be 3 * 4 * pntsu * resolu in size and zero-ed - * \param tilt_array: set when non-NULL - * \param radius_array: set when non-NULL - */ void BKE_nurb_makeCurve(const Nurb *nu, float *coord_array, float *tilt_array, @@ -1712,9 +1696,6 @@ void BKE_nurb_makeCurve(const Nurb *nu, MEM_freeN(basisu); } -/** - * Calculate the length for arrays filled in by #BKE_curve_calc_coords_axis. - */ unsigned int BKE_curve_calc_coords_axis_len(const unsigned int bezt_array_len, const unsigned int resolu, const bool is_cyclic, @@ -1726,12 +1707,6 @@ unsigned int BKE_curve_calc_coords_axis_len(const unsigned int bezt_array_len, return points_len; } -/** - * Calculate an array for the entire curve (cyclic or non-cyclic). - * \note Call for each axis. - * - * \param use_cyclic_duplicate_endpoint: Duplicate values at the beginning & end of the array. - */ void BKE_curve_calc_coords_axis(const BezTriple *bezt_array, const unsigned int bezt_array_len, const unsigned int resolu, @@ -1788,7 +1763,6 @@ void BKE_curve_calc_coords_axis(const BezTriple *bezt_array, UNUSED_VARS_NDEBUG(points_len); } -/* forward differencing method for bezier curve */ void BKE_curve_forward_diff_bezier( float q0, float q1, float q2, float q3, float *p, int it, int stride) { @@ -1817,7 +1791,6 @@ void BKE_curve_forward_diff_bezier( } } -/* forward differencing method for first derivative of cubic bezier curve */ void BKE_curve_forward_diff_tangent_bezier( float q0, float q1, float q2, float q3, float *p, int it, int stride) { @@ -4048,23 +4021,12 @@ void BKE_nurb_handle_smooth_fcurve(BezTriple *bezt, int total, bool cyclic) } } -/** - * Recalculate the handles of a nurb bezier-triple. Acts based on handle selection with `SELECT` - * flag. To use a different flag, use #BKE_nurb_handle_calc_ex(). - */ void BKE_nurb_handle_calc( BezTriple *bezt, BezTriple *prev, BezTriple *next, const bool is_fcurve, const char smoothing) { calchandleNurb_intern(bezt, prev, next, SELECT, is_fcurve, false, smoothing); } -/** - * Variant of #BKE_nurb_handle_calc() that allows calculating based on a different select flag. - * - * \param handle_sel_flag: The flag (bezt.f1/2/3) value to use to determine selection. - * Usually #SELECT, but may want to use a different one at times - * (if caller does not operate on selection). - */ void BKE_nurb_handle_calc_ex(BezTriple *bezt, BezTriple *prev, BezTriple *next, @@ -4105,8 +4067,6 @@ static void nurb_handles_calc__align_selected(Nurb *nu) nurbList_handles_swap_select(nu); } -/* similar to BKE_nurb_handle_calc but for curves and - * figures out the previous and next for us */ void BKE_nurb_handle_calc_simple(Nurb *nu, BezTriple *bezt) { if (nu->pntsu > 1) { @@ -4131,19 +4091,6 @@ void BKE_nurb_handle_calc_simple_auto(Nurb *nu, BezTriple *bezt) } } -/** - * Update selected handle types to ensure valid state, e.g. deduce "Auto" types to concrete ones. - * Thereby \a sel_flag defines what qualifies as selected. - * Use when something has changed handle positions. - * - * The caller needs to recalculate handles. - * - * \param sel_flag: The flag (bezt.f1/2/3) value to use to determine selection. Usually `SELECT`, - * but may want to use a different one at times (if caller does not operate on - * selection). - * \param use_handle: Check selection state of individual handles, otherwise always update both - * handles if the key is selected. - */ void BKE_nurb_bezt_handle_test(BezTriple *bezt, const eBezTriple_Flag__Alias sel_flag, const bool use_handle, @@ -4307,15 +4254,6 @@ void BKE_nurbList_handles_autocalc(ListBase *editnurb, uint8_t flag) } } -/** - * \param code: - * - 1 (#HD_AUTO): set auto-handle. - * - 2 (#HD_VECT): set vector-handle. - * - 3 (#HD_ALIGN) it toggle, vector-handles become #HD_FREE. - * - * - 5: Set align, like 3 but no toggle. - * - 6: Clear align (setting #HD_FREE), like 3 but no toggle. - */ void BKE_nurbList_handles_set(ListBase *editnurb, const char code) { BezTriple *bezt; @@ -4493,9 +4431,6 @@ void BKE_nurbList_flag_set(ListBase *editnurb, uint8_t flag, bool set) } } -/** - * Set \a flag for every point that already has \a from_flag set. - */ bool BKE_nurbList_flag_set_from_flag(ListBase *editnurb, uint8_t from_flag, uint8_t flag) { bool changed = false; @@ -4912,9 +4847,6 @@ bool BKE_nurb_order_clamp_v(struct Nurb *nu) return changed; } -/** - * \note caller must ensure active vertex remains valid. - */ bool BKE_nurb_type_convert(Nurb *nu, const short type, const bool use_handles, @@ -5058,7 +4990,6 @@ bool BKE_nurb_type_convert(Nurb *nu, return true; } -/* Get edit nurbs or normal nurbs list */ ListBase *BKE_curve_nurbs_get(Curve *cu) { if (cu->editnurb) { @@ -5095,7 +5026,6 @@ Nurb *BKE_curve_nurb_active_get(Curve *cu) return BLI_findlink(nurbs, cu->actnu); } -/* Get active vert for curve */ void *BKE_curve_vert_active_get(Curve *cu) { Nurb *nu = NULL; @@ -5116,7 +5046,6 @@ int BKE_curve_nurb_vert_index_get(const Nurb *nu, const void *vert) return (BPoint *)vert - nu->bp; } -/* Set active nurb and active vert for curve */ void BKE_curve_nurb_vert_active_set(Curve *cu, const Nurb *nu, const void *vert) { if (nu) { @@ -5134,7 +5063,6 @@ void BKE_curve_nurb_vert_active_set(Curve *cu, const Nurb *nu, const void *vert) } } -/* Get points to the active nurb and active vert for curve. */ bool BKE_curve_nurb_vert_active_get(Curve *cu, Nurb **r_nu, void **r_vert) { Nurb *nu = NULL; @@ -5187,7 +5115,6 @@ void BKE_curve_nurb_vert_active_validate(Curve *cu) } } -/* basic vertex data functions */ bool BKE_curve_minmax(Curve *cu, bool use_radius, float min[3], float max[3]) { ListBase *nurb_lb = BKE_curve_nurbs_get(cu); @@ -5553,8 +5480,6 @@ void BKE_curve_rect_from_textbox(const struct Curve *cu, r_rect->ymin = r_rect->ymax - tb->h; } -/* This function is almost the same as BKE_fcurve_correct_bezpart(), but doesn't allow as large a - * tangent. */ void BKE_curve_correct_bezpart(const float v1[2], float v2[2], float v3[2], const float v4[2]) { float h1[2], h2[2], len1, len2, len, fac; diff --git a/source/blender/blenkernel/intern/curve_deform.c b/source/blender/blenkernel/intern/curve_deform.c index b8b8506d681..d754f8cc27d 100644 --- a/source/blender/blenkernel/intern/curve_deform.c +++ b/source/blender/blenkernel/intern/curve_deform.c @@ -410,12 +410,6 @@ void BKE_curve_deform_coords_with_editmesh(const Object *ob_curve, em_target); } -/** - * \param orco: Input vec and orco = local coord in curve space - * orco is original not-animated or deformed reference point. - * - * The result written in vec and r_mat. - */ void BKE_curve_deform_co(const Object *ob_curve, const Object *ob_target, const float orco[3], diff --git a/source/blender/blenkernel/intern/curve_to_mesh_convert.cc b/source/blender/blenkernel/intern/curve_to_mesh_convert.cc index 03525e32a52..5522a84d094 100644 --- a/source/blender/blenkernel/intern/curve_to_mesh_convert.cc +++ b/source/blender/blenkernel/intern/curve_to_mesh_convert.cc @@ -691,16 +691,6 @@ static void copy_spline_domain_attributes_to_mesh(const CurveEval &curve, } } -/** - * Extrude all splines in the profile curve along the path of every spline in the curve input. - * Transfer curve attributes to the mesh. - * - * \note Normal calculation is by far the slowest part of calculations relating to the result mesh. - * Although it would be a sensible decision to use the better topology information available while - * generating the mesh to also generate the normals, that work may wasted if the output mesh is - * changed anyway in a way that affects the normals. So currently this code uses the safer / - * simpler solution of deferring normal calculation to the rest of Blender. - */ Mesh *curve_to_mesh_sweep(const CurveEval &curve, const CurveEval &profile, const bool fill_caps) { Span profiles = profile.splines(); @@ -776,10 +766,6 @@ static CurveEval get_curve_single_vert() return curve; } -/** - * Create a loose-edge mesh based on the evaluated path of the curve's splines. - * Transfer curve attributes to the mesh. - */ Mesh *curve_to_wire_mesh(const CurveEval &curve) { static const CurveEval vert_curve = get_curve_single_vert(); diff --git a/source/blender/blenkernel/intern/curveprofile.cc b/source/blender/blenkernel/intern/curveprofile.cc index 7f2a2bc342d..387709fca29 100644 --- a/source/blender/blenkernel/intern/curveprofile.cc +++ b/source/blender/blenkernel/intern/curveprofile.cc @@ -44,9 +44,6 @@ /** \name Data Handling * \{ */ -/** - * Returns a pointer to a newly allocated curve profile, using the given preset. - */ struct CurveProfile *BKE_curveprofile_add(eCurveProfilePresets preset) { CurveProfile *profile = (CurveProfile *)MEM_callocN(sizeof(CurveProfile), __func__); @@ -104,7 +101,6 @@ void BKE_curveprofile_blend_write(struct BlendWriter *writer, const struct Curve BLO_write_struct_array(writer, CurveProfilePoint, profile->path_len, profile->path); } -/* Expects that the curve profile itself has been read already. */ void BKE_curveprofile_blend_read(struct BlendDataReader *reader, struct CurveProfile *profile) { BLO_read_data_address(reader, &profile->path); @@ -125,14 +121,6 @@ void BKE_curveprofile_blend_read(struct BlendDataReader *reader, struct CurvePro /** \name Editing * \{ */ -/** - * Move a point's handle, accounting for the alignment of handles with the #HD_ALIGN type. - * - * \param handle_1: Whether to move the 1st or 2nd control point. - * \param delta: The *relative* change in the handle's position. - * \note Requires #BKE_curveprofile_update call after. - * \return Whether the handle moved from its start position. - */ bool BKE_curveprofile_move_handle(struct CurveProfilePoint *point, const bool handle_1, const bool snap, @@ -173,14 +161,6 @@ bool BKE_curveprofile_move_handle(struct CurveProfilePoint *point, return false; } -/** - * Moves a control point, accounting for clipping and snapping, and moving free handles. - * - * \param snap: Whether to snap the point to the grid - * \param delta: The *relative* change of the point's location. - * \return Whether the point moved from its start position. - * \note Requires #BKE_curveprofile_update call after. - */ bool BKE_curveprofile_move_point(struct CurveProfile *profile, struct CurveProfilePoint *point, const bool snap, @@ -228,10 +208,6 @@ bool BKE_curveprofile_move_point(struct CurveProfile *profile, return false; } -/** - * Removes a specific point from the path of control points. - * \note Requires #BKE_curveprofile_update call after. - */ bool BKE_curveprofile_remove_point(CurveProfile *profile, CurveProfilePoint *point) { /* Must have 2 points minimum. */ @@ -262,13 +238,6 @@ bool BKE_curveprofile_remove_point(CurveProfile *profile, CurveProfilePoint *poi return true; } -/** - * Removes every point in the widget with the supplied flag set, except for the first and last. - * - * \param flag: #CurveProfilePoint.flag. - * - * \note Requires #BKE_curveprofile_update call after. - */ void BKE_curveprofile_remove_by_flag(CurveProfile *profile, const short flag) { /* Copy every point without the flag into the new path. */ @@ -308,13 +277,6 @@ static void point_init(CurveProfilePoint *point, float x, float y, short flag, c point->h2 = h2; } -/** - * Adds a new point at the specified location. The choice for which points to place the new vertex - * between is made by checking which control point line segment is closest to the new point and - * placing the new vertex in between that segment's points. - * - * \note Requires #BKE_curveprofile_update call after. - */ CurveProfilePoint *BKE_curveprofile_insert(CurveProfile *profile, float x, float y) { const float new_loc[2] = {x, y}; @@ -370,11 +332,6 @@ CurveProfilePoint *BKE_curveprofile_insert(CurveProfile *profile, float x, float return new_pt; } -/** - * Sets the handle type of the selected control points. - * \param type_1, type_2: Handle type for the first handle. HD_VECT, HD_AUTO, HD_FREE, or HD_ALIGN. - * \note Requires #BKE_curveprofile_update call after. - */ void BKE_curveprofile_selected_handle_set(CurveProfile *profile, int type_1, int type_2) { for (int i = 0; i < profile->path_len; i++) { @@ -397,11 +354,6 @@ static CurveProfilePoint mirror_point(const CurveProfilePoint *point) return new_point; } -/** - * Flips the profile across the diagonal so that its orientation is reversed. - * - * \note Requires #BKE_curveprofile_update call after. - */ void BKE_curveprofile_reverse(CurveProfile *profile) { /* When there are only two points, reversing shouldn't do anything. */ @@ -478,19 +430,11 @@ static void curveprofile_build_steps(CurveProfile *profile) } } -/** - * Reset the view to the clipping rectangle. - */ void BKE_curveprofile_reset_view(CurveProfile *profile) { profile->view_rect = profile->clip_rect; } -/** - * Resets the profile to the current preset. - * - * \note Requires #BKE_curveprofile_update call after. - */ void BKE_curveprofile_reset(CurveProfile *profile) { MEM_SAFE_FREE(profile->path); @@ -871,10 +815,6 @@ static void create_samples(CurveProfile *profile, MEM_freeN(n_samples); } -/** - * Sets the default settings and clip range for the profile widget. - * Does not generate either table. - */ void BKE_curveprofile_set_defaults(CurveProfile *profile) { profile->flag = PROF_USE_CLIP; @@ -895,12 +835,6 @@ void BKE_curveprofile_set_defaults(CurveProfile *profile) profile->changed_timestamp = 0; } -/** - * Refreshes the higher resolution table sampled from the input points. A call to this or - * #BKE_curveprofile_update is needed before evaluation functions that use the table. - * Also sets the number of segments used for the display preview of the locations - * of the sampled points. - */ void BKE_curveprofile_init(CurveProfile *profile, short segments_len) { if (segments_len != profile->segments_len) { @@ -1044,12 +978,6 @@ static void curveprofile_make_segments_table(CurveProfile *profile) profile->segments = new_table; } -/** - * Should be called after the widget is changed. Does profile and remove double checks and more - * importantly, recreates the display / evaluation and segments tables. - * \param update_flags: Bitfield with fields defined in header file. Controls removing doubles and - * clipping. - */ void BKE_curveprofile_update(CurveProfile *profile, const int update_flags) { CurveProfilePoint *points = profile->path; @@ -1105,13 +1033,6 @@ void BKE_curveprofile_update(CurveProfile *profile, const int update_flags) } } -/** - * Does a single evaluation along the profile's path. - * Travels down (length_portion * path) length and returns the position at that point. - * - * \param length_portion: The portion (0 to 1) of the path's full length to sample at. - * \note Requires #BKE_curveprofile_init or #BKE_curveprofile_update call before to fill table. - */ void BKE_curveprofile_evaluate_length_portion(const CurveProfile *profile, float length_portion, float *x_out, diff --git a/source/blender/blenkernel/intern/customdata.c b/source/blender/blenkernel/intern/customdata.c index 743d5471aa7..090de26c230 100644 --- a/source/blender/blenkernel/intern/customdata.c +++ b/source/blender/blenkernel/intern/customdata.c @@ -73,7 +73,6 @@ BLI_STATIC_ASSERT(ARRAY_SIZE(((CustomData *)NULL)->typemap) == CD_NUMTYPES, "siz static CLG_LogRef LOG = {"bke.customdata"}; -/** Update mask_dst with layers defined in mask_src (equivalent to a bitwise OR). */ void CustomData_MeshMasks_update(CustomData_MeshMasks *mask_dst, const CustomData_MeshMasks *mask_src) { @@ -84,7 +83,6 @@ void CustomData_MeshMasks_update(CustomData_MeshMasks *mask_dst, mask_dst->lmask |= mask_src->lmask; } -/** Return True if all layers set in \a mask_required are also set in \a mask_ref */ bool CustomData_MeshMasks_are_matching(const CustomData_MeshMasks *mask_ref, const CustomData_MeshMasks *mask_required) { @@ -2182,7 +2180,6 @@ bool CustomData_merge(const struct CustomData *source, return changed; } -/* NOTE: Take care of referenced layers by yourself! */ void CustomData_realloc(CustomData *data, int totelem) { for (int i = 0; i < data->totlayer; i++) { @@ -2444,8 +2441,6 @@ void CustomData_set_layer_stencil(CustomData *data, int type, int n) } } -/* For using with an index from CustomData_get_active_layer_index and - * CustomData_get_render_layer_index. */ void CustomData_set_layer_active_index(CustomData *data, int type, int n) { for (int i = 0; i < data->totlayer; i++) { @@ -2648,7 +2643,6 @@ void *CustomData_add_layer( return NULL; } -/* Same as above but accepts a name. */ void *CustomData_add_layer_named(CustomData *data, int type, eCDAllocType alloctype, @@ -3068,18 +3062,6 @@ void CustomData_free_elem(CustomData *data, int index, int count) #define SOURCE_BUF_SIZE 100 -/** - * Interpolate given custom data source items into a single destination one. - * - * \param src_indices: Indices of every source items to interpolate into the destination one. - * \param weights: The weight to apply to each source value individually. If NULL, they will be - * averaged. - * \param sub_weights: The weights of sub-items, only used to affect each corners of a - * tessellated face data (should always be and array of four values). - * \param count: The number of source items to interpolate. - * \param dest_index: Index of the destination item, in which to put the result of the - * interpolation. - */ void CustomData_interp(const CustomData *source, CustomData *dest, const int *src_indices, @@ -3162,13 +3144,6 @@ void CustomData_interp(const CustomData *source, } } -/** - * Swap data inside each item, for all layers. - * This only applies to item types that may store several sub-item data - * (e.g. corner data [UVs, VCol, ...] of tessellated faces). - * - * \param corner_indices: A mapping 'new_index -> old_index' of sub-item data. - */ void CustomData_swap_corners(struct CustomData *data, int index, const int *corner_indices) { for (int i = 0; i < data->totlayer; i++) { @@ -3182,9 +3157,6 @@ void CustomData_swap_corners(struct CustomData *data, int index, const int *corn } } -/** - * Swap two items of given custom data, in all available layers. - */ void CustomData_swap(struct CustomData *data, const int index_a, const int index_b) { char buff_static[256]; @@ -3362,7 +3334,7 @@ void CustomData_set(const CustomData *data, int index, int type, const void *sou } /* BMesh functions */ -/* needed to convert to/from different face reps */ + void CustomData_to_bmeshpoly(CustomData *fdata, CustomData *ldata, int totloop) { for (int i = 0; i < fdata->totlayer; i++) { @@ -3418,12 +3390,6 @@ void CustomData_from_bmeshpoly(CustomData *fdata, CustomData *ldata, int total) } #ifndef NDEBUG -/** - * Debug check, used to assert when we expect layers to be in/out of sync. - * - * \param fallback: Use when there are no layers to handle, - * since callers may expect success or failure. - */ bool CustomData_from_bmeshpoly_test(CustomData *fdata, CustomData *ldata, bool fallback) { int a_num = 0, b_num = 0; @@ -3491,11 +3457,6 @@ void CustomData_bmesh_update_active_layers(CustomData *fdata, CustomData *ldata) } } -/* update active indices for active/render/clone/stencil custom data layers - * based on indices from fdata layers - * used by do_versions in readfile.c when creating pdata and ldata for pre-bmesh - * meshes and needed to preserve active/render/clone/stencil flags set in pre-bmesh files - */ void CustomData_bmesh_do_versions_update_active_layers(CustomData *fdata, CustomData *ldata) { int act; @@ -3677,9 +3638,6 @@ void CustomData_bmesh_free_block(CustomData *data, void **block) *block = NULL; } -/** - * Same as #CustomData_bmesh_free_block but zero the memory rather than freeing. - */ void CustomData_bmesh_free_block_data(CustomData *data, void *block) { if (block == NULL) { @@ -3713,9 +3671,6 @@ static void CustomData_bmesh_alloc_block(CustomData *data, void **block) } } -/** - * A selective version of #CustomData_bmesh_free_block_data. - */ void CustomData_bmesh_free_block_data_exclude_by_type(CustomData *data, void *block, const CustomDataMask mask_exclude) @@ -3832,9 +3787,6 @@ void CustomData_bmesh_copy_data(const CustomData *source, CustomData_bmesh_copy_data_exclude_by_type(source, dest, src_block, dest_block, 0); } -/* BMesh Custom Data Functions. - * Should replace edit-mesh ones with these as well, due to more efficient memory alloc. - */ void *CustomData_bmesh_get(const CustomData *data, void *block, int type) { /* get the layer index of the first layer of type */ @@ -3857,7 +3809,6 @@ void *CustomData_bmesh_get_n(const CustomData *data, void *block, int type, int return POINTER_OFFSET(block, data->layers[layer_index + n].offset); } -/* Gets from the layer at physical index n, NOTE: doesn't check type. */ void *CustomData_bmesh_get_layer_n(const CustomData *data, void *block, int n) { if (n < 0 || n >= data->totlayer) { @@ -3902,7 +3853,6 @@ bool CustomData_has_math(const struct CustomData *data) return false; } -/* a non bmesh version would have to check layer->data */ bool CustomData_bmesh_has_free(const struct CustomData *data) { for (int i = 0; i < data->totlayer; i++) { @@ -3938,8 +3888,6 @@ bool CustomData_has_referenced(const struct CustomData *data) return false; } -/* copies the "value" (e.g. mloopuv uv or mloopcol colors) from one block to - * another, while not overwriting anything else (e.g. flags). */ void CustomData_data_copy_value(int type, const void *source, void *dest) { const LayerTypeInfo *typeInfo = layerType_getInfo(type); @@ -3956,8 +3904,6 @@ void CustomData_data_copy_value(int type, const void *source, void *dest) } } -/* Mixes the "value" (e.g. mloopuv uv or mloopcol colors) from one block into - * another, while not overwriting anything else (e.g. flags). */ void CustomData_data_mix_value( int type, const void *source, void *dest, const int mixmode, const float mixfactor) { @@ -4074,10 +4020,6 @@ void CustomData_bmesh_set_layer_n(CustomData *data, void *block, int n, const vo } } -/** - * \note src_blocks_ofs & dst_block_ofs - * must be pointers to the data, offset by layer->offset already. - */ void CustomData_bmesh_interp_n(CustomData *data, const void **src_blocks_ofs, const float *weights, @@ -4146,11 +4088,6 @@ void CustomData_bmesh_interp(CustomData *data, } } -/** - * \param use_default_init: initializes data which can't be copied, - * typically you'll want to use this if the BM_xxx create function - * is called with BM_CREATE_SKIP_CD flag - */ void CustomData_to_bmesh_block(const CustomData *source, CustomData *dest, int src_index, @@ -4265,25 +4202,6 @@ void CustomData_file_write_info(int type, const char **r_struct_name, int *r_str *r_struct_num = typeInfo->structnum; } -/** - * Prepare given custom data for file writing. - * - * \param data: the customdata to tweak for .blend file writing (modified in place). - * \param r_write_layers: contains a reduced set of layers to be written to file, - * use it with writestruct_at_address() - * (caller must free it if != \a write_layers_buff). - * - * \param write_layers_buff: an optional buffer for r_write_layers (to avoid allocating it). - * \param write_layers_size: the size of pre-allocated \a write_layer_buff. - * - * \warning After this func has ran, given custom data is no more valid from Blender PoV - * (its totlayer is invalid). This func shall always be called with localized data - * (as it is in write_meshes()). - * - * \note data->typemap is not updated here, since it is always rebuilt on file read anyway. - * This means written typemap does not match written layers (as returned by \a r_write_layers). - * Trivial to fix is ever needed. - */ void CustomData_blend_write_prepare(CustomData *data, CustomDataLayer **r_write_layers, CustomDataLayer *write_layers_buff, @@ -4337,20 +4255,12 @@ const char *CustomData_layertype_name(int type) return layerType_getName(type); } -/** - * Can only ever be one of these. - */ bool CustomData_layertype_is_singleton(int type) { const LayerTypeInfo *typeInfo = layerType_getInfo(type); return typeInfo->defaultname == NULL; } -/** - * Has dynamically allocated members. - * This is useful to know if operations such as #memcmp are - * valid when comparing data from two layers. - */ bool CustomData_layertype_is_dynamic(int type) { const LayerTypeInfo *typeInfo = layerType_getInfo(type); @@ -4358,9 +4268,6 @@ bool CustomData_layertype_is_dynamic(int type) return (typeInfo->free != NULL); } -/** - * \return Maximum number of layers of given \a type, -1 means 'no limit'. - */ int CustomData_layertype_layers_max(const int type) { const LayerTypeInfo *typeInfo = layerType_getInfo(type); @@ -4502,12 +4409,6 @@ bool CustomData_verify_versions(struct CustomData *data, int index) return keeplayer; } -/** - * Validate and fix data of \a layer, - * if possible (needs relevant callback in layer's type to be defined). - * - * \return True if some errors were found. - */ bool CustomData_layer_validate(CustomDataLayer *layer, const uint totitems, const bool do_fixes) { const LayerTypeInfo *typeInfo = layerType_getInfo(layer->type); @@ -4971,7 +4872,6 @@ static void customdata_data_transfer_interp_generic(const CustomDataTransferLaye MEM_freeN(tmp_dst); } -/* Normals are special, we need to take care of source & destination spaces... */ void customdata_data_transfer_interp_normal_normals(const CustomDataTransferLayerMap *laymap, void *data_dst, const void **sources, @@ -5118,9 +5018,6 @@ static void write_grid_paint_mask(BlendWriter *writer, int count, GridPaintMask } } -/** - * \param layers: The layers argument assigned by #CustomData_blend_write_prepare. - */ void CustomData_blend_write(BlendWriter *writer, CustomData *data, CustomDataLayer *layers, diff --git a/source/blender/blenkernel/intern/data_transfer.c b/source/blender/blenkernel/intern/data_transfer.c index b83621e8b79..f036f1ced87 100644 --- a/source/blender/blenkernel/intern/data_transfer.c +++ b/source/blender/blenkernel/intern/data_transfer.c @@ -93,10 +93,6 @@ void BKE_object_data_transfer_dttypes_to_cdmask(const int dtdata_types, } } -/** - * Check what can do each layer type - * (if it is actually handled by transfer-data, if it supports advanced mixing. - */ bool BKE_object_data_transfer_get_dttypes_capacity(const int dtdata_types, bool *r_advanced_mixing, bool *r_threshold) @@ -1232,12 +1228,6 @@ static bool data_transfer_layersmapping_generate(ListBase *r_map, return false; } -/** - * Transfer data *layout* of selected types from source to destination object. - * By default, it only creates new data layers if needed on \a ob_dst. - * If \a use_delete is true, it will also delete data layers on \a ob_dst that do not match those - * from \a ob_src, to get (as much as possible) exact copy of source data layout. - */ void BKE_object_data_transfer_layout(struct Depsgraph *depsgraph, Scene *scene, Object *ob_src, diff --git a/source/blender/blenkernel/intern/data_transfer_intern.h b/source/blender/blenkernel/intern/data_transfer_intern.h index c5d7dd42cb8..e40b4946f52 100644 --- a/source/blender/blenkernel/intern/data_transfer_intern.h +++ b/source/blender/blenkernel/intern/data_transfer_intern.h @@ -68,6 +68,10 @@ bool data_transfer_layersmapping_vgroups(struct ListBase *r_map, const int tolayers); /* Defined in customdata.c */ + +/** + * Normals are special, we need to take care of source & destination spaces. + */ void customdata_data_transfer_interp_normal_normals(const CustomDataTransferLayerMap *laymap, void *data_dst, const void **sources, diff --git a/source/blender/blenkernel/intern/deform.c b/source/blender/blenkernel/intern/deform.c index 6bba6a9caec..6b429a146d4 100644 --- a/source/blender/blenkernel/intern/deform.c +++ b/source/blender/blenkernel/intern/deform.c @@ -107,11 +107,6 @@ bDeformGroup *BKE_defgroup_duplicate(const bDeformGroup *ingroup) return outgroup; } -/** - * Overwrite weights filtered by vgroup_subset. - * - do nothing if neither are set. - * - add destination weight if needed - */ void BKE_defvert_copy_subset(MDeformVert *dvert_dst, const MDeformVert *dvert_src, const bool *vgroup_subset, @@ -125,11 +120,6 @@ void BKE_defvert_copy_subset(MDeformVert *dvert_dst, } } -/** - * Overwrite weights filtered by vgroup_subset and with mirroring specified by the flip map - * - do nothing if neither are set. - * - add destination weight if needed - */ void BKE_defvert_mirror_subset(MDeformVert *dvert_dst, const MDeformVert *dvert_src, const bool *vgroup_subset, @@ -168,11 +158,6 @@ void BKE_defvert_copy(MDeformVert *dvert_dst, const MDeformVert *dvert_src) } } -/** - * Copy an index from one dvert to another. - * - do nothing if neither are set. - * - add destination weight if needed. - */ void BKE_defvert_copy_index(MDeformVert *dvert_dst, const int defgroup_dst, const MDeformVert *dvert_src, @@ -197,10 +182,6 @@ void BKE_defvert_copy_index(MDeformVert *dvert_dst, } } -/** - * Only sync over matching weights, don't add or remove groups - * warning, loop within loop. - */ void BKE_defvert_sync(MDeformVert *dvert_dst, const MDeformVert *dvert_src, const bool use_ensure) { if (dvert_src->totweight && dvert_dst->totweight) { @@ -221,9 +202,6 @@ void BKE_defvert_sync(MDeformVert *dvert_dst, const MDeformVert *dvert_src, cons } } -/** - * be sure all flip_map values are valid - */ void BKE_defvert_sync_mapped(MDeformVert *dvert_dst, const MDeformVert *dvert_src, const int *flip_map, @@ -250,9 +228,6 @@ void BKE_defvert_sync_mapped(MDeformVert *dvert_dst, } } -/** - * be sure all flip_map values are valid - */ void BKE_defvert_remap(MDeformVert *dvert, const int *map, const int map_len) { MDeformWeight *dw = dvert->dw; @@ -265,9 +240,6 @@ void BKE_defvert_remap(MDeformVert *dvert, const int *map, const int map_len) } } -/** - * Same as #BKE_defvert_normalize but takes a bool array. - */ void BKE_defvert_normalize_subset(MDeformVert *dvert, const bool *vgroup_subset, const int vgroup_tot) @@ -334,9 +306,6 @@ void BKE_defvert_normalize(MDeformVert *dvert) } } -/** - * Same as BKE_defvert_normalize() if the locked vgroup is not a member of the subset - */ void BKE_defvert_normalize_lock_single(MDeformVert *dvert, const bool *vgroup_subset, const int vgroup_tot, @@ -391,9 +360,6 @@ void BKE_defvert_normalize_lock_single(MDeformVert *dvert, } } -/** - * Same as BKE_defvert_normalize() if no locked vgroup is a member of the subset - */ void BKE_defvert_normalize_lock_map(MDeformVert *dvert, const bool *vgroup_subset, const int vgroup_tot, @@ -610,17 +576,11 @@ int BKE_object_defgroup_count(const Object *ob) return BLI_listbase_count(BKE_object_defgroup_list(ob)); } -/** - * \note For historical reasons, the index starts at 1 rather than 0. - */ int BKE_object_defgroup_active_index_get(const Object *ob) { return *object_defgroup_active_index_get_p(ob); } -/** - * \note For historical reasons, the index starts at 1 rather than 0. - */ void BKE_object_defgroup_active_index_set(Object *ob, const int new_index) { /* Cast away const just for the accessor. */ @@ -628,9 +588,6 @@ void BKE_object_defgroup_active_index_set(Object *ob, const int new_index) *index = new_index; } -/** - * \note caller must free. - */ int *BKE_object_defgroup_flip_map(const Object *ob, int *flip_map_len, const bool use_default) { const ListBase *defbase = BKE_object_defgroup_list(ob); @@ -670,9 +627,6 @@ int *BKE_object_defgroup_flip_map(const Object *ob, int *flip_map_len, const boo return map; } -/** - * \note caller must free. - */ int *BKE_object_defgroup_flip_map_single(const Object *ob, int *flip_map_len, const bool use_default, @@ -769,13 +723,6 @@ float BKE_defvert_find_weight(const struct MDeformVert *dvert, const int defgrou return dw ? dw->weight : 0.0f; } -/** - * Take care with this the rationale is: - * - if the object has no vertex group. act like vertex group isn't set and return 1.0, - * - if the vertex group exists but the 'defgroup' isn't found on this vertex, _still_ return 0.0 - * - * This is a bit confusing, just saves some checks from the caller. - */ float BKE_defvert_array_find_weight_safe(const struct MDeformVert *dvert, const int index, const int defgroup) @@ -814,11 +761,6 @@ MDeformWeight *BKE_defvert_find_index(const MDeformVert *dvert, const int defgro return NULL; } -/** - * Ensures that mv has a deform weight entry for the specified defweight group. - * - * \note this function is mirrored in editmesh_tools.c, for use for editvertices. - */ MDeformWeight *BKE_defvert_ensure_index(MDeformVert *dvert, const int defgroup) { MDeformWeight *dw_new; @@ -850,15 +792,10 @@ MDeformWeight *BKE_defvert_ensure_index(MDeformVert *dvert, const int defgroup) return dw_new; } -/* TODO: merge with code above! */ - -/** - * Adds the given vertex to the specified vertex group, with given weight. - * - * \warning this does NOT check for existing, assume caller already knows its not there. - */ void BKE_defvert_add_index_notest(MDeformVert *dvert, int defgroup, const float weight) { + /* TODO: merge with #BKE_defvert_ensure_index! */ + MDeformWeight *dw_new; /* do this check always, this function is used to check for it */ @@ -880,11 +817,6 @@ void BKE_defvert_add_index_notest(MDeformVert *dvert, int defgroup, const float dvert->totweight++; } -/** - * Removes the given vertex from the vertex group. - * - * \warning This function frees the given MDeformWeight, do not use it afterward! - */ void BKE_defvert_remove_group(MDeformVert *dvert, MDeformWeight *dw) { if (dvert && dw) { @@ -923,10 +855,6 @@ void BKE_defvert_clear(MDeformVert *dvert) dvert->totweight = 0; } -/** - * \return The first group index shared by both deform verts - * or -1 if none are found. - */ int BKE_defvert_find_shared(const MDeformVert *dvert_a, const MDeformVert *dvert_b) { if (dvert_a->totweight && dvert_b->totweight) { @@ -943,9 +871,6 @@ int BKE_defvert_find_shared(const MDeformVert *dvert_a, const MDeformVert *dvert return -1; } -/** - * return true if has no weights - */ bool BKE_defvert_is_weight_zero(const struct MDeformVert *dvert, const int defgroup_tot) { MDeformWeight *dw = dvert->dw; @@ -960,9 +885,6 @@ bool BKE_defvert_is_weight_zero(const struct MDeformVert *dvert, const int defgr return true; } -/** - * \return The total weight in all groups marked in the selection mask. - */ float BKE_defvert_total_selected_weight(const struct MDeformVert *dv, int defbase_tot, const bool *defbase_sel) @@ -985,14 +907,6 @@ float BKE_defvert_total_selected_weight(const struct MDeformVert *dv, return total; } -/** - * \return The representative weight of a multipaint group, used for - * viewport colors and actual painting. - * - * Result equal to sum of weights with auto normalize, and average otherwise. - * Value is not clamped, since painting relies on multiplication being always - * commutative with the collective weight function. - */ float BKE_defvert_multipaint_collective_weight(const struct MDeformVert *dv, int defbase_tot, const bool *defbase_sel, @@ -1010,11 +924,6 @@ float BKE_defvert_multipaint_collective_weight(const struct MDeformVert *dv, return total; } -/** - * Computes the display weight for the lock relative weight paint mode. - * - * \return weight divided by 1-locked_weight with division by zero check - */ float BKE_defvert_calc_lock_relative_weight(float weight, float locked_weight, float unlocked_weight) @@ -1043,11 +952,6 @@ float BKE_defvert_calc_lock_relative_weight(float weight, return weight / (1.0f - locked_weight); } -/** - * Computes the display weight for the lock relative weight paint mode, using weight data. - * - * \return weight divided by unlocked, or 1-locked_weight with division by zero check. - */ float BKE_defvert_lock_relative_weight(float weight, const struct MDeformVert *dv, int defbase_tot, @@ -1139,10 +1043,6 @@ void BKE_defvert_extract_vgroup_to_vertweights(MDeformVert *dvert, } } -/** - * The following three make basic interpolation, - * using temp vert_weights array to avoid looking up same weight several times. - */ void BKE_defvert_extract_vgroup_to_edgeweights(MDeformVert *dvert, const int defgroup, const int num_verts, diff --git a/source/blender/blenkernel/intern/displist.cc b/source/blender/blenkernel/intern/displist.cc index cae7a5fa65c..a8a7b5c5af3 100644 --- a/source/blender/blenkernel/intern/displist.cc +++ b/source/blender/blenkernel/intern/displist.cc @@ -402,12 +402,6 @@ static void curve_to_displist(const Curve *cu, } } -/** - * \param normal_proj: Optional normal that's used to project the scanfill verts into 2d coords. - * Pass this along if known since it saves time calculating the normal. - * This is also used to initialize #DispList.nors (one normal per display list). - * \param flipnormal: Flip the normal (same as passing \a normal_proj negated) - */ void BKE_displist_fill(const ListBase *dispbase, ListBase *to, const float normal_proj[3], diff --git a/source/blender/blenkernel/intern/dynamicpaint.c b/source/blender/blenkernel/intern/dynamicpaint.c index 05f1e9b286f..ce92a34de47 100644 --- a/source/blender/blenkernel/intern/dynamicpaint.c +++ b/source/blender/blenkernel/intern/dynamicpaint.c @@ -327,7 +327,6 @@ static int dynamicPaint_surfaceNumOfPoints(DynamicPaintSurface *surface) return 0; } -/* get currently active surface (in user interface) */ DynamicPaintSurface *get_activeSurface(DynamicPaintCanvasSettings *canvas) { return BLI_findlink(&canvas->surfaces, canvas->active_sur); @@ -420,7 +419,6 @@ void dynamicPaintSurface_setUniqueName(DynamicPaintSurface *surface, const char surface_duplicateNameExists, surface, name, '.', surface->name, sizeof(surface->name)); } -/* change surface data to defaults on new type */ void dynamicPaintSurface_updateType(struct DynamicPaintSurface *surface) { if (surface->format == MOD_DPAINT_SURFACE_F_IMAGESEQ) { @@ -855,7 +853,6 @@ static void surfaceGenerateGrid(struct DynamicPaintSurface *surface) /***************************** Freeing data ******************************/ -/* Free brush data */ void dynamicPaint_freeBrush(struct DynamicPaintModifierData *pmd) { if (pmd->brush) { @@ -992,7 +989,6 @@ void dynamicPaint_freeSurface(const DynamicPaintModifierData *pmd, DynamicPaintS MEM_freeN(surface); } -/* Free canvas data */ void dynamicPaint_freeCanvas(DynamicPaintModifierData *pmd) { if (pmd->canvas) { @@ -1011,7 +1007,6 @@ void dynamicPaint_freeCanvas(DynamicPaintModifierData *pmd) } } -/* Free whole dp modifier */ void dynamicPaint_Modifier_free(DynamicPaintModifierData *pmd) { if (pmd == NULL) { @@ -1024,11 +1019,6 @@ void dynamicPaint_Modifier_free(DynamicPaintModifierData *pmd) /***************************** Initialize and reset ******************************/ -/* - * Creates a new surface and adds it to the list - * If scene is null, frame range of 1-250 is used - * A pointer to this surface is returned - */ DynamicPaintSurface *dynamicPaint_createNewSurface(DynamicPaintCanvasSettings *canvas, Scene *scene) { @@ -1106,9 +1096,6 @@ DynamicPaintSurface *dynamicPaint_createNewSurface(DynamicPaintCanvasSettings *c return surface; } -/* - * Initialize modifier data - */ bool dynamicPaint_createType(struct DynamicPaintModifierData *pmd, int type, struct Scene *scene) { if (pmd) { @@ -1721,7 +1708,6 @@ static void dynamicPaint_setInitialColor(const Scene *scene, DynamicPaintSurface } } -/* clears surface data back to zero */ void dynamicPaint_clearSurface(const Scene *scene, DynamicPaintSurface *surface) { PaintSurfaceData *sData = surface->data; @@ -1751,7 +1737,6 @@ void dynamicPaint_clearSurface(const Scene *scene, DynamicPaintSurface *surface) } } -/* Completely (re)initializes surface (only for point cache types). */ bool dynamicPaint_resetSurface(const Scene *scene, DynamicPaintSurface *surface) { int numOfPoints = dynamicPaint_surfaceNumOfPoints(surface); @@ -2079,7 +2064,6 @@ static Mesh *dynamicPaint_Modifier_apply(DynamicPaintModifierData *pmd, Object * return result; } -/* update cache frame range */ void dynamicPaint_cacheUpdateFrames(DynamicPaintSurface *surface) { if (surface->pointcache) { @@ -2189,7 +2173,6 @@ static void dynamicPaint_frameUpdate(DynamicPaintModifierData *pmd, } } -/* Modifier call. Processes dynamic paint modifier step. */ Mesh *dynamicPaint_Modifier_do(DynamicPaintModifierData *pmd, struct Depsgraph *depsgraph, Scene *scene, @@ -6369,9 +6352,6 @@ static int dynamicPaint_doStep(Depsgraph *depsgraph, return ret; } -/** - * Calculate a single frame and included sub-frames for surface. - */ int dynamicPaint_calculateFrame(DynamicPaintSurface *surface, struct Depsgraph *depsgraph, Scene *scene, diff --git a/source/blender/blenkernel/intern/editmesh.c b/source/blender/blenkernel/intern/editmesh.c index 83e03ef44f5..805d3cdb5e3 100644 --- a/source/blender/blenkernel/intern/editmesh.c +++ b/source/blender/blenkernel/intern/editmesh.c @@ -39,10 +39,6 @@ #include "BKE_mesh_wrapper.h" #include "BKE_object.h" -/** - * \note The caller is responsible for ensuring triangulation data, - * typically by calling #BKE_editmesh_looptri_calc. - */ BMEditMesh *BKE_editmesh_create(BMesh *bm) { BMEditMesh *em = MEM_callocN(sizeof(BMEditMesh), __func__); @@ -75,12 +71,6 @@ BMEditMesh *BKE_editmesh_copy(BMEditMesh *em) return em_copy; } -/** - * \brief Return the BMEditMesh for a given object - * - * \note this function assumes this is a mesh object, - * don't add NULL data check here. caller must do that - */ BMEditMesh *BKE_editmesh_from_object(Object *ob) { BLI_assert(ob->type == OB_MESH); @@ -158,10 +148,6 @@ void BKE_editmesh_looptri_calc(BMEditMesh *em) }); } -/** - * Performing the face normal calculation at the same time as tessellation - * gives a reasonable performance boost (approx ~20% faster). - */ void BKE_editmesh_looptri_and_normals_calc(BMEditMesh *em) { BKE_editmesh_looptri_calc_ex(em, @@ -221,7 +207,6 @@ void BKE_editmesh_free_derived_caches(BMEditMesh *em) MEM_SAFE_FREE(em->bb_cage); } -/* Does not free the #BMEditMesh struct itself. */ void BKE_editmesh_free_data(BMEditMesh *em) { BKE_editmesh_free_derived_caches(em); @@ -342,7 +327,6 @@ void BKE_editmesh_lnorspace_update(BMEditMesh *em, Mesh *me) BM_lnorspace_update(bm); } -/* If autosmooth not already set, set it */ void BKE_editmesh_ensure_autosmooth(BMEditMesh *em, Mesh *me) { if (!(me->flag & ME_AUTOSMOOTH)) { diff --git a/source/blender/blenkernel/intern/editmesh_bvh.c b/source/blender/blenkernel/intern/editmesh_bvh.c index 5058863912f..e200a504b5d 100644 --- a/source/blender/blenkernel/intern/editmesh_bvh.c +++ b/source/blender/blenkernel/intern/editmesh_bvh.c @@ -565,9 +565,6 @@ static bool bmbvh_overlap_cb(void *userdata, int index_a, int index_b, int UNUSE ((verts_shared == 0) || (len_squared_v3v3(ix_pair[0], ix_pair[1]) > data->epsilon))); } -/** - * Overlap indices reference the looptri's - */ BVHTreeOverlap *BKE_bmbvh_overlap(const BMBVHTree *bmtree_a, const BMBVHTree *bmtree_b, unsigned int *r_overlap_tot) @@ -591,9 +588,6 @@ static bool bmbvh_overlap_self_cb(void *userdata, int index_a, int index_b, int return false; } -/** - * Overlap indices reference the looptri's - */ BVHTreeOverlap *BKE_bmbvh_overlap_self(const BMBVHTree *bmtree, unsigned int *r_overlap_tot) { struct BMBVHTree_OverlapData data; diff --git a/source/blender/blenkernel/intern/editmesh_tangent.c b/source/blender/blenkernel/intern/editmesh_tangent.c index da4ea742656..ff0d47e534e 100644 --- a/source/blender/blenkernel/intern/editmesh_tangent.c +++ b/source/blender/blenkernel/intern/editmesh_tangent.c @@ -273,13 +273,6 @@ static void emDM_calc_loop_tangents_thread(TaskPool *__restrict UNUSED(pool), vo } } -/** - * \see #BKE_mesh_calc_loop_tangent, same logic but used arrays instead of #BMesh data. - * - * \note This function is not so normal, its using #BMesh.ldata as input, - * but output's to #Mesh.ldata. - * This is done because #CD_TANGENT is cache data used only for drawing. - */ void BKE_editmesh_loop_tangent_calc(BMEditMesh *em, bool calc_active_tangent, const char (*tangent_names)[MAX_NAME], diff --git a/source/blender/blenkernel/intern/effect.c b/source/blender/blenkernel/intern/effect.c index a88339082fe..0a863c7e465 100644 --- a/source/blender/blenkernel/intern/effect.c +++ b/source/blender/blenkernel/intern/effect.c @@ -221,9 +221,6 @@ static void add_effector_evaluation(ListBase **effectors, precalculate_effector(depsgraph, eff); } -/* Create list of effector relations in the collection or entire scene. - * This is used by the depsgraph to build relations, as well as faster - * lookup of effectors during evaluation. */ ListBase *BKE_effector_relations_create(Depsgraph *depsgraph, ViewLayer *view_layer, Collection *collection) @@ -329,7 +326,6 @@ static bool is_effector_relevant(PartDeflect *pd, EffectorWeights *weights, bool is_effector_nonzero_strength(pd); } -/* Create effective list of effectors from relations built beforehand. */ ListBase *BKE_effectors_create(Depsgraph *depsgraph, Object *ob_src, ParticleSystem *psys_src, @@ -1130,20 +1126,6 @@ static void do_physical_effector(EffectorCache *eff, } } -/* -------- BKE_effectors_apply() -------- - * generic force/speed system, now used for particles and softbodies - * scene = scene where it runs in, for time and stuff - * lb = listbase with objects that take part in effecting - * opco = global coord, as input - * force = accumulator for force - * wind_force = accumulator for force only acting perpendicular to a surface - * speed = actual current speed which can be altered - * cur_time = "external" time in frames, is constant for static particles - * loc_time = "local" time in frames, range <0-1> for the lifetime of particle - * par_layer = layer the caller is in - * flags = only used for softbody wind now - * guide = old speed of particle - */ void BKE_effectors_apply(ListBase *effectors, ListBase *colliders, EffectorWeights *weights, @@ -1152,6 +1134,22 @@ void BKE_effectors_apply(ListBase *effectors, float *wind_force, float *impulse) { + /* WARNING(@campbellbarton): historic comment? + * Many of these parameters don't exist! + * + * scene = scene where it runs in, for time and stuff. + * lb = listbase with objects that take part in effecting. + * opco = global coord, as input. + * force = accumulator for force. + * wind_force = accumulator for force only acting perpendicular to a surface. + * speed = actual current speed which can be altered. + * cur_time = "external" time in frames, is constant for static particles. + * loc_time = "local" time in frames, range <0-1> for the lifetime of particle. + * par_layer = layer the caller is in. + * flags = only used for soft-body wind now. + * guide = old speed of particle. + */ + /* * Modifies the force on a particle according to its * relation with the effector object diff --git a/source/blender/blenkernel/intern/fcurve.c b/source/blender/blenkernel/intern/fcurve.c index bbf61c51bfb..5bbfc0913a1 100644 --- a/source/blender/blenkernel/intern/fcurve.c +++ b/source/blender/blenkernel/intern/fcurve.c @@ -77,7 +77,6 @@ FCurve *BKE_fcurve_create(void) /** \name F-Curve Data Free * \{ */ -/* Frees the F-Curve itself too, so make sure BLI_remlink is called before calling this... */ void BKE_fcurve_free(FCurve *fcu) { if (fcu == NULL) { @@ -99,7 +98,6 @@ void BKE_fcurve_free(FCurve *fcu) MEM_freeN(fcu); } -/* Frees a list of F-Curves. */ void BKE_fcurves_free(ListBase *list) { FCurve *fcu, *fcn; @@ -128,7 +126,6 @@ void BKE_fcurves_free(ListBase *list) /** \name F-Curve Data Copy * \{ */ -/* Duplicate a F-Curve. */ FCurve *BKE_fcurve_copy(const FCurve *fcu) { FCurve *fcu_d; @@ -161,7 +158,6 @@ FCurve *BKE_fcurve_copy(const FCurve *fcu) return fcu_d; } -/* Duplicate a list of F-Curves. */ void BKE_fcurves_copy(ListBase *dst, ListBase *src) { FCurve *dfcu, *sfcu; @@ -181,10 +177,6 @@ void BKE_fcurves_copy(ListBase *dst, ListBase *src) } } -/** - * Callback used by lib_query to walk over all ID usages (mimics `foreach_id` callback of - * `IDTypeInfo` structure). - */ void BKE_fcurve_foreach_id(FCurve *fcu, LibraryForeachIDData *data) { ChannelDriver *driver = fcu->driver; @@ -221,7 +213,6 @@ void BKE_fcurve_foreach_id(FCurve *fcu, LibraryForeachIDData *data) /* ----------------- Finding F-Curves -------------------------- */ -/* High level function to get an fcurve from C without having the RNA. */ FCurve *id_data_find_fcurve( ID *id, void *data, StructRNA *type, const char *prop_name, int index, bool *r_driven) { @@ -273,8 +264,6 @@ FCurve *id_data_find_fcurve( return fcu; } -/* Find the F-Curve affecting the given RNA-access path + index, - * in the list of F-Curves provided. */ FCurve *BKE_fcurve_find(ListBase *list, const char rna_path[], const int array_index) { FCurve *fcu; @@ -304,7 +293,6 @@ FCurve *BKE_fcurve_find(ListBase *list, const char rna_path[], const int array_i /** \name FCurve Iteration * \{ */ -/* Quick way to loop over all fcurves of a given 'path'. */ FCurve *BKE_fcurve_iter_step(FCurve *fcu_iter, const char rna_path[]) { FCurve *fcu; @@ -325,18 +313,6 @@ FCurve *BKE_fcurve_iter_step(FCurve *fcu_iter, const char rna_path[]) return NULL; } -/** - * Get list of LinkData's containing pointers to the F-Curves - * which control the types of data indicated. - * - * Lists... - * - dst: list of LinkData's matching the criteria returned. - * List must be freed after use, and is assumed to be empty when passed. - * - src: list of F-Curves to search through - * Filters... - * - dataPrefix: i.e. 'pose.bones[' or 'nodes[' - * - dataName: name of entity within "" immediately following the prefix - */ int BKE_fcurves_filter(ListBase *dst, ListBase *src, const char *dataPrefix, const char *dataName) { FCurve *fcu; @@ -601,9 +577,6 @@ static int BKE_fcurve_bezt_binarysearch_index_ex(const BezTriple array[], return start; } -/* Binary search algorithm for finding where to insert BezTriple. (for use by insert_bezt_fcurve) - * Returns the index to insert at (data already at that index will be offset if replace is 0) - */ int BKE_fcurve_bezt_binarysearch_index(const BezTriple array[], const float frame, const int arraylen, @@ -667,7 +640,6 @@ static short get_fcurve_end_keyframes(FCurve *fcu, return found; } -/* Calculate the extents of F-Curve's data. */ bool BKE_fcurve_calc_bounds(FCurve *fcu, float *xmin, float *xmax, @@ -798,7 +770,6 @@ bool BKE_fcurve_calc_bounds(FCurve *fcu, return foundvert; } -/* Calculate the extents of F-Curve's keyframes. */ bool BKE_fcurve_calc_range( FCurve *fcu, float *start, float *end, const bool do_sel_only, const bool do_min_length) { @@ -846,14 +817,6 @@ bool BKE_fcurve_calc_range( return foundvert; } -/** - * Return an array of keyed frames, rounded to `interval`. - * - * \param interval: Set to 1.0 to round to whole keyframes, 0.5 for in-between key-frames, etc. - * - * \note An interval of zero could be supported (this implies no rounding at all), - * however this risks very small differences in float values being treated as separate keyframes. - */ float *BKE_fcurves_calc_keyed_frames_ex(FCurve **fcurve_array, int fcurve_array_len, const float interval, @@ -902,10 +865,6 @@ float *BKE_fcurves_calc_keyed_frames(FCurve **fcurve_array, /** \name Active Keyframe * \{ */ -/** - * Set the index that stores the FCurve's active keyframe, assuming that \a active_bezt - * is already part of `fcu->bezt`. If NULL, set active keyframe index to "none." - */ void BKE_fcurve_active_keyframe_set(FCurve *fcu, const BezTriple *active_bezt) { if (active_bezt == NULL) { @@ -927,9 +886,6 @@ void BKE_fcurve_active_keyframe_set(FCurve *fcu, const BezTriple *active_bezt) fcu->active_keyframe_index = (int)offset; } -/** - * Get the active keyframe index, with sanity checks for point bounds. - */ int BKE_fcurve_active_keyframe_index(const FCurve *fcu) { const int active_keyframe_index = fcu->active_keyframe_index; @@ -963,10 +919,6 @@ void BKE_fcurve_keyframe_move_value_with_handles(struct BezTriple *keyframe, con /** \name Status Checks * \{ */ -/* Are keyframes on F-Curve of any use? - * Usability of keyframes refers to whether they should be displayed, - * and also whether they will have any influence on the final result. - */ bool BKE_fcurve_are_keyframes_usable(FCurve *fcu) { /* F-Curve must exist. */ @@ -1032,9 +984,6 @@ bool BKE_fcurve_is_protected(FCurve *fcu) return ((fcu->flag & FCURVE_PROTECTED) || ((fcu->grp) && (fcu->grp->flag & AGRP_PROTECTED))); } -/* Can keyframes be added to F-Curve? - * Keyframes can only be added if they are already visible. - */ bool BKE_fcurve_is_keyframable(FCurve *fcu) { /* F-Curve's keyframes must be "usable" (i.e. visible + have an effect on final result) */ @@ -1057,7 +1006,6 @@ bool BKE_fcurve_is_keyframable(FCurve *fcu) /** \name Keyframe Column Tools * \{ */ -/* Add a BezTriple to a column. */ static void UNUSED_FUNCTION(bezt_add_to_cfra_elem)(ListBase *lb, BezTriple *bezt) { CfraElem *ce, *cen; @@ -1100,18 +1048,12 @@ static void UNUSED_FUNCTION(bezt_add_to_cfra_elem)(ListBase *lb, BezTriple *bezt * which BezTriples/Keyframe data are ill equipped to do. */ -/* Basic sampling callback which acts as a wrapper for evaluate_fcurve() - * 'data' arg here is unneeded here... - */ float fcurve_samplingcb_evalcurve(FCurve *fcu, void *UNUSED(data), float evaltime) { /* Assume any interference from drivers on the curve is intended... */ return evaluate_fcurve(fcu, evaltime); } -/* Main API function for creating a set of sampled curve data, given some callback function - * used to retrieve the values to store. - */ void fcurve_store_samples(FCurve *fcu, void *data, int start, int end, FcuSampleFunc sample_cb) { FPoint *fpt, *new_fpt; @@ -1159,7 +1101,6 @@ static void init_unbaked_bezt_data(BezTriple *bezt) bezt->h1 = bezt->h2 = HD_AUTO_ANIM; } -/* Convert baked/sampled fcurves into bezt/regular fcurves. */ void fcurve_samples_to_keyframes(FCurve *fcu, const int start, const int end) { @@ -1235,7 +1176,6 @@ void fcurve_samples_to_keyframes(FCurve *fcu, const int start, const int end) * that the handles are correct. */ -/* Checks if the F-Curve has a Cycles modifier, and returns the type of the cycle behavior. */ eFCU_Cycle_Type BKE_fcurve_get_cycle_type(FCurve *fcu) { FModifier *fcm = fcu->modifiers.first; @@ -1269,8 +1209,6 @@ eFCU_Cycle_Type BKE_fcurve_get_cycle_type(FCurve *fcu) return FCU_CYCLE_NONE; } -/* Checks if the F-Curve has a Cycles modifier with simple settings - * that warrant transition smoothing. */ bool BKE_fcurve_is_cyclic(FCurve *fcu) { return BKE_fcurve_get_cycle_type(fcu) != FCU_CYCLE_NONE; @@ -1299,13 +1237,6 @@ static BezTriple *cycle_offset_triple( return out; } -/** - * Variant of #calchandles_fcurve() that allows calculating based on a different select flag. - * - * \param handle_sel_flag: The flag (bezt.f1/2/3) value to use to determine selection. - * Usually `SELECT`, but may want to use a different one at times - * (if caller does not operate on selection). - */ void calchandles_fcurve_ex(FCurve *fcu, eBezTriple_Flag handle_sel_flag) { BezTriple *bezt, *prev, *next; @@ -1389,28 +1320,11 @@ void calchandles_fcurve_ex(FCurve *fcu, eBezTriple_Flag handle_sel_flag) } } -/** - * This function recalculates the handles of an F-Curve. Acts based on selection with `SELECT` - * flag. To use a different flag, use #calchandles_fcurve_ex(). - * - * If the BezTriples have been rearranged, sort them first before using this. - */ void calchandles_fcurve(FCurve *fcu) { calchandles_fcurve_ex(fcu, SELECT); } -/** - * Update handles, making sure the handle-types are valid (e.g. correctly deduced from an "Auto" - * type), and recalculating their position vectors. - * Use when something has changed handle positions. - * - * \param sel_flag: The flag (bezt.f1/2/3) value to use to determine selection. Usually `SELECT`, - * but may want to use a different one at times (if caller does not operate on - * selection). - * \param use_handle: Check selection state of individual handles, otherwise always update both - * handles if the key is selected. - */ void testhandles_fcurve(FCurve *fcu, eBezTriple_Flag sel_flag, const bool use_handle) { BezTriple *bezt; @@ -1430,9 +1344,6 @@ void testhandles_fcurve(FCurve *fcu, eBezTriple_Flag sel_flag, const bool use_ha calchandles_fcurve_ex(fcu, sel_flag); } -/* This function sorts BezTriples so that they are arranged in chronological order, - * as tools working on F-Curves expect that the BezTriples are in order. - */ void sort_time_fcurve(FCurve *fcu) { if (fcu->bezt == NULL) { @@ -1475,7 +1386,6 @@ void sort_time_fcurve(FCurve *fcu) } } -/* This function tests if any BezTriples are out of order, thus requiring a sort. */ bool test_time_fcurve(FCurve *fcu) { unsigned int a; @@ -1517,14 +1427,6 @@ bool test_time_fcurve(FCurve *fcu) /** \name F-Curve Calculations * \{ */ -/** - * The length of each handle is not allowed to be more - * than the horizontal distance between (v1-v4). - * This is to prevent curve loops. - * - * This function is very similar to BKE_curve_correct_bezpart(), but allows a steeper tangent for - * more snappy animations. This is not desired for other areas in which curves are used, though. - */ void BKE_fcurve_correct_bezpart(const float v1[2], float v2[2], float v3[2], const float v4[2]) { float h1[2], h2[2], len1, len2, len, fac; @@ -1709,14 +1611,6 @@ static void berekeny(float f1, float f2, float f3, float f4, float *o, int b) } } -/** - * Adjust Bezier handles of all three given BezTriples, so that `bezt` can be inserted between - * `prev` and `next` without changing the resulting curve shape. - * - * \param r_pdelta: return Y difference between `bezt` and the original curve value at its X - * position. - * \return Whether the split was successful. - */ bool BKE_fcurve_bezt_subdivide_handles(struct BezTriple *bezt, struct BezTriple *prev, struct BezTriple *next, @@ -2252,14 +2146,12 @@ float evaluate_fcurve_driver(PathResolvedRNA *anim_rna, return evaluate_fcurve_ex(fcu, evaltime, cvalue); } -/* Checks if the curve has valid keys, drivers or modifiers that produce an actual curve. */ bool BKE_fcurve_is_empty(FCurve *fcu) { return (fcu->totvert == 0) && (fcu->driver == NULL) && !list_has_suitable_fmodifier(&fcu->modifiers, 0, FMI_TYPE_GENERATE_CURVE); } -/* Calculate the value of the given F-Curve at the given frame, and set its curval. */ float calculate_fcurve(PathResolvedRNA *anim_rna, FCurve *fcu, const AnimationEvalContext *anim_eval_context) diff --git a/source/blender/blenkernel/intern/fcurve_cache.c b/source/blender/blenkernel/intern/fcurve_cache.c index 8142b871edd..4f27bad5b91 100644 --- a/source/blender/blenkernel/intern/fcurve_cache.c +++ b/source/blender/blenkernel/intern/fcurve_cache.c @@ -155,11 +155,6 @@ FCurve *BKE_fcurve_pathcache_find(struct FCurvePathCache *fcache, return NULL; } -/** - * Fill in an array of F-Curve, leave NULL when not found. - * - * \return The number of F-Curves found. - */ int BKE_fcurve_pathcache_find_array(struct FCurvePathCache *fcache, const char *rna_path, FCurve **fcurve_result, diff --git a/source/blender/blenkernel/intern/fcurve_driver.c b/source/blender/blenkernel/intern/fcurve_driver.c index 3ac64dbf84b..c2b3b24c4b2 100644 --- a/source/blender/blenkernel/intern/fcurve_driver.c +++ b/source/blender/blenkernel/intern/fcurve_driver.c @@ -199,9 +199,6 @@ static float dtar_get_prop_val(ChannelDriver *driver, DriverTarget *dtar) return value; } -/** - * Same as 'dtar_get_prop_val'. but get the RNA property. - */ bool driver_get_variable_property(ChannelDriver *driver, DriverTarget *dtar, PointerRNA *r_ptr, @@ -621,7 +618,6 @@ static void quaternion_to_angles(float quat[4], int channel) } } -/* Compute channel values for a rotational Transform Channel driver variable. */ void BKE_driver_target_matrix_to_rot_channels( float mat[4][4], int auto_order, int rotation_mode, int channel, bool angles, float r_buf[4]) { @@ -720,7 +716,6 @@ static const DriverVarTypeInfo *get_dvar_typeinfo(int type) /** \name Driver API * \{ */ -/* Perform actual freeing driver variable and remove it from the given list */ void driver_free_variable(ListBase *variables, DriverVar *dvar) { /* Sanity checks. */ @@ -745,7 +740,6 @@ void driver_free_variable(ListBase *variables, DriverVar *dvar) BLI_freelinkN(variables, dvar); } -/* Free the driver variable and do extra updates */ void driver_free_variable_ex(ChannelDriver *driver, DriverVar *dvar) { /* Remove and free the driver variable. */ @@ -755,7 +749,6 @@ void driver_free_variable_ex(ChannelDriver *driver, DriverVar *dvar) BKE_driver_invalidate_expression(driver, false, true); } -/* Copy driver variables from src_vars list to dst_vars list */ void driver_variables_copy(ListBase *dst_vars, const ListBase *src_vars) { BLI_assert(BLI_listbase_is_empty(dst_vars)); @@ -773,7 +766,6 @@ void driver_variables_copy(ListBase *dst_vars, const ListBase *src_vars) } } -/* Change the type of driver variable */ void driver_change_variable_type(DriverVar *dvar, int type) { const DriverVarTypeInfo *dvti = get_dvar_typeinfo(type); @@ -803,7 +795,6 @@ void driver_change_variable_type(DriverVar *dvar, int type) DRIVER_TARGETS_LOOPER_END; } -/* Validate driver name (after being renamed) */ void driver_variable_name_validate(DriverVar *dvar) { /* Special character blacklist */ @@ -873,7 +864,6 @@ void driver_variable_name_validate(DriverVar *dvar) } } -/* Add a new driver variable */ DriverVar *driver_add_new_variable(ChannelDriver *driver) { DriverVar *dvar; @@ -906,7 +896,6 @@ DriverVar *driver_add_new_variable(ChannelDriver *driver) return dvar; } -/* This frees the driver itself */ void fcurve_free_driver(FCurve *fcu) { ChannelDriver *driver; @@ -939,7 +928,6 @@ void fcurve_free_driver(FCurve *fcu) fcu->driver = NULL; } -/* This makes a copy of the given driver */ ChannelDriver *fcurve_copy_driver(const ChannelDriver *driver) { ChannelDriver *ndriver; @@ -1082,7 +1070,6 @@ static bool driver_try_evaluate_simple_expr(ChannelDriver *driver, driver_evaluate_simple_expr(driver, driver_orig->expr_simple, result, time); } -/* Check if the expression in the driver conforms to the simple subset. */ bool BKE_driver_has_simple_expression(ChannelDriver *driver) { return driver_compile_simple_expr(driver) && BLI_expr_pylike_is_valid(driver->expr_simple); @@ -1109,7 +1096,6 @@ static bool python_driver_exression_depends_on_time(const char *expression) return false; } -/* Check if the expression in the driver may depend on the current frame. */ bool BKE_driver_expression_depends_on_time(ChannelDriver *driver) { if (driver->type != DRIVER_TYPE_PYTHON) { @@ -1125,7 +1111,6 @@ bool BKE_driver_expression_depends_on_time(ChannelDriver *driver) return python_driver_exression_depends_on_time(driver->expression); } -/* Reset cached compiled expression data */ void BKE_driver_invalidate_expression(ChannelDriver *driver, bool expr_changed, bool varname_changed) @@ -1152,7 +1137,6 @@ void BKE_driver_invalidate_expression(ChannelDriver *driver, /** \name Driver Evaluation * \{ */ -/* Evaluate a Driver Variable to get a value that contributes to the final */ float driver_get_variable_value(ChannelDriver *driver, DriverVar *dvar) { const DriverVarTypeInfo *dvti; @@ -1269,14 +1253,6 @@ static void evaluate_driver_python(PathResolvedRNA *anim_rna, } } -/** - * Evaluate an Channel-Driver to get a 'time' value to use - * instead of `anim_eval_context->eval_time`. - * - * - `anim_eval_context->eval_time` is the frame at which F-Curve is being evaluated. - * - Has to return a float value. - * - \a driver_orig is where we cache Python expressions, in case of COW - */ float evaluate_driver(PathResolvedRNA *anim_rna, ChannelDriver *driver, ChannelDriver *driver_orig, diff --git a/source/blender/blenkernel/intern/fluid.c b/source/blender/blenkernel/intern/fluid.c index 9d26a1528f3..13e7cadb034 100644 --- a/source/blender/blenkernel/intern/fluid.c +++ b/source/blender/blenkernel/intern/fluid.c @@ -4437,8 +4437,6 @@ static void manta_smoke_calc_transparency(FluidDomainSettings *fds, ViewLayer *v } } -/* Get fluid velocity and density at given coordinates - * Returns fluid density or -1.0f if outside domain. */ float BKE_fluid_get_velocity_at(struct Object *ob, float position[3], float velocity[3]) { FluidModifierData *fmd = (FluidModifierData *)BKE_modifiers_findby_type(ob, eModifierType_Fluid); diff --git a/source/blender/blenkernel/intern/fmodifier.c b/source/blender/blenkernel/intern/fmodifier.c index 121927513cc..d140e70978a 100644 --- a/source/blender/blenkernel/intern/fmodifier.c +++ b/source/blender/blenkernel/intern/fmodifier.c @@ -1065,10 +1065,6 @@ static void fmods_init_typeinfo(void) fmodifiersTypeInfo[9] = &FMI_STEPPED; /* Stepped F-Curve Modifier */ } -/** - * This function should be used for getting the appropriate type-info when only - * a F-Curve modifier type is known. - */ const FModifierTypeInfo *get_fmodifier_typeinfo(const int type) { /* initialize the type-info list? */ @@ -1088,10 +1084,6 @@ const FModifierTypeInfo *get_fmodifier_typeinfo(const int type) return NULL; } -/** - * This function should always be used to get the appropriate type-info, - * as it has checks which prevent segfaults in some weird cases. - */ const FModifierTypeInfo *fmodifier_get_typeinfo(const FModifier *fcm) { /* only return typeinfo for valid modifiers */ @@ -1108,9 +1100,6 @@ const FModifierTypeInfo *fmodifier_get_typeinfo(const FModifier *fcm) /** \name F-Curve Modifier Public API * \{ */ -/** - * Add a new F-Curve Modifier to the given F-Curve of a certain type. - */ FModifier *add_fmodifier(ListBase *modifiers, int type, FCurve *owner_fcu) { const FModifierTypeInfo *fmi = get_fmodifier_typeinfo(type); @@ -1161,9 +1150,6 @@ FModifier *add_fmodifier(ListBase *modifiers, int type, FCurve *owner_fcu) return fcm; } -/** - * Make a copy of the specified F-Modifier. - */ FModifier *copy_fmodifier(const FModifier *src) { const FModifierTypeInfo *fmi = fmodifier_get_typeinfo(src); @@ -1191,9 +1177,6 @@ FModifier *copy_fmodifier(const FModifier *src) return dst; } -/** - * Duplicate all of the F-Modifiers in the Modifier stacks. - */ void copy_fmodifiers(ListBase *dst, const ListBase *src) { FModifier *fcm, *srcfcm; @@ -1220,9 +1203,6 @@ void copy_fmodifiers(ListBase *dst, const ListBase *src) } } -/** - * Remove and free the given F-Modifier from the given stack. - */ bool remove_fmodifier(ListBase *modifiers, FModifier *fcm) { const FModifierTypeInfo *fmi = fmodifier_get_typeinfo(fcm); @@ -1263,9 +1243,6 @@ bool remove_fmodifier(ListBase *modifiers, FModifier *fcm) return false; } -/** - * Remove all of a given F-Curve's modifiers. - */ void free_fmodifiers(ListBase *modifiers) { FModifier *fcm, *fmn; @@ -1282,9 +1259,6 @@ void free_fmodifiers(ListBase *modifiers) } } -/** - * Find the active F-Modifier. - */ FModifier *find_active_fmodifier(ListBase *modifiers) { FModifier *fcm; @@ -1305,9 +1279,6 @@ FModifier *find_active_fmodifier(ListBase *modifiers) return NULL; } -/** - * Set the active F-Modifier. - */ void set_active_fmodifier(ListBase *modifiers, FModifier *fcm) { FModifier *fm; @@ -1328,12 +1299,6 @@ void set_active_fmodifier(ListBase *modifiers, FModifier *fcm) } } -/** - * Do we have any modifiers which match certain criteria. - * - * \param mtype: Type of modifier (if 0, doesn't matter). - * \param acttype: Type of action to perform (if -1, doesn't matter). - */ bool list_has_suitable_fmodifier(ListBase *modifiers, int mtype, short acttype) { FModifier *fcm; @@ -1443,19 +1408,6 @@ static float eval_fmodifier_influence(FModifier *fcm, float evaltime) return influence; } -/** - * Evaluate time modifications imposed by some F-Curve Modifiers. - * - * - This step acts as an optimization to prevent the F-Curve stack being evaluated - * several times by modifiers requesting the time be modified, as the final result - * would have required using the modified time - * - Modifiers only ever receive the unmodified time, as subsequent modifiers should be - * working on the 'global' result of the modified curve, not some localized segment, - * so \a evaltime gets set to whatever the last time-modifying modifier likes. - * - We start from the end of the stack, as only the last one matters for now. - * - * \param fcu: Can be NULL. - */ float evaluate_time_fmodifiers(FModifiersStackStorage *storage, ListBase *modifiers, FCurve *fcu, @@ -1513,10 +1465,6 @@ float evaluate_time_fmodifiers(FModifiersStackStorage *storage, return evaltime; } -/** - * Evaluates the given set of F-Curve Modifiers using the given data - * Should only be called after evaluate_time_fmodifiers() has been called. - */ void evaluate_value_fmodifiers(FModifiersStackStorage *storage, ListBase *modifiers, FCurve *fcu, @@ -1565,10 +1513,6 @@ void evaluate_value_fmodifiers(FModifiersStackStorage *storage, /* ---------- */ -/** - * Bake modifiers for given F-Curve to curve sample data, in the frame range defined - * by start and end (inclusive). - */ void fcurve_bake_modifiers(FCurve *fcu, int start, int end) { ChannelDriver *driver; diff --git a/source/blender/blenkernel/intern/freestyle.c b/source/blender/blenkernel/intern/freestyle.c index d9b3faf8623..68b7e274970 100644 --- a/source/blender/blenkernel/intern/freestyle.c +++ b/source/blender/blenkernel/intern/freestyle.c @@ -152,10 +152,6 @@ bool BKE_freestyle_module_delete(FreestyleConfig *config, FreestyleModuleConfig return true; } -/** - * Reinsert \a module_conf offset by \a direction from current position. - * \return if position of \a module_conf changed. - */ bool BKE_freestyle_module_move(FreestyleConfig *config, FreestyleModuleConfig *module_conf, int direction) diff --git a/source/blender/blenkernel/intern/geometry_component_curve.cc b/source/blender/blenkernel/intern/geometry_component_curve.cc index a0d7bfe135a..bd3912ddfc0 100644 --- a/source/blender/blenkernel/intern/geometry_component_curve.cc +++ b/source/blender/blenkernel/intern/geometry_component_curve.cc @@ -77,7 +77,6 @@ bool CurveComponent::has_curve() const return curve_ != nullptr; } -/* Clear the component and replace it with the new curve. */ void CurveComponent::replace(CurveEval *curve, GeometryOwnershipType ownership) { BLI_assert(this->is_mutable()); @@ -128,10 +127,6 @@ void CurveComponent::ensure_owns_direct_data() } } -/** - * Create empty curve data used for rendering the spline's wire edges. - * \note See comment on #curve_for_render_ for further explanation. - */ const Curve *CurveComponent::get_curve_for_render() const { if (curve_ == nullptr) { diff --git a/source/blender/blenkernel/intern/geometry_component_instances.cc b/source/blender/blenkernel/intern/geometry_component_instances.cc index b7caa2c9937..62d66f13e9f 100644 --- a/source/blender/blenkernel/intern/geometry_component_instances.cc +++ b/source/blender/blenkernel/intern/geometry_component_instances.cc @@ -64,12 +64,6 @@ void InstancesComponent::reserve(int min_capacity) attributes_.reallocate(min_capacity); } -/** - * Resize the transform, handles, and ID vectors to the specified capacity. - * - * \note This function should be used carefully, only when it's guaranteed - * that the data will be filled. - */ void InstancesComponent::resize(int capacity) { instance_reference_handles_.resize(capacity); @@ -113,11 +107,6 @@ blender::Span InstancesComponent::instance_transforms() const return instance_transforms_; } -/** - * With write access to the instances component, the data in the instanced geometry sets can be - * changed. This is a function on the component rather than each reference to ensure `const` - * correctness for that reason. - */ GeometrySet &InstancesComponent::geometry_set_from_reference(const int reference_index) { /* If this assert fails, it means #ensure_geometry_instances must be called first or that the @@ -129,11 +118,6 @@ GeometrySet &InstancesComponent::geometry_set_from_reference(const int reference return const_cast(references_[reference_index].geometry_set()); } -/** - * Returns a handle for the given reference. - * If the reference exists already, the handle of the existing reference is returned. - * Otherwise a new handle is added. - */ int InstancesComponent::add_reference(const InstanceReference &reference) { return references_.index_of_or_add_as(reference); diff --git a/source/blender/blenkernel/intern/geometry_component_mesh.cc b/source/blender/blenkernel/intern/geometry_component_mesh.cc index e7d48670f73..cc15e6d7b84 100644 --- a/source/blender/blenkernel/intern/geometry_component_mesh.cc +++ b/source/blender/blenkernel/intern/geometry_component_mesh.cc @@ -29,7 +29,6 @@ #include "attribute_access_intern.hh" -/* Can't include BKE_object_deform.h right now, due to an enum forward declaration. */ extern "C" MDeformVert *BKE_object_defgroup_data_create(ID *id); /* -------------------------------------------------------------------- */ @@ -71,7 +70,6 @@ bool MeshComponent::has_mesh() const return mesh_ != nullptr; } -/* Clear the component and replace it with the new mesh. */ void MeshComponent::replace(Mesh *mesh, GeometryOwnershipType ownership) { BLI_assert(this->is_mutable()); @@ -80,8 +78,6 @@ void MeshComponent::replace(Mesh *mesh, GeometryOwnershipType ownership) ownership_ = ownership; } -/* Return the mesh and clear the component. The caller takes over responsibility for freeing the - * mesh (if the component was responsible before). */ Mesh *MeshComponent::release() { BLI_assert(this->is_mutable()); @@ -90,15 +86,11 @@ Mesh *MeshComponent::release() return mesh; } -/* Get the mesh from this component. This method can be used by multiple threads at the same - * time. Therefore, the returned mesh should not be modified. No ownership is transferred. */ const Mesh *MeshComponent::get_for_read() const { return mesh_; } -/* Get the mesh from this component. This method can only be used when the component is mutable, - * i.e. it is not shared. The returned mesh can be modified. No ownership is transferred. */ Mesh *MeshComponent::get_for_write() { BLI_assert(this->is_mutable()); diff --git a/source/blender/blenkernel/intern/geometry_component_pointcloud.cc b/source/blender/blenkernel/intern/geometry_component_pointcloud.cc index c6a1c61a96d..80c09a7ed4a 100644 --- a/source/blender/blenkernel/intern/geometry_component_pointcloud.cc +++ b/source/blender/blenkernel/intern/geometry_component_pointcloud.cc @@ -62,7 +62,6 @@ bool PointCloudComponent::has_pointcloud() const return pointcloud_ != nullptr; } -/* Clear the component and replace it with the new point cloud. */ void PointCloudComponent::replace(PointCloud *pointcloud, GeometryOwnershipType ownership) { BLI_assert(this->is_mutable()); @@ -71,8 +70,6 @@ void PointCloudComponent::replace(PointCloud *pointcloud, GeometryOwnershipType ownership_ = ownership; } -/* Return the point cloud and clear the component. The caller takes over responsibility for freeing - * the point cloud (if the component was responsible before). */ PointCloud *PointCloudComponent::release() { BLI_assert(this->is_mutable()); @@ -81,17 +78,11 @@ PointCloud *PointCloudComponent::release() return pointcloud; } -/* Get the point cloud from this component. This method can be used by multiple threads at the same - * time. Therefore, the returned point cloud should not be modified. No ownership is transferred. - */ const PointCloud *PointCloudComponent::get_for_read() const { return pointcloud_; } -/* Get the point cloud from this component. This method can only be used when the component is - * mutable, i.e. it is not shared. The returned point cloud can be modified. No ownership is - * transferred. */ PointCloud *PointCloudComponent::get_for_write() { BLI_assert(this->is_mutable()); diff --git a/source/blender/blenkernel/intern/geometry_component_volume.cc b/source/blender/blenkernel/intern/geometry_component_volume.cc index 94ed07a63de..e9874153b4c 100644 --- a/source/blender/blenkernel/intern/geometry_component_volume.cc +++ b/source/blender/blenkernel/intern/geometry_component_volume.cc @@ -59,7 +59,6 @@ bool VolumeComponent::has_volume() const return volume_ != nullptr; } -/* Clear the component and replace it with the new volume. */ void VolumeComponent::replace(Volume *volume, GeometryOwnershipType ownership) { BLI_assert(this->is_mutable()); @@ -68,8 +67,6 @@ void VolumeComponent::replace(Volume *volume, GeometryOwnershipType ownership) ownership_ = ownership; } -/* Return the volume and clear the component. The caller takes over responsibility for freeing the - * volume (if the component was responsible before). */ Volume *VolumeComponent::release() { BLI_assert(this->is_mutable()); @@ -78,15 +75,11 @@ Volume *VolumeComponent::release() return volume; } -/* Get the volume from this component. This method can be used by multiple threads at the same - * time. Therefore, the returned volume should not be modified. No ownership is transferred. */ const Volume *VolumeComponent::get_for_read() const { return volume_; } -/* Get the volume from this component. This method can only be used when the component is mutable, - * i.e. it is not shared. The returned volume can be modified. No ownership is transferred. */ Volume *VolumeComponent::get_for_write() { BLI_assert(this->is_mutable()); diff --git a/source/blender/blenkernel/intern/geometry_set.cc b/source/blender/blenkernel/intern/geometry_set.cc index f65e3eeb2d0..3e812a7e3c5 100644 --- a/source/blender/blenkernel/intern/geometry_set.cc +++ b/source/blender/blenkernel/intern/geometry_set.cc @@ -105,7 +105,6 @@ bool GeometryComponent::is_empty() const /** \name Geometry Set * \{ */ -/* The methods are defaulted here so that they are not instantiated in every translation unit. */ GeometrySet::GeometrySet() = default; GeometrySet::GeometrySet(const GeometrySet &other) = default; GeometrySet::GeometrySet(GeometrySet &&other) = default; @@ -113,9 +112,6 @@ GeometrySet::~GeometrySet() = default; GeometrySet &GeometrySet::operator=(const GeometrySet &other) = default; GeometrySet &GeometrySet::operator=(GeometrySet &&other) = default; -/* This method can only be used when the geometry set is mutable. It returns a mutable geometry - * component of the given type. - */ GeometryComponent &GeometrySet::get_component_for_write(GeometryComponentType component_type) { GeometryComponentPtr &component_ptr = components_[component_type]; @@ -134,10 +130,6 @@ GeometryComponent &GeometrySet::get_component_for_write(GeometryComponentType co return *component_ptr; } -/** - * Retrieve the pointer to a component without creating it if it does not exist, - * unlike #get_component_for_write. - */ GeometryComponent *GeometrySet::get_component_ptr(GeometryComponentType type) { if (this->has(type)) { @@ -146,7 +138,6 @@ GeometryComponent *GeometrySet::get_component_ptr(GeometryComponentType type) return nullptr; } -/* Get the component of the given type. Might return null if the component does not exist yet. */ const GeometryComponent *GeometrySet::get_component_for_read( GeometryComponentType component_type) const { @@ -163,9 +154,6 @@ void GeometrySet::remove(const GeometryComponentType component_type) components_[component_type].reset(); } -/** - * Remove all geometry components with types that are not in the provided list. - */ void GeometrySet::keep_only(const blender::Span component_types) { for (GeometryComponentPtr &component_ptr : components_) { @@ -184,9 +172,6 @@ void GeometrySet::add(const GeometryComponent &component) components_[component.type()] = const_cast(&component); } -/** - * Get all geometry components in this geometry set for read-only access. - */ Vector GeometrySet::get_components_for_read() const { Vector components; @@ -226,7 +211,6 @@ std::ostream &operator<<(std::ostream &stream, const GeometrySet &geometry_set) return stream; } -/* Remove all geometry components from the geometry set. */ void GeometrySet::clear() { for (GeometryComponentPtr &component_ptr : components_) { @@ -234,8 +218,6 @@ void GeometrySet::clear() } } -/* Make sure that the geometry can be cached. This does not ensure ownership of object/collection - * instances. */ void GeometrySet::ensure_owns_direct_data() { for (GeometryComponentPtr &component_ptr : components_) { @@ -262,70 +244,60 @@ bool GeometrySet::owns_direct_data() const return true; } -/* Returns a read-only mesh or null. */ const Mesh *GeometrySet::get_mesh_for_read() const { const MeshComponent *component = this->get_component_for_read(); return (component == nullptr) ? nullptr : component->get_for_read(); } -/* Returns true when the geometry set has a mesh component that has a mesh. */ bool GeometrySet::has_mesh() const { const MeshComponent *component = this->get_component_for_read(); return component != nullptr && component->has_mesh(); } -/* Returns a read-only point cloud of null. */ const PointCloud *GeometrySet::get_pointcloud_for_read() const { const PointCloudComponent *component = this->get_component_for_read(); return (component == nullptr) ? nullptr : component->get_for_read(); } -/* Returns a read-only volume or null. */ const Volume *GeometrySet::get_volume_for_read() const { const VolumeComponent *component = this->get_component_for_read(); return (component == nullptr) ? nullptr : component->get_for_read(); } -/* Returns a read-only curve or null. */ const CurveEval *GeometrySet::get_curve_for_read() const { const CurveComponent *component = this->get_component_for_read(); return (component == nullptr) ? nullptr : component->get_for_read(); } -/* Returns true when the geometry set has a point cloud component that has a point cloud. */ bool GeometrySet::has_pointcloud() const { const PointCloudComponent *component = this->get_component_for_read(); return component != nullptr && component->has_pointcloud(); } -/* Returns true when the geometry set has an instances component that has at least one instance. */ bool GeometrySet::has_instances() const { const InstancesComponent *component = this->get_component_for_read(); return component != nullptr && component->instances_amount() >= 1; } -/* Returns true when the geometry set has a volume component that has a volume. */ bool GeometrySet::has_volume() const { const VolumeComponent *component = this->get_component_for_read(); return component != nullptr && component->has_volume(); } -/* Returns true when the geometry set has a curve component that has a curve. */ bool GeometrySet::has_curve() const { const CurveComponent *component = this->get_component_for_read(); return component != nullptr && component->has_curve(); } -/* Returns true when the geometry set has any data that is not an instance. */ bool GeometrySet::has_realized_data() const { for (const GeometryComponentPtr &component_ptr : components_) { @@ -338,14 +310,12 @@ bool GeometrySet::has_realized_data() const return false; } -/* Return true if the geometry set has any component that isn't empty. */ bool GeometrySet::is_empty() const { return !(this->has_mesh() || this->has_curve() || this->has_pointcloud() || this->has_volume() || this->has_instances()); } -/* Create a new geometry set that only contains the given mesh. */ GeometrySet GeometrySet::create_with_mesh(Mesh *mesh, GeometryOwnershipType ownership) { GeometrySet geometry_set; @@ -356,7 +326,6 @@ GeometrySet GeometrySet::create_with_mesh(Mesh *mesh, GeometryOwnershipType owne return geometry_set; } -/* Create a new geometry set that only contains the given point cloud. */ GeometrySet GeometrySet::create_with_pointcloud(PointCloud *pointcloud, GeometryOwnershipType ownership) { @@ -368,7 +337,6 @@ GeometrySet GeometrySet::create_with_pointcloud(PointCloud *pointcloud, return geometry_set; } -/* Create a new geometry set that only contains the given curve. */ GeometrySet GeometrySet::create_with_curve(CurveEval *curve, GeometryOwnershipType ownership) { GeometrySet geometry_set; @@ -379,7 +347,6 @@ GeometrySet GeometrySet::create_with_curve(CurveEval *curve, GeometryOwnershipTy return geometry_set; } -/* Clear the existing mesh and replace it with the given one. */ void GeometrySet::replace_mesh(Mesh *mesh, GeometryOwnershipType ownership) { if (mesh == nullptr) { @@ -391,7 +358,6 @@ void GeometrySet::replace_mesh(Mesh *mesh, GeometryOwnershipType ownership) } } -/* Clear the existing curve and replace it with the given one. */ void GeometrySet::replace_curve(CurveEval *curve, GeometryOwnershipType ownership) { if (curve == nullptr) { @@ -403,7 +369,6 @@ void GeometrySet::replace_curve(CurveEval *curve, GeometryOwnershipType ownershi } } -/* Clear the existing point cloud and replace with the given one. */ void GeometrySet::replace_pointcloud(PointCloud *pointcloud, GeometryOwnershipType ownership) { if (pointcloud == nullptr) { @@ -415,7 +380,6 @@ void GeometrySet::replace_pointcloud(PointCloud *pointcloud, GeometryOwnershipTy } } -/* Clear the existing volume and replace with the given one. */ void GeometrySet::replace_volume(Volume *volume, GeometryOwnershipType ownership) { if (volume == nullptr) { @@ -427,28 +391,24 @@ void GeometrySet::replace_volume(Volume *volume, GeometryOwnershipType ownership } } -/* Returns a mutable mesh or null. No ownership is transferred. */ Mesh *GeometrySet::get_mesh_for_write() { MeshComponent *component = this->get_component_ptr(); return component == nullptr ? nullptr : component->get_for_write(); } -/* Returns a mutable point cloud or null. No ownership is transferred. */ PointCloud *GeometrySet::get_pointcloud_for_write() { PointCloudComponent *component = this->get_component_ptr(); return component == nullptr ? nullptr : component->get_for_write(); } -/* Returns a mutable volume or null. No ownership is transferred. */ Volume *GeometrySet::get_volume_for_write() { VolumeComponent *component = this->get_component_ptr(); return component == nullptr ? nullptr : component->get_for_write(); } -/* Returns a mutable curve or null. No ownership is transferred. */ CurveEval *GeometrySet::get_curve_for_write() { CurveComponent *component = this->get_component_ptr(); @@ -578,10 +538,6 @@ static void gather_mutable_geometry_sets(GeometrySet &geometry_set, } } -/** - * Modify every (recursive) instance separately. This is often more efficient than realizing all - * instances just to change the same thing on all of them. - */ void GeometrySet::modify_geometry_sets(ForeachSubGeometryCallback callback) { Vector geometry_sets; diff --git a/source/blender/blenkernel/intern/geometry_set_instances.cc b/source/blender/blenkernel/intern/geometry_set_instances.cc index c73da7d9659..253c4642c14 100644 --- a/source/blender/blenkernel/intern/geometry_set_instances.cc +++ b/source/blender/blenkernel/intern/geometry_set_instances.cc @@ -53,9 +53,6 @@ static void add_final_mesh_as_geometry_component(const Object &object, GeometryS } } -/** - * \note This doesn't extract instances from the "dupli" system for non-geometry-nodes instances. - */ GeometrySet object_get_evaluated_geometry_set(const Object &object) { if (object.type == OB_MESH && object.mode == OB_MODE_EDIT) { @@ -169,16 +166,6 @@ static void geometry_set_collect_recursive(const GeometrySet &geometry_set, } } -/** - * Return flattened vector of the geometry component's recursive instances. I.e. all collection - * instances and object instances will be expanded into the instances of their geometry components. - * Even the instances in those geometry components' will be included. - * - * \note For convenience (to avoid duplication in the caller), the returned vector also contains - * the argument geometry set. - * - * \note This doesn't extract instances from the "dupli" system for non-geometry-nodes instances. - */ void geometry_set_gather_instances(const GeometrySet &geometry_set, Vector &r_instance_groups) { @@ -624,11 +611,6 @@ void InstancesComponent::foreach_referenced_geometry( } } -/** - * If references have a collection or object type, convert them into geometry instances - * recursively. After that, the geometry sets can be edited. There may still be instances of other - * types of they can't be converted to geometry sets. - */ void InstancesComponent::ensure_geometry_instances() { using namespace blender; diff --git a/source/blender/blenkernel/intern/gpencil.c b/source/blender/blenkernel/intern/gpencil.c index f9841aeb8c2..312bbcc5a07 100644 --- a/source/blender/blenkernel/intern/gpencil.c +++ b/source/blender/blenkernel/intern/gpencil.c @@ -365,7 +365,6 @@ void BKE_gpencil_batch_cache_free(bGPdata *gpd) /* ************************************************** */ /* Memory Management */ -/* clean vertex groups weights */ void BKE_gpencil_free_point_weights(MDeformVert *dvert) { if (dvert == NULL) { @@ -404,7 +403,6 @@ void BKE_gpencil_free_stroke_editcurve(bGPDstroke *gps) gps->editcurve = NULL; } -/* free stroke, doesn't unlink from any listbase */ void BKE_gpencil_free_stroke(bGPDstroke *gps) { if (gps == NULL) { @@ -428,7 +426,6 @@ void BKE_gpencil_free_stroke(bGPDstroke *gps) MEM_freeN(gps); } -/* Free strokes belonging to a gp-frame */ bool BKE_gpencil_free_strokes(bGPDframe *gpf) { bool changed = (BLI_listbase_is_empty(&gpf->strokes) == false); @@ -442,7 +439,6 @@ bool BKE_gpencil_free_strokes(bGPDframe *gpf) return changed; } -/* Free all of a gp-layer's frames */ void BKE_gpencil_free_frames(bGPDlayer *gpl) { bGPDframe *gpf_next; @@ -472,7 +468,6 @@ void BKE_gpencil_free_layer_masks(bGPDlayer *gpl) BLI_freelinkN(&gpl->mask_layers, mask); } } -/* Free all of the gp-layers for a viewport (list should be &gpd->layers or so) */ void BKE_gpencil_free_layers(ListBase *list) { bGPDlayer *gpl_next; @@ -496,7 +491,6 @@ void BKE_gpencil_free_layers(ListBase *list) } } -/** Free (or release) any data used by this grease pencil (does not free the gpencil itself). */ void BKE_gpencil_free_data(bGPdata *gpd, bool free_all) { /* free layers */ @@ -514,10 +508,6 @@ void BKE_gpencil_free_data(bGPdata *gpd, bool free_all) } } -/** - * Delete grease pencil evaluated data - * \param gpd_eval: Grease pencil data-block - */ void BKE_gpencil_eval_delete(bGPdata *gpd_eval) { BKE_gpencil_free_data(gpd_eval, true); @@ -526,11 +516,6 @@ void BKE_gpencil_eval_delete(bGPdata *gpd_eval) MEM_freeN(gpd_eval); } -/** - * Tag data-block for depsgraph update. - * Wrapper to avoid include Depsgraph tag functions in other modules. - * \param gpd: Grease pencil data-block. - */ void BKE_gpencil_tag(bGPdata *gpd) { DEG_id_tag_update(&gpd->id, ID_RECALC_TRANSFORM | ID_RECALC_GEOMETRY); @@ -539,12 +524,6 @@ void BKE_gpencil_tag(bGPdata *gpd) /* ************************************************** */ /* Container Creation */ -/** - * Add a new gp-frame to the given layer. - * \param gpl: Grease pencil layer - * \param cframe: Frame number - * \return Pointer to new frame - */ bGPDframe *BKE_gpencil_frame_addnew(bGPDlayer *gpl, int cframe) { bGPDframe *gpf = NULL, *gf = NULL; @@ -598,12 +577,6 @@ bGPDframe *BKE_gpencil_frame_addnew(bGPDlayer *gpl, int cframe) return gpf; } -/** - * Add a copy of the active gp-frame to the given layer. - * \param gpl: Grease pencil layer - * \param cframe: Frame number - * \return Pointer to new frame - */ bGPDframe *BKE_gpencil_frame_addcopy(bGPDlayer *gpl, int cframe) { bGPDframe *new_frame; @@ -658,14 +631,6 @@ bGPDframe *BKE_gpencil_frame_addcopy(bGPDlayer *gpl, int cframe) return new_frame; } -/** - * Add a new gp-layer and make it the active layer. - * \param gpd: Grease pencil data-block - * \param name: Name of the layer - * \param setactive: Set as active - * \param add_to_header: Used to force the layer added at header - * \return Pointer to new layer - */ bGPDlayer *BKE_gpencil_layer_addnew(bGPdata *gpd, const char *name, const bool setactive, @@ -750,12 +715,6 @@ bGPDlayer *BKE_gpencil_layer_addnew(bGPdata *gpd, return gpl; } -/** - * Add a new grease pencil data-block. - * \param bmain: Main pointer - * \param name: Name of the datablock - * \return Pointer to new data-block - */ bGPdata *BKE_gpencil_data_addnew(Main *bmain, const char name[]) { bGPdata *gpd; @@ -807,13 +766,6 @@ bGPdata *BKE_gpencil_data_addnew(Main *bmain, const char name[]) /* Primitive Creation */ /* Utilities for easier bulk-creation of geometry */ -/** - * Create a new stroke, with pre-allocated data buffers. - * \param mat_idx: Index of the material - * \param totpoints: Total points - * \param thickness: Stroke thickness - * \return Pointer to new stroke - */ bGPDstroke *BKE_gpencil_stroke_new(int mat_idx, int totpoints, short thickness) { /* allocate memory for a new stroke */ @@ -850,15 +802,6 @@ bGPDstroke *BKE_gpencil_stroke_new(int mat_idx, int totpoints, short thickness) return gps; } -/** - * Create a new stroke and add to frame. - * \param gpf: Grease pencil frame - * \param mat_idx: Material index - * \param totpoints: Total points - * \param thickness: Stroke thickness - * \param insert_at_head: Add to the head of the strokes list - * \return Pointer to new stroke - */ bGPDstroke *BKE_gpencil_stroke_add( bGPDframe *gpf, int mat_idx, int totpoints, short thickness, const bool insert_at_head) { @@ -877,16 +820,6 @@ bGPDstroke *BKE_gpencil_stroke_add( return gps; } -/** - * Add a stroke and copy the temporary drawing color value - * from one of the existing stroke. - * \param gpf: Grease pencil frame - * \param existing: Stroke with the style to copy - * \param mat_idx: Material index - * \param totpoints: Total points - * \param thickness: Stroke thickness - * \return Pointer to new stroke - */ bGPDstroke *BKE_gpencil_stroke_add_existing_style( bGPDframe *gpf, bGPDstroke *existing, int mat_idx, int totpoints, short thickness) { @@ -911,11 +844,6 @@ bGPDcurve *BKE_gpencil_stroke_editcurve_new(const int tot_curve_points) /* ************************************************** */ /* Data Duplication */ -/** - * Make a copy of a given gpencil weights. - * \param gps_src: Source grease pencil stroke - * \param gps_dst: Destination grease pencil stroke - */ void BKE_gpencil_stroke_weights_duplicate(bGPDstroke *gps_src, bGPDstroke *gps_dst) { if (gps_src == NULL) { @@ -926,7 +854,6 @@ void BKE_gpencil_stroke_weights_duplicate(bGPDstroke *gps_src, bGPDstroke *gps_d BKE_defvert_array_copy(gps_dst->dvert, gps_src->dvert, gps_src->totpoints); } -/* Make a copy of a given gpencil stroke editcurve */ bGPDcurve *BKE_gpencil_stroke_curve_duplicate(bGPDcurve *gpc_src) { bGPDcurve *gpc_dst = MEM_dupallocN(gpc_src); @@ -938,13 +865,6 @@ bGPDcurve *BKE_gpencil_stroke_curve_duplicate(bGPDcurve *gpc_src) return gpc_dst; } -/** - * Make a copy of a given grease-pencil stroke. - * \param gps_src: Source grease pencil strokes. - * \param dup_points: Duplicate points data. - * \param dup_curve: Duplicate curve data. - * \return Pointer to new stroke. - */ bGPDstroke *BKE_gpencil_stroke_duplicate(bGPDstroke *gps_src, const bool dup_points, const bool dup_curve) @@ -982,11 +902,6 @@ bGPDstroke *BKE_gpencil_stroke_duplicate(bGPDstroke *gps_src, return gps_dst; } -/** - * Make a copy of a given gpencil frame. - * \param gpf_src: Source grease pencil frame - * \return Pointer to new frame - */ bGPDframe *BKE_gpencil_frame_duplicate(const bGPDframe *gpf_src, const bool dup_strokes) { bGPDstroke *gps_dst = NULL; @@ -1015,11 +930,6 @@ bGPDframe *BKE_gpencil_frame_duplicate(const bGPDframe *gpf_src, const bool dup_ return gpf_dst; } -/** - * Make a copy of strokes between gpencil frames. - * \param gpf_src: Source grease pencil frame - * \param gpf_dst: Destination grease pencil frame - */ void BKE_gpencil_frame_copy_strokes(bGPDframe *gpf_src, struct bGPDframe *gpf_dst) { bGPDstroke *gps_dst = NULL; @@ -1037,11 +947,6 @@ void BKE_gpencil_frame_copy_strokes(bGPDframe *gpf_src, struct bGPDframe *gpf_ds } } -/** - * Make a copy of a given gpencil layer. - * \param gpl_src: Source grease pencil layer - * \return Pointer to new layer - */ bGPDlayer *BKE_gpencil_layer_duplicate(const bGPDlayer *gpl_src, const bool dup_frames, const bool dup_strokes) @@ -1080,9 +985,6 @@ bGPDlayer *BKE_gpencil_layer_duplicate(const bGPDlayer *gpl_src, return gpl_dst; } -/** - * Make a copy of a given gpencil layer settings. - */ void BKE_gpencil_layer_copy_settings(const bGPDlayer *gpl_src, bGPDlayer *gpl_dst) { gpl_dst->line_change = gpl_src->line_change; @@ -1104,11 +1006,6 @@ void BKE_gpencil_layer_copy_settings(const bGPDlayer *gpl_src, bGPDlayer *gpl_ds gpl_dst->flag = gpl_src->flag; } -/** - * Make a copy of a given gpencil data-block. - * - * XXX: Should this be deprecated? - */ bGPdata *BKE_gpencil_data_duplicate(Main *bmain, const bGPdata *gpd_src, bool internal_copy) { bGPdata *gpd_dst; @@ -1141,10 +1038,6 @@ bGPdata *BKE_gpencil_data_duplicate(Main *bmain, const bGPdata *gpd_src, bool in /* ************************************************** */ /* GP Stroke API */ -/** - * Ensure selection status of stroke is in sync with its points. - * \param gps: Grease pencil stroke - */ void BKE_gpencil_stroke_sync_selection(bGPdata *gpd, bGPDstroke *gps) { bGPDspoint *pt; @@ -1208,14 +1101,12 @@ void BKE_gpencil_curve_sync_selection(bGPdata *gpd, bGPDstroke *gps) } } -/* Assign unique stroke ID for selection. */ void BKE_gpencil_stroke_select_index_set(bGPdata *gpd, bGPDstroke *gps) { gpd->select_last_index++; gps->select_index = gpd->select_last_index; } -/* Reset unique stroke ID for selection. */ void BKE_gpencil_stroke_select_index_reset(bGPDstroke *gps) { gps->select_index = 0; @@ -1224,11 +1115,6 @@ void BKE_gpencil_stroke_select_index_reset(bGPDstroke *gps) /* ************************************************** */ /* GP Frame API */ -/** - * Delete the last stroke of the given frame. - * \param gpl: Grease pencil layer - * \param gpf: Grease pencil frame - */ void BKE_gpencil_frame_delete_laststroke(bGPDlayer *gpl, bGPDframe *gpf) { bGPDstroke *gps = (gpf) ? gpf->strokes.last : NULL; @@ -1260,11 +1146,6 @@ void BKE_gpencil_frame_delete_laststroke(bGPDlayer *gpl, bGPDframe *gpf) /* ************************************************** */ /* GP Layer API */ -/** - * Check if the given layer is able to be edited or not. - * \param gpl: Grease pencil layer - * \return True if layer is editable - */ bool BKE_gpencil_layer_is_editable(const bGPDlayer *gpl) { /* Sanity check */ @@ -1281,12 +1162,6 @@ bool BKE_gpencil_layer_is_editable(const bGPDlayer *gpl) return false; } -/** - * Look up the gp-frame on the requested frame number, but don't add a new one. - * \param gpl: Grease pencil layer - * \param cframe: Frame number - * \return Pointer to frame - */ bGPDframe *BKE_gpencil_layer_frame_find(bGPDlayer *gpl, int cframe) { bGPDframe *gpf; @@ -1303,16 +1178,6 @@ bGPDframe *BKE_gpencil_layer_frame_find(bGPDlayer *gpl, int cframe) return NULL; } -/** - * Get the appropriate gp-frame from a given layer - * - this sets the layer's actframe var (if allowed to) - * - extension beyond range (if first gp-frame is after all frame in interest and cannot add) - * - * \param gpl: Grease pencil layer - * \param cframe: Frame number - * \param addnew: Add option - * \return Pointer to new frame - */ bGPDframe *BKE_gpencil_layer_frame_get(bGPDlayer *gpl, int cframe, eGP_GetFrame_Mode addnew) { bGPDframe *gpf = NULL; @@ -1467,12 +1332,6 @@ bGPDframe *BKE_gpencil_layer_frame_get(bGPDlayer *gpl, int cframe, eGP_GetFrame_ return gpl->actframe; } -/** - * Delete the given frame from a layer. - * \param gpl: Grease pencil layer - * \param gpf: Grease pencil frame - * \return True if delete was done - */ bool BKE_gpencil_layer_frame_delete(bGPDlayer *gpl, bGPDframe *gpf) { bool changed = false; @@ -1496,12 +1355,6 @@ bool BKE_gpencil_layer_frame_delete(bGPDlayer *gpl, bGPDframe *gpf) return changed; } -/** - * Get layer by name - * \param gpd: Grease pencil data-block - * \param name: Layer name - * \return Pointer to layer - */ bGPDlayer *BKE_gpencil_layer_named_get(bGPdata *gpd, const char *name) { if (name[0] == '\0') { @@ -1510,12 +1363,6 @@ bGPDlayer *BKE_gpencil_layer_named_get(bGPdata *gpd, const char *name) return BLI_findstring(&gpd->layers, name, offsetof(bGPDlayer, info)); } -/** - * Get mask layer by name. - * \param gpl: Grease pencil layer - * \param name: Mask name - * \return Pointer to mask layer - */ bGPDlayer_Mask *BKE_gpencil_layer_mask_named_get(bGPDlayer *gpl, const char *name) { if (name[0] == '\0') { @@ -1524,12 +1371,6 @@ bGPDlayer_Mask *BKE_gpencil_layer_mask_named_get(bGPDlayer *gpl, const char *nam return BLI_findstring(&gpl->mask_layers, name, offsetof(bGPDlayer_Mask, name)); } -/** - * Add grease pencil mask layer. - * \param gpl: Grease pencil layer - * \param name: Name of the mask - * \return Pointer to new mask layer - */ bGPDlayer_Mask *BKE_gpencil_layer_mask_add(bGPDlayer *gpl, const char *name) { @@ -1541,11 +1382,6 @@ bGPDlayer_Mask *BKE_gpencil_layer_mask_add(bGPDlayer *gpl, const char *name) return mask; } -/** - * Remove grease pencil mask layer. - * \param gpl: Grease pencil layer - * \param mask: Grease pencil mask layer - */ void BKE_gpencil_layer_mask_remove(bGPDlayer *gpl, bGPDlayer_Mask *mask) { BLI_freelinkN(&gpl->mask_layers, mask); @@ -1553,11 +1389,6 @@ void BKE_gpencil_layer_mask_remove(bGPDlayer *gpl, bGPDlayer_Mask *mask) CLAMP_MIN(gpl->act_mask, 0); } -/** - * Remove any reference to mask layer. - * \param gpd: Grease pencil data-block - * \param name: Name of the mask layer - */ void BKE_gpencil_layer_mask_remove_ref(bGPdata *gpd, const char *name) { bGPDlayer_Mask *mask_next; @@ -1589,11 +1420,6 @@ static int gpencil_cb_sort_masks(const void *arg1, const void *arg2) return val; } -/** - * Sort grease pencil mask layers. - * \param gpd: Grease pencil data-block - * \param gpl: Grease pencil layer - */ void BKE_gpencil_layer_mask_sort(bGPdata *gpd, bGPDlayer *gpl) { /* Update sort index. */ @@ -1609,10 +1435,6 @@ void BKE_gpencil_layer_mask_sort(bGPdata *gpd, bGPDlayer *gpl) BLI_listbase_sort(&gpl->mask_layers, gpencil_cb_sort_masks); } -/** - * Sort all grease pencil mask layer. - * \param gpd: Grease pencil data-block - */ void BKE_gpencil_layer_mask_sort_all(bGPdata *gpd) { LISTBASE_FOREACH (bGPDlayer *, gpl, &gpd->layers) { @@ -1620,9 +1442,6 @@ void BKE_gpencil_layer_mask_sort_all(bGPdata *gpd) } } -/** - * Make a copy of a given gpencil mask layers. - */ void BKE_gpencil_layer_mask_copy(const bGPDlayer *gpl_src, bGPDlayer *gpl_dst) { BLI_listbase_clear(&gpl_dst->mask_layers); @@ -1633,9 +1452,6 @@ void BKE_gpencil_layer_mask_copy(const bGPDlayer *gpl_src, bGPDlayer *gpl_dst) } } -/** - * Clean any invalid mask layer. - */ void BKE_gpencil_layer_mask_cleanup(bGPdata *gpd, bGPDlayer *gpl) { LISTBASE_FOREACH_MUTABLE (bGPDlayer_Mask *, mask, &gpl->mask_layers) { @@ -1645,9 +1461,6 @@ void BKE_gpencil_layer_mask_cleanup(bGPdata *gpd, bGPDlayer *gpl) } } -/** - * Clean any invalid mask layer for all layers. - */ void BKE_gpencil_layer_mask_cleanup_all_layers(bGPdata *gpd) { LISTBASE_FOREACH (bGPDlayer *, gpl, &gpd->layers) { @@ -1676,21 +1489,11 @@ static int gpencil_cb_cmp_frame(void *thunk, const void *a, const void *b) return 0; } -/** - * Sort grease pencil frames. - * \param gpl: Grease pencil layer - * \param r_has_duplicate_frames: Duplicated frames flag - */ void BKE_gpencil_layer_frames_sort(struct bGPDlayer *gpl, bool *r_has_duplicate_frames) { BLI_listbase_sort_r(&gpl->frames, gpencil_cb_cmp_frame, r_has_duplicate_frames); } -/** - * Get the active grease pencil layer for editing. - * \param gpd: Grease pencil data-block - * \return Pointer to layer - */ bGPDlayer *BKE_gpencil_layer_active_get(bGPdata *gpd) { /* error checking */ @@ -1734,11 +1537,6 @@ bGPDlayer *BKE_gpencil_layer_get_by_name(bGPdata *gpd, char *name, int first_if_ return NULL; } -/** - * Set active grease pencil layer. - * \param gpd: Grease pencil data-block - * \param active: Grease pencil layer to set as active - */ void BKE_gpencil_layer_active_set(bGPdata *gpd, bGPDlayer *active) { /* error checking */ @@ -1761,11 +1559,6 @@ void BKE_gpencil_layer_active_set(bGPdata *gpd, bGPDlayer *active) } } -/** - * Set locked layers for autolock mode. - * \param gpd: Grease pencil data-block - * \param unlock: Unlock flag - */ void BKE_gpencil_layer_autolock_set(bGPdata *gpd, const bool unlock) { BLI_assert(gpd != NULL); @@ -1796,11 +1589,6 @@ void BKE_gpencil_layer_autolock_set(bGPdata *gpd, const bool unlock) } } -/** - * Delete grease pencil layer. - * \param gpd: Grease pencil data-block - * \param gpl: Grease pencil layer - */ void BKE_gpencil_layer_delete(bGPdata *gpd, bGPDlayer *gpl) { /* error checking */ @@ -1823,11 +1611,6 @@ void BKE_gpencil_layer_delete(bGPdata *gpd, bGPDlayer *gpl) BLI_freelinkN(&gpd->layers, gpl); } -/** - * Get grease pencil material from brush. - * \param brush: Brush - * \return Pointer to material - */ Material *BKE_gpencil_brush_material_get(Brush *brush) { Material *ma = NULL; @@ -1840,11 +1623,6 @@ Material *BKE_gpencil_brush_material_get(Brush *brush) return ma; } -/** - * Set grease pencil brush material. - * \param brush: Brush - * \param ma: Material - */ void BKE_gpencil_brush_material_set(Brush *brush, Material *ma) { BLI_assert(brush); @@ -1860,13 +1638,6 @@ void BKE_gpencil_brush_material_set(Brush *brush, Material *ma) } } -/** - * Adds the pinned material to the object if necessary. - * \param bmain: Main pointer - * \param ob: Grease pencil object - * \param brush: Brush - * \return Pointer to material - */ Material *BKE_gpencil_object_material_ensure_from_brush(Main *bmain, Object *ob, Brush *brush) { if (brush->gpencil_settings->flag & GP_BRUSH_MATERIAL_PINNED) { @@ -1885,13 +1656,6 @@ Material *BKE_gpencil_object_material_ensure_from_brush(Main *bmain, Object *ob, return BKE_object_material_get(ob, ob->actcol); } -/** - * Assigns the material to object (if not already present) and returns its index (mat_nr). - * \param bmain: Main pointer - * \param ob: Grease pencil object - * \param material: Material - * \return Index of the material - */ int BKE_gpencil_object_material_ensure(Main *bmain, Object *ob, Material *material) { if (!material) { @@ -1906,14 +1670,6 @@ int BKE_gpencil_object_material_ensure(Main *bmain, Object *ob, Material *materi return index; } -/** - * Creates a new grease-pencil material and assigns it to object. - * \param bmain: Main pointer - * \param ob: Grease pencil object - * \param name: Material name - * \param r_index: value is set to zero based index of the new material if \a r_index is not NULL. - * \return Material pointer. - */ Material *BKE_gpencil_object_material_new(Main *bmain, Object *ob, const char *name, int *r_index) { Material *ma = BKE_gpencil_material_add(bmain, name); @@ -1928,12 +1684,6 @@ Material *BKE_gpencil_object_material_new(Main *bmain, Object *ob, const char *n return ma; } -/** - * Returns the material for a brush with respect to its pinned state. - * \param ob: Grease pencil object - * \param brush: Brush - * \return Material pointer - */ Material *BKE_gpencil_object_material_from_brush_get(Object *ob, Brush *brush) { if ((brush) && (brush->gpencil_settings) && @@ -1945,12 +1695,6 @@ Material *BKE_gpencil_object_material_from_brush_get(Object *ob, Brush *brush) return BKE_object_material_get(ob, ob->actcol); } -/** - * Returns the material index for a brush with respect to its pinned state. - * \param ob: Grease pencil object - * \param brush: Brush - * \return Material index. - */ int BKE_gpencil_object_material_get_index_from_brush(Object *ob, Brush *brush) { if ((brush) && (brush->gpencil_settings->flag & GP_BRUSH_MATERIAL_PINNED)) { @@ -1960,12 +1704,6 @@ int BKE_gpencil_object_material_get_index_from_brush(Object *ob, Brush *brush) return ob->actcol - 1; } -/** - * Guaranteed to return a material assigned to object. Returns never NULL. - * \param bmain: Main pointer - * \param ob: Grease pencil object - * \return Material pointer. - */ Material *BKE_gpencil_object_material_ensure_from_active_input_toolsettings(Main *bmain, Object *ob, ToolSettings *ts) @@ -1978,13 +1716,6 @@ Material *BKE_gpencil_object_material_ensure_from_active_input_toolsettings(Main return BKE_gpencil_object_material_ensure_from_active_input_brush(bmain, ob, NULL); } -/** - * Guaranteed to return a material assigned to object. Returns never NULL. - * \param bmain: Main pointer - * \param ob: Grease pencil object. - * \param brush: Brush - * \return Material pointer - */ Material *BKE_gpencil_object_material_ensure_from_active_input_brush(Main *bmain, Object *ob, Brush *brush) @@ -2002,12 +1733,6 @@ Material *BKE_gpencil_object_material_ensure_from_active_input_brush(Main *bmain return BKE_gpencil_object_material_ensure_from_active_input_material(ob); } -/** - * Guaranteed to return a material assigned to object. Returns never NULL. - * Only use this for materials unrelated to user input. - * \param ob: Grease pencil object - * \return Material pointer - */ Material *BKE_gpencil_object_material_ensure_from_active_input_material(Object *ob) { Material *ma = BKE_object_material_get(ob, ob->actcol); @@ -2018,11 +1743,6 @@ Material *BKE_gpencil_object_material_ensure_from_active_input_material(Object * return BKE_material_default_gpencil(); } -/** - * Get active color, and add all default settings if we don't find anything. - * \param ob: Grease pencil object - * \return Material pointer - */ Material *BKE_gpencil_object_material_ensure_active(Object *ob) { Material *ma = NULL; @@ -2041,11 +1761,6 @@ Material *BKE_gpencil_object_material_ensure_active(Object *ob) } /* ************************************************** */ -/** - * Check if stroke has any point selected - * \param gps: Grease pencil stroke - * \return True if selected - */ bool BKE_gpencil_stroke_select_check(const bGPDstroke *gps) { const bGPDspoint *pt; @@ -2061,11 +1776,6 @@ bool BKE_gpencil_stroke_select_check(const bGPDstroke *gps) /* ************************************************** */ /* GP Object - Vertex Groups */ -/** - * Remove a vertex group. - * \param ob: Grease pencil object - * \param defgroup: deform group - */ void BKE_gpencil_vgroup_remove(Object *ob, bDeformGroup *defgroup) { bGPdata *gpd = ob->data; @@ -2105,10 +1815,6 @@ void BKE_gpencil_vgroup_remove(Object *ob, bDeformGroup *defgroup) DEG_id_tag_update(&gpd->id, ID_RECALC_TRANSFORM | ID_RECALC_GEOMETRY); } -/** - * Ensure stroke has vertex group. - * \param gps: Grease pencil stroke - */ void BKE_gpencil_dvert_ensure(bGPDstroke *gps) { if (gps->dvert == NULL) { @@ -2118,14 +1824,6 @@ void BKE_gpencil_dvert_ensure(bGPDstroke *gps) /* ************************************************** */ -/** - * Get range of selected frames in layer. - * Always the active frame is considered as selected, so if no more selected the range - * will be equal to the current active frame. - * \param gpl: Layer. - * \param r_initframe: Number of first selected frame. - * \param r_endframe: Number of last selected frame. - */ void BKE_gpencil_frame_range_selected(bGPDlayer *gpl, int *r_initframe, int *r_endframe) { *r_initframe = gpl->actframe->framenum; @@ -2143,14 +1841,6 @@ void BKE_gpencil_frame_range_selected(bGPDlayer *gpl, int *r_initframe, int *r_e } } -/** - * Get Falloff factor base on frame range - * \param gpf: Frame. - * \param actnum: Number of active frame in layer. - * \param f_init: Number of first selected frame. - * \param f_end: Number of last selected frame. - * \param cur_falloff: Curve with falloff factors. - */ float BKE_gpencil_multiframe_falloff_calc( bGPDframe *gpf, int actnum, int f_init, int f_end, CurveMapping *cur_falloff) { @@ -2182,12 +1872,6 @@ float BKE_gpencil_multiframe_falloff_calc( return value; } -/** - * Reassign strokes using a material. - * \param gpd: Grease pencil data-block - * \param totcol: Total materials - * \param index: Index of the material - */ void BKE_gpencil_material_index_reassign(bGPdata *gpd, int totcol, int index) { LISTBASE_FOREACH (bGPDlayer *, gpl, &gpd->layers) { @@ -2203,12 +1887,6 @@ void BKE_gpencil_material_index_reassign(bGPdata *gpd, int totcol, int index) } } -/** - * Remove strokes using a material. - * \param gpd: Grease pencil data-block - * \param index: Index of the material - * \return True if removed - */ bool BKE_gpencil_material_index_used(bGPdata *gpd, int index) { LISTBASE_FOREACH (bGPDlayer *, gpl, &gpd->layers) { @@ -2224,12 +1902,6 @@ bool BKE_gpencil_material_index_used(bGPdata *gpd, int index) return false; } -/** - * Remap material - * \param gpd: Grease pencil data-block - * \param remap: Remap index - * \param remap_len: Remap length - */ void BKE_gpencil_material_remap(struct bGPdata *gpd, const unsigned int *remap, unsigned int remap_len) @@ -2255,15 +1927,6 @@ void BKE_gpencil_material_remap(struct bGPdata *gpd, #undef MAT_NR_REMAP } -/** - * Load a table with material conversion index for merged materials. - * \param ob: Grease pencil object. - * \param hue_threshold: Threshold for Hue. - * \param sat_threshold: Threshold for Saturation. - * \param val_threshold: Threshold for Value. - * \param r_mat_table: return material table. - * \return True if done. - */ bool BKE_gpencil_merge_materials_table_get(Object *ob, const float hue_threshold, const float sat_threshold, @@ -2383,15 +2046,6 @@ bool BKE_gpencil_merge_materials_table_get(Object *ob, return changed; } -/** - * Merge similar materials - * \param ob: Grease pencil object - * \param hue_threshold: Threshold for Hue - * \param sat_threshold: Threshold for Saturation - * \param val_threshold: Threshold for Value - * \param r_removed: Number of materials removed - * \return True if done - */ bool BKE_gpencil_merge_materials(Object *ob, const float hue_threshold, const float sat_threshold, @@ -2450,10 +2104,6 @@ bool BKE_gpencil_merge_materials(Object *ob, return changed; } -/** - * Calc grease pencil statistics functions. - * \param gpd: Grease pencil data-block - */ void BKE_gpencil_stats_update(bGPdata *gpd) { gpd->totlayer = 0; @@ -2473,12 +2123,6 @@ void BKE_gpencil_stats_update(bGPdata *gpd) } } -/** - * Get material index (0-based like mat_nr not actcol). - * \param ob: Grease pencil object - * \param ma: Material - * \return Index of the material - */ int BKE_gpencil_object_material_index_get(Object *ob, Material *ma) { short *totcol = BKE_object_material_len_p(ob); @@ -2521,11 +2165,6 @@ Material *BKE_gpencil_object_material_ensure_by_name(Main *bmain, return BKE_gpencil_object_material_new(bmain, ob, name, r_index); } -/** - * Create a default palette. - * \param bmain: Main pointer - * \param scene: Scene - */ void BKE_gpencil_palette_ensure(Main *bmain, Scene *scene) { const char *hexcol[] = { @@ -2575,15 +2214,6 @@ void BKE_gpencil_palette_ensure(Main *bmain, Scene *scene) BKE_paint_palette_set(&ts->gp_vertexpaint->paint, palette); } -/** - * Create grease pencil strokes from image - * \param sima: Image - * \param gpd: Grease pencil data-block - * \param gpf: Grease pencil frame - * \param size: Size - * \param mask: Mask - * \return True if done - */ bool BKE_gpencil_from_image( SpaceImage *sima, bGPdata *gpd, bGPDframe *gpf, const float size, const bool mask) { @@ -2919,11 +2549,6 @@ void BKE_gpencil_visible_stroke_advanced_iter(ViewLayer *view_layer, } } -/** - * Update original pointers in evaluated frame. - * \param gpf_orig: Original grease-pencil frame. - * \param gpf_eval: Evaluated grease pencil frame. - */ void BKE_gpencil_frame_original_pointers_update(const struct bGPDframe *gpf_orig, const struct bGPDframe *gpf_eval) { @@ -2952,11 +2577,6 @@ void BKE_gpencil_frame_original_pointers_update(const struct bGPDframe *gpf_orig } } -/** - * Update pointers of eval data to original data to keep references. - * \param ob_orig: Original grease pencil object - * \param ob_eval: Evaluated grease pencil object - */ void BKE_gpencil_update_orig_pointers(const Object *ob_orig, const Object *ob_eval) { bGPdata *gpd_eval = (bGPdata *)ob_eval->data; @@ -2987,13 +2607,6 @@ void BKE_gpencil_update_orig_pointers(const Object *ob_orig, const Object *ob_ev } } -/** - * Get parent matrix, including layer parenting. - * \param depsgraph: Depsgraph - * \param obact: Grease pencil object - * \param gpl: Grease pencil layer - * \param diff_mat: Result parent matrix - */ void BKE_gpencil_layer_transform_matrix_get(const Depsgraph *depsgraph, Object *obact, bGPDlayer *gpl, @@ -3042,11 +2655,6 @@ void BKE_gpencil_layer_transform_matrix_get(const Depsgraph *depsgraph, unit_m4(diff_mat); /* not defined type */ } -/** - * Update parent matrix and local transforms. - * \param depsgraph: Depsgraph - * \param ob: Grease pencil object - */ void BKE_gpencil_update_layer_transforms(const Depsgraph *depsgraph, Object *ob) { if (ob->type != OB_GPENCIL) { @@ -3106,12 +2714,6 @@ void BKE_gpencil_update_layer_transforms(const Depsgraph *depsgraph, Object *ob) } } -/** - * Find material by name prefix. - * \param ob: Object pointer - * \param name_prefix: Prefix name of the material - * \return Index - */ int BKE_gpencil_material_find_index_by_name_prefix(Object *ob, const char *name_prefix) { const int name_prefix_len = strlen(name_prefix); @@ -3126,7 +2728,6 @@ int BKE_gpencil_material_find_index_by_name_prefix(Object *ob, const char *name_ return -1; } -/* Create a hash with the list of selected frame number. */ void BKE_gpencil_frame_selected_hash(bGPdata *gpd, struct GHash *r_list) { const bool is_multiedit = (bool)GPENCIL_MULTIEDIT_SESSIONS_ON(gpd); diff --git a/source/blender/blenkernel/intern/gpencil_curve.c b/source/blender/blenkernel/intern/gpencil_curve.c index 98e481e6ea8..d633678b873 100644 --- a/source/blender/blenkernel/intern/gpencil_curve.c +++ b/source/blender/blenkernel/intern/gpencil_curve.c @@ -477,17 +477,6 @@ static void gpencil_editstroke_deselect_all(bGPDcurve *gpc) gpc->flag &= ~GP_CURVE_SELECT; } -/** - * Convert a curve object to grease pencil stroke. - * - * \param bmain: Main thread pointer - * \param scene: Original scene. - * \param ob_gp: Grease pencil object to add strokes. - * \param ob_cu: Curve to convert. - * \param use_collections: Create layers using collection names. - * \param scale_thickness: Scale thickness factor. - * \param sample: Sample distance, zero to disable. - */ void BKE_gpencil_convert_curve(Main *bmain, Scene *scene, Object *ob_gp, @@ -639,9 +628,6 @@ static bGPDcurve *gpencil_stroke_editcurve_generate_edgecases(bGPDstroke *gps, return NULL; } -/** - * Creates a bGPDcurve by doing a cubic curve fitting on the grease pencil stroke points. - */ bGPDcurve *BKE_gpencil_stroke_editcurve_generate(bGPDstroke *gps, const float error_threshold, const float corner_angle, @@ -753,9 +739,6 @@ bGPDcurve *BKE_gpencil_stroke_editcurve_generate(bGPDstroke *gps, return editcurve; } -/** - * Updates the editcurve for a stroke. Frees the old curve if one exists and generates a new one. - */ void BKE_gpencil_stroke_editcurve_update(bGPdata *gpd, bGPDlayer *gpl, bGPDstroke *gps) { if (gps == NULL || gps->totpoints < 0) { @@ -778,9 +761,6 @@ void BKE_gpencil_stroke_editcurve_update(bGPdata *gpd, bGPDlayer *gpl, bGPDstrok gps->editcurve = editcurve; } -/** - * Sync the selection from stroke to editcurve - */ void BKE_gpencil_editcurve_stroke_sync_selection(bGPdata *UNUSED(gpd), bGPDstroke *gps, bGPDcurve *gpc) @@ -807,9 +787,6 @@ void BKE_gpencil_editcurve_stroke_sync_selection(bGPdata *UNUSED(gpd), } } -/** - * Sync the selection from editcurve to stroke - */ void BKE_gpencil_stroke_editcurve_sync_selection(bGPdata *gpd, bGPDstroke *gps, bGPDcurve *gpc) { if (gpc->flag & GP_CURVE_SELECT) { @@ -1055,9 +1032,6 @@ static float *gpencil_stroke_points_from_editcurve_fixed_resolu(bGPDcurve_point return (float(*))r_points; } -/** - * Recalculate stroke points with the editcurve of the stroke. - */ void BKE_gpencil_stroke_update_geometry_from_editcurve(bGPDstroke *gps, const uint resolution, const bool adaptive) @@ -1142,9 +1116,6 @@ void BKE_gpencil_stroke_update_geometry_from_editcurve(bGPDstroke *gps, MEM_freeN(points); } -/** - * Recalculate the handles of the edit curve of a grease pencil stroke - */ void BKE_gpencil_editcurve_recalculate_handles(bGPDstroke *gps) { if (gps == NULL || gps->editcurve == NULL) { diff --git a/source/blender/blenkernel/intern/gpencil_geom.cc b/source/blender/blenkernel/intern/gpencil_geom.cc index fffc13c49a8..aca85984989 100644 --- a/source/blender/blenkernel/intern/gpencil_geom.cc +++ b/source/blender/blenkernel/intern/gpencil_geom.cc @@ -67,15 +67,8 @@ using blender::float3; using blender::Span; -/* GP Object - Boundbox Support */ -/** - *Get min/max coordinate bounds for single stroke. - * \param gps: Grease pencil stroke - * \param use_select: Include only selected points - * \param r_min: Result minimum coordinates - * \param r_max: Result maximum coordinates - * \return True if it was possible to calculate - */ +/* GP Object - Bound-box Support. */ + bool BKE_gpencil_stroke_minmax(const bGPDstroke *gps, const bool use_select, float r_min[3], @@ -104,13 +97,6 @@ bool BKE_gpencil_stroke_minmax(const bGPDstroke *gps, return changed; } -/** - * Get min/max bounds of all strokes in grease pencil data-block. - * \param gpd: Grease pencil datablock - * \param r_min: Result minimum coordinates - * \param r_max: Result maximum coordinates - * \return True if it was possible to calculate - */ bool BKE_gpencil_data_minmax(const bGPdata *gpd, float r_min[3], float r_max[3]) { bool changed = false; @@ -134,11 +120,6 @@ bool BKE_gpencil_data_minmax(const bGPdata *gpd, float r_min[3], float r_max[3]) return changed; } -/** - * Compute center of bounding box. - * \param gpd: Grease pencil data-block - * \param r_centroid: Location of the center - */ void BKE_gpencil_centroid_3d(bGPdata *gpd, float r_centroid[3]) { float3 min; @@ -149,10 +130,6 @@ void BKE_gpencil_centroid_3d(bGPdata *gpd, float r_centroid[3]) mul_v3_v3fl(r_centroid, tot, 0.5f); } -/** - * Compute stroke bounding box. - * \param gps: Grease pencil Stroke - */ void BKE_gpencil_stroke_boundingbox_calc(bGPDstroke *gps) { INIT_MINMAX(gps->boundbox_min, gps->boundbox_max); @@ -184,11 +161,6 @@ static void boundbox_gpencil(Object *ob) bb->flag &= ~BOUNDBOX_DIRTY; } -/** - * Get grease pencil object bounding box. - * \param ob: Grease pencil object - * \return Bounding box - */ BoundBox *BKE_gpencil_boundbox_get(Object *ob) { if (ELEM(nullptr, ob, ob->data)) { @@ -431,12 +403,6 @@ static void stroke_interpolate_deform_weights( } } -/** - * Resample a stroke - * \param gpd: Grease pencil data-block - * \param gps: Stroke to sample - * \param dist: Distance of one segment - */ bool BKE_gpencil_stroke_sample(bGPdata *gpd, bGPDstroke *gps, const float dist, const bool select) { bGPDspoint *pt = gps->points; @@ -594,15 +560,6 @@ static bool BKE_gpencil_stroke_extra_points(bGPDstroke *gps, return true; } -/** - * Backbone stretch similar to Freestyle. - * \param gps: Stroke to sample. - * \param dist: Length of the added section. - * \param overshoot_fac: Relative length of the curve which is used to determine the extension. - * \param mode: Affect to Start, End or Both extremes (0->Both, 1->Start, 2->End) - * \param follow_curvature: True for approximating curvature of given overshoot. - * \param extra_point_count: When follow_curvature is true, use this amount of extra points - */ bool BKE_gpencil_stroke_stretch(bGPDstroke *gps, const float dist, const float overshoot_fac, @@ -779,12 +736,6 @@ bool BKE_gpencil_stroke_stretch(bGPDstroke *gps, return true; } -/** - * Trim stroke to needed segments - * \param gps: Target stroke - * \param index_from: the index of the first point to be used in the trimmed result - * \param index_to: the index of the last point to be used in the trimmed result - */ bool BKE_gpencil_stroke_trim_points(bGPDstroke *gps, const int index_from, const int index_to) { bGPDspoint *pt = gps->points, *new_pt; @@ -837,15 +788,6 @@ bool BKE_gpencil_stroke_trim_points(bGPDstroke *gps, const int index_from, const return true; } -/** - * Split stroke. - * \param gpd: Grease pencil data-block - * \param gpf: Grease pencil frame - * \param gps: Grease pencil original stroke - * \param before_index: Position of the point to split - * \param remaining_gps: Secondary stroke after split. - * \return True if the split was done - */ bool BKE_gpencil_stroke_split(bGPdata *gpd, bGPDframe *gpf, bGPDstroke *gps, @@ -898,12 +840,6 @@ bool BKE_gpencil_stroke_split(bGPdata *gpd, return true; } -/** - * Shrink the stroke by length. - * \param gps: Stroke to shrink - * \param dist: delta length - * \param mode: 1->Start, 2->End - */ bool BKE_gpencil_stroke_shrink(bGPDstroke *gps, const float dist, const short mode) { #define START 1 @@ -976,12 +912,6 @@ bool BKE_gpencil_stroke_shrink(bGPDstroke *gps, const float dist, const short mo return true; } -/** - * Apply smooth position to stroke point. - * \param gps: Stroke to smooth - * \param i: Point index - * \param inf: Amount of smoothing to apply - */ bool BKE_gpencil_stroke_smooth_point(bGPDstroke *gps, int i, float inf) { bGPDspoint *pt = &gps->points[i]; @@ -1054,12 +984,6 @@ bool BKE_gpencil_stroke_smooth_point(bGPDstroke *gps, int i, float inf) return true; } -/** - * Apply smooth strength to stroke point. - * \param gps: Stroke to smooth - * \param point_index: Point index - * \param influence: Amount of smoothing to apply - */ bool BKE_gpencil_stroke_smooth_strength(bGPDstroke *gps, int point_index, float influence) { bGPDspoint *ptb = &gps->points[point_index]; @@ -1132,12 +1056,6 @@ bool BKE_gpencil_stroke_smooth_strength(bGPDstroke *gps, int point_index, float return true; } -/** - * Apply smooth for thickness to stroke point (use pressure). - * \param gps: Stroke to smooth - * \param point_index: Point index - * \param influence: Amount of smoothing to apply - */ bool BKE_gpencil_stroke_smooth_thickness(bGPDstroke *gps, int point_index, float influence) { bGPDspoint *ptb = &gps->points[point_index]; @@ -1209,12 +1127,6 @@ bool BKE_gpencil_stroke_smooth_thickness(bGPDstroke *gps, int point_index, float return true; } -/** - * Apply smooth for UV rotation to stroke point (use pressure). - * \param gps: Stroke to smooth - * \param point_index: Point index - * \param influence: Amount of smoothing to apply - */ bool BKE_gpencil_stroke_smooth_uv(bGPDstroke *gps, int point_index, float influence) { bGPDspoint *ptb = &gps->points[point_index]; @@ -1266,14 +1178,6 @@ bool BKE_gpencil_stroke_smooth_uv(bGPDstroke *gps, int point_index, float influe return true; } -/** - * Get points of stroke always flat to view not affected - * by camera view or view position. - * \param points: Array of grease pencil points (3D) - * \param totpoints: Total of points - * \param points2d: Result array of 2D points - * \param r_direction: Return Concave (-1), Convex (1), or Auto-detect (0) - */ void BKE_gpencil_stroke_2d_flat(const bGPDspoint *points, int totpoints, float (*points2d)[2], @@ -1348,17 +1252,6 @@ void BKE_gpencil_stroke_2d_flat(const bGPDspoint *points, *r_direction = (cross >= 0.0f) ? 1 : -1; } -/** - * Get points of stroke always flat to view not affected by camera view or view position - * using another stroke as reference. - * \param ref_points: Array of reference points (3D) - * \param ref_totpoints: Total reference points - * \param points: Array of points to flat (3D) - * \param totpoints: Total points - * \param points2d: Result array of 2D points - * \param scale: Scale factor - * \param r_direction: Return Concave (-1), Convex (1), or Auto-detect (0) - */ void BKE_gpencil_stroke_2d_flat_ref(const bGPDspoint *ref_points, int ref_totpoints, const bGPDspoint *points, @@ -1482,10 +1375,6 @@ static void gpencil_calc_stroke_fill_uv(const float (*points2d)[2], } } -/** - * Triangulate stroke to generate data for filling areas. - * \param gps: Grease pencil stroke - */ void BKE_gpencil_stroke_fill_triangulate(bGPDstroke *gps) { BLI_assert(gps->totpoints >= 3); @@ -1545,10 +1434,6 @@ void BKE_gpencil_stroke_fill_triangulate(bGPDstroke *gps) MEM_SAFE_FREE(uv); } -/** - * Update Stroke UV data. - * \param gps: Grease pencil stroke - */ void BKE_gpencil_stroke_uv_update(bGPDstroke *gps) { if (gps == nullptr || gps->totpoints == 0) { @@ -1564,11 +1449,6 @@ void BKE_gpencil_stroke_uv_update(bGPDstroke *gps) } } -/** - * Recalc all internal geometry data for the stroke - * \param gpd: Grease pencil data-block - * \param gps: Grease pencil stroke - */ void BKE_gpencil_stroke_geometry_update(bGPdata *gpd, bGPDstroke *gps) { if (gps == nullptr) { @@ -1606,12 +1486,6 @@ void BKE_gpencil_stroke_geometry_update(bGPdata *gpd, bGPDstroke *gps) BKE_gpencil_stroke_boundingbox_calc(gps); } -/** - * Calculate grease pencil stroke length. - * \param gps: Grease pencil stroke - * \param use_3d: Set to true to use 3D points - * \return Length of the stroke - */ float BKE_gpencil_stroke_length(const bGPDstroke *gps, bool use_3d) { if (!gps->points || gps->totpoints < 2) { @@ -1632,7 +1506,6 @@ float BKE_gpencil_stroke_length(const bGPDstroke *gps, bool use_3d) return total_length; } -/** Calculate grease pencil stroke length between points. */ float BKE_gpencil_stroke_segment_length(const struct bGPDstroke *gps, const int start_index, const int end_index, @@ -1660,10 +1533,6 @@ float BKE_gpencil_stroke_segment_length(const struct bGPDstroke *gps, return total_length; } -/** - * Trim stroke to the first intersection or loop. - * \param gps: Stroke data - */ bool BKE_gpencil_stroke_trim(bGPdata *gpd, bGPDstroke *gps) { if (gps->totpoints < 4) { @@ -1756,10 +1625,6 @@ bool BKE_gpencil_stroke_trim(bGPdata *gpd, bGPDstroke *gps) return intersect; } -/** - * Close grease pencil stroke. - * \param gps: Stroke to close - */ bool BKE_gpencil_stroke_close(bGPDstroke *gps) { bGPDspoint *pt1 = nullptr; @@ -1845,13 +1710,6 @@ bool BKE_gpencil_stroke_close(bGPDstroke *gps) return true; } -/** - * Dissolve points in stroke. - * \param gpd: Grease pencil data-block - * \param gpf: Grease pencil frame - * \param gps: Grease pencil stroke - * \param tag: Type of tag for point - */ void BKE_gpencil_dissolve_points(bGPdata *gpd, bGPDframe *gpf, bGPDstroke *gps, const short tag) { bGPDspoint *pt; @@ -1934,11 +1792,6 @@ void BKE_gpencil_dissolve_points(bGPdata *gpd, bGPDframe *gpf, bGPDstroke *gps, } } -/** - * Calculate stroke normals. - * \param gps: Grease pencil stroke - * \param r_normal: Return Normal vector normalized - */ void BKE_gpencil_stroke_normal(const bGPDstroke *gps, float r_normal[3]) { if (gps->totpoints < 3) { @@ -1971,16 +1824,6 @@ void BKE_gpencil_stroke_normal(const bGPDstroke *gps, float r_normal[3]) /* Stroke Simplify ------------------------------------- */ -/** - * Reduce a series of points to a simplified version, but - * maintains the general shape of the series - * - * Ramer - Douglas - Peucker algorithm - * by http://en.wikipedia.org/wiki/Ramer-Douglas-Peucker_algorithm - * \param gpd: Grease pencil data-block - * \param gps: Grease pencil stroke - * \param epsilon: Epsilon value to define precision of the algorithm - */ void BKE_gpencil_stroke_simplify_adaptive(bGPdata *gpd, bGPDstroke *gps, float epsilon) { bGPDspoint *old_points = (bGPDspoint *)MEM_dupallocN(gps->points); @@ -2085,11 +1928,6 @@ void BKE_gpencil_stroke_simplify_adaptive(bGPdata *gpd, bGPDstroke *gps, float e MEM_SAFE_FREE(marked); } -/** - * Simplify alternate vertex of stroke except extremes. - * \param gpd: Grease pencil data-block - * \param gps: Grease pencil stroke - */ void BKE_gpencil_stroke_simplify_fixed(bGPdata *gpd, bGPDstroke *gps) { if (gps->totpoints < 5) { @@ -2150,13 +1988,6 @@ void BKE_gpencil_stroke_simplify_fixed(bGPdata *gpd, bGPDstroke *gps) MEM_SAFE_FREE(old_dvert); } -/** - * Subdivide a stroke - * \param gpd: Grease pencil data-block - * \param gps: Stroke - * \param level: Level of subdivision - * \param type: Type of subdivision - */ void BKE_gpencil_stroke_subdivide(bGPdata *gpd, bGPDstroke *gps, int level, int type) { bGPDspoint *temp_points; @@ -2271,17 +2102,6 @@ void BKE_gpencil_stroke_subdivide(bGPdata *gpd, bGPDstroke *gps, int level, int /* Merge by distance ------------------------------------- */ -/** - * Reduce a series of points when the distance is below a threshold. - * Special case for first and last points (both are kept) for other points, - * the merge point always is at first point. - * - * \param gpd: Grease pencil data-block. - * \param gpf: Grease Pencil frame. - * \param gps: Grease Pencil stroke. - * \param threshold: Distance between points. - * \param use_unselected: Set to true to analyze all stroke and not only selected points. - */ void BKE_gpencil_stroke_merge_distance(bGPdata *gpd, bGPDframe *gpf, bGPDstroke *gps, @@ -2639,22 +2459,6 @@ static void make_element_name(const char *obname, const char *name, const int ma BLI_strncpy_utf8(r_name, str, maxlen); } -/** - * Convert a mesh object to grease pencil stroke. - * - * \param bmain: Main thread pointer. - * \param depsgraph: Original depsgraph. - * \param scene: Original scene. - * \param ob_gp: Grease pencil object to add strokes. - * \param ob_mesh: Mesh to convert. - * \param angle: Limit angle to consider a edge-loop ends. - * \param thickness: Thickness of the strokes. - * \param offset: Offset along the normals. - * \param matrix: Transformation matrix. - * \param frame_offset: Destination frame number offset. - * \param use_seams: Only export seam edges. - * \param use_faces: Export faces as filled strokes. - */ bool BKE_gpencil_convert_mesh(Main *bmain, Depsgraph *depsgraph, Scene *scene, @@ -2807,11 +2611,6 @@ bool BKE_gpencil_convert_mesh(Main *bmain, return true; } -/** - * Apply grease pencil Transforms. - * \param gpd: Grease pencil data-block - * \param mat: Transformation matrix - */ void BKE_gpencil_transform(bGPdata *gpd, const float mat[4][4]) { if (gpd == nullptr) { @@ -2845,7 +2644,6 @@ void BKE_gpencil_transform(bGPdata *gpd, const float mat[4][4]) } } -/* Used for "move only origins" in object_data_transform.c */ int BKE_gpencil_stroke_point_count(const bGPdata *gpd) { int total_points = 0; @@ -2872,7 +2670,6 @@ int BKE_gpencil_stroke_point_count(const bGPdata *gpd) return total_points; } -/* Used for "move only origins" in object_data_transform.c */ void BKE_gpencil_point_coords_get(bGPdata *gpd, GPencilPointCoordinates *elem_data) { if (gpd == nullptr) { @@ -2903,7 +2700,6 @@ void BKE_gpencil_point_coords_get(bGPdata *gpd, GPencilPointCoordinates *elem_da } } -/* Used for "move only origins" in object_data_transform.c */ void BKE_gpencil_point_coords_apply(bGPdata *gpd, const GPencilPointCoordinates *elem_data) { if (gpd == nullptr) { @@ -2937,7 +2733,6 @@ void BKE_gpencil_point_coords_apply(bGPdata *gpd, const GPencilPointCoordinates } } -/* Used for "move only origins" in object_data_transform.c */ void BKE_gpencil_point_coords_apply_with_mat4(bGPdata *gpd, const GPencilPointCoordinates *elem_data, const float mat[4][4]) @@ -2974,10 +2769,6 @@ void BKE_gpencil_point_coords_apply_with_mat4(bGPdata *gpd, } } -/** - * Set a random color to stroke using vertex color. - * \param gps: Stroke - */ void BKE_gpencil_stroke_set_random_color(bGPDstroke *gps) { BLI_assert(gps->totpoints > 0); @@ -2993,7 +2784,6 @@ void BKE_gpencil_stroke_set_random_color(bGPDstroke *gps) } } -/* Flip stroke. */ void BKE_gpencil_stroke_flip(bGPDstroke *gps) { /* Reverse points. */ @@ -3103,20 +2893,6 @@ static void gpencil_stroke_join_islands(bGPdata *gpd, BKE_gpencil_free_stroke(gps_last); } -/* Split the given stroke into several new strokes, partitioning - * it based on whether the stroke points have a particular flag - * is set (e.g. "GP_SPOINT_SELECT" in most cases, but not always) - * - * The algorithm used here is as follows: - * 1) We firstly identify the number of "islands" of non-tagged points - * which will all end up being in new strokes. - * - In the most extreme case (i.e. every other vert is a 1-vert island), - * we have at most n / 2 islands - * - Once we start having larger islands than that, the number required - * becomes much less - * 2) Each island gets converted to a new stroke - * If the number of points is <= limit, the stroke is deleted - */ bGPDstroke *BKE_gpencil_stroke_delete_tagged_points(bGPdata *gpd, bGPDframe *gpf, bGPDstroke *gps, @@ -3126,6 +2902,16 @@ bGPDstroke *BKE_gpencil_stroke_delete_tagged_points(bGPdata *gpd, const bool flat_cap, const int limit) { + /* The algorithm used here is as follows: + * 1) We firstly identify the number of "islands" of non-tagged points + * which will all end up being in new strokes. + * - In the most extreme case (i.e. every other vert is a 1-vert island), + * we have at most `n / 2` islands + * - Once we start having larger islands than that, the number required + * becomes much less + * 2) Each island gets converted to a new stroke + * If the number of points is <= limit, the stroke is deleted. */ + tGPDeleteIsland *islands = (tGPDeleteIsland *)MEM_callocN( sizeof(tGPDeleteIsland) * (gps->totpoints + 1) / 2, "gp_point_islands"); bool in_island = false; @@ -3430,7 +3216,6 @@ static void gpencil_stroke_copy_point(bGPDstroke *gps, } } -/* Join two strokes using the shortest distance (reorder stroke if necessary ) */ void BKE_gpencil_stroke_join(bGPDstroke *gps_a, bGPDstroke *gps_b, const bool leave_gaps, @@ -3560,7 +3345,6 @@ void BKE_gpencil_stroke_join(bGPDstroke *gps_a, } } -/* Copy the stroke of the frame to all frames selected (except current). */ void BKE_gpencil_stroke_copy_to_keyframes( bGPdata *gpd, bGPDlayer *gpl, bGPDframe *gpf, bGPDstroke *gps, const bool tail) { @@ -3649,15 +3433,6 @@ static tSampleEdge *new_sample_edge_from_sample_points(tSamplePoint *from, tSamp return new_edge; } -/** - * Subdivide the grease pencil stroke so the number of points is target_number. - * Does not change the shape of the stroke. The new points will be distributed as - * uniformly as possible by repeatedly subdividing the current longest edge. - * - * \param gps: The stroke to be up-sampled. - * \param target_number: The number of points the up-sampled stroke should have. - * \param select: Select/Deselect the stroke. - */ void BKE_gpencil_stroke_uniform_subdivide(bGPdata *gpd, bGPDstroke *gps, const uint32_t target_number, @@ -3793,12 +3568,6 @@ void BKE_gpencil_stroke_uniform_subdivide(bGPdata *gpd, BKE_gpencil_stroke_geometry_update(gpd, gps); } -/** - * Stroke to view space - * Transforms a stroke to view space. This allows for manipulations in 2D but also easy conversion - * back to 3D. - * NOTE: also takes care of parent space transform - */ void BKE_gpencil_stroke_to_view_space(RegionView3D *rv3d, bGPDstroke *gps, const float diff_mat[4][4]) @@ -3812,12 +3581,6 @@ void BKE_gpencil_stroke_to_view_space(RegionView3D *rv3d, } } -/** - * Stroke from view space - * Transforms a stroke from view space back to world space. Inverse of - * BKE_gpencil_stroke_to_view_space - * NOTE: also takes care of parent space transform - */ void BKE_gpencil_stroke_from_view_space(RegionView3D *rv3d, bGPDstroke *gps, const float diff_mat[4][4]) @@ -4238,12 +4001,6 @@ static ListBase *gpencil_stroke_perimeter_ex(const bGPdata *gpd, return perimeter_list; } -/** - * Calculates the perimeter of a stroke projected from the view and - * returns it as a new stroke. - * \param subdivisions: Number of subdivisions for the start and end caps - * \return: bGPDstroke pointer to stroke perimeter - */ bGPDstroke *BKE_gpencil_stroke_perimeter_from_view(struct RegionView3D *rv3d, bGPdata *gpd, const bGPDlayer *gpl, @@ -4310,7 +4067,6 @@ bGPDstroke *BKE_gpencil_stroke_perimeter_from_view(struct RegionView3D *rv3d, return perimeter_stroke; } -/** Get average pressure. */ float BKE_gpencil_stroke_average_pressure_get(bGPDstroke *gps) { @@ -4327,7 +4083,6 @@ float BKE_gpencil_stroke_average_pressure_get(bGPDstroke *gps) return tot / (float)gps->totpoints; } -/** Check if the thickness of the stroke is constant. */ bool BKE_gpencil_stroke_is_pressure_constant(bGPDstroke *gps) { if (gps->totpoints == 1) { diff --git a/source/blender/blenkernel/intern/gpencil_modifier.c b/source/blender/blenkernel/intern/gpencil_modifier.c index a6164340477..fb6dbc5402d 100644 --- a/source/blender/blenkernel/intern/gpencil_modifier.c +++ b/source/blender/blenkernel/intern/gpencil_modifier.c @@ -76,10 +76,6 @@ static GpencilVirtualModifierData virtualModifierCommonData; * each loop over all the geometry being evaluated. */ -/** - * Init grease pencil lattice deform data. - * \param ob: Grease pencil object - */ void BKE_gpencil_lattice_init(Object *ob) { LISTBASE_FOREACH (GpencilModifierData *, md, &ob->greasepencil_modifiers) { @@ -101,10 +97,6 @@ void BKE_gpencil_lattice_init(Object *ob) } } -/** - * Clear grease pencil lattice deform data. - * \param ob: Grease pencil object - */ void BKE_gpencil_lattice_clear(Object *ob) { LISTBASE_FOREACH (GpencilModifierData *, md, &ob->greasepencil_modifiers) { @@ -121,8 +113,6 @@ void BKE_gpencil_lattice_clear(Object *ob) /* *************************************************** */ /* Modifier Methods - Evaluation Loops, etc. */ -/* This is to include things that are not modifiers in the evaluation of the modifier stack, for - * example parenting to an armature or lattice without having a real modifier. */ GpencilModifierData *BKE_gpencil_modifiers_get_virtual_modifierlist( const Object *ob, GpencilVirtualModifierData *UNUSED(virtualModifierData)) { @@ -150,11 +140,6 @@ GpencilModifierData *BKE_gpencil_modifiers_get_virtual_modifierlist( return md; } -/** - * Check if object has grease pencil Geometry modifiers. - * \param ob: Grease pencil object - * \return True if exist - */ bool BKE_gpencil_has_geometry_modifiers(Object *ob) { LISTBASE_FOREACH (GpencilModifierData *, md, &ob->greasepencil_modifiers) { @@ -167,11 +152,6 @@ bool BKE_gpencil_has_geometry_modifiers(Object *ob) return false; } -/** - * Check if object has grease pencil Time modifiers. - * \param ob: Grease pencil object - * \return True if exist - */ bool BKE_gpencil_has_time_modifiers(Object *ob) { LISTBASE_FOREACH (GpencilModifierData *, md, &ob->greasepencil_modifiers) { @@ -184,11 +164,6 @@ bool BKE_gpencil_has_time_modifiers(Object *ob) return false; } -/** - * Check if object has grease pencil transform stroke modifiers. - * \param ob: Grease pencil object - * \return True if exist - */ bool BKE_gpencil_has_transform_modifiers(Object *ob) { LISTBASE_FOREACH (GpencilModifierData *, md, &ob->greasepencil_modifiers) { @@ -258,7 +233,6 @@ bool BKE_gpencil_is_first_lineart_in_stack(const Object *ob, const GpencilModifi return false; } -/* Get Time modifier frame number. */ int BKE_gpencil_time_modifier_cfra(Depsgraph *depsgraph, Scene *scene, Object *ob, @@ -292,11 +266,6 @@ int BKE_gpencil_time_modifier_cfra(Depsgraph *depsgraph, return nfra; } -/** - * Set current grease pencil active frame. - * \param depsgraph: Current depsgraph - * \param gpd: Grease pencil data-block. - */ void BKE_gpencil_frame_active_set(Depsgraph *depsgraph, bGPdata *gpd) { DEG_debug_print_eval(depsgraph, __func__, gpd->id.name, gpd); @@ -320,9 +289,6 @@ void BKE_gpencil_frame_active_set(Depsgraph *depsgraph, bGPdata *gpd) } } -/** - * Initialize grease pencil modifier. - */ void BKE_gpencil_modifier_init(void) { /* Initialize modifier types */ @@ -346,11 +312,6 @@ void BKE_gpencil_modifier_init(void) #endif } -/** - * Create new grease pencil modifier. - * \param type: Type of modifier - * \return New modifier pointer - */ GpencilModifierData *BKE_gpencil_modifier_new(int type) { const GpencilModifierTypeInfo *mti = BKE_gpencil_modifier_get_info(type); @@ -386,11 +347,6 @@ static void modifier_free_data_id_us_cb(void *UNUSED(userData), } } -/** - * Free grease pencil modifier data - * \param md: Modifier data - * \param flag: Flags - */ void BKE_gpencil_modifier_free_ex(GpencilModifierData *md, const int flag) { const GpencilModifierTypeInfo *mti = BKE_gpencil_modifier_get_info(md->type); @@ -411,16 +367,11 @@ void BKE_gpencil_modifier_free_ex(GpencilModifierData *md, const int flag) MEM_freeN(md); } -/** - * Free grease pencil modifier data - * \param md: Modifier data - */ void BKE_gpencil_modifier_free(GpencilModifierData *md) { BKE_gpencil_modifier_free_ex(md, 0); } -/* check unique name */ bool BKE_gpencil_modifier_unique_name(ListBase *modifiers, GpencilModifierData *gmd) { if (modifiers && gmd) { @@ -435,11 +386,6 @@ bool BKE_gpencil_modifier_unique_name(ListBase *modifiers, GpencilModifierData * return false; } -/** - * Check if grease pencil modifier depends on time. - * \param md: Modifier data - * \return True if depends on time - */ bool BKE_gpencil_modifier_depends_ontime(GpencilModifierData *md) { const GpencilModifierTypeInfo *mti = BKE_gpencil_modifier_get_info(md->type); @@ -447,11 +393,6 @@ bool BKE_gpencil_modifier_depends_ontime(GpencilModifierData *md) return mti->dependsOnTime && mti->dependsOnTime(md); } -/** - * Get grease pencil modifier information. - * \param type: Type of modifier - * \return Pointer to type - */ const GpencilModifierTypeInfo *BKE_gpencil_modifier_get_info(GpencilModifierType type) { /* type unsigned, no need to check < 0 */ @@ -463,12 +404,6 @@ const GpencilModifierTypeInfo *BKE_gpencil_modifier_get_info(GpencilModifierType return NULL; } -/** - * Get the idname of the modifier type's panel, which was defined in the #panelRegister callback. - * - * \param type: Type of modifier - * \param r_idname: ID name - */ void BKE_gpencil_modifierType_panel_id(GpencilModifierType type, char *r_idname) { const GpencilModifierTypeInfo *mti = BKE_gpencil_modifier_get_info(type); @@ -482,11 +417,6 @@ void BKE_gpencil_modifier_panel_expand(GpencilModifierData *md) md->ui_expand_flag |= UI_PANEL_DATA_EXPAND_ROOT; } -/** - * Generic grease pencil modifier copy data. - * \param md_src: Source modifier data - * \param md_dst: Target modifier data - */ void BKE_gpencil_modifier_copydata_generic(const GpencilModifierData *md_src, GpencilModifierData *md_dst) { @@ -516,12 +446,6 @@ static void gpencil_modifier_copy_data_id_us_cb(void *UNUSED(userData), } } -/** - * Copy grease pencil modifier data. - * \param md: Source modifier data - * \param target: Target modifier data - * \param flag: Flags - */ void BKE_gpencil_modifier_copydata_ex(GpencilModifierData *md, GpencilModifierData *target, const int flag) @@ -543,11 +467,6 @@ void BKE_gpencil_modifier_copydata_ex(GpencilModifierData *md, } } -/** - * Copy grease pencil modifier data. - * \param md: Source modifier data - * \param target: Target modifier data - */ void BKE_gpencil_modifier_copydata(GpencilModifierData *md, GpencilModifierData *target) { BKE_gpencil_modifier_copydata_ex(md, target, 0); @@ -566,11 +485,6 @@ GpencilModifierData *BKE_gpencil_modifiers_findby_type(Object *ob, GpencilModifi return md; } -/** - * Set grease pencil modifier error. - * \param md: Modifier data - * \param _format: Format - */ void BKE_gpencil_modifier_set_error(GpencilModifierData *md, const char *_format, ...) { char buffer[512]; @@ -591,12 +505,6 @@ void BKE_gpencil_modifier_set_error(GpencilModifierData *md, const char *_format CLOG_STR_ERROR(&LOG, md->error); } -/** - * Check whether given modifier is not local (i.e. from linked data) when the object is a library - * override. - * - * \param gmd: May be NULL, in which case we consider it as a non-local modifier case. - */ bool BKE_gpencil_modifier_is_nonlocal_in_liboverride(const Object *ob, const GpencilModifierData *gmd) { @@ -604,12 +512,6 @@ bool BKE_gpencil_modifier_is_nonlocal_in_liboverride(const Object *ob, (gmd == NULL || (gmd->flag & eGpencilModifierFlag_OverrideLibrary_Local) == 0)); } -/** - * Link grease pencil modifier related IDs. - * \param ob: Grease pencil object - * \param walk: Walk option - * \param userData: User data - */ void BKE_gpencil_modifiers_foreach_ID_link(Object *ob, GreasePencilIDWalkFunc walk, void *userData) { GpencilModifierData *md = ob->greasepencil_modifiers.first; @@ -623,12 +525,6 @@ void BKE_gpencil_modifiers_foreach_ID_link(Object *ob, GreasePencilIDWalkFunc wa } } -/** - * Link grease pencil modifier related Texts. - * \param ob: Grease pencil object - * \param walk: Walk option - * \param userData: User data - */ void BKE_gpencil_modifiers_foreach_tex_link(Object *ob, GreasePencilTexWalkFunc walk, void *userData) @@ -644,12 +540,6 @@ void BKE_gpencil_modifiers_foreach_tex_link(Object *ob, } } -/** - * Find grease pencil modifier by name. - * \param ob: Grease pencil object - * \param name: Name to find - * \return Pointer to modifier - */ GpencilModifierData *BKE_gpencil_modifiers_findby_name(Object *ob, const char *name) { return BLI_findstring(&(ob->greasepencil_modifiers), name, offsetof(GpencilModifierData, name)); @@ -677,14 +567,6 @@ static int gpencil_remap_time_get(Depsgraph *depsgraph, Scene *scene, Object *ob return remap_cfra; } -/** - * Get the current frame re-timed with time modifiers. - * \param depsgraph: Current depsgraph. - * \param scene: Current scene - * \param ob: Grease pencil object - * \param gpl: Grease pencil layer - * \return New frame number - */ bGPDframe *BKE_gpencil_frame_retime_get(Depsgraph *depsgraph, Scene *scene, Object *ob, @@ -753,12 +635,6 @@ static bGPdata *gpencil_copy_for_eval(bGPdata *gpd) return result; } -/** - * Prepare grease pencil eval data for modifiers - * \param depsgraph: Current depsgraph - * \param scene: Current scene - * \param ob: Grease pencil object - */ void BKE_gpencil_prepare_eval_data(Depsgraph *depsgraph, Scene *scene, Object *ob) { bGPdata *gpd_eval = (bGPdata *)ob->data; @@ -808,12 +684,6 @@ void BKE_gpencil_prepare_eval_data(Depsgraph *depsgraph, Scene *scene, Object *o BKE_gpencil_update_orig_pointers(ob_orig, ob); } -/** - * Calculate gpencil modifiers. - * \param depsgraph: Current depsgraph - * \param scene: Current scene - * \param ob: Grease pencil object - */ void BKE_gpencil_modifiers_calc(Depsgraph *depsgraph, Scene *scene, Object *ob) { bGPdata *gpd = (bGPdata *)ob->data; diff --git a/source/blender/blenkernel/intern/hair.c b/source/blender/blenkernel/intern/hair.c index 4714c266d82..f2a5146422e 100644 --- a/source/blender/blenkernel/intern/hair.c +++ b/source/blender/blenkernel/intern/hair.c @@ -408,6 +408,7 @@ void BKE_hair_data_update(struct Depsgraph *depsgraph, struct Scene *scene, Obje } /* Draw Cache */ + void (*BKE_hair_batch_cache_dirty_tag_cb)(Hair *hair, int mode) = NULL; void (*BKE_hair_batch_cache_free_cb)(Hair *hair) = NULL; diff --git a/source/blender/blenkernel/intern/icons.cc b/source/blender/blenkernel/intern/icons.cc index b9ccbedfa81..7df8e0e1fc0 100644 --- a/source/blender/blenkernel/intern/icons.cc +++ b/source/blender/blenkernel/intern/icons.cc @@ -336,10 +336,6 @@ PreviewImage *BKE_previewimg_copy(const PreviewImage *prv) return prv_img; } -/** - * Duplicate preview image from \a id and clear icon_id, - * to be used by datablock copy functions. - */ void BKE_previewimg_id_copy(ID *new_id, const ID *old_id) { PreviewImage **old_prv_p = BKE_previewimg_id_get_p(old_id); @@ -460,9 +456,6 @@ PreviewImage *BKE_previewimg_cached_get(const char *name) return (PreviewImage *)BLI_ghash_lookup(gCachedPreviews, name); } -/** - * Generate an empty PreviewImage, if not yet existing. - */ PreviewImage *BKE_previewimg_cached_ensure(const char *name) { BLI_assert(BLI_thread_is_main()); @@ -480,10 +473,6 @@ PreviewImage *BKE_previewimg_cached_ensure(const char *name) return prv; } -/** - * Generate a PreviewImage from given file path, using thumbnails management, if not yet existing. - * Does not actually generate the preview, #BKE_previewimg_ensure() must be called for that. - */ PreviewImage *BKE_previewimg_cached_thumbnail_read(const char *name, const char *path, const int source, @@ -538,10 +527,6 @@ void BKE_previewimg_cached_release(const char *name) BKE_previewimg_deferred_release(prv); } -/** - * Handle deferred (lazy) loading/generation of preview image, if needed. - * For now, only used with file thumbnails. - */ void BKE_previewimg_ensure(PreviewImage *prv, const int size) { if ((prv->tag & PRV_TAG_DEFFERED) != 0) { @@ -592,10 +577,6 @@ void BKE_previewimg_ensure(PreviewImage *prv, const int size) } } -/** - * Create an #ImBuf holding a copy of the preview image buffer in \a prv. - * \note The returned image buffer has to be free'd (#IMB_freeImBuf()). - */ ImBuf *BKE_previewimg_to_imbuf(PreviewImage *prv, const int size) { const unsigned int w = prv->w[size]; @@ -796,9 +777,6 @@ int BKE_icon_gplayer_color_ensure(bGPDlayer *gpl) return icon_gplayer_color_ensure_create_icon(gpl); } -/** - * Return icon id of given preview, or create new icon if not found. - */ int BKE_icon_preview_ensure(ID *id, PreviewImage *preview) { if (!preview || G.background) { @@ -839,11 +817,6 @@ int BKE_icon_preview_ensure(ID *id, PreviewImage *preview) return preview->icon_id; } -/** - * Create an icon as owner or \a ibuf. The icon-ID is not stored in \a ibuf, it needs to be stored - * separately. - * \note Transforms ownership of \a ibuf to the newly created icon. - */ int BKE_icon_imbuf_create(ImBuf *ibuf) { int icon_id = get_next_free_id(); @@ -925,9 +898,6 @@ void BKE_icon_id_delete(struct ID *id) BLI_ghash_remove(gIcons, POINTER_FROM_INT(icon_id), nullptr, icon_free); } -/** - * Remove icon and free data. - */ bool BKE_icon_delete(const int icon_id) { if (icon_id == 0) { diff --git a/source/blender/blenkernel/intern/idprop.c b/source/blender/blenkernel/intern/idprop.c index f7411f541b7..c21f3dd0bcf 100644 --- a/source/blender/blenkernel/intern/idprop.c +++ b/source/blender/blenkernel/intern/idprop.c @@ -76,10 +76,6 @@ static size_t idp_size_table[] = { /* --------- property array type -------------*/ -/** - * \note as a start to move away from the stupid IDP_New function, this type - * has its own allocation function. - */ IDProperty *IDP_NewIDPArray(const char *name) { IDProperty *prop = MEM_callocN(sizeof(IDProperty), "IDProperty prop array"); @@ -127,7 +123,6 @@ static void IDP_FreeIDPArray(IDProperty *prop, const bool do_id_user) } } -/* shallow copies item */ void IDP_SetIndexArray(IDProperty *prop, int index, IDProperty *item) { BLI_assert(prop->type == IDP_IDPARRAY); @@ -229,7 +224,6 @@ static void idp_resize_group_array(IDProperty *prop, int newlen, void *newarr) } } -/* This function works for strings too! */ void IDP_ResizeArray(IDProperty *prop, int newlen) { const bool is_grow = newlen >= prop->len; @@ -357,13 +351,6 @@ static IDProperty *IDP_CopyArray(const IDProperty *prop, const int flag) /** \name String Functions (IDProperty String API) * \{ */ -/** - * - * \param st: The string to assign. - * \param name: The property name. - * \param maxlen: The size of the new string (including the \0 terminator). - * \return The new string property. - */ IDProperty *IDP_NewString(const char *st, const char *name, int maxlen) { IDProperty *prop = MEM_callocN(sizeof(IDProperty), "IDProperty string"); @@ -514,8 +501,6 @@ static IDProperty *IDP_CopyGroup(const IDProperty *prop, const int flag) return newp; } -/* use for syncing proxies. - * When values name and types match, copy the values, else ignore */ void IDP_SyncGroupValues(IDProperty *dest, const IDProperty *src) { BLI_assert(dest->type == IDP_GROUP); @@ -565,9 +550,6 @@ void IDP_SyncGroupTypes(IDProperty *dest, const IDProperty *src, const bool do_a } } -/** - * Replaces all properties with the same name in a destination group from a source group. - */ void IDP_ReplaceGroupInGroup(IDProperty *dest, const IDProperty *src) { BLI_assert(dest->type == IDP_GROUP); @@ -592,10 +574,6 @@ void IDP_ReplaceGroupInGroup(IDProperty *dest, const IDProperty *src) } } -/** - * Checks if a property with the same name as prop exists, and if so replaces it. - * Use this to preserve order! - */ void IDP_ReplaceInGroup_ex(IDProperty *group, IDProperty *prop, IDProperty *prop_exist) { BLI_assert(group->type == IDP_GROUP); @@ -618,10 +596,6 @@ void IDP_ReplaceInGroup(IDProperty *group, IDProperty *prop) IDP_ReplaceInGroup_ex(group, prop, prop_exist); } -/** - * If a property is missing in \a dest, add it. - * Do it recursively. - */ void IDP_MergeGroup_ex(IDProperty *dest, const IDProperty *src, const bool do_overwrite, @@ -663,25 +637,11 @@ void IDP_MergeGroup_ex(IDProperty *dest, } } -/** - * If a property is missing in \a dest, add it. - * Do it recursively. - */ void IDP_MergeGroup(IDProperty *dest, const IDProperty *src, const bool do_overwrite) { IDP_MergeGroup_ex(dest, src, do_overwrite, 0); } -/** - * This function has a sanity check to make sure ID properties with the same name don't - * get added to the group. - * - * The sanity check just means the property is not added to the group if another property - * exists with the same name; the client code using ID properties then needs to detect this - * (the function that adds new properties to groups, #IDP_AddToGroup, - * returns false if a property can't be added to the group, and true if it can) - * and free the property. - */ bool IDP_AddToGroup(IDProperty *group, IDProperty *prop) { BLI_assert(group->type == IDP_GROUP); @@ -695,10 +655,6 @@ bool IDP_AddToGroup(IDProperty *group, IDProperty *prop) return false; } -/** - * This is the same as IDP_AddToGroup, only you pass an item - * in the group list to be inserted after. - */ bool IDP_InsertToGroup(IDProperty *group, IDProperty *previous, IDProperty *pnew) { BLI_assert(group->type == IDP_GROUP); @@ -712,12 +668,6 @@ bool IDP_InsertToGroup(IDProperty *group, IDProperty *previous, IDProperty *pnew return false; } -/** - * \note this does not free the property!! - * - * To free the property, you have to do: - * IDP_FreeProperty(prop); - */ void IDP_RemoveFromGroup(IDProperty *group, IDProperty *prop) { BLI_assert(group->type == IDP_GROUP); @@ -727,9 +677,6 @@ void IDP_RemoveFromGroup(IDProperty *group, IDProperty *prop) BLI_remlink(&group->data.group, prop); } -/** - * Removes the property from the group and frees it. - */ void IDP_FreeFromGroup(IDProperty *group, IDProperty *prop) { IDP_RemoveFromGroup(group, prop); @@ -742,7 +689,6 @@ IDProperty *IDP_GetPropertyFromGroup(const IDProperty *prop, const char *name) return (IDProperty *)BLI_findstring(&prop->data.group, name, offsetof(IDProperty, name)); } -/** same as above but ensure type match */ IDProperty *IDP_GetPropertyTypeFromGroup(const IDProperty *prop, const char *name, const char type) { IDProperty *idprop = IDP_GetPropertyFromGroup(prop, name); @@ -768,10 +714,6 @@ static void IDP_FreeGroup(IDProperty *prop, const bool do_id_user) /** \name Main Functions (IDProperty Main API) * \{ */ -/** - * Return an int from an IDProperty with a compatible type. This should be avoided, but - * it's sometimes necessary, for example when legacy files have incorrect property types. - */ int IDP_coerce_to_int_or_zero(const IDProperty *prop) { switch (prop->type) { @@ -786,10 +728,6 @@ int IDP_coerce_to_int_or_zero(const IDProperty *prop) } } -/** - * Return a double from an IDProperty with a compatible type. This should be avoided, but - * it's sometimes necessary, for example when legacy files have incorrect property types. - */ double IDP_coerce_to_double_or_zero(const IDProperty *prop) { switch (prop->type) { @@ -804,10 +742,6 @@ double IDP_coerce_to_double_or_zero(const IDProperty *prop) } } -/** - * Return a float from an IDProperty with a compatible type. This should be avoided, but - * it's sometimes necessary, for example when legacy files have incorrect property types. - */ float IDP_coerce_to_float_or_zero(const IDProperty *prop) { switch (prop->type) { @@ -845,10 +779,6 @@ IDProperty *IDP_CopyProperty(const IDProperty *prop) return IDP_CopyProperty_ex(prop, 0); } -/** - * Copy content from source IDProperty into destination one, freeing destination property's content - * first. - */ void IDP_CopyPropertyContent(IDProperty *dst, IDProperty *src) { IDProperty *idprop_tmp = IDP_CopyProperty(src); @@ -858,11 +788,6 @@ void IDP_CopyPropertyContent(IDProperty *dst, IDProperty *src) IDP_FreeProperty(idprop_tmp); } -/** - * Get the Group property that contains the id properties for ID id. Set create_if_needed - * to create the Group property and attach it to id if it doesn't exist; otherwise - * the function will return NULL if there's no Group property attached to the ID. - */ IDProperty *IDP_GetProperties(ID *id, const bool create_if_needed) { if (id->properties) { @@ -880,8 +805,6 @@ IDProperty *IDP_GetProperties(ID *id, const bool create_if_needed) return id->properties; } -/** - * \param is_strict: When false treat missing items as a match */ bool IDP_EqualsProperties_ex(IDProperty *prop1, IDProperty *prop2, const bool is_strict) { if (prop1 == NULL && prop2 == NULL) { @@ -974,33 +897,6 @@ bool IDP_EqualsProperties(IDProperty *prop1, IDProperty *prop2) return IDP_EqualsProperties_ex(prop1, prop2, true); } -/** - * Allocate a new ID. - * - * This function takes three arguments: the ID property type, a union which defines - * its initial value, and a name. - * - * The union is simple to use; see the top of BKE_idprop.h for its definition. - * An example of using this function: - * - * \code{.c} - * IDPropertyTemplate val; - * IDProperty *group, *idgroup, *color; - * group = IDP_New(IDP_GROUP, val, "group1"); // groups don't need a template. - * - * val.array.len = 4 - * val.array.type = IDP_FLOAT; - * color = IDP_New(IDP_ARRAY, val, "color1"); - * - * idgroup = IDP_GetProperties(some_id, 1); - * IDP_AddToGroup(idgroup, color); - * IDP_AddToGroup(idgroup, group); - * \endcode - * - * Note that you MUST either attach the id property to an id property group with - * IDP_AddToGroup or MEM_freeN the property, doing anything else might result in - * a memory leak. - */ IDProperty *IDP_New(const char type, const IDPropertyTemplate *val, const char *name) { IDProperty *prop = NULL; @@ -1096,11 +992,6 @@ IDProperty *IDP_New(const char type, const IDPropertyTemplate *val, const char * return prop; } -/** - * Free allocated pointers in the UI data that isn't shared with the UI data in the #other - * argument. Useful for returning early on failure when updating UI data in place, or when - * replacing a subset of the UI data's allocated pointers. - */ void IDP_ui_data_free_unique_contents(IDPropertyUIData *ui_data, const eIDPropertyUIDataType type, const IDPropertyUIData *other) @@ -1175,10 +1066,6 @@ void IDP_ui_data_free(IDProperty *prop) prop->ui_data = NULL; } -/** - * \note This will free allocated data, all child properties of arrays and groups, and unlink IDs! - * But it does not free the actual IDProperty struct itself. - */ void IDP_FreePropertyContent_ex(IDProperty *prop, const bool do_id_user) { switch (prop->type) { @@ -1241,14 +1128,6 @@ void IDP_Reset(IDProperty *prop, const IDProperty *reference) } } -/** - * Loop through all ID properties in hierarchy of given \a id_property_root included. - * - * \note Container types (groups and arrays) are processed after applying the callback on them. - * - * \param type_filter: If not 0, only apply callback on properties of matching types, see - * IDP_TYPE_FILTER_ enum in DNA_ID.h. - */ void IDP_foreach_property(IDProperty *id_property_root, const int type_filter, IDPForeachPropertyCallback callback, diff --git a/source/blender/blenkernel/intern/idtype.c b/source/blender/blenkernel/intern/idtype.c index d9dc68b1a4f..e6fd6c14d42 100644 --- a/source/blender/blenkernel/intern/idtype.c +++ b/source/blender/blenkernel/intern/idtype.c @@ -158,13 +158,6 @@ static const IDTypeInfo *idtype_get_info_from_name(const char *idtype_name) /* Various helpers/wrappers around #IDTypeInfo structure. */ -/** - * Convert an \a idcode into a name. - * - * \param idcode: The code to convert. - * \return A static string representing the name of - * the code. - */ const char *BKE_idtype_idcode_to_name(const short idcode) { const IDTypeInfo *id_type = BKE_idtype_get_info_from_idcode(idcode); @@ -172,13 +165,6 @@ const char *BKE_idtype_idcode_to_name(const short idcode) return id_type != NULL ? id_type->name : NULL; } -/** - * Convert an \a idcode into a name (plural). - * - * \param idcode: The code to convert. - * \return A static string representing the name of - * the code. - */ const char *BKE_idtype_idcode_to_name_plural(const short idcode) { const IDTypeInfo *id_type = BKE_idtype_get_info_from_idcode(idcode); @@ -186,12 +172,6 @@ const char *BKE_idtype_idcode_to_name_plural(const short idcode) return id_type != NULL ? id_type->name_plural : NULL; } -/** - * Convert an \a idcode into its translations' context. - * - * \param idcode: The code to convert. - * \return A static string representing the i18n context of the code. - */ const char *BKE_idtype_idcode_to_translation_context(const short idcode) { const IDTypeInfo *id_type = BKE_idtype_get_info_from_idcode(idcode); @@ -199,12 +179,6 @@ const char *BKE_idtype_idcode_to_translation_context(const short idcode) return id_type != NULL ? id_type->translation_context : BLT_I18NCONTEXT_DEFAULT; } -/** - * Convert an ID-type name into an \a idcode (ie. #ID_SCE) - * - * \param idtype_name: The ID-type's "user visible name" to convert. - * \return The \a idcode for the name, or 0 if invalid. - */ short BKE_idtype_idcode_from_name(const char *idtype_name) { const IDTypeInfo *id_type = idtype_get_info_from_name(idtype_name); @@ -212,23 +186,11 @@ short BKE_idtype_idcode_from_name(const char *idtype_name) return id_type != NULL ? id_type->id_code : 0; } -/** - * Return if the ID code is a valid ID code. - * - * \param idcode: The code to check. - * \return Boolean, 0 when invalid. - */ bool BKE_idtype_idcode_is_valid(const short idcode) { return BKE_idtype_get_info_from_idcode(idcode) != NULL ? true : false; } -/** - * Check if an ID type is linkable. - * - * \param idcode: The IDType code to check. - * \return Boolean, false when non linkable, true otherwise. - */ bool BKE_idtype_idcode_is_linkable(const short idcode) { const IDTypeInfo *id_type = BKE_idtype_get_info_from_idcode(idcode); @@ -236,12 +198,6 @@ bool BKE_idtype_idcode_is_linkable(const short idcode) return id_type != NULL ? (id_type->flags & IDTYPE_FLAGS_NO_LIBLINKING) == 0 : false; } -/** - * Check if an ID type is only appendable. - * - * \param idcode: The IDType code to check. - * \return Boolean, false when also linkable, true when only appendable. - */ bool BKE_idtype_idcode_is_only_appendable(const short idcode) { const IDTypeInfo *id_type = BKE_idtype_get_info_from_idcode(idcode); @@ -254,12 +210,6 @@ bool BKE_idtype_idcode_is_only_appendable(const short idcode) return false; } -/** - * Check if an ID type can try to reuse and existing matching local one when being appended again. - * - * \param idcode: The IDType code to check. - * \return Boolean, false when it cannot be re-used, true otherwise. - */ bool BKE_idtype_idcode_append_is_reusable(const short idcode) { const IDTypeInfo *id_type = BKE_idtype_get_info_from_idcode(idcode); @@ -272,9 +222,6 @@ bool BKE_idtype_idcode_append_is_reusable(const short idcode) return false; } -/** - * Convert an \a idcode into an \a idfilter (e.g. ID_OB -> FILTER_ID_OB). - */ uint64_t BKE_idtype_idcode_to_idfilter(const short idcode) { #define CASE_IDFILTER(_id) \ @@ -324,9 +271,6 @@ uint64_t BKE_idtype_idcode_to_idfilter(const short idcode) #undef CASE_IDFILTER } -/** - * Convert an \a idfilter into an \a idcode (e.g. #FILTER_ID_OB -> #ID_OB). - */ short BKE_idtype_idcode_from_idfilter(const uint64_t idfilter) { #define CASE_IDFILTER(_id) \ @@ -375,9 +319,6 @@ short BKE_idtype_idcode_from_idfilter(const uint64_t idfilter) #undef CASE_IDFILTER } -/** - * Convert an \a idcode into an index (e.g. #ID_OB -> #INDEX_ID_OB). - */ int BKE_idtype_idcode_to_index(const short idcode) { #define CASE_IDINDEX(_id) \ @@ -437,9 +378,6 @@ int BKE_idtype_idcode_to_index(const short idcode) #undef CASE_IDINDEX } -/** - * Get an \a idcode from an index (e.g. #INDEX_ID_OB -> #ID_OB). - */ short BKE_idtype_idcode_from_index(const int index) { #define CASE_IDCODE(_id) \ @@ -499,20 +437,11 @@ short BKE_idtype_idcode_from_index(const int index) #undef CASE_IDCODE } -/** - * Return an ID code and steps the index forward 1. - * - * \param index: start as 0. - * \return the code, 0 when all codes have been returned. - */ short BKE_idtype_idcode_iter_step(int *index) { return (*index < ARRAY_SIZE(id_types)) ? BKE_idtype_idcode_from_index((*index)++) : 0; } -/** - * Wrapper around #IDTypeInfo foreach_cache that also handles embedded IDs. - */ void BKE_idtype_id_foreach_cache(struct ID *id, IDTypeForeachCacheFunctionCallback function_callback, void *user_data) diff --git a/source/blender/blenkernel/intern/image.c b/source/blender/blenkernel/intern/image.c index 6fe415aedab..1c31e1be8bb 100644 --- a/source/blender/blenkernel/intern/image.c +++ b/source/blender/blenkernel/intern/image.c @@ -549,10 +549,6 @@ static void image_free_anims(Image *ima) } } -/** - * Simply free the image data from memory, - * on display the image can load again (except for render buffers). - */ void BKE_image_free_buffers_ex(Image *ima, bool do_lock) { if (do_lock) { @@ -579,7 +575,6 @@ void BKE_image_free_buffers(Image *ima) BKE_image_free_buffers_ex(ima, false); } -/** Free (or release) any data used by this image (does not free the image itself). */ void BKE_image_free_data(Image *ima) { image_free_data(&ima->id); @@ -706,9 +701,11 @@ void BKE_image_merge(Main *bmain, Image *dest, Image *source) } } -/* NOTE: We could be clever and scale all imbuf's but since some are mipmaps its not so simple. */ bool BKE_image_scale(Image *image, int width, int height) { + /* NOTE: We could be clever and scale all imbuf's + * but since some are mipmaps its not so simple. */ + ImBuf *ibuf; void *lock; @@ -807,9 +804,6 @@ int BKE_image_get_tile_from_pos(struct Image *ima, return tile_number; } -/** - * Return the tile_number for the closest UDIM tile. - */ int BKE_image_find_nearest_tile(const Image *image, const float co[2]) { const float co_floor[2] = {floorf(co[0]), floorf(co[1])}; @@ -908,10 +902,6 @@ Image *BKE_image_load(Main *bmain, const char *filepath) return ima; } -/* checks if image was already loaded, then returns same image */ -/* otherwise creates new. */ -/* does not load ibuf itself */ -/* pass on optional frame for #name images */ Image *BKE_image_load_exists_ex(Main *bmain, const char *filepath, bool *r_exists) { Image *ima; @@ -1058,7 +1048,6 @@ static ImBuf *add_ibuf_size(unsigned int width, return ibuf; } -/* adds new image block, creates ImBuf and initializes color */ Image *BKE_image_add_generated(Main *bmain, unsigned int width, unsigned int height, @@ -1119,11 +1108,6 @@ Image *BKE_image_add_generated(Main *bmain, return ima; } -/** - * Create an image from ibuf. The refcount of ibuf is increased, - * caller should take care to drop its reference by calling - * #IMB_freeImBuf if needed. - */ Image *BKE_image_add_from_imbuf(Main *bmain, ImBuf *ibuf, const char *name) { /* on save, type is changed to FILE in editsima.c */ @@ -1175,7 +1159,6 @@ static bool image_memorypack_imbuf(Image *ima, ImBuf *ibuf, const char *filepath return true; } -/* Pack image to memory. */ bool BKE_image_memorypack(Image *ima) { bool ok = true; @@ -1408,7 +1391,6 @@ static bool imagecache_check_free_anim(ImBuf *ibuf, void *UNUSED(userkey), void (except_frame != IMA_INDEX_ENTRY(ibuf->index)); } -/* except_frame is weak, only works for seqs without offset... */ void BKE_image_free_anim_ibufs(Image *ima, int except_frame) { BLI_mutex_lock(ima->runtime.cache_mutex); @@ -1670,8 +1652,6 @@ char BKE_imtype_valid_depths(const char imtype) } } -/* string is from command line --render-format arg, keep in sync with - * creator_args.c help info */ char BKE_imtype_from_arg(const char *imtype_arg) { if (STREQ(imtype_arg, "TGA")) { @@ -2775,8 +2755,6 @@ static const char *stamp_metadata_fields[] = { NULL, }; -/* Check whether the given metadata field name translates to a known field of - * a stamp. */ bool BKE_stamp_is_known_field(const char *field_name) { int i = 0; @@ -2938,8 +2916,6 @@ bool BKE_imbuf_alpha_test(ImBuf *ibuf) return false; } -/* NOTE: imf->planes is ignored here, its assumed the image channels - * are already set */ void BKE_imbuf_write_prepare(ImBuf *ibuf, const ImageFormatData *imf) { char imtype = imf->imtype; @@ -3116,8 +3092,6 @@ int BKE_imbuf_write(ImBuf *ibuf, const char *name, const ImageFormatData *imf) return ok; } -/* same as BKE_imbuf_write() but crappy workaround not to permanently modify - * _some_, values in the imbuf */ int BKE_imbuf_write_as(ImBuf *ibuf, const char *name, ImageFormatData *imf, const bool save_copy) { ImBuf ibuf_back = *ibuf; @@ -3216,7 +3190,6 @@ struct anim *openanim_noload(const char *name, return anim; } -/* used by sequencer too */ struct anim *openanim(const char *name, int flags, int streamindex, char colorspace[IMA_MAX_SPACE]) { struct anim *anim; @@ -3262,8 +3235,6 @@ struct anim *openanim(const char *name, int flags, int streamindex, char colorsp * -> comes from packedfile or filename or generated */ -/* forces existence of 1 Image for renderout or nodes, returns Image */ -/* name is only for default, when making new one */ Image *BKE_image_ensure_viewer(Main *bmain, int type, const char *name) { Image *ima; @@ -3304,7 +3275,6 @@ static void image_viewer_create_views(const RenderData *rd, Image *ima) } } -/* Reset the image cache and views when the Viewer Nodes views don't match the scene views */ void BKE_image_ensure_viewer_views(const RenderData *rd, Image *ima, ImageUser *iuser) { bool do_reset; @@ -3959,7 +3929,6 @@ bool BKE_image_fill_tile(struct Image *ima, /* if layer or pass changes, we need an index for the imbufs list */ /* note it is called for rendered results, but it doesn't use the index! */ -/* and because rendered results use fake layer/passes, don't correct for wrong indices here */ RenderPass *BKE_image_multilayer_index(RenderResult *rr, ImageUser *iuser) { RenderLayer *rl; @@ -4014,7 +3983,6 @@ void BKE_image_multiview_index(Image *ima, ImageUser *iuser) /* if layer or pass changes, we need an index for the imbufs list */ /* note it is called for rendered results, but it doesn't use the index! */ -/* and because rendered results use fake layer/passes, don't correct for wrong indices here */ bool BKE_image_is_multilayer(Image *ima) { if (ELEM(ima->source, IMA_SRC_FILE, IMA_SRC_SEQUENCE, IMA_SRC_TILED)) { @@ -5046,9 +5014,10 @@ BLI_INLINE bool image_quick_test(Image *ima, const ImageUser *iuser) return true; } -/* Checks optional ImageUser and verifies/creates ImBuf. +/** + * Checks optional #ImageUser and verifies/creates #ImBuf. * - * not thread-safe, so callee should worry about thread locks + * \warning Not thread-safe, so callee should worry about thread locks. */ static ImBuf *image_acquire_ibuf(Image *ima, ImageUser *iuser, void **r_lock) { @@ -5169,15 +5138,11 @@ static ImBuf *image_acquire_ibuf(Image *ima, ImageUser *iuser, void **r_lock) return ibuf; } -/* return image buffer for given image and user - * - * - will lock render result if image type is render result and lock is not NULL - * - will return NULL if image is NULL or image type is render or composite result and lock is NULL - * - * references the result, BKE_image_release_ibuf should be used to de-reference - */ ImBuf *BKE_image_acquire_ibuf(Image *ima, ImageUser *iuser, void **r_lock) { + /* NOTE: same as #image_acquire_ibuf, but can be used to retrieve images being rendered in + * a thread safe way, always call both acquire and release. */ + if (ima == NULL) { return NULL; } @@ -5213,7 +5178,6 @@ void BKE_image_release_ibuf(Image *ima, ImBuf *ibuf, void *lock) } } -/* checks whether there's an image buffer for given image and user */ bool BKE_image_has_ibuf(Image *ima, ImageUser *iuser) { ImBuf *ibuf; @@ -5721,19 +5685,16 @@ bool BKE_image_has_filepath(Image *ima) return ima->filepath[0] != '\0'; } -/* Checks the image buffer changes with time (not keyframed values). */ bool BKE_image_is_animated(Image *image) { return ELEM(image->source, IMA_SRC_MOVIE, IMA_SRC_SEQUENCE); } -/* Checks whether the image consists of multiple buffers. */ bool BKE_image_has_multiple_ibufs(Image *image) { return ELEM(image->source, IMA_SRC_MOVIE, IMA_SRC_SEQUENCE, IMA_SRC_TILED); } -/* Image modifications */ bool BKE_image_is_dirty_writable(Image *image, bool *r_is_writable) { bool is_dirty = false; @@ -5819,10 +5780,6 @@ bool BKE_image_has_loaded_ibuf(Image *image) return has_loaded_ibuf; } -/** - * References the result, #BKE_image_release_ibuf is to be called to de-reference. - * Use lock=NULL when calling #BKE_image_release_ibuf(). - */ ImBuf *BKE_image_get_ibuf_with_name(Image *image, const char *name) { ImBuf *ibuf = NULL; @@ -5847,15 +5804,6 @@ ImBuf *BKE_image_get_ibuf_with_name(Image *image, const char *name) return ibuf; } -/** - * References the result, #BKE_image_release_ibuf is to be called to de-reference. - * Use lock=NULL when calling #BKE_image_release_ibuf(). - * - * TODO(sergey): This is actually "get first item from the cache", which is - * not so much predictable. But using first loaded image buffer - * was also malicious logic and all the areas which uses this - * function are to be re-considered. - */ ImBuf *BKE_image_get_first_ibuf(Image *image) { ImBuf *ibuf = NULL; diff --git a/source/blender/blenkernel/intern/image_gpu.cc b/source/blender/blenkernel/intern/image_gpu.cc index fa2c17826d5..8b1441f812c 100644 --- a/source/blender/blenkernel/intern/image_gpu.cc +++ b/source/blender/blenkernel/intern/image_gpu.cc @@ -61,7 +61,6 @@ struct ImagePartialRefresh { int tile_y; }; -/* Is the alpha of the `GPUTexture` for a given image/ibuf premultiplied. */ bool BKE_image_has_gpu_texture_premultiplied_alpha(Image *image, ImBuf *ibuf) { if (image) { @@ -598,7 +597,6 @@ void BKE_image_free_all_gputextures(Main *bmain) } } -/* same as above but only free animated images */ void BKE_image_free_anim_gputextures(Main *bmain) { if (bmain) { @@ -901,8 +899,6 @@ static void image_update_gputexture_ex( } } -/* Partial update of texture for texture painting. This is often much - * quicker than fully updating the texture for high resolution images. */ void BKE_image_update_gputexture(Image *ima, ImageUser *iuser, int x, int y, int w, int h) { ImBuf *ibuf = BKE_image_acquire_ibuf(ima, iuser, nullptr); @@ -916,10 +912,6 @@ void BKE_image_update_gputexture(Image *ima, ImageUser *iuser, int x, int y, int BKE_image_release_ibuf(ima, ibuf, nullptr); } -/* Mark areas on the GPUTexture that needs to be updated. The areas are marked in chunks. - * The next time the GPUTexture is used these tiles will be refreshes. This saves time - * when writing to the same place multiple times This happens for during foreground - * rendering. */ void BKE_image_update_gputexture_delayed( struct Image *ima, struct ImBuf *ibuf, int x, int y, int w, int h) { @@ -993,10 +985,6 @@ void BKE_image_update_gputexture_delayed( } } -/* these two functions are called on entering and exiting texture paint mode, - * temporary disabling/enabling mipmapping on all images for quick texture - * updates with glTexSubImage2D. images that didn't change don't have to be - * re-uploaded to OpenGL */ void BKE_image_paint_set_mipmap(Main *bmain, bool mipmap) { LISTBASE_FOREACH (Image *, ima, &bmain->images) { diff --git a/source/blender/blenkernel/intern/ipo.c b/source/blender/blenkernel/intern/ipo.c index d2e053f58e8..d87331fd65c 100644 --- a/source/blender/blenkernel/intern/ipo.c +++ b/source/blender/blenkernel/intern/ipo.c @@ -2095,17 +2095,6 @@ static bool seq_convert_callback(Sequence *seq, void *userdata) /* *************************************************** */ /* External API - Only Called from do_versions() */ -/* Called from do_versions() in readfile.c to convert the old 'IPO/adrcode' system - * to the new 'Animato/RNA' system. - * - * The basic method used here, is to loop over data-blocks which have IPO-data, - * and add those IPO's to new AnimData blocks as Actions. - * Action/NLA data only works well for Objects, so these only need to be checked for there. - * - * Data that has been converted should be freed immediately, which means that it is immediately - * clear which data-blocks have yet to be converted, and also prevent freeing errors when we exit. - */ -/* XXX currently done after all file reading... */ void do_versions_ipos_to_animato(Main *bmain) { ListBase drivers = {NULL, NULL}; diff --git a/source/blender/blenkernel/intern/key.c b/source/blender/blenkernel/intern/key.c index eedd02b2271..ff199794ab3 100644 --- a/source/blender/blenkernel/intern/key.c +++ b/source/blender/blenkernel/intern/key.c @@ -246,7 +246,6 @@ typedef struct WeightsArrayCache { float **defgroup_weights; } WeightsArrayCache; -/** Free (or release) any data used by this shapekey (does not free the key itself). */ void BKE_key_free_data(Key *key) { shapekey_free_data(&key->id); @@ -316,11 +315,6 @@ Key *BKE_key_add(Main *bmain, ID *id) /* common function */ return key; } -/** - * Sort shape keys after a change. - * This assumes that at most one key was moved, - * which is a valid assumption for the places it's currently being called. - */ void BKE_key_sort(Key *key) { KeyBlock *kb; @@ -394,7 +388,6 @@ void key_curve_position_weights(float t, float data[4], int type) } } -/* first derivative */ void key_curve_tangent_weights(float t, float data[4], int type) { float t2, fc; @@ -433,7 +426,6 @@ void key_curve_tangent_weights(float t, float data[4], int type) } } -/* second derivative */ void key_curve_normal_weights(float t, float data[4], int type) { float fc; @@ -1524,7 +1516,6 @@ static void do_latt_key(Object *ob, Key *key, char *out, const int tot) } } -/* returns key coordinates (+ tilt) when key applied, NULL otherwise */ float *BKE_key_evaluate_object_ex(Object *ob, int *r_totelem, float *arr, size_t arr_size) { Key *key = BKE_key_from_object(ob); @@ -1626,9 +1617,6 @@ float *BKE_key_evaluate_object(Object *ob, int *r_totelem) return BKE_key_evaluate_object_ex(ob, r_totelem, NULL, 0); } -/** - * \param shape_index: The index to use or all (when -1). - */ int BKE_keyblock_element_count_from_shape(const Key *key, const int shape_index) { int result = 0; @@ -1646,9 +1634,6 @@ int BKE_keyblock_element_count(const Key *key) return BKE_keyblock_element_count_from_shape(key, -1); } -/** - * \param shape_index: The index to use or all (when -1). - */ size_t BKE_keyblock_element_calc_size_from_shape(const Key *key, const int shape_index) { return (size_t)BKE_keyblock_element_count_from_shape(key, shape_index) * key->elemsize; @@ -1666,9 +1651,6 @@ size_t BKE_keyblock_element_calc_size(const Key *key) * use #BKE_keyblock_element_calc_size to allocate the size of the data needed. * \{ */ -/** - * \param shape_index: The index to use or all (when -1). - */ void BKE_keyblock_data_get_from_shape(const Key *key, float (*arr)[3], const int shape_index) { uint8_t *elements = (uint8_t *)arr; @@ -1687,9 +1669,6 @@ void BKE_keyblock_data_get(const Key *key, float (*arr)[3]) BKE_keyblock_data_get_from_shape(key, arr, -1); } -/** - * Set the data to all key-blocks (or shape_index if != -1). - */ void BKE_keyblock_data_set_with_mat4(Key *key, const int shape_index, const float (*coords)[3], @@ -1717,10 +1696,6 @@ void BKE_keyblock_data_set_with_mat4(Key *key, } } -/** - * Set the data for all key-blocks (or shape_index if != -1), - * transforming by \a mat. - */ void BKE_keyblock_curve_data_set_with_mat4( Key *key, const ListBase *nurb, const int shape_index, const void *data, const float mat[4][4]) { @@ -1736,9 +1711,6 @@ void BKE_keyblock_curve_data_set_with_mat4( } } -/** - * Set the data for all key-blocks (or shape_index if != -1). - */ void BKE_keyblock_data_set(Key *key, const int shape_index, const void *data) { const uint8_t *elements = data; @@ -1870,14 +1842,6 @@ KeyBlock *BKE_keyblock_add(Key *key, const char *name) return kb; } -/** - * \note sorting is a problematic side effect in some cases, - * better only do this explicitly by having its own function, - * - * \param key: The key datablock to add to. - * \param name: Optional name for the new keyblock. - * \param do_force: always use ctime even for relative keys. - */ KeyBlock *BKE_keyblock_add_ctime(Key *key, const char *name, const bool do_force) { KeyBlock *kb = BKE_keyblock_add(key, name); @@ -1906,7 +1870,6 @@ KeyBlock *BKE_keyblock_add_ctime(Key *key, const char *name, const bool do_force return kb; } -/* Only the active key-block. */ KeyBlock *BKE_keyblock_from_object(Object *ob) { Key *key = BKE_key_from_object(ob); @@ -1930,7 +1893,6 @@ KeyBlock *BKE_keyblock_from_object_reference(Object *ob) return NULL; } -/* get the appropriate KeyBlock given an index */ KeyBlock *BKE_keyblock_from_key(Key *key, int index) { if (key) { @@ -1948,15 +1910,11 @@ KeyBlock *BKE_keyblock_from_key(Key *key, int index) return NULL; } -/* get the appropriate KeyBlock given a name to search for */ KeyBlock *BKE_keyblock_find_name(Key *key, const char name[]) { return BLI_findstring(&key->block, name, offsetof(KeyBlock, name)); } -/** - * \brief copy shape-key attributes, but not key data.or name/uid - */ void BKE_keyblock_copy_settings(KeyBlock *kb_dst, const KeyBlock *kb_src) { kb_dst->pos = kb_src->pos; @@ -1968,9 +1926,6 @@ void BKE_keyblock_copy_settings(KeyBlock *kb_dst, const KeyBlock *kb_src) kb_dst->slidermax = kb_src->slidermax; } -/* Get RNA-Path for 'value' setting of the given ShapeKey - * NOTE: the user needs to free the returned string once they're finish with it - */ char *BKE_keyblock_curval_rnapath_get(Key *key, KeyBlock *kb) { PointerRNA ptr; @@ -1993,6 +1948,7 @@ char *BKE_keyblock_curval_rnapath_get(Key *key, KeyBlock *kb) /* conversion functions */ /************************* Lattice ************************/ + void BKE_keyblock_update_from_lattice(Lattice *lt, KeyBlock *kb) { BPoint *bp; @@ -2193,6 +2149,7 @@ void BKE_keyblock_convert_to_curve(KeyBlock *kb, Curve *UNUSED(cu), ListBase *nu } /************************* Mesh ************************/ + void BKE_keyblock_update_from_mesh(Mesh *me, KeyBlock *kb) { MVert *mvert; @@ -2245,15 +2202,6 @@ void BKE_keyblock_convert_to_mesh(KeyBlock *kb, Mesh *me) } } -/** - * Computes normals (vertices, polygons and/or loops ones) of given mesh for given shape key. - * - * \param kb: the KeyBlock to use to compute normals. - * \param mesh: the Mesh to apply key-block to. - * \param r_vertnors: if non-NULL, an array of vectors, same length as number of vertices. - * \param r_polynors: if non-NULL, an array of vectors, same length as number of polygons. - * \param r_loopnors: if non-NULL, an array of vectors, same length as number of loops. - */ void BKE_keyblock_mesh_calc_normals(struct KeyBlock *kb, struct Mesh *mesh, float (*r_vertnors)[3], @@ -2318,6 +2266,7 @@ void BKE_keyblock_mesh_calc_normals(struct KeyBlock *kb, } /************************* raw coords ************************/ + void BKE_keyblock_update_from_vertcos(Object *ob, KeyBlock *kb, const float (*vertCos)[3]) { const float(*co)[3] = vertCos; @@ -2471,6 +2420,7 @@ float (*BKE_keyblock_convert_to_vertcos(Object *ob, KeyBlock *kb))[3] } /************************* raw coord offsets ************************/ + void BKE_keyblock_update_from_offset(Object *ob, KeyBlock *kb, const float (*ofs)[3]) { int a; @@ -2508,15 +2458,6 @@ void BKE_keyblock_update_from_offset(Object *ob, KeyBlock *kb, const float (*ofs /* ==========================================================*/ -/** - * Move shape key from org_index to new_index. Safe, clamps index to valid range, - * updates reference keys, the object's active shape index, - * the 'frame' value in case of absolute keys, etc. - * Note indices are expected in real values (not 'fake' shapenr +1 ones). - * - * \param org_index: if < 0, current object's active shape will be used as skey to move. - * \return true if something was done, else false. - */ bool BKE_keyblock_move(Object *ob, int org_index, int new_index) { Key *key = BKE_key_from_object(ob); @@ -2595,9 +2536,6 @@ bool BKE_keyblock_move(Object *ob, int org_index, int new_index) return true; } -/** - * Check if given key-block (as index) is used as basis by others in given key. - */ bool BKE_keyblock_is_basis(Key *key, const int index) { KeyBlock *kb; diff --git a/source/blender/blenkernel/intern/keyconfig.c b/source/blender/blenkernel/intern/keyconfig.c index d25f475c140..84e11c1166e 100644 --- a/source/blender/blenkernel/intern/keyconfig.c +++ b/source/blender/blenkernel/intern/keyconfig.c @@ -121,7 +121,6 @@ void BKE_keyconfig_pref_type_free(void) /** \name Key-Config Versioning * \{ */ -/* Set select mouse, for versioning code. */ void BKE_keyconfig_pref_set_select_mouse(UserDef *userdef, int value, bool override) { wmKeyConfigPref *kpt = BKE_keyconfig_pref_ensure(userdef, WM_KEYCONFIG_STR_DEFAULT); @@ -201,10 +200,6 @@ void BKE_keyconfig_keymap_filter_item(wmKeyMap *keymap, } } -/** - * Filter & optionally remove key-map items, - * intended for versioning, but may be used in other situations too. - */ void BKE_keyconfig_pref_filter_items(struct UserDef *userdef, const struct wmKeyConfigFilterItemParams *params, bool (*filter_fn)(wmKeyMapItem *kmi, void *user_data), diff --git a/source/blender/blenkernel/intern/layer.c b/source/blender/blenkernel/intern/layer.c index 6aa8e78c4f6..5a9e9f1c2ff 100644 --- a/source/blender/blenkernel/intern/layer.c +++ b/source/blender/blenkernel/intern/layer.c @@ -117,8 +117,6 @@ static Base *object_base_new(Object *ob) /* RenderLayer */ -/* Returns the default view layer to view in workspaces if there is - * none linked to the workspace yet. */ ViewLayer *BKE_view_layer_default_view(const Scene *scene) { LISTBASE_FOREACH (ViewLayer *, view_layer, &scene->view_layers) { @@ -131,7 +129,6 @@ ViewLayer *BKE_view_layer_default_view(const Scene *scene) return scene->view_layers.first; } -/* Returns the default view layer to render if we need to render just one. */ ViewLayer *BKE_view_layer_default_render(const Scene *scene) { LISTBASE_FOREACH (ViewLayer *, view_layer, &scene->view_layers) { @@ -144,7 +141,6 @@ ViewLayer *BKE_view_layer_default_render(const Scene *scene) return scene->view_layers.first; } -/* Returns view layer with matching name, or NULL if not found. */ ViewLayer *BKE_view_layer_find(const Scene *scene, const char *layer_name) { LISTBASE_FOREACH (ViewLayer *, view_layer, &scene->view_layers) { @@ -156,11 +152,6 @@ ViewLayer *BKE_view_layer_find(const Scene *scene, const char *layer_name) return NULL; } -/** - * This is a placeholder to know which areas of the code need to be addressed - * for the Workspace changes. Never use this, you should typically get the - * active layer from the context or window. - */ ViewLayer *BKE_view_layer_context_active_PLACEHOLDER(const Scene *scene) { BLI_assert(scene->view_layers.first); @@ -198,10 +189,6 @@ static void layer_collection_exclude_all(LayerCollection *layer_collection) } } -/** - * Add a new view layer - * by default, a view layer has the master collection - */ ViewLayer *BKE_view_layer_add(Scene *scene, const char *name, ViewLayer *view_layer_source, @@ -261,9 +248,6 @@ void BKE_view_layer_free(ViewLayer *view_layer) BKE_view_layer_free_ex(view_layer, true); } -/** - * Free (or release) any data used by this ViewLayer. - */ void BKE_view_layer_free_ex(ViewLayer *view_layer, const bool do_id_user) { view_layer->basact = NULL; @@ -304,9 +288,6 @@ void BKE_view_layer_free_ex(ViewLayer *view_layer, const bool do_id_user) MEM_freeN(view_layer); } -/** - * Tag all the selected objects of a render-layer. - */ void BKE_view_layer_selected_objects_tag(ViewLayer *view_layer, const int tag) { LISTBASE_FOREACH (Base *, base, &view_layer->object_bases) { @@ -332,13 +313,6 @@ static bool find_scene_collection_in_scene_collections(ListBase *lb, const Layer return false; } -/** - * Fallback for when a Scene has no camera to use - * - * \param view_layer: in general you want to use the same ViewLayer that is used - * for depsgraph. If rendering you pass the scene active layer, when viewing in the viewport - * you want to get ViewLayer from context. - */ Object *BKE_view_layer_camera_find(ViewLayer *view_layer) { LISTBASE_FOREACH (Base *, base, &view_layer->object_bases) { @@ -350,9 +324,6 @@ Object *BKE_view_layer_camera_find(ViewLayer *view_layer) return NULL; } -/** - * Find the ViewLayer a LayerCollection belongs to - */ ViewLayer *BKE_view_layer_find_from_collection(const Scene *scene, LayerCollection *lc) { LISTBASE_FOREACH (ViewLayer *, view_layer, &scene->view_layers) { @@ -471,11 +442,6 @@ static void layer_collections_copy_data(ViewLayer *view_layer_dst, } } -/** - * Only copy internal data of ViewLayer from source to already allocated/initialized destination. - * - * \param flag: Copying options (see BKE_lib_id.h's LIB_ID_COPY_... flags for more). - */ void BKE_view_layer_copy_data(Scene *scene_dst, const Scene *UNUSED(scene_src), ViewLayer *view_layer_dst, @@ -620,26 +586,17 @@ static bool layer_collection_hidden(ViewLayer *view_layer, LayerCollection *lc) return false; } -/** - * Get the collection for a given index - */ LayerCollection *BKE_layer_collection_from_index(ViewLayer *view_layer, const int index) { int i = 0; return collection_from_index(&view_layer->layer_collections, index, &i); } -/** - * Get the active collection - */ LayerCollection *BKE_layer_collection_get_active(ViewLayer *view_layer) { return view_layer->active_collection; } -/* - * Activate collection - */ bool BKE_layer_collection_activate(ViewLayer *view_layer, LayerCollection *lc) { if (lc->flag & LAYER_COLLECTION_EXCLUDE) { @@ -650,9 +607,6 @@ bool BKE_layer_collection_activate(ViewLayer *view_layer, LayerCollection *lc) return true; } -/** - * Activate first parent collection - */ LayerCollection *BKE_layer_collection_activate_parent(ViewLayer *view_layer, LayerCollection *lc) { CollectionParent *parent = lc->collection->parents.first; @@ -690,10 +644,6 @@ static int collection_count(const ListBase *lb) return i; } -/** - * Get the total number of collections - * (including all the nested collections) - */ int BKE_layer_collection_count(const ViewLayer *view_layer) { return collection_count(&view_layer->layer_collections); @@ -721,9 +671,6 @@ static int index_from_collection(ListBase *lb, const LayerCollection *lc, int *i return -1; } -/** - * Return -1 if not found - */ int BKE_layer_collection_findindex(ViewLayer *view_layer, const LayerCollection *lc) { int i = 0; @@ -1220,11 +1167,6 @@ static bool view_layer_objects_base_cache_validate(ViewLayer *UNUSED(view_layer) } #endif -/** - * Update view layer collection tree from collections used in the scene. - * This is used when collections are removed or added, both while editing - * and on file loaded in case linked data changed or went missing. - */ void BKE_layer_collection_sync(const Scene *scene, ViewLayer *view_layer) { if (no_resync) { @@ -1379,12 +1321,6 @@ void BKE_main_collection_sync_remap(const Main *bmain) /* ---------------------------------------------------------------------- */ -/** - * Select all the objects of this layer collection - * - * It also select the objects that are in nested collections. - * \note Recursive - */ bool BKE_layer_collection_objects_select(ViewLayer *view_layer, LayerCollection *lc, bool deselect) { if (lc->collection->flag & COLLECTION_HIDE_SELECT) { @@ -1463,7 +1399,6 @@ bool BKE_layer_collection_has_layer_collection(LayerCollection *lc_parent, /* ---------------------------------------------------------------------- */ -/* Update after toggling visibility of an object base. */ void BKE_base_set_visible(Scene *scene, ViewLayer *view_layer, Base *base, bool extend) { if (!extend) { @@ -1552,14 +1487,6 @@ static void layer_collection_flag_unset_recursive(LayerCollection *lc, const int } } -/** - * Isolate the collection - hide all other collections but this one. - * Make sure to show all the direct parents and all children of the layer collection as well. - * When extending we simply show the collections and its direct family. - * - * If the collection or any of its parents is disabled, make it enabled. - * Don't change the children disable state though. - */ void BKE_layer_collection_isolate_global(Scene *scene, ViewLayer *view_layer, LayerCollection *lc, @@ -1668,9 +1595,6 @@ void BKE_layer_collection_local_sync(ViewLayer *view_layer, const View3D *v3d) } } -/** - * Sync the local collection for all the 3D Viewports. - */ void BKE_layer_collection_local_sync_all(const Main *bmain) { if (no_resync) { @@ -1694,11 +1618,6 @@ void BKE_layer_collection_local_sync_all(const Main *bmain) } } -/** - * Isolate the collection locally - * - * Same as BKE_layer_collection_isolate_local but for a viewport - */ void BKE_layer_collection_isolate_local(ViewLayer *view_layer, const View3D *v3d, LayerCollection *lc, @@ -1771,11 +1690,6 @@ static void layer_collection_bases_hide_recursive(ViewLayer *view_layer, LayerCo } } -/** - * Hide/show all the elements of a collection. - * Don't change the collection children enable/disable state, - * but it may change it for the collection itself. - */ void BKE_layer_collection_set_visible(ViewLayer *view_layer, LayerCollection *lc, const bool visible, @@ -1862,9 +1776,6 @@ static LayerCollection *find_layer_collection_by_scene_collection(LayerCollectio return NULL; } -/** - * Return the first matching LayerCollection in the ViewLayer for the Collection. - */ LayerCollection *BKE_layer_collection_first_from_scene_collection(const ViewLayer *view_layer, const Collection *collection) { @@ -1878,17 +1789,11 @@ LayerCollection *BKE_layer_collection_first_from_scene_collection(const ViewLaye return NULL; } -/** - * See if view layer has the scene collection linked directly, or indirectly (nested) - */ bool BKE_view_layer_has_collection(const ViewLayer *view_layer, const Collection *collection) { return BKE_layer_collection_first_from_scene_collection(view_layer, collection) != NULL; } -/** - * See if the object is in any of the scene layers of the scene - */ bool BKE_scene_has_object(Scene *scene, Object *ob) { LISTBASE_FOREACH (ViewLayer *, view_layer, &scene->view_layers) { @@ -2190,9 +2095,6 @@ void BKE_view_layer_bases_in_mode_iterator_end(BLI_Iterator *UNUSED(iter)) /* Evaluation. */ -/* Applies object's restrict flags on top of flags coming from the collection - * and stores those in base->flag. BASE_VISIBLE_DEPSGRAPH ignores viewport flags visibility - * (i.e., restriction and local collection). */ void BKE_base_eval_flags(Base *base) { /* Apply collection flags. */ @@ -2455,12 +2357,6 @@ static void bke_view_layer_verify_aov_cb(void *userdata, } } -/* Update the naming and conflicts of the AOVs. - * - * Name must be unique between all AOVs. - * Conflicts with render passes will show a conflict icon. Reason is that switching a render - * engine or activating a render pass could lead to other conflicts that wouldn't be that clear - * for the user. */ void BKE_view_layer_verify_aov(struct RenderEngine *engine, struct Scene *scene, struct ViewLayer *view_layer) @@ -2478,7 +2374,6 @@ void BKE_view_layer_verify_aov(struct RenderEngine *engine, BLI_ghash_free(name_count, MEM_freeN, NULL); } -/* Check if the given view layer has at least one valid AOV. */ bool BKE_view_layer_has_valid_aov(ViewLayer *view_layer) { LISTBASE_FOREACH (ViewLayerAOV *, aov, &view_layer->aovs) { diff --git a/source/blender/blenkernel/intern/layer_utils.c b/source/blender/blenkernel/intern/layer_utils.c index 48179e0c3bf..51ea7f58469 100644 --- a/source/blender/blenkernel/intern/layer_utils.c +++ b/source/blender/blenkernel/intern/layer_utils.c @@ -193,13 +193,6 @@ bool BKE_view_layer_filter_edit_mesh_has_edges(const Object *ob, void *UNUSED(us return false; } -/** - * Use this in rare cases we need to detect a pair of objects (active, selected). - * This returns the other non-active selected object. - * - * Returns NULL with it finds multiple other selected objects - * as behavior in this case would be random from the user perspective. - */ Object *BKE_view_layer_non_active_selected_object(struct ViewLayer *view_layer, const struct View3D *v3d) { diff --git a/source/blender/blenkernel/intern/lib_id.c b/source/blender/blenkernel/intern/lib_id.c index 53dada99405..692e27731c5 100644 --- a/source/blender/blenkernel/intern/lib_id.c +++ b/source/blender/blenkernel/intern/lib_id.c @@ -89,7 +89,6 @@ static CLG_LogRef LOG = {.identifier = "bke.lib_id"}; -/* Empty shell mostly, but needed for read code. */ IDTypeInfo IDType_ID_LINK_PLACEHOLDER = { .id_code = ID_LINK_PLACEHOLDER, .id_filter = 0, @@ -190,12 +189,6 @@ static int lib_id_clear_library_data_users_update_cb(LibraryIDLinkCallbackData * return IDWALK_RET_NOP; } -/** - * Pull an ID out of a library (make it local). Only call this for IDs that - * don't have other library users. - * - * \param flags: Same set of `LIB_ID_MAKELOCAL_` flags as passed to `BKE_lib_id_make_local`. - */ void BKE_lib_id_clear_library_data(Main *bmain, ID *id, const int flags) { const bool id_in_mainlist = (id->tag & LIB_TAG_NO_MAIN) == 0 && @@ -275,14 +268,6 @@ void id_lib_indirect_weak_link(ID *id) } } -/** - * Ensure we have a real user - * - * \note Now that we have flags, we could get rid of the 'fake_user' special case, - * flags are enough to ensure we always have a real user. - * However, #ID_REAL_USERS is used in several places outside of core lib.c, - * so think we can wait later to make this change. - */ void id_us_ensure_real(ID *id) { if (id) { @@ -313,10 +298,6 @@ void id_us_clear_real(ID *id) } } -/** - * Same as \a id_us_plus, but does not handle lib indirect -> extern. - * Only used by readfile.c so far, but simpler/safer to keep it here nonetheless. - */ void id_us_plus_no_lib(ID *id) { if (id) { @@ -341,7 +322,6 @@ void id_us_plus(ID *id) } } -/* decrements the user count for *id. */ void id_us_min(ID *id) { if (id) { @@ -457,10 +437,6 @@ static int lib_id_expand_local_cb(LibraryIDLinkCallbackData *cb_data) return IDWALK_RET_NOP; } -/** - * Expand ID usages of given id as 'extern' (and no more indirect) linked data. - * Used by ID copy/make_local functions. - */ void BKE_lib_id_expand_local(Main *bmain, ID *id, const int flags) { BKE_library_foreach_ID_link( @@ -478,9 +454,6 @@ static void lib_id_copy_ensure_local(Main *bmain, const ID *old_id, ID *new_id, } } -/** - * Generic 'make local' function, works for most of data-block types... - */ void BKE_lib_id_make_local_generic(Main *bmain, ID *id, const int flags) { if (!ID_IS_LINKED(id)) { @@ -550,15 +523,6 @@ void BKE_lib_id_make_local_generic(Main *bmain, ID *id, const int flags) } } -/** - * Calls the appropriate make_local method for the block, unless test is set. - * - * \note Always set #ID.newid pointer in case it gets duplicated. - * - * \param flags: Special flag used when making a whole library's content local, - * it needs specific handling. - * \return true is the ID has successfully been made local. - */ bool BKE_lib_id_make_local(Main *bmain, ID *id, const int flags) { const bool lib_local = (flags & LIB_ID_MAKELOCAL_FULL_LIBRARY) != 0; @@ -633,27 +597,6 @@ bool BKE_id_copy_is_allowed(const ID *id) #undef LIB_ID_TYPES_NOCOPY } -/** - * Generic entry point for copying a data-block (new API). - * - * \note Copy is generally only affecting the given data-block - * (no ID used by copied one will be affected, besides usercount). - * There are exceptions though: - * - Embedded IDs (root node trees and master collections) are always copied with their owner. - * - If #LIB_ID_COPY_ACTIONS is defined, actions used by animdata will be duplicated. - * - If #LIB_ID_COPY_SHAPEKEY is defined, shapekeys will be duplicated. - * - If #LIB_ID_CREATE_LOCAL is defined, root node trees will be deep-duplicated recursively. - * - * \note Usercount of new copy is always set to 1. - * - * \param bmain: Main database, may be NULL only if LIB_ID_CREATE_NO_MAIN is specified. - * \param id: Source data-block. - * \param r_newid: Pointer to new (copied) ID pointer, may be NULL. Used to allow copying into - * already allocated memory. - * \param flag: Set of copy options, see DNA_ID.h enum for details (leave to zero for default, - * full copy). - * \return NULL when copying that ID type is not supported, the new copy otherwise. - */ ID *BKE_id_copy_ex(Main *bmain, const ID *id, ID **r_newid, const int flag) { ID *newid = (r_newid != NULL) ? *r_newid : NULL; @@ -716,19 +659,11 @@ ID *BKE_id_copy_ex(Main *bmain, const ID *id, ID **r_newid, const int flag) return newid; } -/** - * Invokes the appropriate copy method for the block and returns the result in - * newid, unless test. Returns true if the block can be copied. - */ ID *BKE_id_copy(Main *bmain, const ID *id) { return BKE_id_copy_ex(bmain, id, NULL, LIB_ID_COPY_DEFAULT); } -/** - * Invokes the appropriate copy method for the block and returns the result in - * newid, unless test. Returns true if the block can be copied. - */ ID *BKE_id_copy_for_duplicate(Main *bmain, ID *id, const eDupli_ID_Flags duplicate_flags, @@ -809,31 +744,16 @@ static void id_swap(Main *bmain, ID *id_a, ID *id_b, const bool do_full_id) } } -/** - * Does a mere memory swap over the whole IDs data (including type-specific memory). - * \note Most internal ID data itself is not swapped (only IDProperties are). - * - * \param bmain: May be NULL, in which case there will be no remapping of internal pointers to - * itself. - */ void BKE_lib_id_swap(Main *bmain, ID *id_a, ID *id_b) { id_swap(bmain, id_a, id_b, false); } -/** - * Does a mere memory swap over the whole IDs data (including type-specific memory). - * \note All internal ID data itself is also swapped. - * - * \param bmain: May be NULL, in which case there will be no remapping of internal pointers to - * itself. - */ void BKE_lib_id_swap_full(Main *bmain, ID *id_a, ID *id_b) { id_swap(bmain, id_a, id_b, true); } -/** Does *not* set ID->newid pointer. */ bool id_single_user(bContext *C, ID *id, PointerRNA *ptr, PropertyRNA *prop) { ID *newid = NULL; @@ -898,7 +818,6 @@ static int libblock_management_us_min(LibraryIDLinkCallbackData *cb_data) return IDWALK_RET_NOP; } -/** Add a 'NO_MAIN' data-block to given main (also sets usercounts of its IDs if needed). */ void BKE_libblock_management_main_add(Main *bmain, void *idv) { ID *id = idv; @@ -932,7 +851,6 @@ void BKE_libblock_management_main_add(Main *bmain, void *idv) BKE_lib_libblock_session_uuid_ensure(id); } -/** Remove a data-block from given main (set it to 'NO_MAIN' status). */ void BKE_libblock_management_main_remove(Main *bmain, void *idv) { ID *id = idv; @@ -977,9 +895,6 @@ void BKE_libblock_management_usercounts_clear(Main *bmain, void *idv) id->tag |= LIB_TAG_NO_USER_REFCOUNT; } -/** - * Clear or set given tags for all ids in listbase (runtime tags). - */ void BKE_main_id_tag_listbase(ListBase *lb, const int tag, const bool value) { ID *id; @@ -996,9 +911,6 @@ void BKE_main_id_tag_listbase(ListBase *lb, const int tag, const bool value) } } -/** - * Clear or set given tags for all ids of given type in bmain (runtime tags). - */ void BKE_main_id_tag_idcode(struct Main *mainvar, const short type, const int tag, @@ -1009,9 +921,6 @@ void BKE_main_id_tag_idcode(struct Main *mainvar, BKE_main_id_tag_listbase(lb, tag, value); } -/** - * Clear or set given tags for all ids in bmain (runtime tags). - */ void BKE_main_id_tag_all(struct Main *mainvar, const int tag, const bool value) { ListBase *lbarray[INDEX_ID_MAX]; @@ -1023,9 +932,6 @@ void BKE_main_id_tag_all(struct Main *mainvar, const int tag, const bool value) } } -/** - * Clear or set given flags for all ids in listbase (persistent flags). - */ void BKE_main_id_flag_listbase(ListBase *lb, const int flag, const bool value) { ID *id; @@ -1042,9 +948,6 @@ void BKE_main_id_flag_listbase(ListBase *lb, const int flag, const bool value) } } -/** - * Clear or set given flags for all ids in bmain (persistent flags). - */ void BKE_main_id_flag_all(Main *bmain, const int flag, const bool value) { ListBase *lbarray[INDEX_ID_MAX]; @@ -1110,9 +1013,6 @@ void BKE_main_lib_objects_recalc_all(Main *bmain) * * **************************** */ -/** - * Get allocation size of a given data-block type and optionally allocation name. - */ size_t BKE_libblock_get_alloc_info(short type, const char **name) { const IDTypeInfo *id_type = BKE_idtype_get_info_from_idcode(type); @@ -1130,10 +1030,6 @@ size_t BKE_libblock_get_alloc_info(short type, const char **name) return id_type->struct_size; } -/** - * Allocates and returns memory of the right size for the specified block type, - * initialized to zero. - */ void *BKE_libblock_alloc_notest(short type) { const char *name; @@ -1145,12 +1041,6 @@ void *BKE_libblock_alloc_notest(short type) return NULL; } -/** - * Allocates and returns a block of the specified type, with the specified name - * (adjusted as necessary to ensure uniqueness), and appended to the specified list. - * The user count is set to 1, all other content (apart from name and links) being - * initialized to zero. - */ void *BKE_libblock_alloc(Main *bmain, short type, const char *name, const int flag) { BLI_assert((flag & LIB_ID_CREATE_NO_ALLOCATE) == 0); @@ -1213,10 +1103,6 @@ void *BKE_libblock_alloc(Main *bmain, short type, const char *name, const int fl return id; } -/** - * Initialize an ID of given type, such that it has valid 'empty' data. - * ID is assumed to be just calloc'ed. - */ void BKE_libblock_init_empty(ID *id) { const IDTypeInfo *idtype_info = BKE_idtype_get_info_from_id(id); @@ -1234,12 +1120,6 @@ void BKE_libblock_init_empty(ID *id) /* ********** ID session-wise UUID management. ********** */ static uint global_session_uuid = 0; -/** - * Generate a session-wise uuid for the given \a id. - * - * \note "session-wise" here means while editing a given .blend file. Once a new .blend file is - * loaded or created, undo history is cleared/reset, and so is the uuid counter. - */ void BKE_lib_libblock_session_uuid_ensure(ID *id) { if (id->session_uuid == MAIN_ID_SESSION_UUID_UNSET) { @@ -1253,25 +1133,12 @@ void BKE_lib_libblock_session_uuid_ensure(ID *id) } } -/** - * Re-generate a new session-wise uuid for the given \a id. - * - * \warning This has a few very specific use-cases, no other usage is expected currently: - * - To handle UI-related data-blocks that are kept across new file reading, when we do keep - * existing UI. - * - For IDs that are made local without needing any copying. - */ void BKE_lib_libblock_session_uuid_renew(ID *id) { id->session_uuid = MAIN_ID_SESSION_UUID_UNSET; BKE_lib_libblock_session_uuid_ensure(id); } -/** - * Generic helper to create a new empty data-block of given type in given \a bmain database. - * - * \param name: can be NULL, in which case we get default name for this ID type. - */ void *BKE_id_new(Main *bmain, const short type, const char *name) { BLI_assert(bmain != NULL); @@ -1286,11 +1153,6 @@ void *BKE_id_new(Main *bmain, const short type, const char *name) return id; } -/** - * Generic helper to create a new temporary empty data-block of given type, - * *outside* of any Main database. - * - * \param name: can be NULL, in which case we get default name for this ID type. */ void *BKE_id_new_nomain(const short type, const char *name) { if (name == NULL) { @@ -1404,7 +1266,6 @@ void BKE_libblock_copy_ex(Main *bmain, const ID *id, ID **r_newid, const int ori *r_newid = new_id; } -/* used everywhere in blenkernel */ void *BKE_libblock_copy(Main *bmain, const ID *id) { ID *idn; @@ -1415,6 +1276,7 @@ void *BKE_libblock_copy(Main *bmain, const ID *id) } /* ***************** ID ************************ */ + ID *BKE_libblock_find_name(struct Main *bmain, const short type, const char *name) { ListBase *lb = which_libbase(bmain, type); @@ -1436,14 +1298,6 @@ struct ID *BKE_libblock_find_session_uuid(Main *bmain, return NULL; } -/** - * Sort given \a id into given \a lb list, using case-insensitive comparison of the id names. - * - * \note All other IDs beside given one are assumed already properly sorted in the list. - * - * \param id_sorting_hint: Ignored if NULL. Otherwise, used to check if we can insert \a id - * immediately before or after that pointer. It must always be into given \a lb list. - */ void id_sort_by_name(ListBase *lb, ID *id, ID *id_sorting_hint) { #define ID_SORT_STEP_SIZE 512 @@ -1801,16 +1655,6 @@ static bool check_for_dupid(ListBase *lb, ID *id, char *name, ID **r_id_sorting_ #undef MIN_NUMBER #undef MAX_NUMBER -/** - * Ensures given ID has a unique name in given listbase. - * - * Only for local IDs (linked ones already have a unique ID in their library). - * - * \param do_linked_data: if true, also ensure a unique name in case the given \a id is linked - * (otherwise, just ensure that it is properly sorted). - * - * \return true if a new name had to be created. - */ bool BKE_id_new_name_validate(ListBase *lb, ID *id, const char *tname, const bool do_linked_data) { bool result = false; @@ -1860,7 +1704,6 @@ bool BKE_id_new_name_validate(ListBase *lb, ID *id, const char *tname, const boo return result; } -/* Next to indirect usage in `readfile.c/writefile.c` also in `editobject.c`, `scene.c`. */ void BKE_main_id_newptr_and_tag_clear(Main *bmain) { ID *id; @@ -1983,30 +1826,20 @@ static void library_make_local_copying_check(ID *id, BLI_gset_remove(loop_tags, id, NULL); } -/** - * Make linked data-blocks local. - * - * \param bmain: Almost certainly global main. - * \param lib: If not NULL, only make local data-blocks from this library. - * \param untagged_only: If true, only make local data-blocks not tagged with - * LIB_TAG_PRE_EXISTING. - * \param set_fake: If true, set fake user on all localized data-blocks - * (except group and objects ones). - */ /* NOTE: Old (2.77) version was simply making (tagging) data-blocks as local, * without actually making any check whether they were also indirectly used or not... * * Current version uses regular id_make_local callback, with advanced pre-processing step to * detect all cases of IDs currently indirectly used, but which will be used by local data only * once this function is finished. This allows to avoid any unneeded duplication of IDs, and - * hence all time lost afterwards to remove orphaned linked data-blocks... - */ + * hence all time lost afterwards to remove orphaned linked data-blocks. */ void BKE_library_make_local(Main *bmain, const Library *lib, GHash *old_to_new_ids, const bool untagged_only, const bool set_fake) { + ListBase *lbarray[INDEX_ID_MAX]; LinkNode *todo_ids = NULL; @@ -2280,10 +2113,6 @@ void BKE_library_make_local(Main *bmain, #endif } -/** - * Use after setting the ID's name - * When name exists: call 'new_id' - */ void BLI_libblock_ensure_unique_name(Main *bmain, const char *name) { ListBase *lb; @@ -2303,9 +2132,6 @@ void BLI_libblock_ensure_unique_name(Main *bmain, const char *name) } } -/** - * Sets the name of a block to name, suitably adjusted for uniqueness. - */ void BKE_libblock_rename(Main *bmain, ID *id, const char *name) { BLI_assert(!ID_IS_LINKED(id)); @@ -2315,16 +2141,6 @@ void BKE_libblock_rename(Main *bmain, ID *id, const char *name) } } -/** - * Generate full name of the data-block (without ID code, but with library if any). - * - * \note Result is unique to a given ID type in a given Main database. - * - * \param name: An allocated string of minimal length #MAX_ID_FULL_NAME, - * will be filled with generated string. - * \param separator_char: Character to use for separating name and library name. Can be 0 to use - * default (' '). - */ void BKE_id_full_name_get(char name[MAX_ID_FULL_NAME], const ID *id, char separator_char) { strcpy(name, id->name + 2); @@ -2341,19 +2157,6 @@ void BKE_id_full_name_get(char name[MAX_ID_FULL_NAME], const ID *id, char separa } } -/** - * Generate full name of the data-block (without ID code, but with library if any), - * with a 2 to 3 character prefix prepended indicating whether it comes from a library, - * is overriding, has a fake or no user, etc. - * - * \note Result is unique to a given ID type in a given Main database. - * - * \param name: An allocated string of minimal length #MAX_ID_FULL_NAME_UI, - * will be filled with generated string. - * \param separator_char: Character to use for separating name and library name. Can be 0 to use - * default (' '). - * \param r_prefix_len: The length of the prefix added. - */ void BKE_id_full_name_ui_prefix_get(char name[MAX_ID_FULL_NAME_UI], const ID *id, const bool add_lib_hint, @@ -2375,11 +2178,6 @@ void BKE_id_full_name_ui_prefix_get(char name[MAX_ID_FULL_NAME_UI], } } -/** - * Generate a concatenation of ID name (including two-chars type code) and its lib name, if any. - * - * \return A unique allocated string key for any ID in the whole Main database. - */ char *BKE_id_to_unique_string_key(const struct ID *id) { if (!ID_IS_LINKED(id)) { @@ -2403,10 +2201,6 @@ void BKE_id_tag_clear_atomic(ID *id, int tag) atomic_fetch_and_and_int32(&id->tag, ~tag); } -/** - * Check that given ID pointer actually is in G_MAIN. - * Main intended use is for debug asserts in places we cannot easily get rid of G_Main... - */ bool BKE_id_is_in_global_main(ID *id) { /* We do not want to fail when id is NULL here, even though this is a bit strange behavior... @@ -2453,10 +2247,6 @@ static int id_order_compare(const void *a, const void *b) return strcmp(id_a->name, id_b->name); } -/** - * Returns ordered list of data-blocks for display in the UI. - * Result is list of LinkData of IDs that must be freed. - */ void BKE_id_ordered_list(ListBase *ordered_lb, const ListBase *lb) { BLI_listbase_clear(ordered_lb); @@ -2476,9 +2266,6 @@ void BKE_id_ordered_list(ListBase *ordered_lb, const ListBase *lb) } } -/** - * Reorder ID in the list, before or after the "relative" ID. - */ void BKE_id_reorder(const ListBase *lb, ID *id, ID *relative, bool after) { int *id_order = id_order_get(id); diff --git a/source/blender/blenkernel/intern/lib_id_delete.c b/source/blender/blenkernel/intern/lib_id_delete.c index 502a1197616..1922a54addb 100644 --- a/source/blender/blenkernel/intern/lib_id_delete.c +++ b/source/blender/blenkernel/intern/lib_id_delete.c @@ -90,23 +90,6 @@ void BKE_libblock_free_datablock(ID *id, const int UNUSED(flag)) BLI_assert_msg(0, "IDType Missing IDTypeInfo"); } -/** - * Complete ID freeing, extended version for corner cases. - * Can override default (and safe!) freeing process, to gain some speed up. - * - * At that point, given id is assumed to not be used by any other data-block already - * (might not be actually true, in case e.g. several inter-related IDs get freed together...). - * However, they might still be using (referencing) other IDs, this code takes care of it if - * #LIB_TAG_NO_USER_REFCOUNT is not defined. - * - * \param bmain: #Main database containing the freed #ID, - * can be NULL in case it's a temp ID outside of any #Main. - * \param idv: Pointer to ID to be freed. - * \param flag: Set of \a LIB_ID_FREE_... flags controlling/overriding usual freeing process, - * 0 to get default safe behavior. - * \param use_flag_from_idtag: Still use freeing info flags from given #ID datablock, - * even if some overriding ones are passed in \a flag parameter. - */ void BKE_id_free_ex(Main *bmain, void *idv, int flag, const bool use_flag_from_idtag) { ID *id = idv; @@ -191,24 +174,11 @@ void BKE_id_free_ex(Main *bmain, void *idv, int flag, const bool use_flag_from_i } } -/** - * Complete ID freeing, should be usable in most cases (even for out-of-Main IDs). - * - * See #BKE_id_free_ex description for full details. - * - * \param bmain: Main database containing the freed ID, - * can be NULL in case it's a temp ID outside of any Main. - * \param idv: Pointer to ID to be freed. - */ void BKE_id_free(Main *bmain, void *idv) { BKE_id_free_ex(bmain, idv, 0, true); } -/** - * Not really a freeing function by itself, - * it decrements usercount of given id, and only frees it if it reaches 0. - */ void BKE_id_free_us(Main *bmain, void *idv) /* test users */ { ID *id = idv; @@ -378,9 +348,6 @@ static size_t id_delete(Main *bmain, const bool do_tagged_deletion) return num_datablocks_deleted; } -/** - * Properly delete a single ID from given \a bmain database. - */ void BKE_id_delete(Main *bmain, void *idv) { BKE_main_id_tag_all(bmain, LIB_TAG_DOIT, false); @@ -389,16 +356,6 @@ void BKE_id_delete(Main *bmain, void *idv) id_delete(bmain, false); } -/** - * Properly delete all IDs tagged with \a LIB_TAG_DOIT, in given \a bmain database. - * - * This is more efficient than calling #BKE_id_delete repetitively on a large set of IDs - * (several times faster when deleting most of the IDs at once)... - * - * \warning Considered experimental for now, seems to be working OK but this is - * risky code in a complicated area. - * \return Number of deleted datablocks. - */ size_t BKE_id_multi_tagged_delete(Main *bmain) { return id_delete(bmain, true); @@ -408,12 +365,6 @@ size_t BKE_id_multi_tagged_delete(Main *bmain) /** \name Python Data Handling * \{ */ -/** - * In most cases #BKE_id_free_ex handles this, when lower level functions are called directly - * this function will need to be called too, if Python has access to the data. - * - * ID data-blocks such as #Material.nodetree are not stored in #Main. - */ void BKE_libblock_free_data_py(ID *id) { #ifdef WITH_PYTHON diff --git a/source/blender/blenkernel/intern/lib_id_eval.c b/source/blender/blenkernel/intern/lib_id_eval.c index 140fe403ac3..a29d9270d72 100644 --- a/source/blender/blenkernel/intern/lib_id_eval.c +++ b/source/blender/blenkernel/intern/lib_id_eval.c @@ -29,11 +29,6 @@ #include "BKE_lib_id.h" #include "BKE_mesh.h" -/** - * Copy relatives parameters, from `id` to `id_cow`. - * Use handle the #ID_RECALC_PARAMETERS tag. - * \note Keep in sync with #ID_TYPE_SUPPORTS_PARAMS_WITHOUT_COW. - */ void BKE_id_eval_properties_copy(ID *id_cow, ID *id) { const ID_Type id_type = GS(id->name); diff --git a/source/blender/blenkernel/intern/lib_override.c b/source/blender/blenkernel/intern/lib_override.c index 66a550ec6b0..52bfeb4b4d3 100644 --- a/source/blender/blenkernel/intern/lib_override.c +++ b/source/blender/blenkernel/intern/lib_override.c @@ -99,7 +99,6 @@ BLI_INLINE IDOverrideLibrary *lib_override_get(Main *bmain, ID *id) return id->override_library; } -/** Initialize empty overriding of \a reference_id by \a local_id. */ IDOverrideLibrary *BKE_lib_override_library_init(ID *local_id, ID *reference_id) { /* If reference_id is NULL, we are creating an override template for purely local data. @@ -134,7 +133,6 @@ IDOverrideLibrary *BKE_lib_override_library_init(ID *local_id, ID *reference_id) return local_id->override_library; } -/** Shalow or deep copy of a whole override from \a src_id to \a dst_id. */ void BKE_lib_override_library_copy(ID *dst_id, const ID *src_id, const bool do_full_copy) { BLI_assert(ID_IS_OVERRIDE_LIBRARY(src_id) || ID_IS_OVERRIDE_LIBRARY_TEMPLATE(src_id)); @@ -176,7 +174,6 @@ void BKE_lib_override_library_copy(ID *dst_id, const ID *src_id, const bool do_f dst_id->tag &= ~LIB_TAG_OVERRIDE_LIBRARY_REFOK; } -/** Clear any overriding data from given \a override. */ void BKE_lib_override_library_clear(IDOverrideLibrary *override, const bool do_id_user) { BLI_assert(override != NULL); @@ -196,7 +193,6 @@ void BKE_lib_override_library_clear(IDOverrideLibrary *override, const bool do_i } } -/** Free given \a override. */ void BKE_lib_override_library_free(struct IDOverrideLibrary **override, const bool do_id_user) { BLI_assert(*override != NULL); @@ -245,14 +241,11 @@ static ID *lib_override_library_create_from(Main *bmain, return local_id; } -/** - * Check if given ID has some override rules that actually indicate the user edited it. - * - * TODO: This could be simplified by storing a flag in #IDOverrideLibrary during the diffing - * process? - */ +/* TODO: This could be simplified by storing a flag in #IDOverrideLibrary + * during the diffing process? */ bool BKE_lib_override_library_is_user_edited(struct ID *id) { + if (!ID_IS_OVERRIDE_LIBRARY(id)) { return false; } @@ -280,7 +273,6 @@ bool BKE_lib_override_library_is_user_edited(struct ID *id) return false; } -/** Create an overridden local copy of linked reference. */ ID *BKE_lib_override_library_create_from_id(Main *bmain, ID *reference_id, const bool do_tagged_remap) @@ -322,25 +314,6 @@ ID *BKE_lib_override_library_create_from_id(Main *bmain, return local_id; } -/** - * Create overridden local copies of all tagged data-blocks in given Main. - * - * \note Set `id->newid` of overridden libs with newly created overrides, - * caller is responsible to clean those pointers before/after usage as needed. - * - * \note By default, it will only remap newly created local overriding data-blocks between - * themselves, to avoid 'enforcing' those overrides into all other usages of the linked data in - * main. You can add more local IDs to be remapped to use new overriding ones by setting their - * LIB_TAG_DOIT tag. - * - * \param reference_library: the library from which the linked data being overridden come from - * (i.e. the library of the linked reference ID). - * - * \param do_no_main: Create the new override data outside of Main database. - * Used for resyncing of linked overrides. - * - * \return \a true on success, \a false otherwise. - */ bool BKE_lib_override_library_create_from_tag(Main *bmain, const Library *reference_library, const bool do_no_main) @@ -890,24 +863,6 @@ static void lib_override_library_create_post_process(Main *bmain, BLI_gset_free(all_objects_in_scene, NULL); } -/** - * Advanced 'smart' function to create fully functional overrides. - * - * \note Currently it only does special things if given \a id_root is an object or collection, more - * specific behaviors may be added in the future for other ID types. - * - * \note It will override all IDs tagged with \a LIB_TAG_DOIT, and it does not clear that tag at - * its beginning, so caller code can add extra data-blocks to be overridden as well. - * - * \param view_layer: the active view layer to search instantiated collections in, can be NULL (in - * which case \a scene's master collection children hierarchy is used instead). - * \param id_root: The root ID to create an override from. - * \param id_reference: Some reference ID used to do some post-processing after overrides have been - * created, may be NULL. Typically, the Empty object instantiating the linked collection we - * override, currently. - * \param r_id_root_override: if not NULL, the override generated for the given \a id_root. - * \return true if override was successfully created. - */ bool BKE_lib_override_library_create(Main *bmain, Scene *scene, ViewLayer *view_layer, @@ -942,9 +897,6 @@ bool BKE_lib_override_library_create(Main *bmain, return success; } -/** - * Create a library override template. - */ bool BKE_lib_override_library_template_create(struct ID *id) { if (ID_IS_LINKED(id)) { @@ -958,16 +910,6 @@ bool BKE_lib_override_library_template_create(struct ID *id) return true; } -/** - * Convert a given proxy object into a library override. - * - * \note This is a thin wrapper around \a BKE_lib_override_library_create, only extra work is to - * actually convert the proxy itself into an override first. - * - * \param view_layer: the active view layer to search instantiated collections in, can be NULL (in - * which case \a scene's master collection children hierarchy is used instead). - * \return true if override was successfully created. - */ bool BKE_lib_override_library_proxy_convert(Main *bmain, Scene *scene, ViewLayer *view_layer, @@ -1039,14 +981,6 @@ static void lib_override_library_proxy_convert_do(Main *bmain, } } -/** - * Convert all proxy objects into library overrides. - * - * \note Only affects local proxies, linked ones are not affected. - * - * \param view_layer: the active view layer to search instantiated collections in, can be NULL (in - * which case \a scene's master collection children hierarchy is used instead). - */ void BKE_lib_override_library_main_proxy_convert(Main *bmain, BlendFileReadReport *reports) { LISTBASE_FOREACH (Scene *, scene, &bmain->scenes) { @@ -1086,15 +1020,6 @@ void BKE_lib_override_library_main_proxy_convert(Main *bmain, BlendFileReadRepor } } -/** - * Advanced 'smart' function to resync, re-create fully functional overrides up-to-date with linked - * data, from an existing override hierarchy. - * - * \param id_root: The root liboverride ID to resync from. - * \param view_layer: the active view layer to search instantiated collections in, can be NULL (in - * which case \a scene's master collection children hierarchy is used instead). - * \return true if override was successfully resynced. - */ bool BKE_lib_override_library_resync(Main *bmain, Scene *scene, ViewLayer *view_layer, @@ -1801,23 +1726,6 @@ static int lib_override_libraries_index_define(Main *bmain) return library_indirect_level_max; } -/** - * Detect and handle required resync of overrides data, when relations between reference linked IDs - * have changed. - * - * This is a fairly complex and costly operation, typically it should be called after - * #BKE_lib_override_library_main_update, which would already detect and tag a lot of cases. - * - * This function will first detect the remaining cases requiring a resync (namely, either when an - * existing linked ID that did not require to be overridden before now would be, or when new IDs - * are added to the hierarchy). - * - * Then it will handle the resync of necessary IDs (through calls to - * #BKE_lib_override_library_resync). - * - * \param view_layer: the active view layer to search instantiated collections in, can be NULL (in - * which case \a scene's master collection children hierarchy is used instead). - */ void BKE_lib_override_library_main_resync(Main *bmain, Scene *scene, ViewLayer *view_layer, @@ -1866,14 +1774,6 @@ void BKE_lib_override_library_main_resync(Main *bmain, } } -/** - * Advanced 'smart' function to delete library overrides (including their existing override - * hierarchy) and remap their usages to their linked reference IDs. - * - * \note All IDs tagged with `LIB_TAG_DOIT` will be deleted. - * - * \param id_root: The root liboverride ID to delete. - */ void BKE_lib_override_library_delete(Main *bmain, ID *id_root) { BLI_assert(ID_IS_OVERRIDE_LIBRARY_REAL(id_root)); @@ -1911,11 +1811,6 @@ void BKE_lib_override_library_delete(Main *bmain, ID *id_root) BKE_main_id_tag_all(bmain, LIB_TAG_DOIT, false); } -/** Make given ID fully local. - * - * \note Only differs from lower-level `BKE_lib_override_library_free in infamous embedded ID - * cases. - */ void BKE_lib_override_library_make_local(ID *id) { if (!ID_IS_OVERRIDE_LIBRARY(id)) { @@ -1972,9 +1867,6 @@ BLI_INLINE GHash *override_library_rna_path_mapping_ensure(IDOverrideLibrary *ov return override_runtime->rna_path_to_override_properties; } -/** - * Find override property from given RNA path, if it exists. - */ IDOverrideLibraryProperty *BKE_lib_override_library_property_find(IDOverrideLibrary *override, const char *rna_path) { @@ -1982,9 +1874,6 @@ IDOverrideLibraryProperty *BKE_lib_override_library_property_find(IDOverrideLibr return BLI_ghash_lookup(override_runtime, rna_path); } -/** - * Find override property from given RNA path, or create it if it does not exist. - */ IDOverrideLibraryProperty *BKE_lib_override_library_property_get(IDOverrideLibrary *override, const char *rna_path, bool *r_created) @@ -2010,13 +1899,6 @@ IDOverrideLibraryProperty *BKE_lib_override_library_property_get(IDOverrideLibra return op; } -/** - * Get the RNA-property matching the \a library_prop override property. Used for UI to query - * additional data about the overridden property (e.g. UI name). - * - * \param idpoin: Pointer to the override ID. - * \param library_prop: The library override property to find the matching RNA property for. - */ bool BKE_lib_override_rna_property_find(PointerRNA *idpoin, const IDOverrideLibraryProperty *library_prop, PointerRNA *r_override_poin, @@ -2053,9 +1935,6 @@ void lib_override_library_property_clear(IDOverrideLibraryProperty *op) BLI_freelistN(&op->operations); } -/** - * Remove and free given \a override_property from given ID \a override. - */ void BKE_lib_override_library_property_delete(IDOverrideLibrary *override, IDOverrideLibraryProperty *override_property) { @@ -2069,9 +1948,6 @@ void BKE_lib_override_library_property_delete(IDOverrideLibrary *override, BLI_freelinkN(&override->properties, override_property); } -/** - * Find override property operation from given sub-item(s), if it exists. - */ IDOverrideLibraryPropertyOperation *BKE_lib_override_library_property_operation_find( IDOverrideLibraryProperty *override_property, const char *subitem_refname, @@ -2158,9 +2034,6 @@ IDOverrideLibraryPropertyOperation *BKE_lib_override_library_property_operation_ return NULL; } -/** - * Find override property operation from given sub-item(s), or create it if it does not exist. - */ IDOverrideLibraryPropertyOperation *BKE_lib_override_library_property_operation_get( IDOverrideLibraryProperty *override_property, const short operation, @@ -2227,9 +2100,6 @@ void lib_override_library_property_operation_clear(IDOverrideLibraryPropertyOper } } -/** - * Remove and free given \a override_property_operation from given ID \a override_property. - */ void BKE_lib_override_library_property_operation_delete( IDOverrideLibraryProperty *override_property, IDOverrideLibraryPropertyOperation *override_property_operation) @@ -2238,9 +2108,6 @@ void BKE_lib_override_library_property_operation_delete( BLI_freelinkN(&override_property->operations, override_property_operation); } -/** - * Validate that required data for a given operation are available. - */ bool BKE_lib_override_library_property_operation_operands_validate( struct IDOverrideLibraryPropertyOperation *override_property_operation, struct PointerRNA *ptr_dst, @@ -2278,7 +2145,6 @@ bool BKE_lib_override_library_property_operation_operands_validate( return true; } -/** Check against potential \a bmain. */ void BKE_lib_override_library_validate(Main *UNUSED(bmain), ID *id, ReportList *reports) { if (id->override_library == NULL) { @@ -2312,7 +2178,6 @@ void BKE_lib_override_library_validate(Main *UNUSED(bmain), ID *id, ReportList * } } -/** Check against potential \a bmain. */ void BKE_lib_override_library_main_validate(Main *bmain, ReportList *reports) { ID *id; @@ -2325,16 +2190,6 @@ void BKE_lib_override_library_main_validate(Main *bmain, ReportList *reports) FOREACH_MAIN_ID_END; } -/** - * Check that status of local data-block is still valid against current reference one. - * - * It means that all overridable, but not overridden, properties' local values must be equal to - * reference ones. Clears #LIB_TAG_OVERRIDE_OK if they do not. - * - * This is typically used to detect whether some property has been changed in local and a new - * #IDOverrideProperty (of #IDOverridePropertyOperation) has to be added. - * - * \return true if status is OK, false otherwise. */ bool BKE_lib_override_library_status_check_local(Main *bmain, ID *local) { BLI_assert(ID_IS_OVERRIDE_LIBRARY_REAL(local)); @@ -2384,16 +2239,6 @@ bool BKE_lib_override_library_status_check_local(Main *bmain, ID *local) return true; } -/** - * Check that status of reference data-block is still valid against current local one. - * - * It means that all non-overridden properties' local values must be equal to reference ones. - * Clears LIB_TAG_OVERRIDE_OK if they do not. - * - * This is typically used to detect whether some reference has changed and local - * needs to be updated against it. - * - * \return true if status is OK, false otherwise. */ bool BKE_lib_override_library_status_check_reference(Main *bmain, ID *local) { BLI_assert(ID_IS_OVERRIDE_LIBRARY_REAL(local)); @@ -2450,20 +2295,6 @@ bool BKE_lib_override_library_status_check_reference(Main *bmain, ID *local) return true; } -/** - * Compare local and reference data-blocks and create new override operations as needed, - * or reset to reference values if overriding is not allowed. - * - * \note Defining override operations is only mandatory before saving a `.blend` file on disk - * (not for undo!). - * Knowing that info at runtime is only useful for UI/UX feedback. - * - * \note This is by far the biggest operation (the more time-consuming) of the three so far, - * since it has to go over all properties in depth (all overridable ones at least). - * Generating differential values and applying overrides are much cheaper. - * - * \return true if any library operation was created. - */ bool BKE_lib_override_library_operations_create(Main *bmain, ID *local) { BLI_assert(local->override_library != NULL); @@ -2540,7 +2371,6 @@ static void lib_override_library_operations_create_cb(TaskPool *__restrict pool, } } -/** Check all overrides from given \a bmain and create/update overriding operations as needed. */ bool BKE_lib_override_library_main_operations_create(Main *bmain, const bool force_auto) { ID *id; @@ -2669,7 +2499,6 @@ static bool lib_override_library_id_reset_do(Main *bmain, ID *id_root) return was_op_deleted; } -/** Reset all overrides in given \a id_root, while preserving ID relations. */ void BKE_lib_override_library_id_reset(Main *bmain, ID *id_root) { if (!ID_IS_OVERRIDE_LIBRARY_REAL(id_root)) { @@ -2728,7 +2557,6 @@ static void lib_override_library_id_hierarchy_recursive_reset(Main *bmain, ID *i } } -/** Reset all overrides in given \a id_root and its dependencies, while preserving ID relations. */ void BKE_lib_override_library_id_hierarchy_reset(Main *bmain, ID *id_root) { BKE_main_relations_create(bmain, 0); @@ -2749,7 +2577,6 @@ void BKE_lib_override_library_id_hierarchy_reset(Main *bmain, ID *id_root) FOREACH_MAIN_ID_END; } -/** Set or clear given tag in all operations in that override property data. */ void BKE_lib_override_library_operations_tag(struct IDOverrideLibraryProperty *override_property, const short tag, const bool do_set) @@ -2773,7 +2600,6 @@ void BKE_lib_override_library_operations_tag(struct IDOverrideLibraryProperty *o } } -/** Set or clear given tag in all properties and operations in that override data. */ void BKE_lib_override_library_properties_tag(struct IDOverrideLibrary *override, const short tag, const bool do_set) @@ -2785,7 +2611,6 @@ void BKE_lib_override_library_properties_tag(struct IDOverrideLibrary *override, } } -/** Set or clear given tag in all properties and operations in that Main's ID override data. */ void BKE_lib_override_library_main_tag(struct Main *bmain, const short tag, const bool do_set) { ID *id; @@ -2798,7 +2623,6 @@ void BKE_lib_override_library_main_tag(struct Main *bmain, const short tag, cons FOREACH_MAIN_ID_END; } -/** Remove all tagged-as-unused properties and operations from that ID override data. */ void BKE_lib_override_library_id_unused_cleanup(struct ID *local) { if (ID_IS_OVERRIDE_LIBRARY_REAL(local)) { @@ -2818,7 +2642,6 @@ void BKE_lib_override_library_id_unused_cleanup(struct ID *local) } } -/** Remove all tagged-as-unused properties and operations from that Main's ID override data. */ void BKE_lib_override_library_main_unused_cleanup(struct Main *bmain) { ID *id; @@ -2839,7 +2662,6 @@ static void lib_override_id_swap(Main *bmain, ID *id_local, ID *id_temp) id_local->tag |= (id_temp->tag & LIB_TAG_LIB_OVERRIDE_NEED_RESYNC); } -/** Update given override from its reference (re-applying overridden properties). */ void BKE_lib_override_library_update(Main *bmain, ID *local) { if (!ID_IS_OVERRIDE_LIBRARY_REAL(local)) { @@ -2964,7 +2786,6 @@ void BKE_lib_override_library_update(Main *bmain, ID *local) DEG_relations_tag_update(bmain); } -/** Update all overrides from given \a bmain. */ void BKE_lib_override_library_main_update(Main *bmain) { ID *id; @@ -2985,7 +2806,6 @@ void BKE_lib_override_library_main_update(Main *bmain) G_MAIN = orig_gmain; } -/** In case an ID is used by another liboverride ID, user may not be allowed to delete it. */ bool BKE_lib_override_library_id_is_user_deletable(struct Main *bmain, struct ID *id) { if (!(ID_IS_LINKED(id) || ID_IS_OVERRIDE_LIBRARY(id))) { @@ -3026,17 +2846,11 @@ bool BKE_lib_override_library_id_is_user_deletable(struct Main *bmain, struct ID * exact same data as "desired" ones (kind of "baked" data-blocks). */ -/** Initialize an override storage. */ OverrideLibraryStorage *BKE_lib_override_library_operations_store_init(void) { return BKE_main_new(); } -/** - * Generate suitable 'write' data (this only affects differential override operations). - * - * Note that \a local ID is no more modified by this call, - * all extra data are stored in its temp \a storage_id copy. */ ID *BKE_lib_override_library_operations_store_start(Main *bmain, OverrideLibraryStorage *override_storage, ID *local) @@ -3101,10 +2915,6 @@ ID *BKE_lib_override_library_operations_store_start(Main *bmain, return storage_id; } -/** - * Restore given ID modified by #BKE_lib_override_library_operations_store_start, to its - * original state. - */ void BKE_lib_override_library_operations_store_end( OverrideLibraryStorage *UNUSED(override_storage), ID *local) { diff --git a/source/blender/blenkernel/intern/lib_query.c b/source/blender/blenkernel/intern/lib_query.c index 74750a9b61a..4ad0186f9b5 100644 --- a/source/blender/blenkernel/intern/lib_query.c +++ b/source/blender/blenkernel/intern/lib_query.c @@ -76,8 +76,6 @@ typedef struct LibraryForeachIDData { BLI_LINKSTACK_DECLARE(ids_todo, ID *); } LibraryForeachIDData; -/** Check whether current iteration over ID usages should be stopped or not. - * \return true if the iteration should be stopped, false otherwise. */ bool BKE_lib_query_foreachid_iter_stop(LibraryForeachIDData *data) { return (data->status & IDWALK_STOP) != 0; @@ -162,10 +160,6 @@ void BKE_lib_query_idpropertiesForeachIDLink_callback(IDProperty *id_prop, void BKE_LIB_FOREACHID_PROCESS_ID(data, id_prop->data.pointer, cb_flag); } -/** Process embedded ID pointers (root nodetrees, master collections, ...). - * - * Those require specific care, since they are technically sub-data of their owner, yet in some - * cases they still behave as regular IDs. */ void BKE_library_foreach_ID_embedded(LibraryForeachIDData *data, ID **id_pp) { /* Needed e.g. for callbacks handling relationships. This call shall be absolutely read-only. */ @@ -367,18 +361,12 @@ static bool library_foreach_ID_link(Main *bmain, #undef CALLBACK_INVOKE } -/** - * Loop over all of the ID's this data-block links to. - */ void BKE_library_foreach_ID_link( Main *bmain, ID *id, LibraryIDLinkCallback callback, void *user_data, int flag) { library_foreach_ID_link(bmain, NULL, id, callback, user_data, flag, NULL); } -/** - * re-usable function, use when replacing ID's - */ void BKE_library_update_ID_link_user(ID *id_dst, ID *id_src, const int cb_flag) { if (cb_flag & IDWALK_CB_USER) { @@ -390,12 +378,6 @@ void BKE_library_update_ID_link_user(ID *id_dst, ID *id_src, const int cb_flag) } } -/** - * Say whether given \a id_owner may use (in any way) a data-block of \a id_type_used. - * - * This is a 'simplified' abstract version of #BKE_library_foreach_ID_link() above, - * quite useful to reduce useless iterations in some cases. - */ bool BKE_library_id_can_use_idtype(ID *id_owner, const short id_type_used) { /* any type of ID can be used in custom props. */ @@ -567,16 +549,6 @@ static int foreach_libblock_id_users_callback(LibraryIDLinkCallbackData *cb_data return IDWALK_RET_NOP; } -/** - * Return the number of times given \a id_user uses/references \a id_used. - * - * \note This only checks for pointer references of an ID, shallow usages - * (like e.g. by RNA paths, as done for FCurves) are not detected at all. - * - * \param id_user: the ID which is supposed to use (reference) \a id_used. - * \param id_used: the ID which is supposed to be used (referenced) by \a id_user. - * \return the number of direct usages/references of \a id_used by \a id_user. - */ int BKE_library_ID_use_ID(ID *id_user, ID *id_used) { IDUsersIter iter; @@ -625,26 +597,16 @@ static bool library_ID_is_used(Main *bmain, void *idv, const bool check_linked) return is_defined; } -/** - * Check whether given ID is used locally (i.e. by another non-linked ID). - */ bool BKE_library_ID_is_locally_used(Main *bmain, void *idv) { return library_ID_is_used(bmain, idv, false); } -/** - * Check whether given ID is used indirectly (i.e. by another linked ID). - */ bool BKE_library_ID_is_indirectly_used(Main *bmain, void *idv) { return library_ID_is_used(bmain, idv, true); } -/** - * Combine #BKE_library_ID_is_locally_used() and #BKE_library_ID_is_indirectly_used() - * in a single call. - */ void BKE_library_ID_test_usages(Main *bmain, void *idv, bool *is_used_local, bool *is_used_linked) { IDUsersIter iter; @@ -759,21 +721,6 @@ static void lib_query_unused_ids_tag_recurse(Main *bmain, } } -/** - * Tag all unused IDs (a.k.a 'orphaned'). - * - * By default only tag IDs with `0` user count. - * If `do_tag_recursive` is set, it will check dependencies to detect all IDs that are not actually - * used in current file, including 'archipelagos` (i.e. set of IDs referencing each other in - * loops, but without any 'external' valid usages. - * - * Valid usages here are defined as ref-counting usages, which are not towards embedded or - * loop-back data. - * - * \param r_num_tagged: If non-NULL, must be a zero-initialized array of #INDEX_ID_MAX integers. - * Number of tagged-as-unused IDs is then set for each type, and as total in - * #INDEX_ID_NULL item. - */ void BKE_lib_query_unused_ids_tag(Main *bmain, const int tag, const bool do_local_ids, @@ -838,15 +785,6 @@ static int foreach_libblock_used_linked_data_tag_clear_cb(LibraryIDLinkCallbackD return IDWALK_RET_NOP; } -/** - * Detect orphaned linked data blocks (i.e. linked data not used (directly or indirectly) - * in any way by any local data), including complex cases like 'linked archipelagoes', i.e. - * linked data-blocks that use each other in loops, - * which prevents their deletion by 'basic' usage checks. - * - * \param do_init_tag: if \a true, all linked data are checked, if \a false, - * only linked data-blocks already tagged with #LIB_TAG_DOIT are checked. - */ void BKE_library_unused_linked_data_set_tag(Main *bmain, const bool do_init_tag) { ID *id; @@ -876,14 +814,6 @@ void BKE_library_unused_linked_data_set_tag(Main *bmain, const bool do_init_tag) } } -/** - * Untag linked data blocks used by other untagged linked data-blocks. - * Used to detect data-blocks that we can forcefully make local - * (instead of copying them to later get rid of original): - * All data-blocks we want to make local are tagged by caller, - * after this function has ran caller knows data-blocks still tagged can directly be made local, - * since they are only used by other data-blocks that will also be made fully local. - */ void BKE_library_indirectly_used_data_tag_clear(Main *bmain) { ListBase *lb_array[INDEX_ID_MAX]; diff --git a/source/blender/blenkernel/intern/lib_remap.c b/source/blender/blenkernel/intern/lib_remap.c index 014c923f04f..3cea0de32ee 100644 --- a/source/blender/blenkernel/intern/lib_remap.c +++ b/source/blender/blenkernel/intern/lib_remap.c @@ -456,10 +456,6 @@ static void libblock_remap_data( #endif } -/** - * Replace all references in given Main to \a old_id by \a new_id - * (if \a new_id is NULL, it unlinks \a old_id). - */ void BKE_libblock_remap_locked(Main *bmain, void *old_idv, void *new_idv, const short remap_flags) { IDRemap id_remap_data; @@ -565,13 +561,6 @@ void BKE_libblock_remap(Main *bmain, void *old_idv, void *new_idv, const short r BKE_main_unlock(bmain); } -/** - * Unlink given \a id from given \a bmain - * (does not touch to indirect, i.e. library, usages of the ID). - * - * \param do_flag_never_null: If true, all IDs using \a idv in a 'non-NULL' way are flagged by - * #LIB_TAG_DOIT flag (quite obviously, 'non-NULL' usages can never be unlinked by this function). - */ void BKE_libblock_unlink(Main *bmain, void *idv, const bool do_flag_never_null, @@ -587,16 +576,6 @@ void BKE_libblock_unlink(Main *bmain, BKE_main_unlock(bmain); } -/** - * Similar to libblock_remap, but only affects IDs used by given \a idv ID. - * - * \param old_idv: Unlike BKE_libblock_remap, can be NULL, - * in which case all ID usages by given \a idv will be cleared. - * \param us_min_never_null: If \a true and new_id is NULL, - * 'NEVER_NULL' ID usages keep their old id, but this one still gets its user count decremented - * (needed when given \a idv is going to be deleted right after being unlinked). - */ -/* Should be able to replace all _relink() funcs (constraints, rigidbody, etc.) ? */ /* XXX Arg! Naming... :( * _relink? avoids confusion with _remap, but is confusing with _unlink * _remap_used_ids? @@ -604,9 +583,13 @@ void BKE_libblock_unlink(Main *bmain, * BKE_id_remap maybe? * ... sigh */ + void BKE_libblock_relink_ex( Main *bmain, void *idv, void *old_idv, void *new_idv, const short remap_flags) { + + /* Should be able to replace all _relink() funcs (constraints, rigidbody, etc.) ? */ + ID *id = idv; ID *old_id = old_idv; ID *new_id = new_idv; @@ -710,15 +693,6 @@ static void libblock_relink_to_newid(Main *bmain, ID *id, const int remap_flag) bmain, id, id_relink_to_newid_looper, POINTER_FROM_INT(remap_flag), 0); } -/** - * Remaps ID usages of given ID to their `id->newid` pointer if not None, and proceeds recursively - * in the dependency tree of IDs for all data-blocks tagged with `LIB_TAG_NEW`. - * - * NOTE: `LIB_TAG_NEW` is cleared - * - * Very specific usage, not sure we'll keep it on the long run, - * currently only used in Object/Collection duplication code... - */ void BKE_libblock_relink_to_newid(Main *bmain, ID *id, const int remap_flag) { if (ID_IS_LINKED(id)) { diff --git a/source/blender/blenkernel/intern/linestyle.c b/source/blender/blenkernel/intern/linestyle.c index b198808b8f3..ac0dbcb715d 100644 --- a/source/blender/blenkernel/intern/linestyle.c +++ b/source/blender/blenkernel/intern/linestyle.c @@ -1912,10 +1912,6 @@ int BKE_linestyle_geometry_modifier_remove(FreestyleLineStyle *linestyle, LineSt return 0; } -/** - * Reinsert \a modifier in modifier list with an offset of \a direction. - * \return if position of \a modifier has changed. - */ bool BKE_linestyle_color_modifier_move(FreestyleLineStyle *linestyle, LineStyleModifier *modifier, int direction) diff --git a/source/blender/blenkernel/intern/main.c b/source/blender/blenkernel/intern/main.c index a5de0bc99c8..7254d5d50ee 100644 --- a/source/blender/blenkernel/intern/main.c +++ b/source/blender/blenkernel/intern/main.c @@ -205,7 +205,6 @@ void BKE_main_free(Main *mainvar) MEM_freeN(mainvar); } -/* Check whether given `bmain` is empty or contains some IDs. */ bool BKE_main_is_empty(struct Main *bmain) { ID *id_iter; @@ -278,7 +277,6 @@ static int main_relations_create_idlink_cb(LibraryIDLinkCallbackData *cb_data) return IDWALK_RET_NOP; } -/** Generate the mappings between used IDs and their users, and vice-versa. */ void BKE_main_relations_create(Main *bmain, const short flag) { if (bmain->relations != NULL) { @@ -326,7 +324,6 @@ void BKE_main_relations_free(Main *bmain) } } -/** Set or clear given `tag` in all relation entries of given `bmain`. */ void BKE_main_relations_tag_set(struct Main *bmain, const eMainIDRelationsEntryTags tag, const bool value) @@ -350,12 +347,6 @@ void BKE_main_relations_tag_set(struct Main *bmain, BLI_ghashIterator_free(gh_iter); } -/** - * Create a GSet storing all IDs present in given \a bmain, by their pointers. - * - * \param gset: If not NULL, given GSet will be extended with IDs from given \a bmain, - * instead of creating a new one. - */ GSet *BKE_main_gset_create(Main *bmain, GSet *gset) { if (gset == NULL) { @@ -404,12 +395,6 @@ static bool lib_weak_key_cmp(const void *a, const void *b) STREQ(string_pair_a->id_name, string_pair_b->id_name)); } -/** - * Generate a mapping between 'library path' of an ID (as a pair (relative blend file path, id - * name)), and a current local ID, if any. - * - * This uses the information stored in `ID.library_weak_reference`. - */ GHash *BKE_main_library_weak_reference_create(Main *bmain) { GHash *library_weak_reference_mapping = BLI_ghash_new( @@ -442,24 +427,11 @@ GHash *BKE_main_library_weak_reference_create(Main *bmain) return library_weak_reference_mapping; } -/** - * Destroy the data generated by #BKE_main_library_weak_reference_create. - */ void BKE_main_library_weak_reference_destroy(GHash *library_weak_reference_mapping) { BLI_ghash_free(library_weak_reference_mapping, MEM_freeN, NULL); } -/** - * Search for a local ID matching the given linked ID reference. - * - * \param library_weak_reference_mapping: the mapping data generated by - * #BKE_main_library_weak_reference_create. - * \param library_relative_path: the path of a blend file library (relative to current working - * one). - * \param library_id_name: the full ID name, including the leading two chars encoding the ID - * type. - */ ID *BKE_main_library_weak_reference_search_item(GHash *library_weak_reference_mapping, const char *library_filepath, const char *library_id_name) @@ -469,16 +441,6 @@ ID *BKE_main_library_weak_reference_search_item(GHash *library_weak_reference_ma return (ID *)BLI_ghash_lookup(library_weak_reference_mapping, &key); } -/** - * Add the given ID weak library reference to given local ID and the runtime mapping. - * - * \param library_weak_reference_mapping: the mapping data generated by - * #BKE_main_library_weak_reference_create. - * \param library_relative_path: the path of a blend file library (relative to current working - * one). - * \param library_id_name: the full ID name, including the leading two chars encoding the ID type. - * \param new_id: New local ID matching given weak reference. - */ void BKE_main_library_weak_reference_add_item(GHash *library_weak_reference_mapping, const char *library_filepath, const char *library_id_name, @@ -507,21 +469,6 @@ void BKE_main_library_weak_reference_add_item(GHash *library_weak_reference_mapp *id_p = new_id; } -/** - * Update the status of the given ID weak library reference in current local IDs and the runtime - * mapping. - * - * This effectively transfers the 'ownership' of the given weak reference from `old_id` to - * `new_id`. - * - * \param library_weak_reference_mapping: the mapping data generated by - * #BKE_main_library_weak_reference_create. - * \param library_relative_path: the path of a blend file library (relative to current working - * one). - * \param library_id_name: the full ID name, including the leading two chars encoding the ID type. - * \param old_id: Existing local ID matching given weak reference. - * \param new_id: New local ID matching given weak reference. - */ void BKE_main_library_weak_reference_update_item(GHash *library_weak_reference_mapping, const char *library_filepath, const char *library_id_name, @@ -545,16 +492,6 @@ void BKE_main_library_weak_reference_update_item(GHash *library_weak_reference_m *id_p = new_id; } -/** - * Remove the given ID weak library reference from the given local ID and the runtime mapping. - * - * \param library_weak_reference_mapping: the mapping data generated by - * #BKE_main_library_weak_reference_create. - * \param library_relative_path: the path of a blend file library (relative to current working - * one). - * \param library_id_name: the full ID name, including the leading two chars encoding the ID type. - * \param old_id: Existing local ID matching given weak reference. - */ void BKE_main_library_weak_reference_remove_item(GHash *library_weak_reference_mapping, const char *library_filepath, const char *library_id_name, @@ -572,13 +509,6 @@ void BKE_main_library_weak_reference_remove_item(GHash *library_weak_reference_m MEM_SAFE_FREE(old_id->library_weak_reference); } -/** - * Generates a raw .blend file thumbnail data from given image. - * - * \param bmain: If not NULL, also store generated data in this Main. - * \param img: ImBuf image to generate thumbnail data from. - * \return The generated .blend file raw thumbnail data. - */ BlendThumbnail *BKE_main_thumbnail_from_imbuf(Main *bmain, ImBuf *img) { BlendThumbnail *data = NULL; @@ -603,13 +533,6 @@ BlendThumbnail *BKE_main_thumbnail_from_imbuf(Main *bmain, ImBuf *img) return data; } -/** - * Generates an image from raw .blend file thumbnail \a data. - * - * \param bmain: Use this bmain->blen_thumb data if given \a data is NULL. - * \param data: Raw .blend file thumbnail data. - * \return An ImBuf from given data, or NULL if invalid. - */ ImBuf *BKE_main_thumbnail_to_imbuf(Main *bmain, BlendThumbnail *data) { ImBuf *img = NULL; @@ -626,9 +549,6 @@ ImBuf *BKE_main_thumbnail_to_imbuf(Main *bmain, BlendThumbnail *data) return img; } -/** - * Generates an empty (black) thumbnail for given Main. - */ void BKE_main_thumbnail_create(struct Main *bmain) { MEM_SAFE_FREE(bmain->blen_thumb); @@ -638,28 +558,16 @@ void BKE_main_thumbnail_create(struct Main *bmain) bmain->blen_thumb->height = BLEN_THUMB_SIZE; } -/** - * Return filepath of given \a main. - */ const char *BKE_main_blendfile_path(const Main *bmain) { return bmain->name; } -/** - * Return filepath of global main #G_MAIN. - * - * \warning Usage is not recommended, - * you should always try to get a valid Main pointer from context... - */ const char *BKE_main_blendfile_path_from_global(void) { return BKE_main_blendfile_path(G_MAIN); } -/** - * \return A pointer to the \a ListBase of given \a bmain for requested \a type ID type. - */ ListBase *which_libbase(Main *bmain, short type) { switch ((ID_Type)type) { @@ -747,18 +655,6 @@ ListBase *which_libbase(Main *bmain, short type) return NULL; } -/** - * Put the pointers to all the #ListBase structs in given `bmain` into the `*lb[INDEX_ID_MAX]` - * array, and return the number of those for convenience. - * - * This is useful for generic traversal of all the blocks in a #Main (by traversing all the lists - * in turn), without worrying about block types. - * - * \param lb: Array of lists #INDEX_ID_MAX in length. - * - * \note The order of each ID type #ListBase in the array is determined by the `INDEX_ID_` - * enum definitions in `DNA_ID.h`. See also the #FOREACH_MAIN_ID_BEGIN macro in `BKE_main.h` - */ int set_listbasepointers(Main *bmain, ListBase *lb[/*INDEX_ID_MAX*/]) { /* Libraries may be accessed from pretty much any other ID. */ diff --git a/source/blender/blenkernel/intern/main_idmap.c b/source/blender/blenkernel/intern/main_idmap.c index c75365a788d..38523f22aad 100644 --- a/source/blender/blenkernel/intern/main_idmap.c +++ b/source/blender/blenkernel/intern/main_idmap.c @@ -88,18 +88,6 @@ static struct IDNameLib_TypeMap *main_idmap_from_idcode(struct IDNameLib_Map *id return NULL; } -/** - * Generate mapping from ID type/name to ID pointer for given \a bmain. - * - * \note When used during undo/redo, there is no guaranty that ID pointers from UI area - * are not pointing to freed memory (when some IDs have been deleted). To avoid crashes - * in those cases, one can provide the 'old' (aka current) Main database as reference. - * #BKE_main_idmap_lookup_id will then check that given ID does exist in \a old_bmain - * before trying to use it. - * - * \param create_valid_ids_set: If \a true, generate a reference to prevent freed memory accesses. - * \param old_bmain: If not NULL, its IDs will be added the valid references set. - */ struct IDNameLib_Map *BKE_main_idmap_create(struct Main *bmain, const bool create_valid_ids_set, struct Main *old_bmain, diff --git a/source/blender/blenkernel/intern/mask.c b/source/blender/blenkernel/intern/mask.c index 7b916cb1aae..6f498c5c9e7 100644 --- a/source/blender/blenkernel/intern/mask.c +++ b/source/blender/blenkernel/intern/mask.c @@ -373,7 +373,6 @@ MaskLayer *BKE_mask_layer_new(Mask *mask, const char *name) return masklay; } -/* NOTE: may still be hidden, caller needs to check. */ MaskLayer *BKE_mask_layer_active(Mask *mask) { return BLI_findlink(&mask->masklayers, mask->masklay_act); @@ -789,12 +788,11 @@ BLI_INLINE void orthogonal_direction_get(const float vec[2], float result[2]) normalize_v2(result); } -/* TODO(sergey): This function will re-calculate loads of stuff again and again - * when differentiating feather points. This might be easily cached - * in the callee function for this case. - */ void BKE_mask_point_normal(MaskSpline *spline, MaskSplinePoint *point, float u, float n[2]) { + /* TODO(sergey): This function will re-calculate loads of stuff again and again + * when differentiating feather points. This might be easily cached + * in the callee function for this case. */ MaskSplinePoint *point_prev, *point_next; @@ -1134,7 +1132,6 @@ MaskSpline *BKE_mask_spline_copy(const MaskSpline *spline) return nspline; } -/* NOTE: Does NOT add to the list. */ MaskLayerShape *BKE_mask_layer_shape_alloc(MaskLayer *masklay, const int frame) { MaskLayerShape *masklay_shape; @@ -1158,8 +1155,6 @@ void BKE_mask_layer_shape_free(MaskLayerShape *masklay_shape) MEM_freeN(masklay_shape); } -/** \brief Free all animation keys for a mask layer - */ void BKE_mask_layer_free_shapes(MaskLayer *masklay) { MaskLayerShape *masklay_shape; @@ -1247,7 +1242,6 @@ void BKE_mask_coord_from_image(Image *image, ImageUser *iuser, float r_co[2], co BKE_mask_coord_from_frame(r_co, co, frame_size); } -/* as above but divide */ void BKE_mask_coord_to_frame(float r_co[2], const float co[2], const float frame_size[2]) { if (frame_size[0] == frame_size[1]) { @@ -1430,8 +1424,6 @@ void BKE_mask_get_handle_point_adjacent(MaskSpline *spline, *r_point_next = mask_spline_point_next(spline, points_array, point); } -/* calculates the tangent of a point by its previous and next - * (ignoring handles - as if its a poly line) */ void BKE_mask_calc_tangent_polyline(MaskSpline *spline, MaskSplinePoint *point, float t[2]) { float tvec_a[2], tvec_b[2]; @@ -1515,11 +1507,6 @@ void BKE_mask_calc_handle_adjacent_interp(MaskSpline *spline, } } -/** - * \brief Resets auto handles even for non-auto bezier points - * - * Useful for giving sane defaults. - */ void BKE_mask_calc_handle_point_auto(MaskSpline *spline, MaskSplinePoint *point, const bool do_recalc_length) @@ -1642,7 +1629,6 @@ static void mask_layer_shape_to_mask_point(BezTriple *bezt, bezt->radius = fp[7]; } -/* these functions match. copy is swapped */ void BKE_mask_layer_shape_from_mask(MaskLayer *masklay, MaskLayerShape *masklay_shape) { int tot = BKE_mask_layer_shape_totvert(masklay); @@ -1698,7 +1684,6 @@ BLI_INLINE void interp_v2_v2v2_flfl( target[1] = s * a[1] + t * b[1]; } -/* linear interpolation only */ void BKE_mask_layer_shape_to_mask_interp(MaskLayer *masklay, MaskLayerShape *masklay_shape_a, MaskLayerShape *masklay_shape_b, @@ -1759,9 +1744,6 @@ MaskLayerShape *BKE_mask_layer_shape_find_frame(MaskLayer *masklay, const int fr return NULL; } -/** - * When returning 2 - the frame isn't found but before/after frames are. - */ int BKE_mask_layer_shape_find_frame_range(MaskLayer *masklay, const float frame, MaskLayerShape **r_masklay_shape_a, @@ -1924,7 +1906,6 @@ static void interp_weights_uv_v2_apply(const float uv[2], r_pt[1] += dvec[0] * uv[1]; } -/* When a new points added - resize all shape-key array. */ void BKE_mask_layer_shape_changed_add(MaskLayer *masklay, int index, bool do_init, @@ -2019,7 +2000,6 @@ void BKE_mask_layer_shape_changed_add(MaskLayer *masklay, } } -/* move array to account for removed point */ void BKE_mask_layer_shape_changed_remove(MaskLayer *masklay, int index, int count) { MaskLayerShape *masklay_shape; @@ -2081,13 +2061,11 @@ static void mask_clipboard_free_ex(bool final_free) } } -/* Free the clipboard. */ void BKE_mask_clipboard_free(void) { mask_clipboard_free_ex(true); } -/* Copy selected visible splines from the given layer to clipboard. */ void BKE_mask_clipboard_copy_from_layer(MaskLayer *mask_layer) { MaskSpline *spline; @@ -2122,13 +2100,11 @@ void BKE_mask_clipboard_copy_from_layer(MaskLayer *mask_layer) } } -/* Check clipboard is empty. */ bool BKE_mask_clipboard_is_empty(void) { return BLI_listbase_is_empty(&mask_clipboard.splines); } -/* Paste the contents of clipboard to given mask layer */ void BKE_mask_clipboard_paste_to_layer(Main *bmain, MaskLayer *mask_layer) { MaskSpline *spline; diff --git a/source/blender/blenkernel/intern/mask_evaluate.c b/source/blender/blenkernel/intern/mask_evaluate.c index 4584d9e527e..69fc7554eed 100644 --- a/source/blender/blenkernel/intern/mask_evaluate.c +++ b/source/blender/blenkernel/intern/mask_evaluate.c @@ -720,10 +720,6 @@ static float (*mask_spline_feather_differentiated_points_with_resolution__double return feather; } -/** - * values align with #BKE_mask_spline_differentiate_with_resolution - * when \a resol arguments match. - */ float (*BKE_mask_spline_feather_differentiated_points_with_resolution( MaskSpline *spline, const unsigned int resol, @@ -788,7 +784,6 @@ float (*BKE_mask_spline_feather_points(MaskSpline *spline, int *r_tot_feather_po return feather; } -/* *** mask point functions which involve evaluation *** */ float *BKE_mask_point_segment_feather_diff(MaskSpline *spline, MaskSplinePoint *point, int width, diff --git a/source/blender/blenkernel/intern/mask_rasterize.c b/source/blender/blenkernel/intern/mask_rasterize.c index 0c40a1b5078..b0876957620 100644 --- a/source/blender/blenkernel/intern/mask_rasterize.c +++ b/source/blender/blenkernel/intern/mask_rasterize.c @@ -1474,9 +1474,6 @@ static void maskrasterize_buffer_cb(void *__restrict userdata, } } -/** - * \brief Rasterize a buffer from a single mask (threaded execution). - */ void BKE_maskrasterize_buffer(MaskRasterHandle *mr_handle, const unsigned int width, const unsigned int height, diff --git a/source/blender/blenkernel/intern/material.c b/source/blender/blenkernel/intern/material.c index 42009267f49..d6035887790 100644 --- a/source/blender/blenkernel/intern/material.c +++ b/source/blender/blenkernel/intern/material.c @@ -389,7 +389,6 @@ short *BKE_object_material_len_p(Object *ob) return NULL; } -/* same as above but for ID's */ Material ***BKE_id_material_array_p(ID *id) { /* ensure we don't try get materials from non-obdata */ @@ -728,13 +727,6 @@ static ID *get_evaluated_object_data_with_materials(Object *ob) return data; } -/** - * On evaluated objects the number of materials on an object and its data might go out of sync. - * This is because during evaluation materials can be added/removed on the object data. - * - * For rendering or exporting we generally use the materials on the object data. However, some - * material indices might be overwritten by the object. - */ Material *BKE_object_material_get_eval(Object *ob, short act) { BLI_assert(DEG_is_evaluated_object(ob)); @@ -808,10 +800,6 @@ void BKE_id_material_eval_assign(ID *id, int slot, Material *material) (*materials_ptr)[slot_index] = material; } -/** - * Add an empty material slot if the id has no material slots. This material slot allows the - * material to be overwritten by object-linked materials. - */ void BKE_id_material_eval_ensure_default_slot(ID *id) { short *len_ptr = BKE_id_material_len_p(id); @@ -1101,12 +1089,6 @@ void BKE_object_material_remap(Object *ob, const unsigned int *remap) } } -/** - * Calculate a material remapping from \a ob_src to \a ob_dst. - * - * \param remap_src_to_dst: An array the size of `ob_src->totcol` - * where index values are filled in which map to \a ob_dst materials. - */ void BKE_object_material_remap_calc(Object *ob_dst, Object *ob_src, short *remap_src_to_dst) { if (ob_src->totcol == 0) { @@ -1155,9 +1137,6 @@ void BKE_object_material_remap_calc(Object *ob_dst, Object *ob_src, short *remap BLI_ghash_free(gh_mat_map, NULL, NULL); } -/** - * Copy materials from evaluated geometry to the original geometry of an object. - */ void BKE_object_material_from_eval_data(Main *bmain, Object *ob_orig, ID *data_eval) { ID *data_orig = ob_orig->data; @@ -1192,7 +1171,6 @@ void BKE_object_material_from_eval_data(Main *bmain, Object *ob_orig, ID *data_e BKE_object_materials_test(bmain, ob_orig, data_orig); } -/* XXX: this calls many more update calls per object then are needed, could be optimized. */ void BKE_object_material_array_assign(Main *bmain, struct Object *ob, struct Material ***matar, @@ -1555,7 +1533,6 @@ bNode *BKE_texpaint_slot_material_find_node(Material *ma, short texpaint_slot) return find_data.r_node; } -/* r_col = current value, col = new value, (fac == 0) is no change */ void ramp_blend(int type, float r_col[3], const float fac, const float col[3]) { float tmp, facm = 1.0f - fac; diff --git a/source/blender/blenkernel/intern/mball.c b/source/blender/blenkernel/intern/mball.c index e3eaac800fa..ac6b0a04def 100644 --- a/source/blender/blenkernel/intern/mball.c +++ b/source/blender/blenkernel/intern/mball.c @@ -221,8 +221,6 @@ MetaBall *BKE_mball_add(Main *bmain, const char *name) return mb; } -/* most simple meta-element adding function - * don't do context manipulation here (rna uses) */ MetaElem *BKE_mball_element_add(MetaBall *mb, const int type) { MetaElem *ml = MEM_callocN(sizeof(MetaElem), "metaelem"); @@ -269,13 +267,6 @@ MetaElem *BKE_mball_element_add(MetaBall *mb, const int type) return ml; } -/** - * Compute bounding box of all #MetaElem / #MetaBall - * - * Bounding box is computed from polygonized surface. \a ob is - * basic meta-balls (with name `Meta` for example). All other meta-ball objects - * (with names `Meta.001`, `Meta.002`, etc) are included in this bounding-box. - */ void BKE_mball_texspace_calc(Object *ob) { DispList *dl; @@ -319,7 +310,6 @@ void BKE_mball_texspace_calc(Object *ob) bb->flag &= ~BOUNDBOX_DIRTY; } -/** Return or compute bbox for given metaball object. */ BoundBox *BKE_mball_boundbox_get(Object *ob) { BLI_assert(ob->type == OB_MBALL); @@ -372,38 +362,29 @@ float *BKE_mball_make_orco(Object *ob, ListBase *dispbase) return orcodata; } -/** - * \brief Test, if \a ob is a basis meta-ball. - * - * It test last character of Object ID name. If last character - * is digit it return 0, else it return 1. - * - * - * Meta-Ball Basis Notes from Blender-2.5x - * ======================================= - * - * This is a can of worms. - * - * This really needs a rewrite/refactor its totally broken in anything other than basic cases - * Multiple Scenes + Set Scenes & mixing meta-ball basis _should_ work but fails to update the - * depsgraph on rename and linking into scenes or removal of basis meta-ball. - * So take care when changing this code. - * - * Main idiot thing here is that the system returns #BKE_mball_basis_find() - * objects which fail a #BKE_mball_is_basis() test. - * - * Not only that but the depsgraph and their areas depend on this behavior, - * so making small fixes here isn't worth it. - * - Campbell - */ bool BKE_mball_is_basis(Object *ob) { - /* just a quick test */ + /* Meta-Ball Basis Notes from Blender-2.5x + * ======================================= + * + * NOTE(@campbellbarton): This is a can of worms. + * + * This really needs a rewrite/refactor its totally broken in anything other than basic cases + * Multiple Scenes + Set Scenes & mixing meta-ball basis _should_ work but fails to update the + * depsgraph on rename and linking into scenes or removal of basis meta-ball. + * So take care when changing this code. + * + * Main idiot thing here is that the system returns #BKE_mball_basis_find() + * objects which fail a #BKE_mball_is_basis() test. + * + * Not only that but the depsgraph and their areas depend on this behavior, + * so making small fixes here isn't worth it. */ + + /* Just a quick test. */ const int len = strlen(ob->id.name); return (!isdigit(ob->id.name[len - 1])); } -/* return nonzero if ob1 is a basis mball for ob */ bool BKE_mball_is_basis_for(Object *ob1, Object *ob2) { int basis1nr, basis2nr; @@ -456,13 +437,6 @@ bool BKE_mball_is_any_unselected(const MetaBall *mb) return false; } -/** - * \brief copy some properties from object to other meta-ball object with same base name - * - * When some properties (wire-size, threshold, update flags) of meta-ball are changed, then this - * properties are copied to all meta-balls in same "group" (meta-balls with same base name: - * `MBall`, `MBall.001`, `MBall.002`, etc). The most important is to copy properties to the base - * meta-ball, because this meta-ball influence polygonization of meta-balls. */ void BKE_mball_properties_copy(Scene *scene, Object *active_object) { Scene *sce_iter = scene; @@ -501,14 +475,6 @@ void BKE_mball_properties_copy(Scene *scene, Object *active_object) } } -/** \brief This function finds the basis MetaBall. - * - * Basis meta-ball doesn't include any number at the end of - * its name. All meta-balls with same base of name can be - * blended. meta-balls with different basic name can't be blended. - * - * \warning #BKE_mball_is_basis() can fail on returned object, see function docs for details. - */ Object *BKE_mball_basis_find(Scene *scene, Object *object) { Object *bob = object; @@ -573,7 +539,6 @@ bool BKE_mball_minmax_ex( return changed; } -/* basic vertex data functions */ bool BKE_mball_minmax(const MetaBall *mb, float min[3], float max[3]) { INIT_MINMAX(min, max); @@ -648,7 +613,6 @@ void BKE_mball_translate(MetaBall *mb, const float offset[3]) } } -/* *** select funcs *** */ int BKE_mball_select_count(const MetaBall *mb) { int sel = 0; diff --git a/source/blender/blenkernel/intern/mesh.cc b/source/blender/blenkernel/intern/mesh.cc index c367602f037..5f8d4ccb734 100644 --- a/source/blender/blenkernel/intern/mesh.cc +++ b/source/blender/blenkernel/intern/mesh.cc @@ -690,12 +690,6 @@ static int customdata_compare( return 0; } -/** - * Used for unit testing; compares two meshes, checking only - * differences we care about. should be usable with leaf's - * testing framework I get RNA work done, will use hackish - * testing code for now. - */ const char *BKE_mesh_cmp(Mesh *me1, Mesh *me2, float thresh) { int c; @@ -896,10 +890,6 @@ bool BKE_mesh_has_custom_loop_normals(Mesh *me) return CustomData_has_layer(&me->ldata, CD_CUSTOMLOOPNORMAL); } -/** - * Free (or release) any data used by this mesh (does not free the mesh itself). - * Only use for undo, in most cases `BKE_id_free(nullptr, me)` should be used. - */ void BKE_mesh_free_data_for_undo(Mesh *me) { mesh_free_data(&me->id); @@ -1014,10 +1004,6 @@ Mesh *BKE_mesh_new_nomain( return mesh; } -/** - * Copy user editable settings that we want to preserve - * when a new mesh is based on an existing mesh. - */ void BKE_mesh_copy_parameters(Mesh *me_dst, const Mesh *me_src) { /* Copy general settings. */ @@ -1040,12 +1026,6 @@ void BKE_mesh_copy_parameters(Mesh *me_dst, const Mesh *me_src) me_dst->vertex_group_active_index = me_src->vertex_group_active_index; } -/** - * A version of #BKE_mesh_copy_parameters that is intended for evaluated output - * (the modifier stack for example). - * - * \warning User counts are not handled for ID's. - */ void BKE_mesh_copy_parameters_for_eval(Mesh *me_dst, const Mesh *me_src) { /* User counts aren't handled, don't copy into a mesh from #G_MAIN. */ @@ -1344,10 +1324,6 @@ void BKE_mesh_orco_ensure(Object *ob, Mesh *mesh) CustomData_add_layer(&mesh->vdata, CD_ORCO, CD_ASSIGN, orcodata, mesh->totvert); } -/** - * Rotates the vertices of a face in case v[2] or v[3] (vertex index) is = 0. - * this is necessary to make the if #MFace.v4 check for quads work. - */ int BKE_mesh_mface_index_validate(MFace *mface, CustomData *fdata, int mfindex, int nr) { /* first test if the face is legal */ @@ -1551,10 +1527,6 @@ void BKE_mesh_smooth_flag_set(Mesh *me, const bool use_smooth) } } -/** - * Find the index of the loop in 'poly' which references vertex, - * returns -1 if not found - */ int poly_find_loop_from_vert(const MPoly *poly, const MLoop *loopstart, uint vert) { for (int j = 0; j < poly->totloop; j++, loopstart++) { @@ -1566,11 +1538,6 @@ int poly_find_loop_from_vert(const MPoly *poly, const MLoop *loopstart, uint ver return -1; } -/** - * Fill \a r_adj with the loop indices in \a poly adjacent to the - * vertex. Returns the index of the loop matching vertex, or -1 if the - * vertex is not in \a poly - */ int poly_get_adj_loops_from_vert(const MPoly *poly, const MLoop *mloop, uint vert, uint r_adj[2]) { int corner = poly_find_loop_from_vert(poly, &mloop[poly->loopstart], vert); @@ -1584,10 +1551,6 @@ int poly_get_adj_loops_from_vert(const MPoly *poly, const MLoop *mloop, uint ver return corner; } -/** - * Return the index of the edge vert that is not equal to \a v. If - * neither edge vertex is equal to \a v, returns -1. - */ int BKE_mesh_edge_other_vert(const MEdge *e, int v) { if (e->v1 == v) { @@ -1600,9 +1563,6 @@ int BKE_mesh_edge_other_vert(const MEdge *e, int v) return -1; } -/** - * Sets each output array element to the edge index if it is a real edge, or -1. - */ void BKE_mesh_looptri_get_real_edges(const Mesh *mesh, const MLoopTri *looptri, int r_edges[3]) { for (int i = 2, i_next = 0; i_next < 3; i = i_next++) { @@ -1615,7 +1575,6 @@ void BKE_mesh_looptri_get_real_edges(const Mesh *mesh, const MLoopTri *looptri, } } -/* basic vertex data functions */ bool BKE_mesh_minmax(const Mesh *me, float r_min[3], float r_max[3]) { int i = me->totvert; @@ -1797,9 +1756,6 @@ void BKE_mesh_mselect_validate(Mesh *me) me->mselect = mselect_dst; } -/** - * Return the index within me->mselect, or -1 - */ int BKE_mesh_mselect_find(Mesh *me, int index, int type) { BLI_assert(ELEM(type, ME_VSEL, ME_ESEL, ME_FSEL)); @@ -1813,9 +1769,6 @@ int BKE_mesh_mselect_find(Mesh *me, int index, int type) return -1; } -/** - * Return The index of the active element. - */ int BKE_mesh_mselect_active_get(Mesh *me, int type) { BLI_assert(ELEM(type, ME_VSEL, ME_ESEL, ME_FSEL)); @@ -1916,13 +1869,6 @@ void BKE_mesh_vert_normals_apply(Mesh *mesh, const short (*vert_normals)[3]) mesh->runtime.cd_dirty_vert &= ~CD_MASK_NORMAL; } -/** - * Compute 'split' (aka loop, or per face corner's) normals. - * - * \param r_lnors_spacearr: Allows to get computed loop normal space array. - * That data, among other things, contains 'smooth fan' info, useful e.g. - * to split geometry along sharp edges... - */ void BKE_mesh_calc_normals_split_ex(Mesh *mesh, MLoopNorSpaceArray *r_lnors_spacearr) { float(*r_loopnors)[3]; @@ -2198,12 +2144,6 @@ static void split_faces_split_new_edges(Mesh *mesh, } } -/* Split faces based on the edge angle and loop normals. - * Matches behavior of face splitting in render engines. - * - * NOTE: Will leave CD_NORMAL loop data layer which is - * used by render engines to set shading up. - */ void BKE_mesh_split_faces(Mesh *mesh, bool free_loop_normals) { const int num_polys = mesh->totpoly; diff --git a/source/blender/blenkernel/intern/mesh_boolean_convert.cc b/source/blender/blenkernel/intern/mesh_boolean_convert.cc index 3086f117707..771d79a0445 100644 --- a/source/blender/blenkernel/intern/mesh_boolean_convert.cc +++ b/source/blender/blenkernel/intern/mesh_boolean_convert.cc @@ -807,16 +807,6 @@ static Mesh *imesh_to_mesh(IMesh *im, MeshesToIMeshInfo &mim) #endif // WITH_GMP -/** - * Do a mesh boolean operation directly on meshes (without going back and forth to BMesh). - * \param meshes: An array of Mesh pointers. - * \param obmats: An array of pointers to the obmat matrices that transform local - * coordinates to global ones. It is allowed for the pointers to be null, meaning the - * transformation is the identity. - * \param material_remaps: An array of pointers to arrays of maps from material slot numbers in the - * corresponding mesh to the material slot in the first mesh. It is OK for material_remaps or any - * of its constituent arrays to be empty. - */ Mesh *direct_mesh_boolean(Span meshes, Span obmats, const float4x4 &target_transform, diff --git a/source/blender/blenkernel/intern/mesh_convert.cc b/source/blender/blenkernel/intern/mesh_convert.cc index 1769be54211..e8054884f26 100644 --- a/source/blender/blenkernel/intern/mesh_convert.cc +++ b/source/blender/blenkernel/intern/mesh_convert.cc @@ -1277,11 +1277,6 @@ static void add_shapekey_layers(Mesh *mesh_dest, Mesh *mesh_src) } } -/** - * \param use_virtual_modifiers: When enabled calculate virtual-modifiers before applying `md_eval` - * support this since virtual-modifiers are not modifiers from a user perspective, - * allowing shape keys to be included with the modifier being applied, see: T91923. - */ Mesh *BKE_mesh_create_derived_for_modifier(struct Depsgraph *depsgraph, Scene *scene, Object *ob_eval, diff --git a/source/blender/blenkernel/intern/mesh_evaluate.cc b/source/blender/blenkernel/intern/mesh_evaluate.cc index 91fd022a316..e79c9646ea4 100644 --- a/source/blender/blenkernel/intern/mesh_evaluate.cc +++ b/source/blender/blenkernel/intern/mesh_evaluate.cc @@ -191,7 +191,6 @@ void BKE_mesh_calc_poly_center(const MPoly *mpoly, } } -/* NOTE: passing poly-normal is only a speedup so we can skip calculating it. */ float BKE_mesh_calc_poly_area(const MPoly *mpoly, const MLoop *loopstart, const MVert *mvarray) { if (mpoly->totloop == 3) { @@ -249,23 +248,6 @@ float BKE_mesh_calc_poly_uv_area(const MPoly *mpoly, const MLoopUV *uv_array) return area; } -/** - * Calculate the volume and volume-weighted centroid of the volume - * formed by the polygon and the origin. - * Results will be negative if the origin is "outside" the polygon - * (+ve normal side), but the polygon may be non-planar with no effect. - * - * Method from: - * - http://forums.cgsociety.org/archive/index.php?t-756235.html - * - http://www.globalspec.com/reference/52702/203279/4-8-the-centroid-of-a-tetrahedron - * - * \note - * - Volume is 6x actual volume, and centroid is 4x actual volume-weighted centroid - * (so division can be done once at the end). - * - Results will have bias if polygon is non-planar. - * - The resulting volume will only be correct if the mesh is manifold and has consistent - * face winding (non-contiguous face normals or holes in the mesh surface). - */ static float UNUSED_FUNCTION(mesh_calc_poly_volume_centroid)(const MPoly *mpoly, const MLoop *loopstart, const MVert *mvarray, @@ -445,10 +427,6 @@ bool BKE_mesh_center_median(const Mesh *me, float r_cent[3]) return (me->totvert != 0); } -/** - * Calculate the center from polygons, - * use when we want to ignore vertex locations that don't have connected faces. - */ bool BKE_mesh_center_median_from_polys(const Mesh *me, float r_cent[3]) { int i = me->totpoly; @@ -514,10 +492,6 @@ bool BKE_mesh_center_of_surface(const Mesh *me, float r_cent[3]) return (me->totpoly != 0); } -/** - * \note Mesh must be manifold with consistent face-winding, - * see #mesh_calc_poly_volume_centroid for details. - */ bool BKE_mesh_center_of_volume(const Mesh *me, float r_cent[3]) { int i = me->totpoly; @@ -602,12 +576,6 @@ static bool mesh_calc_center_centroid_ex(const MVert *mverts, return true; } -/** - * Calculate the volume and center. - * - * \param r_volume: Volume (unsigned). - * \param r_center: Center of mass. - */ void BKE_mesh_calc_volume(const MVert *mverts, const int mverts_num, const MLoopTri *looptri, @@ -800,19 +768,6 @@ void BKE_mesh_convert_mfaces_to_mpolys(Mesh *mesh) BKE_mesh_update_customdata_pointers(mesh, true); } -/** - * The same as #BKE_mesh_convert_mfaces_to_mpolys - * but oriented to be used in #do_versions from `readfile.c` - * the difference is how active/render/clone/stencil indices are handled here. - * - * normally they're being set from `pdata` which totally makes sense for meshes which are already - * converted to #BMesh structures, but when loading older files indices shall be updated in other - * way around, so newly added `pdata` and `ldata` would have this indices set - * based on `fdata` layer. - * - * this is normally only needed when reading older files, - * in all other cases #BKE_mesh_convert_mfaces_to_mpolys shall be always used. - */ void BKE_mesh_do_versions_convert_mfaces_to_mpolys(Mesh *mesh) { BKE_mesh_convert_mfaces_to_mpolys_ex(&mesh->id, @@ -959,10 +914,6 @@ void BKE_mesh_convert_mfaces_to_mpolys_ex(ID *id, } /** \} */ -/** - * Flip a single MLoop's #MDisps structure, - * low level function to be called from face-flipping code which re-arranged the mdisps themselves. - */ void BKE_mesh_mdisp_flip(MDisps *md, const bool use_loop_mdisp_flip) { if (UNLIKELY(!md->totdisp || !md->disps)) { @@ -999,14 +950,6 @@ void BKE_mesh_mdisp_flip(MDisps *md, const bool use_loop_mdisp_flip) } } -/** - * Flip (invert winding of) the given \a mpoly, i.e. reverse order of its loops - * (keeping the same vertex as 'start point'). - * - * \param mpoly: the polygon to flip. - * \param mloop: the full loops array. - * \param ldata: the loops custom data. - */ void BKE_mesh_polygon_flip_ex(MPoly *mpoly, MLoop *mloop, CustomData *ldata, @@ -1056,11 +999,6 @@ void BKE_mesh_polygon_flip(MPoly *mpoly, MLoop *mloop, CustomData *ldata) BKE_mesh_polygon_flip_ex(mpoly, mloop, ldata, nullptr, mdisp, true); } -/** - * Flip (invert winding of) all polygons (used to inverse their normals). - * - * \note Invalidates tessellation, caller must handle that. - */ void BKE_mesh_polygons_flip(MPoly *mpoly, MLoop *mloop, CustomData *ldata, int totpoly) { MDisps *mdisp = (MDisps *)CustomData_get_layer(ldata, CD_MDISPS); @@ -1076,8 +1014,6 @@ void BKE_mesh_polygons_flip(MPoly *mpoly, MLoop *mloop, CustomData *ldata, int t /** \name Mesh Flag Flushing * \{ */ -/* update the hide flag for edges and faces from the corresponding - * flag in verts */ void BKE_mesh_flush_hidden_from_verts_ex(const MVert *mvert, const MLoop *mloop, MEdge *medge, @@ -1149,9 +1085,6 @@ void BKE_mesh_flush_hidden_from_polys(Mesh *me) me->mvert, me->mloop, me->medge, me->totedge, me->mpoly, me->totpoly); } -/** - * simple poly -> vert/edge selection. - */ void BKE_mesh_flush_select_from_polys_ex(MVert *mvert, const int totvert, const MLoop *mloop, @@ -1254,17 +1187,6 @@ void BKE_mesh_flush_select_from_verts(Mesh *me) /** \name Mesh Spatial Calculation * \{ */ -/** - * This function takes the difference between 2 vertex-coord-arrays - * (\a vert_cos_src, \a vert_cos_dst), - * and applies the difference to \a vert_cos_new relative to \a vert_cos_org. - * - * \param vert_cos_src: reference deform source. - * \param vert_cos_dst: reference deform destination. - * - * \param vert_cos_org: reference for the output location. - * \param vert_cos_new: resulting coords. - */ void BKE_mesh_calc_relative_deform(const MPoly *mpoly, const int totpoly, const MLoop *mloop, diff --git a/source/blender/blenkernel/intern/mesh_iterators.c b/source/blender/blenkernel/intern/mesh_iterators.c index 7a776b0ecb7..3b6afc1f47a 100644 --- a/source/blender/blenkernel/intern/mesh_iterators.c +++ b/source/blender/blenkernel/intern/mesh_iterators.c @@ -34,7 +34,6 @@ #include "MEM_guardedalloc.h" -/* Copied from cdDM_foreachMappedVert */ void BKE_mesh_foreach_mapped_vert(Mesh *mesh, void (*func)(void *userData, int index, @@ -95,11 +94,6 @@ void BKE_mesh_foreach_mapped_vert(Mesh *mesh, } } -/** - * Copied from #cdDM_foreachMappedEdge. - * \param tot_edges: Number of original edges. Used to avoid calling the callback with invalid - * edge indices. - */ void BKE_mesh_foreach_mapped_edge( Mesh *mesh, const int tot_edges, @@ -151,7 +145,6 @@ void BKE_mesh_foreach_mapped_edge( } } -/* Copied from cdDM_foreachMappedLoop */ void BKE_mesh_foreach_mapped_loop(Mesh *mesh, void (*func)(void *userData, int vertex_index, @@ -232,7 +225,6 @@ void BKE_mesh_foreach_mapped_loop(Mesh *mesh, } } -/* Copied from cdDM_foreachMappedFaceCenter */ void BKE_mesh_foreach_mapped_face_center( Mesh *mesh, void (*func)(void *userData, int index, const float cent[3], const float no[3]), @@ -309,7 +301,6 @@ void BKE_mesh_foreach_mapped_face_center( } } -/* Copied from cdDM_foreachMappedFaceCenter */ void BKE_mesh_foreach_mapped_subdiv_face_center( Mesh *mesh, void (*func)(void *userData, int index, const float cent[3], const float no[3]), diff --git a/source/blender/blenkernel/intern/mesh_mapping.c b/source/blender/blenkernel/intern/mesh_mapping.c index b2130bd28b5..f35a44e8b34 100644 --- a/source/blender/blenkernel/intern/mesh_mapping.c +++ b/source/blender/blenkernel/intern/mesh_mapping.c @@ -250,11 +250,6 @@ static void mesh_vert_poly_or_loop_map_create(MeshElemMap **r_map, *r_mem = indices; } -/** - * Generates a map where the key is the vertex and the value - * is a list of polys that use that vertex as a corner. - * The lists are allocated from one memory pool. - */ void BKE_mesh_vert_poly_map_create(MeshElemMap **r_map, int **r_mem, const MPoly *mpoly, @@ -266,11 +261,6 @@ void BKE_mesh_vert_poly_map_create(MeshElemMap **r_map, mesh_vert_poly_or_loop_map_create(r_map, r_mem, mpoly, mloop, totvert, totpoly, totloop, false); } -/** - * Generates a map where the key is the vertex and the value - * is a list of loops that use that vertex as a corner. - * The lists are allocated from one memory pool. - */ void BKE_mesh_vert_loop_map_create(MeshElemMap **r_map, int **r_mem, const MPoly *mpoly, @@ -282,11 +272,6 @@ void BKE_mesh_vert_loop_map_create(MeshElemMap **r_map, mesh_vert_poly_or_loop_map_create(r_map, r_mem, mpoly, mloop, totvert, totpoly, totloop, true); } -/** - * Generates a map where the key is the edge and the value - * is a list of looptris that use that edge. - * The lists are allocated from one memory pool. - */ void BKE_mesh_vert_looptri_map_create(MeshElemMap **r_map, int **r_mem, const MVert *UNUSED(mvert), @@ -331,11 +316,6 @@ void BKE_mesh_vert_looptri_map_create(MeshElemMap **r_map, *r_mem = indices; } -/** - * Generates a map where the key is the vertex and the value - * is a list of edges that use that vertex as an endpoint. - * The lists are allocated from one memory pool. - */ void BKE_mesh_vert_edge_map_create( MeshElemMap **r_map, int **r_mem, const MEdge *medge, int totvert, int totedge) { @@ -375,10 +355,6 @@ void BKE_mesh_vert_edge_map_create( *r_mem = indices; } -/** - * A version of #BKE_mesh_vert_edge_map_create that references connected vertices directly - * (not their edges). - */ void BKE_mesh_vert_edge_vert_map_create( MeshElemMap **r_map, int **r_mem, const MEdge *medge, int totvert, int totedge) { @@ -418,11 +394,6 @@ void BKE_mesh_vert_edge_vert_map_create( *r_mem = indices; } -/** - * Generates a map where the key is the edge and the value is a list of loops that use that edge. - * Loops indices of a same poly are contiguous and in winding order. - * The lists are allocated from one memory pool. - */ void BKE_mesh_edge_loop_map_create(MeshElemMap **r_map, int **r_mem, const MEdge *UNUSED(medge), @@ -476,11 +447,6 @@ void BKE_mesh_edge_loop_map_create(MeshElemMap **r_map, *r_mem = indices; } -/** - * Generates a map where the key is the edge and the value - * is a list of polygons that use that edge. - * The lists are allocated from one memory pool. - */ void BKE_mesh_edge_poly_map_create(MeshElemMap **r_map, int **r_mem, const MEdge *UNUSED(medge), @@ -529,20 +495,6 @@ void BKE_mesh_edge_poly_map_create(MeshElemMap **r_map, *r_mem = indices; } -/** - * This function creates a map so the source-data (vert/edge/loop/poly) - * can loop over the destination data (using the destination arrays origindex). - * - * This has the advantage that it can operate on any data-types. - * - * \param totsource: The total number of elements that \a final_origindex points to. - * \param totfinal: The size of \a final_origindex - * \param final_origindex: The size of the final array. - * - * \note `totsource` could be `totpoly`, - * `totfinal` could be `tottessface` and `final_origindex` its ORIGINDEX custom-data. - * This would allow an MPoly to loop over its tessfaces. - */ void BKE_mesh_origindex_map_create(MeshElemMap **r_map, int **r_mem, const int totsource, @@ -584,10 +536,6 @@ void BKE_mesh_origindex_map_create(MeshElemMap **r_map, *r_mem = indices; } -/** - * A version of #BKE_mesh_origindex_map_create that takes a looptri array. - * Making a poly -> looptri map. - */ void BKE_mesh_origindex_map_create_looptri(MeshElemMap **r_map, int **r_mem, const MPoly *mpoly, @@ -850,14 +798,6 @@ static bool poly_is_island_boundary_smooth_cb(const MPoly *mp, return true; } -/** - * Calculate smooth groups from sharp edges. - * - * \param r_totgroup: The total number of groups, 1 or more. - * \return Polygon aligned array of group index values (bitflags if use_bitflags is true), - * starting at 1 (0 being used as 'invalid' flag). - * Note it's callers's responsibility to MEM_freeN returned array. - */ int *BKE_mesh_calc_smoothgroups(const MEdge *medge, const int totedge, const MPoly *mpoly, @@ -1202,10 +1142,6 @@ static bool mesh_calc_islands_loop_poly_uv(MVert *UNUSED(verts), return true; } -/** - * Calculate 'generic' UV islands, i.e. based only on actual geometry data (edge seams), - * not some UV layers coordinates. - */ bool BKE_mesh_calc_islands_loop_poly_edgeseam(MVert *verts, const int totvert, MEdge *edges, @@ -1220,19 +1156,6 @@ bool BKE_mesh_calc_islands_loop_poly_edgeseam(MVert *verts, verts, totvert, edges, totedge, polys, totpoly, loops, totloop, NULL, r_island_store); } -/** - * Calculate UV islands. - * - * \note If no MLoopUV layer is passed, we only consider edges tagged as seams as UV boundaries. - * This has the advantages of simplicity, and being valid/common to all UV maps. - * However, it means actual UV islands without matching UV seams will not be handled correctly... - * If a valid UV layer is passed as \a luvs parameter, - * UV coordinates are also used to detect islands boundaries. - * - * \note All this could be optimized... - * Not sure it would be worth the more complex code, though, - * those loops are supposed to be really quick to do... - */ bool BKE_mesh_calc_islands_loop_poly_uvmap(MVert *verts, const int totvert, MEdge *edges, diff --git a/source/blender/blenkernel/intern/mesh_merge.c b/source/blender/blenkernel/intern/mesh_merge.c index d3d835378ca..0115a70a52a 100644 --- a/source/blender/blenkernel/intern/mesh_merge.c +++ b/source/blender/blenkernel/intern/mesh_merge.c @@ -204,38 +204,6 @@ static bool poly_gset_compare_fn(const void *k1, const void *k2) return true; } -/** - * Merge Verts - * - * This frees the given mesh and returns a new mesh. - * - * \param vtargetmap: The table that maps vertices to target vertices. a value of -1 - * indicates a vertex is a target, and is to be kept. - * This array is aligned with 'mesh->totvert' - * \warning \a vtargetmap must **not** contain any chained mapping (v1 -> v2 -> v3 etc.), - * this is not supported and will likely generate corrupted geometry. - * - * \param tot_vtargetmap: The number of non '-1' values in vtargetmap. (not the size) - * - * \param merge_mode: enum with two modes. - * - #MESH_MERGE_VERTS_DUMP_IF_MAPPED - * When called by the Mirror Modifier, - * In this mode it skips any faces that have all vertices merged (to avoid creating pairs - * of faces sharing the same set of vertices) - * - #MESH_MERGE_VERTS_DUMP_IF_EQUAL - * When called by the Array Modifier, - * In this mode, faces where all vertices are merged are double-checked, - * to see whether all target vertices actually make up a poly already. - * Indeed it could be that all of a poly's vertices are merged, - * but merged to vertices that do not make up a single poly, - * in which case the original poly should not be dumped. - * Actually this later behavior could apply to the Mirror Modifier as well, - * but the additional checks are costly and not necessary in the case of mirror, - * because each vertex is only merged to its own mirror. - * - * \note #BKE_mesh_tessface_calc_ex has to run on the returned DM - * if you want to access tessfaces. - */ Mesh *BKE_mesh_merge_verts(Mesh *mesh, const int *vtargetmap, const int tot_vtargetmap, diff --git a/source/blender/blenkernel/intern/mesh_mirror.c b/source/blender/blenkernel/intern/mesh_mirror.c index 2756629b440..2d4308945fc 100644 --- a/source/blender/blenkernel/intern/mesh_mirror.c +++ b/source/blender/blenkernel/intern/mesh_mirror.c @@ -130,10 +130,6 @@ void BKE_mesh_mirror_apply_mirror_on_axis(struct Main *bmain, BM_mesh_free(bm); } -/** - * \warning This should _not_ be used to modify original meshes since - * it doesn't handle shape-keys, use #BKE_mesh_mirror_apply_mirror_on_axis instead. - */ Mesh *BKE_mesh_mirror_apply_mirror_on_axis_for_modifier(MirrorModifierData *mmd, Object *ob, const Mesh *mesh, diff --git a/source/blender/blenkernel/intern/mesh_normals.cc b/source/blender/blenkernel/intern/mesh_normals.cc index 9a761c6fa11..da5b4ccc764 100644 --- a/source/blender/blenkernel/intern/mesh_normals.cc +++ b/source/blender/blenkernel/intern/mesh_normals.cc @@ -316,9 +316,6 @@ void BKE_mesh_ensure_normals(Mesh *mesh) BLI_assert((mesh->runtime.cd_dirty_vert & CD_MASK_NORMAL) == 0); } -/** - * Called after calculating all modifiers. - */ void BKE_mesh_ensure_normals_for_display(Mesh *mesh) { switch ((eMeshWrapperType)mesh->runtime.wrapper_type) { @@ -378,10 +375,6 @@ void BKE_mesh_ensure_normals_for_display(Mesh *mesh) } } -/** - * NOTE: this does not update the #CD_NORMAL layer, - * but does update the normals in the #CD_MVERT layer. - */ void BKE_mesh_calc_normals(Mesh *mesh) { #ifdef DEBUG_TIME @@ -479,13 +472,6 @@ void BKE_lnor_spacearr_init(MLoopNorSpaceArray *lnors_spacearr, lnors_spacearr->data_type = data_type; } -/** - * Utility for multi-threaded calculation that ensures - * `lnors_spacearr_tls` doesn't share memory with `lnors_spacearr` - * that would cause it not to be thread safe. - * - * \note This works as long as threads never operate on the same loops at once. - */ void BKE_lnor_spacearr_tls_init(MLoopNorSpaceArray *lnors_spacearr, MLoopNorSpaceArray *lnors_spacearr_tls) { @@ -493,10 +479,6 @@ void BKE_lnor_spacearr_tls_init(MLoopNorSpaceArray *lnors_spacearr, lnors_spacearr_tls->mem = BLI_memarena_new(BLI_MEMARENA_STD_BUFSIZE, __func__); } -/** - * Utility for multi-threaded calculation - * that merges `lnors_spacearr_tls` into `lnors_spacearr`. - */ void BKE_lnor_spacearr_tls_join(MLoopNorSpaceArray *lnors_spacearr, MLoopNorSpaceArray *lnors_spacearr_tls) { @@ -537,11 +519,6 @@ MLoopNorSpace *BKE_lnor_space_create(MLoopNorSpaceArray *lnors_spacearr) /* This threshold is a bit touchy (usual float precision issue), this value seems OK. */ #define LNOR_SPACE_TRIGO_THRESHOLD (1.0f - 1e-4f) -/* Should only be called once. - * Beware, this modifies ref_vec and other_vec in place! - * In case no valid space can be generated, ref_alpha and ref_beta are set to zero - * (which means 'use auto lnors'). - */ void BKE_lnor_space_define(MLoopNorSpace *lnor_space, const float lnor[3], float vec_ref[3], @@ -614,14 +591,6 @@ void BKE_lnor_space_define(MLoopNorSpace *lnor_space, } } -/** - * Add a new given loop to given lnor_space. - * Depending on \a lnor_space->data_type, we expect \a bm_loop to be a pointer to BMLoop struct - * (in case of BMLOOP_PTR), or nullptr (in case of LOOP_INDEX), loop index is then stored in - * pointer. If \a is_single is set, the BMLoop or loop index is directly stored in \a - * lnor_space->loops pointer (since there is only one loop in this fan), else it is added to the - * linked list of loops in the fan. - */ void BKE_lnor_space_add_loop(MLoopNorSpaceArray *lnors_spacearr, MLoopNorSpace *lnor_space, const int ml_index, @@ -901,12 +870,6 @@ static void mesh_edges_sharp_tag(LoopSplitTaskDataCommon *data, } } -/** - * Define sharp edges as needed to mimic 'autosmooth' from angle threshold. - * - * Used when defining an empty custom loop normals data layer, - * to keep same shading as with auto-smooth! - */ void BKE_edges_sharp_from_angle_set(const struct MVert *mverts, const int UNUSED(numVerts), struct MEdge *medges, @@ -1568,11 +1531,6 @@ static void loop_split_generator(TaskPool *pool, LoopSplitTaskDataCommon *common #endif } -/** - * Compute split normals, i.e. vertex normals associated with each poly (hence 'loop normals'). - * Useful to materialize sharp edges (or non-smooth faces) without actually modifying the geometry - * (splitting edges). - */ void BKE_mesh_normals_loop_split(const MVert *mverts, const int UNUSED(numVerts), MEdge *medges, @@ -2057,36 +2015,16 @@ static void mesh_set_custom_normals(Mesh *mesh, float (*r_custom_nors)[3], const } } -/** - * Higher level functions hiding most of the code needed around call to - * #BKE_mesh_normals_loop_custom_set(). - * - * \param r_custom_loopnors: is not const, since code will replace zero_v3 normals there - * with automatically computed vectors. - */ void BKE_mesh_set_custom_normals(Mesh *mesh, float (*r_custom_loopnors)[3]) { mesh_set_custom_normals(mesh, r_custom_loopnors, false); } -/** - * Higher level functions hiding most of the code needed around call to - * #BKE_mesh_normals_loop_custom_from_vertices_set(). - * - * \param r_custom_vertnors: is not const, since code will replace zero_v3 normals there - * with automatically computed vectors. - */ void BKE_mesh_set_custom_normals_from_vertices(Mesh *mesh, float (*r_custom_vertnors)[3]) { mesh_set_custom_normals(mesh, r_custom_vertnors, true); } -/** - * Computes average per-vertex normals from given custom loop normals. - * - * \param clnors: The computed custom loop normals. - * \param r_vert_clnors: The (already allocated) array where to store averaged per-vertex normals. - */ void BKE_mesh_normals_loop_to_vertex(const int numVerts, const MLoop *mloops, const int numLoops, diff --git a/source/blender/blenkernel/intern/mesh_remap.c b/source/blender/blenkernel/intern/mesh_remap.c index 53a31cbbc7a..149ea6a6936 100644 --- a/source/blender/blenkernel/intern/mesh_remap.c +++ b/source/blender/blenkernel/intern/mesh_remap.c @@ -123,16 +123,6 @@ static bool mesh_remap_bvhtree_query_raycast(BVHTreeFromMesh *treedata, * Find transform of a mesh to get best match with another. * \{ */ -/** - * Compute a value of the difference between both given meshes. - * The smaller the result, the better the match. - * - * We return the inverse of the average of the inversed - * shortest distance from each dst vertex to src ones. - * In other words, beyond a certain (relatively small) distance, all differences have more or less - * the same weight in final result, which allows to reduce influence of a few high differences, - * in favor of a global good matching. - */ float BKE_mesh_remap_calc_difference_from_mesh(const SpaceTransform *space_transform, const MVert *verts_dst, const int numverts_dst, @@ -268,9 +258,6 @@ static void mesh_calc_eigen_matrix(const MVert *verts, copy_v3_v3(r_mat[3], center); } -/** - * Set r_space_transform so that best bbox of dst matches best bbox of src. - */ void BKE_mesh_remap_find_best_match_from_mesh(const MVert *verts_dst, const int numverts_dst, Mesh *me_src, diff --git a/source/blender/blenkernel/intern/mesh_runtime.c b/source/blender/blenkernel/intern/mesh_runtime.c index 7b1d5140421..b5d863778aa 100644 --- a/source/blender/blenkernel/intern/mesh_runtime.c +++ b/source/blender/blenkernel/intern/mesh_runtime.c @@ -74,28 +74,17 @@ static void mesh_runtime_free_mutexes(Mesh *mesh) } } -/** - * \brief Initialize the runtime of the given mesh. - * - * Function expects that the runtime is already cleared. - */ void BKE_mesh_runtime_init_data(Mesh *mesh) { mesh_runtime_init_mutexes(mesh); } -/** - * \brief Free all data (and mutexes) inside the runtime of the given mesh. - */ void BKE_mesh_runtime_free_data(Mesh *mesh) { BKE_mesh_runtime_clear_cache(mesh); mesh_runtime_free_mutexes(mesh); } -/* Clear all pointers which we don't want to be shared on copying the datablock. - * However, keep all the flags which defines what the mesh is (for example, that - * it's deformed only, or that its custom data layers are out of date.) */ void BKE_mesh_runtime_reset_on_copy(Mesh *mesh, const int UNUSED(flag)) { Mesh_Runtime *runtime = &mesh->runtime; @@ -111,11 +100,6 @@ void BKE_mesh_runtime_reset_on_copy(Mesh *mesh, const int UNUSED(flag)) mesh_runtime_init_mutexes(mesh); } -/** - * \brief This function clears runtime cache of the given mesh. - * - * Call this function to recalculate runtime data when used. - */ void BKE_mesh_runtime_clear_cache(Mesh *mesh) { if (mesh->runtime.mesh_eval != NULL) { @@ -128,7 +112,6 @@ void BKE_mesh_runtime_clear_cache(Mesh *mesh) BKE_mesh_runtime_clear_edit_data(mesh); } -/* This is a ported copy of DM_ensure_looptri_data(dm) */ /** * Ensure the array is large enough * @@ -137,6 +120,7 @@ void BKE_mesh_runtime_clear_cache(Mesh *mesh) */ static void mesh_ensure_looptri_data(Mesh *mesh) { + /* This is a ported copy of `DM_ensure_looptri_data(dm)`. */ const uint totpoly = mesh->totpoly; const int looptris_len = poly_to_tri_count(totpoly, mesh->totloop); @@ -162,7 +146,6 @@ static void mesh_ensure_looptri_data(Mesh *mesh) } } -/* This is a ported copy of CDDM_recalc_looptri(dm). */ void BKE_mesh_runtime_looptri_recalc(Mesh *mesh) { mesh_ensure_looptri_data(mesh); @@ -182,9 +165,9 @@ void BKE_mesh_runtime_looptri_recalc(Mesh *mesh) mesh->runtime.looptris.array_wip = NULL; } -/* This is a ported copy of dm_getNumLoopTri(dm). */ int BKE_mesh_runtime_looptri_len(const Mesh *mesh) { + /* This is a ported copy of `dm_getNumLoopTri(dm)`. */ const int looptri_len = poly_to_tri_count(mesh->totpoly, mesh->totloop); BLI_assert(ELEM(mesh->runtime.looptris.len, 0, looptri_len)); return looptri_len; @@ -196,11 +179,6 @@ static void mesh_runtime_looptri_recalc_isolated(void *userdata) BKE_mesh_runtime_looptri_recalc(mesh); } -/** - * \note This function only fills a cache, and therefore the mesh argument can - * be considered logically const. Concurrent access is protected by a mutex. - * \note This is a ported copy of dm_getLoopTriArray(dm). - */ const MLoopTri *BKE_mesh_runtime_looptri_ensure(const Mesh *mesh) { ThreadMutex *mesh_eval_mutex = (ThreadMutex *)mesh->runtime.eval_mutex; @@ -222,7 +200,6 @@ const MLoopTri *BKE_mesh_runtime_looptri_ensure(const Mesh *mesh) return looptri; } -/* This is a copy of DM_verttri_from_looptri(). */ void BKE_mesh_runtime_verttri_from_looptri(MVertTri *r_verttri, const MLoop *mloop, const MLoopTri *looptri, @@ -412,7 +389,6 @@ void BKE_mesh_runtime_debug_print(Mesh *me_eval) MEM_freeN(str); } -/* XXX Should go in customdata file? */ void BKE_mesh_runtime_debug_print_cdlayers(CustomData *data) { int i; diff --git a/source/blender/blenkernel/intern/mesh_tangent.c b/source/blender/blenkernel/intern/mesh_tangent.c index e5e971fd574..c7a1b22dad1 100644 --- a/source/blender/blenkernel/intern/mesh_tangent.c +++ b/source/blender/blenkernel/intern/mesh_tangent.c @@ -115,12 +115,6 @@ static void set_tspace(const SMikkTSpaceContext *pContext, p_res[3] = face_sign; } -/** - * Compute simplified tangent space normals, i.e. - * tangent vector + sign of bi-tangent one, which combined with - * split normals can be used to recreate the full tangent space. - * NOTE: * The mesh should be made of only tris and quads! - */ void BKE_mesh_calc_loop_tangent_single_ex(const MVert *mverts, const int UNUSED(numVerts), const MLoop *mloops, @@ -172,12 +166,6 @@ void BKE_mesh_calc_loop_tangent_single_ex(const MVert *mverts, } } -/** - * Wrapper around BKE_mesh_calc_loop_tangent_single_ex, which takes care of most boiling code. - * \note - * - There must be a valid loop's CD_NORMALS available. - * - The mesh should be made of only tris and quads! - */ void BKE_mesh_calc_loop_tangent_single(Mesh *mesh, const char *uvmap, float (*r_looptangents)[4], @@ -485,12 +473,6 @@ void BKE_mesh_add_loop_tangent_named_layer_for_uv(CustomData *uv_data, } } -/** - * Here we get some useful information such as active uv layer name and - * search if it is already in tangent_names. - * Also, we calculate tangent_mask that works as a descriptor of tangents state. - * If tangent_mask has changed, then recalculate tangents. - */ void BKE_mesh_calc_loop_tangent_step_0(const CustomData *loopData, bool calc_active_tangent, const char (*tangent_names)[MAX_NAME], @@ -564,9 +546,6 @@ void BKE_mesh_calc_loop_tangent_step_0(const CustomData *loopData, } } -/** - * See: #BKE_editmesh_loop_tangent_calc (matching logic). - */ void BKE_mesh_calc_loop_tangent_ex(const MVert *mvert, const MPoly *mpoly, const uint mpoly_len, diff --git a/source/blender/blenkernel/intern/mesh_tessellate.c b/source/blender/blenkernel/intern/mesh_tessellate.c index 213f2929d63..241aefc418c 100644 --- a/source/blender/blenkernel/intern/mesh_tessellate.c +++ b/source/blender/blenkernel/intern/mesh_tessellate.c @@ -154,17 +154,6 @@ static void mesh_loops_to_tessdata(CustomData *fdata, } } -/** - * Recreate #MFace Tessellation. - * - * \param do_face_nor_copy: Controls whether the normals from the poly - * are copied to the tessellated faces. - * - * \return number of tessellation faces. - * - * \note This doesn't use multi-threading like #BKE_mesh_recalc_looptri since - * it's not used in many places and #MFace should be phased out. - */ int BKE_mesh_tessface_calc_ex(CustomData *fdata, CustomData *ldata, CustomData *pdata, @@ -712,9 +701,6 @@ static void mesh_recalc_looptri__multi_threaded(const MLoop *mloop, &settings); } -/** - * Calculate tessellation into #MLoopTri which exist only for this purpose. - */ void BKE_mesh_recalc_looptri(const MLoop *mloop, const MPoly *mpoly, const MVert *mvert, @@ -730,14 +716,6 @@ void BKE_mesh_recalc_looptri(const MLoop *mloop, } } -/** - * A version of #BKE_mesh_recalc_looptri which takes pre-calculated polygon normals - * (used to avoid having to calculate the face normal for NGON tessellation). - * - * \note Only use this function if normals have already been calculated, there is no need - * to calculate normals just to use this function as it will cause the normals for triangles - * to be calculated which aren't needed for tessellation. - */ void BKE_mesh_recalc_looptri_with_normals(const MLoop *mloop, const MPoly *mpoly, const MVert *mvert, diff --git a/source/blender/blenkernel/intern/mesh_validate.c b/source/blender/blenkernel/intern/mesh_validate.c index 08668d55cf4..f5daf641445 100644 --- a/source/blender/blenkernel/intern/mesh_validate.c +++ b/source/blender/blenkernel/intern/mesh_validate.c @@ -213,21 +213,6 @@ static int search_polyloop_cmp(const void *v1, const void *v2) } \ } while (0) -/** - * Validate the mesh, \a do_fixes requires \a mesh to be non-null. - * - * \return false if no changes needed to be made. - * - * Vertex Normals - * ============== - * - * While zeroed normals are checked, these checks aren't comprehensive. - * Technically, to detect errors here a normal recalculation and comparison is necessary. - * However this function is mainly to prevent severe errors in geometry - * (invalid data that will crash Blender, or cause some features to behave incorrectly), - * not to detect subtle differences in the resulting normals which could be caused - * by importers that load normals (for example). - */ /* NOLINTNEXTLINE: readability-function-size */ bool BKE_mesh_validate_arrays(Mesh *mesh, MVert *mverts, @@ -997,9 +982,6 @@ static bool mesh_validate_customdata(CustomData *data, return is_valid; } -/** - * \returns is_valid. - */ bool BKE_mesh_validate_all_customdata(CustomData *vdata, const uint totvert, CustomData *edata, @@ -1061,11 +1043,6 @@ bool BKE_mesh_validate_all_customdata(CustomData *vdata, return is_valid; } -/** - * Validates and corrects a Mesh. - * - * \returns true if a change is made. - */ bool BKE_mesh_validate(Mesh *me, const bool do_verbose, const bool cddata_check_mask) { bool is_valid = true; @@ -1112,13 +1089,6 @@ bool BKE_mesh_validate(Mesh *me, const bool do_verbose, const bool cddata_check_ return false; } -/** - * Checks if a Mesh is valid without any modification. This is always verbose. - * - * \see #DM_is_valid to call on derived meshes - * - * \returns is_valid. - */ bool BKE_mesh_is_valid(Mesh *me) { const bool do_verbose = true; @@ -1162,10 +1132,6 @@ bool BKE_mesh_is_valid(Mesh *me) return is_valid; } -/** - * Check all material indices of polygons are valid, invalid ones are set to 0. - * \returns is_valid. - */ bool BKE_mesh_validate_material_indices(Mesh *me) { /* Cast to unsigned to catch negative indices too. */ @@ -1196,9 +1162,9 @@ bool BKE_mesh_validate_material_indices(Mesh *me) /** \name Mesh Stripping (removing invalid data) * \{ */ -/* We need to keep this for edge creation (for now?), and some old readfile code... */ void BKE_mesh_strip_loose_faces(Mesh *me) { + /* NOTE: We need to keep this for edge creation (for now?), and some old `readfile.c` code. */ MFace *f; int a, b; @@ -1217,13 +1183,6 @@ void BKE_mesh_strip_loose_faces(Mesh *me) } } -/** - * Works on both loops and polys! - * - * \note It won't try to guess which loops of an invalid poly to remove! - * this is the work of the caller, to mark those loops... - * See e.g. #BKE_mesh_validate_arrays(). - */ void BKE_mesh_strip_loose_polysloops(Mesh *me) { MPoly *p; @@ -1512,10 +1471,6 @@ static void mesh_calc_edges_mdata(MVert *UNUSED(allvert), *r_totedge = totedge_final; } -/** - * If the mesh is from a very old blender version, - * convert mface->edcode to edge drawflags - */ void BKE_mesh_calc_edges_legacy(Mesh *me, const bool use_old) { MEdge *medge; @@ -1565,12 +1520,6 @@ void BKE_mesh_calc_edges_loose(Mesh *mesh) } } -/** - * Calculate/create edges from tessface data - * - * \param mesh: The mesh to add edges into - */ - void BKE_mesh_calc_edges_tessface(Mesh *mesh) { const int numFaces = mesh->totface; diff --git a/source/blender/blenkernel/intern/mesh_validate.cc b/source/blender/blenkernel/intern/mesh_validate.cc index 574ab785445..c8fae3cf880 100644 --- a/source/blender/blenkernel/intern/mesh_validate.cc +++ b/source/blender/blenkernel/intern/mesh_validate.cc @@ -220,9 +220,6 @@ static void clear_hash_tables(MutableSpan edge_maps) } // namespace blender::bke::calc_edges -/** - * Calculate edges from polygons. - */ void BKE_mesh_calc_edges(Mesh *mesh, bool keep_existing_edges, const bool select_new_edges) { using namespace blender; diff --git a/source/blender/blenkernel/intern/modifier.c b/source/blender/blenkernel/intern/modifier.c index 6f6cf12f023..0d6beed1ec9 100644 --- a/source/blender/blenkernel/intern/modifier.c +++ b/source/blender/blenkernel/intern/modifier.c @@ -133,9 +133,6 @@ const ModifierTypeInfo *BKE_modifier_get_info(ModifierType type) return NULL; } -/** - * Get the idname of the modifier type's panel, which was defined in the #panelRegister callback. - */ void BKE_modifier_type_panel_id(ModifierType type, char *r_idname) { const ModifierTypeInfo *mti = BKE_modifier_get_info(type); @@ -213,9 +210,6 @@ void BKE_modifier_free(ModifierData *md) BKE_modifier_free_ex(md, 0); } -/** - * Use instead of `BLI_remlink` when the object's active modifier should change. - */ void BKE_modifier_remove_from_list(Object *ob, ModifierData *md) { BLI_assert(BLI_findindex(&ob->modifiers, md) != -1); @@ -328,9 +322,6 @@ void BKE_modifiers_foreach_tex_link(Object *ob, TexWalkFunc walk, void *userData } } -/* callback's can use this - * to avoid copying every member. - */ void BKE_modifier_copydata_generic(const ModifierData *md_src, ModifierData *md_dst, const int UNUSED(flag)) @@ -457,13 +448,6 @@ void BKE_modifier_set_error(const Object *ob, ModifierData *md, const char *_for CLOG_ERROR(&LOG, "Object: \"%s\", Modifier: \"%s\", %s", ob->id.name + 2, md->name, md->error); } -/* used for buttons, to find out if the 'draw deformed in editmode' option is - * there - * - * also used in transform_conversion.c, to detect CrazySpace [tm] (2nd arg - * then is NULL) - * also used for some mesh tools to give warnings - */ int BKE_modifiers_get_cage_index(const Scene *scene, Object *ob, int *r_lastPossibleCageIndex, @@ -547,12 +531,6 @@ bool BKE_modifiers_is_particle_enabled(Object *ob) return (md && md->mode & (eModifierMode_Realtime | eModifierMode_Render)); } -/** - * Check whether is enabled. - * - * \param scene: Current scene, may be NULL, - * in which case isDisabled callback of the modifier is never called. - */ bool BKE_modifier_is_enabled(const struct Scene *scene, ModifierData *md, int required_mode) { const ModifierTypeInfo *mti = BKE_modifier_get_info(md->type); @@ -575,12 +553,6 @@ bool BKE_modifier_is_enabled(const struct Scene *scene, ModifierData *md, int re return true; } -/** - * Check whether given modifier is not local (i.e. from linked data) when the object is a library - * override. - * - * \param md: May be NULL, in which case we consider it as a non-local modifier case. - */ bool BKE_modifier_is_nonlocal_in_liboverride(const Object *ob, const ModifierData *md) { return (ID_IS_OVERRIDE_LIBRARY(ob) && @@ -674,8 +646,6 @@ ModifierData *BKE_modifier_get_last_preview(const struct Scene *scene, return tmp_md; } -/* This is to include things that are not modifiers in the evaluation of the modifier stack, for - * example parenting to an armature. */ ModifierData *BKE_modifiers_get_virtual_modifierlist(const Object *ob, VirtualModifierData *virtualModifierData) { @@ -719,9 +689,6 @@ ModifierData *BKE_modifiers_get_virtual_modifierlist(const Object *ob, return md; } -/* Takes an object and returns its first selected armature, else just its armature - * This should work for multiple armatures per object - */ Object *BKE_modifiers_is_deformed_by_armature(Object *ob) { if (ob->type == OB_GPENCIL) { @@ -790,9 +757,6 @@ Object *BKE_modifiers_is_deformed_by_meshdeform(Object *ob) return NULL; } -/* Takes an object and returns its first selected lattice, else just its lattice - * This should work for multiple lattices per object - */ Object *BKE_modifiers_is_deformed_by_lattice(Object *ob) { VirtualModifierData virtualModifierData; @@ -816,9 +780,6 @@ Object *BKE_modifiers_is_deformed_by_lattice(Object *ob) return NULL; } -/* Takes an object and returns its first selected curve, else just its curve - * This should work for multiple curves per object - */ Object *BKE_modifiers_is_deformed_by_curve(Object *ob) { VirtualModifierData virtualModifierData; @@ -946,7 +907,6 @@ void BKE_modifier_free_temporary_data(ModifierData *md) } } -/* ensure modifier correctness when changing ob->data */ void BKE_modifiers_test_object(Object *ob) { ModifierData *md; @@ -1000,7 +960,6 @@ const char *BKE_modifier_path_relbase_from_global(Object *ob) return BKE_tempdir_session(); } -/* initializes the path with either */ void BKE_modifier_path_init(char *path, int path_maxlen, const char *name) { /* elubie: changed this to default to the same dir as the render output @@ -1086,15 +1045,6 @@ void BKE_modifier_deform_vertsEM(ModifierData *md, /* end modifier callback wrappers */ -/** - * Get evaluated mesh for other evaluated object, which is used as an operand for the modifier, - * e.g. second operand for boolean modifier. - * Note that modifiers in stack always get fully evaluated COW ID pointers, - * never original ones. Makes things simpler. - * - * \param get_cage_mesh: Return evaluated mesh with only deforming modifiers applied - * (i.e. mesh topology remains the same as original one, a.k.a. 'cage' mesh). - */ Mesh *BKE_modifier_get_evaluated_mesh_from_evaluated_object(Object *ob_eval, const bool get_cage_mesh) { diff --git a/source/blender/blenkernel/intern/movieclip.c b/source/blender/blenkernel/intern/movieclip.c index 5a6e5620c5b..e9bda6d0eb5 100644 --- a/source/blender/blenkernel/intern/movieclip.c +++ b/source/blender/blenkernel/intern/movieclip.c @@ -544,10 +544,6 @@ static void movieclip_convert_multilayer_add_pass(void *UNUSED(layer), #endif /* WITH_OPENEXR */ -/* Will try to make image buffer usable when originating from the multi-layer - * source. - * Internally finds a first combined pass and uses that as a buffer. Not ideal, - * but is better than a complete empty buffer. */ void BKE_movieclip_convert_multilayer_ibuf(struct ImBuf *ibuf) { if (ibuf == NULL) { @@ -988,10 +984,6 @@ static void detect_clip_source(Main *bmain, MovieClip *clip) } } -/* checks if image was already loaded, then returns same image - * otherwise creates new. - * does not load ibuf itself - * pass on optional frame for #name images */ MovieClip *BKE_movieclip_file_add(Main *bmain, const char *name) { MovieClip *clip; @@ -1621,7 +1613,6 @@ void BKE_movieclip_get_aspect(MovieClip *clip, float *aspx, float *aspy) *aspy = clip->aspy / clip->aspx / clip->tracking.camera.pixel_aspect; } -/* get segments of cached frames. useful for debugging cache policies */ void BKE_movieclip_get_cache_segments(MovieClip *clip, MovieClipUser *user, int *r_totseg, @@ -1857,9 +1848,6 @@ static void movieclip_build_proxy_ibuf( IMB_freeImBuf(scaleibuf); } -/* NOTE: currently used by proxy job for movies, threading happens within single frame - * (meaning scaling shall be threaded) - */ void BKE_movieclip_build_proxy_frame(MovieClip *clip, int clip_flag, struct MovieDistortion *distortion, @@ -1901,9 +1889,6 @@ void BKE_movieclip_build_proxy_frame(MovieClip *clip, } } -/* NOTE: currently used by proxy job for sequences, threading happens within sequence - * (different threads handles different frames, no threading within frame is needed) - */ void BKE_movieclip_build_proxy_frame_for_ibuf(MovieClip *clip, ImBuf *ibuf, struct MovieDistortion *distortion, diff --git a/source/blender/blenkernel/intern/multires.c b/source/blender/blenkernel/intern/multires.c index dc418545e23..fbad7d98630 100644 --- a/source/blender/blenkernel/intern/multires.c +++ b/source/blender/blenkernel/intern/multires.c @@ -330,9 +330,6 @@ MultiresModifierData *find_multires_modifier_before(Scene *scene, ModifierData * return NULL; } -/* used for applying scale on mdisps layer and syncing subdivide levels when joining objects - * use_first - return first multires modifier if all multires'es are disabled - */ MultiresModifierData *get_multires_modifier(Scene *scene, Object *ob, bool use_first) { ModifierData *md; @@ -519,7 +516,6 @@ static int get_levels_from_disps(Object *ob) return totlvl; } -/* reset the multires levels to match the number of mdisps */ void multiresModifier_set_levels_from_disps(MultiresModifierData *mmd, Object *ob) { Mesh *me = ob->data; @@ -712,7 +708,6 @@ static void multires_del_higher(MultiresModifierData *mmd, Object *ob, int lvl) multires_set_tot_level(ob, mmd, lvl); } -/* (direction = 1) for delete higher, (direction = 0) for lower (not implemented yet) */ void multiresModifier_del_levels(MultiresModifierData *mmd, Scene *scene, Object *ob, @@ -1295,7 +1290,6 @@ DerivedMesh *multires_make_derived_from_derived( return result; } -/* Adapted from sculptmode.c */ void old_mdisps_bilinear(float out[3], float (*disps)[3], const int st, float u, float v) { int x, y, x2, y2; @@ -1349,8 +1343,6 @@ void old_mdisps_bilinear(float out[3], float (*disps)[3], const int st, float u, add_v3_v3v3(out, d2[0], d2[1]); } -/* If 'ob_src' and 'ob_dst' both have multires modifiers, synchronize them - * such that 'ob_dst' has the same total number of levels as 'ob_src'. */ void multiresModifier_sync_levels_ex(Object *ob_dst, MultiresModifierData *mmd_src, MultiresModifierData *mmd_dst) @@ -1469,7 +1461,6 @@ void multiresModifier_prepare_join(struct Depsgraph *depsgraph, multires_apply_smat(depsgraph, scene, ob, mat); } -/* update multires data after topology changing */ void multires_topology_changed(Mesh *me) { MDisps *mdisp = NULL, *cur = NULL; @@ -1504,11 +1495,6 @@ void multires_topology_changed(Mesh *me) } } -/* Makes sure data from an external file is fully read. - * - * Since the multires data files only contain displacement vectors without knowledge about - * subdivision level some extra work is needed. Namely make is to all displacement grids have - * proper level and number of displacement vectors set. */ void multires_ensure_external_read(struct Mesh *mesh, int top_level) { if (!CustomData_external_test(&mesh->ldata, CD_MDISPS)) { @@ -1544,7 +1530,6 @@ void multiresModifier_ensure_external_read(struct Mesh *mesh, const MultiresModi /***************** Multires interpolation stuff *****************/ -/* Find per-corner coordinate with given per-face UV coord */ int mdisp_rot_face_to_crn(struct MVert *UNUSED(mvert), struct MPoly *mpoly, struct MLoop *UNUSED(mloop), diff --git a/source/blender/blenkernel/intern/multires_reshape.c b/source/blender/blenkernel/intern/multires_reshape.c index bd52d70b223..e0bb3cf792c 100644 --- a/source/blender/blenkernel/intern/multires_reshape.c +++ b/source/blender/blenkernel/intern/multires_reshape.c @@ -69,10 +69,6 @@ bool multiresModifier_reshapeFromVertcos(struct Depsgraph *depsgraph, return true; } -/* Returns truth on success, false otherwise. - * - * This function might fail in cases like source and destination not having - * matched amount of vertices. */ bool multiresModifier_reshapeFromObject(struct Depsgraph *depsgraph, struct MultiresModifierData *mmd, struct Object *dst, diff --git a/source/blender/blenkernel/intern/multires_reshape.h b/source/blender/blenkernel/intern/multires_reshape.h index 36ecf1a6395..db419418998 100644 --- a/source/blender/blenkernel/intern/multires_reshape.h +++ b/source/blender/blenkernel/intern/multires_reshape.h @@ -143,15 +143,19 @@ typedef struct ReshapeConstGridElement { * Construct/destruct reshape context. */ -/* Create subdivision surface descriptor which is configured for surface evaluation at a given - * multires modifier. */ +/** + * Create subdivision surface descriptor which is configured for surface evaluation at a given + * multi-res modifier. + */ struct Subdiv *multires_reshape_create_subdiv(struct Depsgraph *depsgraph, struct Object *object, const struct MultiresModifierData *mmd); -/* NOTE: Initialized base mesh to object's mesh, the Subdiv is created from the deformed - * mesh prior to the multires modifier if depsgraph is not NULL. If the depsgraph is NULL - * then Subdiv is created from base mesh (without any deformation applied). */ +/** + * \note Initialized base mesh to object's mesh, the Subdivision is created from the deformed + * mesh prior to the multi-res modifier if depsgraph is not NULL. If the depsgraph is NULL + * then Subdivision is created from base mesh (without any deformation applied). + */ bool multires_reshape_context_create_from_object(MultiresReshapeContext *reshape_context, struct Depsgraph *depsgraph, struct Object *object, @@ -185,29 +189,41 @@ void multires_reshape_context_free(MultiresReshapeContext *reshape_context); * Helper accessors. */ -/* For the given grid index get index of face it was created for. */ +/** + * For the given grid index get index of face it was created for. + */ int multires_reshape_grid_to_face_index(const MultiresReshapeContext *reshape_context, int grid_index); -/* For the given grid index get corner of a face it was created for. */ +/** + * For the given grid index get corner of a face it was created for. + */ int multires_reshape_grid_to_corner(const MultiresReshapeContext *reshape_context, int grid_index); bool multires_reshape_is_quad_face(const MultiresReshapeContext *reshape_context, int face_index); -/* For the given grid index get index of corresponding ptex face. */ +/** + * For the given grid index get index of corresponding PTEX face. + */ int multires_reshape_grid_to_ptex_index(const MultiresReshapeContext *reshape_context, int grid_index); -/* Convert normalized coordinate within a grid to a normalized coordinate within a ptex face. */ +/** + * Convert normalized coordinate within a grid to a normalized coordinate within a PTEX face. + */ PTexCoord multires_reshape_grid_coord_to_ptex(const MultiresReshapeContext *reshape_context, const GridCoord *grid_coord); -/* Convert a normalized coordinate within a ptex face to a normalized coordinate within a grid. */ +/** + * Convert a normalized coordinate within a PTEX face to a normalized coordinate within a grid. + */ GridCoord multires_reshape_ptex_coord_to_grid(const MultiresReshapeContext *reshape_context, const PTexCoord *ptex_coord); -/* Calculate tangent matrix which converts displacement to a object vector. - * Is calculated for the given surface derivatives at a given base face corner. */ +/** + * Calculate tangent matrix which converts displacement to a object vector. + * Is calculated for the given surface derivatives at a given base face corner. + */ void multires_reshape_tangent_matrix_for_corner(const MultiresReshapeContext *reshape_context, const int face_index, const int corner, @@ -215,14 +231,18 @@ void multires_reshape_tangent_matrix_for_corner(const MultiresReshapeContext *re const float dPdv[3], float r_tangent_matrix[3][3]); -/* Get grid elements which are to be reshaped at a given or ptex coordinate. - * The data is coming from final custom mdata layers. */ +/** + * Get grid elements which are to be reshaped at a given or PTEX coordinate. + * The data is coming from final custom mdata layers. + */ ReshapeGridElement multires_reshape_grid_element_for_grid_coord( const MultiresReshapeContext *reshape_context, const GridCoord *grid_coord); ReshapeGridElement multires_reshape_grid_element_for_ptex_coord( const MultiresReshapeContext *reshape_context, const PTexCoord *ptex_coord); -/* Get original grid element for the given coordinate. */ +/** + * Get original grid element for the given coordinate. + */ ReshapeConstGridElement multires_reshape_orig_grid_element_for_grid_coord( const MultiresReshapeContext *reshape_context, const GridCoord *grid_coord); @@ -230,8 +250,10 @@ ReshapeConstGridElement multires_reshape_orig_grid_element_for_grid_coord( * Sample limit surface of the base mesh. */ -/* Evaluate limit surface created from base mesh. - * This is the limit surface which defines tangent space for MDisps. */ +/** + * Evaluate limit surface created from base mesh. + * This is the limit surface which defines tangent space for MDisps. + */ void multires_reshape_evaluate_limit_at_grid(const MultiresReshapeContext *reshape_context, const GridCoord *grid_coord, float r_P[3], @@ -241,17 +263,23 @@ void multires_reshape_evaluate_limit_at_grid(const MultiresReshapeContext *resha * Custom data preparation. */ -/* Make sure custom data is allocated for the given level. */ +/** + * Make sure custom data is allocated for the given level. + */ void multires_reshape_ensure_grids(struct Mesh *mesh, const int level); /* -------------------------------------------------------------------- * Functions specific to reshaping from a set of vertices in a object position. */ -/* Returns truth if all coordinates were assigned. +/** + * Set displacement grids values at a reshape level to a object coordinates of the given source. + * + * \returns truth if all coordinates were assigned. * * False will be returned if the number of vertex coordinates did not match required number of - * vertices at a reshape level. */ + * vertices at a reshape level. + */ bool multires_reshape_assign_final_coords_from_vertcos( const MultiresReshapeContext *reshape_context, const float (*vert_coords)[3], @@ -261,13 +289,15 @@ bool multires_reshape_assign_final_coords_from_vertcos( * Functions specific to reshaping from CCG. */ -/* Store final object-space coordinates in the displacement grids. +/** + * Store final object-space coordinates in the displacement grids. * The reason why displacement grids are used for storage is based on memory * footprint optimization. * - * NOTE: Displacement grids to be at least at a reshape level. + * \note Displacement grids to be at least at a reshape level. * - * Return truth if all coordinates have been updated. */ + * \return truth if all coordinates have been updated. + */ bool multires_reshape_assign_final_coords_from_ccg(const MultiresReshapeContext *reshape_context, struct SubdivCCG *subdiv_ccg); @@ -275,11 +305,15 @@ bool multires_reshape_assign_final_coords_from_ccg(const MultiresReshapeContext * Functions specific to reshaping from MDISPS. */ -/* Reads and writes to the current mesh CD_MDISPS. */ +/** + * Reads and writes to the current mesh #CD_MDISPS. + */ void multires_reshape_assign_final_coords_from_mdisps( const MultiresReshapeContext *reshape_context); -/* Reads from original CD_MIDTSPS, writes to the current mesh CD_MDISPS. */ +/** + * Reads from original #CD_MIDTSPS, writes to the current mesh #CD_MDISPS. + */ void multires_reshape_assign_final_elements_from_orig_mdisps( const MultiresReshapeContext *reshape_context); @@ -287,15 +321,18 @@ void multires_reshape_assign_final_elements_from_orig_mdisps( * Displacement smooth. */ -/* Operates on a displacement grids (CD_MDISPS) which contains object space coordinates stored for +/** + * Operates on a displacement grids (CD_MDISPS) which contains object space coordinates stored for * the reshape level. * * The result is grids which are defining mesh with a smooth surface and details starting from - * reshape level up to top level added back from original displacement grids. */ + * reshape level up to top level added back from original displacement grids. + */ void multires_reshape_smooth_object_grids_with_details( const MultiresReshapeContext *reshape_context); -/* Operates on a displacement grids (CD_MDISPS) which contains object space-coordinates stored for +/** + * Operates on a displacement grids (CD_MDISPS) which contains object space-coordinates stored for * the reshape level. * * Makes it so surface on top level looks smooth. Details are not preserved @@ -307,8 +344,10 @@ void multires_reshape_smooth_object_grids(const MultiresReshapeContext *reshape_ * Displacement, space conversion. */ -/* Store original grid data, so then it's possible to calculate delta from it and add - * high-frequency content on top of reshaped grids. */ +/** + * Store original grid data, so then it's possible to calculate delta from it and add + * high-frequency content on top of reshaped grids. + */ void multires_reshape_store_original_grids(MultiresReshapeContext *reshape_context); void multires_reshape_object_grids_to_tangent_displacement( @@ -318,21 +357,29 @@ void multires_reshape_object_grids_to_tangent_displacement( * Apply base. */ -/* Update mesh coordinates to the final positions of displacement in object space. +/** + * Update mesh coordinates to the final positions of displacement in object space. * This is effectively desired position of base mesh vertices after canceling out displacement. * - * NOTE: Expects that mesh's CD_MDISPS has been set to object space positions. */ + * \note Expects that mesh's CD_MDISPS has been set to object space positions. + */ void multires_reshape_apply_base_update_mesh_coords(MultiresReshapeContext *reshape_context); -/* Perform better fitting of the base mesh so its subdivided version brings vertices to their - * desired locations. */ +/** + * Perform better fitting of the base mesh so its subdivided version brings vertices to their + * desired locations. + */ void multires_reshape_apply_base_refit_base_mesh(MultiresReshapeContext *reshape_context); -/* Refine subdivision surface to the new positions of the base mesh. */ +/** + * Refine subdivision surface to the new positions of the base mesh. + */ void multires_reshape_apply_base_refine_from_base(MultiresReshapeContext *reshape_context); -/* Refine subdivision surface to the new positions of the deformed mesh (base mesh with all - * modifiers leading the multires applied). +/** + * Refine subdivision surface to the new positions of the deformed mesh (base mesh with all + * modifiers leading the multi-res applied). * - * NOTE: Will re-evaluate all leading modifiers, so it's not cheap. */ + * \note Will re-evaluate all leading modifiers, so it's not cheap. + */ void multires_reshape_apply_base_refine_from_deform(MultiresReshapeContext *reshape_context); diff --git a/source/blender/blenkernel/intern/multires_reshape_util.c b/source/blender/blenkernel/intern/multires_reshape_util.c index 79a2b9eb002..b7572204182 100644 --- a/source/blender/blenkernel/intern/multires_reshape_util.c +++ b/source/blender/blenkernel/intern/multires_reshape_util.c @@ -47,8 +47,6 @@ /** \name Construct/destruct reshape context * \{ */ -/* Create subdivision surface descriptor which is configured for surface evaluation at a given - * multires modifier. */ Subdiv *multires_reshape_create_subdiv(Depsgraph *depsgraph, /*const*/ Object *object, const MultiresModifierData *mmd) @@ -332,7 +330,6 @@ void multires_reshape_context_free(MultiresReshapeContext *reshape_context) /** \name Helper accessors * \{ */ -/* For the given grid index get index of face it was created for. */ int multires_reshape_grid_to_face_index(const MultiresReshapeContext *reshape_context, int grid_index) { @@ -345,7 +342,6 @@ int multires_reshape_grid_to_face_index(const MultiresReshapeContext *reshape_co return reshape_context->grid_to_face_index[grid_index]; } -/* For the given grid index get corner of a face it was created for. */ int multires_reshape_grid_to_corner(const MultiresReshapeContext *reshape_context, int grid_index) { BLI_assert(grid_index >= 0); @@ -364,7 +360,6 @@ bool multires_reshape_is_quad_face(const MultiresReshapeContext *reshape_context return (base_poly->totloop == 4); } -/* For the given grid index get index of corresponding ptex face. */ int multires_reshape_grid_to_ptex_index(const MultiresReshapeContext *reshape_context, int grid_index) { @@ -374,7 +369,6 @@ int multires_reshape_grid_to_ptex_index(const MultiresReshapeContext *reshape_co return reshape_context->face_ptex_offset[face_index] + (is_quad ? 0 : corner); } -/* Convert normalized coordinate within a grid to a normalized coordinate within a ptex face. */ PTexCoord multires_reshape_grid_coord_to_ptex(const MultiresReshapeContext *reshape_context, const GridCoord *grid_coord) { @@ -402,7 +396,6 @@ PTexCoord multires_reshape_grid_coord_to_ptex(const MultiresReshapeContext *resh return ptex_coord; } -/* Convert a normalized coordinate within a ptex face to a normalized coordinate within a grid. */ GridCoord multires_reshape_ptex_coord_to_grid(const MultiresReshapeContext *reshape_context, const PTexCoord *ptex_coord) { diff --git a/source/blender/blenkernel/intern/multires_reshape_vertcos.c b/source/blender/blenkernel/intern/multires_reshape_vertcos.c index 04df5698cf9..ed2df1ba8c5 100644 --- a/source/blender/blenkernel/intern/multires_reshape_vertcos.c +++ b/source/blender/blenkernel/intern/multires_reshape_vertcos.c @@ -182,7 +182,6 @@ static void multires_reshape_vertcos_foreach_vertex_every_edge( multires_reshape_vertcos_foreach_vertex(foreach_context, &ptex_coord, subdiv_vertex_index); } -/* Set displacement grids values at a reshape level to a object coordinates of the given source. */ bool multires_reshape_assign_final_coords_from_vertcos( const MultiresReshapeContext *reshape_context, const float (*vert_coords)[3], diff --git a/source/blender/blenkernel/intern/nla.c b/source/blender/blenkernel/intern/nla.c index 7473621432a..84484a63291 100644 --- a/source/blender/blenkernel/intern/nla.c +++ b/source/blender/blenkernel/intern/nla.c @@ -75,9 +75,6 @@ static void nla_tweakmode_find_active(const ListBase /* NlaTrack */ *nla_tracks, /* Freeing ------------------------------------------- */ -/* Remove the given NLA strip from the NLA track it occupies, free the strip's data, - * and the strip itself. - */ void BKE_nlastrip_free(ListBase *strips, NlaStrip *strip, bool do_id_user) { NlaStrip *cs, *csn; @@ -117,9 +114,6 @@ void BKE_nlastrip_free(ListBase *strips, NlaStrip *strip, bool do_id_user) } } -/* Remove the given NLA track from the set of NLA tracks, free the track's data, - * and the track itself. - */ void BKE_nlatrack_free(ListBase *tracks, NlaTrack *nlt, bool do_id_user) { NlaStrip *strip, *stripn; @@ -144,9 +138,6 @@ void BKE_nlatrack_free(ListBase *tracks, NlaTrack *nlt, bool do_id_user) } } -/* Free the elements of type NLA Tracks provided in the given list, but do not free - * the list itself since that is not free-standing - */ void BKE_nla_tracks_free(ListBase *tracks, bool do_id_user) { NlaTrack *nlt, *nltn; @@ -168,13 +159,6 @@ void BKE_nla_tracks_free(ListBase *tracks, bool do_id_user) /* Copying ------------------------------------------- */ -/** - * Copy NLA strip - * - * \param use_same_action: When true, the existing action is used (instead of being duplicated) - * \param flag: Control ID pointers management, see LIB_ID_CREATE_.../LIB_ID_COPY_... - * flags in BKE_lib_id.h - */ NlaStrip *BKE_nlastrip_copy(Main *bmain, NlaStrip *strip, const bool use_same_action, @@ -224,11 +208,6 @@ NlaStrip *BKE_nlastrip_copy(Main *bmain, return strip_d; } -/** - * Copy a single NLA Track. - * \param flag: Control ID pointers management, see LIB_ID_CREATE_.../LIB_ID_COPY_... - * flags in BKE_lib_id.h - */ NlaTrack *BKE_nlatrack_copy(Main *bmain, NlaTrack *nlt, const bool use_same_actions, @@ -258,11 +237,6 @@ NlaTrack *BKE_nlatrack_copy(Main *bmain, return nlt_d; } -/** - * Copy all NLA data. - * \param flag: Control ID pointers management, see LIB_ID_CREATE_.../LIB_ID_COPY_... - * flags in BKE_lib_id.h - */ void BKE_nla_tracks_copy(Main *bmain, ListBase *dst, const ListBase *src, const int flag) { NlaTrack *nlt, *nlt_d; @@ -342,9 +316,6 @@ void BKE_nla_tracks_copy_from_adt(Main *bmain, /* Adding ------------------------------------------- */ -/* Add a NLA Track to the given AnimData - * - prev: NLA-Track to add the new one after - */ NlaTrack *BKE_nlatrack_add(AnimData *adt, NlaTrack *prev, const bool is_liboverride) { NlaTrack *nlt; @@ -388,7 +359,6 @@ NlaTrack *BKE_nlatrack_add(AnimData *adt, NlaTrack *prev, const bool is_liboverr return nlt; } -/* Create a NLA Strip referencing the given Action */ NlaStrip *BKE_nlastrip_new(bAction *act) { NlaStrip *strip; @@ -438,8 +408,6 @@ NlaStrip *BKE_nlastrip_new(bAction *act) return strip; } -/* Add new NLA-strip to the top of the NLA stack - i.e. - * into the last track if space, or a new one otherwise. */ NlaStrip *BKE_nlastack_add_strip(AnimData *adt, bAction *act, const bool is_liboverride) { NlaStrip *strip; @@ -472,7 +440,6 @@ NlaStrip *BKE_nlastack_add_strip(AnimData *adt, bAction *act, const bool is_libo return strip; } -/* Add a NLA Strip referencing the given speaker's sound */ NlaStrip *BKE_nla_add_soundstrip(Main *bmain, Scene *scene, Speaker *speaker) { NlaStrip *strip = MEM_callocN(sizeof(NlaStrip), "NlaSoundStrip"); @@ -509,10 +476,6 @@ NlaStrip *BKE_nla_add_soundstrip(Main *bmain, Scene *scene, Speaker *speaker) return strip; } -/** - * Callback used by lib_query to walk over all ID usages (mimics `foreach_id` callback of - * `IDTypeInfo` structure). - */ void BKE_nla_strip_foreach_id(NlaStrip *strip, LibraryForeachIDData *data) { BKE_LIB_FOREACHID_PROCESS_IDSUPER(data, strip->act, IDWALK_CB_USER); @@ -628,12 +591,6 @@ static float nlastrip_get_frame_transition(NlaStrip *strip, float cframe, short return (cframe - strip->start) / length; } -/* non clipped mapping for strip-time <-> global time - * mode = eNlaTime_ConvertModes[] -> NLATIME_CONVERT_* - * - * only secure for 'internal' (i.e. within AnimSys evaluation) operations, - * but should not be directly relied on for stuff which interacts with editors - */ float nlastrip_get_frame(NlaStrip *strip, float cframe, short mode) { switch (strip->type) { @@ -648,12 +605,6 @@ float nlastrip_get_frame(NlaStrip *strip, float cframe, short mode) } } -/* Non clipped mapping for strip-time <-> global time - * mode = eNlaTime_ConvertModes -> NLATIME_CONVERT_* - * - * Public API method - perform this mapping using the given AnimData block - * and perform any necessary sanity checks on the value - */ float BKE_nla_tweakedit_remap(AnimData *adt, float cframe, short mode) { NlaStrip *strip; @@ -702,7 +653,6 @@ float BKE_nla_tweakedit_remap(AnimData *adt, float cframe, short mode) /* List of Strips ------------------------------------ */ /* (these functions are used for NLA-Tracks and also for nested/meta-strips) */ -/* Check if there is any space in the given list to add the given strip */ bool BKE_nlastrips_has_space(ListBase *strips, float start, float end) { NlaStrip *strip; @@ -737,9 +687,6 @@ bool BKE_nlastrips_has_space(ListBase *strips, float start, float end) return true; } -/* Rearrange the strips in the track so that they are always in order - * (usually only needed after a strip has been moved) - */ void BKE_nlastrips_sort_strips(ListBase *strips) { ListBase tmp = {NULL, NULL}; @@ -783,9 +730,6 @@ void BKE_nlastrips_sort_strips(ListBase *strips) strips->last = tmp.last; } -/* Add the given NLA-Strip to the given list of strips, assuming that it - * isn't currently a member of another list - */ bool BKE_nlastrips_add_strip(ListBase *strips, NlaStrip *strip) { NlaStrip *ns; @@ -821,10 +765,6 @@ bool BKE_nlastrips_add_strip(ListBase *strips, NlaStrip *strip) /* Meta-Strips ------------------------------------ */ -/* Convert 'islands' (i.e. continuous string of) selected strips to be - * contained within 'Meta-Strips' which act as strips which contain strips. - * temp: are the meta-strips to be created 'temporary' ones used for transforms? - */ void BKE_nlastrips_make_metas(ListBase *strips, bool is_temp) { NlaStrip *mstrip = NULL; @@ -878,7 +818,6 @@ void BKE_nlastrips_make_metas(ListBase *strips, bool is_temp) } } -/* Split a meta-strip into a set of normal strips */ void BKE_nlastrips_clear_metastrip(ListBase *strips, NlaStrip *strip) { NlaStrip *cs, *csn; @@ -901,10 +840,6 @@ void BKE_nlastrips_clear_metastrip(ListBase *strips, NlaStrip *strip) BKE_nlastrip_free(strips, strip, true); } -/* Remove meta-strips (i.e. flatten the list of strips) from the top-level of the list of strips - * sel: only consider selected meta-strips, otherwise all meta-strips are removed - * onlyTemp: only remove the 'temporary' meta-strips used for transforms - */ void BKE_nlastrips_clear_metas(ListBase *strips, bool only_sel, bool only_temp) { NlaStrip *strip, *stripn; @@ -930,9 +865,6 @@ void BKE_nlastrips_clear_metas(ListBase *strips, bool only_sel, bool only_temp) } } -/* Add the given NLA-Strip to the given Meta-Strip, assuming that the - * strip isn't attached to any list of strips - */ bool BKE_nlameta_add_strip(NlaStrip *mstrip, NlaStrip *strip) { /* sanity checks */ @@ -981,9 +913,6 @@ bool BKE_nlameta_add_strip(NlaStrip *mstrip, NlaStrip *strip) return BKE_nlastrips_add_strip(&mstrip->strips, strip); } -/* Adjust the settings of NLA-Strips contained within a Meta-Strip (recursively), - * until the Meta-Strips children all fit within the Meta-Strip's new dimensions - */ void BKE_nlameta_flush_transforms(NlaStrip *mstrip) { NlaStrip *strip; @@ -1066,7 +995,6 @@ void BKE_nlameta_flush_transforms(NlaStrip *mstrip) /* NLA-Tracks ---------------------------------------- */ -/* Find the active NLA-track for the given stack */ NlaTrack *BKE_nlatrack_find_active(ListBase *tracks) { NlaTrack *nlt; @@ -1087,11 +1015,6 @@ NlaTrack *BKE_nlatrack_find_active(ListBase *tracks) return NULL; } -/* Get the NLA Track that the active action/action strip comes from, - * since this info is not stored in AnimData. It also isn't as simple - * as just using the active track, since multiple tracks may have been - * entered at the same time. - */ NlaTrack *BKE_nlatrack_find_tweaked(AnimData *adt) { NlaTrack *nlt; @@ -1123,9 +1046,6 @@ NlaTrack *BKE_nlatrack_find_tweaked(AnimData *adt) return NULL; } -/* Toggle the 'solo' setting for the given NLA-track, making sure that it is the only one - * that has this status in its AnimData block. - */ void BKE_nlatrack_solo_toggle(AnimData *adt, NlaTrack *nlt) { NlaTrack *nt; @@ -1160,9 +1080,6 @@ void BKE_nlatrack_solo_toggle(AnimData *adt, NlaTrack *nlt) } } -/* Make the given NLA-track the active one for the given stack. If no track is provided, - * this function can be used to simply deactivate all the NLA tracks in the given stack too. - */ void BKE_nlatrack_set_active(ListBase *tracks, NlaTrack *nlt_a) { NlaTrack *nlt; @@ -1183,7 +1100,6 @@ void BKE_nlatrack_set_active(ListBase *tracks, NlaTrack *nlt_a) } } -/* Check if there is any space in the given track to add a strip of the given length */ bool BKE_nlatrack_has_space(NlaTrack *nlt, float start, float end) { /* sanity checks @@ -1204,9 +1120,6 @@ bool BKE_nlatrack_has_space(NlaTrack *nlt, float start, float end) return BKE_nlastrips_has_space(&nlt->strips, start, end); } -/* Rearrange the strips in the track so that they are always in order - * (usually only needed after a strip has been moved) - */ void BKE_nlatrack_sort_strips(NlaTrack *nlt) { /* sanity checks */ @@ -1218,9 +1131,6 @@ void BKE_nlatrack_sort_strips(NlaTrack *nlt) BKE_nlastrips_sort_strips(&nlt->strips); } -/* Add the given NLA-Strip to the given NLA-Track, assuming that it - * isn't currently attached to another one - */ bool BKE_nlatrack_add_strip(NlaTrack *nlt, NlaStrip *strip, const bool is_liboverride) { /* sanity checks */ @@ -1238,9 +1148,6 @@ bool BKE_nlatrack_add_strip(NlaTrack *nlt, NlaStrip *strip, const bool is_libove return BKE_nlastrips_add_strip(&nlt->strips, strip); } -/* Get the extents of the given NLA-Track including gaps between strips, - * returning whether this succeeded or not - */ bool BKE_nlatrack_get_bounds(NlaTrack *nlt, float bounds[2]) { NlaStrip *strip; @@ -1270,12 +1177,6 @@ bool BKE_nlatrack_get_bounds(NlaTrack *nlt, float bounds[2]) return true; } -/** - * Check whether given NLA track is not local (i.e. from linked data) when the object is a library - * override. - * - * \param nlt: May be NULL, in which case we consider it as a non-local track case. - */ bool BKE_nlatrack_is_nonlocal_in_liboverride(const ID *id, const NlaTrack *nlt) { return (ID_IS_OVERRIDE_LIBRARY(id) && @@ -1284,7 +1185,6 @@ bool BKE_nlatrack_is_nonlocal_in_liboverride(const ID *id, const NlaTrack *nlt) /* NLA Strips -------------------------------------- */ -/* Find the active NLA-strip within the given track */ NlaStrip *BKE_nlastrip_find_active(NlaTrack *nlt) { NlaStrip *strip; @@ -1305,7 +1205,6 @@ NlaStrip *BKE_nlastrip_find_active(NlaTrack *nlt) return NULL; } -/* Make the given NLA-Strip the active one within the given block */ void BKE_nlastrip_set_active(AnimData *adt, NlaStrip *strip) { NlaTrack *nlt; @@ -1329,7 +1228,6 @@ void BKE_nlastrip_set_active(AnimData *adt, NlaStrip *strip) } } -/* Does the given NLA-strip fall within the given bounds (times)? */ bool BKE_nlastrip_within_bounds(NlaStrip *strip, float min, float max) { const float stripLen = (strip) ? strip->end - strip->start : 0.0f; @@ -1457,10 +1355,6 @@ static void nlastrip_fix_resize_overlaps(NlaStrip *strip) } } -/** - * Recalculate the start and end frames for the strip to match the bounds of its action such that - * the overall NLA animation result is unchanged. - */ void BKE_nlastrip_recalculate_bounds_sync_action(NlaStrip *strip) { float prev_actstart; @@ -1478,9 +1372,6 @@ void BKE_nlastrip_recalculate_bounds_sync_action(NlaStrip *strip) BKE_nlastrip_recalculate_bounds(strip); } -/* Recalculate the start and end frames for the current strip, after changing - * the extents of the action or the mapping (repeats or scale factor) info - */ void BKE_nlastrip_recalculate_bounds(NlaStrip *strip) { float actlen, mapping; @@ -1545,7 +1436,6 @@ static bool nlastrip_is_first(AnimData *adt, NlaStrip *strip) /* Animated Strips ------------------------------------------- */ -/* Check if the given NLA-Track has any strips with own F-Curves */ bool BKE_nlatrack_has_animated_strips(NlaTrack *nlt) { NlaStrip *strip; @@ -1566,7 +1456,6 @@ bool BKE_nlatrack_has_animated_strips(NlaTrack *nlt) return false; } -/* Check if given NLA-Tracks have any strips with own F-Curves */ bool BKE_nlatracks_have_animated_strips(ListBase *tracks) { NlaTrack *nlt; @@ -1587,7 +1476,6 @@ bool BKE_nlatracks_have_animated_strips(ListBase *tracks) return false; } -/* Validate the NLA-Strips 'control' F-Curves based on the flags set. */ void BKE_nlastrip_validate_fcurves(NlaStrip *strip) { FCurve *fcu; @@ -1651,9 +1539,6 @@ void BKE_nlastrip_validate_fcurves(NlaStrip *strip) } } -/* Check if the given RNA pointer + property combo should be handled by - * NLA strip curves or not. - */ bool BKE_nlastrip_has_curves_for_property(const PointerRNA *ptr, const PropertyRNA *prop) { /* sanity checks */ @@ -1693,11 +1578,6 @@ static bool nla_editbone_name_check(void *arg, const char *name) return BLI_ghash_haskey((GHash *)arg, (const void *)name); } -/* Find (and set) a unique name for a strip from the whole AnimData block - * Uses a similar method to the BLI method, but is implemented differently - * as we need to ensure that the name is unique over several lists of tracks, - * not just a single track. - */ void BKE_nlastrip_validate_name(AnimData *adt, NlaStrip *strip) { GHash *gh; @@ -1871,7 +1751,6 @@ static void BKE_nlastrip_validate_autoblends(NlaTrack *nlt, NlaStrip *nls) } } -/* Ensure that auto-blending and other settings are set correctly */ void BKE_nla_validate_state(AnimData *adt) { NlaStrip *strip, *fstrip = NULL; @@ -1928,12 +1807,6 @@ void BKE_nla_validate_state(AnimData *adt) /* name of stashed tracks - the translation stuff is included here to save extra work */ #define STASH_TRACK_NAME DATA_("[Action Stash]") -/* Check if an action is "stashed" in the NLA already - * - * The criteria for this are: - * 1) The action in question lives in a "stash" track - * 2) We only check first-level strips. That is, we will not check inside meta strips. - */ bool BKE_nla_action_is_stashed(AnimData *adt, bAction *act) { NlaTrack *nlt; @@ -1952,9 +1825,6 @@ bool BKE_nla_action_is_stashed(AnimData *adt, bAction *act) return false; } -/* "Stash" an action (i.e. store it as a track/layer in the NLA, but non-contributing) - * to retain it in the file for future uses - */ bool BKE_nla_action_stash(AnimData *adt, const bool is_liboverride) { NlaTrack *prev_track = NULL; @@ -2023,12 +1893,6 @@ bool BKE_nla_action_stash(AnimData *adt, const bool is_liboverride) /* Core Tools ------------------------------------------- */ -/* For the given AnimData block, add the active action to the NLA - * stack (i.e. 'push-down' action). The UI should only allow this - * for normal editing only (i.e. not in editmode for some strip's action), - * so no checks for this are performed. - */ -/* TODO: maybe we should have checks for this too... */ void BKE_nla_action_pushdown(AnimData *adt, const bool is_liboverride) { NlaStrip *strip; @@ -2158,9 +2022,6 @@ static void nla_tweakmode_find_active(const ListBase /* NlaTrack */ *nla_tracks, *r_active_strip = activeStrip; } -/* Find the active strip + track combo, and set them up as the tweaking track, - * and return if successful or not. - */ bool BKE_nla_tweakmode_enter(AnimData *adt) { NlaTrack *nlt, *activeTrack = NULL; @@ -2231,7 +2092,6 @@ bool BKE_nla_tweakmode_enter(AnimData *adt) return true; } -/* Exit tweak-mode for this AnimData block. */ void BKE_nla_tweakmode_exit(AnimData *adt) { NlaStrip *strip; diff --git a/source/blender/blenkernel/intern/node.cc b/source/blender/blenkernel/intern/node.cc index 6c1a0d2657f..7dce57a2773 100644 --- a/source/blender/blenkernel/intern/node.cc +++ b/source/blender/blenkernel/intern/node.cc @@ -542,7 +542,6 @@ static void write_node_socket_interface(BlendWriter *writer, bNodeSocket *sock) write_node_socket_default_value(writer, sock); } -/* this is only direct data, tree itself should have been written */ void ntreeBlendWrite(BlendWriter *writer, bNodeTree *ntree) { BKE_id_blend_write(writer, &ntree->id); @@ -704,7 +703,6 @@ static void direct_link_node_socket(BlendDataReader *reader, bNodeSocket *sock) sock->declaration = nullptr; } -/* ntree itself has been read! */ void ntreeBlendReadData(BlendDataReader *reader, bNodeTree *ntree) { /* NOTE: writing and reading goes in sync, for speed. */ @@ -1296,14 +1294,6 @@ static void update_typeinfo(Main *bmain, FOREACH_NODETREE_END; } -/** - * Try to initialize all type-info in a node tree. - * - * \note In general undefined type-info is a perfectly valid case, - * the type may just be registered later. - * In that case the update_typeinfo function will set type-info on registration - * and do necessary updates. - */ void ntreeSetTypes(const struct bContext *C, bNodeTree *ntree) { ntree->init |= NTREE_TYPE_INIT; @@ -2059,13 +2049,11 @@ void nodeRemoveAllSockets(bNodeTree *ntree, bNode *node) node->update |= NODE_UPDATE; } -/* finds a node based on its name */ bNode *nodeFindNodebyName(bNodeTree *ntree, const char *name) { return (bNode *)BLI_findstring(&ntree->nodes, name, offsetof(bNode, name)); } -/* Finds a node based on given socket and returns true on success. */ bool nodeFindNode(bNodeTree *ntree, bNodeSocket *sock, bNode **r_node, int *r_sockindex) { *r_node = nullptr; @@ -2089,9 +2077,6 @@ bool nodeFindNode(bNodeTree *ntree, bNodeSocket *sock, bNode **r_node, int *r_so return false; } -/** - * \note Recursive - */ bNode *nodeFindRootParent(bNode *node) { if (node->parent) { @@ -2100,10 +2085,6 @@ bNode *nodeFindRootParent(bNode *node) return node->type == NODE_FRAME ? node : nullptr; } -/** - * \returns true if \a child has \a parent as a parent/grandparent/... - * \note Recursive - */ bool nodeIsChildOf(const bNode *parent, const bNode *child) { if (parent == child) { @@ -2115,13 +2096,6 @@ bool nodeIsChildOf(const bNode *parent, const bNode *child) return false; } -/** - * Iterate over a chain of nodes, starting with \a node_start, executing - * \a callback for each node (which can return false to end iterator). - * - * \param reversed: for backwards iteration - * \note Recursive - */ void nodeChainIter(const bNodeTree *ntree, const bNode *node_start, bool (*callback)(bNode *, bNode *, void *, const bool), @@ -2176,17 +2150,6 @@ static void iter_backwards_ex(const bNodeTree *ntree, } } -/** - * Iterate over a chain of nodes, starting with \a node_start, executing - * \a callback for each node (which can return false to end iterator). - * - * Faster than nodeChainIter. Iter only once per node. - * Can be called recursively (using another nodeChainIterBackwards) by - * setting the recursion_lvl accordingly. - * - * \note Needs updated socket links (ntreeUpdateTree). - * \note Recursive - */ void nodeChainIterBackwards(const bNodeTree *ntree, const bNode *node_start, bool (*callback)(bNode *, bNode *, void *), @@ -2209,12 +2172,6 @@ void nodeChainIterBackwards(const bNodeTree *ntree, iter_backwards_ex(ntree, node_start, callback, userdata, recursion_mask); } -/** - * Iterate over all parents of \a node, executing \a callback for each parent - * (which can return false to end iterator) - * - * \note Recursive - */ void nodeParentsIter(bNode *node, bool (*callback)(bNode *, void *), void *userdata) { if (node->parent) { @@ -2227,7 +2184,6 @@ void nodeParentsIter(bNode *node, bool (*callback)(bNode *, void *), void *userd /* ************** Add stuff ********** */ -/* Find the first available, non-duplicate name for a given node */ void nodeUniqueName(bNodeTree *ntree, bNode *node) { BLI_uniquename( @@ -2290,9 +2246,6 @@ static void node_socket_copy(bNodeSocket *sock_dst, const bNodeSocket *sock_src, sock_dst->cache = nullptr; } -/* keep socket listorder identical, for copying links */ -/* ntree is the target tree */ -/* unique_name needs to be true. It's only disabled for speed when doing GPUnodetrees. */ bNode *BKE_node_copy_ex(bNodeTree *ntree, const bNode *node_src, const int flag, @@ -2436,7 +2389,6 @@ static int node_count_links(const bNodeTree *ntree, const bNodeSocket *socket) return count; } -/* also used via rna api, so we check for proper input output direction */ bNodeLink *nodeAddLink( bNodeTree *ntree, bNode *fromnode, bNodeSocket *fromsock, bNode *tonode, bNodeSocket *tosock) { @@ -2855,8 +2807,8 @@ bNodeTree *ntreeCopyTree(Main *bmain, const bNodeTree *ntree) /* XXX this should be removed eventually ... * Currently BKE functions are modeled closely on previous code, * using BKE_node_preview_init_tree to set up previews for a whole node tree in advance. - * This should be left more to the individual node tree implementations. - */ + * This should be left more to the individual node tree implementations. */ + bool BKE_node_preview_used(const bNode *node) { /* XXX check for closed nodes? */ @@ -3089,9 +3041,6 @@ void BKE_node_preview_merge_tree(bNodeTree *to_ntree, bNodeTree *from_ntree, boo } } -/* hack warning! this function is only used for shader previews, and - * since it gets called multiple times per pixel for Ztransp we only - * add the color once. Preview gets cleared before it starts render though */ void BKE_node_preview_set_pixel( bNodePreview *preview, const float col[4], int x, int y, bool do_manage) { @@ -3115,7 +3064,6 @@ void BKE_node_preview_set_pixel( /* ************** Free stuff ********** */ -/* goes over entire tree */ void nodeUnlinkNode(bNodeTree *ntree, bNode *node) { LISTBASE_FOREACH_MUTABLE (bNodeLink *, link, &ntree->links) { @@ -3305,8 +3253,6 @@ static void free_localized_node_groups(bNodeTree *ntree) } } -/* Free (or release) any data used by this nodetree. Does not free the - * nodetree itself and does no ID user counting. */ void ntreeFreeTree(bNodeTree *ntree) { ntree_free_data(&ntree->id); @@ -3410,12 +3356,6 @@ void ntreeSetOutput(bNodeTree *ntree) * might be different for editor or for "real" use... */ } -/** - * Get address of potential node-tree pointer of given ID. - * - * \warning Using this function directly is potentially dangerous, if you don't know or are not - * sure, please use `ntreeFromID()` instead. - */ bNodeTree **BKE_ntree_ptr_from_id(ID *id) { switch (GS(id->name)) { @@ -3438,7 +3378,6 @@ bNodeTree **BKE_ntree_ptr_from_id(ID *id) } } -/* Returns the private NodeTree object of the datablock, if it has one. */ bNodeTree *ntreeFromID(ID *id) { bNodeTree **nodetree = BKE_ntree_ptr_from_id(id); @@ -3477,7 +3416,6 @@ void ntreeNodeFlagSet(const bNodeTree *ntree, const int flag, const bool enable) } } -/* returns localized tree for execution in threads */ bNodeTree *ntreeLocalize(bNodeTree *ntree) { if (ntree) { @@ -3516,9 +3454,6 @@ bNodeTree *ntreeLocalize(bNodeTree *ntree) return nullptr; } -/* sync local composite with real tree */ -/* local tree is supposed to be running, be careful moving previews! */ -/* is called by jobs manager, outside threads, so it doesn't happen during draw */ void ntreeLocalSync(bNodeTree *localtree, bNodeTree *ntree) { if (localtree && ntree) { @@ -3528,8 +3463,6 @@ void ntreeLocalSync(bNodeTree *localtree, bNodeTree *ntree) } } -/* merge local tree results back, and free local tree */ -/* we have to assume the editor already changed completely */ void ntreeLocalMerge(Main *bmain, bNodeTree *localtree, bNodeTree *ntree) { if (ntree && localtree) { @@ -3897,7 +3830,6 @@ static bNode *node_get_active_id_recursive(bNodeInstanceKey active_key, return nullptr; } -/* two active flags, ID nodes have special flag for buttons display */ bNode *nodeGetActiveID(bNodeTree *ntree, short idtype) { if (ntree) { @@ -3940,7 +3872,6 @@ bool nodeSetActiveID(bNodeTree *ntree, short idtype, ID *id) return ok; } -/* two active flags, ID nodes have special flag for buttons display */ void nodeClearActiveID(bNodeTree *ntree, short idtype) { if (ntree == nullptr) { @@ -3983,7 +3914,6 @@ void nodeClearActive(bNodeTree *ntree) } } -/* two active flags, ID nodes have special flag for buttons display */ void nodeSetActive(bNodeTree *ntree, bNode *node) { /* make sure only one node is active, and only one per ID type */ @@ -4052,10 +3982,6 @@ static void update_socket_declarations(ListBase *sockets, } } -/** - * Update `socket->declaration` for all sockets in the node. This assumes that the node declaration - * and sockets are up to date already. - */ void nodeSocketDeclarationsUpdate(bNode *node) { BLI_assert(node->declaration != nullptr); @@ -4063,10 +3989,6 @@ void nodeSocketDeclarationsUpdate(bNode *node) update_socket_declarations(&node->outputs, node->declaration->outputs()); } -/** - * Just update `node->declaration` if necessary. This can also be called on nodes that may not be - * up to date (e.g. because the need versioning or are dynamic). - */ bool nodeDeclarationEnsureOnOutdatedNode(bNodeTree *UNUSED(ntree), bNode *node) { if (node->declaration != nullptr) { @@ -4088,10 +4010,6 @@ bool nodeDeclarationEnsureOnOutdatedNode(bNodeTree *UNUSED(ntree), bNode *node) return true; } -/** - * If the node implements a `declare` function, this function makes sure that `node->declaration` - * is up to date. It is expected that the sockets of the node are up to date already. - */ bool nodeDeclarationEnsure(bNodeTree *ntree, bNode *node) { if (nodeDeclarationEnsureOnOutdatedNode(ntree, node)) { @@ -4156,7 +4074,6 @@ void BKE_node_clipboard_clear(void) #endif } -/* return false when one or more ID's are lost */ bool BKE_node_clipboard_validate(void) { bool ok = true; @@ -4258,7 +4175,6 @@ void BKE_node_clipboard_free(void) /* Node Instance Hash */ -/* magic number for initial hash key */ const bNodeInstanceKey NODE_INSTANCE_KEY_BASE = {5381}; const bNodeInstanceKey NODE_INSTANCE_KEY_NONE = {0}; @@ -5083,9 +4999,6 @@ static bool update_field_inferencing(bNodeTree &btree) } // namespace blender::bke::node_field_inferencing -/** - * \param tree_update_flag: #eNodeTreeUpdate enum. - */ void ntreeUpdateAllUsers(Main *main, ID *id, const int tree_update_flag) { if (id == nullptr) { @@ -5290,7 +5203,6 @@ void nodeLabel(bNodeTree *ntree, bNode *node, char *label, int maxlen) } } -/* Get node socket label if it is set */ const char *nodeSocketLabel(const bNodeSocket *sock) { return (sock->label[0] != '\0') ? sock->label : sock->name; @@ -5472,10 +5384,6 @@ void node_type_size_preset(struct bNodeType *ntype, eNodeSizePreset size) } } -/** - * \warning Nodes defining a storage type _must_ allocate this for new nodes. - * Otherwise nodes will reload as undefined (T46619). - */ void node_type_storage(bNodeType *ntype, const char *storagename, void (*freefunc)(struct bNode *node), diff --git a/source/blender/blenkernel/intern/object.cc b/source/blender/blenkernel/intern/object.cc index a73a8a75127..4327e7357d7 100644 --- a/source/blender/blenkernel/intern/object.cc +++ b/source/blender/blenkernel/intern/object.cc @@ -1456,12 +1456,6 @@ void BKE_object_modifier_gpencil_hook_reset(Object *ob, HookGpencilModifierData } } -/** - * Set the object's active modifier. - * - * \param md: If nullptr, only clear the active modifier, otherwise - * it must be in the #Object.modifiers list. - */ void BKE_object_modifier_set_active(Object *ob, ModifierData *md) { LISTBASE_FOREACH (ModifierData *, md_iter, &ob->modifiers) { @@ -1496,9 +1490,6 @@ ModifierData *BKE_object_active_modifier(const Object *ob) return nullptr; } -/** - * \return True if the object's type supports regular modifiers (not grease pencil modifiers). - */ bool BKE_object_supports_modifiers(const Object *ob) { return ( @@ -1576,17 +1567,6 @@ static ParticleSystem *object_copy_modifier_particle_system_ensure(Main *bmain, return psys_dst; } -/** - * Copy a single modifier. - * - * \note **Do not** use this function to copy a whole modifier stack (see note below too). Use - * `BKE_object_modifier_stack_copy` instead. - * - * \note Complex modifiers relaying on other data (like e.g. dynamic paint or fluid using particle - * systems) are not always 100% 'correctly' copied here, since we have to use heuristics to decide - * which particle system to use or add in `ob_dst`, and it's placement in the stack, etc. If used - * more than once, this function should preferably be called in stack order. - */ bool BKE_object_copy_modifier( Main *bmain, Scene *scene, Object *ob_dst, const Object *ob_src, ModifierData *md_src) { @@ -1686,12 +1666,6 @@ bool BKE_object_copy_modifier( return true; } -/** - * Copy a single GPencil modifier. - * - * \note **Do not** use this function to copy a whole modifier stack. Use - * `BKE_object_modifier_stack_copy` instead. - */ bool BKE_object_copy_gpencil_modifier(struct Object *ob_dst, GpencilModifierData *gmd_src) { BLI_assert(ob_dst->type == OB_GPENCIL); @@ -1709,15 +1683,6 @@ bool BKE_object_copy_gpencil_modifier(struct Object *ob_dst, GpencilModifierData return true; } -/** - * Copy the whole stack of modifiers from one object into another. - * - * \warning **Does not** clear modifier stack and related data (particle systems, soft-body, - * etc.) in `ob_dst`, if needed calling code must do it. - * - * \param do_copy_all: If true, even modifiers that should not support copying (like Hook one) - * will be duplicated. - */ bool BKE_object_modifier_stack_copy(Object *ob_dst, const Object *ob_src, const bool do_copy_all, @@ -1866,9 +1831,6 @@ static void object_update_from_subsurf_ccg(Object *object) subdiv_ccg->dirty.hidden = false; } -/** - * Assign #Object.data after modifier stack evaluation. - */ void BKE_object_eval_assign_data(Object *object_eval, ID *data_eval, bool is_owned) { BLI_assert(object_eval->id.tag & LIB_TAG_COPIED_ON_WRITE); @@ -1898,9 +1860,6 @@ void BKE_object_eval_assign_data(Object *object_eval, ID *data_eval, bool is_own object_eval->runtime.geometry_set_eval = nullptr; } -/** - * Free data derived from mesh, called when mesh changes or is freed. - */ void BKE_object_free_derived_caches(Object *ob) { MEM_SAFE_FREE(ob->runtime.bb); @@ -1995,9 +1954,6 @@ void BKE_object_free_caches(Object *object) } } -/** - * Actual check for internal data, not context or flags. - */ bool BKE_object_is_in_editmode(const Object *ob) { if (ob->data == nullptr) { @@ -2147,9 +2103,6 @@ bool BKE_object_is_mode_compat(const struct Object *ob, eObjectMode object_mode) return ((ob->mode == object_mode) || (ob->mode & object_mode) != 0); } -/** - * Return which parts of the object are visible, as evaluated by depsgraph - */ int BKE_object_visibility(const Object *ob, const int dag_eval_mode) { if ((ob->base_flag & BASE_VISIBLE_DEPSGRAPH) == 0) { @@ -2317,9 +2270,6 @@ void *BKE_object_obdata_add_from_type(Main *bmain, int type, const char *name) } } -/** - * Return -1 on failure. - */ int BKE_object_obdata_to_type(const ID *id) { /* Keep in sync with #OB_DATA_SUPPORT_ID macro. */ @@ -2355,9 +2305,6 @@ int BKE_object_obdata_to_type(const ID *id) } } -/** - * More general add: creates minimum required data, but without vertices etc. - */ Object *BKE_object_add_only_object(Main *bmain, int type, const char *name) { if (!name) { @@ -2387,14 +2334,6 @@ static Object *object_add_common(Main *bmain, ViewLayer *view_layer, int type, c return ob; } -/** - * General add: to scene, with layer from area and default name - * - * Object is added to the active #Collection. - * If there is no linked collection to the active #ViewLayer we create a new one. - * - * \note Creates minimum required data, but without vertices etc. - */ Object *BKE_object_add(Main *bmain, ViewLayer *view_layer, int type, const char *name) { Object *ob = object_add_common(bmain, view_layer, type, name); @@ -2408,11 +2347,6 @@ Object *BKE_object_add(Main *bmain, ViewLayer *view_layer, int type, const char return ob; } -/** - * Add a new object, using another one as a reference - * - * \param ob_src: object to use to determine the collections of the new object. - */ Object *BKE_object_add_from( Main *bmain, Scene *scene, ViewLayer *view_layer, int type, const char *name, Object *ob_src) { @@ -2425,15 +2359,6 @@ Object *BKE_object_add_from( return ob; } -/** - * Add a new object, but assign the given data-block as the `ob->data` - * for the newly created object. - * - * \param data: The data-block to assign as `ob->data` for the new object. - * This is assumed to be of the correct type. - * \param do_id_user: If true, #id_us_plus() will be called on data when - * assigning it to the object. - */ Object *BKE_object_add_for_data( Main *bmain, ViewLayer *view_layer, int type, const char *name, ID *data, bool do_id_user) { @@ -2685,9 +2610,6 @@ Object *BKE_object_pose_armature_get_visible(Object *ob, ViewLayer *view_layer, return nullptr; } -/** - * Access pose array with special check to get pose object when in weight paint mode. - */ Object **BKE_object_pose_array_get_ex(ViewLayer *view_layer, View3D *v3d, uint *r_objects_len, @@ -2782,17 +2704,6 @@ void BKE_object_transform_copy(Object *ob_tar, const Object *ob_src) copy_v3_v3(ob_tar->scale, ob_src->scale); } -/** - * Perform deep-copy of object and its 'children' data-blocks (obdata, materials, actions, etc.). - * - * \param dupflag: Controls which sub-data are also duplicated - * (see #eDupli_ID_Flags in DNA_userdef_types.h). - * - * \note This function does not do any remapping to new IDs, caller must do it - * (\a #BKE_libblock_relink_to_newid()). - * \note Caller MUST free \a newid pointers itself (#BKE_main_id_newptr_and_tag_clear()) and call - * updates of DEG too (#DAG_relations_tag_update()). - */ Object *BKE_object_duplicate(Main *bmain, Object *ob, uint dupflag, uint duplicate_options) { const bool is_subprocess = (duplicate_options & LIB_ID_DUPLICATE_IS_SUBPROCESS) != 0; @@ -2962,17 +2873,11 @@ Object *BKE_object_duplicate(Main *bmain, Object *ob, uint dupflag, uint duplica return obn; } -/** - * Returns true if the Object is from an external blend file (libdata). - */ bool BKE_object_is_libdata(const Object *ob) { return (ob && ID_IS_LINKED(ob)); } -/** - * Returns true if the Object data is from an external blend file (libdata). - */ bool BKE_object_obdata_is_libdata(const Object *ob) { /* Linked objects with local obdata are forbidden! */ @@ -3036,12 +2941,6 @@ void BKE_object_copy_proxy_drivers(Object *ob, Object *target) } } -/** - * Proxy rule: - * - lib_object->proxy_from == the one we borrow from, set temporally while object_update. - * - local_object->proxy == pointer to library object, saved in files and read. - * - local_object->proxy_group == pointer to collection dupli-object, saved in files and read. - */ void BKE_object_make_proxy(Main *bmain, Object *ob, Object *target, Object *cob) { /* paranoia checks */ @@ -3141,10 +3040,6 @@ void BKE_object_make_proxy(Main *bmain, Object *ob, Object *target, Object *cob) ob->dt = target->dt; } -/** - * Use with newly created objects to set their size - * (used to apply scene-scale). - */ void BKE_object_obdata_size_init(struct Object *ob, const float size) { /* apply radius as a scale to types that support it */ @@ -3783,12 +3678,6 @@ void BKE_object_where_is_calc_time(Depsgraph *depsgraph, Scene *scene, Object *o object_where_is_calc_ex(depsgraph, scene, ob, ctime, nullptr, nullptr); } -/** - * Calculate object transformation matrix without recalculating dependencies and - * constraints -- assume dependencies are already solved by depsgraph. - * No changes to object and its parent would be done. - * Used for bundles orientation in 3d space relative to parented blender camera. - */ void BKE_object_where_is_calc_mat4(Object *ob, float r_obmat[4][4]) { if (ob->parent) { @@ -3812,14 +3701,6 @@ void BKE_object_where_is_calc(Depsgraph *depsgraph, Scene *scene, Object *ob) object_where_is_calc_ex(depsgraph, scene, ob, ctime, nullptr, nullptr); } -/** - * For calculation of the inverse parent transform, only used for editor. - * - * It assumes the object parent is already in the depsgraph. - * Otherwise, after changing ob->parent you need to call: - * - #DEG_relations_tag_update(bmain); - * - #BKE_scene_graph_update_tagged(depsgraph, bmain); - */ void BKE_object_workob_calc_parent(Depsgraph *depsgraph, Scene *scene, Object *ob, Object *workob) { BKE_object_workob_clear(workob); @@ -3851,16 +3732,6 @@ void BKE_object_workob_calc_parent(Depsgraph *depsgraph, Scene *scene, Object *o BKE_object_where_is_calc(depsgraph, scene, workob); } -/** - * Applies the global transformation \a mat to the \a ob using a relative parent space if - * supplied. - * - * \param mat: the global transformation mat that the object should be set object to. - * \param parent: the parent space in which this object will be set relative to - * (should probably always be parent_eval). - * \param use_compat: true to ensure that rotations are set using the - * min difference between the old and new orientation. - */ void BKE_object_apply_mat4_ex(Object *ob, const float mat[4][4], Object *parent, @@ -4010,9 +3881,6 @@ BoundBox *BKE_object_boundbox_get(Object *ob) return bb; } -/** - * Use this to temporally disable/enable bound-box. - */ void BKE_object_boundbox_flag(Object *ob, int flag, const bool set) { BoundBox *bb = BKE_object_boundbox_get(ob); @@ -4102,14 +3970,6 @@ void BKE_object_dimensions_get(Object *ob, float r_vec[3]) } } -/** - * The original scale and object matrix can be passed in so any difference - * of the objects matrix and the final matrix can be accounted for, - * typically this caused by parenting, constraints or delta-scale. - * - * Re-using these values from the object causes a feedback loop - * when multiple values are modified at once in some situations. see: T69536. - */ void BKE_object_dimensions_set_ex(Object *ob, const float value[3], int axis_mask, @@ -4528,19 +4388,6 @@ static void object_handle_update_proxy(Depsgraph *depsgraph, } } -/** - * Proxy rule: - * - lib_object->proxy_from == the one we borrow from, only set temporal and cleared here. - * - local_object->proxy == pointer to library object, saved in files and read. - * - * Function below is polluted with proxy exceptions, cleanup will follow! - * - * The main object update call, for object matrix, constraints, keys and displist (modifiers) - * requires flags to be set! - * - * Ideally we shouldn't have to pass the rigid body world, - * but need bigger restructuring to avoid id. - */ void BKE_object_handle_update_ex(Depsgraph *depsgraph, Scene *scene, Object *ob, @@ -4595,13 +4442,6 @@ void BKE_object_handle_update_ex(Depsgraph *depsgraph, object_handle_update_proxy(depsgraph, scene, ob, do_proxy_update); } -/** - * \warning "scene" here may not be the scene object actually resides in. - * When dealing with background-sets, "scene" is actually the active scene. - * e.g. "scene" <-- set 1 <-- set 2 ("ob" lives here) <-- set 3 <-- ... <-- set n - * rigid bodies depend on their world so use #BKE_object_handle_update_ex() - * to also pass along the current rigid body world. - */ void BKE_object_handle_update(Depsgraph *depsgraph, Scene *scene, Object *ob) { BKE_object_handle_update_ex(depsgraph, scene, ob, nullptr, true); @@ -4659,7 +4499,6 @@ bool BKE_object_obdata_texspace_get(Object *ob, short **r_texflag, float **r_loc return true; } -/** Get evaluated mesh for given object. */ Mesh *BKE_object_get_evaluated_mesh(const Object *object) { /* First attempt to retrieve the evaluated mesh from the evaluated geometry set. Most @@ -4687,13 +4526,6 @@ Mesh *BKE_object_get_evaluated_mesh(const Object *object) return nullptr; } -/** - * Get mesh which is not affected by modifiers: - * - For original objects it will be same as `object->data`, and it is a mesh - * which is in the corresponding #Main. - * - For copied-on-write objects it will give pointer to a copied-on-write - * mesh which corresponds to original object's mesh. - */ Mesh *BKE_object_get_pre_modified_mesh(const Object *object) { if (object->type == OB_MESH && object->runtime.data_orig != nullptr) { @@ -4709,12 +4541,6 @@ Mesh *BKE_object_get_pre_modified_mesh(const Object *object) return (Mesh *)object->data; } -/** - * Get a mesh which corresponds to the very original mesh from #Main. - * - For original objects it will be object->data. - * - For evaluated objects it will be same mesh as corresponding original - * object uses as data. - */ Mesh *BKE_object_get_original_mesh(const Object *object) { Mesh *result = nullptr; @@ -5087,10 +4913,6 @@ bool BKE_object_is_child_recursive(const Object *ob_parent, const Object *ob_chi return false; } -/** - * Most important if this is modified it should _always_ return true, in certain - * cases false positives are hard to avoid (shape keys for example). - */ int BKE_object_is_modified(Scene *scene, Object *ob) { /* Always test on original object since evaluated object may no longer @@ -5124,21 +4946,6 @@ int BKE_object_is_modified(Scene *scene, Object *ob) return flag; } -/** - * Check of objects moves in time. - * - * \note This function is currently optimized for usage in combination - * with modifier deformation checks (#eModifierTypeType_OnlyDeform), - * so modifiers can quickly check if their target objects moves - * (causing deformation motion blur) or not. - * - * This makes it possible to give some degree of false-positives here, - * but it's currently an acceptable tradeoff between complexity and check - * speed. In combination with checks of modifier stack and real life usage - * percentage of false-positives shouldn't be that high. - * - * \note This function does not consider physics systems. - */ bool BKE_object_moves_in_time(const Object *object, bool recurse_parent) { /* If object has any sort of animation data assume it is moving. */ @@ -5234,11 +5041,6 @@ static bool modifiers_has_animation_check(const Object *ob) return false; } -/** - * Test if object is affected by deforming modifiers (for motion blur). again - * most important is to avoid false positives, this is to skip computations - * and we can still if there was actual deformation afterwards. - */ int BKE_object_is_deform_modified(Scene *scene, Object *ob) { /* Always test on original object since evaluated object may no longer @@ -5288,7 +5090,6 @@ int BKE_object_is_deform_modified(Scene *scene, Object *ob) return flag; } -/** Return the number of scenes using (instantiating) that object in their collections. */ int BKE_object_scenes_users_get(Main *bmain, Object *ob) { int num_scenes = 0; @@ -5333,9 +5134,6 @@ void BKE_object_runtime_reset(Object *object) memset(&object->runtime, 0, sizeof(object->runtime)); } -/** - * Reset all pointers which we don't want to be shared when copying the object. - */ void BKE_object_runtime_reset_on_copy(Object *object, const int UNUSED(flag)) { Object_Runtime *runtime = &object->runtime; @@ -5348,12 +5146,6 @@ void BKE_object_runtime_reset_on_copy(Object *object, const int UNUSED(flag)) runtime->geometry_set_eval = nullptr; } -/** - * The function frees memory used by the runtime data, but not the runtime field itself. - * - * All runtime data is cleared to ensure it's not used again, - * in keeping with other `_free_data(..)` functions. - */ void BKE_object_runtime_free_data(Object *object) { /* Currently this is all that's needed. */ @@ -5395,13 +5187,6 @@ static void obrel_list_add(LinkNode **links, Object *ob) ob->id.tag |= LIB_TAG_DOIT; } -/** - * Iterates over all objects of the given scene layer. - * Depending on the #eObjectSet flag: - * collect either #OB_SET_ALL, #OB_SET_VISIBLE or #OB_SET_SELECTED objects. - * If #OB_SET_VISIBLE or#OB_SET_SELECTED are collected, - * then also add related objects according to the given \a includeFilter. - */ LinkNode *BKE_object_relational_superset(struct ViewLayer *view_layer, eObjectSet objectSet, eObRelationTypes includeFilter) @@ -5479,9 +5264,6 @@ LinkNode *BKE_object_relational_superset(struct ViewLayer *view_layer, return links; } -/** - * return all groups this object is a part of, caller must free. - */ struct LinkNode *BKE_object_groups(Main *bmain, Scene *scene, Object *ob) { LinkNode *collection_linknode = nullptr; @@ -5502,15 +5284,6 @@ void BKE_object_groups_clear(Main *bmain, Scene *scene, Object *ob) } } -/** - * Return a KDTree_3d from the deformed object (in world-space). - * - * \note Only mesh objects currently support deforming, others are TODO. - * - * \param ob: - * \param r_tot: - * \return The kdtree or nullptr if it can't be created. - */ KDTree_3d *BKE_object_as_kdtree(Object *ob, int *r_tot) { KDTree_3d *tree = nullptr; @@ -5773,10 +5546,6 @@ static void object_cacheIgnoreClear(Object *ob, int state) BLI_freelistN(&pidlist); } -/** - * \note this function should eventually be replaced by depsgraph functionality. - * Avoid calling this in new code unless there is a very good reason for it! - */ bool BKE_object_modifier_update_subframe(Depsgraph *depsgraph, Scene *scene, Object *ob, @@ -5880,9 +5649,6 @@ bool BKE_object_modifier_update_subframe(Depsgraph *depsgraph, return false; } -/** - * Updates select_id of all objects in the given \a bmain. - */ void BKE_object_update_select_id(struct Main *bmain) { Object *ob = (Object *)bmain->objects.first; diff --git a/source/blender/blenkernel/intern/object_deform.c b/source/blender/blenkernel/intern/object_deform.c index 511f5d4ae66..362258c6a8a 100644 --- a/source/blender/blenkernel/intern/object_deform.c +++ b/source/blender/blenkernel/intern/object_deform.c @@ -63,13 +63,6 @@ static Lattice *object_defgroup_lattice_get(ID *id) return (lt->editlatt) ? lt->editlatt->latt : lt; } -/** - * Update users of vgroups from this object, according to given map. - * - * Use it when you remove or reorder vgroups in the object. - * - * \param map: an array mapping old indices to new indices. - */ void BKE_object_defgroup_remap_update_users(Object *ob, const int *map) { ModifierData *md; @@ -112,9 +105,6 @@ void BKE_object_defgroup_remap_update_users(Object *ob, const int *map) /** \name Group creation * \{ */ -/** - * Add a vgroup of given name to object. *Does not* handle MDeformVert data at all! - */ bDeformGroup *BKE_object_defgroup_add_name(Object *ob, const char *name) { bDeformGroup *defgroup; @@ -129,17 +119,12 @@ bDeformGroup *BKE_object_defgroup_add_name(Object *ob, const char *name) return defgroup; } -/** - * Add a vgroup of default name to object. *Does not* handle MDeformVert data at all! - */ bDeformGroup *BKE_object_defgroup_add(Object *ob) { return BKE_object_defgroup_add_name(ob, DATA_("Group")); } -/** - * Create MDeformVert data for given ID. Work in Object mode only. - */ +/* Can't include BKE_object_deform.h right now, due to an enum forward declaration. */ MDeformVert *BKE_object_defgroup_data_create(ID *id) { if (GS(id->name) == ID_ME) { @@ -162,12 +147,6 @@ MDeformVert *BKE_object_defgroup_data_create(ID *id) /** \name Group clearing * \{ */ -/** - * Remove all verts (or only selected ones) from given vgroup. Work in Object and Edit modes. - * - * \param use_selection: Only operate on selection. - * \return True if any vertex was removed, false otherwise. - */ bool BKE_object_defgroup_clear(Object *ob, bDeformGroup *dg, const bool use_selection) { MDeformVert *dv; @@ -239,12 +218,6 @@ bool BKE_object_defgroup_clear(Object *ob, bDeformGroup *dg, const bool use_sele return changed; } -/** - * Remove all verts (or only selected ones) from all vgroups. Work in Object and Edit modes. - * - * \param use_selection: Only operate on selection. - * \return True if any vertex was removed, false otherwise. - */ bool BKE_object_defgroup_clear_all(Object *ob, const bool use_selection) { bDeformGroup *dg; @@ -406,9 +379,6 @@ static void object_defgroup_remove_edit_mode(Object *ob, bDeformGroup *dg) object_defgroup_remove_common(ob, dg, def_nr); } -/** - * Remove given vgroup from object. Work in Object and Edit modes. - */ void BKE_object_defgroup_remove(Object *ob, bDeformGroup *defgroup) { if (ob->type == OB_GPENCIL) { @@ -426,10 +396,6 @@ void BKE_object_defgroup_remove(Object *ob, bDeformGroup *defgroup) } } -/** - * Remove all vgroups from object. Work in Object and Edit modes. - * When only_unlocked=true, locked vertex groups are not removed. - */ void BKE_object_defgroup_remove_all_ex(struct Object *ob, bool only_unlocked) { ListBase *defbase = BKE_object_defgroup_list_mutable(ob); @@ -469,19 +435,11 @@ void BKE_object_defgroup_remove_all_ex(struct Object *ob, bool only_unlocked) } } -/** - * Remove all vgroups from object. Work in Object and Edit modes. - */ void BKE_object_defgroup_remove_all(struct Object *ob) { BKE_object_defgroup_remove_all_ex(ob, false); } -/** - * Compute mapping for vertex groups with matching name, -1 is used for no remapping. - * Returns null if no remapping is required. - * The returned array has to be freed. - */ int *BKE_object_defgroup_index_map_create(Object *ob_src, Object *ob_dst, int *r_map_len) { const ListBase *src_defbase = BKE_object_defgroup_list(ob_src); @@ -549,11 +507,6 @@ void BKE_object_defgroup_index_map_apply(MDeformVert *dvert, } } -/** - * Get MDeformVert vgroup data from given object. Should only be used in Object mode. - * - * \return True if the id type supports weights. - */ bool BKE_object_defgroup_array_get(ID *id, MDeformVert **dvert_arr, int *dvert_tot) { if (id) { @@ -583,10 +536,6 @@ bool BKE_object_defgroup_array_get(ID *id, MDeformVert **dvert_arr, int *dvert_t /* --- functions for getting vgroup aligned maps --- */ -/** - * gets the status of "flag" for each bDeformGroup - * in the object data's vertex group list and returns an array containing them - */ bool *BKE_object_defgroup_lock_flags_get(Object *ob, const int defbase_tot) { bool is_locked = false; @@ -675,8 +624,6 @@ bool *BKE_object_defgroup_validmap_get(Object *ob, const int defbase_tot) return defgroup_validmap; } -/* Returns total selected vgroups, - * wpi.defbase_sel is assumed malloc'd, all values are set */ bool *BKE_object_defgroup_selected_get(Object *ob, int defbase_tot, int *r_dg_flags_sel_tot) { bool *dg_selection = MEM_mallocN(defbase_tot * sizeof(bool), __func__); @@ -708,11 +655,6 @@ bool *BKE_object_defgroup_selected_get(Object *ob, int defbase_tot, int *r_dg_fl return dg_selection; } -/** - * Checks if the lock relative mode is applicable. - * - * \return true if an unlocked deform group is active. - */ bool BKE_object_defgroup_check_lock_relative(const bool *lock_flags, const bool *validmap, int index) @@ -720,11 +662,6 @@ bool BKE_object_defgroup_check_lock_relative(const bool *lock_flags, return validmap && validmap[index] && !(lock_flags && lock_flags[index]); } -/** - * Additional check for whether the lock relative mode is applicable in multi-paint mode. - * - * \return true if none of the selected groups are locked. - */ bool BKE_object_defgroup_check_lock_relative_multi(int defbase_tot, const bool *lock_flags, const bool *selected, @@ -747,11 +684,6 @@ bool BKE_object_defgroup_check_lock_relative_multi(int defbase_tot, return true; } -/** - * Takes a pair of boolean masks of all locked and all deform groups, and computes - * a pair of masks for locked deform and unlocked deform groups. Output buffers may - * reuse the input ones. - */ void BKE_object_defgroup_split_locked_validmap( int defbase_tot, const bool *locked, const bool *deform, bool *r_locked, bool *r_unlocked) { @@ -774,11 +706,6 @@ void BKE_object_defgroup_split_locked_validmap( } } -/** - * Marks mirror vgroups in output and counts them. - * Output and counter assumed to be already initialized. - * Designed to be usable after BKE_object_defgroup_selected_get to extend selection to mirror. - */ void BKE_object_defgroup_mirror_selection(struct Object *ob, int defbase_tot, const bool *dg_selection, @@ -808,9 +735,6 @@ void BKE_object_defgroup_mirror_selection(struct Object *ob, } } -/** - * Return the subset type of the Vertex Group Selection - */ bool *BKE_object_defgroup_subset_from_select_type(Object *ob, eVGroupSelect subset_type, int *r_defgroup_tot, @@ -873,9 +797,6 @@ bool *BKE_object_defgroup_subset_from_select_type(Object *ob, return defgroup_validmap; } -/** - * store indices from the defgroup_validmap (faster lookups in some cases) - */ void BKE_object_defgroup_subset_to_index_array(const bool *defgroup_validmap, const int defgroup_tot, int *r_defgroup_subset_map) diff --git a/source/blender/blenkernel/intern/object_dupli.cc b/source/blender/blenkernel/intern/object_dupli.cc index 442755be15d..76f1fecfdf3 100644 --- a/source/blender/blenkernel/intern/object_dupli.cc +++ b/source/blender/blenkernel/intern/object_dupli.cc @@ -1678,9 +1678,6 @@ static const DupliGenerator *get_dupli_generator(const DupliContext *ctx) /** \name Dupli-Container Implementation * \{ */ -/** - * \return a #ListBase of #DupliObject. - */ ListBase *object_duplilist(Depsgraph *depsgraph, Scene *sce, Object *ob) { ListBase *duplilist = (ListBase *)MEM_callocN(sizeof(ListBase), "duplilist"); diff --git a/source/blender/blenkernel/intern/object_update.c b/source/blender/blenkernel/intern/object_update.c index 34a899b2e91..4c0d0303c1f 100644 --- a/source/blender/blenkernel/intern/object_update.c +++ b/source/blender/blenkernel/intern/object_update.c @@ -67,14 +67,6 @@ #include "DEG_depsgraph.h" #include "DEG_depsgraph_query.h" -/** - * Restore the object->data to a non-modifier evaluated state. - * - * Some changes done directly in evaluated object require them to be reset - * before being re-evaluated. - * For example, we need to call this before #BKE_mesh_new_from_object(), - * in case we removed/added modifiers in the evaluated object. - */ void BKE_object_eval_reset(Object *ob_eval) { BKE_object_free_derived_caches(ob_eval); @@ -88,10 +80,10 @@ void BKE_object_eval_local_transform(Depsgraph *depsgraph, Object *ob) BKE_object_to_mat4(ob, ob->obmat); } -/* Evaluate parent */ -/* NOTE: based on solve_parenting(), but with the cruft stripped out */ void BKE_object_eval_parent(Depsgraph *depsgraph, Object *ob) { + /* NOTE: based on `solve_parenting()`, but with the cruft stripped out. */ + Object *par = ob->parent; float totmat[4][4]; diff --git a/source/blender/blenkernel/intern/ocean.c b/source/blender/blenkernel/intern/ocean.c index e9683d3b52c..97326c24a61 100644 --- a/source/blender/blenkernel/intern/ocean.c +++ b/source/blender/blenkernel/intern/ocean.c @@ -270,7 +270,6 @@ void BKE_ocean_eval_uv(struct Ocean *oc, struct OceanResult *ocr, float u, float BLI_rw_mutex_unlock(&oc->oceanmutex); } -/* use catmullrom interpolation rather than linear */ void BKE_ocean_eval_uv_catrom(struct Ocean *oc, struct OceanResult *ocr, float u, float v) { int i0, i1, i2, i3, j0, j1, j2, j3; @@ -378,8 +377,6 @@ void BKE_ocean_eval_xz_catrom(struct Ocean *oc, struct OceanResult *ocr, float x BKE_ocean_eval_uv_catrom(oc, ocr, x / oc->_Lx, z / oc->_Lz); } -/* note that this doesn't wrap properly for i, j < 0, but its not really meant for that being - * just a way to get the raw data out to save in some image format. */ void BKE_ocean_eval_ij(struct Ocean *oc, struct OceanResult *ocr, int i, int j) { BLI_rw_mutex_lock(&oc->oceanmutex, THREAD_LOCK_READ); @@ -650,9 +647,6 @@ static void ocean_compute_normal_z(TaskPool *__restrict pool, void *UNUSED(taskd fftw_execute(o->_N_z_plan); } -/** - * Return true if the ocean is valid and can be used. - */ bool BKE_ocean_is_valid(const struct Ocean *o) { return o->_k != NULL; @@ -777,9 +771,6 @@ bool BKE_ocean_ensure(struct OceanModifierData *omd, const int resolution) return true; } -/** - * Return true if the ocean data is valid and can be used. - */ bool BKE_ocean_init_from_modifier(struct Ocean *ocean, struct OceanModifierData const *omd, const int resolution) @@ -818,9 +809,6 @@ bool BKE_ocean_init_from_modifier(struct Ocean *ocean, omd->seed); } -/** - * Return true if the ocean data is valid and can be used. - */ bool BKE_ocean_init(struct Ocean *o, int M, int N, diff --git a/source/blender/blenkernel/intern/ocean_spectrum.c b/source/blender/blenkernel/intern/ocean_spectrum.c index c5504b22b43..43e0f399213 100644 --- a/source/blender/blenkernel/intern/ocean_spectrum.c +++ b/source/blender/blenkernel/intern/ocean_spectrum.c @@ -128,11 +128,6 @@ static float jonswap(const Ocean *oc, const float k2) return val; } -/** - * Pierson-Moskowitz model, 1964, assumes waves reach equilibrium with wind. - * Model is intended for large area 'fully developed' sea, where winds have been steadily blowing - * for days over an area that includes hundreds of wavelengths on a side. - */ float BLI_ocean_spectrum_piersonmoskowitz(const Ocean *oc, const float kx, const float kz) { const float k2 = kx * kx + kz * kz; @@ -159,10 +154,6 @@ float BLI_ocean_spectrum_piersonmoskowitz(const Ocean *oc, const float kx, const return val; } -/** - * TMA extends the JONSWAP spectrum. - * This spectral model is best suited to shallow water. - */ float BLI_ocean_spectrum_texelmarsenarsloe(const Ocean *oc, const float kx, const float kz) { const float k2 = kx * kx + kz * kz; @@ -195,14 +186,6 @@ float BLI_ocean_spectrum_texelmarsenarsloe(const Ocean *oc, const float kx, cons return val; } -/** - * Hasselmann et al, 1973. This model extends the Pierson-Moskowitz model with a peak sharpening - * function This enhancement is an artificial construct to address the problem that the wave - * spectrum is never fully developed. - * - * The fetch parameter represents the distance from a lee shore, - * called the fetch, or the distance over which the wind blows with constant velocity. - */ float BLI_ocean_spectrum_jonswap(const Ocean *oc, const float kx, const float kz) { const float k2 = kx * kx + kz * kz; diff --git a/source/blender/blenkernel/intern/packedFile.c b/source/blender/blenkernel/intern/packedFile.c index f0f8343420d..8989450e41b 100644 --- a/source/blender/blenkernel/intern/packedFile.c +++ b/source/blender/blenkernel/intern/packedFile.c @@ -242,7 +242,6 @@ PackedFile *BKE_packedfile_new(ReportList *reports, const char *filename, const return pf; } -/* no libraries for now */ void BKE_packedfile_pack_all(Main *bmain, ReportList *reports, bool verbose) { Image *ima; @@ -373,14 +372,6 @@ int BKE_packedfile_write_to_file(ReportList *reports, return ret_value; } -/** - * This function compares a packed file to a 'real' file. - * It returns an integer indicating if: - * - * - PF_EQUAL: the packed file and original file are identical - * - PF_DIFFERENT: the packed file and original file differ - * - PF_NOFILE: the original file doesn't exist - */ enum ePF_FileCompare BKE_packedfile_compare_to_file(const char *ref_file_name, const char *filename, PackedFile *pf) @@ -434,16 +425,6 @@ enum ePF_FileCompare BKE_packedfile_compare_to_file(const char *ref_file_name, return ret_val; } -/** - * #BKE_packedfile_unpack_to_file() looks at the existing files (abs_name, local_name) - * and a packed file. - * - * It returns a char *to the existing file name / new file name or NULL when - * there was an error or when the user decides to cancel the operation. - * - * \warning 'abs_name' may be relative still! (use a "//" prefix) - * be sure to run #BLI_path_abs on it first. - */ char *BKE_packedfile_unpack_to_file(ReportList *reports, const char *ref_file_name, const char *abs_name, @@ -804,7 +785,6 @@ void BKE_packedfile_unpack_all(Main *bmain, ReportList *reports, enum ePF_FileSt } } -/* ID should be not NULL, return 1 if there's a packed file */ bool BKE_packedfile_id_check(const ID *id) { switch (GS(id->name)) { @@ -834,7 +814,6 @@ bool BKE_packedfile_id_check(const ID *id) return false; } -/* ID should be not NULL */ void BKE_packedfile_id_unpack(Main *bmain, ID *id, ReportList *reports, enum ePF_FileStatus how) { switch (GS(id->name)) { diff --git a/source/blender/blenkernel/intern/paint.c b/source/blender/blenkernel/intern/paint.c index f419bef64a0..72210eea71d 100644 --- a/source/blender/blenkernel/intern/paint.c +++ b/source/blender/blenkernel/intern/paint.c @@ -727,7 +727,6 @@ void BKE_paint_curve_clamp_endpoint_add_index(PaintCurve *pc, const int add_inde pc->add_index = (add_index || pc->tot_points == 1) ? (add_index + 1) : 0; } -/** Remove color from palette. Must be certain color is inside the palette! */ void BKE_palette_color_remove(Palette *palette, PaletteColor *color) { if (BLI_listbase_count_at_most(&palette->colors, palette->active_color) == @@ -966,7 +965,6 @@ bool BKE_palette_from_hash(Main *bmain, GHash *color_table, const char *name, co return done; } -/* are we in vertex paint or weight paint face select mode? */ bool BKE_paint_select_face_test(Object *ob) { return ((ob != NULL) && (ob->type == OB_MESH) && (ob->data != NULL) && @@ -974,7 +972,6 @@ bool BKE_paint_select_face_test(Object *ob) (ob->mode & (OB_MODE_VERTEX_PAINT | OB_MODE_WEIGHT_PAINT | OB_MODE_TEXTURE_PAINT))); } -/* are we in weight paint vertex select mode? */ bool BKE_paint_select_vert_test(Object *ob) { return ((ob != NULL) && (ob->type == OB_MESH) && (ob->data != NULL) && @@ -982,10 +979,6 @@ bool BKE_paint_select_vert_test(Object *ob) (ob->mode & OB_MODE_WEIGHT_PAINT || ob->mode & OB_MODE_VERTEX_PAINT)); } -/** - * used to check if selection is possible - * (when we don't care if its face or vert) - */ bool BKE_paint_select_elem_test(Object *ob) { return (BKE_paint_select_vert_test(ob) || BKE_paint_select_face_test(ob)); @@ -1028,9 +1021,6 @@ eObjectMode BKE_paint_object_mode_from_paintmode(ePaintMode mode) } } -/** - * Call when entering each respective paint mode. - */ bool BKE_paint_ensure(ToolSettings *ts, struct Paint **r_paint) { Paint *paint = NULL; @@ -1151,10 +1141,6 @@ void BKE_paint_free(Paint *paint) MEM_SAFE_FREE(paint->tool_slots); } -/* called when copying scene settings, so even if 'src' and 'tar' are the same - * still do a id_us_plus(), rather than if we were copying between 2 existing - * scenes where a matching value should decrease the existing user count as - * with paint_brush_set() */ void BKE_paint_copy(Paint *src, Paint *tar, const int flag) { tar->brush = src->brush; @@ -1234,8 +1220,6 @@ void BKE_paint_blend_read_lib(BlendLibReader *reader, Scene *sce, Paint *p) } } -/* returns non-zero if any of the face's vertices - * are hidden, zero otherwise */ bool paint_is_face_hidden(const MLoopTri *lt, const MVert *mvert, const MLoop *mloop) { return ((mvert[mloop[lt->tri[0]].v].flag & ME_HIDE) || @@ -1243,9 +1227,6 @@ bool paint_is_face_hidden(const MLoopTri *lt, const MVert *mvert, const MLoop *m (mvert[mloop[lt->tri[2]].v].flag & ME_HIDE)); } -/* returns non-zero if any of the corners of the grid - * face whose inner corner is at (x, y) are hidden, - * zero otherwise */ bool paint_is_grid_face_hidden(const uint *grid_hidden, int gridsize, int x, int y) { /* skip face if any of its corners are hidden */ @@ -1255,7 +1236,6 @@ bool paint_is_grid_face_hidden(const uint *grid_hidden, int gridsize, int x, int BLI_BITMAP_TEST(grid_hidden, (y + 1) * gridsize + x)); } -/* Return true if all vertices in the face are visible, false otherwise */ bool paint_is_bmesh_face_hidden(BMFace *f) { BMLoop *l_iter; @@ -1524,8 +1504,6 @@ void BKE_sculptsession_free(Object *ob) } } -/* Sculpt mode handles multires differently from regular meshes, but only if - * it's the last modifier on the stack and it is not on the first level */ MultiresModifierData *BKE_sculpt_multires_active(Scene *scene, Object *ob) { Mesh *me = (Mesh *)ob->data; @@ -1815,7 +1793,6 @@ void BKE_sculpt_color_layer_create_if_needed(struct Object *object) DEG_id_tag_update(&orig_me->id, ID_RECALC_GEOMETRY_ALL_MODES); } -/** \warning Expects a fully evaluated depsgraph. */ void BKE_sculpt_update_object_for_edit( Depsgraph *depsgraph, Object *ob_orig, bool need_pmap, bool need_mask, bool need_colors) { @@ -1945,10 +1922,6 @@ static bool check_sculpt_object_deformed(Object *object, const bool for_construc return deformed; } -/** - * Ensures that a Face Set data-layers exists. If it does not, it creates one respecting the - * visibility stored in the vertices of the mesh. If it does, it copies the visibility from the - * mesh to the Face Sets. */ void BKE_sculpt_face_sets_ensure_from_base_mesh_visibility(Mesh *mesh) { const int face_sets_default_visible_id = 1; @@ -2050,12 +2023,6 @@ void BKE_sculpt_sync_face_set_visibility(struct Mesh *mesh, struct SubdivCCG *su BKE_sculpt_sync_face_sets_visibility_to_grids(mesh, subdiv_ccg); } -/** - * Ensures we do have expected mesh data in original mesh for the sculpt mode. - * - * \note IDs are expected to be original ones here, and calling code should ensure it updates its - * depsgraph properly after calling this function if it needs up-to-date evaluated data. - */ void BKE_sculpt_ensure_orig_mesh_data(Scene *scene, Object *object) { Mesh *mesh = BKE_mesh_from_object(object); @@ -2227,8 +2194,6 @@ void BKE_sculpt_bvh_update_from_ccg(PBVH *pbvh, SubdivCCG *subdiv_ccg) subdiv_ccg->grid_hidden); } -/* Test if PBVH can be used directly for drawing, which is faster than - * drawing the mesh and all updates that come with it. */ bool BKE_sculptsession_use_pbvh_draw(const Object *ob, const View3D *v3d) { SculptSession *ss = ob->sculpt; diff --git a/source/blender/blenkernel/intern/paint_toolslots.c b/source/blender/blenkernel/intern/paint_toolslots.c index 0ea0173f8a3..bdb7b483997 100644 --- a/source/blender/blenkernel/intern/paint_toolslots.c +++ b/source/blender/blenkernel/intern/paint_toolslots.c @@ -140,10 +140,6 @@ void BKE_paint_toolslots_brush_update(Paint *paint) BKE_paint_toolslots_brush_update_ex(paint, paint->brush); } -/** - * Run this to ensure brush types are set for each slot on entering modes - * (for new scenes for example). - */ void BKE_paint_toolslots_brush_validate(Main *bmain, Paint *paint) { /* Clear slots with invalid slots or mode (unlikely but possible). */ diff --git a/source/blender/blenkernel/intern/particle.c b/source/blender/blenkernel/intern/particle.c index b868ee57289..18b3d69d59f 100644 --- a/source/blender/blenkernel/intern/particle.c +++ b/source/blender/blenkernel/intern/particle.c @@ -556,7 +556,6 @@ static void get_cpa_texture(Mesh *mesh, int event, float cfra); -/* few helpers for countall etc. */ int count_particles(ParticleSystem *psys) { ParticleSettings *part = psys->part; @@ -646,7 +645,7 @@ static void psys_free_path_cache_buffers(ParticleCacheKey **cache, ListBase *buf /************************************************/ /* Getting stuff */ /************************************************/ -/* get object's active particle system safely */ + ParticleSystem *psys_get_current(Object *ob) { ParticleSystem *psys; @@ -914,9 +913,11 @@ int psys_uses_gravity(ParticleSimulationData *sim) return sim->scene->physics_settings.flag & PHYS_GLOBAL_GRAVITY && sim->psys->part && sim->psys->part->effector_weights->global_gravity != 0.0f; } + /************************************************/ /* Freeing stuff */ /************************************************/ + static void fluid_free_settings(SPHFluidSettings *fluid) { if (fluid) { @@ -1056,7 +1057,6 @@ void psys_free_pdd(ParticleSystem *psys) psys->pdd->partsize = 0; } } -/* free everything */ void psys_free(Object *ob, ParticleSystem *psys) { if (psys) { @@ -1204,6 +1204,7 @@ void psys_copy_particles(ParticleSystem *psys_dst, ParticleSystem *psys_src) /************************************************/ /* Interpolation */ /************************************************/ + static float interpolate_particle_value( float v1, float v2, float v3, float v4, const float w[4], int four) { @@ -1671,7 +1672,7 @@ static void interpolate_pathcache(ParticleCacheKey *first, float t, ParticleCach /************************************************/ /* Particles on a dm */ /************************************************/ -/* interpolate a location on a face based on face coordinates */ + void psys_interpolate_face(MVert *mvert, MFace *mface, MTFace *tface, @@ -1903,18 +1904,6 @@ static void psys_origspace_to_w(OrigSpaceFace *osface, int quad, const float w[4 } } -/** - * Find the final derived mesh tessface for a particle, from its original tessface index. - * This is slow and can be optimized but only for many lookups. - * - * \param mesh_final: Final mesh, it may not have the same topology as original mesh. - * \param mesh_original: Original mesh, use for accessing #MPoly to #MFace mapping. - * \param findex_orig: The input tessface index. - * \param fw: Face weights (position of the particle inside the \a findex_orig tessface). - * \param poly_nodes: May be NULL, otherwise an array of linked list, - * one for each final \a mesh_final polygon, containing all its tessfaces indices. - * \return The \a mesh_final tessface index. - */ int psys_particle_dm_face_lookup(Mesh *mesh_final, Mesh *mesh_original, int findex_orig, @@ -2096,7 +2085,6 @@ static int psys_map_index_on_dm(Mesh *mesh, return 1; } -/* interprets particle data to get a point on a mesh in object space */ void psys_particle_on_dm(Mesh *mesh_final, int from, int index, @@ -2218,9 +2206,11 @@ ParticleSystemModifierData *psys_get_modifier(Object *ob, ParticleSystem *psys) } return NULL; } + /************************************************/ /* Particles on a shape */ /************************************************/ + /* ready for future use */ static void psys_particle_on_shape(int UNUSED(distr), int UNUSED(index), @@ -2249,6 +2239,7 @@ static void psys_particle_on_shape(int UNUSED(distr), copy_v3_v3(orco, zerovec); } } + /************************************************/ /* Particles on emitter */ /************************************************/ @@ -2323,6 +2314,7 @@ void psys_particle_on_emitter(ParticleSystemModifierData *psmd, psys_particle_on_shape(from, index, fuv, vec, nor, utan, vtan, orco); } } + /************************************************/ /* Path Cache */ /************************************************/ @@ -3275,11 +3267,6 @@ static void cache_key_incremental_rotation(ParticleCacheKey *key0, } } -/** - * Calculates paths ready for drawing/rendering - * - Useful for making use of opengl vertex arrays for super fast strand drawing. - * - Makes child strands possible and creates them too into the cache. - * - Cached path data is also used to determine cut position for the editmode tool. */ void psys_cache_paths(ParticleSimulationData *sim, float cfra, const bool use_render_params) { PARTICLE_PSMD; @@ -3762,9 +3749,11 @@ void psys_cache_edit_paths(Depsgraph *depsgraph, } } } + /************************************************/ /* Particle Key handling */ /************************************************/ + void copy_particle_key(ParticleKey *to, ParticleKey *from, int time) { if (time) { @@ -3924,6 +3913,7 @@ void psys_mat_hair_to_global( /************************************************/ /* ParticleSettings handling */ /************************************************/ + static ModifierData *object_add_or_copy_particle_system( Main *bmain, Scene *scene, Object *ob, const char *name, const ParticleSystem *psys_orig) { @@ -4460,9 +4450,11 @@ void psys_get_texture( CLAMP_WARP_PARTICLE_TEXTURE_POS(PAMAP_DAMP, ptex->damp); CLAMP_PARTICLE_TEXTURE_POS(PAMAP_LENGTH, ptex->length); } + /************************************************/ /* Particle State */ /************************************************/ + float psys_get_timestep(ParticleSimulationData *sim) { return 0.04f * sim->psys->part->timetweak; @@ -4588,7 +4580,6 @@ static void get_child_modifier_parameters(ParticleSettings *part, ctx->mesh, cpa_from, cpa_num, cpa_fuv, ctx->vg_twist); } } -/* gets hair (or keyed) particles state at the "path time" specified in state->time */ void psys_get_particle_on_path(ParticleSimulationData *sim, int p, ParticleKey *state, @@ -4857,7 +4848,6 @@ void psys_get_particle_on_path(ParticleSimulationData *sim, } } } -/* gets particle's state at a time, returns 1 if particle exists and can be seen and 0 if not */ int psys_get_particle_state(ParticleSimulationData *sim, int p, ParticleKey *state, int always) { ParticleSystem *psys = sim->psys; diff --git a/source/blender/blenkernel/intern/particle_system.c b/source/blender/blenkernel/intern/particle_system.c index 8986847a034..e489f9e2bac 100644 --- a/source/blender/blenkernel/intern/particle_system.c +++ b/source/blender/blenkernel/intern/particle_system.c @@ -452,7 +452,6 @@ void psys_calc_dmcache(Object *ob, Mesh *mesh_final, Mesh *mesh_original, Partic } } -/* threaded child particle distribution and path caching */ void psys_thread_context_init(ParticleThreadContext *ctx, ParticleSimulationData *sim) { memset(ctx, 0, sizeof(ParticleThreadContext)); @@ -591,7 +590,6 @@ static void init_particle_texture(ParticleSimulationData *sim, ParticleData *pa, } } -/* set particle parameters that don't change during particle's life */ void init_particle(ParticleSimulationData *sim, ParticleData *pa) { ParticleSettings *part = sim->psys->part; @@ -1066,7 +1064,6 @@ static void evaluate_emitter_anim(struct Depsgraph *depsgraph, BKE_object_where_is_calc_time(depsgraph, scene, ob, cfra); } -/* sets particle to the emitter surface with initial velocity & rotation */ void reset_particle(ParticleSimulationData *sim, ParticleData *pa, float dtime, float cfra) { ParticleSystem *psys = sim->psys; @@ -1157,9 +1154,11 @@ static void reset_all_particles(ParticleSimulationData *sim, float dtime, float reset_particle(sim, pa, dtime, cfra); } } + /************************************************/ /* Particle targets */ /************************************************/ + ParticleSystem *psys_get_target_system(Object *ob, ParticleTarget *pt) { ParticleSystem *psys = NULL; @@ -1180,10 +1179,11 @@ ParticleSystem *psys_get_target_system(Object *ob, ParticleTarget *pt) return psys; } + /************************************************/ /* Keyed particles */ /************************************************/ -/* Counts valid keyed targets */ + void psys_count_keyed_targets(ParticleSimulationData *sim) { ParticleSystem *psys = sim->psys, *kpsys; @@ -1288,6 +1288,7 @@ static void set_keyed_keys(ParticleSimulationData *sim) /************************************************/ /* Point Cache */ /************************************************/ + void psys_make_temp_pointcache(Object *ob, ParticleSystem *psys) { PointCache *cache = psys->pointcache; @@ -1325,6 +1326,7 @@ static void bvhtree_balance_isolated(void *userdata) /************************************************/ /* Effectors */ /************************************************/ + static void psys_update_particle_bvhtree(ParticleSystem *psys, float cfra) { if (psys) { @@ -2181,7 +2183,6 @@ void psys_sph_finalize(SPHData *sphdata) } } -/* Sample the density field at a point in space. */ void psys_sph_density(BVHTree *tree, SPHData *sphdata, float co[3], float vars[2]) { ParticleSystem **psys = sphdata->psys; @@ -2234,6 +2235,7 @@ static void sph_integrate(ParticleSimulationData *sim, /************************************************/ /* Basic physics */ /************************************************/ + typedef struct EfData { ParticleTexture ptex; ParticleSimulationData *sim; @@ -2787,7 +2789,6 @@ static int collision_sphere_to_verts(ParticleCollision *col, return hit != NULL; } -/* Callback for BVHTree near test */ void BKE_psys_collision_neartest_cb(void *userdata, int index, const BVHTreeRay *ray, @@ -3179,10 +3180,14 @@ static void collision_check(ParticleSimulationData *sim, int p, float dfra, floa } } } + /************************************************/ /* Hair */ /************************************************/ -/* check if path cache or children need updating and do it if needed */ + +/** + * Check if path cache or children need updating and do it if needed. + */ static void psys_update_path_cache(ParticleSimulationData *sim, float cfra, const bool use_render_params) @@ -4627,7 +4632,6 @@ static void system_step(ParticleSimulationData *sim, float cfra, const bool use_ } } -/* system type has changed so set sensible defaults and clear non applicable flags */ void psys_changed_type(Object *ob, ParticleSystem *psys) { ParticleSettings *part = psys->part; @@ -4765,8 +4769,6 @@ static void particle_settings_free_local(ParticleSettings *particle_settings) MEM_freeN(particle_settings); } -/* main particle update call, checks that things are ok on the large scale and - * then advances in to actual particle calculations depending on particle type */ void particle_system_update(struct Depsgraph *depsgraph, Scene *scene, Object *ob, diff --git a/source/blender/blenkernel/intern/pbvh.c b/source/blender/blenkernel/intern/pbvh.c index 2318a05e635..2f22f94d142 100644 --- a/source/blender/blenkernel/intern/pbvh.c +++ b/source/blender/blenkernel/intern/pbvh.c @@ -78,7 +78,6 @@ void BB_reset(BB *bb) bb->bmax[0] = bb->bmax[1] = bb->bmax[2] = -FLT_MAX; } -/* Expand the bounding box to include a new coordinate */ void BB_expand(BB *bb, const float co[3]) { for (int i = 0; i < 3; i++) { @@ -87,7 +86,6 @@ void BB_expand(BB *bb, const float co[3]) } } -/* Expand the bounding box to include another bounding box */ void BB_expand_with_bb(BB *bb, BB *bb2) { for (int i = 0; i < 3; i++) { @@ -96,7 +94,6 @@ void BB_expand_with_bb(BB *bb, BB *bb2) } } -/* Return 0, 1, or 2 to indicate the widest axis of the bounding box */ int BB_widest_axis(const BB *bb) { float dim[3]; @@ -351,7 +348,6 @@ static void update_vb(PBVH *pbvh, PBVHNode *node, BBC *prim_bbc, int offset, int node->orig_vb = node->vb; } -/* Returns the number of visible quads in the nodes' grids. */ int BKE_pbvh_count_grid_quads(BLI_bitmap **grid_hidden, const int *grid_indices, int totgrid, @@ -555,12 +551,6 @@ static void pbvh_build(PBVH *pbvh, BB *cb, BBC *prim_bbc, int totprim) build_sub(pbvh, 0, cb, prim_bbc, 0, totprim); } -/** - * Do a full rebuild with on Mesh data structure. - * - * \note Unlike mpoly/mloop/verts, looptri is **totally owned** by PBVH - * (which means it may rewrite it if needed, see #BKE_pbvh_vert_coords_apply(). - */ void BKE_pbvh_build_mesh(PBVH *pbvh, const Mesh *mesh, const MPoly *mpoly, @@ -621,7 +611,6 @@ void BKE_pbvh_build_mesh(PBVH *pbvh, MEM_freeN(pbvh->vert_bitmap); } -/* Do a full rebuild with on Grids data structure */ void BKE_pbvh_build_grids(PBVH *pbvh, CCGElem **grids, int totgrid, @@ -1954,11 +1943,6 @@ void BKE_pbvh_node_get_bm_orco_data(PBVHNode *node, *r_orco_coords = node->bm_orco; } -/** - * \note doing a full search on all vertices here seems expensive, - * however this is important to avoid having to recalculate bound-box & sync the buffers to the - * GPU (which is far more expensive!) See: T47232. - */ bool BKE_pbvh_node_vert_update_check_any(PBVH *pbvh, PBVHNode *node) { BLI_assert(pbvh->type == PBVH_FACES); diff --git a/source/blender/blenkernel/intern/pbvh_bmesh.c b/source/blender/blenkernel/intern/pbvh_bmesh.c index 679a8b378b9..6f57448b0ab 100644 --- a/source/blender/blenkernel/intern/pbvh_bmesh.c +++ b/source/blender/blenkernel/intern/pbvh_bmesh.c @@ -1875,7 +1875,6 @@ static void pbvh_bmesh_create_nodes_fast_recursive( /***************************** Public API *****************************/ -/* Build a PBVH from a BMesh */ void BKE_pbvh_build_bmesh(PBVH *pbvh, BMesh *bm, bool smooth_shading, @@ -1953,7 +1952,6 @@ void BKE_pbvh_build_bmesh(PBVH *pbvh, MEM_freeN(nodeinfo); } -/* Collapse short edges, subdivide long edges */ bool BKE_pbvh_bmesh_update_topology(PBVH *pbvh, PBVHTopologyUpdateMode mode, const float center[3], @@ -2031,10 +2029,6 @@ bool BKE_pbvh_bmesh_update_topology(PBVH *pbvh, return modified; } -/* In order to perform operations on the original node coordinates - * (currently just raycast), store the node's triangles and vertices. - * - * Skips triangles that are hidden. */ void BKE_pbvh_bmesh_node_save_orig(BMesh *bm, PBVHNode *node) { /* Skip if original coords/triangles are already saved */ diff --git a/source/blender/blenkernel/intern/pbvh_intern.h b/source/blender/blenkernel/intern/pbvh_intern.h index 79b25c027ba..12c2d7aac78 100644 --- a/source/blender/blenkernel/intern/pbvh_intern.h +++ b/source/blender/blenkernel/intern/pbvh_intern.h @@ -180,9 +180,18 @@ struct PBVH { /* pbvh.c */ void BB_reset(BB *bb); +/** + * Expand the bounding box to include a new coordinate. + */ void BB_expand(BB *bb, const float co[3]); +/** + * Expand the bounding box to include another bounding box. + */ void BB_expand_with_bb(BB *bb, BB *bb2); void BBC_update_centroid(BBC *bbc); +/** + * Return 0, 1, or 2 to indicate the widest axis of the bounding box. + */ int BB_widest_axis(const BB *bb); void pbvh_grow_nodes(PBVH *bvh, int totnode); bool ray_face_intersection_quad(const float ray_start[3], diff --git a/source/blender/blenkernel/intern/pointcache.c b/source/blender/blenkernel/intern/pointcache.c index 57225872c7e..91b78680595 100644 --- a/source/blender/blenkernel/intern/pointcache.c +++ b/source/blender/blenkernel/intern/pointcache.c @@ -266,7 +266,8 @@ static void ptcache_softbody_error(const ID *UNUSED(owner_id), /* ignored for now */ } -/* Particle functions */ +/* Particle functions. */ + void BKE_ptcache_make_particle_key(ParticleKey *key, int index, void **data, float time) { PTCACHE_DATA_TO(data, BPHYS_DATA_LOCATION, index, key->co); @@ -873,6 +874,7 @@ static void ptcache_rigidbody_error(const struct ID *UNUSED(owner_id), } /* Creating ID's */ + void BKE_ptcache_id_from_softbody(PTCacheID *pid, Object *ob, SoftBody *sb) { memset(pid, 0, sizeof(PTCacheID)); @@ -1008,9 +1010,6 @@ void BKE_ptcache_id_from_cloth(PTCacheID *pid, Object *ob, ClothModifierData *cl pid->file_type = PTCACHE_FILE_PTCACHE; } -/* The fluid modifier does not actually use this anymore, but some parts of Blender expect that it - * still has a point cache currently. For example, the fluid modifier uses - * #DEG_add_collision_relations, which internally creates relations with the point cache. */ void BKE_ptcache_id_from_smoke(PTCacheID *pid, struct Object *ob, struct FluidModifierData *fmd) { FluidDomainSettings *fds = fmd->domain; @@ -1104,10 +1103,6 @@ void BKE_ptcache_id_from_rigidbody(PTCacheID *pid, Object *ob, RigidBodyWorld *r pid->file_type = PTCACHE_FILE_PTCACHE; } -/** - * \param ob: Optional, may be NULL. - * \param scene: Optional may be NULL. - */ PTCacheID BKE_ptcache_id_find(Object *ob, Scene *scene, PointCache *cache) { PTCacheID result = {0}; @@ -1713,7 +1708,8 @@ static int ptcache_file_header_begin_write(PTCacheFile *pf) return 1; } -/* Data pointer handling */ +/* Data pointer handling. */ + int BKE_ptcache_data_size(int data_type) { return ptcache_data_size[data_type]; @@ -1734,7 +1730,6 @@ static void ptcache_file_pointers_init(PTCacheFile *pf) pf->cur[BPHYS_DATA_BOIDS] = (data_types & (1 << BPHYS_DATA_BOIDS)) ? &pf->data.boids : NULL; } -/* Check to see if point number "index" is in pm, uses binary search for index data. */ int BKE_ptcache_mem_index_find(PTCacheMem *pm, unsigned int index) { if (pm->totpoint > 0 && pm->data[BPHYS_DATA_INDEX]) { @@ -2288,7 +2283,6 @@ static int ptcache_interpolate(PTCacheID *pid, float cfra, int cfra1, int cfra2) return 1; } /* reads cache from disk or memory */ -/* possible to get old or interpolated result */ int BKE_ptcache_read(PTCacheID *pid, float cfra, bool no_extrapolate_old) { int cfrai = (int)floor(cfra), cfra1 = 0, cfra2 = 0; @@ -2549,7 +2543,6 @@ static int ptcache_write_needed(PTCacheID *pid, int cfra, int *overwrite) return 0; } -/* writes cache to disk or memory */ int BKE_ptcache_write(PTCacheID *pid, unsigned int cfra) { PointCache *cache = pid->cache; @@ -2600,7 +2593,8 @@ int BKE_ptcache_write(PTCacheID *pid, unsigned int cfra) * mode - PTCACHE_CLEAR_ALL, */ -/* Clears & resets */ +/* Clears & resets. */ + void BKE_ptcache_id_clear(PTCacheID *pid, int mode, unsigned int cfra) { unsigned int len; /* store the length of the string */ @@ -3014,7 +3008,6 @@ int BKE_ptcache_object_reset(Scene *scene, Object *ob, int mode) return reset; } -/* Use this when quitting blender, with unsaved files */ void BKE_ptcache_remove(void) { char path[MAX_PTCACHE_PATH]; @@ -3150,7 +3143,6 @@ static PointCache *ptcache_copy(PointCache *cache, const bool copy_data) return ncache; } -/* returns first point cache */ PointCache *BKE_ptcache_copy_list(ListBase *ptcaches_new, const ListBase *ptcaches_old, const int flag) @@ -3170,6 +3162,7 @@ PointCache *BKE_ptcache_copy_list(ListBase *ptcaches_new, * every user action changing stuff, and then it runs a complete bake??? (ton) */ /* Baking */ + void BKE_ptcache_quick_cache_all(Main *bmain, Scene *scene, ViewLayer *view_layer) { PTCacheBaker baker; @@ -3202,7 +3195,6 @@ static void ptcache_dt_to_str(char *str, double dtime) } } -/* if bake is not given run simulations to current frame */ void BKE_ptcache_bake(PTCacheBaker *baker) { Scene *scene = baker->scene; @@ -3439,7 +3431,9 @@ void BKE_ptcache_bake(PTCacheBaker *baker) /* TODO: call redraw all windows somehow */ } + /* Helpers */ + void BKE_ptcache_disk_to_mem(PTCacheID *pid) { PointCache *cache = pid->cache; diff --git a/source/blender/blenkernel/intern/pointcloud.cc b/source/blender/blenkernel/intern/pointcloud.cc index e9b7f82b3c4..82dde79cff6 100644 --- a/source/blender/blenkernel/intern/pointcloud.cc +++ b/source/blender/blenkernel/intern/pointcloud.cc @@ -419,6 +419,7 @@ void BKE_pointcloud_data_update(struct Depsgraph *depsgraph, struct Scene *scene } /* Draw Cache */ + void (*BKE_pointcloud_batch_cache_dirty_tag_cb)(PointCloud *pointcloud, int mode) = nullptr; void (*BKE_pointcloud_batch_cache_free_cb)(PointCloud *pointcloud) = nullptr; diff --git a/source/blender/blenkernel/intern/preferences.c b/source/blender/blenkernel/intern/preferences.c index 7b77261e2ea..4bb2231bbb1 100644 --- a/source/blender/blenkernel/intern/preferences.c +++ b/source/blender/blenkernel/intern/preferences.c @@ -62,10 +62,6 @@ bUserAssetLibrary *BKE_preferences_asset_library_add(UserDef *userdef, return library; } -/** - * Unlink and free a library preference member. - * \note Free's \a library itself. - */ void BKE_preferences_asset_library_remove(UserDef *userdef, bUserAssetLibrary *library) { BLI_freelinkN(&userdef->asset_libraries, library); @@ -84,10 +80,6 @@ void BKE_preferences_asset_library_name_set(UserDef *userdef, sizeof(library->name)); } -/* Set the library path, ensuring it is pointing to a directory. - * Single blend files can only act as "Current File" library; libraries on disk - * should always be directories. If the path does not exist, that's fine; it can - * created as directory if necessary later. */ void BKE_preferences_asset_library_path_set(bUserAssetLibrary *library, const char *path) { BLI_strncpy(library->path, path, sizeof(library->path)); diff --git a/source/blender/blenkernel/intern/report.c b/source/blender/blenkernel/intern/report.c index 90e7ca3f11a..bc11861f2c8 100644 --- a/source/blender/blenkernel/intern/report.c +++ b/source/blender/blenkernel/intern/report.c @@ -76,11 +76,6 @@ void BKE_reports_init(ReportList *reports, int flag) reports->flag = flag; } -/** - * Only frees the list \a reports. - * To make displayed reports disappear, either remove window-manager reports - * (wmWindowManager.reports, or CTX_wm_reports()), or use #WM_report_banners_cancel(). - */ void BKE_reports_clear(ReportList *reports) { Report *report, *report_next; diff --git a/source/blender/blenkernel/intern/rigidbody.c b/source/blender/blenkernel/intern/rigidbody.c index 4482285c271..5bbe8ce2701 100644 --- a/source/blender/blenkernel/intern/rigidbody.c +++ b/source/blender/blenkernel/intern/rigidbody.c @@ -103,7 +103,6 @@ static void RB_constraint_delete(void *UNUSED(con)) #endif -/* Free rigidbody world */ void BKE_rigidbody_free_world(Scene *scene) { bool is_orig = (scene->id.tag & LIB_TAG_COPIED_ON_WRITE) == 0; @@ -160,7 +159,6 @@ void BKE_rigidbody_free_world(Scene *scene) MEM_freeN(rbw); } -/* Free RigidBody settings and sim instances */ void BKE_rigidbody_free_object(Object *ob, RigidBodyWorld *rbw) { bool is_orig = (ob->id.tag & LIB_TAG_COPIED_ON_WRITE) == 0; @@ -208,7 +206,6 @@ void BKE_rigidbody_free_object(Object *ob, RigidBodyWorld *rbw) ob->rigidbody_object = NULL; } -/* Free RigidBody constraint and sim instance */ void BKE_rigidbody_free_constraint(Object *ob) { RigidBodyCon *rbc = (ob) ? ob->rigidbody_constraint : NULL; diff --git a/source/blender/blenkernel/intern/scene.c b/source/blender/blenkernel/intern/scene.c index f2ac6b7fd22..916a2786a98 100644 --- a/source/blender/blenkernel/intern/scene.c +++ b/source/blender/blenkernel/intern/scene.c @@ -1701,7 +1701,6 @@ static void remove_sequencer_fcurves(Scene *sce) } } -/* flag -- copying options (see BKE_lib_id.h's LIB_ID_COPY_... flags for more). */ ToolSettings *BKE_toolsettings_copy(ToolSettings *toolsettings, const int flag) { if (toolsettings == NULL) { @@ -2028,9 +2027,6 @@ Scene *BKE_scene_add(Main *bmain, const char *name) return sce; } -/** - * Check if there is any instance of the object in the scene - */ bool BKE_scene_object_find(Scene *scene, Object *ob) { LISTBASE_FOREACH (ViewLayer *, view_layer, &scene->view_layers) { @@ -2053,12 +2049,6 @@ Object *BKE_scene_object_find_by_name(const Scene *scene, const char *name) return NULL; } -/** - * Sets the active scene, mainly used when running in background mode - * (`--scene` command line argument). - * This is also called to set the scene directly, bypassing windowing code. - * Otherwise #WM_window_set_active_scene is used when changing scenes by the user. - */ void BKE_scene_set_background(Main *bmain, Scene *scene) { Object *ob; @@ -2083,7 +2073,6 @@ void BKE_scene_set_background(Main *bmain, Scene *scene) * (render code calls own animation updates). */ } -/* called from creator_args.c */ Scene *BKE_scene_set_name(Main *bmain, const char *name) { Scene *sce = (Scene *)BKE_libblock_find_name(bmain, ID_SCE, name); @@ -2097,8 +2086,6 @@ Scene *BKE_scene_set_name(Main *bmain, const char *name) return NULL; } -/* Used by meta-balls, return *all* objects (including duplis) - * existing in the scene (including scene's sets). */ int BKE_scene_base_iter_next( Depsgraph *depsgraph, SceneBaseIter *iter, Scene **scene, int val, Base **base, Object **ob) { @@ -2323,8 +2310,6 @@ const char *BKE_scene_find_marker_name(const Scene *scene, int frame) return NULL; } -/* return the current marker for this frame, - * we can have more than 1 marker per frame, this just returns the first :/ */ const char *BKE_scene_find_last_marker_name(const Scene *scene, int frame) { const TimeMarker *marker, *best_marker = NULL; @@ -2368,7 +2353,6 @@ void BKE_scene_remove_rigidbody_object(struct Main *bmain, } } -/* checks for cycle, returns 1 if it's all OK */ bool BKE_scene_validate_setscene(Main *bmain, Scene *sce) { Scene *sce_iter; @@ -2391,16 +2375,11 @@ bool BKE_scene_validate_setscene(Main *bmain, Scene *sce) return true; } -/* Return fractional frame number taking into account subframes and time - * remapping. This the time value used by animation, modifiers and physics - * evaluation. */ float BKE_scene_ctime_get(const Scene *scene) { return BKE_scene_frame_to_ctime(scene, scene->r.cfra); } -/* Convert integer frame number to fractional frame number taking into account - * subframes and time remapping. */ float BKE_scene_frame_to_ctime(const Scene *scene, const int frame) { float ctime = frame; @@ -2410,13 +2389,11 @@ float BKE_scene_frame_to_ctime(const Scene *scene, const int frame) return ctime; } -/* Get current fractional frame based on frame and subframe. */ float BKE_scene_frame_get(const Scene *scene) { return scene->r.cfra + scene->r.subframe; } -/* Set current frame and subframe based on a fractional frame. */ void BKE_scene_frame_set(Scene *scene, float frame) { double intpart; @@ -2453,12 +2430,6 @@ TransformOrientationSlot *BKE_scene_orientation_slot_get_from_flag(Scene *scene, return BKE_scene_orientation_slot_get(scene, slot_index); } -/** - * Activate a transform orientation in a 3D view based on an enum value. - * - * \param orientation: If this is #V3D_ORIENT_CUSTOM or greater, the custom transform orientation - * with index \a orientation - #V3D_ORIENT_CUSTOM gets activated. - */ void BKE_scene_orientation_slot_set_index(TransformOrientationSlot *orient_slot, int orientation) { const bool is_custom = orientation >= V3D_ORIENT_CUSTOM; @@ -2665,7 +2636,6 @@ void BKE_scene_graph_evaluated_ensure(Depsgraph *depsgraph, Main *bmain) scene_graph_update_tagged(depsgraph, bmain, true); } -/* applies changes right away, does all sets too */ void BKE_scene_graph_update_for_newframe_ex(Depsgraph *depsgraph, const bool clear_recalc) { Scene *scene = DEG_get_input_scene(depsgraph); @@ -2741,12 +2711,6 @@ void BKE_scene_graph_update_for_newframe(Depsgraph *depsgraph) BKE_scene_graph_update_for_newframe_ex(depsgraph, true); } -/** - * Ensures given scene/view_layer pair has a valid, up-to-date depsgraph. - * - * \warning Sets matching depsgraph as active, - * so should only be called from the active editing context (usually, from operators). - */ void BKE_scene_view_layer_graph_evaluated_ensure(Main *bmain, Scene *scene, ViewLayer *view_layer) { Depsgraph *depsgraph = BKE_scene_ensure_depsgraph(bmain, scene, view_layer); @@ -2754,7 +2718,6 @@ void BKE_scene_view_layer_graph_evaluated_ensure(Main *bmain, Scene *scene, View BKE_scene_graph_update_tagged(depsgraph, bmain); } -/* return default view */ SceneRenderView *BKE_scene_add_render_view(Scene *sce, const char *name) { SceneRenderView *srv; @@ -2824,12 +2787,6 @@ int get_render_child_particle_number(const RenderData *r, int num, bool for_rend return num; } -/** - * Helper function for the SETLOOPER and SETLOOPER_VIEW_LAYER macros - * - * It iterates over the bases of the active layer and then the bases - * of the active layer of the background (set) scenes recursively. - */ Base *_setlooper_base_step(Scene **sce_iter, ViewLayer *view_layer, Base *base) { if (base && base->next) { @@ -2894,7 +2851,6 @@ typedef enum eCyclesFeatureSet { CYCLES_FEATURES_EXPERIMENTAL = 1, } eCyclesFeatureSet; -/* We cannot use const as RNA_id_pointer_create is not using a const ID. */ bool BKE_scene_uses_cycles_experimental_features(Scene *scene) { BLI_assert(BKE_scene_uses_cycles(scene)); @@ -2920,16 +2876,6 @@ void BKE_scene_base_flag_to_objects(ViewLayer *view_layer) } } -/** - * Synchronize object base flags - * - * This is usually handled by the depsgraph. - * However, in rare occasions we need to use the latest object flags - * before depsgraph is fully updated. - * - * It should (ideally) only run for copy-on-written objects since this is - * runtime data generated per-viewlayer. - */ void BKE_scene_object_base_flag_sync_from_base(Base *base) { Object *ob = base->object; @@ -3002,10 +2948,6 @@ int BKE_render_preview_pixel_size(const RenderData *r) return r->preview_pixel_size; } -/** - * Apply the needed correction factor to value, based on unit_type - * (only length-related are affected currently) and unit->scale_length. - */ double BKE_scene_unit_scale(const UnitSettings *unit, const int unit_type, double value) { if (unit->system == USER_UNIT_NONE) { @@ -3080,7 +3022,6 @@ bool BKE_scene_multiview_is_stereo3d(const RenderData *rd) ((srv[1]->viewflag & SCE_VIEW_DISABLE) == 0)); } -/* return whether to render this SceneRenderView */ bool BKE_scene_multiview_is_render_view_active(const RenderData *rd, const SceneRenderView *srv) { if (srv == NULL) { @@ -3107,7 +3048,6 @@ bool BKE_scene_multiview_is_render_view_active(const RenderData *rd, const Scene return false; } -/* return true if viewname is the first or if the name is NULL or not found */ bool BKE_scene_multiview_is_render_view_first(const RenderData *rd, const char *viewname) { SceneRenderView *srv; @@ -3129,7 +3069,6 @@ bool BKE_scene_multiview_is_render_view_first(const RenderData *rd, const char * return true; } -/* return true if viewname is the last or if the name is NULL or not found */ bool BKE_scene_multiview_is_render_view_last(const RenderData *rd, const char *viewname) { SceneRenderView *srv; @@ -3213,12 +3152,6 @@ void BKE_scene_multiview_filepath_get(SceneRenderView *srv, const char *filepath BLI_path_suffix(r_filepath, FILE_MAX, srv->suffix, ""); } -/** - * When multiview is not used the filepath is as usual (e.g., `Image.jpg`). - * When multiview is on, even if only one view is enabled the view is incorporated - * into the file name (e.g., `Image_L.jpg`). That allows for the user to re-render - * individual views. - */ void BKE_scene_multiview_view_filepath_get(const RenderData *rd, const char *filepath, const char *viewname, @@ -3606,10 +3539,6 @@ TransformOrientation *BKE_scene_transform_orientation_find(const Scene *scene, c return BLI_findlink(&scene->transform_spaces, index); } -/** - * \return the index that \a orientation has within \a scene's transform-orientation list - * or -1 if not found. - */ int BKE_scene_transform_orientation_get_index(const Scene *scene, const TransformOrientation *orientation) { diff --git a/source/blender/blenkernel/intern/screen.c b/source/blender/blenkernel/intern/screen.c index 4b631e5b1cc..531b5d42132 100644 --- a/source/blender/blenkernel/intern/screen.c +++ b/source/blender/blenkernel/intern/screen.c @@ -97,10 +97,6 @@ static void screen_foreach_id_dopesheet(LibraryForeachIDData *data, bDopeSheet * } } -/** - * Callback used by lib_query to walk over all ID usages (mimics `foreach_id` callback of - * `IDTypeInfo` structure). - */ void BKE_screen_foreach_id_screen_area(LibraryForeachIDData *data, ScrArea *area) { BKE_LIB_FOREACHID_PROCESS_IDSUPER(data, area->full, IDWALK_CB_NOP); @@ -258,7 +254,6 @@ static void screen_blend_write(BlendWriter *writer, ID *id, const void *id_addre BKE_screen_area_map_blend_write(writer, AREAMAP_FROM_SCREEN(screen)); } -/* Cannot use IDTypeInfo callback yet, because of the return value. */ bool BKE_screen_blend_read_data(BlendDataReader *reader, bScreen *screen) { bool success = true; @@ -516,7 +511,6 @@ static void region_copylist(SpaceType *st, ListBase *lb1, ListBase *lb2) } } -/* lb1 should be empty */ void BKE_spacedata_copylist(ListBase *lb1, ListBase *lb2) { BLI_listbase_clear(lb1); /* to be sure */ @@ -534,9 +528,6 @@ void BKE_spacedata_copylist(ListBase *lb1, ListBase *lb2) } } -/* facility to set locks for drawing to survive (render) threads accessing drawing data */ -/* lock can become bitflag too */ -/* should be replaced in future by better local data handling for threads */ void BKE_spacedata_draw_locks(bool set) { LISTBASE_FOREACH (SpaceType *, st, &spacetypes) { @@ -551,10 +542,6 @@ void BKE_spacedata_draw_locks(bool set) } } -/** - * Version of #BKE_area_find_region_type that also works if \a slink - * is not the active space of \a area. - */ ARegion *BKE_spacedata_find_region_type(const SpaceLink *slink, const ScrArea *area, int region_type) @@ -588,7 +575,6 @@ void BKE_spacedata_callback_id_remap_set(void (*func)(ScrArea *area, SpaceLink * spacedata_id_remap_cb = func; } -/* UNUSED!!! */ void BKE_spacedata_id_unref(struct ScrArea *area, struct SpaceLink *sl, struct ID *id) { if (spacedata_id_remap_cb) { @@ -652,7 +638,6 @@ void BKE_area_region_panels_free(ListBase *panels) BLI_listbase_clear(panels); } -/* not region itself */ void BKE_area_region_free(SpaceType *st, ARegion *region) { if (st) { @@ -692,7 +677,6 @@ void BKE_area_region_free(SpaceType *st, ARegion *region) BLI_freelistN(®ion->panels_category_active); } -/* not area itself */ void BKE_screen_area_free(ScrArea *area) { SpaceType *st = BKE_spacetype_from_id(area->spacetype); @@ -720,7 +704,6 @@ void BKE_screen_area_map_free(ScrAreaMap *area_map) BLI_freelistN(&area_map->areabase); } -/** Free (or release) any data used by this screen (does not free the screen itself). */ void BKE_screen_free_data(bScreen *screen) { screen_free_data(&screen->id); @@ -883,12 +866,6 @@ void BKE_screen_remove_unused_scrverts(bScreen *screen) /* ***************** Utilities ********************** */ -/** - * Find a region of type \a region_type in the currently active space of \a area. - * - * \note This does _not_ work if the region to look up is not in the active - * space. Use #BKE_spacedata_find_region_type if that may be the case. - */ ARegion *BKE_area_find_region_type(const ScrArea *area, int region_type) { if (area) { @@ -933,9 +910,6 @@ ARegion *BKE_area_find_region_xy(ScrArea *area, const int regiontype, int x, int return NULL; } -/** - * \note This is only for screen level regions (typically menus/popups). - */ ARegion *BKE_screen_find_region_xy(bScreen *screen, const int regiontype, int x, int y) { LISTBASE_FOREACH (ARegion *, region, &screen->regionbase) { @@ -948,10 +922,6 @@ ARegion *BKE_screen_find_region_xy(bScreen *screen, const int regiontype, int x, return NULL; } -/** - * \note Ideally we can get the area from the context, - * there are a few places however where this isn't practical. - */ ScrArea *BKE_screen_find_area_from_space(struct bScreen *screen, SpaceLink *sl) { LISTBASE_FOREACH (ScrArea *, area, &screen->areabase) { @@ -963,10 +933,6 @@ ScrArea *BKE_screen_find_area_from_space(struct bScreen *screen, SpaceLink *sl) return NULL; } -/** - * \note Using this function is generally a last resort, you really want to be - * using the context when you can - campbell - */ ScrArea *BKE_screen_find_big_area(bScreen *screen, const int spacetype, const short min) { ScrArea *big = NULL; @@ -1056,14 +1022,11 @@ ARegion *BKE_screen_find_main_region_at_xy(bScreen *screen, return BKE_area_find_region_xy(area, RGN_TYPE_WINDOW, x, y); } -/* magic zoom calculation, no idea what - * it signifies, if you find out, tell me! -zr - */ +/* Magic zoom calculation, no idea what it signifies, if you find out, tell me! -zr + * + * Simple, its magic dude! Well, to be honest, + * this gives a natural feeling zooming with multiple keypad presses (ton). */ -/* simple, its magic dude! - * well, to be honest, this gives a natural feeling zooming - * with multiple keypad presses (ton) - */ float BKE_screen_view3d_zoom_to_fac(float camzoom) { return powf(((float)M_SQRT2 + camzoom / 50.0f), 2.0f) / 4.0f; @@ -1478,7 +1441,6 @@ static void direct_link_region(BlendDataReader *reader, ARegion *region, int spa } /* for the saved 2.50 files without regiondata */ -/* and as patch for 2.48 and older */ void BKE_screen_view3d_do_versions_250(View3D *v3d, ListBase *regions) { LISTBASE_FOREACH (ARegion *, region, regions) { @@ -1785,9 +1747,6 @@ static void direct_link_area(BlendDataReader *reader, ScrArea *area) BLO_read_data_address(reader, &area->v4); } -/** - * \return false on error. - */ bool BKE_screen_area_map_blend_read_data(BlendDataReader *reader, ScrAreaMap *area_map) { BLO_read_list(reader, &area_map->vertbase); diff --git a/source/blender/blenkernel/intern/shader_fx.c b/source/blender/blenkernel/intern/shader_fx.c index 12017907038..a0d67a78d0f 100644 --- a/source/blender/blenkernel/intern/shader_fx.c +++ b/source/blender/blenkernel/intern/shader_fx.c @@ -57,7 +57,6 @@ static ShaderFxTypeInfo *shader_fx_types[NUM_SHADER_FX_TYPES] = {NULL}; /* *************************************************** */ /* Methods - Evaluation Loops, etc. */ -/* check if exist grease pencil effects */ bool BKE_shaderfx_has_gpencil(const Object *ob) { const ShaderFxData *fx; @@ -136,7 +135,6 @@ void BKE_shaderfx_free(ShaderFxData *fx) BKE_shaderfx_free_ex(fx, 0); } -/* check unique name */ bool BKE_shaderfx_unique_name(ListBase *shaders, ShaderFxData *fx) { if (shaders && fx) { @@ -164,24 +162,12 @@ const ShaderFxTypeInfo *BKE_shaderfx_get_info(ShaderFxType type) return NULL; } -/** - * Check whether given shaderfx is not local (i.e. from linked data) when the object is a library - * override. - * - * \param shaderfx: May be NULL, in which case we consider it as a non-local shaderfx case. - */ bool BKE_shaderfx_is_nonlocal_in_liboverride(const Object *ob, const ShaderFxData *shaderfx) { return (ID_IS_OVERRIDE_LIBRARY(ob) && ((shaderfx == NULL) || (shaderfx->flag & eShaderFxFlag_OverrideLibrary_Local) == 0)); } -/** - * Get an effect's panel type, which was defined in the #panelRegister callback. - * - * \note ShaderFx panel types are assumed to be named with the struct name field concatenated to - * the defined prefix. - */ void BKE_shaderfxType_panel_id(ShaderFxType type, char *r_idname) { const ShaderFxTypeInfo *fxi = BKE_shaderfx_get_info(type); diff --git a/source/blender/blenkernel/intern/shrinkwrap.c b/source/blender/blenkernel/intern/shrinkwrap.c index dd863f1ce06..00a80d6e74f 100644 --- a/source/blender/blenkernel/intern/shrinkwrap.c +++ b/source/blender/blenkernel/intern/shrinkwrap.c @@ -101,7 +101,6 @@ typedef struct ShrinkwrapCalcCBData { SpaceTransform *local2aux; } ShrinkwrapCalcCBData; -/* Checks if the modifier needs target normals with these settings. */ bool BKE_shrinkwrap_needs_normals(int shrinkType, int shrinkMode) { return (shrinkType == MOD_SHRINKWRAP_TARGET_PROJECT) || @@ -109,7 +108,6 @@ bool BKE_shrinkwrap_needs_normals(int shrinkType, int shrinkMode) shrinkMode == MOD_SHRINKWRAP_ABOVE_SURFACE); } -/* Initializes the mesh data structure from the given mesh and settings. */ bool BKE_shrinkwrap_init_tree( ShrinkwrapTreeData *data, Mesh *mesh, int shrinkType, int shrinkMode, bool force_normals) { @@ -160,13 +158,11 @@ bool BKE_shrinkwrap_init_tree( return true; } -/* Frees the tree data if necessary. */ void BKE_shrinkwrap_free_tree(ShrinkwrapTreeData *data) { free_bvhtree_from_mesh(&data->treeData); } -/* Free boundary data for target project */ void BKE_shrinkwrap_discard_boundary_data(struct Mesh *mesh) { struct ShrinkwrapBoundaryData *data = mesh->runtime.shrinkwrap_data; @@ -434,14 +430,6 @@ static void shrinkwrap_calc_nearest_vertex(ShrinkwrapCalcData *calc) 0, calc->numVerts, &data, shrinkwrap_calc_nearest_vertex_cb_ex, &settings); } -/* - * This function raycast a single vertex and updates the hit if the "hit" is considered valid. - * Returns true if "hit" was updated. - * Opts control whether an hit is valid or not - * Supported options are: - * - MOD_SHRINKWRAP_CULL_TARGET_FRONTFACE (front faces hits are ignored) - * - MOD_SHRINKWRAP_CULL_TARGET_BACKFACE (back faces hits are ignored) - */ bool BKE_shrinkwrap_project_normal(char options, const float vert[3], const float dir[3], @@ -1089,9 +1077,6 @@ static void mesh_looptri_target_project(void *userdata, } } -/* - * Maps the point to the nearest surface, either by simple nearest, or by target normal projection. - */ void BKE_shrinkwrap_find_nearest_surface(struct ShrinkwrapTreeData *tree, BVHTreeNearest *nearest, float co[3], @@ -1196,13 +1181,6 @@ static void shrinkwrap_calc_nearest_surface_point_cb_ex(void *__restrict userdat } } -/** - * Compute a smooth normal of the target (if applicable) at the hit location. - * - * \param tree: information about the mesh - * \param transform: transform from the hit coordinate space to the object space; may be null - * \param r_no: output in hit coordinate space; may be shared with inputs - */ void BKE_shrinkwrap_compute_smooth_normal(const struct ShrinkwrapTreeData *tree, const struct SpaceTransform *transform, int looptri_idx, @@ -1318,13 +1296,6 @@ static void shrinkwrap_snap_with_side(float r_point_co[3], } } -/** - * Apply the shrink to surface modes to the given original coordinates and nearest point. - * - * \param tree: mesh data for smooth normals - * \param transform: transform from the hit coordinate space to the object space; may be null - * \param r_point_co: may be the same memory location as point_co, hit_co, or hit_no. - */ void BKE_shrinkwrap_snap_point_to_surface(const struct ShrinkwrapTreeData *tree, const struct SpaceTransform *transform, int mode, @@ -1404,7 +1375,6 @@ static void shrinkwrap_calc_nearest_surface_point(ShrinkwrapCalcData *calc) 0, calc->numVerts, &data, shrinkwrap_calc_nearest_surface_point_cb_ex, &settings); } -/* Main shrinkwrap function */ void shrinkwrapModifier_deform(ShrinkwrapModifierData *smd, const ModifierEvalContext *ctx, struct Scene *scene, diff --git a/source/blender/blenkernel/intern/softbody.c b/source/blender/blenkernel/intern/softbody.c index a008edd038a..b811c17a3bc 100644 --- a/source/blender/blenkernel/intern/softbody.c +++ b/source/blender/blenkernel/intern/softbody.c @@ -3112,7 +3112,6 @@ static void sb_new_scratch(SoftBody *sb) /* ************ Object level, exported functions *************** */ -/* allocates and initializes general main data */ SoftBody *sbNew(void) { SoftBody *sb; @@ -3162,7 +3161,6 @@ SoftBody *sbNew(void) return sb; } -/* frees all */ void sbFree(Object *ob) { SoftBody *sb = ob->soft; @@ -3193,7 +3191,6 @@ void sbFreeSimulation(SoftBody *sb) free_softbody_intern(sb); } -/* makes totally fresh start situation */ void sbObjectToSoftbody(Object *ob) { // ob->softflag |= OB_SB_REDO; @@ -3213,7 +3210,6 @@ static bool object_has_edges(const Object *ob) return false; } -/* SB global visible functions */ void sbSetInterruptCallBack(int (*f)(void)) { SB_localInterruptCallBack = f; @@ -3244,20 +3240,6 @@ static void softbody_update_positions(Object *ob, } } -/* void SB_estimate_transform */ -/* input Object *ob out (says any object that can do SB like mesh, lattice, curve ) - * output float lloc[3], float lrot[3][3], float lscale[3][3] - * that is: - * a precise position vector denoting the motion of the center of mass - * give a rotation/scale matrix using averaging method, that's why estimate and not calculate - * see: this is kind of reverse engineering: having to states of a point cloud and recover what - * happened our advantage here we know the identity of the vertex there are others methods giving - * other results. lloc, lrot, lscale are allowed to be NULL, just in case you don't need it. - * should be pretty useful for pythoneers :) - * not! velocity .. 2nd order stuff - * vcloud_estimate_transform_v3 see - */ - void SB_estimate_transform(Object *ob, float lloc[3], float lrot[3][3], float lscale[3][3]) { BodyPoint *bp; @@ -3523,7 +3505,6 @@ static void sbStoreLastFrame(struct Depsgraph *depsgraph, Object *object, float object_orig->soft->last_frame = framenr; } -/* simulates one step. framenr is in frames */ void sbObjectStep(struct Depsgraph *depsgraph, Scene *scene, Object *ob, diff --git a/source/blender/blenkernel/intern/spline_base.cc b/source/blender/blenkernel/intern/spline_base.cc index 52bbd2bec57..4ff392a5ddb 100644 --- a/source/blender/blenkernel/intern/spline_base.cc +++ b/source/blender/blenkernel/intern/spline_base.cc @@ -62,9 +62,6 @@ static SplinePtr create_spline(const Spline::Type type) return {}; } -/** - * Return a new spline with the same data, settings, and attributes. - */ SplinePtr Spline::copy() const { SplinePtr dst = this->copy_without_attributes(); @@ -72,9 +69,6 @@ SplinePtr Spline::copy() const return dst; } -/** - * Return a new spline with the same type and settings like "cyclic", but without any data. - */ SplinePtr Spline::copy_only_settings() const { SplinePtr dst = create_spline(type_); @@ -83,9 +77,6 @@ SplinePtr Spline::copy_only_settings() const return dst; } -/** - * The same as #copy, but skips copying dynamic attributes to the new spline. - */ SplinePtr Spline::copy_without_attributes() const { SplinePtr dst = this->copy_only_settings(); @@ -185,12 +176,6 @@ static void accumulate_lengths(Span positions, } } -/** - * Return non-owning access to the cache of accumulated lengths along the spline. Each item is the - * length of the subsequent segment, i.e. the first value is the length of the first segment rather - * than 0. This calculation is rather trivial, and only depends on the evaluated positions. - * However, the results are used often, and it is necessarily single threaded, so it is cached. - */ Span Spline::evaluated_lengths() const { if (!length_cache_dirty_) { @@ -252,9 +237,6 @@ static void calculate_tangents(Span positions, } } -/** - * Return non-owning access to the direction of the curve at each evaluated point. - */ Span Spline::evaluated_tangents() const { if (!tangent_cache_dirty_) { @@ -375,10 +357,6 @@ static void calculate_normals_minimum(Span tangents, } } -/** - * Return non-owning access to the direction vectors perpendicular to the tangents at every - * evaluated point. The method used to generate the normal vectors depends on Spline.normal_mode. - */ Span Spline::evaluated_normals() const { if (!normal_cache_dirty_) { @@ -428,9 +406,6 @@ Spline::LookupResult Spline::lookup_evaluated_factor(const float factor) const return this->lookup_evaluated_length(this->length() * factor); } -/** - * \note This does not support extrapolation currently. - */ Spline::LookupResult Spline::lookup_evaluated_length(const float length) const { BLI_assert(length >= 0.0f && length <= this->length()); @@ -447,11 +422,6 @@ Spline::LookupResult Spline::lookup_evaluated_length(const float length) const return LookupResult{index, next_index, factor}; } -/** - * Return an array of evenly spaced samples along the length of the spline. The samples are indices - * and factors to the next index encoded in floats. The logic for converting from the float values - * to interpolation data is in #lookup_data_from_index_factor. - */ Array Spline::sample_uniform_index_factors(const int samples_size) const { const Span lengths = this->evaluated_lengths(); @@ -532,11 +502,6 @@ GVArray Spline::interpolate_to_evaluated(GSpan data) const return this->interpolate_to_evaluated(GVArray::ForSpan(data)); } -/** - * Sample any input data with a value for each evaluated point (already interpolated to evaluated - * points) to arbitrary parameters in between the evaluated points. The interpolation is quite - * simple, but this handles the cyclic and end point special cases. - */ void Spline::sample_with_index_factors(const GVArray &src, Span index_factors, GMutableSpan dst) const diff --git a/source/blender/blenkernel/intern/spline_bezier.cc b/source/blender/blenkernel/intern/spline_bezier.cc index 4f854333c8a..9ce285cebb8 100644 --- a/source/blender/blenkernel/intern/spline_bezier.cc +++ b/source/blender/blenkernel/intern/spline_bezier.cc @@ -369,12 +369,6 @@ int BezierSpline::evaluated_points_size() const return this->control_point_offsets().last(); } -/** - * If the spline is not cyclic, the direction for the first and last points is just the - * direction formed by the corresponding handles and control points. In the unlikely situation - * that the handles define a zero direction, fallback to using the direction defined by the - * first and last evaluated segments already calculated in #Spline::evaluated_tangents(). - */ void BezierSpline::correct_end_tangents() const { if (is_cyclic_) { diff --git a/source/blender/blenkernel/intern/spline_nurbs.cc b/source/blender/blenkernel/intern/spline_nurbs.cc index 7fa332a0330..69afb82baa8 100644 --- a/source/blender/blenkernel/intern/spline_nurbs.cc +++ b/source/blender/blenkernel/intern/spline_nurbs.cc @@ -81,9 +81,6 @@ void NURBSpline::set_order(const uint8_t value) this->mark_cache_invalid(); } -/** - * \warning Call #reallocate on the spline's attributes after adding all points. - */ void NURBSpline::add_point(const float3 position, const float radius, const float tilt, diff --git a/source/blender/blenkernel/intern/spline_poly.cc b/source/blender/blenkernel/intern/spline_poly.cc index b5aca0357be..4af68b5f270 100644 --- a/source/blender/blenkernel/intern/spline_poly.cc +++ b/source/blender/blenkernel/intern/spline_poly.cc @@ -112,12 +112,6 @@ Span PolySpline::evaluated_positions() const return this->positions(); } -/** - * Poly spline interpolation from control points to evaluated points is a special case, since - * the result data is the same as the input data. This function returns a GVArray that points to - * the original data. Therefore the lifetime of the returned virtual array must not be longer than - * the source data. - */ GVArray PolySpline::interpolate_to_evaluated(const GVArray &src) const { BLI_assert(src.size() == this->size()); diff --git a/source/blender/blenkernel/intern/studiolight.c b/source/blender/blenkernel/intern/studiolight.c index 29f726ece71..b7690e69aa1 100644 --- a/source/blender/blenkernel/intern/studiolight.c +++ b/source/blender/blenkernel/intern/studiolight.c @@ -1402,7 +1402,6 @@ void BKE_studiolight_default(SolidLight lights[4], float light_ambient[3]) lights[3].vec[2] = -0.542269f; } -/* API */ void BKE_studiolight_init(void) { /* Add default studio light */ @@ -1532,7 +1531,6 @@ void BKE_studiolight_preview(uint *icon_buffer, StudioLight *sl, int icon_id_typ } } -/* Ensure state of Studiolights */ void BKE_studiolight_ensure_flag(StudioLight *sl, int flag) { if ((sl->flag & flag) == flag) { @@ -1570,8 +1568,9 @@ void BKE_studiolight_ensure_flag(StudioLight *sl, int flag) } /* - * Python API Functions + * Python API Functions. */ + void BKE_studiolight_remove(StudioLight *sl) { if (sl->flag & STUDIOLIGHT_USER_DEFINED) { @@ -1608,7 +1607,6 @@ StudioLight *BKE_studiolight_create(const char *path, return sl; } -/* Only useful for workbench while editing the userprefs. */ StudioLight *BKE_studiolight_studio_edit_get(void) { static StudioLight sl = {0}; diff --git a/source/blender/blenkernel/intern/subsurf_ccg.c b/source/blender/blenkernel/intern/subsurf_ccg.c index 6796b1ac397..2669da98488 100644 --- a/source/blender/blenkernel/intern/subsurf_ccg.c +++ b/source/blender/blenkernel/intern/subsurf_ccg.c @@ -717,7 +717,6 @@ static void minmax_v3_v3v3(const float vec[3], float min[3], float max[3]) } } -/* UNUSED, keep since this functionality may be useful in the future. */ static void UNUSED_FUNCTION(ccgDM_getMinMax)(DerivedMesh *dm, float r_min[3], float r_max[3]) { CCGDerivedMesh *ccgdm = (CCGDerivedMesh *)dm; @@ -912,8 +911,6 @@ static void ccgDM_getFinalVertNo(DerivedMesh *dm, int vertNum, float r_no[3]) normal_short_to_float_v3(r_no, mvert.no); } -/* Translate GridHidden into the ME_HIDE flag for MVerts. Assumes - * vertices are in the order output by ccgDM_copyFinalVertArray. */ void subsurf_copy_grid_hidden(DerivedMesh *dm, const MPoly *mpoly, MVert *mvert, @@ -955,8 +952,6 @@ void subsurf_copy_grid_hidden(DerivedMesh *dm, } } -/* Translate GridPaintMask into vertex paint masks. Assumes vertices - * are in the order output by ccgDM_copyFinalVertArray. */ void subsurf_copy_grid_paint_mask(DerivedMesh *dm, const MPoly *mpoly, float *paint_mask, diff --git a/source/blender/blenkernel/intern/text.c b/source/blender/blenkernel/intern/text.c index 9a7e54600a5..4406647bd2c 100644 --- a/source/blender/blenkernel/intern/text.c +++ b/source/blender/blenkernel/intern/text.c @@ -279,9 +279,6 @@ IDTypeInfo IDType_ID_TXT = { /** \name Text Add, Free, Validation * \{ */ -/** - * \note caller must handle `compiled` member. - */ void BKE_text_free_lines(Text *text) { for (TextLine *tmp = text->lines.first, *tmp_next; tmp; tmp = tmp_next) { @@ -311,8 +308,6 @@ Text *BKE_text_add(Main *bmain, const char *name) return ta; } -/* this function replaces extended ascii characters */ -/* to a valid utf-8 sequences */ int txt_extended_ascii_as_utf8(char **str) { ptrdiff_t bad_char, i = 0; @@ -475,14 +470,6 @@ bool BKE_text_reload(Text *text) return true; } -/** - * Load a text file. - * - * \param is_internal: If \a true, this text data-block only exists in memory, - * not as a file on disk. - * - * \note text data-blocks have no real user but have 'fake user' enabled by default - */ Text *BKE_text_load_ex(Main *bmain, const char *file, const char *relpath, const bool is_internal) { unsigned char *buffer; @@ -535,11 +522,6 @@ Text *BKE_text_load_ex(Main *bmain, const char *file, const char *relpath, const return ta; } -/** - * Load a text file. - * - * \note Text data-blocks have no user by default, only the 'real user' flag. - */ Text *BKE_text_load(Main *bmain, const char *file, const char *relpath) { return BKE_text_load_ex(bmain, file, relpath, false); @@ -559,11 +541,6 @@ void BKE_text_write(Text *text, const char *str) /* called directly from rna */ txt_make_dirty(text); } -/* returns 0 if file on disk is the same or Text is in memory only - * returns 1 if file has been modified on disk since last local edit - * returns 2 if file on disk has been deleted - * -1 is returned if an error occurs */ - int BKE_text_file_modified_check(Text *text) { BLI_stat_t st; @@ -1143,7 +1120,6 @@ void txt_move_toline(Text *text, unsigned int line, const bool sel) txt_move_to(text, line, 0, sel); } -/* Moves to a certain byte in a line, not a certain utf8-character! */ void txt_move_to(Text *text, unsigned int line, unsigned int ch, const bool sel) { TextLine **linep; @@ -1303,11 +1279,6 @@ void txt_sel_all(Text *text) text->selc = text->sell->len; } -/** - * Reverse of #txt_pop_sel - * Clears the selection and ensures the cursor is located - * at the selection (where the cursor is visually while editing). - */ void txt_sel_clear(Text *text) { if (text->sell) { @@ -1394,9 +1365,6 @@ void txt_sel_set(Text *text, int startl, int startc, int endl, int endc) * - Are not null terminated. * \{ */ -/** - * Create a buffer, the only requirement is #txt_from_buf_for_undo can decode it. - */ char *txt_to_buf_for_undo(Text *text, int *r_buf_len) { int buf_len = 0; @@ -1414,9 +1382,6 @@ char *txt_to_buf_for_undo(Text *text, int *r_buf_len) return buf; } -/** - * Decode a buffer from #txt_to_buf_for_undo. - */ void txt_from_buf_for_undo(Text *text, const char *buf, int buf_len) { const char *buf_end = buf + buf_len; @@ -2413,10 +2378,11 @@ int text_check_bracket(const char ch) return 0; } -/* TODO: have a function for operators - - * http://docs.python.org/py3k/reference/lexical_analysis.html#operators */ bool text_check_delim(const char ch) { + /* TODO: have a function for operators: + * http://docs.python.org/py3k/reference/lexical_analysis.html#operators */ + int a; char delims[] = "():\"\' ~!%^&*-+=[]{};/<>|.#\t,@"; diff --git a/source/blender/blenkernel/intern/texture.c b/source/blender/blenkernel/intern/texture.c index 5725e8a5dcc..ee9247e6e60 100644 --- a/source/blender/blenkernel/intern/texture.c +++ b/source/blender/blenkernel/intern/texture.c @@ -232,7 +232,6 @@ IDTypeInfo IDType_ID_TE = { .lib_override_apply_post = NULL, }; -/* Utils for all IDs using those texture slots. */ void BKE_texture_mtex_foreach_id(LibraryForeachIDData *data, MTex *mtex) { BKE_LIB_FOREACHID_PROCESS_IDSUPER(data, mtex->object, IDWALK_CB_NOP); @@ -414,7 +413,6 @@ MTex *BKE_texture_mtex_add(void) return mtex; } -/* slot -1 for first free ID */ MTex *BKE_texture_mtex_add_id(ID *id, int slot) { MTex **mtex_ar; @@ -672,9 +670,6 @@ void BKE_texture_pointdensity_free(PointDensity *pd) } /* ------------------------------------------------------------------------- */ -/** - * \returns true if this texture can use its #Texture.ima (even if its NULL) - */ bool BKE_texture_is_image_user(const struct Tex *tex) { switch (tex->type) { @@ -686,7 +681,6 @@ bool BKE_texture_is_image_user(const struct Tex *tex) return false; } -/* ------------------------------------------------------------------------- */ bool BKE_texture_dependsOnTime(const struct Tex *texture) { if (texture->ima && BKE_image_is_animated(texture->ima)) { @@ -760,7 +754,6 @@ static void texture_nodes_fetch_images_for_pool(Tex *texture, } } -/* Make sure all images used by texture are loaded into pool. */ void BKE_texture_fetch_images_for_pool(Tex *texture, struct ImagePool *pool) { if (texture->nodetree != NULL) { diff --git a/source/blender/blenkernel/intern/tracking.c b/source/blender/blenkernel/intern/tracking.c index 3cdb8e927a6..3878d3b1c98 100644 --- a/source/blender/blenkernel/intern/tracking.c +++ b/source/blender/blenkernel/intern/tracking.c @@ -160,11 +160,6 @@ static void tracking_dopesheet_free(MovieTrackingDopesheet *dopesheet) dopesheet->tot_channel = 0; } -/* Free tracking structure, only frees structure contents - * (if structure is allocated in heap, it shall be handled outside). - * - * All the pointers inside structure becomes invalid after this call. - */ void BKE_tracking_free(MovieTracking *tracking) { tracking_tracks_free(&tracking->tracks); @@ -276,7 +271,6 @@ static void tracking_objects_copy(ListBase *objects_dst, } } -/* Copy tracking structure content. */ void BKE_tracking_copy(MovieTracking *tracking_dst, const MovieTracking *tracking_src, const int flag) @@ -321,9 +315,6 @@ void BKE_tracking_copy(MovieTracking *tracking_dst, BLI_ghash_free(tracks_mapping, NULL, NULL); } -/* Initialize motion tracking settings to default values, - * used when new movie clip datablock is created. - */ void BKE_tracking_settings_init(MovieTracking *tracking) { tracking->camera.sensor_width = 35.0f; @@ -361,7 +352,6 @@ void BKE_tracking_settings_init(MovieTracking *tracking) BKE_tracking_object_add(tracking, "Camera"); } -/* Get list base of active object's tracks. */ ListBase *BKE_tracking_get_active_tracks(MovieTracking *tracking) { MovieTrackingObject *object = BKE_tracking_object_get_active(tracking); @@ -373,7 +363,6 @@ ListBase *BKE_tracking_get_active_tracks(MovieTracking *tracking) return &tracking->tracks; } -/* Get list base of active object's plane tracks. */ ListBase *BKE_tracking_get_active_plane_tracks(MovieTracking *tracking) { MovieTrackingObject *object = BKE_tracking_object_get_active(tracking); @@ -385,7 +374,6 @@ ListBase *BKE_tracking_get_active_plane_tracks(MovieTracking *tracking) return &tracking->plane_tracks; } -/* Get reconstruction data of active object. */ MovieTrackingReconstruction *BKE_tracking_get_active_reconstruction(MovieTracking *tracking) { MovieTrackingObject *object = BKE_tracking_object_get_active(tracking); @@ -393,9 +381,6 @@ MovieTrackingReconstruction *BKE_tracking_get_active_reconstruction(MovieTrackin return BKE_tracking_object_get_reconstruction(tracking, object); } -/* Get transformation matrix for a given object which is used - * for parenting motion tracker reconstruction to 3D world. - */ void BKE_tracking_get_camera_object_matrix(Object *camera_object, float mat[4][4]) { BLI_assert(camera_object != NULL); @@ -412,11 +397,6 @@ void BKE_tracking_get_camera_object_matrix(Object *camera_object, float mat[4][4 BKE_object_where_is_calc_mat4(camera_object, mat); } -/* Get projection matrix for camera specified by given tracking object - * and frame number. - * - * NOTE: frame number should be in clip space, not scene space - */ void BKE_tracking_get_projection_matrix(MovieTracking *tracking, MovieTrackingObject *object, int framenr, @@ -472,7 +452,6 @@ void BKE_tracking_get_projection_matrix(MovieTracking *tracking, /*********************** clipboard *************************/ -/* Free clipboard by freeing memory used by all tracks in it. */ void BKE_tracking_clipboard_free(void) { MovieTrackingTrack *track = tracking_clipboard.tracks.first, *next_track; @@ -489,7 +468,6 @@ void BKE_tracking_clipboard_free(void) BLI_listbase_clear(&tracking_clipboard.tracks); } -/* Copy selected tracks from specified object to the clipboard. */ void BKE_tracking_clipboard_copy_tracks(MovieTracking *tracking, MovieTrackingObject *object) { ListBase *tracksbase = BKE_tracking_object_get_tracks(tracking, object); @@ -510,17 +488,11 @@ void BKE_tracking_clipboard_copy_tracks(MovieTracking *tracking, MovieTrackingOb } } -/* Check whether there are any tracks in the clipboard. */ bool BKE_tracking_clipboard_has_tracks(void) { return (BLI_listbase_is_empty(&tracking_clipboard.tracks) == false); } -/* Paste tracks from clipboard to specified object. - * - * Names of new tracks in object are guaranteed to - * be unique here. - */ void BKE_tracking_clipboard_paste_tracks(MovieTracking *tracking, MovieTrackingObject *object) { ListBase *tracksbase = BKE_tracking_object_get_tracks(tracking, object); @@ -541,10 +513,6 @@ void BKE_tracking_clipboard_paste_tracks(MovieTracking *tracking, MovieTrackingO /*********************** Tracks *************************/ -/* Add new empty track to the given list of tracks. - * - * It is required that caller will append at least one marker to avoid degenerate tracks. - */ MovieTrackingTrack *BKE_tracking_track_add_empty(MovieTracking *tracking, ListBase *tracks_list) { const MovieTrackingSettings *settings = &tracking->settings; @@ -569,14 +537,6 @@ MovieTrackingTrack *BKE_tracking_track_add_empty(MovieTracking *tracking, ListBa return track; } -/* Add new track to a specified tracks base. - * - * Coordinates are expected to be in normalized 0..1 space, - * frame number is expected to be in clip space. - * - * Width and height are clip's dimension used to scale track's - * pattern and search regions. - */ MovieTrackingTrack *BKE_tracking_track_add(MovieTracking *tracking, ListBase *tracksbase, float x, @@ -618,7 +578,6 @@ MovieTrackingTrack *BKE_tracking_track_add(MovieTracking *tracking, return track; } -/* Duplicate the specified track, result will no belong to any list. */ MovieTrackingTrack *BKE_tracking_track_duplicate(MovieTrackingTrack *track) { MovieTrackingTrack *new_track; @@ -639,10 +598,6 @@ MovieTrackingTrack *BKE_tracking_track_duplicate(MovieTrackingTrack *track) return new_track; } -/* Ensure specified track has got unique name, - * if it's not name of specified track will be changed - * keeping names of all other tracks unchanged. - */ void BKE_tracking_track_unique_name(ListBase *tracksbase, MovieTrackingTrack *track) { BLI_uniquename(tracksbase, @@ -653,11 +608,6 @@ void BKE_tracking_track_unique_name(ListBase *tracksbase, MovieTrackingTrack *tr sizeof(track->name)); } -/* Free specified track, only frees contents of a structure - * (if track is allocated in heap, it shall be handled outside). - * - * All the pointers inside track becomes invalid after this call. - */ void BKE_tracking_track_free(MovieTrackingTrack *track) { if (track->markers) { @@ -665,8 +615,6 @@ void BKE_tracking_track_free(MovieTrackingTrack *track) } } -/* Get frame numbers of the very first and last markers. - * There is no check on whether the marker is enabled or not. */ void BKE_tracking_track_first_last_frame_get(const MovieTrackingTrack *track, int *r_first_frame, int *r_last_frame) @@ -677,9 +625,6 @@ void BKE_tracking_track_first_last_frame_get(const MovieTrackingTrack *track, *r_last_frame = track->markers[last_marker_index].framenr; } -/* Find the minimum starting frame and maximum ending frame within given set of - * tracks. - */ void BKE_tracking_tracks_first_last_frame_minmax(/*const*/ MovieTrackingTrack **tracks, const int num_tracks, int *r_first_frame, @@ -745,11 +690,6 @@ MovieTrackingTrack **BKE_tracking_selected_tracks_in_active_object(MovieTracking return source_tracks; } -/* Set flag for all specified track's areas. - * - * area - which part of marker should be selected. see TRACK_AREA_* constants. - * flag - flag to be set for areas. - */ void BKE_tracking_track_flag_set(MovieTrackingTrack *track, int area, int flag) { if (area == TRACK_AREA_NONE) { @@ -767,11 +707,6 @@ void BKE_tracking_track_flag_set(MovieTrackingTrack *track, int area, int flag) } } -/* Clear flag from all specified track's areas. - * - * area - which part of marker should be selected. see TRACK_AREA_* constants. - * flag - flag to be cleared for areas. - */ void BKE_tracking_track_flag_clear(MovieTrackingTrack *track, int area, int flag) { if (area == TRACK_AREA_NONE) { @@ -789,19 +724,11 @@ void BKE_tracking_track_flag_clear(MovieTrackingTrack *track, int area, int flag } } -/* Check whether track has got marker at specified frame. - * - * NOTE: frame number should be in clip space, not scene space. - */ bool BKE_tracking_track_has_marker_at_frame(MovieTrackingTrack *track, int framenr) { return BKE_tracking_marker_get_exact(track, framenr) != NULL; } -/* Check whether track has got enabled marker at specified frame. - * - * NOTE: frame number should be in clip space, not scene space. - */ bool BKE_tracking_track_has_enabled_marker_at_frame(MovieTrackingTrack *track, int framenr) { MovieTrackingMarker *marker = BKE_tracking_marker_get_exact(track, framenr); @@ -809,18 +736,6 @@ bool BKE_tracking_track_has_enabled_marker_at_frame(MovieTrackingTrack *track, i return marker && (marker->flag & MARKER_DISABLED) == 0; } -/* Clear track's path: - * - * - If action is TRACK_CLEAR_REMAINED path from ref_frame+1 up to - * end will be clear. - * - * - If action is TRACK_CLEAR_UPTO path from the beginning up to - * ref_frame-1 will be clear. - * - * - If action is TRACK_CLEAR_ALL only marker at frame ref_frame will remain. - * - * NOTE: frame number should be in clip space, not scene space - */ void BKE_tracking_track_path_clear(MovieTrackingTrack *track, int ref_frame, int action) { int a; @@ -1281,7 +1196,6 @@ static void track_mask_gpencil_layer_rasterize(int frame_width, } } -/* Region is in pixel space, relative to marker's center. */ float *tracking_track_get_mask_for_region(int frame_width, int frame_height, const float region_min[2], @@ -1336,7 +1250,6 @@ float BKE_tracking_track_get_weight_for_marker(MovieClip *clip, return weight; } -/* area - which part of marker should be selected. see TRACK_AREA_* constants */ void BKE_tracking_track_select(ListBase *tracksbase, MovieTrackingTrack *track, int area, @@ -1510,16 +1423,6 @@ void BKE_tracking_marker_clamp(MovieTrackingMarker *marker, int event) } } -/** - * Get marker closest to the given frame number. - * - * If there is maker with exact frame number it returned. - * Otherwise, marker with highest frame number but lower than the requested - * frame is returned if such marker exists. Otherwise, the marker with lowest - * frame number greater than the requested frame number is returned. - * - * This function has complexity of `O(log number_of_markers)`. - */ MovieTrackingMarker *BKE_tracking_marker_get(MovieTrackingTrack *track, int framenr) { const int num_markers = track->markersnr; @@ -1705,7 +1608,6 @@ void BKE_tracking_marker_get_subframe_position(MovieTrackingTrack *track, /*********************** Plane Track *************************/ -/* Creates new plane track out of selected point tracks */ MovieTrackingPlaneTrack *BKE_tracking_plane_track_add(MovieTracking *tracking, ListBase *plane_tracks_base, ListBase *tracks, @@ -1789,11 +1691,6 @@ void BKE_tracking_plane_track_unique_name(ListBase *plane_tracks_base, sizeof(plane_track->name)); } -/* Free specified plane track, only frees contents of a structure - * (if track is allocated in heap, it shall be handled outside). - * - * All the pointers inside track becomes invalid after this call. - */ void BKE_tracking_plane_track_free(MovieTrackingPlaneTrack *plane_track) { if (plane_track->markers) { @@ -1988,9 +1885,6 @@ void BKE_tracking_plane_marker_delete(MovieTrackingPlaneTrack *plane_track, int * would be nice to de-duplicate them somehow.. */ -/* Get a plane marker at given frame, - * If there's no such marker, closest one from the left side will be returned. - */ MovieTrackingPlaneMarker *BKE_tracking_plane_marker_get(MovieTrackingPlaneTrack *plane_track, int framenr) { @@ -2039,9 +1933,6 @@ MovieTrackingPlaneMarker *BKE_tracking_plane_marker_get(MovieTrackingPlaneTrack return NULL; } -/* Get a plane marker at exact given frame, if there's no marker at the frame, - * NULL will be returned. - */ MovieTrackingPlaneMarker *BKE_tracking_plane_marker_get_exact(MovieTrackingPlaneTrack *plane_track, int framenr) { @@ -2054,7 +1945,6 @@ MovieTrackingPlaneMarker *BKE_tracking_plane_marker_get_exact(MovieTrackingPlane return plane_marker; } -/* Ensure there's a marker for the given frame. */ MovieTrackingPlaneMarker *BKE_tracking_plane_marker_ensure(MovieTrackingPlaneTrack *plane_track, int framenr) { @@ -2326,7 +2216,6 @@ static void reconstructed_camera_scale_set(MovieTrackingObject *object, float ma } } -/* converts principal offset from center to offset of blender's camera */ void BKE_tracking_camera_shift_get( MovieTracking *tracking, int winx, int winy, float *shiftx, float *shifty) { @@ -2899,10 +2788,6 @@ ImBuf *BKE_tracking_get_search_imbuf(ImBuf *ibuf, return searchibuf; } -/* zap channels from the imbuf that are disabled by the user. this can lead to - * better tracks sometimes. however, instead of simply zeroing the channels - * out, do a partial grayscale conversion so the display is better. - */ void BKE_tracking_disable_channels( ImBuf *ibuf, bool disable_red, bool disable_green, bool disable_blue, bool grayscale) { @@ -3417,9 +3302,6 @@ static void tracking_dopesheet_calc_coverage(MovieTracking *tracking) MEM_freeN(per_frame_counter); } -/* Tag dopesheet for update, actual update will happen later - * when it'll be actually needed. - */ void BKE_tracking_dopesheet_tag_update(MovieTracking *tracking) { MovieTrackingDopesheet *dopesheet = &tracking->dopesheet; @@ -3427,7 +3309,6 @@ void BKE_tracking_dopesheet_tag_update(MovieTracking *tracking) dopesheet->ok = false; } -/* Do dopesheet update, if update is not needed nothing will happen. */ void BKE_tracking_dopesheet_update(MovieTracking *tracking) { MovieTrackingDopesheet *dopesheet = &tracking->dopesheet; @@ -3451,7 +3332,6 @@ void BKE_tracking_dopesheet_update(MovieTracking *tracking) dopesheet->ok = true; } -/* NOTE: Returns NULL if the track comes from camera object, */ MovieTrackingObject *BKE_tracking_find_object_for_track(const MovieTracking *tracking, const MovieTrackingTrack *track) { @@ -3479,7 +3359,6 @@ ListBase *BKE_tracking_find_tracks_list_for_track(MovieTracking *tracking, return &tracking->tracks; } -/* NOTE: Returns NULL if the track comes from camera object, */ MovieTrackingObject *BKE_tracking_find_object_for_plane_track( const MovieTracking *tracking, const MovieTrackingPlaneTrack *plane_track) { diff --git a/source/blender/blenkernel/intern/tracking_auto.c b/source/blender/blenkernel/intern/tracking_auto.c index e2a29d7858d..c83e595c611 100644 --- a/source/blender/blenkernel/intern/tracking_auto.c +++ b/source/blender/blenkernel/intern/tracking_auto.c @@ -775,7 +775,7 @@ void BKE_autotrack_context_sync(AutoTrackContext *context) } /* TODO(sergey): Find a way to avoid this, somehow making all needed logic in - * BKE_autotrack_context_sync(). */ + * #BKE_autotrack_context_sync(). */ void BKE_autotrack_context_sync_user(AutoTrackContext *context, MovieClipUser *user) { user->framenr = context->synchronized_scene_frame; diff --git a/source/blender/blenkernel/intern/tracking_detect.c b/source/blender/blenkernel/intern/tracking_detect.c index 08719161e1a..be680ef8a8b 100644 --- a/source/blender/blenkernel/intern/tracking_detect.c +++ b/source/blender/blenkernel/intern/tracking_detect.c @@ -148,7 +148,6 @@ static void run_configured_detector(MovieTracking *tracking, } } -/* Detect features using FAST detector */ void BKE_tracking_detect_fast(MovieTracking *tracking, ListBase *tracksbase, ImBuf *ibuf, @@ -170,7 +169,6 @@ void BKE_tracking_detect_fast(MovieTracking *tracking, tracking, tracksbase, ibuf, framenr, layer, place_outside_layer, &options); } -/* Detect features using Harris detector */ void BKE_tracking_detect_harris(MovieTracking *tracking, ListBase *tracksbase, ImBuf *ibuf, diff --git a/source/blender/blenkernel/intern/tracking_plane_tracker.c b/source/blender/blenkernel/intern/tracking_plane_tracker.c index b787cd366c5..d4a5bb2aa9d 100644 --- a/source/blender/blenkernel/intern/tracking_plane_tracker.c +++ b/source/blender/blenkernel/intern/tracking_plane_tracker.c @@ -167,7 +167,6 @@ static void track_plane_from_existing_motion(MovieTrackingPlaneTrack *plane_trac } } -/* NOTE: frame number should be in clip space, not scene space */ void BKE_tracking_track_plane_from_existing_motion(MovieTrackingPlaneTrack *plane_track, int start_frame) { diff --git a/source/blender/blenkernel/intern/tracking_region_tracker.c b/source/blender/blenkernel/intern/tracking_region_tracker.c index 179def0a6f2..ad3f226fa92 100644 --- a/source/blender/blenkernel/intern/tracking_region_tracker.c +++ b/source/blender/blenkernel/intern/tracking_region_tracker.c @@ -180,7 +180,6 @@ static ImBuf *tracking_context_get_reference_ibuf(MovieClip *clip, return ibuf; } -/* Fill in libmv tracker options structure with settings need to be used to perform track. */ void tracking_configure_tracker(const MovieTrackingTrack *track, float *mask, const bool is_backwards, @@ -311,11 +310,6 @@ static bool refine_marker_reference_frame_get(MovieTrackingTrack *track, return (reference->flag & MARKER_DISABLED) == 0; } -/* Refine marker's position using previously known keyframe. - * Direction of searching for a keyframe depends on backwards flag, - * which means if backwards is false, previous keyframe will be as - * reference. - */ void BKE_tracking_refine_marker(MovieClip *clip, MovieTrackingTrack *track, MovieTrackingMarker *marker, diff --git a/source/blender/blenkernel/intern/tracking_solver.c b/source/blender/blenkernel/intern/tracking_solver.c index d89d36f85ea..47a955c9d93 100644 --- a/source/blender/blenkernel/intern/tracking_solver.c +++ b/source/blender/blenkernel/intern/tracking_solver.c @@ -325,7 +325,6 @@ static int reconstruct_count_tracks_on_both_keyframes(MovieTracking *tracking, return tot; } -/* Perform early check on whether everything is fine to start reconstruction. */ bool BKE_tracking_reconstruction_check(MovieTracking *tracking, MovieTrackingObject *object, char *error_msg, @@ -354,11 +353,6 @@ bool BKE_tracking_reconstruction_check(MovieTracking *tracking, return true; } -/* Create context for camera/object motion reconstruction. - * Copies all data needed for reconstruction from movie - * clip datablock, so editing this clip is safe during - * reconstruction job is in progress. - */ MovieReconstructContext *BKE_tracking_reconstruction_context_new(MovieClip *clip, MovieTrackingObject *object, int keyframe1, @@ -446,7 +440,6 @@ const char *BKE_tracking_reconstruction_error_message_get(const MovieReconstruct return context->error_message; } -/* Free memory used by a reconstruction process. */ void BKE_tracking_reconstruction_context_free(MovieReconstructContext *context) { if (context->reconstruction) { @@ -486,15 +479,6 @@ static void reconstructionOptionsFromContext(libmv_ReconstructionOptions *recons reconstruction_options->refine_intrinsics = context->refine_flags; } -/* Solve camera/object motion and reconstruct 3D markers position - * from a prepared reconstruction context. - * - * stop is not actually used at this moment, so reconstruction - * job could not be stopped. - * - * do_update, progress and stat_message are set by reconstruction - * callback in libmv side and passing to an interface. - */ void BKE_tracking_reconstruction_solve(MovieReconstructContext *context, short *stop, short *do_update, @@ -542,9 +526,6 @@ void BKE_tracking_reconstruction_solve(MovieReconstructContext *context, context->reprojection_error = error; } -/* Finish reconstruction process by copying reconstructed data - * to an actual movie clip datablock. - */ bool BKE_tracking_reconstruction_finish(MovieReconstructContext *context, MovieTracking *tracking) { MovieTrackingReconstruction *reconstruction; @@ -608,9 +589,6 @@ static void tracking_scale_reconstruction(ListBase *tracksbase, } } -/* Apply scale on all reconstructed cameras and bundles, - * used by camera scale apply operator. - */ void BKE_tracking_reconstruction_scale(MovieTracking *tracking, float scale[3]) { LISTBASE_FOREACH (MovieTrackingObject *, object, &tracking->objects) { diff --git a/source/blender/blenkernel/intern/tracking_stabilize.c b/source/blender/blenkernel/intern/tracking_stabilize.c index a4dbebb08a9..fe9a2f2268a 100644 --- a/source/blender/blenkernel/intern/tracking_stabilize.c +++ b/source/blender/blenkernel/intern/tracking_stabilize.c @@ -1252,24 +1252,6 @@ static StabContext *init_stabilizer(MovieClip *clip, int size, float aspect) /* === public interface functions === */ -/* Get stabilization data (translation, scaling and angle) for a given frame. - * Returned data describes how to compensate the detected movement, but with any - * chosen scale factor already applied and any target frame position already - * compensated. In case stabilization fails or is disabled, neutral values are - * returned. - * - * framenr is a frame number, relative to the clip (not relative to the scene - * timeline) - * width is an effective width of the canvas (square pixels), used to scale the - * determined translation - * - * Outputs: - * - translation of the lateral shift, absolute canvas coordinates - * (square pixels). - * - scale of the scaling to apply - * - angle of the rotation angle, relative to the frame center - */ -/* TODO(sergey): Use r_ prefix for output parameters here. */ void BKE_tracking_stabilization_data_get(MovieClip *clip, int framenr, int width, @@ -1336,12 +1318,6 @@ static void tracking_stabilize_frame_interpolation_cb( } } -/* Stabilize given image buffer using stabilization data for a specified - * frame number. - * - * NOTE: frame number should be in clip space, not scene space. - */ -/* TODO(sergey): Use r_ prefix for output parameters here. */ ImBuf *BKE_tracking_stabilize_frame( MovieClip *clip, int framenr, ImBuf *ibuf, float translation[2], float *scale, float *angle) { @@ -1449,16 +1425,6 @@ ImBuf *BKE_tracking_stabilize_frame( return tmpibuf; } -/* Build a 4x4 transformation matrix based on the given 2D stabilization data. - * mat is a 4x4 matrix in homogeneous coordinates, adapted to the - * final image buffer size and compensated for pixel aspect ratio, - * ready for direct OpenGL drawing. - * - * TODO(sergey): The signature of this function should be changed. we actually - * don't need the dimensions of the image buffer. Instead we - * should consider to provide the pivot point of the rotation as a - * further stabilization data parameter. - */ void BKE_tracking_stabilization_data_to_mat4(int buffer_width, int buffer_height, float pixel_aspect, diff --git a/source/blender/blenkernel/intern/tracking_util.c b/source/blender/blenkernel/intern/tracking_util.c index 16b36e94328..f1fd3a13e0e 100644 --- a/source/blender/blenkernel/intern/tracking_util.c +++ b/source/blender/blenkernel/intern/tracking_util.c @@ -338,11 +338,6 @@ static void search_pixel_to_marker_unified(int frame_width, sub_v2_v2v2(marker_unified, frame_unified, marker->pos); } -/* Each marker has 5 coordinates associated with it that get warped with - * tracking: the four corners ("pattern_corners"), and the center ("pos"). - * This function puts those 5 points into the appropriate frame for tracking - * (the "search" coordinate frame). - */ void tracking_get_marker_coords_for_tracking(int frame_width, int frame_height, const MovieTrackingMarker *marker, @@ -369,7 +364,6 @@ void tracking_get_marker_coords_for_tracking(int frame_width, search_pixel_y[4] = pixel_coords[1] - 0.5f; } -/* Inverse of above. */ void tracking_set_marker_coords_from_tracking(int frame_width, int frame_height, MovieTrackingMarker *marker, @@ -411,15 +405,6 @@ void tracking_set_marker_coords_from_tracking(int frame_width, /** \name General Purpose Utility Functions * \{ */ -/* Place a disabled marker before or after specified ref_marker. - * - * If before is truth, disabled marker is placed before reference - * one, and it's placed after it otherwise. - * - * If there's already a marker at the frame where disabled one - * is expected to be placed, nothing will happen if overwrite - * is false. - */ void tracking_marker_insert_disabled(MovieTrackingTrack *track, const MovieTrackingMarker *ref_marker, bool before, @@ -526,7 +511,6 @@ static void distortion_model_parameters_from_options( BLI_assert_msg(0, "Unknown distortion model"); } -/* Fill in Libmv C-API camera intrinsics options from tracking structure. */ void tracking_cameraIntrinscisOptionsFromTracking( MovieTracking *tracking, int calibration_width, @@ -563,7 +547,6 @@ void tracking_trackingCameraFromIntrinscisOptions( distortion_model_parameters_from_options(camera_intrinsics_options, camera); } -/* Get previous keyframed marker. */ MovieTrackingMarker *tracking_get_keyframed_marker(MovieTrackingTrack *track, int current_frame, bool backwards) diff --git a/source/blender/blenkernel/intern/undo_system.c b/source/blender/blenkernel/intern/undo_system.c index 26d37489e35..a2f27c9e3b6 100644 --- a/source/blender/blenkernel/intern/undo_system.c +++ b/source/blender/blenkernel/intern/undo_system.c @@ -93,10 +93,6 @@ static bool g_undo_callback_running = false; /** \} */ /* -------------------------------------------------------------------- */ -/** \name Public Undo Types - * - * Unfortunately we need this for a handful of places. - * \{ */ const UndoType *BKE_UNDOSYS_TYPE_IMAGE = NULL; const UndoType *BKE_UNDOSYS_TYPE_MEMFILE = NULL; const UndoType *BKE_UNDOSYS_TYPE_PAINTCURVE = NULL; @@ -358,7 +354,6 @@ void BKE_undosys_stack_init_from_main(UndoStack *ustack, struct Main *bmain) undosys_stack_push_main(ustack, IFACE_("Original"), bmain); } -/* called after 'BKE_undosys_stack_init_from_main' */ void BKE_undosys_stack_init_from_context(UndoStack *ustack, bContext *C) { const UndoType *ut = BKE_undosys_type_from_context(C); @@ -367,7 +362,6 @@ void BKE_undosys_stack_init_from_context(UndoStack *ustack, bContext *C) } } -/* name optional */ bool BKE_undosys_stack_has_undo(const UndoStack *ustack, const char *name) { if (name) { @@ -397,10 +391,6 @@ UndoStep *BKE_undosys_stack_init_or_active_with_type(UndoStack *ustack, const Un return BKE_undosys_stack_active_with_type(ustack, ut); } -/** - * \param steps: Limit the number of undo steps. - * \param memory_limit: Limit the amount of memory used by the undo stack. - */ void BKE_undosys_stack_limit_steps_and_memory(UndoStack *ustack, int steps, size_t memory_limit) { UNDO_NESTED_ASSERT(false); @@ -497,9 +487,6 @@ UndoStep *BKE_undosys_step_push_init(UndoStack *ustack, bContext *C, const char return BKE_undosys_step_push_init_with_type(ustack, C, name, ut); } -/** - * \param C: Can be NULL from some callers if their encoding function doesn't need it - */ eUndoPushReturn BKE_undosys_step_push_with_type(UndoStack *ustack, bContext *C, const char *name, @@ -613,9 +600,6 @@ eUndoPushReturn BKE_undosys_step_push(UndoStack *ustack, bContext *C, const char return BKE_undosys_step_push_with_type(ustack, C, name, ut); } -/** - * Useful when we want to diff against previous undo data but can't be sure the types match. - */ UndoStep *BKE_undosys_step_same_type_next(UndoStep *us) { if (us) { @@ -629,9 +613,6 @@ UndoStep *BKE_undosys_step_same_type_next(UndoStep *us) return us; } -/** - * Useful when we want to diff against previous undo data but can't be sure the types match. - */ UndoStep *BKE_undosys_step_same_type_prev(UndoStep *us) { if (us) { @@ -674,14 +655,6 @@ UndoStep *BKE_undosys_step_find_by_type(UndoStack *ustack, const UndoType *ut) return NULL; } -/** - * Return direction of the undo/redo from `us_reference` (or `ustack->step_active` if NULL), and - * `us_target`. - * - * \note If `us_reference` and `us_target` are the same, we consider this is an undo. - * - * \return -1 for undo, 1 for redo, 0 in case of error. - */ eUndoStepDir BKE_undosys_step_calc_direction(const UndoStack *ustack, const UndoStep *us_target, const UndoStep *us_reference) @@ -741,19 +714,6 @@ static UndoStep *undosys_step_iter_first(UndoStep *us_reference, const eUndoStep return (undo_dir == -1) ? us_reference->prev : us_reference->next; } -/** - * Undo/Redo until the given `us_target` step becomes the active (currently loaded) one. - * - * \note Unless `us_target` is a 'skipped' one and `use_skip` is true, `us_target` - * will become the active step. - * - * \note In case `use_skip` is true, the final target will always be **beyond** the given one - * (if the given one has to be skipped). - * - * \param us_reference: If NULL, will be set to current active step in the undo stack. Otherwise, - * it is assumed to match the current state, and will be used as basis for the undo/redo process - * (i.e. all steps in-between `us_reference` and `us_target` will be processed). - */ bool BKE_undosys_step_load_data_ex(UndoStack *ustack, bContext *C, UndoStep *us_target, @@ -842,19 +802,12 @@ bool BKE_undosys_step_load_data_ex(UndoStack *ustack, return false; } -/** - * Undo/Redo until the given `us_target` step becomes the active (currently loaded) one. - */ bool BKE_undosys_step_load_data(UndoStack *ustack, bContext *C, UndoStep *us_target) { /* Note that here we do not skip 'skipped' steps by default. */ return BKE_undosys_step_load_data_ex(ustack, C, us_target, NULL, false); } -/** - * Undo/Redo until the step matching given `index` in the undo stack becomes the active (currently - * loaded) one. - */ void BKE_undosys_step_load_from_index(UndoStack *ustack, bContext *C, const int index) { UndoStep *us_target = BLI_findlink(&ustack->steps, index); @@ -862,17 +815,6 @@ void BKE_undosys_step_load_from_index(UndoStack *ustack, bContext *C, const int BKE_undosys_step_load_data(ustack, C, us_target); } -/** - * Undo until `us_target` step becomes the active (currently loaded) one. - * - * \warning This function assumes that the given target step is _before_ current active one. - * - * \note Unless `us_target` is a 'skipped' one and `use_skip` is true, `us_target` will become the - * active step. - * - * \note In case `use_skip` is true, the final target will always be **before** the given one (if - * the given one has to be skipped). - */ bool BKE_undosys_step_undo_with_data_ex(UndoStack *ustack, bContext *C, UndoStep *us_target, @@ -888,19 +830,11 @@ bool BKE_undosys_step_undo_with_data_ex(UndoStack *ustack, return BKE_undosys_step_load_data_ex(ustack, C, us_target, us_reference, use_skip); } -/** - * Undo until `us_target` step becomes the active (currently loaded) one. - * - * \note See #BKE_undosys_step_undo_with_data_ex for details. - */ bool BKE_undosys_step_undo_with_data(UndoStack *ustack, bContext *C, UndoStep *us_target) { return BKE_undosys_step_undo_with_data_ex(ustack, C, us_target, true); } -/** - * Undo one step from current active (currently loaded) one. - */ bool BKE_undosys_step_undo(UndoStack *ustack, bContext *C) { if (ustack->step_active != NULL) { @@ -909,17 +843,6 @@ bool BKE_undosys_step_undo(UndoStack *ustack, bContext *C) return false; } -/** - * Redo until `us_target` step becomes the active (currently loaded) one. - * - * \warning This function assumes that the given target step is _after_ current active one. - * - * \note Unless `us_target` is a 'skipped' one and `use_skip` is true, `us_target` will become the - * active step. - * - * \note In case `use_skip` is true, the final target will always be **after** the given one (if - * the given one has to be skipped). - */ bool BKE_undosys_step_redo_with_data_ex(UndoStack *ustack, bContext *C, UndoStep *us_target, @@ -934,19 +857,11 @@ bool BKE_undosys_step_redo_with_data_ex(UndoStack *ustack, return BKE_undosys_step_load_data_ex(ustack, C, us_target, us_reference, use_skip); } -/** - * Redo until `us_target` step becomes the active (currently loaded) one. - * - * \note See #BKE_undosys_step_redo_with_data_ex for details. - */ bool BKE_undosys_step_redo_with_data(UndoStack *ustack, bContext *C, UndoStep *us_target) { return BKE_undosys_step_redo_with_data_ex(ustack, C, us_target, true); } -/** - * Redo one step from current active one. - */ bool BKE_undosys_step_redo(UndoStack *ustack, bContext *C) { if (ustack->step_active != NULL) { @@ -955,9 +870,6 @@ bool BKE_undosys_step_redo(UndoStack *ustack, bContext *C) return false; } -/** - * Similar to #WM_operatortype_append - */ UndoType *BKE_undosys_type_append(void (*undosys_fn)(UndoType *)) { UndoType *ut; diff --git a/source/blender/blenkernel/intern/unit.c b/source/blender/blenkernel/intern/unit.c index 4e9a3c9fb2e..fde3ac13ceb 100644 --- a/source/blender/blenkernel/intern/unit.c +++ b/source/blender/blenkernel/intern/unit.c @@ -1091,22 +1091,6 @@ double BKE_unit_apply_preferred_unit(const struct UnitSettings *settings, int ty return value * scalar + bias; } -/** - * Make a copy of the string that replaces the units with numbers. - * - * This is only used when evaluating user input and can afford to be a bit slower - * - * This is to be used before python evaluation so.. - * 10.1km -> 10.1*1000.0 - * ...will be resolved by python. - * - * Values will be split by an add sign. - * 5'2" -> 5*0.3048 + 2*0.0254 - * - * \param str_prev: is optional, when valid it is used to get a base unit when none is set. - * - * \return True of a change was made. - */ bool BKE_unit_replace_string( char *str, int len_max, const char *str_prev, double scale_pref, int system, int type) { @@ -1196,7 +1180,6 @@ bool BKE_unit_replace_string( return changed; } -/* 45µm --> 45um */ void BKE_unit_name_to_alt(char *str, int len_max, const char *orig_str, int system, int type) { const bUnitCollection *usys = unit_get_system(system, type); diff --git a/source/blender/blenkernel/intern/vfont.c b/source/blender/blenkernel/intern/vfont.c index a17a57dc5ef..4a598288ee6 100644 --- a/source/blender/blenkernel/intern/vfont.c +++ b/source/blender/blenkernel/intern/vfont.c @@ -201,7 +201,6 @@ IDTypeInfo IDType_ID_VF = { /***************************** VFont *******************************/ -/* The vfont code */ void BKE_vfont_free_data(struct VFont *vfont) { if (vfont->data) { @@ -1761,10 +1760,6 @@ bool BKE_vfont_to_curve_nubase(Object *ob, int mode, ListBase *r_nubase) return BKE_vfont_to_curve_ex(ob, ob->data, mode, r_nubase, NULL, NULL, NULL, NULL); } -/** - * Warning: expects to have access to evaluated data - * (i.e. passed object should be evaluated one...). - */ bool BKE_vfont_to_curve(Object *ob, int mode) { Curve *cu = ob->data; diff --git a/source/blender/blenkernel/intern/vfontdata_freetype.c b/source/blender/blenkernel/intern/vfontdata_freetype.c index bd58d156d06..9b79d5635d1 100644 --- a/source/blender/blenkernel/intern/vfontdata_freetype.c +++ b/source/blender/blenkernel/intern/vfontdata_freetype.c @@ -396,14 +396,6 @@ static bool check_freetypefont(PackedFile *pf) return success; } -/** - * Construct a new VFontData structure from - * Freetype font data in a PackedFile. - * - * \param pf: The font data. - * \retval A new VFontData structure, or NULL - * if unable to load. - */ VFontData *BKE_vfontdata_from_freetypefont(PackedFile *pf) { VFontData *vfd = NULL; diff --git a/source/blender/blenkernel/intern/volume.cc b/source/blender/blenkernel/intern/volume.cc index 05734aaf77f..130aa957491 100644 --- a/source/blender/blenkernel/intern/volume.cc +++ b/source/blender/blenkernel/intern/volume.cc @@ -1240,7 +1240,6 @@ const VolumeGrid *BKE_volume_grid_active_get_for_read(const Volume *volume) return BKE_volume_grid_get_for_read(volume, index); } -/* Tries to find a grid with the given name. Make sure that the volume has been loaded. */ const VolumeGrid *BKE_volume_grid_find_for_read(const Volume *volume, const char *name) { int num_grids = BKE_volume_num_grids(volume); @@ -1380,7 +1379,6 @@ int BKE_volume_grid_channels(const VolumeGrid *grid) return 0; } -/* Transformation from index space to object space. */ void BKE_volume_grid_transform_matrix(const VolumeGrid *volume_grid, float mat[4][4]) { #ifdef WITH_OPENVDB diff --git a/source/blender/blenkernel/intern/workspace.c b/source/blender/blenkernel/intern/workspace.c index ac3608ffd33..e3fe1e04368 100644 --- a/source/blender/blenkernel/intern/workspace.c +++ b/source/blender/blenkernel/intern/workspace.c @@ -321,13 +321,6 @@ WorkSpace *BKE_workspace_add(Main *bmain, const char *name) return new_workspace; } -/** - * Remove \a workspace by freeing itself and its data. This is a higher-level wrapper that - * calls #workspace_free_data (through #BKE_id_free) to free the workspace data, and frees - * other data-blocks owned by \a workspace and its layouts (currently that is screens only). - * - * Always use this to remove (and free) workspaces. Don't free non-ID workspace members here. - */ void BKE_workspace_remove(Main *bmain, WorkSpace *workspace) { for (WorkSpaceLayout *layout = workspace->layouts.first, *layout_next; layout; @@ -371,9 +364,6 @@ void BKE_workspace_instance_hook_free(const Main *bmain, WorkSpaceInstanceHook * MEM_freeN(hook); } -/** - * Add a new layout to \a workspace for \a screen. - */ WorkSpaceLayout *BKE_workspace_layout_add(Main *bmain, WorkSpace *workspace, bScreen *screen, @@ -436,13 +426,6 @@ WorkSpaceLayout *BKE_workspace_layout_find(const WorkSpace *workspace, const bSc return NULL; } -/** - * Find the layout for \a screen without knowing which workspace to look in. - * Can also be used to find the workspace that contains \a screen. - * - * \param r_workspace: Optionally return the workspace that contains the - * looked up layout (if found). - */ WorkSpaceLayout *BKE_workspace_layout_find_global(const Main *bmain, const bScreen *screen, WorkSpace **r_workspace) @@ -466,15 +449,6 @@ WorkSpaceLayout *BKE_workspace_layout_find_global(const Main *bmain, return NULL; } -/** - * Circular workspace layout iterator. - * - * \param callback: Custom function which gets executed for each layout. - * Can return false to stop iterating. - * \param arg: Custom data passed to each \a callback call. - * - * \return the layout at which \a callback returned false. - */ WorkSpaceLayout *BKE_workspace_layout_iter_circular(const WorkSpace *workspace, WorkSpaceLayout *start, bool (*callback)(const WorkSpaceLayout *layout, @@ -566,18 +540,11 @@ void BKE_workspace_active_set(WorkSpaceInstanceHook *hook, WorkSpace *workspace) } } -/** - * Get the layout that is active for \a hook (which is the visible layout for the active workspace - * in \a hook). - */ WorkSpaceLayout *BKE_workspace_active_layout_get(const WorkSpaceInstanceHook *hook) { return hook->act_layout; } -/** - * Get the layout to be activated should \a workspace become or be the active workspace in \a hook. - */ WorkSpaceLayout *BKE_workspace_active_layout_for_workspace_get(const WorkSpaceInstanceHook *hook, const WorkSpace *workspace) { @@ -590,17 +557,6 @@ WorkSpaceLayout *BKE_workspace_active_layout_for_workspace_get(const WorkSpaceIn return workspace_relation_get_data_matching_parent(&workspace->hook_layout_relations, hook); } -/** - * \brief Activate a layout - * - * Sets \a layout as active for \a workspace when activated through or already active in \a hook. - * So when the active workspace of \a hook is \a workspace, \a layout becomes the active layout of - * \a hook too. See #BKE_workspace_active_set(). - * - * \a workspace does not need to be active for this. - * - * WorkSpaceInstanceHook.act_layout should only be modified directly to update the layout pointer. - */ void BKE_workspace_active_layout_set(WorkSpaceInstanceHook *hook, const int winid, WorkSpace *workspace, diff --git a/source/blender/blenkernel/intern/writeavi.c b/source/blender/blenkernel/intern/writeavi.c index 4635db98514..a4f20f980b4 100644 --- a/source/blender/blenkernel/intern/writeavi.c +++ b/source/blender/blenkernel/intern/writeavi.c @@ -315,7 +315,6 @@ static void context_free_avi(void *context_v) #endif /* WITH_AVI */ -/* similar to BKE_image_path_from_imformat() */ void BKE_movie_filepath_get(char *string, const RenderData *rd, bool preview, const char *suffix) { bMovieHandle *mh = BKE_movie_handle_get(rd->im_format.imtype); diff --git a/source/blender/blenkernel/nla_private.h b/source/blender/blenkernel/nla_private.h index 3e13ba602a4..93014c1b859 100644 --- a/source/blender/blenkernel/nla_private.h +++ b/source/blender/blenkernel/nla_private.h @@ -165,18 +165,30 @@ typedef struct NlaKeyframingContext { /* --------------- NLA Functions (not to be used as a proper API) ----------------------- */ -/* convert from strip time <-> global time */ +/** + * Convert non clipped mapping for strip-time <-> global time: + * `mode = eNlaTime_ConvertModes[] -> NLATIME_CONVERT_*` + * + * Only secure for 'internal' (i.e. within AnimSys evaluation) operations, + * but should not be directly relied on for stuff which interacts with editors. + */ float nlastrip_get_frame(NlaStrip *strip, float cframe, short mode); /* --------------- NLA Evaluation (very-private stuff) ----------------------- */ /* these functions are only defined here to avoid problems with the order * in which they get defined. */ +/** + * Gets the strip active at the current time for a list of strips for evaluation purposes. + */ NlaEvalStrip *nlastrips_ctime_get_strip(ListBase *list, ListBase *strips, short index, const struct AnimationEvalContext *anim_eval_context, const bool flush_to_original); +/** + * Evaluates the given evaluation strip. + */ void nlastrip_evaluate(PointerRNA *ptr, NlaEvalData *channels, ListBase *modifiers, @@ -184,6 +196,9 @@ void nlastrip_evaluate(PointerRNA *ptr, NlaEvalSnapshot *snapshot, const struct AnimationEvalContext *anim_eval_context, const bool flush_to_original); +/** + * write the accumulated settings to. + */ void nladata_flush_channels(PointerRNA *ptr, NlaEvalData *channels, NlaEvalSnapshot *snapshot, @@ -193,6 +208,14 @@ void nlasnapshot_enable_all_blend_domain(NlaEvalSnapshot *snapshot); void nlasnapshot_ensure_channels(NlaEvalData *eval_data, NlaEvalSnapshot *snapshot); +/** + * Blends the \a lower_snapshot with the \a upper_snapshot into \a r_blended_snapshot according + * to the given \a upper_blendmode and \a upper_influence. + * + * For \a upper_snapshot, blending limited to values in the \a blend_domain. + * For Replace blend-mode, this allows the upper snapshot to have a location XYZ channel + * where only a subset of values are blended. + */ void nlasnapshot_blend(NlaEvalData *eval_data, NlaEvalSnapshot *lower_snapshot, NlaEvalSnapshot *upper_snapshot, @@ -200,6 +223,14 @@ void nlasnapshot_blend(NlaEvalData *eval_data, const float upper_influence, NlaEvalSnapshot *r_blended_snapshot); +/** + * Using \a blended_snapshot and \a lower_snapshot, we can solve for the \a r_upper_snapshot. + * + * Only channels that exist within \a blended_snapshot are inverted. + * + * For \a r_upper_snapshot, disables \a NlaEvalChannelSnapshot->remap_domain for failed inversions. + * Only values within the \a remap_domain are processed. + */ void nlasnapshot_blend_get_inverted_upper_snapshot(NlaEvalData *eval_data, NlaEvalSnapshot *lower_snapshot, NlaEvalSnapshot *blended_snapshot, diff --git a/source/blender/blenkernel/tracking_private.h b/source/blender/blenkernel/tracking_private.h index 8de6ec93a7c..0c1f73fa4b6 100644 --- a/source/blender/blenkernel/tracking_private.h +++ b/source/blender/blenkernel/tracking_private.h @@ -78,12 +78,21 @@ void tracking_get_search_origin_frame_pixel(int frame_width, const struct MovieTrackingMarker *marker, float frame_pixel[2]); +/** + * Each marker has 5 coordinates associated with it that get warped with + * tracking: the four corners ("pattern_corners"), and the center ("pos"). + * This function puts those 5 points into the appropriate frame for tracking + * (the "search" coordinate frame). + */ void tracking_get_marker_coords_for_tracking(int frame_width, int frame_height, const struct MovieTrackingMarker *marker, double search_pixel_x[5], double search_pixel_y[5]); +/** + * Inverse of #tracking_get_marker_coords_for_tracking. + */ void tracking_set_marker_coords_from_tracking(int frame_width, int frame_height, struct MovieTrackingMarker *marker, @@ -92,11 +101,23 @@ void tracking_set_marker_coords_from_tracking(int frame_width, /*********************** General purpose utility functions *************************/ +/** + * Place a disabled marker before or after specified ref_marker. + * + * If before is truth, disabled marker is placed before reference + * one, and it's placed after it otherwise. + * + * If there's already a marker at the frame where disabled one is expected to be placed, + * nothing will happen if overwrite is false. + */ void tracking_marker_insert_disabled(struct MovieTrackingTrack *track, const struct MovieTrackingMarker *ref_marker, bool before, bool overwrite); +/** + * Fill in Libmv C-API camera intrinsics options from tracking structure. + */ void tracking_cameraIntrinscisOptionsFromTracking( struct MovieTracking *tracking, int calibration_width, @@ -109,17 +130,26 @@ void tracking_trackingCameraFromIntrinscisOptions( struct libmv_TrackRegionOptions; +/** + * Fill in libmv tracker options structure with settings need to be used to perform track. + */ void tracking_configure_tracker(const MovieTrackingTrack *track, float *mask, bool is_backwards, struct libmv_TrackRegionOptions *options); +/** + * Get previous keyframed marker. + */ struct MovieTrackingMarker *tracking_get_keyframed_marker(struct MovieTrackingTrack *track, int current_frame, bool backwards); /*********************** Masking *************************/ +/** + * Region is in pixel space, relative to marker's center. + */ float *tracking_track_get_mask_for_region(int frame_width, int frame_height, const float region_min[2], @@ -145,11 +175,13 @@ typedef struct TrackingImageAccessor { SpinLock cache_lock; } TrackingImageAccessor; -/* Clips are used to access images of an actual footage. +/** + * Clips are used to access images of an actual footage. * Tracks are used to access masks associated with the tracks. * - * NOTE: Both clips and tracks arrays are copied into the image accessor. It means that the caller - * is allowed to pass temporary arrays which are only valid during initialization. */ + * \note Both clips and tracks arrays are copied into the image accessor. It means that the caller + * is allowed to pass temporary arrays which are only valid during initialization. + */ TrackingImageAccessor *tracking_image_accessor_new(MovieClip *clips[MAX_ACCESSOR_CLIP], int num_clips, MovieTrackingTrack **tracks, -- cgit v1.2.3