Math Engine Reference: Transform

Translation과 unit quaternion 회전을 보관하는 caller-owned rigid transform이다.

typedef struct math_engine_rigid_transform_f64 {
    math_engine_vec3_f64_t translation; /**< 회전 뒤 point에 더하는 translation이다. Vector에는 더하지 않는다. */
    math_engine_quat_f64_t rotation; /**< =context= tolerance 안에서 unit length여야 하는 회전 quaternion이다. */
} math_engine_rigid_transform_f64_t;

Matrix buffer가 row-major임을 고정하는 storage convention이다.

typedef enum math_engine_matrix_storage {
    MATH_ENGINE_MATRIX_STORAGE_INVALID = 0, /**< 초기화되지 않았거나 지원하지 않는 matrix storage sentinel이다. */
    MATH_ENGINE_MATRIX_STORAGE_ROW_MAJOR = 1 /**< 원소 index가 =row * column_count + column=인 row-major storage다. */
} math_engine_matrix_storage_t;

Vector를 matrix 오른쪽의 column으로 해석하는 convention이다.

typedef enum math_engine_vector_side {
    MATH_ENGINE_VECTOR_SIDE_INVALID = 0, /**< 초기화되지 않았거나 지원하지 않는 vector-side sentinel이다. */
    MATH_ENGINE_VECTOR_SIDE_COLUMN = 1 /**< Transform이 matrix 오른쪽의 column vector에 왼쪽에서 곱해진다. */
} math_engine_vector_side_t;

Coordinate frame의 left/right handedness 선택이다.

typedef enum math_engine_handedness {
    MATH_ENGINE_HANDEDNESS_INVALID = 0, /**< 초기화되지 않았거나 지원하지 않는 coordinate handedness sentinel이다. */
    MATH_ENGINE_HANDEDNESS_LEFT = 1, /**< Left-handed coordinate convention을 선택한다. */
    MATH_ENGINE_HANDEDNESS_RIGHT = 2 /**< Right-handed coordinate convention을 선택한다. */
} math_engine_handedness_t;

ABI에서 고정한 storage·vector·composition 의미를 runtime에도 노출한다.

typedef struct math_engine_transform_convention {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_transform_convention_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_TRANSFORM_CONVENTION_VERSION_1=인 구조체 ABI version이다. */
    uint32_t matrix_storage; /**< =math_engine_matrix_storage_t= 값이며 현재는 =ROW_MAJOR=다. */
    uint32_t vector_side; /**< =math_engine_vector_side_t= 값이며 현재는 =COLUMN=이다. */
    uint32_t default_handedness; /**< Handedness를 받지 않는 API에 적용되는 =math_engine_handedness_t= 기본값이다. */
    uint32_t outer_after_inner; /**< 1이면 compose(outer, inner)가 =outer(inner(point))= 순서임을 뜻한다. */
    uint64_t convention_fingerprint; /**< Storage·vector·handedness·합성 규약을 식별하는 안정된 64-bit fingerprint다. */
    uint64_t reserved[2]; /**< 향후 ABI 확장용 두 slot이다. Producer는 모두 0을 기록하고 consumer는 무시한다. */
} math_engine_transform_convention_t;

math_engine_transform_convention_t 의 최초 안정 ABI version이다.

#define MATH_ENGINE_TRANSFORM_CONVENTION_VERSION_1 UINT32_C(1)

고정된 storage, vector side, handedness 및 합성 순서를 조회한다.

• 매개변수 out_convention: caller가 size/version을 채운 versioned storage.
• 반환: size/version 오류를 포함한 status. 실패하면 output을 보존한다.
• Math Engine ownership: out_convention=caller
• Math Engine nullable: out_convention=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_transform_convention_get(
    math_engine_transform_convention_t* out_convention);

Caller storage를 identity transform으로 초기화한다.

• 매개변수 out_transform: 초기화할 caller-owned storage. NULL이면 오류다.
• 반환: 성공 또는 음수 상태 code.
• Math Engine ownership: out_transform=caller
• Math Engine nullable: out_transform=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_rigid_transform_init_identity_f64(
    math_engine_rigid_transform_f64_t* out_transform);

