VavCore & Godot 통합 아키텍처 설계

1. 개요

이 문서는 기존 Windows 전용 Vav2Player 프로젝트를 확장하여, VavCore 라이브러리를 크로스-플랫폼(Windows, Android, iOS)으로 지원하고, 이를 Godot 엔진 4.4.1에서 사용할 수 있는 C# 익스텐션(Addon)으로 개발하기 위한 아키텍처 및 디렉토리 구조를 설계하는 것을 목표로 한다.

2. 핵심 목표

코드 재사용 극대화: C++로 작성된 핵심 디코딩 로직을 모든 플랫폼에서 공유한다.
플랫폼별 빌드 분리: 각 플랫폼(Windows, Android, iOS)에 맞는 빌드 환경을 명확히 분리하여 관리한다.
재사용 가능한 애드온: Godot의 표준 애드온 시스템을 통해 어떤 Godot 프로젝트에서든 쉽게 비디오 플레이어 기능을 추가할 수 있도록 한다.
기존 프로젝트 유지: 현재의 Vav2Player 프로젝트 구조와 기능에 영향을 주지 않는다.

3. 개발 디렉토리 구조

프로젝트의 확장성과 유지보수성을 위해 다음과 같은 디렉토리 구조를 제안한다.

D:\Project\video-av1\
└── vav2/
    ├── Vav2Player/               # (유지) 기존 Windows용 WinUI 3 플레이어
    │   ├── Vav2Player.sln
    │   └── ...
    │
    ├── VavCore/                  # ✅ (완료) 모든 플랫폼이 공유하는 핵심 C++ 소스
    │   ├── include/              # 외부 노출용 C API 헤더
    │   │   └── VavCore/VavCore.h
    │   └── src/                  # 공용 C++ 소스 코드
    │       ├── Common/
    │       ├── Decoder/          # AndroidMediaCodecAV1Decoder 포함
    │       └── FileIO/
    │
    ├── Vav2Player_Android/       # 🆕 Android 전용 애플리케이션 프로젝트
    │   ├── app/                  # 메인 애플리케이션 모듈
    │   │   ├── build.gradle
    │   │   └── src/
    │   │       ├── main/
    │   │       │   ├── java/com/vav2/player/
    │   │       │   │   ├── MainActivity.java          # 메인 테스트 액티비티
    │   │       │   │   ├── VavCoreTestActivity.java   # VavCore 기능 테스트
    │   │       │   │   ├── VideoPlayerActivity.java   # 실제 비디오 플레이어
    │   │       │   │   └── MediaCodecTestActivity.java # MediaCodec 전용 테스트
    │   │       │   ├── cpp/
    │   │       │   │   ├── native-lib.cpp             # JNI 브릿지
    │   │       │   │   └── CMakeLists.txt             # VavCore 통합
    │   │       │   ├── res/layout/                    # UI 레이아웃들
    │   │       │   └── AndroidManifest.xml
    │   │       ├── test/                              # 유닛 테스트
    │   │       │   └── java/com/vav2/player/
    │   │       │       ├── VavCoreUnitTest.java
    │   │       │       └── MediaCodecTest.java
    │   │       └── androidTest/                       # 인스트루먼트 테스트
    │   │           └── java/com/vav2/player/
    │   │               └── VavCoreIntegrationTest.java
    │   ├── vavcore/              # VavCore 라이브러리 모듈
    │   │   ├── build.gradle
    │   │   └── src/main/
    │   │       ├── cpp/CMakeLists.txt                 # VavCore 소스 빌드
    │   │       └── java/com/vavcore/VavCore.java      # JNI 인터페이스
    │   ├── build.gradle          # 프로젝트 레벨 빌드 설정
    │   ├── settings.gradle
    │   └── gradle.properties
    │
    ├── platforms/                # ✅ (부분완료) 플랫폼별 빌드 프로젝트 관리
    │   ├── windows/
    │   │   └── VavCore.vcxproj   # Windows용 .lib 빌드 프로젝트
    │   ├── android/              # ✅ MediaCodec 통합 완료
    │   │   ├── build.gradle      # Android 스튜디오 프로젝트
    │   │   ├── CMakeLists.txt    # Android용 .so 빌드용 CMake
    │   │   ├── libs/             # dav1d 라이브러리 (arm64-v8a, armeabi-v7a)
    │   │   └── src/android_test.cpp # 기본 테스트 코드
    │   └── ios/
    │       └── VavCore.xcodeproj # iOS용 .a 빌드용 Xcode 프로젝트
    │
    ├── platforms/                # ✅ 플랫폼별 구조로 개편 완료
    │   └── windows/
    │       ├── vavcore/          # VavCore Windows 라이브러리
    │       ├── godot-plugin/     # ✅ Godot Extension (완전 구현)
    │       │   ├── VavCoreGodot.sln   # C# 래퍼 및 Godot 노드용 솔루션
    │       │   ├── src/
    │       │   │   ├── VavCore.Wrapper/  # C# P/Invoke 래퍼 클래스
    │       │   │   └── VavCore.Godot/    # Godot 커스텀 노드 구현
    │       │   └── libs/windows-x86_64/  # Windows DLL들
    │       ├── applications/     # Windows 애플리케이션들
    │       └── tests/           # 테스트 프로젝트들
    │   ├── project.godot         # 익스텐션 테스트/개발용 Godot 프로젝트
    │   └── shaders/
    │       └── yuv_to_rgb.gdshader
    │
    └── libs_output/              # (예정) 빌드된 라이브러리 중앙 출력 폴더
        ├── windows/x64/
        │   └── VavCore.lib
        ├── android/arm64-v8a/
        │   └── libVavCore.so
        └── ios/
            └── libVavCore.a

