103 lines
5.0 KiB
C
103 lines
5.0 KiB
C
#ifndef INCLUDED_C_MATRIX_H
|
||
#define INCLUDED_C_MATRIX_H
|
||
|
||
#ifndef INCLUDED_C_TYPES_H
|
||
#include <c_Types.h>
|
||
#endif /*INCLUDED_C_TYPES_H*/
|
||
|
||
|
||
#ifndef INCLUDED_C_ALLOCATOR_H
|
||
#include <c_Allocator.h>
|
||
#endif /*INCLUDED_C_ALLOCATOR_H*/
|
||
|
||
|
||
/* ------------------------------------------------------------------------------------------------------------------ */
|
||
/* */
|
||
|
||
// 元素对元素算子：将 a 和 b 运算后的结果写入 out 中
|
||
typedef void (*c_Matrix_OpFn_t)(void* out, const void* a, const void* b, void* ud);
|
||
|
||
// 变号算子：将 in 取负（或执行共轭对调等）后写入 out 中
|
||
typedef void (*c_Matrix_NegFn_t)(void* out, const void* in, void* ud);
|
||
|
||
|
||
typedef struct {
|
||
void* data; // 一维扁平化的连续行优先（Row-Major）存储区
|
||
c_size_t rows; // 矩阵的固定总行数
|
||
c_size_t cols; // 矩阵的固定总列数
|
||
c_size_t item_size; // 单个元素的字节大小
|
||
c_Allocator_t allocator; // 内部绑定的自主内存管理器
|
||
} c_Matrix_t;
|
||
|
||
/* ------------------------------------------------------------------------------------------------------------------ */
|
||
/* */
|
||
|
||
c_err_t c_Matrix_Init(c_Matrix_t* self, c_size_t rows, c_size_t cols, c_size_t item_size, c_Allocator_t* allocator);
|
||
void c_Matrix_Destroy(c_Matrix_t* self);
|
||
|
||
// 核心定点操作 API (安全值复制模式)
|
||
c_err_t c_Matrix_Write(c_Matrix_t* self, c_size_t r, c_size_t c, const void* item);
|
||
c_err_t c_Matrix_Read(const c_Matrix_t* self, c_size_t r, c_size_t c, void* out_item);
|
||
void* c_Matrix_Get(const c_Matrix_t* self, c_size_t r, c_size_t c);
|
||
|
||
// 矩阵高级辅助操作
|
||
c_err_t c_Matrix_Fill(c_Matrix_t* self, const void* item);
|
||
c_err_t c_Matrix_CopyRow(const c_Matrix_t* self, c_size_t r, void* out_row_buffer);
|
||
|
||
// 内联高频辅助接口
|
||
C_STATIC_FORCE_INLINE c_size_t c_Matrix_Rows(const c_Matrix_t* self) { return self ? self->rows : 0; }
|
||
C_STATIC_FORCE_INLINE c_size_t c_Matrix_Cols(const c_Matrix_t* self) { return self ? self->cols : 0; }
|
||
|
||
/* ------------------------------------------------------------------------------------------------------------------ */
|
||
/* */
|
||
|
||
// 1. 矩阵与矩阵之间的加、减、乘、除（其中加减除为 Element-wise 逐元素运算，乘法为标准线性代数矩阵乘法）
|
||
c_err_t c_Matrix_Add(c_Matrix_t* out, const c_Matrix_t* lhs, const c_Matrix_t* rhs, c_Matrix_OpFn_t add_op, void* ud);
|
||
c_err_t c_Matrix_Sub(c_Matrix_t* out, const c_Matrix_t* lhs, const c_Matrix_t* rhs, c_Matrix_OpFn_t sub_op, void* ud);
|
||
c_err_t c_Matrix_Div(c_Matrix_t* out, const c_Matrix_t* lhs, const c_Matrix_t* rhs, c_Matrix_OpFn_t div_op, void* ud);
|
||
|
||
// 标准线性代数矩阵乘法 (Matrix Multiplication)：要求 lhs 的列数等于 rhs 的行数
|
||
// 内部包含累加逻辑，因此除了乘法算子，还需要额外传入一个加法算子
|
||
c_err_t c_Matrix_Mul(c_Matrix_t* out, const c_Matrix_t* lhs, const c_Matrix_t* rhs,
|
||
c_Matrix_OpFn_t mul_op, c_Matrix_OpFn_t add_op, void* ud);
|
||
|
||
// 2. 矩阵与标量（Scalar）的加减乘除（即矩阵中的每一个元素都与外部单值标量进行运算）
|
||
c_err_t c_Matrix_AddScalar(c_Matrix_t* out, const c_Matrix_t* in, const void* scalar, c_Matrix_OpFn_t add_op, void* ud);
|
||
c_err_t c_Matrix_SubScalar(c_Matrix_t* out, const c_Matrix_t* in, const void* scalar, c_Matrix_OpFn_t sub_op, void* ud);
|
||
c_err_t c_Matrix_MulScalar(c_Matrix_t* out, const c_Matrix_t* in, const void* scalar, c_Matrix_OpFn_t mul_op, void* ud);
|
||
c_err_t c_Matrix_DivScalar(c_Matrix_t* out, const c_Matrix_t* in, const void* scalar, c_Matrix_OpFn_t div_op, void* ud);
|
||
|
||
/* ------------------------------------------------------------------------------------------------------------------ */
|
||
/* */
|
||
|
||
/**
|
||
* @brief 矩阵转置 (Matrix Transpose)
|
||
* @param out 存储结果的目标矩阵。空间几何拓扑必须满足：out->rows == in->cols 且 out->cols == in->rows
|
||
* @param in 输入的原矩阵 (M x N)
|
||
* @return c_err_t 成功返回 C_ERR_OK
|
||
*/
|
||
c_err_t c_Matrix_Transpose(c_Matrix_t* out, const c_Matrix_t* in);
|
||
|
||
/* ------------------------------------------------------------------------------------------------------------------ */
|
||
/* */
|
||
|
||
|
||
/**
|
||
* @brief 泛型矩阵行列式求解 (Matrix Determinant)
|
||
* @note 采用经典的拉普拉斯代数余子式递归展开法（Laplace Expansion）
|
||
* @param self 目标矩阵，空间拓扑必须为方阵：self->rows == self->cols
|
||
* @param out_det 外部提供用以承接最终行列式标量值的缓冲区（大小必须 >= item_size）
|
||
* @param add_op 加法算子
|
||
* @param sub_op 减法算子
|
||
* @param mul_op 乘法算子
|
||
* @param neg_op 变号/取负算子
|
||
* @param ud 用户自定义上下文指针
|
||
* @return c_err_t 成功返回 C_ERR_OK，方阵校验失败返回 C_ERR_OUTOFBOUND
|
||
*/
|
||
c_err_t c_Matrix_Determinant(c_Matrix_t* self, void* out_det,
|
||
c_Matrix_OpFn_t add_op, c_Matrix_OpFn_t sub_op,
|
||
c_Matrix_OpFn_t mul_op, c_Matrix_NegFn_t neg_op,
|
||
void* ud);
|
||
|
||
#endif /*INCLUDED_C_MATRIX_H*/
|