Math Engine Reference: Collision

문서 탐색

개요

World-state-free continuous collision과 caller-owned heightfield query를 제공한다.

모든 geometry는 하나의 caller-selected 좌표계와 길이 단위를 공유하고 시간 suffix가 붙은 값은 초를 사용한다. 함수는 world object를 생성하거나 input view를 보관하지 않는다.

실행 원본: include/math_engine/math_engine_collision.h
분류: 물리·운동·제어

공개 API

Header 사용 시작

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

#include <math_engine/math_engine_collision.h>

Type과 callback

`math_engine_collision_phase_t`

@brief Collision hit의 시간 구간상 phase 분류다.

typedef enum math_engine_collision_phase {
    MATH_ENGINE_COLLISION_PHASE_INVALID = 0, /**< Hit이 없거나 result가 아직 초기화 상태인 sentinel이다. */
    MATH_ENGINE_COLLISION_PHASE_INITIAL_OVERLAP = 1, /**< 탐색 시작 시간에 두 대상의 distance가 tolerance 안이다. */
    MATH_ENGINE_COLLISION_PHASE_ENTER = 2, /**< 분리 상태에서 contact 영역으로 처음 진입하는 hit다. */
    MATH_ENGINE_COLLISION_PHASE_TANGENT = 3, /**< 부호를 바꾸지 않고 한 시점에서 접하는 tangent hit다. */
    MATH_ENGINE_COLLISION_PHASE_EXIT = 4 /**< Overlap/contact 상태에서 분리 상태로 나가는 hit다. */
} math_engine_collision_phase_t;

math_engine_collision_phase_t.MATH_ENGINE_COLLISION_PHASE_INVALID
Hit이 없거나 result가 아직 초기화 상태인 sentinel이다.
```
MATH_ENGINE_COLLISION_PHASE_INVALID = 0,
```
math_engine_collision_phase_t.MATH_ENGINE_COLLISION_PHASE_INITIAL_OVERLAP
탐색 시작 시간에 두 대상의 distance가 tolerance 안이다.
```
MATH_ENGINE_COLLISION_PHASE_INITIAL_OVERLAP = 1,
```
math_engine_collision_phase_t.MATH_ENGINE_COLLISION_PHASE_ENTER
분리 상태에서 contact 영역으로 처음 진입하는 hit다.
```
MATH_ENGINE_COLLISION_PHASE_ENTER = 2,
```
math_engine_collision_phase_t.MATH_ENGINE_COLLISION_PHASE_TANGENT
부호를 바꾸지 않고 한 시점에서 접하는 tangent hit다.
```
MATH_ENGINE_COLLISION_PHASE_TANGENT = 3,
```
math_engine_collision_phase_t.MATH_ENGINE_COLLISION_PHASE_EXIT
Overlap/contact 상태에서 분리 상태로 나가는 hit다.
```
MATH_ENGINE_COLLISION_PHASE_EXIT = 4,
```

`math_engine_collision_quality_t`

@brief Collision time과 contact 결과의 수치 해석 품질 분류다.

typedef enum math_engine_collision_quality {
    MATH_ENGINE_COLLISION_QUALITY_INVALID = 0, /**< Hit 품질이 없거나 result가 초기화 상태인 sentinel이다. */
    MATH_ENGINE_COLLISION_QUALITY_EXACT_ANALYTIC = 1, /**< Closed-form predicate와 root로 구한 analytic hit다. */
    MATH_ENGINE_COLLISION_QUALITY_BRACKETED_REFINED = 2, /**< Sign-change bracket을 tolerance까지 반복 정제한 hit다. */
    MATH_ENGINE_COLLISION_QUALITY_APPROXIMATE_BOUNDED = 3 /**< Sampling과 명시 error bound로 제한한 근사 hit다. */
} math_engine_collision_quality_t;

math_engine_collision_quality_t.MATH_ENGINE_COLLISION_QUALITY_INVALID
Hit 품질이 없거나 result가 초기화 상태인 sentinel이다.
```
MATH_ENGINE_COLLISION_QUALITY_INVALID = 0,
```
math_engine_collision_quality_t.MATH_ENGINE_COLLISION_QUALITY_EXACT_ANALYTIC
Closed-form predicate와 root로 구한 analytic hit다.
```
MATH_ENGINE_COLLISION_QUALITY_EXACT_ANALYTIC = 1,
```
math_engine_collision_quality_t.MATH_ENGINE_COLLISION_QUALITY_BRACKETED_REFINED
Sign-change bracket을 tolerance까지 반복 정제한 hit다.
```
MATH_ENGINE_COLLISION_QUALITY_BRACKETED_REFINED = 2,
```
math_engine_collision_quality_t.MATH_ENGINE_COLLISION_QUALITY_APPROXIMATE_BOUNDED
Sampling과 명시 error bound로 제한한 근사 hit다.
```
MATH_ENGINE_COLLISION_QUALITY_APPROXIMATE_BOUNDED = 3,
```

