Shader Common Library Consolidation & SystemCodeManager Refactoring

[redcamel]

📝 Problem Description

현재 RedGPU 엔진의 WGSL 셰이더 코드 전반에 linearDepth, hash, colorSpace 변환 등 공통적으로 사용되는 함수들이 여러 파일에 중복 정의되어 있거나, 미세하게 다른 버전으로 산재해 있습니다. 이는 코드의 일관성을 저해하고 유지보수의 어려움을 초래하며, 대규모 시스템(SkyAtmosphere, TAA 등) 구현 시 수치적 정밀도 불일치를 야기합니다.

🎯 Goals

1. 중복 로직 제거: 파편화된 공통 함수들을 단일 라이브러리로 통합.
2. 수치 안정성 표준화: 검증된 최적화/안정화 로직(예: Linear Depth)을 엔진 전역에 강제 적용.
3. 아키텍처 현대화: 타입 추론과 문서화가 용이한 계층적 관리 시스템 구축.

🛠 Proposed Changes

1. SystemCodeManager 도입 (Architecture Refactoring)

• Static Registry: 기존의 단순 객체 방식을 폐기하고, 모든 프로퍼티와 메서드가 static으로 정의된 SystemCodeManager 클래스로 전환합니다.
• Hierarchical Namespace: SystemCodeManager.category.function 형태의 계층적 접근을 지원하여 완벽한 타입 추론과 IDE 인텔리센스 기능을 제공합니다.
• Implementation Example:

  export default class SystemCodeManager {
      static readonly math = {
          hash11: hash11_wgsl,
          hash33: hash33_wgsl,
      } as const;
      static readonly color = {
          get_luminance: get_luminance_wgsl,
      } as const;
  }

2. 폴더 구조 및 인클루드 시스템 개선

• Atomic Chunk Structure: 각 함수는 도메인별 폴더 내에 개별 WGSL 파일로 관리됩니다.

  src/systemCodeManager/
  ├── SystemCodeManager.ts
  └── shader/
      ├── math/ (hash11.wgsl, hash12.wgsl...)
      ├── color/ (rgb_to_ycocg.wgsl, get_luminance.wgsl...)
      └── depth/ (linearizeDepth.wgsl...)
  

• Dot-Notation Include: #redgpu_include color.get_luminance와 같이 계층 구조를 반영한 점 표기법 인클루드를 지원하도록 전처리 로직을 개선합니다.

3. 표준화 대상 후보 (Priority Candidates)

• Math: hash12, hash22, hash33, noise 함수 통합.
• Color: 휘도(Luminance) 계수 표준화 (Rec. 709), YCoCg 변환 로직 통합.
• Depth: 안정화된 linearizeDepth 적용 및 고정밀 reconstructWorldPosition 표준화.

✅ Acceptance Criteria

• SystemCodeManager 클래스 구현 및 기존 SystemCode 대체.
• 도메인별 계층적 폴더 구조 및 WGSL 원자적 분리 완료.
• #redgpu_include 점 표기법 지원 확인.
• TAA, SkyAtmosphere 등 주요 시스템의 중복 로직 리팩토링 및 정상 동작 확인.
• TypeDoc을 통한 셰이더 청크 문서화 정상 출력 확인.

📊 Expected Impact

• 셰이더 코드량 감소 및 유지보수 편의성 비약적 향상.
• 엔진 전역의 수치 연산 결과(깊이, 휘도 등) 일관성 확보.
• 신규 기능 개발 시 기초 그래픽스 인프라 활용도 제고.

---

Priority: 🔴 High
Target Version: V4.1.0-Alpha