3.1. 디렉토리별 상세 역할

vav2/VavCore/ ✅ (완료)
- 모든 플랫폼에서 재사용될 순수 C++ 디코딩 로직의 핵심부. 기존 Vav2Player/VavCore의 소스 코드를 이곳으로 이전하여 공용 자원으로 관리한다.
- include/VavCore/VavCore.h: C#에서 P/Invoke로 호출할 C API를 정의하는 인터페이스 헤더 파일이다.
- AndroidMediaCodecAV1Decoder: Android MediaCodec API를 통한 하드웨어 가속 AV1 디코딩 구현 완료
vav2/Vav2Player_Android/ 🆕 (신규 추가)
- 완전한 Android 애플리케이션: VavCore 기능을 테스트하고 실제 사용할 수 있는 독립적인 Android 앱
- 다양한 테스트 액티비티: MediaCodec 테스트, 성능 벤치마크, 실제 비디오 플레이어 등
- 포괄적인 테스트 환경: 유닛 테스트, 인스트루먼트 테스트, UI 테스트 모두 포함
- 실제 사용 시나리오 검증: Android 기기에서의 실제 성능과 호환성 검증 가능
vav2/platforms/ ✅ (부분 완료)
- 각 운영체제에 맞는 네이티브 라이브러리(.lib, .so, .a)를 빌드하기 위한 플랫폼별 프로젝트 파일을 관리한다.
- Android 플랫폼: MediaCodec 통합, dav1d 크로스 컴파일, CMake 빌드 시스템 완료
- 각 프로젝트는 vav2/VavCore/src의 공용 소스를 참조한다.
vav2/platforms/windows/godot-plugin/ ✅ (완료)
- Windows 전용 Godot 엔진 플러그인 개발 및 테스트 공간
- VavCore.Wrapper: Windows VavCore DLL의 C 함수를 호출하는 저수준 C# P/Invoke 코드 포함. 실제 VavCore C API에 맞춰 28개 함수로 단순화 완료
- VavCore.Godot: VavCore.Wrapper를 사용하여 Godot 에디터에서 사용할 수 있는 커스텀 노드(예: VavCorePlayerNode) 구현
- 플랫폼별 구조: Windows 특화 최적화 및 NVDEC/VPL/AMF 하드웨어 가속 지원
- API 설계 철학: 작고 간편한 player-centric 디자인으로 기술부채 최소화
vav2/libs_output/ (예정)
- 각 플랫폼용으로 컴파일된 최종 라이브러리 파일들이 저장되는 중앙 출력 위치. Godot C# 프로젝트에서 이 폴더의 바이너리를 참조하여 관리를 용이하게 한다.

4. Godot 애드온 배포 및 사용

vav2/platforms/windows/godot-plugin에서 개발된 결과물은 다른 Godot 프로젝트에서 쉽게 사용할 수 있는 '애드온' 형태로 배포된다.