`math_engine_triangle_motion_f64_t`

@brief t=0 triangle pose와 일정 선형·각속도의 caller-owned 값이다.

typedef struct math_engine_triangle_motion_f64 {
    math_engine_rigid_transform_f64_t initial_pose; /**< Local triangle을 world로 옮기는 =t=0= rigid pose다. */
    math_engine_vec3_f64_t linear_velocity; /**< World frame에서 pose translation의 초당 길이 변화량이다. */
    math_engine_vec3_f64_t angular_velocity_rad_per_sec; /**< World frame 회전축 방향과 rad/s 크기를 함께 담는 각속도 벡터다. */
} math_engine_triangle_motion_f64_t;

math_engine_triangle_motion_f64_t.initial_pose
Local triangle을 world로 옮기는 t=0 rigid pose다.
```
math_engine_rigid_transform_f64_t initial_pose;
```
math_engine_triangle_motion_f64_t.linear_velocity
World frame에서 pose translation의 초당 길이 변화량이다.
```
math_engine_vec3_f64_t linear_velocity;
```
math_engine_triangle_motion_f64_t.angular_velocity_rad_per_sec
World frame 회전축 방향과 rad/s 크기를 함께 담는 각속도 벡터다.
```
math_engine_vec3_f64_t angular_velocity_rad_per_sec;
```

`math_engine_collision_options_f64_t`

@brief Temporal bracket sample 수와 시간·거리 tolerance option이다.

typedef struct math_engine_collision_options_f64 {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_collision_options_f64_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_COLLISION_OPTIONS_VERSION_1=인 option ABI version이다. */
    uint32_t temporal_samples; /**< 포함 시간 구간에서 bracket 후보를 찾는 sample 수다. 2..1048576 범위다. */
    uint32_t reserved32; /**< 향후 ABI 확장용이다. Caller는 0으로 설정해야 하며 nonzero option은 INVALID_ARGUMENT로 거부된다. */
    double time_tolerance; /**< TOI bracket과 root refinement를 멈추는 finite nonnegative 시간 tolerance(s)다. */
    double distance_tolerance; /**< Contact/inside predicate에 사용하는 finite nonnegative 길이 tolerance다. */
    uint64_t reserved[2]; /**< 향후 ABI 확장용 두 slot이다. Caller는 모두 0으로 설정해야 하며 nonzero option은 INVALID_ARGUMENT로 거부된다. */
} math_engine_collision_options_f64_t;

math_engine_collision_options_f64_t.struct_size
Caller가 sizeof(math_engine_collision_options_f64_t) 로 설정하는 byte 크기다.
```
uint32_t struct_size;
```
math_engine_collision_options_f64_t.struct_version
MATH_ENGINE_COLLISION_OPTIONS_VERSION_1 인 option ABI version이다.
```
uint32_t struct_version;
```
math_engine_collision_options_f64_t.temporal_samples
포함 시간 구간에서 bracket 후보를 찾는 sample 수다. 2..1048576 범위다.
```
uint32_t temporal_samples;
```
math_engine_collision_options_f64_t.reserved32
향후 ABI 확장용이다. Caller는 0으로 설정해야 하며 nonzero option은 INVALID_ARGUMENT로 거부된다.
```
uint32_t reserved32;
```
math_engine_collision_options_f64_t.time_tolerance
TOI bracket과 root refinement를 멈추는 finite nonnegative 시간 tolerance(s)다.
```
double time_tolerance;
```
math_engine_collision_options_f64_t.distance_tolerance
Contact/inside predicate에 사용하는 finite nonnegative 길이 tolerance다.
```
double distance_tolerance;
```
math_engine_collision_options_f64_t.reserved
향후 ABI 확장용 두 slot이다. Caller는 모두 0으로 설정해야 하며 nonzero option은 INVALID_ARGUMENT로 거부된다.
```
uint64_t reserved[2];
```

`math_engine_collision_result_f64_t`

