Skip to main content

API

1. Overview​

본 문서는 gmath 라이브러리의 Public API 구조를 정의한다.

gmath는 수학 타입과 수학 연산을 제공하는 header-only 수학 라이브러리이며,
라이브러리의 기능은 모듈 기반 Public API 구조를 통해 제공된다.

API는 다음 수학 도메인으로 구성된다.

  • scalar
  • vec
  • mat
  • numeric
  • geom

각 API는 해당 모듈의 umbrella header를 통해 접근할 수 있다.

2. Public API Entry​

gmath 라이브러리는 단일 umbrella header를 통해 전체 API를 제공한다.

#include <gmath/gmath.hpp>

이 헤더는 라이브러리의 모든 공개 모듈을 포함한다.

config
meta
scalar
vec
mat
numeric
geom

사용자는 단일 헤더를 포함하여 전체 API에 접근할 수 있다.

3. Module API Structure​

각 모듈은 모듈 단위 umbrella header를 제공한다.

#include <gmath/scalar/scalar.hpp>
#include <gmath/vec/vec.hpp>
#include <gmath/mat/mat.hpp>
#include <gmath/numeric/numeric.hpp>
#include <gmath/geom/geom.hpp>

모듈 umbrella header는 내부 헤더를 포함하여 해당 모듈의 기능을 제공한다.

4. API Design Model​

gmath의 API는 다음 설계 모델을 따른다.

4.1 Header-only API​

모든 API는 헤더 파일을 통해 제공된다.

특징

  • 별도의 링크 단계 없음
  • 컴파일 타임 인라이닝 가능
  • 단일 include 방식 사용 가능

4.2 Free Function Interface​

수학 연산은 free function 방식으로 제공된다.

예

add(a, b)
dot(a, b)
normalize(v)

이 방식은 다음 장점을 제공한다.

  • 타입 구조 단순화
  • 함수 확장 용이성
  • SIMD 확장 가능성

4.3 Arithmetic vs Storage Types​

API는 연산 타입과 저장 타입을 분리한다.

Arithmetic 타입

Vec2
Vec3
Vec4
Mat3
Mat4

Storage 타입

PackedVec2
PackedVec3
PackedVec4

Packed 타입은 데이터 저장 목적으로만 사용된다.

5. API Namespace​

gmath 라이브러리의 모든 API는 다음 namespace에 정의된다.

namespace gmath

이 namespace는 다음 요소를 포함한다.

  • 수학 타입
  • 수학 함수
  • 기하 타입
  • 기하 쿼리

6. API Access Model​

사용자는 다음 방식으로 API를 사용할 수 있다.

전체 API 사용​

#include <gmath/gmath.hpp>

모듈 단위 API 사용​

#include <gmath/vec/vec.hpp>
#include <gmath/mat/mat.hpp>

이 방식은 필요한 기능만 선택적으로 사용할 수 있도록 한다.

7. API Scope​

gmath API는 다음 기능을 제공한다.

  • 수학 타입
  • 수학 연산
  • 수치 계산 helper
  • 기하 계산 기능

다음 기능은 API 범위에 포함되지 않는다.

  • Scene 시스템
  • Transform 시스템
  • Rendering pipeline
  • 플랫폼 인터페이스

이러한 기능은 상위 엔진 모듈에서 제공된다.