[Bf-blender-cvs] [9e365069afe] master: Cleanup: move public doc-strings into headers for 'blenlib'
Campbell Barton
noreply at git.blender.org
Thu Dec 9 10:04:00 CET 2021
Commit: 9e365069afe156f33fadfad9705e1325f894cd54
Author: Campbell Barton
Date: Thu Dec 9 20:01:44 2021 +1100
Branches: master
https://developer.blender.org/rB9e365069afe156f33fadfad9705e1325f894cd54
Cleanup: move public doc-strings into headers for 'blenlib'
- 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
===================================================================
M source/blender/blenlib/BLI_array.h
M source/blender/blenlib/BLI_array_store.h
M source/blender/blenlib/BLI_array_utils.h
M source/blender/blenlib/BLI_astar.h
M source/blender/blenlib/BLI_bitmap.h
M source/blender/blenlib/BLI_bitmap_draw_2d.h
M source/blender/blenlib/BLI_boxpack_2d.h
M source/blender/blenlib/BLI_buffer.h
M source/blender/blenlib/BLI_convexhull_2d.h
M source/blender/blenlib/BLI_dlrbTree.h
M source/blender/blenlib/BLI_dynstr.h
M source/blender/blenlib/BLI_edgehash.h
M source/blender/blenlib/BLI_expr_pylike_eval.h
M source/blender/blenlib/BLI_fileops.h
M source/blender/blenlib/BLI_ghash.h
M source/blender/blenlib/BLI_gsqueue.h
M source/blender/blenlib/BLI_hash_md5.h
M source/blender/blenlib/BLI_hash_mm2a.h
M source/blender/blenlib/BLI_heap.h
M source/blender/blenlib/BLI_heap_simple.h
M source/blender/blenlib/BLI_index_mask.hh
M source/blender/blenlib/BLI_kdopbvh.h
M source/blender/blenlib/BLI_lasso_2d.h
M source/blender/blenlib/BLI_linklist.h
M source/blender/blenlib/BLI_listbase.h
M source/blender/blenlib/BLI_math_base.h
M source/blender/blenlib/BLI_math_boolean.hh
M source/blender/blenlib/BLI_math_color.h
M source/blender/blenlib/BLI_math_geom.h
M source/blender/blenlib/BLI_math_interp.h
M source/blender/blenlib/BLI_math_matrix.h
M source/blender/blenlib/BLI_math_rotation.h
M source/blender/blenlib/BLI_math_solvers.h
M source/blender/blenlib/BLI_math_statistics.h
M source/blender/blenlib/BLI_math_time.h
M source/blender/blenlib/BLI_math_vector.h
M source/blender/blenlib/BLI_memarena.h
M source/blender/blenlib/BLI_memblock.h
M source/blender/blenlib/BLI_memiter.h
M source/blender/blenlib/BLI_mempool.h
M source/blender/blenlib/BLI_mesh_intersect.hh
M source/blender/blenlib/BLI_noise.h
M source/blender/blenlib/BLI_path_util.h
M source/blender/blenlib/BLI_polyfill_2d.h
M source/blender/blenlib/BLI_polyfill_2d_beautify.h
M source/blender/blenlib/BLI_rand.h
M source/blender/blenlib/BLI_rand.hh
M source/blender/blenlib/BLI_rect.h
M source/blender/blenlib/BLI_scanfill.h
M source/blender/blenlib/BLI_smallhash.h
M source/blender/blenlib/BLI_stack.h
M source/blender/blenlib/BLI_string.h
M source/blender/blenlib/BLI_string_search.h
M source/blender/blenlib/BLI_string_utf8.h
M source/blender/blenlib/BLI_string_utils.h
M source/blender/blenlib/BLI_task.h
M source/blender/blenlib/BLI_threads.h
M source/blender/blenlib/BLI_timecode.h
M source/blender/blenlib/BLI_utildefines.h
M source/blender/blenlib/BLI_uvproject.h
M source/blender/blenlib/BLI_voxel.h
M source/blender/blenlib/intern/BLI_array.c
M source/blender/blenlib/intern/BLI_assert.c
M source/blender/blenlib/intern/BLI_dynstr.c
M source/blender/blenlib/intern/BLI_filelist.c
M source/blender/blenlib/intern/BLI_ghash.c
M source/blender/blenlib/intern/BLI_ghash_utils.c
M source/blender/blenlib/intern/BLI_heap.c
M source/blender/blenlib/intern/BLI_heap_simple.c
M source/blender/blenlib/intern/BLI_kdopbvh.c
M source/blender/blenlib/intern/BLI_linklist.c
M source/blender/blenlib/intern/BLI_memarena.c
M source/blender/blenlib/intern/BLI_memblock.c
M source/blender/blenlib/intern/BLI_memiter.c
M source/blender/blenlib/intern/BLI_mempool.c
M source/blender/blenlib/intern/BLI_mempool_private.h
M source/blender/blenlib/intern/DLRB_tree.c
M source/blender/blenlib/intern/array_store.c
M source/blender/blenlib/intern/array_utils.c
M source/blender/blenlib/intern/astar.c
M source/blender/blenlib/intern/bitmap.c
M source/blender/blenlib/intern/bitmap_draw_2d.c
M source/blender/blenlib/intern/boxpack_2d.c
M source/blender/blenlib/intern/buffer.c
M source/blender/blenlib/intern/convexhull_2d.c
M source/blender/blenlib/intern/edgehash.c
M source/blender/blenlib/intern/expr_pylike_eval.c
M source/blender/blenlib/intern/fileops.c
M source/blender/blenlib/intern/gsqueue.c
M source/blender/blenlib/intern/hash_md5.c
M source/blender/blenlib/intern/hash_mm2a.c
M source/blender/blenlib/intern/index_mask.cc
M source/blender/blenlib/intern/lasso_2d.c
M source/blender/blenlib/intern/listbase.c
M source/blender/blenlib/intern/math_base.c
M source/blender/blenlib/intern/math_base_inline.c
M source/blender/blenlib/intern/math_boolean.cc
M source/blender/blenlib/intern/math_color.c
M source/blender/blenlib/intern/math_color_inline.c
M source/blender/blenlib/intern/math_geom.c
M source/blender/blenlib/intern/math_geom_inline.c
M source/blender/blenlib/intern/math_interp.c
M source/blender/blenlib/intern/math_matrix.c
M source/blender/blenlib/intern/math_rotation.c
M source/blender/blenlib/intern/math_solvers.c
M source/blender/blenlib/intern/math_statistics.c
M source/blender/blenlib/intern/math_time.c
M source/blender/blenlib/intern/math_vector.c
M source/blender/blenlib/intern/math_vector_inline.c
M source/blender/blenlib/intern/memory_utils.c
M source/blender/blenlib/intern/mesh_boolean.cc
M source/blender/blenlib/intern/mesh_intersect.cc
M source/blender/blenlib/intern/noise.c
M source/blender/blenlib/intern/path_util.c
M source/blender/blenlib/intern/polyfill_2d.c
M source/blender/blenlib/intern/polyfill_2d_beautify.c
M source/blender/blenlib/intern/rand.cc
M source/blender/blenlib/intern/rct.c
M source/blender/blenlib/intern/scanfill_utils.c
M source/blender/blenlib/intern/smallhash.c
M source/blender/blenlib/intern/stack.c
M source/blender/blenlib/intern/storage.c
M source/blender/blenlib/intern/string.c
M source/blender/blenlib/intern/string_search.cc
M source/blender/blenlib/intern/string_utf8.c
M source/blender/blenlib/intern/string_utils.c
M source/blender/blenlib/intern/system.c
M source/blender/blenlib/intern/system_win32.c
M source/blender/blenlib/intern/task_iterator.c
M source/blender/blenlib/intern/threads.cc
M source/blender/blenlib/intern/timecode.c
M source/blender/blenlib/intern/uvproject.c
M source/blender/blenlib/intern/voxel.c
===================================================================
diff --git a/source/blender/blenlib/BLI_array.h b/source/blender/blenlib/BLI_array.h
index 084f573e8c7..5b15bb979f5 100644
--- a/source/blender/blenlib/BLI_array.h
+++ b/source/blender/blenlib/BLI_array.h
@@ -28,7 +28,7 @@
/** \name Internal defines
* \{ */
-/** this returns the entire size of the array, including any buffering. */
+/** This returns the entire size of the array, including any buffering. */
#define _bli_array_totalsize_dynamic(arr) \
(((arr) == NULL) ? 0 : MEM_allocN_len(arr) / sizeof(*(arr)))
@@ -44,8 +44,12 @@
/**
* BLI_array.c
*
- * Doing the realloc in a macro isn't so simple,
+ * Doing the reallocation in a macro isn't so simple,
* so use a function the macros can use.
+ *
+ * This function is only to be called via macros.
+ *
+ * \note The caller must adjust \a arr_len
*/
void _bli_array_grow_func(void **arr_p,
const void *arr_static,
@@ -64,8 +68,9 @@ void _bli_array_grow_func(void **arr_p,
void *_##arr##_static = NULL
/**
- * this will use stack space, up to maxstatic array elements, before
- * switching to dynamic heap allocation */
+ * This will use stack space, up to `maxstatic` array elements,
+ * before switching to dynamic heap allocation.
+ */
#define BLI_array_staticdeclare(arr, maxstatic) \
int _##arr##_len = 0; \
char _##arr##_static[maxstatic * sizeof(*(arr))]
@@ -77,7 +82,8 @@ void _bli_array_grow_func(void **arr_p,
* Grow the array by a fixed number of items.
*
* Allow for a large 'num' value when the new size is more than double
- * to allocate the exact sized array. */
+ * to allocate the exact sized array.
+ */
#define BLI_array_reserve(arr, num) \
(void)((((void *)(arr) == NULL) && \
((void *)(_##arr##_static) != \
@@ -95,12 +101,16 @@ void _bli_array_grow_func(void **arr_p,
num, \
"BLI_array." #arr)))
-/** returns length of array */
+/**
+ * Returns length of array.
+ */
#define BLI_array_grow_items(arr, num) (BLI_array_reserve(arr, num), (_##arr##_len += num))
#define BLI_array_grow_one(arr) BLI_array_grow_items(arr, 1)
-/** appends an item to the array. */
+/**
+ * Appends an item to the array.
+ */
#define BLI_array_append(arr, item) \
((void)BLI_array_grow_one(arr), (void)(arr[_##arr##_len - 1] = item))
@@ -111,7 +121,9 @@ void _bli_array_grow_func(void **arr_p,
#define BLI_array_append_r(arr, item) \
((void)BLI_array_grow_one(arr), (void)(arr[_##arr##_len - 1] = item), (&arr[_##arr##_len - 1]))
-/** appends (grows) & returns a pointer to the uninitialized memory */
+/**
+ * Appends (grows) & returns a pointer to the uninitialized memory.
+ */
#define BLI_array_append_ret(arr) (BLI_array_reserve(arr, 1), &arr[(_##arr##_len++)])
#define BLI_array_free(arr) \
@@ -127,7 +139,8 @@ void _bli_array_grow_func(void **arr_p,
/**
* Resets the logical size of an array to zero, but doesn't
- * free the memory. */
+ * free the memory.
+ */
#define BLI_array_clear(arr) \
{ \
_##arr##_len = 0; \
@@ -135,30 +148,32 @@ void _bli_array_grow_func(void **arr_p,
((void)0)
/**
- * Set the length of the array, doesn't actually increase the allocated array
- * size. don't use this unless you know what you're doing. */
+ * Set the length of the array, doesn't actually increase the allocated array size.
+ * Don't use this unless you know what you're doing.
+ */
#define BLI_array_len_set(arr, len) \
{ \
_##arr##_len = (len); \
} \
((void)0)
-/** only to prevent unused warnings */
+/**
+ * Only to prevent unused warnings.
+ */
#define BLI_array_fake_user(arr) ((void)_##arr##_len, (void)_##arr##_static)
/** \} */
/* -------------------------------------------------------------------- */
/** \name Generic Array Utils
- * other useful defines
- * (unrelated to the main array macros)
*
+ * Other useful defines (unrelated to the main array macros).
* \{ */
/**
- * Not part of the 'API' but handy functions,
- * same purpose as #BLI_array_staticdeclare()
- * but use when the max size is known ahead of time */
+ * Not part of the 'API' but handy functions, same purpose as #BLI_array_staticdeclare()
+ * but use when the max size is known ahead of time.
+ */
#define BLI_array_fixedstack_declare(arr, maxstatic, realsize, allocstr) \
char _##arr##_static[maxstatic * sizeof(*(arr))]; \
const bool _##arr##_is_static = ((void *)_##arr##_static) != \
diff --git a/source/blender/blenlib/BLI_array_store.h b/source/blender/blenlib/BLI_array_store.h
index 78d718117ba..0be361d4ab9 100644
--- a/source/blender/blenlib/BLI_array_store.h
+++ b/source/blender/blenlib/BLI_array_store.h
@@ -28,25 +28,88 @@ extern "C" {
typedef struct BArrayState BArrayState;
typedef struct BArrayStore BArrayStore;
+/**
+ * Create a new array store, which can store any number of arrays
+ * as long as their stride matches.
+ *
+ * \param stride: `sizeof()` each element,
+ *
+ * \note while a stride of `1` will always work,
+ * its less efficient since duplicate chunks of memory will be searched
+ * at positions unaligned with the array data.
+ *
+ * \param chunk_count: Number of elements to split each chunk into.
+ * - A small value increases the ability to de-duplicate chunks,
+ * but adds overhead by increasing the number of chunks to look up when searching for duplicates,
+ * as well as some overhead constructing the original array again, with more calls to `memcpy`.
+ * - Larger values reduce the *book keeping* overhead,
+ * but increase the chance a small,
+ * isolated change will cause a larger amount of data to be duplicated.
+ *
+ * \return A new array store, to be freed with #BLI_array_store_destroy.
+ */
BArrayStore *BLI_array_store_create(unsigned int stride, unsigned int chunk_count);
+/**
+ * Free the #BArrayStore, including all states and chunks.
+ */
void BLI_array_store_destroy(BArrayStore *bs);
+/**
+ * Clear all contents, allowing reuse of \a bs.
+ */
void BLI_array_store_clear(BArrayStore *bs);
-/* find the memory used by all states (expanded & real) */
+/**
+ * Find the memory used by all states (expanded & real).
+ *
+ * \return the total amount of memory that would be used by getting the arrays for all states.
+ */
size_t BLI_array_store_calc_size_expanded_get(const BArrayStore *bs);
+/**
+ * \return the amount of memory used by all #BChunk.data
+ * (duplicate chunks are only counted once).
+ */
size_t BLI_array_store_calc_size_compacted_get(const BArrayStore *bs);
+/**
+ *
+ * \param data: Data used to create
+ * \param state_reference: The state to use as a reference when adding the new state,
+ * typically this is the previous state,
+ * however it can be any previously created state from this \a bs.
+ *
+ * \return The new state,
+ * which is used by the caller as a handle to get back the contents of \a data.
+ * This may be removed using #BLI_array_store_state_remove,
+ * otherwise it will be removed with #BLI_array_store_destroy.
+ */
BArrayState *BLI_array_store_state_add(BArrayStore *bs,
const void *data,
const size_t data_len,
const BArrayState *state_reference);
+/**
+ * Remove a state and free any unused #BChunk data.
+ *
+ * The states can be freed in any order.
+ */
void BLI_array_store_state_remove(BArrayStore *bs, BArrayState *state);
+/**
+ * \return the expanded size of the array,
+ * use this to know how much memory to allocate #BLI_array_store_state_data_get's argument.
+ */
size_t BLI_array_store_state_size_get(BArrayState *state);
+/**
+ * Fill in existing allocated memory with the contents of \a state.
+ */
void BLI_array_store_state_data_get(BArrayState *state, void *data);
+/**
+ * Allocate an array for \a state and return it.
+ */
void *BLI_array_store_state_data_get_alloc(BArrayState *state, size_t *r_data_len);
-/* only for tests */
+/**
+ * \note Only for tests.
+ */
bool BLI_array_store_is_valid(BArrayStore *bs);
#ifdef __cplusplus
diff --git a/source/blender/blenlib/BLI_array_utils.h b/source/blender/blenlib/BLI_array_utils.h
index 52d41173a0e..eb14b030bf9 100644
--- a/source/blender/blenlib/BLI_array_utils.h
+++ b/source/blender/blenlib/BLI_array_utils.h
@@ -28,12 +28,29 @@
extern "C" {
#endif
+/**
+ * In-place array reverse.
+ *
+ * Access via #BLI_array_reverse
+ */
void _bli_array_reverse(void *arr, uint arr_len, size_t arr_stride);
#define BLI_array_reverse(arr, arr_len) _bli_array_reverse(arr, arr_len, sizeof(*(arr)))
+/**
+ * In-place array wrap.
+ * (rotate the array one step forward or backwards).
+ *
+ * Access via #BLI_array_wrap
+ */
void _bli_array_wrap(void *arr, uint arr_len, size_t arr_stride, int dir);
#define BLI_array_wrap(arr, arr_len, dir) _bli_array_wrap(arr, arr_len, sizeof(*(arr)), dir)
+/**
+ *In-place array permute.
+ * (re-arrange elements based on an array of indices).
+ *
+ * Access via #BLI_array_wrap
+ */
void _bli_array_permute(
void *arr, const uint arr_len, const size_t arr_stride, const uint *order, void *arr_temp);
#define BLI_array_permute(arr, arr_len, order) \
@@ -41,13 +58,30 @@ void _bli_array_permute(
#define BLI_array_permute_ex(arr, arr_len, order, arr_temp) \
_bli_array_permute(arr, arr_len, sizeof(*(arr)), order, arr_temp)
+/**
+ * In-place array de-duplication of an ordered array.
+ *
+ * \return The new length of the array.
+ *
+ * Access via #BLI_array_deduplicate_ordered
+ */
uint _bli_array_deduplicate_ordered(void *arr, uint arr_len, size_t arr_stride);
#define BLI_array_deduplicate_ordered(arr, arr_len) \
_bli_array_deduplicate_ordered(arr, arr_len, sizeof(*(arr)))
+/**
+ * Find the first index of an item in an array.
+ *
+ * Access via #BLI_array_findindex
+ *
+ * \note Not efficient, use for error checks/asserts.
+ */
int _bli_array_findindex(const void *arr, uint arr_len, size_t arr_stride, const void *p);
#define BLI_array_findindex(arr, arr_len, p) _bli_array_findindex(arr, arr_len, sizeof(*(arr)), p)
+/**
+ * A version of #BLI_array_findindex that searches from the end of the list.
+ */
int _bli_array_rfindindex(const void *arr, uint a
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-blender-cvs
mailing list