@brief TOI, bracket, contact point/normal과 오차 경계를 담는 결과다.

typedef struct math_engine_collision_result_f64 {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_collision_result_f64_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_COLLISION_RESULT_VERSION_1=인 result ABI version이다. */
    uint32_t flags; /**< =MATH_ENGINE_RESULT_FLAG_*= 중 VALUE 또는 MISS와 선택적인 quality bit 조합이다. */
    int32_t phase; /**< Hit의 =math_engine_collision_phase_t= 값이며 MISS에서는 INVALID다. */
    int32_t quality; /**< TOI 계산의 =math_engine_collision_quality_t= 값이며 MISS에서는 INVALID다. */
    int32_t predicate_certainty; /**< Contact predicate의 =math_engine_predicate_certainty_t= 판정이다. */
    uint32_t reserved32; /**< 향후 ABI 확장용이다. Producer는 0을 기록하고 consumer는 무시한다. */
    double time_sec; /**< Motion의 =t=0=을 기준으로 한 hit time(s)이며 요청한 closed search interval 안이다. MISS에서는 0이다. */
    double bracket_lower_sec; /**< Hit time을 포함하는 closed bracket의 하한(s)이다. */
    double bracket_upper_sec; /**< Hit time을 포함하는 closed bracket의 상한(s)이다. */
    double residual; /**< Contact predicate의 signed distance 또는 방정식 residual이며 길이 단위다. */
    double time_error_bound; /**< 보고한 =time_sec=의 보수적 절대 error bound(s)다. */
    double distance_error_bound; /**< 보고한 contact point/predicate의 보수적 길이 error bound다. */
    math_engine_vec3_f64_t point; /**< Hit 시점의 world-frame contact point다. */
    math_engine_vec3_f64_t normal; /**< Query별 contact convention의 world-frame unit normal이다. Point-sphere에서는 sphere center에서 point 방향이고 point-plane에서는 plane normal 방향이다. */
    double barycentric[3]; /**< Triangle query의 세 vertex weight다. Hit에서는 합이 tolerance 안에서 1이다. */
    uint64_t iterations; /**< Root/bracket refinement iteration 수다. Analytic query는 0이다. */
    uint64_t evaluations; /**< Distance/contact predicate 평가 횟수다. */
    uint64_t reserved[2]; /**< 향후 ABI 확장용 두 slot이다. Producer는 모두 0을 기록하고 consumer는 무시한다. */
} math_engine_collision_result_f64_t;

math_engine_collision_result_f64_t.struct_size
Caller가 sizeof(math_engine_collision_result_f64_t) 로 설정하는 byte 크기다.
```
uint32_t struct_size;
```
math_engine_collision_result_f64_t.struct_version
MATH_ENGINE_COLLISION_RESULT_VERSION_1 인 result ABI version이다.
```
uint32_t struct_version;
```
math_engine_collision_result_f64_t.flags
MATH_ENGINE_RESULT_FLAG_* 중 VALUE 또는 MISS와 선택적인 quality bit 조합이다.
```
uint32_t flags;
```
math_engine_collision_result_f64_t.phase
Hit의 math_engine_collision_phase_t 값이며 MISS에서는 INVALID다.
```
int32_t phase;
```
math_engine_collision_result_f64_t.quality
TOI 계산의 math_engine_collision_quality_t 값이며 MISS에서는 INVALID다.
```
int32_t quality;
```
math_engine_collision_result_f64_t.predicate_certainty
Contact predicate의 math_engine_predicate_certainty_t 판정이다.
```
int32_t predicate_certainty;
```
math_engine_collision_result_f64_t.reserved32
향후 ABI 확장용이다. Producer는 0을 기록하고 consumer는 무시한다.
```
uint32_t reserved32;
```
math_engine_collision_result_f64_t.time_sec
Motion의 =t=0=을 기준으로 한 hit time(s)이며 요청한 closed search interval 안이다. MISS에서는 0이다.
```
double time_sec;
```
math_engine_collision_result_f64_t.bracket_lower_sec
Hit time을 포함하는 closed bracket의 하한(s)이다.
```
double bracket_lower_sec;
```
math_engine_collision_result_f64_t.bracket_upper_sec
Hit time을 포함하는 closed bracket의 상한(s)이다.
```
double bracket_upper_sec;
```
math_engine_collision_result_f64_t.residual
Contact predicate의 signed distance 또는 방정식 residual이며 길이 단위다.
```
double residual;
```
math_engine_collision_result_f64_t.time_error_bound
보고한 time_sec 의 보수적 절대 error bound(s)다.
```
double time_error_bound;
```
math_engine_collision_result_f64_t.distance_error_bound
보고한 contact point/predicate의 보수적 길이 error bound다.
```
double distance_error_bound;
```
math_engine_collision_result_f64_t.point
Hit 시점의 world-frame contact point다.
```
math_engine_vec3_f64_t point;
```
math_engine_collision_result_f64_t.normal
Query별 contact convention의 world-frame unit normal이다. Point-sphere에서는 sphere center에서 point 방향이고 point-plane에서는 plane normal 방향이다.
```
math_engine_vec3_f64_t normal;
```
math_engine_collision_result_f64_t.barycentric
Triangle query의 세 vertex weight다. Hit에서는 합이 tolerance 안에서 1이다.
```
double barycentric[3];
```
math_engine_collision_result_f64_t.iterations
Root/bracket refinement iteration 수다. Analytic query는 0이다.
```
uint64_t iterations;
```
math_engine_collision_result_f64_t.evaluations
Distance/contact predicate 평가 횟수다.
```
uint64_t evaluations;
```
math_engine_collision_result_f64_t.reserved
향후 ABI 확장용 두 slot이다. Producer는 모두 0을 기록하고 consumer는 무시한다.
```
uint64_t reserved[2];
```

