ginter API Reference
Overview
본 문서는 ginter 모듈에서 제공하는 Public API를 설명한다.
ginter는 다음 기능을 제공한다.
- Keycode 매핑
- Native Event → Engine Event 변환
- Native Event 처리(Event Pump)
외부 코드에서는 다음 헤더를 포함하여 ginter API를 사용할 수 있다.
#include <ginter/ginter.hpp>
KeycodeMap
Description
KeycodeMap은 플랫폼 키코드를 gcore::KeyCode로 변환하는 매핑 객체이다.
Native Event의 raw keycode 값을 엔진 내부 KeyCode로 변환할 때 사용된다.
Factory Function
make_win32_default
Signature
KeycodeMap make_win32_default()
Description
Win32 플랫폼 기준 기본 키코드 매핑 테이블을 생성한다.
Key Mapping
map
Signature
gcore::KeyCode map(uint32_t keycode_raw) const
Parameters
| Parameter | Type | Description |
|---|---|---|
| keycode_raw | uint32_t | Native Keycode 값 |
Return Value
| Type | Description |
|---|---|
| gcore::KeyCode | 변환된 엔진 키코드 |
ConvertContext
Description
ConvertContext는 Native Event를 Engine Event로 변환할 때 필요한 실행 정보를 제공한다.
Fields
| Field | Type | Description |
|---|---|---|
| keymap | KeycodeMap* | 키코드 매핑 객체 |
| window_id | gcore::WindowId | 이벤트 발생 Window |
| frame_index | uint64_t | 현재 프레임 인덱스 |
| next_event_id | uint64_t | 다음 Event ID |
| opt | ConvertOptions | 이벤트 변환 옵션 |
ConvertOptions
Description
이벤트 변환 동작을 제어하는 옵션 구조체이다.
Fields
| Field | Description |
|---|---|
| drop_unknown_events | Unknown 이벤트 필터링 여부 |
native_to_gcore_event
Description
Native Event를 Engine Event로 변환한다.
Signature
std::optional<gcore::Event>
native_to_gcore_event(
const ghost::NativeEvent& e,
const ConvertContext& ctx
)
Parameters
| Parameter | Type | Description |
|---|---|---|
| e | ghost::NativeEvent | Native 입력 이벤트 |
| ctx | ConvertContext | 이벤트 변환 컨텍스트 |
Return Value
| Type | Description |
|---|---|
std::optional<gcore::Event> | 변환된 이벤트 |
변환할 수 없는 이벤트의 경우 std::nullopt가 반환된다.
advance_event_id
Description
ConvertContext의 Event ID를 증가시킨 새로운 Context를 반환한다.
Signature
ConvertContext advance_event_id(const ConvertContext& ctx)
Parameters
| Parameter | Type | Description |
|---|---|---|
| ctx | ConvertContext | 기존 ConvertContext |
Return Value
| Type | Description |
|---|---|
| ConvertContext | EventId가 증가된 새로운 Context |
EventPump
Description
Native Event를 수집하고 Engine Event로 전달하는 Event Pump 객체이다.
EventPump는 ghost::Window에서 Native Event를 읽고 convert 모듈을 통해 이벤트를 변환한 후 Event Bus로 전달한다.
pump
Signature
PumpResult pump(
ghost::Window& window,
BusLike& bus,
const KeycodeMap& keymap,
uint64_t frame_index,
ConvertOptions opt
) const
Parameters
| Parameter | Type | Description |
|---|---|---|
| window | ghost::Window | Native Event를 제공하는 Window |
| bus | BusLike | Event Bus 객체 |
| keymap | KeycodeMap | 키코드 변환 객체 |
| frame_index | uint64_t | 현재 프레임 인덱스 |
| opt | ConvertOptions | 이벤트 변환 옵션 |
Return Value
| Type | Description |
|---|---|
| PumpResult | EventPump 실행 결과 |
Event Bus Contract
EventPump는 BusLike 타입을 통해 Event Bus와 통신한다.
BusLike는 다음 인터페이스를 제공해야 한다.
push(const gcore::Event&)
Return Type
bool
EventPump는 변환된 Engine Event를 이 인터페이스를 통해 전달한다.