ghost

1. Overview

ghost는 Grap 시스템에서 플랫폼 상호작용을 담당하는 라이브러리 계층이다.

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

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

ghost는 엔진 개념 레이어(gcore)와 운영체제 사이의 인터페이스 계층으로 동작한다.

이 계층은 플랫폼 API를 직접 사용하는 코드를 격리하여
엔진 레이어가 플랫폼에 의존하지 않도록 설계되어 있다.

2. Layer Position

Ghost는 Grap 시스템에서 다음 계층 구조에 위치한다.

Application
   ▲
   │
ginter
   ▲
   │
ghost
   ▲
   │
gcore
   ▲
   │
gbase

각 계층 역할

Layer	Responsibility
Application	애플리케이션 로직
ginter	플랫폼 이벤트 → 엔진 이벤트 변환
ghost	OS 시스템 인터페이스
gcore	엔진 개념 모델
gbase	기본 유틸리티

3. Responsibilities

ghost는 다음 기능을 제공한다.

Feature	Description
Window System	OS 창 생성 및 관리
Event System	OS 이벤트 수집
CPU Surface	CPU Writable Surface 제공
Clock	플랫폼 시간 제공

Ghost는 플랫폼 API wrapper 역할만 수행하며
엔진 로직이나 UI 시스템을 포함하지 않는다.

4. Non-Responsibilities

다음 기능은 Ghost의 책임 범위에 포함되지 않는다.

Feature	Reason
Rendering Pipeline	렌더 시스템은 별도 모듈
UI System	UI 시스템은 상위 레이어
Event Interpretation	이벤트 의미 해석은 ginter
Application Logic	애플리케이션 레이어 책임

Ghost는 플랫폼 기능만 제공하는 최소 인터페이스를 유지한다.

5. Module Structure

Ghost는 다음 모듈로 구성된다.

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

각 모듈 역할

Module	Responsibility
common	공통 타입 및 설정
id	객체 식별 타입
window	Window API
time	플랫폼 시간 API
native_event	OS 이벤트 데이터
platform	플랫폼 구현

6. Directory Layout

Ghost 디렉토리 구조

ghost/
 ├─ CMakeLists.txt
 ├─ ghost.hpp
 │
 ├─ common/
 ├─ id/
 ├─ window/
 ├─ time/
 ├─ native_event/
 │
 ├─ platform/
 │   └─ win32/
 │
 └─ tests/

플랫폼 구현은 platform 디렉토리에 위치한다.

7. Public API Access

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

예

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

Ghost는 모든 Public API를 포함하는 umbrella header를 제공한다.

#include <ghost/ghost.hpp>

8. Platform Abstraction

Ghost는 플랫폼 구현을 Public API로부터 분리한다.

Public API

ghost/window/window.hpp
ghost/native_event/native_event.hpp
ghost/time/clock.hpp

플랫폼 구현

ghost/platform/win32

이 구조는 플랫폼 코드가 엔진 시스템에 직접 노출되는 것을 방지한다.

9. Event Model

Ghost는 Raw Event Model을 사용한다.

플랫폼 이벤트는 의미 해석 없이 전달된다.

예

Field	Description
keycode_raw	플랫폼 키 코드
button_raw	플랫폼 버튼 코드
mouse_x	마우스 위치
mouse_y	마우스 위치

이벤트 의미 해석은 ginter 레이어에서 수행된다.

10. Resource Management

Ghost 시스템은 명시적인 리소스 관리 방식을 사용한다.

Window 관리 예

auto result = ghost::Window::create(desc);

ghost::Window window = std::move(result.value());

window.destroy();

Surface 관리 예

auto surface = window.acquire_cpu_surface();

window.release_cpu_surface();

이 구조는 플랫폼 리소스 수명을 명확하게 관리하기 위해 사용된다.

11. Platform Implementation

Ghost는 플랫폼 backend 구조를 사용한다.

현재 구현

platform/win32

주요 구현 파일

win32_window.cpp
win32_wndproc.cpp
win32_surface.cpp
win32_native_event.cpp
win32_clock.cpp

이 구현은 OS API를 직접 호출한다.

12. Design Principles

Ghost는 다음 설계 원칙을 따른다.

Principle	Description
Platform Isolation	플랫폼 코드 분리
Minimal Interface	최소 플랫폼 기능
Raw Event Model	의미 해석 없는 이벤트 전달
Explicit Resource Management	명시적 리소스 관리
Modular Architecture	모듈 기반 구조

13. Summary

ghost는 Grap 시스템에서 운영체제와 상호작용하는 플랫폼 인터페이스 계층이다.

이 라이브러리는 다음 목표를 가진다.

플랫폼 의존 코드 격리
엔진 레이어 보호
최소 플랫폼 인터페이스 제공
확장 가능한 플랫폼 구조

Ghost는 엔진 시스템이 운영체제에 직접 의존하지 않도록 하는 핵심 인프라 레이어이다.

1. Overview​