forked from bartvdbraak/blender
Docs: comment functions in BLI & Py API
This commit is contained in:
parent
23f54076db
commit
62c8f46ab6
@ -61,7 +61,7 @@ def abspath(path, start=None, library=None):
|
||||
|
||||
:arg start: Relative to this path,
|
||||
when not set the current filename is used.
|
||||
:type start: string
|
||||
:type start: string or bytes
|
||||
:arg library: The library this path is from. This is only included for
|
||||
convenience, when the library is not None its path replaces *start*.
|
||||
:type library: :class:`bpy.types.Library`
|
||||
@ -90,9 +90,11 @@ def relpath(path, start=None):
|
||||
"""
|
||||
Returns the path relative to the current blend file using the "//" prefix.
|
||||
|
||||
:arg path: An absolute path.
|
||||
:type path: string or bytes
|
||||
:arg start: Relative to this path,
|
||||
when not set the current filename is used.
|
||||
:type start: string
|
||||
:type start: string or bytes
|
||||
"""
|
||||
if isinstance(path, bytes):
|
||||
if not path.startswith(b"//"):
|
||||
@ -112,6 +114,9 @@ def is_subdir(path, directory):
|
||||
"""
|
||||
Returns true if *path* in a subdirectory of *directory*.
|
||||
Both paths must be absolute.
|
||||
|
||||
:arg path: An absolute path.
|
||||
:type path: string or bytes
|
||||
"""
|
||||
from os.path import normpath, normcase
|
||||
path = normpath(normcase(path))
|
||||
@ -129,7 +134,7 @@ def clean_name(name, replace="_"):
|
||||
may cause problems under various circumstances,
|
||||
such as writing to a file.
|
||||
All characters besides A-Z/a-z, 0-9 are replaced with "_"
|
||||
or the replace argument if defined.
|
||||
or the *replace* argument if defined.
|
||||
"""
|
||||
|
||||
if replace != "_":
|
||||
|
@ -27,11 +27,6 @@
|
||||
|
||||
/** \file BLI_memarena.h
|
||||
* \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.
|
||||
*/
|
||||
|
||||
#ifndef __BLI_MEMARENA_H__
|
||||
|
@ -30,8 +30,6 @@
|
||||
|
||||
/** \file BLI_mempool.h
|
||||
* \ingroup bli
|
||||
* \author Geoffrey Bantle
|
||||
* \brief Simple fast memory allocator for fixed size chunks.
|
||||
*/
|
||||
|
||||
#ifdef __cplusplus
|
||||
@ -46,10 +44,6 @@ struct BLI_mempool_chunk;
|
||||
|
||||
typedef struct BLI_mempool BLI_mempool;
|
||||
|
||||
/* allow_iter allows iteration on this mempool. note: this requires that the
|
||||
* first four bytes of the elements never contain the character string
|
||||
* 'free'. use with care.*/
|
||||
|
||||
BLI_mempool *BLI_mempool_create(unsigned int esize, unsigned int totelem,
|
||||
unsigned int pchunk, unsigned int flag) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT;
|
||||
void *BLI_mempool_alloc(BLI_mempool *pool) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1);
|
||||
@ -82,6 +76,11 @@ typedef struct BLI_mempool_iter {
|
||||
/* flag */
|
||||
enum {
|
||||
BLI_MEMPOOL_NOP = 0,
|
||||
/** allow iterating on this mempool.
|
||||
*
|
||||
* \note this requires that the first four bytes of the elements never begin with 'free'
|
||||
* \note order of iteration is only assured to be the order of allocation when no chunks have been freed.
|
||||
*/
|
||||
BLI_MEMPOOL_ALLOW_ITER = (1 << 0),
|
||||
};
|
||||
|
||||
|
@ -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>
|
||||
|
@ -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>
|
||||
|
@ -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>
|
||||
|
@ -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>
|
||||
|
@ -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)
|
||||
|
Loading…
Reference in New Issue
Block a user