Math Engine Reference: Affine

Row-major 선형 부분과 translation으로 구성된 caller-owned affine 변환이다.

typedef struct math_engine_affine3_f64 {
    math_engine_mat3_f64_t linear; /**< Point와 vector에 먼저 적용하는 row-major 3x3 선형 부분이다. */
    math_engine_vec3_f64_t translation; /**< 선형 변환 뒤 point에 더하는 translation이다. Vector에는 더하지 않는다. */
} math_engine_affine3_f64_t;

t + R(S p) 의미를 가진 제한 표현이다. 합성 결과 shear는 이 type에 들어가지 않는다.

typedef struct math_engine_trs3_f64 {
    math_engine_vec3_f64_t translation; /**< 회전·scale 뒤 point에 더하는 translation이다. */
    math_engine_quat_f64_t rotation; /**< =context= tolerance 안에서 unit length여야 하는 회전 quaternion이다. */
    math_engine_vec3_f64_t scale; /**< 회전 전에 적용하는 signed 축별 scale이며 각 성분의 절댓값은 tolerance보다 커야 한다. 음수 성분은 reflection을 나타낸다. */
} math_engine_trs3_f64_t;

Caller storage를 identity affine 변환으로 초기화한다.

• 매개변수 out_transform: 결과를 받을 caller-owned storage.
• 반환: 성공 또는 음수 상태 code. 실패 시 output은 변경하지 않는다.
• 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_affine3_init_identity_f64(
    math_engine_affine3_f64_t* out_transform);

Translation, unit quaternion rotation, 축별 scale로 affine 변환을 만든다.

• 매개변수 translation: 입력 translation.
• 매개변수 rotation: 입력 unit quaternion.
• 매개변수 scale: 입력 축별 scale. 각 성분의 절댓값은 absolute tolerance보다 커야 한다.
• 매개변수 context: tolerance를 제공하는 borrowed context.
• 매개변수 out_transform: 결과를 받을 caller-owned storage.
• 반환: 성공 또는 음수 상태 code. 실패 시 output은 변경하지 않는다.
• Math Engine ownership: translation=borrowed rotation=borrowed scale=borrowed context=borrowed out_transform=caller
• Math Engine nullable: translation=false rotation=false scale=false context=false out_transform=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_affine3_from_trs_f64(
    const math_engine_vec3_f64_t* translation,
    const math_engine_quat_f64_t* rotation,
    const math_engine_vec3_f64_t* scale,
    const math_engine_context_t* context,
    math_engine_affine3_f64_t* out_transform);

Affine 변환의 finite 값과 가역성을 검증한다.

• 매개변수 transform: 검증할 borrowed 변환.
• 매개변수 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_affine3_validate_f64(
    const math_engine_affine3_f64_t* transform,
    const math_engine_context_t* context);

Point에 선형 변환과 translation을 적용한다.

• 매개변수 transform: 적용할 borrowed 변환.
• 매개변수 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_affine3_apply_point_f64(
    const math_engine_affine3_f64_t* transform,
    const math_engine_vec3_f64_t* point,
    const math_engine_context_t* context,
    math_engine_vec3_f64_t* out_point);

translation 없이 linear part를 vector에 적용한다.

• 매개변수 transform: borrowed affine transform.
• 매개변수 vector: borrowed 입력 vector.
• 매개변수 context: borrowed tolerance context.
• 매개변수 out_vector: caller-owned 결과. vector 와 같은 주소여도 된다.
• 반환: 성공 또는 오류 status. 실패하면 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_affine3_apply_vector_f64(
    const math_engine_affine3_f64_t* transform,
    const math_engine_vec3_f64_t* vector,
    const math_engine_context_t* context,
    math_engine_vec3_f64_t* out_vector);

linear part를 적용한 뒤 unit direction으로 정규화한다.

• 매개변수 transform: borrowed affine transform.
• 매개변수 direction: borrowed 입력 direction.
• 매개변수 context: borrowed tolerance context.
• 매개변수 out_direction: caller-owned 결과. direction 과 alias할 수 있다.
• 반환: 영벡터면 DEGENERATE 이며 실패하면 output을 보존한다.
• Math Engine ownership: transform=borrowed direction=borrowed context=borrowed out_direction=caller
• Math Engine nullable: transform=false direction=false context=false out_direction=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_affine3_apply_direction_f64(
    const math_engine_affine3_f64_t* transform,
    const math_engine_vec3_f64_t* direction,
    const math_engine_context_t* context,
    math_engine_vec3_f64_t* out_direction);