`math_engine_heightfield_view_f64_t`

@brief Borrowed row-major 높이 sample view다.

row_stride 는 double element 단위다. 높이와 origin/cell size는 동일한 길이 단위를 사용하며 query는 pointer를 보관하거나 해제하지 않는다.

typedef struct math_engine_heightfield_view_f64 {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_heightfield_view_f64_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_HEIGHTFIELD_VIEW_VERSION_1=인 view ABI version이다. */
    const double* heights; /**< Caller-owned row-major sample storage를 빌려 읽는 non-null pointer다. 최소 =(depth - 1) * row_stride + width= 원소가 호출 종료까지 readable이어야 하며 보관하지 않는다. */
    size_t width; /**< 각 row에서 의미 있는 height sample 수다. 2 이상이어야 한다. */
    size_t depth; /**< z 방향 row 수다. 2 이상이어야 한다. */
    size_t row_stride; /**< 연속 row 시작 사이의 =double= 원소 수다. =width= 이상이어야 한다. */
    math_engine_vec3_f64_t origin; /**< Grid index (0,0)의 world-frame x/z와 height 기준 y를 같은 길이 단위로 정한다. */
    double cell_size_x; /**< 인접 column 사이의 finite positive world x 간격이다. */
    double cell_size_z; /**< 인접 row 사이의 finite positive world z 간격이다. */
    uint64_t reserved[2]; /**< 향후 ABI 확장용 두 slot이다. Caller는 모두 0으로 설정해야 하며 nonzero view는 INVALID_ARGUMENT로 거부된다. */
} math_engine_heightfield_view_f64_t;

math_engine_heightfield_view_f64_t.struct_size
Caller가 sizeof(math_engine_heightfield_view_f64_t) 로 설정하는 byte 크기다.
```
uint32_t struct_size;
```
math_engine_heightfield_view_f64_t.struct_version
MATH_ENGINE_HEIGHTFIELD_VIEW_VERSION_1 인 view ABI version이다.
```
uint32_t struct_version;
```
math_engine_heightfield_view_f64_t.heights
Caller-owned row-major sample storage를 빌려 읽는 non-null pointer다. 최소 (depth - 1) * row_stride + width 원소가 호출 종료까지 readable이어야 하며 보관하지 않는다.
```
const double* heights;
```
math_engine_heightfield_view_f64_t.width
각 row에서 의미 있는 height sample 수다. 2 이상이어야 한다.
```
size_t width;
```
math_engine_heightfield_view_f64_t.depth
z 방향 row 수다. 2 이상이어야 한다.
```
size_t depth;
```
math_engine_heightfield_view_f64_t.row_stride
연속 row 시작 사이의 double 원소 수다. width 이상이어야 한다.
```
size_t row_stride;
```
math_engine_heightfield_view_f64_t.origin
Grid index (0,0)의 world-frame x/z와 height 기준 y를 같은 길이 단위로 정한다.
```
math_engine_vec3_f64_t origin;
```
math_engine_heightfield_view_f64_t.cell_size_x
인접 column 사이의 finite positive world x 간격이다.
```
double cell_size_x;
```
math_engine_heightfield_view_f64_t.cell_size_z
인접 row 사이의 finite positive world z 간격이다.
```
double cell_size_z;
```
math_engine_heightfield_view_f64_t.reserved
향후 ABI 확장용 두 slot이다. Caller는 모두 0으로 설정해야 하며 nonzero view는 INVALID_ARGUMENT로 거부된다.
```
uint64_t reserved[2];
```

