diff options
author | Campbell Barton <ideasman42@gmail.com> | 2021-12-07 09:19:15 +0300 |
---|---|---|
committer | Campbell Barton <ideasman42@gmail.com> | 2021-12-07 09:38:48 +0300 |
commit | ffc4c126f5416b04a01653e7a03451797b98aba4 (patch) | |
tree | ac63d70d33aae5ab1666c9c2f62058c9c1eebd5c /source/blender/blenkernel/BKE_bvhutils.h | |
parent | f159d49f56cedccd509ee93f5a5fb51f4f39eeb8 (diff) |
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
Diffstat (limited to 'source/blender/blenkernel/BKE_bvhutils.h')
-rw-r--r-- | source/blender/blenkernel/BKE_bvhutils.h | 63 |
1 files changed, 58 insertions, 5 deletions
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 |