inverse-transpose를 적용하고 정규화해 surface normal을 변환한다.

• 매개변수 transform: borrowed nonsingular affine transform.
• 매개변수 normal: borrowed 입력 normal.
• 매개변수 context: borrowed tolerance context.
• 매개변수 out_normal: caller-owned 결과. normal 과 alias할 수 있다.
• 반환: singular/영벡터면 DEGENERATE 이며 실패하면 output을 보존한다.
• Math Engine ownership: transform=borrowed normal=borrowed context=borrowed out_normal=caller
• Math Engine nullable: transform=false normal=false context=false out_normal=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_affine3_apply_normal_f64(
    const math_engine_affine3_f64_t* transform,
    const math_engine_vec3_f64_t* normal,
    const math_engine_context_t* context,
    math_engine_vec3_f64_t* out_normal);

affine을 row-major homogeneous 4x4 column-vector matrix로 내보낸다.

• 매개변수 transform: borrowed affine 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_affine3_to_matrix4_f64(
    const math_engine_affine3_f64_t* transform,
    const math_engine_context_t* context,
    math_engine_mat4_f64_t* out_matrix);

Affine 변환의 역변환을 계산한다.

• 매개변수 transform: 입력 borrowed 변환.
• 매개변수 context: tolerance를 제공하는 borrowed context.
• 매개변수 out_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_affine3_inverse_f64(
    const math_engine_affine3_f64_t* transform,
    const math_engine_context_t* context,
    math_engine_affine3_f64_t* out_inverse);

outer(inner(point)) 순서로 두 affine 변환을 합성한다.

• 매개변수 outer: 나중에 적용할 borrowed 변환.
• 매개변수 inner: 먼저 적용할 borrowed 변환.
• 매개변수 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_affine3_compose_f64(
    const math_engine_affine3_f64_t* outer,
    const math_engine_affine3_f64_t* inner,
    const math_engine_context_t* context,
    math_engine_affine3_f64_t* out_composed);

translation + pivot + R(S(point-pivot)) affine을 만든다.

• 매개변수 translation: borrowed translation.
• 매개변수 rotation: borrowed unit quaternion.
• 매개변수 scale: borrowed nonzero axis scale.
• 매개변수 pivot: borrowed 고정 pivot.
• 매개변수 context: borrowed tolerance context.
• 매개변수 out_transform: caller-owned 결과.
• 반환: degenerate/non-finite 입력을 거부하며 실패하면 output을 보존한다.
• Math Engine ownership: translation=borrowed rotation=borrowed scale=borrowed pivot=borrowed context=borrowed out_transform=caller
• Math Engine nullable: translation=false rotation=false scale=false pivot=false context=false out_transform=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_affine3_from_trs_pivot_f64(
    const math_engine_vec3_f64_t* translation,
    const math_engine_quat_f64_t* rotation,
    const math_engine_vec3_f64_t* scale,
    const math_engine_vec3_f64_t* pivot,
    const math_engine_context_t* context,
    math_engine_affine3_f64_t* out_transform);

plane point와 normal로 reflection affine을 만든다.

• 매개변수 plane_point: borrowed plane 위의 점.
• 매개변수 plane_normal: borrowed normal. 함수가 정규화한다.
• 매개변수 context: borrowed tolerance context.
• 매개변수 out_transform: caller-owned 결과.
• 반환: 영 normal이면 DEGENERATE 이며 실패하면 output을 보존한다.
• Math Engine ownership: plane_point=borrowed plane_normal=borrowed context=borrowed out_transform=caller
• Math Engine nullable: plane_point=false plane_normal=false context=false out_transform=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_affine3_reflection_f64(
    const math_engine_vec3_f64_t* plane_point,
    const math_engine_vec3_f64_t* plane_normal,
    const math_engine_context_t* context,
    math_engine_affine3_f64_t* out_transform);

locale 및 process stream 상태와 무관한 shortest binary64 text를 기록한다.

