ginter
Software Design Specification (SDS)
1. Overview
ginter는 Grap 엔진 아키텍처에서 이벤트 브릿지 레이어(Event Bridge Layer) 역할을 수행하는 모듈이다.
이 모듈은 ghost 시스템에서 제공되는 Native Event를
gcore 시스템에서 사용하는 Engine Event로 변환하고 전달한다.
이벤트 흐름은 다음과 같다.
ghost → ginter → gcore
ginter는 다음 두 구성 요소로 이루어진다.
- convert
- pump
2. Design Goals
ginter 모듈의 설계 목표는 다음과 같다.
- Native Event와 Engine Event 사이의 명확한 인터페이스 제공
- 이벤트 변환 로직과 이벤트 처리 루프의 분리
- 플랫폼 이벤트 시스템과 엔진 이벤트 시스템의 결합도 최소화
3. Module Architecture
ginter 모듈은 다음 두 하위 모듈로 구성된다.
ginter
├─ convert
└ ─ pump
각 모듈의 역할은 다음과 같다.
| Module | Responsibility |
|---|---|
| convert | Native Event → Engine Event 변환 |
| pump | Native Event 수집 및 Event Bus 전달 |
4. Component Design
4.1 convert Module
convert 모듈은 이벤트 변환 로직을 담당한다.
주요 구성 요소
- KeycodeMap
- ConvertContext
- ConvertOptions
- native_to_gcore_event
Event Conversion
Native Event 변환은 다음 API를 통해 수행된다.
std::optional<gcore::Event>
native_to_gcore_event(
const ghost::NativeEvent&,
const ConvertContext&
)
이 함수는 Native Event 타입에 따라 Engine Event를 생성한다.
4.2 pump Module
pump 모듈은 Native Event를 읽어 Event Bus로 전달하는 기능을 제공한다.
주요 구성 요소
- EventPump
- PumpResult
EventPump는 Window에서 Native Event를 수집하고 convert 모듈을 이용하여 Engine Event를 생성한다.
Event Pump API
PumpResult pump(
ghost::Window& window,
BusLike& bus,
const KeycodeMap& keymap,
uint64_t frame_index,
ConvertOptions opt
) const
5. Data Structures
5.1 ConvertContext
ConvertContext는 이벤트 변환에 필요한 실행 정보를 포함한다.
| Field | Type | Description |
|---|---|---|
| keymap | KeycodeMap* | 키코드 변환 객체 |
| window_id | gcore::WindowId | 이벤트 발생 Window |
| frame_index | uint64_t | 현재 프레임 |
| next_event_id | uint64_t | 다음 Event ID |
| opt | ConvertOptions | 변환 옵션 |
5.2 ConvertOptions
ConvertOptions는 이벤트 변환 정책을 정의한다.
현재 옵션
drop_unknown_events
이 옵션이 활성화된 경우 Unknown KeyCode 또는 Unknown Mouse Button 이벤트는 변환되지 않는다.
6. Event Flow
이벤트 처리 흐름은 다음과 같다.
ghost::Window
↓
Native Event
↓
EventPump
↓
native_to_gcore_event
↓
gcore::Event
↓
Event Bus
7. Error Handling
다음 경우 이벤트 변환은 수행되지 않는다.
- NativeEventType::None
- KeycodeMap 미설정
- Unknown KeyCode
- Unknown Mouse Button
이 경우 변환 함수는 다음 값을 반환한다.
std::nullopt
8. Dependencies
ginter 모듈은 다음 모듈에 의존한다.
| Module | Description |
|---|---|
| ghost | Native Event 및 Window 제공 |
| gcore | Engine Event 시스템 |
| gbase | 기본 타입 및 유틸리티 |
9. Extension Points
향후 확장을 위해 다음 영역이 고려될 수 있다.
- 추가 입력 이벤트 타입 지원
- 플랫폼별 KeycodeMap 확장
- Event Pump 정책 확장
본 문서는 현재 코드 기준 설계를 설명하며 실제 구현된 구성 요소만을 기반으로 작성되었다.