`math_engine_ground_result_f64_t`

@brief Heightfield cell, triangle, surface point/normal과 barycentric 결과다.

typedef struct math_engine_ground_result_f64 {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_ground_result_f64_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_GROUND_RESULT_VERSION_1=인 result ABI version이다. */
    uint32_t flags; /**< =MATH_ENGINE_RESULT_FLAG_*= 중 VALUE 또는 MISS와 선택적인 quality bit 조합이다. */
    uint32_t cell_x; /**< Hit/sample을 포함하는 cell의 왼쪽 heightfield column index다. */
    uint32_t cell_z; /**< Hit/sample을 포함하는 cell의 앞쪽 heightfield row index다. */
    uint32_t triangle_index; /**< 고정 diagonal로 나눈 cell 내부 triangle index 0 또는 1이다. */
    uint32_t reserved32; /**< 향후 ABI 확장용이다. Producer는 0을 기록하고 consumer는 무시한다. */
    double height; /**< Query x/z에서 piecewise-linear surface의 world y 값이다. */
    double ray_parameter; /**< Raycast hit point를 =origin + parameter * direction=으로 재구성하는 parameter다. Sample query에서는 0이다. */
    math_engine_vec3_f64_t point; /**< World frame의 surface sample 또는 nearest ray hit point다. */
    math_engine_vec3_f64_t normal; /**< 선택 triangle의 deterministic world-frame unit surface normal이다. */
    double barycentric[3]; /**< 선택 triangle의 세 vertex weight다. 합은 tolerance 안에서 1이다. */
    uint64_t evaluations; /**< 검사한 triangle 또는 surface predicate 평가 횟수다. */
    uint64_t reserved[2]; /**< 향후 ABI 확장용 두 slot이다. Producer는 모두 0을 기록하고 consumer는 무시한다. */
} math_engine_ground_result_f64_t;

math_engine_ground_result_f64_t.struct_size
Caller가 sizeof(math_engine_ground_result_f64_t) 로 설정하는 byte 크기다.
```
uint32_t struct_size;
```
math_engine_ground_result_f64_t.struct_version
MATH_ENGINE_GROUND_RESULT_VERSION_1 인 result ABI version이다.
```
uint32_t struct_version;
```
math_engine_ground_result_f64_t.flags
MATH_ENGINE_RESULT_FLAG_* 중 VALUE 또는 MISS와 선택적인 quality bit 조합이다.
```
uint32_t flags;
```
math_engine_ground_result_f64_t.cell_x
Hit/sample을 포함하는 cell의 왼쪽 heightfield column index다.
```
uint32_t cell_x;
```
math_engine_ground_result_f64_t.cell_z
Hit/sample을 포함하는 cell의 앞쪽 heightfield row index다.
```
uint32_t cell_z;
```
math_engine_ground_result_f64_t.triangle_index
고정 diagonal로 나눈 cell 내부 triangle index 0 또는 1이다.
```
uint32_t triangle_index;
```
math_engine_ground_result_f64_t.reserved32
향후 ABI 확장용이다. Producer는 0을 기록하고 consumer는 무시한다.
```
uint32_t reserved32;
```
math_engine_ground_result_f64_t.height
Query x/z에서 piecewise-linear surface의 world y 값이다.
```
double height;
```
math_engine_ground_result_f64_t.ray_parameter
Raycast hit point를 origin + parameter * direction 으로 재구성하는 parameter다. Sample query에서는 0이다.
```
double ray_parameter;
```
math_engine_ground_result_f64_t.point
World frame의 surface sample 또는 nearest ray hit point다.
```
math_engine_vec3_f64_t point;
```
math_engine_ground_result_f64_t.normal
선택 triangle의 deterministic world-frame unit surface normal이다.
```
math_engine_vec3_f64_t normal;
```
math_engine_ground_result_f64_t.barycentric
선택 triangle의 세 vertex weight다. 합은 tolerance 안에서 1이다.
```
double barycentric[3];
```
math_engine_ground_result_f64_t.evaluations
검사한 triangle 또는 surface predicate 평가 횟수다.
```
uint64_t evaluations;
```
math_engine_ground_result_f64_t.reserved
향후 ABI 확장용 두 slot이다. Producer는 모두 0을 기록하고 consumer는 무시한다.
```
uint64_t reserved[2];
```

