Math Engine Reference: Types

문서 탐색

Math Engine 전체 목차

개요

Math Engine component가 공유하는 중립 POD 값 type을 선언한다.

Scalar 기반 vector, quaternion과 행렬 값을 C ABI로 전달하기 위한 caller-owned type을 제공한다. 좌표 frame과 단위는 각 operation 계약에서 별도로 명시한다.

실행 원본: include/math_engine/math_engine_types.h
분류: 진입점·ABI·공통 계약

공개 API

Header 사용 시작

이 module의 public declaration을 사용하려면 installed SDK의 다음 header를 include한다.

#include <math_engine/math_engine_types.h>

Type과 callback

`math_engine_vec2_f64_t`

2차원 double vector 값이다. Component 순서는 x, y다.

typedef struct math_engine_vec2_f64 {
    double x; /**< 벡터의 첫 번째 Cartesian 성분. 단위와 좌표 frame은 소비 API가 정한다. */
    double y; /**< 벡터의 두 번째 Cartesian 성분. 단위와 좌표 frame은 소비 API가 정한다. */
} math_engine_vec2_f64_t;

math_engine_vec2_f64_t.x
벡터의 첫 번째 Cartesian 성분. 단위와 좌표 frame은 소비 API가 정한다.
```
double x;
```
math_engine_vec2_f64_t.y
벡터의 두 번째 Cartesian 성분. 단위와 좌표 frame은 소비 API가 정한다.
```
double y;
```

`math_engine_vec3_f64_t`

3차원 double vector 값이다. Component 순서는 x, y, z다.

typedef struct math_engine_vec3_f64 {
    double x; /**< 벡터의 첫 번째 Cartesian 성분. 단위와 좌표 frame은 소비 API가 정한다. */
    double y; /**< 벡터의 두 번째 Cartesian 성분. 단위와 좌표 frame은 소비 API가 정한다. */
    double z; /**< 벡터의 세 번째 Cartesian 성분. 단위와 좌표 frame은 소비 API가 정한다. */
} math_engine_vec3_f64_t;

math_engine_vec3_f64_t.x
벡터의 첫 번째 Cartesian 성분. 단위와 좌표 frame은 소비 API가 정한다.
```
double x;
```
math_engine_vec3_f64_t.y
벡터의 두 번째 Cartesian 성분. 단위와 좌표 frame은 소비 API가 정한다.
```
double y;
```
math_engine_vec3_f64_t.z
벡터의 세 번째 Cartesian 성분. 단위와 좌표 frame은 소비 API가 정한다.
```
double z;
```

`math_engine_vec4_f64_t`

4차원 double vector 값이다. Component 순서는 x, y, z, w다.

typedef struct math_engine_vec4_f64 {
    double x; /**< 벡터의 첫 번째 성분. 구체 의미와 단위는 소비 API가 정한다. */
    double y; /**< 벡터의 두 번째 성분. 구체 의미와 단위는 소비 API가 정한다. */
    double z; /**< 벡터의 세 번째 성분. 구체 의미와 단위는 소비 API가 정한다. */
    double w; /**< 벡터의 네 번째 성분. 동차좌표 여부 등 의미는 소비 API가 정한다. */
} math_engine_vec4_f64_t;

math_engine_vec4_f64_t.x
벡터의 첫 번째 성분. 구체 의미와 단위는 소비 API가 정한다.
```
double x;
```
math_engine_vec4_f64_t.y
벡터의 두 번째 성분. 구체 의미와 단위는 소비 API가 정한다.
```
double y;
```
math_engine_vec4_f64_t.z
벡터의 세 번째 성분. 구체 의미와 단위는 소비 API가 정한다.
```
double z;
```
math_engine_vec4_f64_t.w
벡터의 네 번째 성분. 동차좌표 여부 등 의미는 소비 API가 정한다.
```
double w;
```

`math_engine_quat_f64_t`

실수부가 먼저 오는 double quaternion 값이다.

typedef struct math_engine_quat_f64 {
    double w; /**< Quaternion의 scalar(실수) 성분. 회전 API에서는 unit quaternion이어야 한다. */
    double x; /**< Quaternion vector part의 x 성분. */
    double y; /**< Quaternion vector part의 y 성분. */
    double z; /**< Quaternion vector part의 z 성분. */
} math_engine_quat_f64_t;

math_engine_quat_f64_t.w
Quaternion의 scalar(실수) 성분. 회전 API에서는 unit quaternion이어야 한다.
```
double w;
```
math_engine_quat_f64_t.x
Quaternion vector part의 x 성분.
```
double x;
```
math_engine_quat_f64_t.y
Quaternion vector part의 y 성분.
```
double y;
```
math_engine_quat_f64_t.z
Quaternion vector part의 z 성분.
```
double z;
```

`math_engine_mat2_f64_t`

Row-major 2x2 double matrix 값이다. Index는 row * 2 + column 이다.

typedef struct math_engine_mat2_f64 {
    double values[4]; /**< Row-major 2x2 원소 배열. 원소 =(row, column)=은 =values[row * 2 + column]=이다. */
} math_engine_mat2_f64_t;

math_engine_mat2_f64_t.values
Row-major 2x2 원소 배열. 원소 (row, column)=은 =values[row * 2 + column] 이다.
```
double values[4];
```

`math_engine_mat3_f64_t`

Row-major 3x3 double matrix 값이다. Index는 row * 3 + column 이다.

typedef struct math_engine_mat3_f64 {
    double values[9]; /**< Row-major 3x3 원소 배열. 원소 =(row, column)=은 =values[row * 3 + column]=이다. */
} math_engine_mat3_f64_t;

