commit fdb2167b4ad9f140708e38bfcc30fdbd3168bf1e Author: Campbell Barton Date: Mon Dec 20 19:01:14 2021 +1100 Docs: use doxygen formatting for BLI Differentiate doc-strings from title/section text. diff --git a/source/blender/blenlib/BLI_assert.h b/source/blender/blenlib/BLI_assert.h index 6019f0f3566..e32a19cfc25 100644 --- a/source/blender/blenlib/BLI_assert.h +++ b/source/blender/blenlib/BLI_assert.h @@ -30,6 +30,7 @@ extern "C" { #endif /* Utility functions. */ + void _BLI_assert_print_pos(const char *file, const int line, const char *function, const char *id); void _BLI_assert_print_extra(const char *str); void _BLI_assert_print_backtrace(void); diff --git a/source/blender/blenlib/BLI_color.hh b/source/blender/blenlib/BLI_color.hh index d93bd7f6f76..dce625777b9 100644 --- a/source/blender/blenlib/BLI_color.hh +++ b/source/blender/blenlib/BLI_color.hh @@ -73,27 +73,27 @@ namespace blender { * - Add non RGB spaces/storages ColorXyz. */ -/* Enumeration containing the different alpha modes. */ +/** Enumeration containing the different alpha modes. */ enum class eAlpha { - /* Color and alpha are unassociated. */ + /** Color and alpha are unassociated. */ Straight, - /* Color and alpha are associated. */ + /** Color and alpha are associated. */ Premultiplied, }; std::ostream &operator<<(std::ostream &stream, const eAlpha &space); -/* Enumeration containing internal spaces. */ +/** Enumeration containing internal spaces. */ enum class eSpace { - /* Blender theme color space (sRGB). */ + /** Blender theme color space (sRGB). */ Theme, - /* Blender internal scene linear color space (maps to SceneReference role in OCIO). */ + /** Blender internal scene linear color space (maps to SceneReference role in OCIO). */ SceneLinear, - /* Blender internal scene linear color space compressed to be stored in 4 uint8_t. */ + /** Blender internal scene linear color space compressed to be stored in 4 uint8_t. */ SceneLinearByteEncoded, }; std::ostream &operator<<(std::ostream &stream, const eSpace &space); -/* Template class to store RGBA values with different precision, space and alpha association. */ +/** Template class to store RGBA values with different precision, space and alpha association. */ template class ColorRGBA { public: ChannelStorageType r, g, b, a; @@ -153,11 +153,13 @@ template class ColorRGB }; /* Forward declarations of concrete color classes. */ + template class ColorSceneLinear4f; template class ColorSceneLinearByteEncoded4b; template class ColorTheme4; /* Forward declaration of precision conversion methods. */ + BLI_INLINE ColorTheme4 BLI_color_convert_to_theme4f(const ColorTheme4 &srgb4b); BLI_INLINE ColorTheme4 BLI_color_convert_to_theme4b(const ColorTheme4 &srgb4f); @@ -354,6 +356,7 @@ BLI_color_convert_to_theme4b(const ColorSceneLinear4f &scene_l } /* Internal roles. For convenience to shorten the type names and hide complexity. */ + using ColorGeometry4f = ColorSceneLinear4f; using ColorGeometry4b = ColorSceneLinearByteEncoded4b; diff --git a/source/blender/blenlib/BLI_compiler_compat.h b/source/blender/blenlib/BLI_compiler_compat.h index bd8f84cedd6..023fea3853e 100644 --- a/source/blender/blenlib/BLI_compiler_compat.h +++ b/source/blender/blenlib/BLI_compiler_compat.h @@ -34,7 +34,7 @@ #if (defined(__GNUC__) || defined(__clang__)) && defined(__cplusplus) extern "C++" { -/* Some magic to be sure we don't have reference in the type. */ +/** Some magic to be sure we don't have reference in the type. */ template static inline T decltype_helper(T x) { return x; diff --git a/source/blender/blenlib/BLI_delaunay_2d.h b/source/blender/blenlib/BLI_delaunay_2d.h index 658dcadadce..db0df95499f 100644 --- a/source/blender/blenlib/BLI_delaunay_2d.h +++ b/source/blender/blenlib/BLI_delaunay_2d.h @@ -222,7 +222,7 @@ void BLI_delaunay_2d_cdt_free(CDT_result *result); namespace blender::meshintersect { -/* vec2 is a 2d vector with Arith_t as the type for coordinates. */ +/** #vec2 is a 2d vector with #Arith_t as the type for coordinates. */ template struct vec2_impl; template<> struct vec2_impl { typedef double2 type; diff --git a/source/blender/blenlib/BLI_dlrbTree.h b/source/blender/blenlib/BLI_dlrbTree.h index 72f18244d5b..3cf849efaef 100644 --- a/source/blender/blenlib/BLI_dlrbTree.h +++ b/source/blender/blenlib/BLI_dlrbTree.h @@ -40,7 +40,7 @@ extern "C" { /** \name Base Structs * \{ */ -/* Basic Layout for a Node */ +/** Basic Layout for a Node. */ typedef struct DLRBT_Node { /* ListBase capabilities */ struct DLRBT_Node *next, *prev; @@ -53,7 +53,7 @@ typedef struct DLRBT_Node { /* ... for nice alignment, next item should usually be a char too... */ } DLRBT_Node; -/* Red/Black defines for tree_col */ +/** Red/Black defines for tree_col. */ typedef enum eDLRBT_Colors { DLRBT_BLACK = 0, DLRBT_RED, @@ -61,7 +61,7 @@ typedef enum eDLRBT_Colors { /* -------- */ -/* The Tree Data */ +/** The Tree Data. */ typedef struct DLRBT_Tree { /* ListBase capabilities */ void *first, *last; /* these should be based on DLRBT_Node-s */ diff --git a/source/blender/blenlib/BLI_endian_switch.h b/source/blender/blenlib/BLI_endian_switch.h index b512133b34c..e6ccbe4629a 100644 --- a/source/blender/blenlib/BLI_endian_switch.h +++ b/source/blender/blenlib/BLI_endian_switch.h @@ -30,6 +30,7 @@ extern "C" { #endif /* BLI_endian_switch_inline.h */ + BLI_INLINE void BLI_endian_switch_int16(short *val) ATTR_NONNULL(1); BLI_INLINE void BLI_endian_switch_uint16(unsigned short *val) ATTR_NONNULL(1); BLI_INLINE void BLI_endian_switch_int32(int *val) ATTR_NONNULL(1); @@ -40,6 +41,7 @@ BLI_INLINE void BLI_endian_switch_uint64(uint64_t *val) ATTR_NONNULL(1); BLI_INLINE void BLI_endian_switch_double(double *val) ATTR_NONNULL(1); /* endian_switch.c */ + void BLI_endian_switch_int16_array(short *val, const int size) ATTR_NONNULL(1); void BLI_endian_switch_uint16_array(unsigned short *val, const int size) ATTR_NONNULL(1); void BLI_endian_switch_int32_array(int *val, const int size) ATTR_NONNULL(1); diff --git a/source/blender/blenlib/BLI_endian_switch_inline.h b/source/blender/blenlib/BLI_endian_switch_inline.h index ec4cfe4801a..31be7fd47e4 100644 --- a/source/blender/blenlib/BLI_endian_switch_inline.h +++ b/source/blender/blenlib/BLI_endian_switch_inline.h @@ -33,6 +33,7 @@ extern "C" { * use bit shifting instead. */ /* *** 16 *** */ + BLI_INLINE void BLI_endian_switch_int16(short *val) { BLI_endian_switch_uint16((unsigned short *)val); @@ -48,6 +49,7 @@ BLI_INLINE void BLI_endian_switch_uint16(unsigned short *val) } /* *** 32 *** */ + BLI_INLINE void BLI_endian_switch_int32(int *val) { BLI_endian_switch_uint32((unsigned int *)val); @@ -67,6 +69,7 @@ BLI_INLINE void BLI_endian_switch_float(float *val) } /* *** 64 *** */ + BLI_INLINE void BLI_endian_switch_int64(int64_t *val) { BLI_endian_switch_uint64((uint64_t *)val); diff --git a/source/blender/blenlib/BLI_filereader.h b/source/blender/blenlib/BLI_filereader.h index da223cddf40..f232ad72cc4 100644 --- a/source/blender/blenlib/BLI_filereader.h +++ b/source/blender/blenlib/BLI_filereader.h @@ -47,7 +47,7 @@ typedef ssize_t (*FileReaderReadFn)(struct FileReader *reader, void *buffer, siz typedef off64_t (*FileReaderSeekFn)(struct FileReader *reader, off64_t offset, int whence); typedef void (*FileReaderCloseFn)(struct FileReader *reader); -/* General structure for all FileReaders, implementations add custom fields at the end. */ +/** General structure for all #FileReaders, implementations add custom fields at the end. */ typedef struct FileReader { FileReaderReadFn read; FileReaderSeekFn seek; @@ -64,16 +64,16 @@ typedef struct FileReader { * take over the base FileReader and will clean it up when their clean() is called. */ -/* Create FileReader from raw file descriptor. */ +/** Create #FileReader from raw file descriptor. */ FileReader *BLI_filereader_new_file(int filedes) ATTR_WARN_UNUSED_RESULT; -/* Create FileReader from raw file descriptor using memory-mapped IO. */ +/** Create #FileReader from raw file descriptor using memory-mapped IO. */ FileReader *BLI_filereader_new_mmap(int filedes) ATTR_WARN_UNUSED_RESULT; -/* Create FileReader from a region of memory. */ +/** Create #FileReader from a region of memory. */ FileReader *BLI_filereader_new_memory(const void *data, size_t len) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(); -/* Create FileReader from applying `Zstd` decompression on an underlying file. */ +/** Create #FileReader from applying `Zstd` decompression on an underlying file. */ FileReader *BLI_filereader_new_zstd(FileReader *base) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(); -/* Create FileReader from applying `Gzip` decompression on an underlying file. */ +/** Create #FileReader from applying `Gzip` decompression on an underlying file. */ FileReader *BLI_filereader_new_gzip(FileReader *base) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(); #ifdef __cplusplus diff --git a/source/blender/blenlib/BLI_ghash.h b/source/blender/blenlib/BLI_ghash.h index 0194f9aad40..fca705535a3 100644 --- a/source/blender/blenlib/BLI_ghash.h +++ b/source/blender/blenlib/BLI_ghash.h @@ -450,7 +450,7 @@ void *BLI_gset_pop_key(GSet *gs, const void *key) ATTR_WARN_UNUSED_RESULT; /* rely on inline api for now */ -/* so we can cast but compiler sees as different */ +/** Use a GSet specific type so we can cast but compiler sees as different */ typedef struct GSetIterator { GHashIterator _ghi #if defined(__GNUC__) && !defined(__clang__) diff --git a/source/blender/blenlib/BLI_kdtree_impl.h b/source/blender/blenlib/BLI_kdtree_impl.h index 26a22fc2ac4..35dbf141c92 100644 --- a/source/blender/blenlib/BLI_kdtree_impl.h +++ b/source/blender/blenlib/BLI_kdtree_impl.h @@ -74,7 +74,7 @@ int BLI_kdtree_nd_(calc_duplicates_fast)(const KDTree *tree, int BLI_kdtree_nd_(deduplicate)(KDTree *tree); -/* Versions of find/range search that take a squared distance callback to support bias. */ +/** Versions of find/range search that take a squared distance callback to support bias. */ int BLI_kdtree_nd_(find_nearest_n_with_len_squared_cb)( const KDTree *tree, const float co[KD_DIMS], diff --git a/source/blender/blenlib/BLI_linklist_lockfree.h b/source/blender/blenlib/BLI_linklist_lockfree.h index 142fa1cf243..d2083bdd44e 100644 --- a/source/blender/blenlib/BLI_linklist_lockfree.h +++ b/source/blender/blenlib/BLI_linklist_lockfree.h @@ -48,18 +48,19 @@ typedef void (*LockfreeeLinkNodeFreeFP)(void *link); /* NOTE: These functions are NOT safe for use from threads. */ /* NOTE: !!! I REPEAT: DO NOT USE THEM WITHOUT EXTERNAL LOCK !!! */ -/* Make list ready for lock-free access. */ +/** Make list ready for lock-free access. */ void BLI_linklist_lockfree_init(LockfreeLinkList *list); -/* Completely free the whole list, it is NOT re-usable after this. */ +/** Completely free the whole list, it is NOT re-usable after this. */ void BLI_linklist_lockfree_free(LockfreeLinkList *list, LockfreeeLinkNodeFreeFP free_func); -/* Remove all the elements from the list, keep it usable for further - * inserts. +/** + * Remove all the elements from the list, keep it usable for further inserts. */ void BLI_linklist_lockfree_clear(LockfreeLinkList *list, LockfreeeLinkNodeFreeFP free_func); -/* Begin iteration of lock-free linked list, starting with a +/** + * Begin iteration of lock-free linked list, starting with a * first user=defined node. Will ignore the dummy node. */ LockfreeLinkNode *BLI_linklist_lockfree_begin(LockfreeLinkList *list); diff --git a/source/blender/blenlib/BLI_math_base.h b/source/blender/blenlib/BLI_math_base.h index 83822481112..6c82bd89e64 100644 --- a/source/blender/blenlib/BLI_math_base.h +++ b/source/blender/blenlib/BLI_math_base.h @@ -76,8 +76,7 @@ #if defined(__GNUC__) # define NAN_FLT __builtin_nanf("") -#else -/* evil quiet NaN definition */ +#else /* evil quiet NaN definition */ static const int NAN_INT = 0x7FC00000; # define NAN_FLT (*((float *)(&NAN_INT))) #endif @@ -97,7 +96,8 @@ extern "C" { /******************************* Float ******************************/ -/* powf is really slow for raising to integer powers. */ +/* `powf` is really slow for raising to integer powers. */ + MINLINE float pow2f(float x); MINLINE float pow3f(float x); MINLINE float pow4f(float x); diff --git a/source/blender/blenlib/BLI_math_bits.h b/source/blender/blenlib/BLI_math_bits.h index e881f1a0e4e..70a54879446 100644 --- a/source/blender/blenlib/BLI_math_bits.h +++ b/source/blender/blenlib/BLI_math_bits.h @@ -28,24 +28,29 @@ extern "C" { #endif /* Search the value from LSB to MSB for a set bit. Returns index of this bit. */ + MINLINE int bitscan_forward_i(int a); MINLINE unsigned int bitscan_forward_uint(unsigned int a); MINLINE unsigned int bitscan_forward_uint64(unsigned long long a); /* Similar to above, but also clears the bit. */ + MINLINE int bitscan_forward_clear_i(int *a); MINLINE unsigned int bitscan_forward_clear_uint(unsigned int *a); /* Search the value from MSB to LSB for a set bit. Returns index of this bit. */ + MINLINE int bitscan_reverse_i(int a); MINLINE unsigned int bitscan_reverse_uint(unsigned int a); MINLINE unsigned int bitscan_reverse_uint64(unsigned long long a); /* Similar to above, but also clears the bit. */ + MINLINE int bitscan_reverse_clear_i(int *a); MINLINE unsigned int bitscan_reverse_clear_uint(unsigned int *a); /* NOTE: Those functions returns 2 to the power of index of highest order bit. */ + MINLINE unsigned int highest_order_bit_uint(unsigned int n); MINLINE unsigned short highest_order_bit_s(unsigned short n); diff --git a/source/blender/blenlib/BLI_math_geom.h b/source/blender/blenlib/BLI_math_geom.h index 55d118d17de..c2a5ffafa64 100644 --- a/source/blender/blenlib/BLI_math_geom.h +++ b/source/blender/blenlib/BLI_math_geom.h @@ -441,7 +441,9 @@ void isect_seg_seg_v3(const float a0[3], float r_a[3], float r_b[3]); -/* intersect Line-Line, shorts */ +/** + * Intersect Line-Line, integer. + */ int isect_seg_seg_v2_int(const int v1[2], const int v2[2], const int v3[2], const int v4[2]); /** * Get intersection point of two 2D segments. @@ -929,7 +931,7 @@ void interp_weights_quad_v3(float w[4], void interp_weights_poly_v3(float w[], float v[][3], const int n, const float co[3]); void interp_weights_poly_v2(float w[], float v[][2], const int n, const float co[2]); -/* (x1, v1)(t1=0)------(x2, v2)(t2=1), 0 (x, v)(t) */ +/** `(x1, v1)(t1=0)------(x2, v2)(t2=1), 0 (x, v)(t)`. */ void interp_cubic_v3(float x[3], float v[3], const float x1[3], diff --git a/source/blender/blenlib/BLI_math_matrix.h b/source/blender/blenlib/BLI_math_matrix.h index 3d8fe6f564a..90b74e2f504 100644 --- a/source/blender/blenlib/BLI_math_matrix.h +++ b/source/blender/blenlib/BLI_math_matrix.h @@ -56,16 +56,18 @@ void copy_m4_m2(float m1[4][4], const float m2[2][2]); void copy_m4_m4_db(double m1[4][4], const double m2[4][4]); /* double->float */ + void copy_m3_m3d(float m1[3][3], const double m2[3][3]); /* float->double */ + void copy_m3d_m3(double m1[3][3], const float m2[3][3]); void copy_m4d_m4(double m1[4][4], const float m2[4][4]); void swap_m3m3(float m1[3][3], float m2[3][3]); void swap_m4m4(float m1[4][4], float m2[4][4]); -/* Build index shuffle matrix */ +/** Build index shuffle matrix. */ void shuffle_m4(float R[4][4], const int index[4]); /** \} */ @@ -112,7 +114,8 @@ void mul_m4db_m4db_m4fl_uniq(double R[4][4], const double A[4][4], const float B void mul_m4_m4_pre(float R[4][4], const float A[4][4]); void mul_m4_m4_post(float R[4][4], const float B[4][4]); -/* mul_m3_series */ +/* Implement #mul_m3_series macro. */ + void _va_mul_m3_series_3(float R[3][3], const float M1[3][3], const float M2[3][3]) ATTR_NONNULL(); void _va_mul_m3_series_4(float R[3][3], const float M1[3][3], @@ -153,7 +156,9 @@ void _va_mul_m3_series_9(float R[3][3], const float M6[3][3], const float M7[3][3], const float M8[3][3]) ATTR_NONNULL(); -/* mul_m4_series */ + +/* Implement #mul_m4_series macro. */ + void _va_mul_m4_series_3(float R[4][4], const float M1[4][4], const float M2[4][4]) ATTR_NONNULL(); void _va_mul_m4_series_4(float R[4][4], const float M1[4][4], @@ -266,11 +271,13 @@ bool invert_m4_m4(float R[4][4], const float A[4][4]); */ bool invert_m4_m4_fallback(float R[4][4], const float A[4][4]); -/* double arithmetic (mixed float/double) */ +/* Double arithmetic (mixed float/double). */ + void mul_m4_v4d(const float M[4][4], double r[4]); void mul_v4d_m4v4d(double r[4], const float M[4][4], const double v[4]); -/* double matrix functions (no mixing types) */ +/* Double matrix functions (no mixing types). */ + void mul_v3_m3v3_db(double r[3], const double M[3][3], const double a[3]); void mul_m3_v3_db(const double M[3][3], double r[3]); @@ -282,7 +289,9 @@ void mul_m3_v3_db(const double M[3][3], double r[3]); void transpose_m3(float R[3][3]); void transpose_m3_m3(float R[3][3], const float M[3][3]); -/* seems obscure but in-fact a common operation */ +/** + * \note Seems obscure but in-fact a common operation. + */ void transpose_m3_m4(float R[3][3], const float M[4][4]); void transpose_m4(float R[4][4]); void transpose_m4_m4(float R[4][4], const float M[4][4]); diff --git a/source/blender/blenlib/BLI_math_rotation.h b/source/blender/blenlib/BLI_math_rotation.h index 5e72d502262..8106251684d 100644 --- a/source/blender/blenlib/BLI_math_rotation.h +++ b/source/blender/blenlib/BLI_math_rotation.h @@ -57,7 +57,8 @@ void unit_axis_angle(float axis[3], float *angle); void unit_qt(float q[4]); void copy_qt_qt(float q[4], const float a[4]); -/* arithmetic */ +/* Arithmetic. */ + void mul_qt_qtqt(float q[4], const float a[4], const float b[4]); /** * \note @@ -106,7 +107,8 @@ float dot_qtqt(const float a[4], const float b[4]); float normalize_qt(float q[4]); float normalize_qt_qt(float r[4], const float q[4]); -/* comparison */ +/* Comparison. */ + bool is_zero_qt(const float q[4]); /* interpolation */ @@ -122,7 +124,8 @@ void interp_dot_slerp(const float t, const float cosom, float r_w[2]); void interp_qt_qtqt(float q[4], const float a[4], const float b[4], const float t); void add_qt_qtqt(float q[4], const float a[4], const float b[4], const float t); -/* conversion */ +/* Conversion. */ + void quat_to_mat3(float mat[3][3], const float q[4]); void quat_to_mat4(float mat[4][4], const float q[4]); @@ -188,7 +191,8 @@ float angle_signed_qtqt(const float q1[4], const float q2[4]); */ void mat3_to_quat_is_ok(float q[4], const float mat[3][3]); -/* other */ +/* Other. */ + void print_qt(const char *str, const float q[4]); #define print_qt_id(q) print_qt(STRINGIFY(q), q) @@ -199,7 +203,8 @@ void print_qt(const char *str, const float q[4]); /** \name Axis Angle * \{ */ -/* conversion */ +/* Conversion. */ + void axis_angle_normalized_to_quat(float r[4], const float axis[3], const float angle); void axis_angle_to_quat(float r[4], const float axis[3], const float angle); /** @@ -271,32 +276,25 @@ void expmap_to_quat(float r[4], const float expmap[3]); /** \name XYZ Eulers * \{ */ -/* XYZ order. */ void eul_to_quat(float quat[4], const float eul[3]); -/* XYZ order */ void eul_to_mat3(float mat[3][3], const float eul[3]); -/* XYZ order */ void eul_to_mat4(float mat[4][4], const float eul[3]); -/* XYZ order */ void mat3_normalized_to_eul(float eul[3], const float mat[3][3]); -/* XYZ order */ void mat4_normalized_to_eul(float eul[3], const float mat[4][4]); void mat3_to_eul(float eul[3], const float mat[3][3]); void mat4_to_eul(float eul[3], const float mat[4][4]); -/* XYZ order */ void quat_to_eul(float eul[3], const float quat[4]); -/* XYZ order */ void mat3_normalized_to_compatible_eul(float eul[3], const float old[3], float mat[3][3]); void mat3_to_compatible_eul(float eul[3], const float old[3], float mat[3][3]); void quat_to_compatible_eul(float eul[3], const float oldrot[3], const float quat[4]); -/* order independent! */ -void compatible_eul(float eul[3], const float old[3]); - -/* XYZ order */ void rotate_eul(float eul[3], const char axis, const float angle); +/* Order independent. */ + +void compatible_eul(float eul[3], const float old[3]); + void add_eul_euleul(float r_eul[3], float a[3], float b[3], const short order); void sub_eul_euleul(float r_eul[3], float a[3], float b[3], const short order); diff --git a/source/blender/blenlib/BLI_math_vector.h b/source/blender/blenlib/BLI_math_vector.h index 8f955076baf..61090e30f7b 100644 --- a/source/blender/blenlib/BLI_math_vector.h +++ b/source/blender/blenlib/BLI_math_vector.h @@ -79,7 +79,9 @@ MINLINE void copy_v4_v4_char(char r[4], const char a[4]); MINLINE void copy_v2_v2_short(short r[2], const short a[2]); MINLINE void copy_v3_v3_short(short r[3], const short a[3]); MINLINE void copy_v4_v4_short(short r[4], const short a[4]); + /* int */ + MINLINE void zero_v3_int(int r[3]); MINLINE void copy_v2_v2_int(int r[2], const int a[2]); MINLINE void copy_v3_v3_int(int r[3], const int a[3]); diff --git a/source/blender/blenlib/BLI_mempool.h b/source/blender/blenlib/BLI_mempool.h index d6abae36e00..a3cf2a77646 100644 --- a/source/blender/blenlib/BLI_mempool.h +++ b/source/blender/blenlib/BLI_mempool.h @@ -103,14 +103,14 @@ void BLI_mempool_set_memory_debug(void); * \note this may easy to produce bugs with. */ -/* Private structure. */ +/** \note Private structure. */ typedef struct BLI_mempool_iter { BLI_mempool *pool; struct BLI_mempool_chunk *curchunk; unsigned int curindex; } BLI_mempool_iter; -/* flag */ +/** #BLI_mempool.flag */ enum { BLI_MEMPOOL_NOP = 0, /** allow iterating on this mempool. diff --git a/source/blender/blenlib/BLI_quadric.h b/source/blender/blenlib/BLI_quadric.h index fdb7d1e67ac..450653a20ea 100644 --- a/source/blender/blenlib/BLI_quadric.h +++ b/source/blender/blenlib/BLI_quadric.h @@ -31,18 +31,21 @@ typedef struct Quadric { double a2, ab, ac, ad, b2, bc, bd, c2, cd, d2; } Quadric; -/* conversion */ +/* Conversion. */ + void BLI_quadric_from_plane(Quadric *q, const double v[4]); void BLI_quadric_to_vector_v3(const Quadric *q, double v[3]); void BLI_quadric_clear(Quadric *q); -/* math */ +/* Math operations. */ + void BLI_quadric_add_qu_qu(Quadric *a, const Quadric *b); void BLI_quadric_add_qu_ququ(Quadric *r, const Quadric *a, const Quadric *b); void BLI_quadric_mul(Quadric *a, const double scalar); -/* solve */ +/* Solve. */ + double BLI_quadric_evaluate(const Quadric *q, const double v[3]); bool BLI_quadric_optimize(const Quadric *q, double v[3], const double epsilon); diff --git a/source/blender/blenlib/BLI_scanfill.h b/source/blender/blenlib/BLI_scanfill.h index 744d30397d4..ec7fa8f27a0 100644 --- a/source/blender/blenlib/BLI_scanfill.h +++ b/source/blender/blenlib/BLI_scanfill.h @@ -91,6 +91,7 @@ typedef struct ScanFillFace { } ScanFillFace; /* scanfill.c */ + struct ScanFillVert *BLI_scanfill_vert_add(ScanFillContext *sf_ctx, const float vec[3]); struct ScanFillEdge *BLI_scanfill_edge_add(ScanFillContext *sf_ctx, struct ScanFillVert *v1, diff --git a/source/blender/blenlib/BLI_session_uuid.h b/source/blender/blenlib/BLI_session_uuid.h index 887044e9b54..29e291add5a 100644 --- a/source/blender/blenlib/BLI_session_uuid.h +++ b/source/blender/blenlib/BLI_session_uuid.h @@ -33,18 +33,19 @@ extern "C" { #include "DNA_session_uuid_types.h" -/* Generate new UUID which is unique throughout the Blender session. */ +/** Generate new UUID which is unique throughout the Blender session. */ SessionUUID BLI_session_uuid_generate(void); -/* Check whether the UUID is properly generated. */ +/** Check whether the UUID is properly generated. */ bool BLI_session_uuid_is_generated(const SessionUUID *uuid); -/* Check whether two UUIDs are identical. */ +/** Check whether two UUIDs are identical. */ bool BLI_session_uuid_is_equal(const SessionUUID *lhs, const SessionUUID *rhs); uint64_t BLI_session_uuid_hash_uint64(const SessionUUID *uuid); /* Utility functions to make it possible to create GHash/GSet with UUID as a key. */ + uint BLI_session_uuid_ghash_hash(const void *uuid_v); bool BLI_session_uuid_ghash_compare(const void *lhs_v, const void *rhs_v); diff --git a/source/blender/blenlib/BLI_sort.h b/source/blender/blenlib/BLI_sort.h index 969816086e2..31a052eb79d 100644 --- a/source/blender/blenlib/BLI_sort.h +++ b/source/blender/blenlib/BLI_sort.h @@ -30,7 +30,7 @@ # define BLI_qsort_r qsort_r #endif -/* Quick sort re-entrant */ +/** Quick sort (re-entrant). */ typedef int (*BLI_sort_cmp_t)(const void *a, const void *b, void *ctx); void BLI_qsort_r(void *a, size_t n, size_t es, BLI_sort_cmp_t cmp, void *thunk) diff --git a/source/blender/blenlib/BLI_sys_types.h b/source/blender/blenlib/BLI_sys_types.h index 2740e3740f2..95327ff33b8 100644 --- a/source/blender/blenlib/BLI_sys_types.h +++ b/source/blender/blenlib/BLI_sys_types.h @@ -72,8 +72,8 @@ typedef uint64_t u_int64_t; #include /* size_t define */ #ifndef __cplusplus +/* The standard header is missing on some systems. */ # if defined(__APPLE__) || defined(__NetBSD__) -/* The standard header is missing on macOS. */ typedef unsigned int char32_t; # else # include diff --git a/source/blender/blenlib/BLI_system.h b/source/blender/blenlib/BLI_system.h index 0d5b2e6e2df..2e5e07d8407 100644 --- a/source/blender/blenlib/BLI_system.h +++ b/source/blender/blenlib/BLI_system.h @@ -30,7 +30,7 @@ int BLI_cpu_support_sse2(void); int BLI_cpu_support_sse41(void); void BLI_system_backtrace(FILE *fp); -/* Get CPU brand, result is to be MEM_freeN()-ed. */ +/** Get CPU brand, result is to be MEM_freeN()-ed. */ char *BLI_cpu_brand_string(void); /** @@ -45,15 +45,19 @@ char *BLI_cpu_brand_string(void); */ void BLI_hostname_get(char *buffer, size_t bufsize); -/* Get maximum addressable memory in megabytes. */ +/** Get maximum addressable memory in megabytes. */ size_t BLI_system_memory_max_in_megabytes(void); +/** Get maximum addressable memory in megabytes (clamped to #INT_MAX). */ int BLI_system_memory_max_in_megabytes_int(void); /* For `getpid`. */ #ifdef WIN32 # define BLI_SYSTEM_PID_H -/* void* since we really do not want to drag Windows.h in to get the proper typedef. */ +/** + * \note Use `void *` for `exception` since we really do not want to drag Windows.h + * in to get the proper `typedef`. + */ void BLI_windows_handle_exception(void *exception); #else diff --git a/source/blender/blenlib/BLI_task.h b/source/blender/blenlib/BLI_task.h index a67de2e2910..616237bc261 100644 --- a/source/blender/blenlib/BLI_task.h +++ b/source/blender/blenlib/BLI_task.h @@ -303,7 +303,7 @@ void BLI_task_parallel_mempool(struct BLI_mempool *mempool, TaskParallelMempoolFunc func, const TaskParallelSettings *settings); -/* TODO(sergey): Think of a better place for this. */ +/** TODO(sergey): Think of a better place for this. */ BLI_INLINE void BLI_parallel_range_settings_defaults(TaskParallelSettings *settings) { memset(settings, 0, sizeof(*settings)); diff --git a/source/blender/blenlib/BLI_threads.h b/source/blender/blenlib/BLI_threads.h index 6e60430ea38..7bae16f25ef 100644 --- a/source/blender/blenlib/BLI_threads.h +++ b/source/blender/blenlib/BLI_threads.h @@ -31,7 +31,7 @@ extern "C" { #endif -/* for tables, button in UI, etc */ +/** For tables, button in UI, etc. */ #define BLENDER_MAX_THREADS 1024 struct ListBase; diff --git a/source/blender/blenlib/BLI_timer.h b/source/blender/blenlib/BLI_timer.h index c219b5502f3..b1cc8d5514f 100644 --- a/source/blender/blenlib/BLI_timer.h +++ b/source/blender/blenlib/BLI_timer.h @@ -29,8 +29,11 @@ extern "C" { #endif -/* ret < 0: the timer will be removed. - * ret >= 0: the timer will be called again in ret seconds */ +/** + * \return A value of: + * - < 0: the timer will be removed. + * - >= 0: the timer will be called again in this number of seconds. + */ typedef double (*BLI_timer_func)(uintptr_t uuid, void *user_data); typedef void (*BLI_timer_data_free)(uintptr_t uuid, void *user_data); @@ -45,10 +48,10 @@ void BLI_timer_register(uintptr_t uuid, bool BLI_timer_is_registered(uintptr_t uuid); -/* Returns False when the timer does not exist (anymore). */ +/** Returns False when the timer does not exist (anymore). */ bool BLI_timer_unregister(uintptr_t uuid); -/* Execute all registered functions that are due. */ +/** Execute all registered functions that are due. */ void BLI_timer_execute(void); void BLI_timer_free(void); diff --git a/source/blender/blenlib/BLI_virtual_array.hh b/source/blender/blenlib/BLI_virtual_array.hh index 5103ac4b668..3ed9f14712e 100644 --- a/source/blender/blenlib/BLI_virtual_array.hh +++ b/source/blender/blenlib/BLI_virtual_array.hh @@ -44,7 +44,7 @@ namespace blender { -/* Forward declarations for generic virtual arrays. */ +/** Forward declarations for generic virtual arrays. */ namespace fn { class GVArray; class GVMutableArray; @@ -194,7 +194,7 @@ template class VArrayImpl { } }; -/* Similar to #VArrayImpl, but adds methods that allow modifying the referenced elements. */ +/** Similar to #VArrayImpl, but adds methods that allow modifying the referenced elements. */ template class VMutableArrayImpl : public VArrayImpl { public: using VArrayImpl::VArrayImpl; diff --git a/source/blender/blenlib/BLI_virtual_vector_array.hh b/source/blender/blenlib/BLI_virtual_vector_array.hh index ab5afd2d80a..7672a76d5de 100644 --- a/source/blender/blenlib/BLI_virtual_vector_array.hh +++ b/source/blender/blenlib/BLI_virtual_vector_array.hh @@ -29,7 +29,7 @@ namespace blender { -/* A readonly virtual array of vectors. */ +/** A read-only virtual array of vectors. */ template class VVectorArray { protected: int64_t size_; diff --git a/source/blender/blenlib/BLI_winstuff.h b/source/blender/blenlib/BLI_winstuff.h index cbf1716602a..568734ee8a7 100644 --- a/source/blender/blenlib/BLI_winstuff.h +++ b/source/blender/blenlib/BLI_winstuff.h @@ -88,7 +88,7 @@ typedef SSIZE_T ssize_t; # endif #endif -/* Directory reading compatibility with UNIX. */ +/** Directory reading compatibility with UNIX. */ struct dirent { int d_ino; int d_off; @@ -96,7 +96,7 @@ struct dirent { char *d_name; }; -/* intentionally opaque to users */ +/** Intentionally opaque to users. */ typedef struct __dirstream DIR; DIR *opendir(const char *path); @@ -105,6 +105,7 @@ int closedir(DIR *dp); const char *dirname(char *path); /* Windows utility functions. */ + bool BLI_windows_register_blend_extension(const bool background); void BLI_windows_get_default_root_dir(char root_dir[4]); int BLI_windows_get_executable_dir(char *str);