4.1. 소비자 프로젝트 예시 (`GodotPlayer`)

새로운 게임 프로젝트 GodotPlayer에서 VavCore 비디오 재생 기능을 사용하는 경우의 디렉토리 구조는 다음과 같다.

D:\MyGames\GodotPlayer\
├── project.godot               # GodotPlayer 게임의 메인 프로젝트 파일
├── main.tscn                   # 게임의 메인 씬
├── icon.svg
└── addons\                     # Godot의 애드온을 저장하는 표준 폴더
    └── VavCoreGodot\           <-- (복사해 온 애드온 폴더)
        ├── plugin.cfg          # Godot에 이 폴더가 애드온임을 알리는 설정 파일
        ├── VavCore.Wrapper/    # C# P/Invoke 래퍼 소스 코드
        ├── VavCore.Godot/      # C# 커스텀 노드 소스 코드
        └── libs/               # 미리 컴파일된 네이티브 라이브러리들
            ├── windows-x86_64/
            │   └── VavCore.dll
            ├── android-arm64/
            │   └── libVavCore.so
            └── ios-arm64/
                └── libVavCore.a

4.2. 사용 절차

애드온 복사: 개발된 VavCoreGodot 애드온 폴더 전체를 GodotPlayer 프로젝트 내의 addons 폴더로 복사한다.
애드온 활성화: Godot 에디터에서 GodotPlayer 프로젝트를 연 뒤, 프로젝트 -> 프로젝트 설정 -> 플러그인 탭에서 VavCoreGodot 플러그인을 '활성' 상태로 변경한다.
노드 사용: '씬에 노드 추가' 메뉴에서 직접 만든 커스텀 비디오 플레이어 노드를 검색하여 씬에 추가하고 사용한다.

5. 개발 현황 및 다음 단계

5.1. 완료된 작업 ✅

VavCore 크로스 플랫폼 아키텍처: Windows/Android 공통 코드베이스 구축
Android MediaCodec 통합: 하드웨어 가속 AV1 디코딩 완전 구현
VideoDecoderFactory: 플랫폼별 디코더 자동 선택 시스템
dav1d Android 빌드: ARM64/ARM32 크로스 컴파일 완료
CMake 빌드 시스템: Android NDK 통합 및 라이브러리 빌드
platforms/android/godot-plugin: Godot 4.4.1 Android 네이티브 플러그인 완료
platforms/windows/godot-plugin C# wrapper: VavCore C API 기반 P/Invoke 레이어 완료
API 설계 단순화: 70+ 함수에서 28개 vavcore_* 함수로 축소

5.2. 현재 진행 중 🔄

Godot C# 익스텐션: C# wrapper 및 Godot 노드 구현
- VavCore C API 기반 P/Invoke 래퍼 완료 (28개 함수)
- Godot 커스텀 노드 및 리소스 시스템 구현
- 크로스 플랫폼 Surface 지원 및 GPU 렌더링 통합

5.3. 다음 단계 계획 📋

VavCore C API 구현체 완성 (우선순위 1)
- 28개 vavcore_* 함수의 실제 구현
- 기존 VavCore C++ 클래스들과 C API 연결
- 크로스 플랫폼 Surface 지원 완성
C# 익스텐션 빌드 및 테스트 (우선순위 2)
- .NET 6.0 프로젝트 빌드 검증
- Godot 4.4.1 프로젝트 통합 테스트
- 실제 AV1 비디오 재생 검증
iOS 지원 (우선순위 3)
- iOS 플랫폼별 빌드 시스템
- VideoToolbox 하드웨어 가속 통합

6. 기대 효과

모듈성 및 재사용성: 핵심 디코딩 기능이 VavCore 라이브러리로 캡슐화되어 어떤 프로젝트에서든 재사용할 수 있다.
하드웨어 가속 최적화: 각 플랫폼의 네이티브 하드웨어 가속을 최대한 활용
실제 검증 환경: Vav2Player_Android를 통한 실제 사용 시나리오 검증
유지보수의 용이성: C++ 핵심 로직, 플랫폼별 빌드, 테스트 환경이 명확히 분리
안정적인 개발: 기존 Vav2Player에 영향을 주지 않으면서 새로운 플랫폼과 Godot 지원을 추가할 수 있다.

12 KiB Raw Blame History