math_engine_mat3_f64_t.values
Row-major 3x3 원소 배열. 원소 (row, column)=은 =values[row * 3 + column] 이다.
```
double values[9];
```

`math_engine_mat4_f64_t`

Row-major 4x4 double matrix 값이다. Index는 row * 4 + column 이다.

typedef struct math_engine_mat4_f64 {
    double values[16]; /**< Row-major 4x4 원소 배열. 원소 =(row, column)=은 =values[row * 4 + column]=이다. */
} math_engine_mat4_f64_t;

math_engine_mat4_f64_t.values
Row-major 4x4 원소 배열. 원소 (row, column)=은 =values[row * 4 + column] 이다.
```
double values[16];
```

`math_engine_result_info_t`

계산 결과의 상태, 품질과 실행 통계를 반환하는 caller-owned POD다.

status 는 math_engine_status_t 의 명시 값이며 ABI 폭을 고정하기 위해 int32_t 로 저장한다. 성공한 producer는 struct_size, status, 정확히 하나의 primary flags, 통계와 오차를 채우고 reserved 를 0으로 둔다. 실패 시 output 보존이 기본이다.

typedef struct math_engine_result_info {
    uint32_t struct_size; /**< Producer가 기록한 이 ABI 구조체의 byte 크기다. */
    int32_t status; /**< 연산의 =math_engine_status_t= 값. ABI 폭을 위해 signed 32-bit로 저장한다. */
    uint32_t flags; /**< 정확히 하나의 primary 결과 bit와 선택적인 orthogonal quality bit의 조합이다. */
    uint32_t reserved; /**< 향후 ABI 확장용이다. Producer는 0을 기록하고 consumer는 무시한다. */
    uint64_t iterations; /**< 알고리즘이 수행한 반복 횟수. 반복하지 않는 API는 0이다. */
    uint64_t evaluations; /**< 목적함수·식·kernel 평가 횟수. 해당 통계가 없으면 0이다. */
    double absolute_error; /**< 결과 단위로 표현한 절대 오차 또는 보수적 오차 추정치다. 미제공이면 API가 정한 값이다. */
    double relative_error; /**< 무차원 상대 오차 또는 보수적 오차 추정치다. 미제공이면 API가 정한 값이다. */
} math_engine_result_info_t;

math_engine_result_info_t.struct_size
Producer가 기록한 이 ABI 구조체의 byte 크기다.
```
uint32_t struct_size;
```
math_engine_result_info_t.status
연산의 math_engine_status_t 값. ABI 폭을 위해 signed 32-bit로 저장한다.
```
int32_t status;
```
math_engine_result_info_t.flags
정확히 하나의 primary 결과 bit와 선택적인 orthogonal quality bit의 조합이다.
```
uint32_t flags;
```
math_engine_result_info_t.reserved
향후 ABI 확장용이다. Producer는 0을 기록하고 consumer는 무시한다.
```
uint32_t reserved;
```
math_engine_result_info_t.iterations
알고리즘이 수행한 반복 횟수. 반복하지 않는 API는 0이다.
```
uint64_t iterations;
```
math_engine_result_info_t.evaluations
목적함수·식·kernel 평가 횟수. 해당 통계가 없으면 0이다.
```
uint64_t evaluations;
```
math_engine_result_info_t.absolute_error
결과 단위로 표현한 절대 오차 또는 보수적 오차 추정치다. 미제공이면 API가 정한 값이다.
```
double absolute_error;
```
math_engine_result_info_t.relative_error
무차원 상대 오차 또는 보수적 오차 추정치다. 미제공이면 API가 정한 값이다.
```
double relative_error;
```

Macro와 constant

`MATH_ENGINE_RESULT_FLAG_EMPTY`

유효한 입력 집합이나 결과 collection이 비어 있음을 나타내는 정상 primary 결과 bit다.

#define MATH_ENGINE_RESULT_FLAG_EMPTY UINT32_C(0x00000004)

`MATH_ENGINE_RESULT_FLAG_MISS`

질의가 유효하게 완료됐지만 교차·충돌·해 등이 없음을 나타내는 정상 primary 결과 bit다.

#define MATH_ENGINE_RESULT_FLAG_MISS UINT32_C(0x00000002)

`MATH_ENGINE_RESULT_FLAG_PARTIAL`

해당 API가 명시적으로 허용한 일부 output만 commit되었음을 나타내는 primary 결과 bit다.

#define MATH_ENGINE_RESULT_FLAG_PARTIAL UINT32_C(0x00000008)

`MATH_ENGINE_RESULT_FLAG_PRIMARY_MASK`

VALUE|MISS|EMPTY|PARTIAL primary bit를 추출하는 mask다.

#define MATH_ENGINE_RESULT_FLAG_PRIMARY_MASK UINT32_C(0x0000000f)

`MATH_ENGINE_RESULT_FLAG_UNCERTAIN`

Primary 결과에 orthogonal한 usable-but-uncertain quality 표시다.

#define MATH_ENGINE_RESULT_FLAG_UNCERTAIN UINT32_C(0x00010000)

`MATH_ENGINE_RESULT_FLAG_VALUE`

연산이 요청한 값을 생성했음을 나타내는 정상 primary 결과 bit다.

#define MATH_ENGINE_RESULT_FLAG_VALUE UINT32_C(0x00000001)

Math Engine Reference: Types

문서 탐색

개요

관련 public header

공개 API

Header 사용 시작

Type과 callback

math_engine_vec2_f64_t

math_engine_vec3_f64_t

math_engine_vec4_f64_t

math_engine_quat_f64_t

math_engine_mat2_f64_t

math_engine_mat3_f64_t

math_engine_mat4_f64_t

math_engine_result_info_t