diff options
author | Campbell Barton <ideasman42@gmail.com> | 2021-12-09 12:01:44 +0300 |
---|---|---|
committer | Campbell Barton <ideasman42@gmail.com> | 2021-12-09 12:01:44 +0300 |
commit | 9e365069afe156f33fadfad9705e1325f894cd54 (patch) | |
tree | 78373044d029feb51f987b45208e0c1a36958625 /source/blender/blenlib/BLI_math_base.h | |
parent | d8b42751625c915113b64f5a2d9c72f19f009fee (diff) |
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
Diffstat (limited to 'source/blender/blenlib/BLI_math_base.h')
-rw-r--r-- | source/blender/blenlib/BLI_math_base.h | 76 |
1 files changed, 72 insertions, 4 deletions
diff --git a/source/blender/blenlib/BLI_math_base.h b/source/blender/blenlib/BLI_math_base.h index 9b54f780296..83822481112 100644 --- a/source/blender/blenlib/BLI_math_base.h +++ b/source/blender/blenlib/BLI_math_base.h @@ -97,6 +97,7 @@ extern "C" { /******************************* Float ******************************/ +/* powf is really slow for raising to integer powers. */ MINLINE float pow2f(float x); MINLINE float pow3f(float x); MINLINE float pow4f(float x); @@ -120,11 +121,18 @@ MINLINE double interpd(double a, double b, double t); MINLINE float ratiof(float min, float max, float pos); MINLINE double ratiod(double min, double max, double pos); +/** + * Map a normalized value, i.e. from interval [0, 1] to interval [a, b]. + */ MINLINE float scalenorm(float a, float b, float x); +/** + * Map a normalized value, i.e. from interval [0, 1] to interval [a, b]. + */ MINLINE double scalenormd(double a, double b, double x); /* NOTE: Compilers will upcast all types smaller than int to int when performing arithmetic * operation. */ + MINLINE int square_s(short a); MINLINE int square_uchar(unsigned char a); MINLINE int cube_s(short a); @@ -170,7 +178,23 @@ MINLINE int clamp_i(int value, int min, int max); MINLINE float clamp_f(float value, float min, float max); MINLINE size_t clamp_z(size_t value, size_t min, size_t max); +/** + * Almost-equal for IEEE floats, using absolute difference method. + * + * \param max_diff: the maximum absolute difference. + */ MINLINE int compare_ff(float a, float b, const float max_diff); +/** + * Almost-equal for IEEE floats, using their integer representation + * (mixing ULP and absolute difference methods). + * + * \param max_diff: is the maximum absolute difference (allows to take care of the near-zero area, + * where relative difference methods cannot really work). + * \param max_ulps: is the 'maximum number of floats + 1' + * allowed between \a a and \a b to consider them equal. + * + * \see https://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/ + */ MINLINE int compare_ff_relative(float a, float b, const float max_diff, const int max_ulps); MINLINE bool compare_threshold_relative(const float value1, const float value2, @@ -180,13 +204,25 @@ MINLINE float signf(float f); MINLINE int signum_i_ex(float a, float eps); MINLINE int signum_i(float a); +/** + * Used for zoom values. + */ MINLINE float power_of_2(float f); +/** + * Returns number of (base ten) *significant* digits of integer part of given float + * (negative in case of decimal-only floats, 0.01 returns -1 e.g.). + */ MINLINE int integer_digits_f(const float f); +/** + * Returns number of (base ten) *significant* digits of integer part of given double + * (negative in case of decimal-only floats, 0.01 returns -1 e.g.). + */ MINLINE int integer_digits_d(const double d); MINLINE int integer_digits_i(const int i); -/* these don't really fit anywhere but were being copied about a lot */ +/* These don't really fit anywhere but were being copied about a lot. */ + MINLINE int is_power_of_2_i(int n); MINLINE int power_of_2_max_i(int n); MINLINE int power_of_2_min_i(int n); @@ -196,9 +232,19 @@ MINLINE unsigned int power_of_2_min_u(unsigned int x); MINLINE unsigned int log2_floor_u(unsigned int x); MINLINE unsigned int log2_ceil_u(unsigned int x); +/** + * Integer division that rounds 0.5 up, particularly useful for color blending + * with integers, to avoid gradual darkening when rounding down. + */ MINLINE int divide_round_i(int a, int b); +/** + * modulo that handles negative numbers, works the same as Python's. + */ MINLINE int mod_i(int i, int n); +/** + * Round to closest even number, halfway cases are rounded away from zero. + */ MINLINE float round_to_even(float f); MINLINE signed char round_fl_to_char(float a); @@ -230,18 +276,40 @@ MINLINE int round_db_to_int_clamp(double a); MINLINE unsigned int round_db_to_uint_clamp(double a); int pow_i(int base, int exp); + +/** + * \param ndigits: must be between 0 and 21. + */ double double_round(double x, int ndigits); +/** + * Floor to the nearest power of 10, e.g.: + * - 15.0 -> 10.0 + * - 0.015 -> 0.01 + * - 1.0 -> 1.0 + * + * \param f: Value to floor, must be over 0.0. + * \note If we wanted to support signed values we could if this becomes necessary. + */ float floor_power_of_10(float f); +/** + * Ceiling to the nearest power of 10, e.g.: + * - 15.0 -> 100.0 + * - 0.015 -> 0.1 + * - 1.0 -> 1.0 + * + * \param f: Value to ceiling, must be over 0.0. + * \note If we wanted to support signed values we could if this becomes necessary. + */ float ceil_power_of_10(float f); #ifdef BLI_MATH_GCC_WARN_PRAGMA # pragma GCC diagnostic pop #endif -/* asserts, some math functions expect normalized inputs - * check the vector is unit length, or zero length (which can't be helped in some cases). - */ +/* Asserts, some math functions expect normalized inputs + * check the vector is unit length, or zero length (which can't be helped in some cases). */ + #ifndef NDEBUG /** \note 0.0001 is too small because normals may be converted from short's: see T34322. */ # define BLI_ASSERT_UNIT_EPSILON 0.0002f |