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_solvers.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_solvers.h')
-rw-r--r-- | source/blender/blenlib/BLI_math_solvers.h | 62 |
1 files changed, 59 insertions, 3 deletions
diff --git a/source/blender/blenlib/BLI_math_solvers.h b/source/blender/blenlib/BLI_math_solvers.h index 39a79efc7e2..32d4577899c 100644 --- a/source/blender/blenlib/BLI_math_solvers.h +++ b/source/blender/blenlib/BLI_math_solvers.h @@ -35,22 +35,61 @@ extern "C" { # pragma GCC diagnostic ignored "-Wredundant-decls" #endif -/********************************** Eigen Solvers *********************************/ +/* -------------------------------------------------------------------- */ +/** \name Eigen Solvers + * \{ */ +/** + * \brief Compute the eigen values and/or vectors of given 3D symmetric (aka adjoint) matrix. + * + * \param m3: the 3D symmetric matrix. + * \return r_eigen_values the computed eigen values (NULL if not needed). + * \return r_eigen_vectors the computed eigen vectors (NULL if not needed). + */ bool BLI_eigen_solve_selfadjoint_m3(const float m3[3][3], float r_eigen_values[3], float r_eigen_vectors[3][3]); +/** + * \brief Compute the SVD (Singular Values Decomposition) of given 3D matrix (m3 = USV*). + * + * \param m3: the matrix to decompose. + * \return r_U the computed left singular vector of \a m3 (NULL if not needed). + * \return r_S the computed singular values of \a m3 (NULL if not needed). + * \return r_V the computed right singular vector of \a m3 (NULL if not needed). + */ void BLI_svd_m3(const float m3[3][3], float r_U[3][3], float r_S[3], float r_V[3][3]); -/***************************** Simple Solvers ************************************/ +/** \} */ +/* -------------------------------------------------------------------- */ +/** \name Simple Solvers + * \{ */ + +/** + * \brief Solve a tridiagonal system of equations: + * + * a[i] * r_x[i-1] + b[i] * r_x[i] + c[i] * r_x[i+1] = d[i] + * + * Ignores a[0] and c[count-1]. Uses the Thomas algorithm, e.g. see wiki. + * + * \param r_x: output vector, may be shared with any of the input ones + * \return true if success + */ bool BLI_tridiagonal_solve( const float *a, const float *b, const float *c, const float *d, float *r_x, const int count); +/** + * \brief Solve a possibly cyclic tridiagonal system using the Sherman-Morrison formula. + * + * \param r_x: output vector, may be shared with any of the input ones + * \return true if success + */ bool BLI_tridiagonal_solve_cyclic( const float *a, const float *b, const float *c, const float *d, float *r_x, const int count); -/* Generic 3 variable Newton's method solver. */ +/** + * Generic 3 variable Newton's method solver. + */ typedef void (*Newton3D_DeltaFunc)(void *userdata, const float x[3], float r_delta[3]); typedef void (*Newton3D_JacobianFunc)(void *userdata, const float x[3], float r_jacobian[3][3]); typedef bool (*Newton3D_CorrectionFunc)(void *userdata, @@ -58,6 +97,21 @@ typedef bool (*Newton3D_CorrectionFunc)(void *userdata, float step[3], float x_next[3]); +/** + * \brief Solve a generic f(x) = 0 equation using Newton's method. + * + * \param func_delta: Callback computing the value of f(x). + * \param func_jacobian: Callback computing the Jacobian matrix of the function at x. + * \param func_correction: Callback for forcing the search into an arbitrary custom domain. + * May be NULL. + * \param userdata: Data for the callbacks. + * \param epsilon: Desired precision. + * \param max_iterations: Limit on the iterations. + * \param trace: Enables logging to console. + * \param x_init: Initial solution vector. + * \param result: Final result. + * \return true if success + */ bool BLI_newton3d_solve(Newton3D_DeltaFunc func_delta, Newton3D_JacobianFunc func_jacobian, Newton3D_CorrectionFunc func_correction, @@ -72,6 +126,8 @@ bool BLI_newton3d_solve(Newton3D_DeltaFunc func_delta, # pragma GCC diagnostic pop #endif +/** \} */ + #ifdef __cplusplus } #endif |