Transform의 finite translation과 unit quaternion 계약을 검증한다.

• 매개변수 transform: 검증할 borrowed transform.
• 매개변수 context: tolerance를 제공하는 borrowed context.
• 반환: 유효하면 성공, 아니면 음수 상태 code.
• Math Engine ownership: transform=borrowed context=borrowed
• Math Engine nullable: transform=false context=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_rigid_transform_validate_f64(
    const math_engine_rigid_transform_f64_t* transform,
    const math_engine_context_t* context);

Point에 rotation과 translation을 적용한다.

• 매개변수 transform: 적용할 borrowed transform.
• 매개변수 point: 입력 point.
• 매개변수 context: tolerance를 제공하는 borrowed context.
• 매개변수 out_point: 성공 시 결과를 받는 caller-owned storage.
• 반환: 성공 또는 음수 상태 code. 실패 시 output은 변경하지 않는다.
• Math Engine ownership: transform=borrowed point=borrowed context=borrowed out_point=caller
• Math Engine nullable: transform=false point=false context=false out_point=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_rigid_transform_apply_point_f64(
    const math_engine_rigid_transform_f64_t* transform,
    const math_engine_vec3_f64_t* point,
    const math_engine_context_t* context,
    math_engine_vec3_f64_t* out_point);

Direction vector에 rotation만 적용한다.

• 매개변수 transform: 적용할 borrowed transform.
• 매개변수 vector: 입력 direction vector.
• 매개변수 context: tolerance를 제공하는 borrowed context.
• 매개변수 out_vector: 성공 시 결과를 받는 caller-owned storage.
• 반환: 성공 또는 음수 상태 code. 실패 시 output은 변경하지 않는다.
• Math Engine ownership: transform=borrowed vector=borrowed context=borrowed out_vector=caller
• Math Engine nullable: transform=false vector=false context=false out_vector=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_rigid_transform_apply_vector_f64(
    const math_engine_rigid_transform_f64_t* transform,
    const math_engine_vec3_f64_t* vector,
    const math_engine_context_t* context,
    math_engine_vec3_f64_t* out_vector);

rigid pose를 row-major homogeneous 4x4 column-vector matrix로 내보낸다.

• 매개변수 transform: borrowed rigid transform.
• 매개변수 context: borrowed tolerance context.
• 매개변수 out_matrix: caller-owned 4x4 결과.
• 반환: 성공 또는 오류 status. 실패하면 output을 보존한다.
• Math Engine ownership: transform=borrowed context=borrowed out_matrix=caller
• Math Engine nullable: transform=false context=false out_matrix=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_rigid_transform_to_matrix4_f64(
    const math_engine_rigid_transform_f64_t* transform,
    const math_engine_context_t* context,
    math_engine_mat4_f64_t* out_matrix);

Rigid transform의 역변환을 계산한다.

• 매개변수 transform: 입력 borrowed transform.
• 매개변수 context: tolerance를 제공하는 borrowed context.
• 매개변수 out_inverse: 성공 시 inverse를 받는 caller-owned storage.
• 반환: 성공 또는 음수 상태 code. 실패 시 output은 변경하지 않는다.
• Math Engine ownership: transform=borrowed context=borrowed out_inverse=caller
• Math Engine nullable: transform=false context=false out_inverse=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_rigid_transform_inverse_f64(
    const math_engine_rigid_transform_f64_t* transform,
    const math_engine_context_t* context,
    math_engine_rigid_transform_f64_t* out_inverse);

outer(inner(point)) 순서로 두 rigid transform을 합성한다.