Macro와 constant

`MATH_ENGINE_COLLISION_OPTIONS_VERSION_1`

Collision option POD의 현재 ABI layout version이다.

#define MATH_ENGINE_COLLISION_OPTIONS_VERSION_1 UINT32_C(1)

`MATH_ENGINE_COLLISION_RESULT_VERSION_1`

Collision result POD의 현재 ABI layout version이다.

#define MATH_ENGINE_COLLISION_RESULT_VERSION_1 UINT32_C(1)

`MATH_ENGINE_GROUND_RESULT_VERSION_1`

Ground result POD의 현재 ABI layout version이다.

#define MATH_ENGINE_GROUND_RESULT_VERSION_1 UINT32_C(1)

`MATH_ENGINE_HEIGHTFIELD_VIEW_VERSION_1`

Heightfield view POD의 현재 ABI layout version이다.

#define MATH_ENGINE_HEIGHTFIELD_VIEW_VERSION_1 UINT32_C(1)

Function

`math_engine_collision_options_f64_init`

Runtime mode와 context tolerance에서 collision option 기본값을 만든다.

매개변수 context (in): 검증할 borrowed context. GAME_FAST는 32, 다른 지원 mode는 128 temporal sample을 선택한다.
매개변수 out_options (out): 성공 시 초기화된 caller-owned option.
반환: 성공 또는 context validation/unsupported 상태 code.

FINANCE_FIXED는 UNSUPPORTED 이며 time/distance tolerance는 context absolute tolerance다. 실패 시 output을 보존하고 callback/cancellation은 사용하지 않는다.

Math Engine ownership: context=borrowed out_options=caller
Math Engine nullable: context=false out_options=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_collision_options_f64_init(
    const math_engine_context_t* context,
    math_engine_collision_options_f64_t* out_options);

`math_engine_collision_result_f64_init`

Collision query에 전달할 빈 결과 storage를 초기화한다.

매개변수 out_result (out): 성공 시 size/version과 invalid phase/quality가 설정된 결과.
반환: 성공 또는 INVALID_ARGUMENT. 실패 시 output을 보존한다.
Math Engine ownership: out_result=caller
Math Engine nullable: out_result=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_collision_result_f64_init(
    math_engine_collision_result_f64_t* out_result);

`math_engine_point_plane_toi3_f64`

선형 이동 point와 평면의 local-time analytic TOI를 구한다.

매개변수 point (in): t=0 point 위치.
매개변수 point_velocity (in): point 선형 속도(길이 단위/s).
매개변수 plane (in): normal dot x + offset = 0 형식의 t=0 평면.
매개변수 plane_velocity (in): 평면의 선형 이동 속도(길이 단위/s).
매개변수 time_min_sec (in): 포함할 탐색 시작 시간(s).
매개변수 time_max_sec (in): 시작 이상인 포함할 탐색 끝 시간(s).
매개변수 context (in): FINANCE_FIXED가 아닌 tolerance/mode context.
매개변수 out_result (out): 미리 초기화한 hit 또는 MISS 결과 storage.
반환: 유효 query이면 hit/miss 모두 OK; validation/degenerate 상태 code.

시작 signed distance가 spatial tolerance 이내면 INITIAL_OVERLAP이다. 평면 normal은 tolerance보다 길어야 한다. No-hit도 OK 와 MISS flag로 commit한다. Input/output은 겹치면 안 되며 음수 상태에서는 output을 보존한다. Callback/cancel은 사용하지 않는다.

Math Engine ownership: point=borrowed point_velocity=borrowed plane=borrowed plane_velocity=borrowed context=borrowed out_result=caller
Math Engine nullable: point=false point_velocity=false plane=false plane_velocity=false context=false out_result=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_point_plane_toi3_f64(
    const math_engine_vec3_f64_t* point,
    const math_engine_vec3_f64_t* point_velocity,
    const math_engine_plane3_f64_t* plane,
    const math_engine_vec3_f64_t* plane_velocity,
    double time_min_sec,
    double time_max_sec,
    const math_engine_context_t* context,
    math_engine_collision_result_f64_t* out_result);

`math_engine_point_sphere_toi3_f64`