• 매개변수 transform: borrowed affine transform.
• 매개변수 context: borrowed validation context.
• 매개변수 buffer: caller-owned byte buffer. 크기 질의에서는 NULL일 수 있다.
• 매개변수 capacity: NUL을 포함한 buffer byte 용량.
• 매개변수 out_size: caller-owned 필요/기록 byte 수. 끝 NUL은 포함하지 않는다.
• 반환: buffer가 작으면 INSUFFICIENT_BUFFER 이며 buffer는 보존하고 out_size 만 기록한다.
• Math Engine ownership: transform=borrowed context=borrowed buffer=caller out_size=caller
• Math Engine nullable: transform=false context=false buffer=capacity_zero_only out_size=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_affine3_format_f64(
    const math_engine_affine3_f64_t* transform,
    const math_engine_context_t* context,
    char* buffer,
    size_t capacity,
    size_t* out_size);

caller-owned TRS를 identity로 초기화한다.

• 매개변수 out_transform: caller-owned 결과.
• 반환: 성공 또는 INVALID_ARGUMENT. 실패하면 output을 보존한다.
• 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_trs3_init_identity_f64(
    math_engine_trs3_f64_t* out_transform);

translation, unit quaternion, nonzero scale 계약을 검사한다.

• 매개변수 transform: borrowed TRS.
• 매개변수 context: borrowed tolerance context.
• 반환: 성공 또는 degenerate/non-finite 오류 status.
• 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_trs3_validate_f64(
    const math_engine_trs3_f64_t* transform,
    const math_engine_context_t* context);

t + R(S point) 를 적용한다.

• 매개변수 transform: borrowed TRS.
• 매개변수 point: borrowed 입력 point.
• 매개변수 context: borrowed tolerance context.
• 매개변수 out_point: caller-owned 결과. point 와 alias할 수 있다.
• 반환: 성공 또는 오류 status. 실패하면 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_trs3_apply_point_f64(
    const math_engine_trs3_f64_t* transform,
    const math_engine_vec3_f64_t* point,
    const math_engine_context_t* context,
    math_engine_vec3_f64_t* out_point);

TRS의 정확한 nonsingular affine 표현을 만든다.

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

MATH_ENGINE_API math_engine_status_t math_engine_trs3_to_affine_f64(
    const math_engine_trs3_f64_t* transform,
    const math_engine_context_t* context,
    math_engine_affine3_f64_t* out_affine);

직교 scale basis인 affine만 TRS로 내린다.

• 매개변수 affine: borrowed affine transform.
• 매개변수 context: borrowed tolerance context.
• 매개변수 out_transform: caller-owned 결과.
• 반환: shear면 NOT_REPRESENTABLE 이며 실패하면 output을 보존한다.
• Math Engine ownership: affine=borrowed context=borrowed out_transform=caller
• Math Engine nullable: affine=false context=false out_transform=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_trs3_from_affine_checked_f64(
    const math_engine_affine3_f64_t* affine,
    const math_engine_context_t* context,
    math_engine_trs3_f64_t* out_transform);

outer(inner(point)) 의 정확한 affine 합성을 만든다.

• 매개변수 outer: borrowed 나중 TRS.
• 매개변수 inner: borrowed 먼저 TRS.
• 매개변수 context: borrowed tolerance context.
• 매개변수 out_composed: caller-owned affine 결과.
• 반환: 성공 또는 오류 status. 실패하면 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_trs3_compose_affine_f64(
    const math_engine_trs3_f64_t* outer,
    const math_engine_trs3_f64_t* inner,
    const math_engine_context_t* context,
    math_engine_affine3_f64_t* out_composed);

outer(inner(point)) 가 shear 없이 표현될 때만 TRS로 합성한다.

• 매개변수 outer: borrowed 나중 TRS.
• 매개변수 inner: borrowed 먼저 TRS.
• 매개변수 context: borrowed tolerance context.
• 매개변수 out_composed: caller-owned TRS 결과. 입력과 alias할 수 있다.
• 반환: shear면 NOT_REPRESENTABLE 이며 실패하면 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_trs3_compose_checked_f64(
    const math_engine_trs3_f64_t* outer,
    const math_engine_trs3_f64_t* inner,
    const math_engine_context_t* context,
    math_engine_trs3_f64_t* out_composed);