• 매개변수 outer: 나중에 적용할 borrowed transform.
• 매개변수 inner: 먼저 적용할 borrowed transform.
• 매개변수 context: tolerance를 제공하는 borrowed context.
• 매개변수 out_composed: 성공 시 합성 결과를 받는 caller-owned storage.
• 반환: 성공 또는 음수 상태 code. 실패 시 output은 변경하지 않는다.
• Math Engine ownership: outer=borrowed inner=borrowed context=borrowed out_composed=caller
• Math Engine nullable: outer=false inner=false context=false out_composed=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_rigid_transform_compose_f64(
    const math_engine_rigid_transform_f64_t* outer,
    const math_engine_rigid_transform_f64_t* inner,
    const math_engine_context_t* context,
    math_engine_rigid_transform_f64_t* out_composed);

local +Z가 target을 향하는 left-handed pose를 만든다.

• 매개변수 eye: borrowed pose translation.
• 매개변수 target: borrowed 시선 target.
• 매개변수 up: borrowed up reference.
• 매개변수 context: borrowed tolerance context.
• 매개변수 out_transform: caller-owned 결과.
• 반환: eye/target 일치 또는 up 평행이면 DEGENERATE 이며 output을 보존한다.
• Math Engine ownership: eye=borrowed target=borrowed up=borrowed context=borrowed out_transform=caller
• Math Engine nullable: eye=false target=false up=false context=false out_transform=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_rigid_transform_look_at_lh_f64(
    const math_engine_vec3_f64_t* eye,
    const math_engine_vec3_f64_t* target,
    const math_engine_vec3_f64_t* up,
    const math_engine_context_t* context,
    math_engine_rigid_transform_f64_t* out_transform);

local -Z가 target을 향하는 right-handed pose를 만든다.

• 매개변수 eye: borrowed pose translation.
• 매개변수 target: borrowed 시선 target.
• 매개변수 up: borrowed up reference.
• 매개변수 context: borrowed tolerance context.
• 매개변수 out_transform: caller-owned 결과.
• 반환: eye/target 일치 또는 up 평행이면 DEGENERATE 이며 output을 보존한다.
• Math Engine ownership: eye=borrowed target=borrowed up=borrowed context=borrowed out_transform=caller
• Math Engine nullable: eye=false target=false up=false context=false out_transform=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_rigid_transform_look_at_rh_f64(
    const math_engine_vec3_f64_t* eye,
    const math_engine_vec3_f64_t* target,
    const math_engine_vec3_f64_t* up,
    const math_engine_context_t* context,
    math_engine_rigid_transform_f64_t* out_transform);

두 direction 사이의 shortest rotation을 zero-translation pose로 만든다.

• 매개변수 from_direction: borrowed 시작 direction.
• 매개변수 to_direction: borrowed 목표 direction.
• 매개변수 context: borrowed tolerance context.
• 매개변수 out_transform: caller-owned 결과.
• 반환: 영벡터면 DEGENERATE 이며 실패하면 output을 보존한다.
• Math Engine ownership: from_direction=borrowed to_direction=borrowed context=borrowed out_transform=caller
• Math Engine nullable: from_direction=false to_direction=false context=false out_transform=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_rigid_transform_align_f64(
    const math_engine_vec3_f64_t* from_direction,
    const math_engine_vec3_f64_t* to_direction,
    const math_engine_context_t* context,
    math_engine_rigid_transform_f64_t* out_transform);

translation lerp와 shortest-path quaternion slerp를 수행한다.

• 매개변수 first: borrowed 시작 pose.
• 매개변수 second: borrowed 끝 pose.
• 매개변수 parameter: 닫힌 구간 [0,1]의 보간 인자.
• 매개변수 context: borrowed tolerance context.
• 매개변수 out_transform: caller-owned 결과. 입력과 alias할 수 있다.
• 반환: endpoint는 bit-exact하며 실패하면 output을 보존한다.
• Math Engine ownership: first=borrowed second=borrowed context=borrowed out_transform=caller
• Math Engine nullable: first=false second=false context=false out_transform=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_rigid_transform_interpolate_f64(
    const math_engine_rigid_transform_f64_t* first,
    const math_engine_rigid_transform_f64_t* second,
    double parameter,
    const math_engine_context_t* context,
    math_engine_rigid_transform_f64_t* out_transform);