선형 이동 point와 sphere의 local-time analytic TOI를 구한다.

매개변수 point (in): t=0 point 위치.
매개변수 point_velocity (in): point 선형 속도(길이 단위/s).
매개변수 sphere (in): 0 이상 radius를 가진 t=0 sphere.
매개변수 sphere_velocity (in): sphere center 속도(길이 단위/s).
매개변수 time_min_sec (in): 포함할 탐색 시작 시간(s).
매개변수 time_max_sec (in): 시작 이상인 포함할 탐색 끝 시간(s).
매개변수 context (in): FINANCE_FIXED가 아닌 tolerance/mode context.
매개변수 out_result (out): 미리 초기화한 hit 또는 MISS 결과 storage.
반환: 유효 query이면 hit/miss 모두 OK; validation/overflow 상태 code.

안정적인 quadratic root를 사용하고 discriminant roundoff 범위를 tangent로 분류한다. 시작 거리가 radius+tolerance 이하면 INITIAL_OVERLAP이다. No-hit도 MISS로 commit하며 input/output은 겹치면 안 되고 음수 상태에서는 output을 보존한다.

Math Engine ownership: point=borrowed point_velocity=borrowed sphere=borrowed sphere_velocity=borrowed context=borrowed out_result=caller
Math Engine nullable: point=false point_velocity=false sphere=false sphere_velocity=false context=false out_result=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_point_sphere_toi3_f64(
    const math_engine_vec3_f64_t* point,
    const math_engine_vec3_f64_t* point_velocity,
    const math_engine_sphere3_f64_t* sphere,
    const math_engine_vec3_f64_t* sphere_velocity,
    double time_min_sec,
    double time_max_sec,
    const math_engine_context_t* context,
    math_engine_collision_result_f64_t* out_result);

`math_engine_point_rigid_triangle_toi3_f64`

선형 이동 point와 rigid moving triangle의 bounded local-time TOI를 구한다.

매개변수 point (in): t=0 world point 위치.
매개변수 point_velocity (in): point 속도(길이 단위/s).
매개변수 triangle_local (in): triangle의 local-coordinate 세 vertex.
매개변수 triangle_motion (in): t=0 pose, world 선형 속도와 각속도(rad/s).
매개변수 time_min_sec (in): 포함할 탐색 시작 시간(s).
매개변수 time_max_sec (in): 시작 이상인 포함할 탐색 끝 시간(s).
매개변수 options (in): 2..1048576 sample과 0 이상 time/distance tolerance.
매개변수 context (in): mode, evaluation/iteration budget와 cancel callback.
매개변수 out_result (out): 미리 초기화한 hit 또는 MISS 결과 storage.
반환: 유효 query이면 OK; validation, CANCELLED, BUDGET_EXHAUSTED 또는 root/geometry 상태 code.

GAME_FAST는 bounded sampling/bisection으로 APPROXIMATE_BOUNDED, PC_PRECISION/FULL은 root solver로 BRACKETED_REFINED를 생성한다. Candidate가 triangle 내부 distance tolerance를 통과할 때만 hit이며 snapping으로 miss를 hit로 바꾸지 않는다. Cancel callback은 호출 thread에서 동기 호출하고 보관하지 않는다. 음수 상태에서는 output을 보존하고 no-hit은 =OK=+MISS로 commit한다. 모든 storage는 서로 겹치면 안 된다.

Math Engine ownership: point=borrowed point_velocity=borrowed triangle_local=borrowed triangle_motion=borrowed options=borrowed context=borrowed out_result=caller
Math Engine nullable: point=false point_velocity=false triangle_local=false triangle_motion=false options=false context=false out_result=false
Math Engine thread_safety: conditional

MATH_ENGINE_API math_engine_status_t math_engine_point_rigid_triangle_toi3_f64(
    const math_engine_vec3_f64_t* point,
    const math_engine_vec3_f64_t* point_velocity,
    const math_engine_triangle3_f64_t* triangle_local,
    const math_engine_triangle_motion_f64_t* triangle_motion,
    double time_min_sec,
    double time_max_sec,
    const math_engine_collision_options_f64_t* options,
    const math_engine_context_t* context,
    math_engine_collision_result_f64_t* out_result);

`math_engine_ground_result_f64_init`

Heightfield query에 전달할 빈 ground 결과 storage를 초기화한다.

