Math Engine Reference: Game Fast
문서 탐색
개요
Desktop GAME_FAST workload budget와 bounded-result 정책을 제공한다.
Latency fields are release benchmark ceilings for the documented reference machine; they are not wall-clock timers. Operation-count exhaustion returns BUDGET_EXHAUSTED. A caller deadline is delivered through the context cancel callback and returns CANCELLED. An approximate usable value returns OK with VALUE|UNCERTAIN. A prefix result is permitted only when the selected budget explicitly declares PREFIX_BOUNDED and the operation reports its completed count; all other failures preserve caller-owned outputs.
- 실행 원본:
include/math_engine/math_engine_game_fast.h - 분류: 수 표현·실행 profile
관련 public header
공개 API
Header 사용 시작
이 module의 public declaration을 사용하려면 installed SDK의 다음 header를 include한다.
#include <math_engine/math_engine_game_fast.h>
Type과 callback
math_engine_game_fast_workload_t
@brief Canonical GAME_FAST workload 종류다.
typedef enum math_engine_game_fast_workload {
MATH_ENGINE_GAME_FAST_WORKLOAD_INVALID = 0, /**< Uninitialized or unsupported workload sentinel. */
MATH_ENGINE_GAME_FAST_WORKLOAD_TRANSFORM_BATCH = 1, /**< Bounded f32 affine point batch. */
MATH_ENGINE_GAME_FAST_WORKLOAD_COLLISION_QUERY = 2, /**< Bounded collision or time-of-impact query. */
MATH_ENGINE_GAME_FAST_WORKLOAD_PHYSICS_STEP = 3, /**< Fixed-step force/physics batch. */
MATH_ENGINE_GAME_FAST_WORKLOAD_RIGID_INTEGRATOR = 4, /**< Fixed-step rigid-state integration. */
MATH_ENGINE_GAME_FAST_WORKLOAD_TRAJECTORY_SAMPLE = 5, /**< Bounded trajectory interpolation sample. */
MATH_ENGINE_GAME_FAST_WORKLOAD_CONTROLLER_STEP = 6, /**< Fixed-step controller transition. */
MATH_ENGINE_GAME_FAST_WORKLOAD_INTEGRATED_TICK = 7 /**< Six-subsystem atomic integrated tick. */
} math_engine_game_fast_workload_t;
math_engine_game_fast_workload_t.MATH_ENGINE_GAME_FAST_WORKLOAD_INVALID
Uninitialized or unsupported workload sentinel.
MATH_ENGINE_GAME_FAST_WORKLOAD_INVALID = 0,
math_engine_game_fast_workload_t.MATH_ENGINE_GAME_FAST_WORKLOAD_TRANSFORM_BATCH
Bounded f32 affine point batch.
MATH_ENGINE_GAME_FAST_WORKLOAD_TRANSFORM_BATCH = 1,
math_engine_game_fast_workload_t.MATH_ENGINE_GAME_FAST_WORKLOAD_COLLISION_QUERY
Bounded collision or time-of-impact query.
MATH_ENGINE_GAME_FAST_WORKLOAD_COLLISION_QUERY = 2,
math_engine_game_fast_workload_t.MATH_ENGINE_GAME_FAST_WORKLOAD_PHYSICS_STEP
Fixed-step force/physics batch.
MATH_ENGINE_GAME_FAST_WORKLOAD_PHYSICS_STEP = 3,
math_engine_game_fast_workload_t.MATH_ENGINE_GAME_FAST_WORKLOAD_RIGID_INTEGRATOR
Fixed-step rigid-state integration.
MATH_ENGINE_GAME_FAST_WORKLOAD_RIGID_INTEGRATOR = 4,
math_engine_game_fast_workload_t.MATH_ENGINE_GAME_FAST_WORKLOAD_TRAJECTORY_SAMPLE
Bounded trajectory interpolation sample.
MATH_ENGINE_GAME_FAST_WORKLOAD_TRAJECTORY_SAMPLE = 5,
math_engine_game_fast_workload_t.MATH_ENGINE_GAME_FAST_WORKLOAD_CONTROLLER_STEP
Fixed-step controller transition.
MATH_ENGINE_GAME_FAST_WORKLOAD_CONTROLLER_STEP = 6,
math_engine_game_fast_workload_t.MATH_ENGINE_GAME_FAST_WORKLOAD_INTEGRATED_TICK
Six-subsystem atomic integrated tick.
MATH_ENGINE_GAME_FAST_WORKLOAD_INTEGRATED_TICK = 7,
math_engine_game_fast_completion_policy_t
@brief 실패 시 atomic 또는 completed-prefix commit 여부를 정의한다.
typedef enum math_engine_game_fast_completion_policy {
MATH_ENGINE_GAME_FAST_COMPLETION_INVALID = 0, /**< No valid completion contract. */
MATH_ENGINE_GAME_FAST_COMPLETION_ATOMIC = 1, /**< Any negative status preserves every caller output. */
MATH_ENGINE_GAME_FAST_COMPLETION_PREFIX_BOUNDED = 2 /**< Cancellation may commit an explicitly counted prefix. */
} math_engine_game_fast_completion_policy_t;
math_engine_game_fast_completion_policy_t.MATH_ENGINE_GAME_FAST_COMPLETION_INVALID
No valid completion contract.
MATH_ENGINE_GAME_FAST_COMPLETION_INVALID = 0,
math_engine_game_fast_completion_policy_t.MATH_ENGINE_GAME_FAST_COMPLETION_ATOMIC
Any negative status preserves every caller output.
MATH_ENGINE_GAME_FAST_COMPLETION_ATOMIC = 1,
math_engine_game_fast_completion_policy_t.MATH_ENGINE_GAME_FAST_COMPLETION_PREFIX_BOUNDED
Cancellation may commit an explicitly counted prefix.
MATH_ENGINE_GAME_FAST_COMPLETION_PREFIX_BOUNDED = 2,
math_engine_game_fast_kernel_t
@brief Transform batch의 requested/selected CPU kernel 종류다.
typedef enum math_engine_game_fast_kernel {
MATH_ENGINE_GAME_FAST_KERNEL_INVALID = 0, /**< Uninitialized or unsupported kernel sentinel. */
MATH_ENGINE_GAME_FAST_KERNEL_AUTO = 1, /**< Select SSE2 when compiled and available, else scalar. */
MATH_ENGINE_GAME_FAST_KERNEL_SCALAR = 2, /**< Portable single-lane f32 implementation. */
MATH_ENGINE_GAME_FAST_KERNEL_SSE2 = 3 /**< Explicit four-lane SSE2 implementation request. */
} math_engine_game_fast_kernel_t;
math_engine_game_fast_kernel_t.MATH_ENGINE_GAME_FAST_KERNEL_INVALID
Uninitialized or unsupported kernel sentinel.
MATH_ENGINE_GAME_FAST_KERNEL_INVALID = 0,
math_engine_game_fast_kernel_t.MATH_ENGINE_GAME_FAST_KERNEL_AUTO
Select SSE2 when compiled and available, else scalar.
MATH_ENGINE_GAME_FAST_KERNEL_AUTO = 1,
math_engine_game_fast_kernel_t.MATH_ENGINE_GAME_FAST_KERNEL_SCALAR
Portable single-lane f32 implementation.
MATH_ENGINE_GAME_FAST_KERNEL_SCALAR = 2,
math_engine_game_fast_kernel_t.MATH_ENGINE_GAME_FAST_KERNEL_SSE2
Explicit four-lane SSE2 implementation request.
MATH_ENGINE_GAME_FAST_KERNEL_SSE2 = 3,
math_engine_game_fast_budget_t
@brief 한 public GAME_FAST workload 호출의 고정·유한 budget 계약이다.
typedef struct math_engine_game_fast_budget {
uint32_t struct_size; /**< Exact byte size supplied by the caller. */
uint32_t struct_version; /**< =MATH_ENGINE_GAME_FAST_BUDGET_VERSION_1=. */
uint32_t workload; /**< One non-invalid =math_engine_game_fast_workload_t=. */
uint32_t flags; /**< Bitwise =MATH_ENGINE_GAME_FAST_BUDGET_FLAG_*= policy mask. */
uint64_t required_workload_capabilities; /**< Required =MATH_ENGINE_GAME_FAST_CAPABILITY_*= mask. */
uint64_t maximum_items; /**< Inclusive per-call item ceiling for the workload. */
uint64_t max_iterations; /**< Inclusive algorithm iteration ceiling. */
uint64_t max_evaluations; /**< Inclusive callback/kernel evaluation ceiling. */
uint64_t max_workspace_bytes; /**< Maximum caller scratch requirement, in bytes. */
uint64_t target_latency_nanoseconds; /**< Reference-machine target benchmark latency in ns. */
uint64_t maximum_latency_nanoseconds; /**< Reference-machine release ceiling in ns, not a timer. */
uint64_t fixed_step_nanoseconds; /**< Required fixed step in ns, or 0 when not applicable. */
double absolute_tolerance; /**< Canonical finite nonnegative absolute error tolerance. */
double relative_tolerance; /**< Canonical finite nonnegative relative error tolerance. */
uint32_t completion_policy; /**< Atomic or explicitly counted-prefix commit policy. */
int32_t budget_exhausted_status; /**< Status returned on operation-count exhaustion. */
int32_t deadline_status; /**< Status returned when caller cancellation signals a deadline. */
uint32_t approximate_result_flags; /**< Required flags for a usable bounded approximation. */
uint64_t reserved[2]; /**< Reserved words; written as 0. */
} math_engine_game_fast_budget_t;
math_engine_game_fast_budget_t.struct_size
Exact byte size supplied by the caller.
uint32_t struct_size;
math_engine_game_fast_budget_t.struct_version
MATH_ENGINE_GAME_FAST_BUDGET_VERSION_1.uint32_t struct_version;
math_engine_game_fast_budget_t.workload
One non-invalid
math_engine_game_fast_workload_t.uint32_t workload;
math_engine_game_fast_budget_t.flags
Bitwise
MATH_ENGINE_GAME_FAST_BUDGET_FLAG_*policy mask.uint32_t flags;
math_engine_game_fast_budget_t.required_workload_capabilities
Required
MATH_ENGINE_GAME_FAST_CAPABILITY_*mask.uint64_t required_workload_capabilities;
math_engine_game_fast_budget_t.maximum_items
Inclusive per-call item ceiling for the workload.
uint64_t maximum_items;
math_engine_game_fast_budget_t.max_iterations
Inclusive algorithm iteration ceiling.
uint64_t max_iterations;
math_engine_game_fast_budget_t.max_evaluations
Inclusive callback/kernel evaluation ceiling.
uint64_t max_evaluations;
math_engine_game_fast_budget_t.max_workspace_bytes
Maximum caller scratch requirement, in bytes.
uint64_t max_workspace_bytes;
math_engine_game_fast_budget_t.target_latency_nanoseconds
Reference-machine target benchmark latency in ns.
uint64_t target_latency_nanoseconds;
math_engine_game_fast_budget_t.maximum_latency_nanoseconds
Reference-machine release ceiling in ns, not a timer.
uint64_t maximum_latency_nanoseconds;
math_engine_game_fast_budget_t.fixed_step_nanoseconds
Required fixed step in ns, or 0 when not applicable.
uint64_t fixed_step_nanoseconds;
math_engine_game_fast_budget_t.absolute_tolerance
Canonical finite nonnegative absolute error tolerance.
double absolute_tolerance;
math_engine_game_fast_budget_t.relative_tolerance
Canonical finite nonnegative relative error tolerance.
double relative_tolerance;
math_engine_game_fast_budget_t.completion_policy
Atomic or explicitly counted-prefix commit policy.
uint32_t completion_policy;
math_engine_game_fast_budget_t.budget_exhausted_status
Status returned on operation-count exhaustion.
int32_t budget_exhausted_status;
math_engine_game_fast_budget_t.deadline_status
Status returned when caller cancellation signals a deadline.
int32_t deadline_status;
math_engine_game_fast_budget_t.approximate_result_flags
Required flags for a usable bounded approximation.
uint32_t approximate_result_flags;
math_engine_game_fast_budget_t.reserved
Reserved words; written as 0.
uint64_t reserved[2];
math_engine_game_fast_dispatch_info_t
@brief Runtime-selected private kernel과 CPU feature를 기술하는 중립 POD다.
typedef struct math_engine_game_fast_dispatch_info {
uint32_t struct_size; /**< Exact byte size supplied by the caller. */
uint32_t struct_version; /**< =MATH_ENGINE_GAME_FAST_DISPATCH_INFO_VERSION_1=. */
uint32_t requested_kernel; /**< Caller request, including AUTO when used. */
uint32_t selected_kernel; /**< Resolved SCALAR or SSE2 kernel. */
uint32_t vector_width_f32; /**< Selected f32 lane count: 1 for scalar, 4 for SSE2. */
uint32_t workspace_alignment; /**< Required scratch alignment in bytes; currently 16. */
uint32_t deterministic; /**< Boolean: 1 when identical inputs preserve operation order. */
uint32_t reserved32; /**< Reserved for ABI growth; written as 0. */
uint64_t compiled_cpu_features; /**< Feature bits compiled into this artifact. */
uint64_t runtime_cpu_features; /**< Compiled features also detected on the running CPU. */
uint64_t required_cpu_features; /**< Features required by =selected_kernel=. */
uint64_t reserved64; /**< Reserved for ABI growth; written as 0. */
} math_engine_game_fast_dispatch_info_t;
math_engine_game_fast_dispatch_info_t.struct_size
Exact byte size supplied by the caller.
uint32_t struct_size;
math_engine_game_fast_dispatch_info_t.struct_version
MATH_ENGINE_GAME_FAST_DISPATCH_INFO_VERSION_1.uint32_t struct_version;
math_engine_game_fast_dispatch_info_t.requested_kernel
Caller request, including AUTO when used.
uint32_t requested_kernel;
math_engine_game_fast_dispatch_info_t.selected_kernel
Resolved SCALAR or SSE2 kernel.
uint32_t selected_kernel;
math_engine_game_fast_dispatch_info_t.vector_width_f32
Selected f32 lane count: 1 for scalar, 4 for SSE2.
uint32_t vector_width_f32;
math_engine_game_fast_dispatch_info_t.workspace_alignment
Required scratch alignment in bytes; currently 16.
uint32_t workspace_alignment;
math_engine_game_fast_dispatch_info_t.deterministic
Boolean: 1 when identical inputs preserve operation order.
uint32_t deterministic;
math_engine_game_fast_dispatch_info_t.reserved32
Reserved for ABI growth; written as 0.
uint32_t reserved32;
math_engine_game_fast_dispatch_info_t.compiled_cpu_features
Feature bits compiled into this artifact.
uint64_t compiled_cpu_features;
math_engine_game_fast_dispatch_info_t.runtime_cpu_features
Compiled features also detected on the running CPU.
uint64_t runtime_cpu_features;
math_engine_game_fast_dispatch_info_t.required_cpu_features
Features required by
selected_kernel.uint64_t required_cpu_features;
math_engine_game_fast_dispatch_info_t.reserved64
Reserved for ABI growth; written as 0.
uint64_t reserved64;
math_engine_game_fast_affine3_f32_t
@brief Public row-major 3x4 f32 affine 값이다. Private SIMD type은 노출하지 않는다.
typedef struct math_engine_game_fast_affine3_f32 {
float values[12]; /**< Finite row-major 3x4 affine coefficients, rows x/y/z. */
} math_engine_game_fast_affine3_f32_t;
math_engine_game_fast_soa3_const_f32_t
@brief 연속 caller-owned structure-of-arrays 입력의 borrowed view다.
typedef struct math_engine_game_fast_soa3_const_f32 {
const float* x; /**< Non-null borrowed x array of =count= floats; retained only for the call. */
const float* y; /**< Non-null borrowed y array of =count= floats; retained only for the call. */
const float* z; /**< Non-null borrowed z array of =count= floats; retained only for the call. */
uint32_t count; /**< Common readable element count in inclusive [1, 4096]. */
uint32_t reserved; /**< Reserved for ABI growth; must be 0. */
} math_engine_game_fast_soa3_const_f32_t;
math_engine_game_fast_soa3_const_f32_t.x
Non-null borrowed x array of
countfloats; retained only for the call.const float* x;
math_engine_game_fast_soa3_const_f32_t.y
Non-null borrowed y array of
countfloats; retained only for the call.const float* y;
math_engine_game_fast_soa3_const_f32_t.z
Non-null borrowed z array of
countfloats; retained only for the call.const float* z;
math_engine_game_fast_soa3_const_f32_t.count
Common readable element count in inclusive [1, 4096].
uint32_t count;
math_engine_game_fast_soa3_const_f32_t.reserved
Reserved for ABI growth; must be 0.
uint32_t reserved;
math_engine_game_fast_soa3_f32_t
@brief 연속 caller-owned structure-of-arrays 출력 view다.
typedef struct math_engine_game_fast_soa3_f32 {
float* x; /**< Non-null caller-owned writable x array of =capacity= floats; never retained. */
float* y; /**< Non-null caller-owned writable y array of =capacity= floats; never retained. */
float* z; /**< Non-null caller-owned writable z array of =capacity= floats; never retained. */
uint32_t capacity; /**< Common writable capacity; must be at least the input count. */
uint32_t reserved; /**< Reserved for ABI growth; must be 0. */
} math_engine_game_fast_soa3_f32_t;
math_engine_game_fast_soa3_f32_t.x
Non-null caller-owned writable x array of
capacityfloats; never retained.float* x;
math_engine_game_fast_soa3_f32_t.y
Non-null caller-owned writable y array of
capacityfloats; never retained.float* y;
math_engine_game_fast_soa3_f32_t.z
Non-null caller-owned writable z array of
capacityfloats; never retained.float* z;
math_engine_game_fast_soa3_f32_t.capacity
Common writable capacity; must be at least the input count.
uint32_t capacity;
math_engine_game_fast_soa3_f32_t.reserved
Reserved for ABI growth; must be 0.
uint32_t reserved;
math_engine_game_fast_batch_result_t
@brief Batch 완료 범위, selected kernel, error bound와 replay fingerprint다.
typedef struct math_engine_game_fast_batch_result {
uint32_t struct_size; /**< Exact byte size supplied by the caller. */
uint32_t struct_version; /**< =MATH_ENGINE_GAME_FAST_BATCH_RESULT_VERSION_1=. */
uint32_t flags; /**< Generic result flags plus GAME_FAST SIMD/deterministic bits. */
uint32_t requested_kernel; /**< Original AUTO, SCALAR or SSE2 request. */
uint32_t selected_kernel; /**< Kernel that evaluated the committed prefix. */
uint32_t vector_width_f32; /**< Selected f32 lane count, 1 or 4. */
uint32_t item_count; /**< Total requested input count. */
uint32_t completed_count; /**< Output prefix committed; equals =item_count= on success. */
double maximum_magnitude; /**< Maximum absolute x/y/z component in the committed prefix. */
double maximum_error_bound; /**< Context-derived absolute bound at maximum magnitude. */
uint64_t deterministic_fingerprint; /**< FNV fingerprint of committed x/y/z float bytes. */
uint64_t reserved[3]; /**< Reserved words; written as 0. */
} math_engine_game_fast_batch_result_t;
math_engine_game_fast_batch_result_t.struct_size
Exact byte size supplied by the caller.
uint32_t struct_size;
math_engine_game_fast_batch_result_t.struct_version
MATH_ENGINE_GAME_FAST_BATCH_RESULT_VERSION_1.uint32_t struct_version;
math_engine_game_fast_batch_result_t.flags
Generic result flags plus GAME_FAST SIMD/deterministic bits.
uint32_t flags;
math_engine_game_fast_batch_result_t.requested_kernel
Original AUTO, SCALAR or SSE2 request.
uint32_t requested_kernel;
math_engine_game_fast_batch_result_t.selected_kernel
Kernel that evaluated the committed prefix.
uint32_t selected_kernel;
math_engine_game_fast_batch_result_t.vector_width_f32
Selected f32 lane count, 1 or 4.
uint32_t vector_width_f32;
math_engine_game_fast_batch_result_t.item_count
Total requested input count.
uint32_t item_count;
math_engine_game_fast_batch_result_t.completed_count
Output prefix committed; equals
item_counton success.uint32_t completed_count;
math_engine_game_fast_batch_result_t.maximum_magnitude
Maximum absolute x/y/z component in the committed prefix.
double maximum_magnitude;
math_engine_game_fast_batch_result_t.maximum_error_bound
Context-derived absolute bound at maximum magnitude.
double maximum_error_bound;
math_engine_game_fast_batch_result_t.deterministic_fingerprint
FNV fingerprint of committed x/y/z float bytes.
uint64_t deterministic_fingerprint;
math_engine_game_fast_batch_result_t.reserved
Reserved words; written as 0.
uint64_t reserved[3];
math_engine_game_fast_tick_config_f64_t
Immutable fixed-tick scenario policy다.
Integrated path는 rigid transform, point/plane collision, gravity, 6-state RK4, two-knot trajectory와 3축 PID transition을 이 순서로 적용한다.
typedef struct math_engine_game_fast_tick_config_f64 {
uint32_t struct_size; /**< Exact byte size of this tick policy. */
uint32_t struct_version; /**< =MATH_ENGINE_GAME_FAST_TICK_CONFIG_VERSION_1=. */
double fixed_delta_seconds; /**< Finite positive simulation step in seconds. */
double mass_kg; /**< Finite positive body mass used by gravity, in kilograms. */
double trajectory_horizon_seconds; /**< Finite horizon in seconds, at least one fixed step. */
double ground_plane_offset; /**< Plane equation offset for =dot(normal,p)+offset=0=, in metres. */
math_engine_vec3_f64_t gravity_mps2; /**< Finite world-frame gravitational acceleration in m/s^2. */
math_engine_vec3_f64_t ground_normal; /**< Finite non-degenerate world-frame plane normal. */
/** Body-local point transformed for ground collision, in metres. */
math_engine_vec3_f64_t local_collision_point_m;
math_engine_vec3_f64_t target_position_m; /**< World-frame endpoint of the two-knot trajectory, in metres. */
math_engine_quat_f64_t orientation; /**< Finite normalized body-to-world orientation. */
/** Fixed-step parameters shared by x/y/z position controllers. */
math_engine_pid_parameters_f64_t controller_parameters;
uint64_t reserved[4]; /**< Reserved words; all four elements must be 0. */
} math_engine_game_fast_tick_config_f64_t;
math_engine_game_fast_tick_config_f64_t.struct_size
Exact byte size of this tick policy.
uint32_t struct_size;
math_engine_game_fast_tick_config_f64_t.struct_version
MATH_ENGINE_GAME_FAST_TICK_CONFIG_VERSION_1.uint32_t struct_version;
math_engine_game_fast_tick_config_f64_t.fixed_delta_seconds
Finite positive simulation step in seconds.
double fixed_delta_seconds;
math_engine_game_fast_tick_config_f64_t.mass_kg
Finite positive body mass used by gravity, in kilograms.
double mass_kg;
math_engine_game_fast_tick_config_f64_t.trajectory_horizon_seconds
Finite horizon in seconds, at least one fixed step.
double trajectory_horizon_seconds;
math_engine_game_fast_tick_config_f64_t.ground_plane_offset
Plane equation offset for
dot(normal,p)+offset=0, in metres.double ground_plane_offset;
math_engine_game_fast_tick_config_f64_t.gravity_mps2
Finite world-frame gravitational acceleration in m/s^2.
math_engine_vec3_f64_t gravity_mps2;
math_engine_game_fast_tick_config_f64_t.ground_normal
Finite non-degenerate world-frame plane normal.
math_engine_vec3_f64_t ground_normal;
math_engine_game_fast_tick_config_f64_t.local_collision_point_m
Body-local point transformed for ground collision, in metres.
/** Body-local point transformed for ground collision, in metres. */ math_engine_vec3_f64_t local_collision_point_m;math_engine_game_fast_tick_config_f64_t.target_position_m
World-frame endpoint of the two-knot trajectory, in metres.
math_engine_vec3_f64_t target_position_m;
math_engine_game_fast_tick_config_f64_t.orientation
Finite normalized body-to-world orientation.
math_engine_quat_f64_t orientation;
math_engine_game_fast_tick_config_f64_t.controller_parameters
Fixed-step parameters shared by x/y/z position controllers.
/** Fixed-step parameters shared by x/y/z position controllers. */ math_engine_pid_parameters_f64_t controller_parameters;math_engine_game_fast_tick_config_f64_t.reserved
Reserved words; all four elements must be 0.
uint64_t reserved[4];
math_engine_game_fast_tick_state_f64_t
@brief Caller-owned integrated-tick dynamic state다.
Controller output은 다음 tick의 acceleration input으로 적용된다.
typedef struct math_engine_game_fast_tick_state_f64 {
uint32_t struct_size; /**< Exact byte size of this dynamic state. */
uint32_t struct_version; /**< =MATH_ENGINE_GAME_FAST_TICK_STATE_VERSION_1=. */
math_engine_vec3_f64_t position_m; /**< Finite world-frame body position in metres. */
math_engine_vec3_f64_t velocity_mps; /**< Finite world-frame linear velocity in m/s. */
/** Controller acceleration applied during the next evaluated tick. */
math_engine_vec3_f64_t control_acceleration_mps2;
math_engine_pid_vec3_state_v2_f64_t controller_state; /**< Versioned x/y/z PID histories retained across ticks. */
uint64_t tick_index; /**< Last committed tick number; must be below =UINT64_MAX=. */
uint64_t replay_fingerprint; /**< Rolling deterministic fingerprint through =tick_index=. */
uint64_t reserved[2]; /**< Reserved words; both elements must be 0. */
} math_engine_game_fast_tick_state_f64_t;
math_engine_game_fast_tick_state_f64_t.struct_size
Exact byte size of this dynamic state.
uint32_t struct_size;
math_engine_game_fast_tick_state_f64_t.struct_version
MATH_ENGINE_GAME_FAST_TICK_STATE_VERSION_1.uint32_t struct_version;
math_engine_game_fast_tick_state_f64_t.position_m
Finite world-frame body position in metres.
math_engine_vec3_f64_t position_m;
math_engine_game_fast_tick_state_f64_t.velocity_mps
Finite world-frame linear velocity in m/s.
math_engine_vec3_f64_t velocity_mps;
math_engine_game_fast_tick_state_f64_t.control_acceleration_mps2
Controller acceleration applied during the next evaluated tick.
/** Controller acceleration applied during the next evaluated tick. */ math_engine_vec3_f64_t control_acceleration_mps2;math_engine_game_fast_tick_state_f64_t.controller_state
Versioned x/y/z PID histories retained across ticks.
math_engine_pid_vec3_state_v2_f64_t controller_state;
math_engine_game_fast_tick_state_f64_t.tick_index
Last committed tick number; must be below
UINT64_MAX.uint64_t tick_index;
math_engine_game_fast_tick_state_f64_t.replay_fingerprint
Rolling deterministic fingerprint through
tick_index.uint64_t replay_fingerprint;
math_engine_game_fast_tick_state_f64_t.reserved
Reserved words; both elements must be 0.
uint64_t reserved[2];
math_engine_game_fast_tick_result_f64_t
@brief 한 atomic integrated tick의 결과와 deterministic replay identity다.
typedef struct math_engine_game_fast_tick_result_f64 {
uint32_t struct_size; /**< Exact byte size supplied by the caller. */
uint32_t struct_version; /**< =MATH_ENGINE_GAME_FAST_TICK_RESULT_VERSION_1=. */
uint32_t flags; /**< Generic value/uncertain flags plus collision/deterministic bits. */
uint32_t subsystem_count; /**< Number of executed canonical subsystems; currently 6. */
uint64_t tick_index; /**< Newly committed tick index. */
uint64_t evaluation_count; /**< Aggregate collision, integration and fixed-stage evaluations. */
math_engine_vec3_f64_t transformed_collision_point_m; /**< Body point transformed into world frame, in metres. */
math_engine_vec3_f64_t gravity_force_newtons; /**< World-frame uniform-gravity force in newtons. */
math_engine_vec3_f64_t integrated_position_m; /**< World-frame position after the fixed RK4 step, in metres. */
math_engine_vec3_f64_t integrated_velocity_mps; /**< World-frame velocity after the fixed RK4 step, in m/s. */
math_engine_vec3_f64_t trajectory_setpoint_m; /**< Sampled world-frame controller setpoint in metres. */
/** Controller output to apply on the following tick, in m/s^2. */
math_engine_vec3_f64_t controller_acceleration_mps2;
double collision_time_seconds; /**< Hit time in [0, step], or the full step when no hit exists. */
double maximum_error_bound; /**< Maximum reported absolute bound across all six subsystems. */
uint64_t replay_fingerprint; /**< Rolling deterministic identity also stored in the next state. */
uint64_t reserved[3]; /**< Reserved words; written as 0. */
} math_engine_game_fast_tick_result_f64_t;
math_engine_game_fast_tick_result_f64_t.struct_size
Exact byte size supplied by the caller.
uint32_t struct_size;
math_engine_game_fast_tick_result_f64_t.struct_version
MATH_ENGINE_GAME_FAST_TICK_RESULT_VERSION_1.uint32_t struct_version;
math_engine_game_fast_tick_result_f64_t.flags
Generic value/uncertain flags plus collision/deterministic bits.
uint32_t flags;
math_engine_game_fast_tick_result_f64_t.subsystem_count
Number of executed canonical subsystems; currently 6.
uint32_t subsystem_count;
math_engine_game_fast_tick_result_f64_t.tick_index
Newly committed tick index.
uint64_t tick_index;
math_engine_game_fast_tick_result_f64_t.evaluation_count
Aggregate collision, integration and fixed-stage evaluations.
uint64_t evaluation_count;
math_engine_game_fast_tick_result_f64_t.transformed_collision_point_m
Body point transformed into world frame, in metres.
math_engine_vec3_f64_t transformed_collision_point_m;
math_engine_game_fast_tick_result_f64_t.gravity_force_newtons
World-frame uniform-gravity force in newtons.
math_engine_vec3_f64_t gravity_force_newtons;
math_engine_game_fast_tick_result_f64_t.integrated_position_m
World-frame position after the fixed RK4 step, in metres.
math_engine_vec3_f64_t integrated_position_m;
math_engine_game_fast_tick_result_f64_t.integrated_velocity_mps
World-frame velocity after the fixed RK4 step, in m/s.
math_engine_vec3_f64_t integrated_velocity_mps;
math_engine_game_fast_tick_result_f64_t.trajectory_setpoint_m
Sampled world-frame controller setpoint in metres.
math_engine_vec3_f64_t trajectory_setpoint_m;
math_engine_game_fast_tick_result_f64_t.controller_acceleration_mps2
Controller output to apply on the following tick, in m/s^2.
/** Controller output to apply on the following tick, in m/s^2. */ math_engine_vec3_f64_t controller_acceleration_mps2;math_engine_game_fast_tick_result_f64_t.collision_time_seconds
Hit time in [0, step], or the full step when no hit exists.
double collision_time_seconds;
math_engine_game_fast_tick_result_f64_t.maximum_error_bound
Maximum reported absolute bound across all six subsystems.
double maximum_error_bound;
math_engine_game_fast_tick_result_f64_t.replay_fingerprint
Rolling deterministic identity also stored in the next state.
uint64_t replay_fingerprint;
math_engine_game_fast_tick_result_f64_t.reserved
Reserved words; written as 0.
uint64_t reserved[3];
Macro와 constant
MATH_ENGINE_GAME_FAST_BATCH_RESULT_VERSION_1
Initial layout version for math_engine_game_fast_batch_result_t.
#define MATH_ENGINE_GAME_FAST_BATCH_RESULT_VERSION_1 UINT32_C(1)
MATH_ENGINE_GAME_FAST_BUDGET_FLAG_BINARY32_PRIMARY
Binary32 is the primary storage/evaluation format for this workload.
#define MATH_ENGINE_GAME_FAST_BUDGET_FLAG_BINARY32_PRIMARY (UINT32_C(1) << 4u)
MATH_ENGINE_GAME_FAST_BUDGET_FLAG_BINARY64_ALLOWED
Binary64 intermediates or public values are allowed by this workload.
#define MATH_ENGINE_GAME_FAST_BUDGET_FLAG_BINARY64_ALLOWED (UINT32_C(1) << 5u)
MATH_ENGINE_GAME_FAST_BUDGET_FLAG_CALLER_WORKSPACE
All reusable scratch storage is supplied by the caller.
#define MATH_ENGINE_GAME_FAST_BUDGET_FLAG_CALLER_WORKSPACE (UINT32_C(1) << 2u)
MATH_ENGINE_GAME_FAST_BUDGET_FLAG_DETERMINISTIC
Workload uses a deterministic operation order and replay identity.
#define MATH_ENGINE_GAME_FAST_BUDGET_FLAG_DETERMINISTIC (UINT32_C(1) << 0u)
MATH_ENGINE_GAME_FAST_BUDGET_FLAG_FIXED_STEP
Workload requires the published nonzero fixed_step_nanoseconds.
#define MATH_ENGINE_GAME_FAST_BUDGET_FLAG_FIXED_STEP (UINT32_C(1) << 1u)
MATH_ENGINE_GAME_FAST_BUDGET_FLAG_HEAP_FORBIDDEN
Workload implementation performs no heap allocation.
#define MATH_ENGINE_GAME_FAST_BUDGET_FLAG_HEAP_FORBIDDEN (UINT32_C(1) << 3u)
MATH_ENGINE_GAME_FAST_BUDGET_VERSION_1
Initial layout version for math_engine_game_fast_budget_t.
#define MATH_ENGINE_GAME_FAST_BUDGET_VERSION_1 UINT32_C(1)
MATH_ENGINE_GAME_FAST_CAPABILITY_COLLISION
Artifact can execute the GAME_FAST collision workload.
#define MATH_ENGINE_GAME_FAST_CAPABILITY_COLLISION (UINT64_C(1) << 1u)
MATH_ENGINE_GAME_FAST_CAPABILITY_CONTROL
Artifact can execute the GAME_FAST controller workload.
#define MATH_ENGINE_GAME_FAST_CAPABILITY_CONTROL (UINT64_C(1) << 5u)
MATH_ENGINE_GAME_FAST_CAPABILITY_INTEGRATOR
Artifact can execute the GAME_FAST integrator workload.
#define MATH_ENGINE_GAME_FAST_CAPABILITY_INTEGRATOR (UINT64_C(1) << 3u)
MATH_ENGINE_GAME_FAST_CAPABILITY_PHYSICS
Artifact can execute the GAME_FAST physics workload.
#define MATH_ENGINE_GAME_FAST_CAPABILITY_PHYSICS (UINT64_C(1) << 2u)
MATH_ENGINE_GAME_FAST_CAPABILITY_TRAJECTORY
Artifact can execute the GAME_FAST trajectory workload.
#define MATH_ENGINE_GAME_FAST_CAPABILITY_TRAJECTORY (UINT64_C(1) << 4u)
MATH_ENGINE_GAME_FAST_CAPABILITY_TRANSFORM
Artifact can execute the GAME_FAST affine transform workload.
#define MATH_ENGINE_GAME_FAST_CAPABILITY_TRANSFORM (UINT64_C(1) << 0u)
MATH_ENGINE_GAME_FAST_CPU_FEATURE_SSE2
CPU feature bit indicating SSE2 support in compiled/runtime masks.
#define MATH_ENGINE_GAME_FAST_CPU_FEATURE_SSE2 (UINT64_C(1) << 0u)
MATH_ENGINE_GAME_FAST_DISPATCH_INFO_VERSION_1
Initial layout version for math_engine_game_fast_dispatch_info_t.
#define MATH_ENGINE_GAME_FAST_DISPATCH_INFO_VERSION_1 UINT32_C(1)
MATH_ENGINE_GAME_FAST_RESULT_FLAG_DETERMINISTIC
Batch or tick used a deterministic operation order and fingerprint.
#define MATH_ENGINE_GAME_FAST_RESULT_FLAG_DETERMINISTIC (UINT32_C(1) << 25u)
MATH_ENGINE_GAME_FAST_RESULT_FLAG_SIMD
Batch selected a vectorized SIMD kernel.
#define MATH_ENGINE_GAME_FAST_RESULT_FLAG_SIMD (UINT32_C(1) << 24u)
MATH_ENGINE_GAME_FAST_TICK_CONFIG_VERSION_1
Initial layout version for math_engine_game_fast_tick_config_f64_t.
#define MATH_ENGINE_GAME_FAST_TICK_CONFIG_VERSION_1 UINT32_C(1)
MATH_ENGINE_GAME_FAST_TICK_FLAG_COLLISION_HIT
Integrated tick에서 ground collision이 검출되었음을 나타내는 result bit다.
#define MATH_ENGINE_GAME_FAST_TICK_FLAG_COLLISION_HIT (UINT32_C(1) << 26u)
MATH_ENGINE_GAME_FAST_TICK_RESULT_VERSION_1
Initial layout version for math_engine_game_fast_tick_result_f64_t.
#define MATH_ENGINE_GAME_FAST_TICK_RESULT_VERSION_1 UINT32_C(1)
MATH_ENGINE_GAME_FAST_TICK_STATE_VERSION_1
Initial layout version for math_engine_game_fast_tick_state_f64_t.
#define MATH_ENGINE_GAME_FAST_TICK_STATE_VERSION_1 UINT32_C(1)
Function
math_engine_game_fast_budget_count
Immutable canonical GAME_FAST workload budget 개수를 반환한다.
- 반환: 현재 append-only workload table의 항목 수 7.
외부 state, allocation, callback을 사용하지 않는다.
- Math Engine thread_safety:
safe
MATH_ENGINE_API uint32_t math_engine_game_fast_budget_count(void);
math_engine_game_fast_budget_get
Workload enum에 해당하는 canonical GAME_FAST budget를 조회한다.
- 매개변수
workload(in): INVALID가 아닌 공개 workload 식별자. - 매개변수
out_budget(in,out): size/version을 미리 설정한 caller-owned budget storage. - 반환: 알려진 workload이면
OK, 아니면 validation/unsupported 상태 code.
Budget table은 immutable하며 동일 build에서 deterministic하다. 실패 시 초기화된 output을 보존하고 callback/cancellation을 사용하지 않는다.
- Math Engine ownership:
out_budget=caller - Math Engine nullable:
out_budget=false - Math Engine thread_safety:
safe
MATH_ENGINE_API math_engine_status_t math_engine_game_fast_budget_get(
math_engine_game_fast_workload_t workload,
math_engine_game_fast_budget_t* out_budget);
math_engine_game_fast_dispatch_info_init
Kernel dispatch 조회에 전달할 빈 info storage를 초기화한다.
- 매개변수
out_info(out): 성공 시 size/version이 설정된 caller-owned info. - 반환: 성공 또는
INVALID_ARGUMENT. 실패 시 output을 보존한다. - Math Engine ownership:
out_info=caller - Math Engine nullable:
out_info=false - Math Engine thread_safety:
safe
MATH_ENGINE_API math_engine_status_t math_engine_game_fast_dispatch_info_init(
math_engine_game_fast_dispatch_info_t* out_info);
math_engine_game_fast_batch_result_init
Transform batch에 전달할 빈 result storage를 초기화한다.
- 매개변수
out_result(out): 성공 시 size/version이 설정된 caller-owned result. - 반환: 성공 또는
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_game_fast_batch_result_init(
math_engine_game_fast_batch_result_t* out_result);
math_engine_game_fast_tick_config_f64_init
Canonical 60 Hz integrated scenario policy를 초기화하고 검증한다.
- 매개변수
context(in): GAME_FAST mode인 borrowed runtime context. - 매개변수
out_config(out): 성공 시 SI gravity/mass, target와 fixed-step PID가 설정된 config. - 반환: 성공 또는 context/PID/geometry validation 상태 code.
fixed_delta_seconds 와 trajectory horizon은 1/60 s, mass는 1 kg, 중력은
=(0,-9.80665,0) m/s^2=다. 실패 시 output을 보존하고 callback은 호출하지 않는다.
- Math Engine ownership:
context=borrowed out_config=caller - Math Engine nullable:
context=false out_config=false - Math Engine thread_safety:
safe
MATH_ENGINE_API math_engine_status_t math_engine_game_fast_tick_config_f64_init(
const math_engine_context_t* context,
math_engine_game_fast_tick_config_f64_t* out_config);
math_engine_game_fast_tick_config_f64_validate
Integrated-tick config의 ABI, SI 값, frame과 fixed PID policy를 검증한다.
- 매개변수
config(in): 검증할 borrowed immutable scenario config. - 매개변수
context(in): GAME_FAST mode와 degeneracy tolerance를 제공하는 context. - 반환: 성공 또는 size/version, non-finite, degenerate, unsupported 상태 code.
양의 fixed step/mass, horizon>=step, non-degenerate ground normal, normalized 가능한 orientation과 fixed-step PID 일치를 요구한다. Input을 변경하지 않고 cancel을 호출하지 않는다.
- Math Engine ownership:
config=borrowed context=borrowed - Math Engine nullable:
config=false context=false - Math Engine thread_safety:
safe
MATH_ENGINE_API math_engine_status_t math_engine_game_fast_tick_config_f64_validate(
const math_engine_game_fast_tick_config_f64_t* config,
const math_engine_context_t* context);
math_engine_game_fast_tick_state_f64_init
Ground 기준 1 m 높이의 replayable integrated-tick state를 초기화한다.
- 매개변수
out_state(out): position=(0,1,0) m, zero velocity/control과 empty PID state. - 반환: 성공 또는
INVALID_ARGUMENT이나 내부 PID 초기화 상태 code.
Replay fingerprint는 고정 FNV-1a offset으로 시작한다. 실패 시 output을 보존한다.
- Math Engine ownership:
out_state=caller - Math Engine nullable:
out_state=false - Math Engine thread_safety:
safe
MATH_ENGINE_API math_engine_status_t math_engine_game_fast_tick_state_f64_init(
math_engine_game_fast_tick_state_f64_t* out_state);
math_engine_game_fast_tick_result_f64_init
Integrated-tick에 전달할 빈 result storage를 초기화한다.
- 매개변수
out_result(out): 성공 시 size/version이 설정된 caller-owned result. - 반환: 성공 또는
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_game_fast_tick_result_f64_init(
math_engine_game_fast_tick_result_f64_t* out_result);
math_engine_game_fast_dispatch_get
검증된 GAME_FAST context에서 AUTO/scalar/SSE2 kernel을 resolve한다.
- 매개변수
context(in): GAME_FAST mode인 borrowed context. - 매개변수
requested_kernel(in): AUTO, SCALAR 또는 SSE2 요청. - 매개변수
out_info(in,out): 미리 초기화한 caller-owned dispatch result. - 반환: 성공 또는 context, kernel, CPU support, output ABI 상태 code.
AUTO는 compile/runtime SSE2가 모두 있으면 SSE2, 아니면 scalar를 선택한다. 명시 SSE2가
없으면 UNSUPPORTED 다. Alignment는 16 byte, 결과는 deterministic으로 보고한다.
실패 시 output을 보존하고 callback/cancel은 사용하지 않는다.
- Math Engine ownership:
context=borrowed out_info=caller - Math Engine nullable:
context=false out_info=false - Math Engine thread_safety:
safe
MATH_ENGINE_API math_engine_status_t math_engine_game_fast_dispatch_get(
const math_engine_context_t* context,
math_engine_game_fast_kernel_t requested_kernel,
math_engine_game_fast_dispatch_info_t* out_info);
math_engine_game_fast_transform_batch_workspace_size_f32
Transform batch의 reusable 16-byte-aligned staging workspace byte 수를 구한다.
- 매개변수
maximum_items(in): 1..4096 범위의 최대 point 수. - 매개변수
out_bytes(out): 성공 시maximum_items * 3 * sizeof(float)byte 수. - 반환: 성공 또는
INVALID_ARGUMENT,OUT_OF_RANGE.
실패 시 output을 보존하고 allocation을 수행하지 않는다.
- Math Engine ownership:
out_bytes=caller - Math Engine nullable:
out_bytes=false - Math Engine thread_safety:
safe
MATH_ENGINE_API math_engine_status_t
math_engine_game_fast_transform_batch_workspace_size_f32(
uint32_t maximum_items,
size_t* out_bytes);
math_engine_game_fast_transform_batch_f32
연속 SoA point batch에 하나의 f32 affine transform을 적용한다.
- 매개변수
transform(in): 유한한 row-major 3x4 affine 값. - 매개변수
input(in): 각각count개인 borrowed contiguous x/y/z input arrays. - 매개변수
context(in): GAME_FAST mode, error tolerance와 cancel callback. - 매개변수
requested_kernel(in): AUTO, SCALAR 또는 SSE2 dispatch 요청. - 매개변수
workspace(in,out): 최소 size query 결과 크기이고 16-byte 정렬된 caller scratch. - 매개변수
workspace_bytes(in): workspace의 byte capacity. - 매개변수
output(in,out): 각각capacity개인 caller-owned x/y/z output arrays의 view. - 매개변수
out_result(in,out): 미리 초기화한 completion/kernel/error/fingerprint result. - 반환: 성공, 또는 validation/workspace/kernel 상태와
CANCELLED.
Input/output arrays may alias because all results are staged in reusable caller workspace. Output x/y/z arrays must not overlap each other and the workspace must overlap neither input nor output. On cancellation after at least one fixed 64-item chunk, the completed prefix and PARTIAL result are committed and CANCELLED is returned; cancellation before work is atomic. Item 수는 1..4096이고 동일 kernel/input에서는 고정 연산 순서와 FNV fingerprint를 사용한다. Cancel callback은 호출 thread에서 chunk 경계마다 동기 호출하고 보관하지 않는다.
- Math Engine ownership:
transform=borrowed input=borrowed context=borrowed workspace=caller output=caller out_result=caller - Math Engine nullable:
transform=false input=false context=false workspace=false output=false out_result=false - Math Engine thread_safety:
conditional
MATH_ENGINE_API math_engine_status_t math_engine_game_fast_transform_batch_f32(
const math_engine_game_fast_affine3_f32_t* transform,
const math_engine_game_fast_soa3_const_f32_t* input,
const math_engine_context_t* context,
math_engine_game_fast_kernel_t requested_kernel,
void* workspace,
size_t workspace_bytes,
const math_engine_game_fast_soa3_f32_t* output,
math_engine_game_fast_batch_result_t* out_result);
math_engine_game_fast_tick_f64
Transform부터 controller까지 allocation-free integrated fixed tick을 실행한다.
- 매개변수
config(in): 검증된 immutable GAME_FAST SI scenario policy. - 매개변수
state(in): 현재 caller-owned dynamic state. - 매개변수
context(in): GAME_FAST mode, tolerance/budget와 cancel callback. - 매개변수
out_state(out): 다음 tick state.state와 exact alias 가능하다. - 매개변수
out_result(out): 6개 subsystem 결과, error bound와 replay fingerprint. - 반환: 성공 또는 config/state/subsystem 상태와
CANCELLED,BUDGET_EXHAUSTED.
Rigid transform, point-plane collision, uniform gravity, 6-state fixed RK4,
two-knot trajectory sample, three-axis PID 순서로 실행한다. 현재 state의 control
acceleration은 이번 tick에, 새 controller output은 다음 tick에 적용한다. 동일 input과
callback 결과에서는 deterministic하며 result에 UNCERTAIN bounded flag를 기록한다.
out_state may exactly alias state. 다른 storage overlap은 금지한다. Cancel callback은
호출 thread에서 subsystem 경계와 하위 kernel에서 동기 호출되고 보관되지 않는다. 모든
validation, cancellation과 subsystem 실패는 atomic하며 음수 상태에서 두 output을 보존한다.
- Math Engine ownership:
config=borrowed state=borrowed context=borrowed out_state=caller out_result=caller - Math Engine nullable:
config=false state=false context=false out_state=false out_result=false - Math Engine thread_safety:
conditional
MATH_ENGINE_API math_engine_status_t math_engine_game_fast_tick_f64(
const math_engine_game_fast_tick_config_f64_t* config,
const math_engine_game_fast_tick_state_f64_t* state,
const math_engine_context_t* context,
math_engine_game_fast_tick_state_f64_t* out_state,
math_engine_game_fast_tick_result_f64_t* out_result);