diff options
author | Campbell Barton <ideasman42@gmail.com> | 2015-08-04 17:21:50 +0300 |
---|---|---|
committer | Campbell Barton <ideasman42@gmail.com> | 2015-08-04 19:09:03 +0300 |
commit | 62c8f46ab6f16f99bcf848936a690e01f4c9e770 (patch) | |
tree | 5945055a8cea5b65eccfeaa29629c942f27df575 /source/blender/blenlib/intern | |
parent | 23f54076db6d241af2a8f9404ab5f5b8072a4db0 (diff) |
Docs: comment functions in BLI & Py API
Diffstat (limited to 'source/blender/blenlib/intern')
-rw-r--r-- | source/blender/blenlib/intern/BLI_array.c | 21 | ||||
-rw-r--r-- | source/blender/blenlib/intern/BLI_kdopbvh.c | 10 | ||||
-rw-r--r-- | source/blender/blenlib/intern/BLI_memarena.c | 8 | ||||
-rw-r--r-- | source/blender/blenlib/intern/BLI_mempool.c | 7 | ||||
-rw-r--r-- | source/blender/blenlib/intern/array_utils.c | 26 |
5 files changed, 58 insertions, 14 deletions
diff --git a/source/blender/blenlib/intern/BLI_array.c b/source/blender/blenlib/intern/BLI_array.c index 01550ad1008..f681d222e69 100644 --- a/source/blender/blenlib/intern/BLI_array.c +++ b/source/blender/blenlib/intern/BLI_array.c @@ -30,18 +30,12 @@ * \ingroup bli * \brief A (mainly) macro array library. * - * This library needs to be changed to not use macros quite so heavily, - * and to be more of a complete array API. The way arrays are - * exposed to client code as normal C arrays is very useful though, imho. - * it does require some use of macros, however. + * This is an array library, used to manage array (re)allocation. * - * anyway, it's used a bit too heavily to simply rewrite as a - * more "correct" solution without macros entirely. I originally wrote this - * to be very easy to use, without the normal pain of most array libraries. - * This was especially helpful when it came to the massive refactors necessary - * for bmesh, and really helped to speed the process up. - joeedh + * \note This is primarily accessed via macros, + * functions are used to implement some of the internals. * - * little array macro library. example of usage: + * Example usage: * * \code{.c} * int *arr = NULL; @@ -55,9 +49,10 @@ * BLI_array_free(arr); * \endcode * - * arrays are buffered, using double-buffering (so on each reallocation, - * the array size is doubled). supposedly this should give good Big Oh - * behavior, though it may not be the best in practice. + * Arrays are over allocated, so each reallocation the array size is doubled. + * In situations where contiguous array access isn't needed, + * other solutions for allocation are available. + * Consider using on of: BLI_memarena.c, BLI_mempool.c, BLi_stack.c */ #include <string.h> diff --git a/source/blender/blenlib/intern/BLI_kdopbvh.c b/source/blender/blenlib/intern/BLI_kdopbvh.c index e4504bcaab1..6eab670b359 100644 --- a/source/blender/blenlib/intern/BLI_kdopbvh.c +++ b/source/blender/blenlib/intern/BLI_kdopbvh.c @@ -27,6 +27,16 @@ /** \file blender/blenlib/intern/BLI_kdopbvh.c * \ingroup bli + * \brief BVH-tree implementation. + * + * KD-Overlap-BVH, implements a bvh-tree structure with support for: + * + * - Ray-cast: + * #BLI_bvhtree_ray_cast, #BVHRayCastData + * - Nearest point on surface: + * #BLI_bvhtree_find_nearest, #BVHNearestData + * - Overlapping 2 trees: + * #BLI_bvhtree_overlap, #BVHOverlapData */ #include <assert.h> diff --git a/source/blender/blenlib/intern/BLI_memarena.c b/source/blender/blenlib/intern/BLI_memarena.c index dd0997c8e1c..2604dbafdc0 100644 --- a/source/blender/blenlib/intern/BLI_memarena.c +++ b/source/blender/blenlib/intern/BLI_memarena.c @@ -28,6 +28,14 @@ /** \file blender/blenlib/intern/BLI_memarena.c * \ingroup bli + * \brief Memory arena ADT. + * \section aboutmemarena Memory Arena + * + * Memory arena's are commonly used when the program + * needs to quickly allocate lots of little bits of data, + * which are all freed at the same moment. + * + * \note Memory can't be freed during the arenas lifetime. */ #include <stdlib.h> diff --git a/source/blender/blenlib/intern/BLI_mempool.c b/source/blender/blenlib/intern/BLI_mempool.c index 8fc5f97221d..7338804c685 100644 --- a/source/blender/blenlib/intern/BLI_mempool.c +++ b/source/blender/blenlib/intern/BLI_mempool.c @@ -27,8 +27,15 @@ /** \file blender/blenlib/intern/BLI_mempool.c * \ingroup bli + * \author Geoffrey Bantle * * Simple, fast memory allocator for allocating many elements of the same size. + * + * Supports: + * + * - Freeing chunks. + * - Iterating over allocated chunks + * (optionally when using the #BLI_MEMPOOL_ALLOW_ITER flag). */ #include <string.h> diff --git a/source/blender/blenlib/intern/array_utils.c b/source/blender/blenlib/intern/array_utils.c index 6c5dc5a7f1e..65c653c9b4f 100644 --- a/source/blender/blenlib/intern/array_utils.c +++ b/source/blender/blenlib/intern/array_utils.c @@ -21,6 +21,10 @@ /** \file blender/blenlib/intern/array_utils.c * \ingroup bli * \brief Generic array manipulation API. + * + * \warning Some array operations here are inherently inefficient, + * and only included for the cases where the performance is acceptable. + * Use with care. */ #include <string.h> #include <stdlib.h> @@ -35,7 +39,11 @@ #include "BLI_strict_flags.h" - +/** + *In-place array reverse. + * + * Access via #BLI_array_reverse + */ void _bli_array_reverse(void *arr_v, unsigned int arr_len, size_t arr_stride) { const unsigned int arr_stride_uint = (unsigned int)arr_stride; @@ -54,6 +62,12 @@ void _bli_array_reverse(void *arr_v, unsigned int arr_len, size_t arr_stride) } } +/** + * In-place array wrap. + * (rotate the array one step forward or backwards). + * + * Access via #BLI_array_wrap + */ void _bli_array_wrap(void *arr_v, unsigned int arr_len, size_t arr_stride, int dir) { char *arr = arr_v; @@ -74,6 +88,12 @@ void _bli_array_wrap(void *arr_v, unsigned int arr_len, size_t arr_stride, int d } } +/** + *In-place array permute. + * (re-arrange elemrnts based on an array of indices). + * + * Access via #BLI_array_wrap + */ void _bli_array_permute( void *arr_v, const unsigned int arr_len, const size_t arr_stride, const unsigned int *order, void *arr_temp) @@ -105,6 +125,10 @@ void _bli_array_permute( } /** + * 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, unsigned int arr_len, size_t arr_stride, const void *p) |