Ghost Architecture

1. Layer Position

ghost는 Grap 엔진에서 플랫폼 추상화 계층(Platform Abstraction Layer) 을 제공하는 라이브러리이다.

이 모듈은 운영체제 API와 직접 통신하여 다음 기능을 제공한다.

Window 생성 및 관리
OS 이벤트 수집
CPU Writable Surface 제공
플랫폼 시간 측정

ghost는 엔진 개념을 정의하지 않는다.

이벤트 의미 해석, 키 매핑, 엔진 이벤트 생성은
상위 계층인 ginter에서 수행된다.

시스템 레이어 구조

Application
   ▲
   │
ginter
(Event Interpretation)
   ▲
   │
ghost
(Platform Layer)
   ▲
   │
Operating System
(Win32)

레이어 역할

Layer	Responsibility
Application	애플리케이션 로직
ginter	NativeEvent → 엔진 이벤트 변환
ghost	플랫폼 시스템 인터페이스
OS	운영체제 API

2. Internal Modules

ghost는 다음 서브시스템으로 구성된다.

ghost
 ├─ common
 ├─ id
 ├─ window
 ├─ time
 ├─ native_event
 └─ platform

각 모듈은 플랫폼 기능을 분리된 형태로 제공한다.

common

공통 설정 제공
Result 타입 정의
공용 설정 인터페이스 제공

id

Window 식별자 타입 정의
Handle 기반 객체 식별 구조 제공

window

Window 생성 및 파괴
Window 상태 조회
이벤트 접근 인터페이스
CPU Writable Surface 접근
화면 출력 기능

time

플랫폼 시간 측정 기능 제공
monotonic clock 인터페이스 제공

native_event

플랫폼 이벤트 데이터 구조 정의
OS 이벤트 저장 구조 제공
NativeEventQueue 이벤트 큐 제공

platform

운영체제 API 구현 계층
Window 시스템 구현
이벤트 변환 구현
CPU Surface 구현
Clock 구현

현재 구현된 플랫폼

platform/win32

3. Dependency Structure

ghost 내부 모듈은 다음 의존 구조를 따른다.

common
  ▲
  │
id
  ▲
  │
window
  ▲
  │
native_event
  ▲
  │
platform

time
 └─ (platform 구현)

의존 규칙

common은 최하위 모듈
id는 common에 의존 가능
window는 id 및 common에 의존 가능
native_event는 common에 의존 가능
platform은 모든 모듈 구현에 의존 가능
순환 의존성 금지

4. Header Architecture

Ghost는 Public Header 구조를 제공한다.

모든 Public API는 <ghost/...> 경로로 접근한다.

예

#include <ghost/window/window.hpp>
#include <ghost/native_event/native_event.hpp>
#include <ghost/time/clock.hpp>

Ghost는 umbrella header를 제공한다.

#include <ghost/ghost.hpp>

이 헤더는 Ghost Public API 전체를 포함한다.

5. Directory Layout

Ghost 디렉토리 구조

ghost/
 ├─ ghost.hpp
 │
 ├─ common/
 │  ├─ config.hpp
 │  └─ result.hpp
 │
 ├─ id/
 │  ├─ ids.hpp
 │  └─ handle.hpp
 │
 ├─ window/
 │  ├─ surface_types.hpp
 │  ├─ cpu_surface.hpp
 │  ├─ window_desc.hpp
 │  └─ window.hpp
 │
 ├─ time/
 │  ├─ clock_types.hpp
 │  └─ clock.hpp
 │
 ├─ native_event/
 │  ├─ native_event_types.hpp
 │  ├─ native_event_queue.hpp
 │  └─ native_event.hpp
 │
 └─ platform/
    └─ win32/
       ├─ win32_internal.hpp
       ├─ win32_state.hpp
       ├─ win32_window.cpp
       ├─ win32_wndproc.cpp
       ├─ win32_surface.cpp
       ├─ win32_native_event.cpp
       └─ win32_clock.cpp

6. Design Principles

Ghost 시스템은 다음 설계 원칙을 따른다.

Platform Isolation

플랫폼 의존 코드는 platform 모듈 내부에만 존재한다.

Public API는 Win32 타입을 노출하지 않는다.

예

Type	Visibility
HWND	platform only
HDC	platform only
HBITMAP	platform only

Minimal Interface

Ghost는 최소한의 플랫폼 기능만 제공한다.

제공 기능

Window
NativeEvent
Clock
CPU Surface

Raw Event Model

Ghost는 이벤트 의미를 해석하지 않는다.

예

keycode_raw
button_raw

이벤트 의미 해석은 상위 레이어에서 수행한다.

Platform Backend Separation

플랫폼 구현은 별도 backend 구조를 사용한다.

예

platform/win32
platform/linux
platform/macos

Explicit Resource Management

Window 및 Surface는 명시적인 수명 관리 방식을 사용한다.

예

Window::create()
Window::destroy()

Window::acquire_cpu_surface()
Window::release_cpu_surface()

7. System Interaction

Ghost 시스템의 데이터 흐름

Window 생성

Application
   │
   ▼
Window::create
   │
   ▼
platform/win32
   │
   ▼
CreateWindow (Win32)

Event Processing

Win32 Message
      │
      ▼
WndProc
      │
      ▼
NativeEvent 생성
      │
      ▼
NativeEventQueue 저장
      │
      ▼
Window::native_events()

Surface Rendering

Application
      │
      ▼
acquire_cpu_surface()
      │
      ▼
CPU pixel write
      │
      ▼
release_cpu_surface()
      │
      ▼
present()
      │
      ▼
Window 출력

8. Summary

Ghost는 Grap 엔진에서 플랫폼 시스템 인터페이스 계층을 제공하는 라이브러리이다.

주요 기능

Window 시스템
NativeEvent 시스템
CPU Writable Surface
플랫폼 시간 측정

Ghost는 엔진 개념을 포함하지 않으며
플랫폼 기능을 단순하고 독립적인 인터페이스로 제공하는 것을 목표로 한다.

1. Layer Position​

2. Internal Modules

common​

id​

window​

time​

native_event​

platform​