매개변수 out_result (out): 성공 시 size/version이 설정된 caller-owned 결과.
반환: 성공 또는 INVALID_ARGUMENT. 실패 시 output을 보존한다.
Math Engine ownership: out_result=caller
Math Engine nullable: out_result=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_ground_result_f64_init(
    math_engine_ground_result_f64_t* out_result);

`math_engine_heightfield_view_validate_f64`

Heightfield view의 ABI, dimension/stride, extent와 유한 sample을 검증한다.

매개변수 view (in): 검증할 borrowed row-major heightfield.
반환: 성공 또는 pointer, size/version, range/overflow, non-finite 상태 code.

Width/depth는 2 이상, row_stride>=width, cell size는 양수여야 한다. 모든 높이 sample을 읽어 검사하지만 view를 변경하거나 보관하지 않는다.

Math Engine ownership: view=borrowed
Math Engine nullable: view=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_heightfield_view_validate_f64(
    const math_engine_heightfield_view_f64_t* view);

`math_engine_heightfield_sample3_f64`

Heightfield cell의 두 triangle piecewise-linear surface를 sample한다.

매개변수 view (in): borrowed heightfield; origin, cell size와 height는 같은 길이 단위다.
매개변수 world_x (in): heightfield world 좌표계의 x.
매개변수 world_z (in): heightfield world 좌표계의 z.
매개변수 context (in): FINANCE_FIXED가 아닌 검증된 context.
매개변수 out_result (out): 미리 초기화한 height, point, normal/barycentric 결과.
반환: 성공 또는 validation, OUT_OF_RANGE, representability 상태 code.

Cell diagonal은 =(x0,z0)->(x1,z1)=로 고정되어 raycast와 동일한 두 triangle을 사용한다. Boundary 좌표를 마지막 cell에 deterministic하게 귀속한다. Input/output은 겹치면 안 되고 음수 상태에서 output을 보존한다. Callback/cancel은 사용하지 않는다.

Math Engine ownership: view=borrowed context=borrowed out_result=caller
Math Engine nullable: view=false context=false out_result=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_heightfield_sample3_f64(
    const math_engine_heightfield_view_f64_t* view,
    double world_x,
    double world_z,
    const math_engine_context_t* context,
    math_engine_ground_result_f64_t* out_result);

`math_engine_heightfield_raycast3_f64`

Bounded ray와 heightfield의 explicit triangle surface 중 가장 이른 hit를 구한다.

매개변수 view (in): borrowed heightfield view.
매개변수 ray (in): world 좌표의 origin과 non-degenerate direction.
매개변수 parameter_min (in): 포함할 ray parameter 하한.
매개변수 parameter_max (in): 하한 이상인 포함할 ray parameter 상한.
매개변수 context (in): tolerance, max_evaluations 와 cancel callback.
매개변수 out_result (out): 미리 초기화한 nearest hit 또는 MISS 결과.
반환: 유효 query이면 hit/miss 모두 OK; validation, DEGENERATE, CANCELLED, BUDGET_EXHAUSTED 상태 code.

Row-major cell 순서와 각 cell triangle 0,1 순서로 exhaustive 검사하며 더 작은 parameter를 선택한다. Callback은 호출 thread에서 동기 호출하고 보관하지 않는다. No-hit은 =OK=+MISS이며 음수 상태에서는 output을 보존한다. Input/output은 겹치면 안 된다.

Math Engine ownership: view=borrowed ray=borrowed context=borrowed out_result=caller
Math Engine nullable: view=false ray=false context=false out_result=false
Math Engine thread_safety: conditional

MATH_ENGINE_API math_engine_status_t math_engine_heightfield_raycast3_f64(
    const math_engine_heightfield_view_f64_t* view,
    const math_engine_ray3_f64_t* ray,
    double parameter_min,
    double parameter_max,
    const math_engine_context_t* context,
    math_engine_ground_result_f64_t* out_result);

Math Engine Reference: Collision

문서 탐색

개요

관련 public header

공개 API

Header 사용 시작

Type과 callback

math_engine_collision_phase_t

math_engine_collision_quality_t

math_engine_triangle_motion_f64_t

math_engine_collision_options_f64_t

math_engine_collision_result_f64_t

math_engine_heightfield_view_f64_t

math_engine_ground_result_f64_t

Macro와 constant

MATH_ENGINE_COLLISION_OPTIONS_VERSION_1

MATH_ENGINE_COLLISION_RESULT_VERSION_1

MATH_ENGINE_GROUND_RESULT_VERSION_1

MATH_ENGINE_HEIGHTFIELD_VIEW_VERSION_1