# VavCore AV1 Static Library - Revised Implementation Plan

## 📚 **라이브러리 개요**

### **VavCore**: Vav2Player 기반 AV1 디코딩 라이브러리
- **기반**: 검증된 Vav2Player 코드베이스에서 핵심 모듈 추출
- **목표**: Godot 엔진 통합을 위한 C API 제공
- **특징**: 적응형 품질 제어, 하드웨어 가속, 플랫폼 독립성

## 🏗️ **통합 아키텍처 설계**

### **Visual Studio 솔루션 구조**
```
Vav2Player.sln                      # 통합 솔루션
├── VavCore/                         # Static Library Project
│   ├── VavCore.vcxproj             # C API 라이브러리 프로젝트
│   ├── include/VavCore/
│   │   ├── VavCore.h               # C API 메인 헤더
│   │   ├── VideoTypes.h            # 데이터 구조체
│   │   └── IVideoDecoder.h         # 디코더 인터페이스
│   └── src/
│       ├── VavCore.cpp             # C API 구현
│       ├── Decoder/                # 디코더 모듈 (from Vav2Player)
│       │   ├── AV1Decoder.h/.cpp
│       │   ├── AdaptiveAV1Decoder.h/.cpp
│       │   ├── AdaptiveNVDECDecoder.h/.cpp
│       │   ├── NVDECAV1Decoder.h/.cpp
│       │   ├── MediaFoundationAV1Decoder.h/.cpp
│       │   └── VideoDecoderFactory.h/.cpp
│       ├── FileIO/                 # 파일 I/O 모듈
│       │   └── WebMFileReader.h/.cpp
│       └── Common/                 # 공통 유틸리티
│           └── [utility files]
├── Vav2Player/                      # WinUI3 GUI Application
│   ├── Vav2Player.vcxproj          # GUI 애플리케이션 프로젝트
│   └── src/                        # GUI 및 렌더링 전용
│       ├── UI/                     # WinUI3 관련 파일들
│       └── Rendering/              # D3D12 렌더링 파이프라인
├── Vav2PlayerHeadless/             # Console Test Application
│   ├── Vav2PlayerHeadless.vcxproj # 헤드리스 테스트 프로젝트
│   └── src/                        # VavCore 기반 콘솔 테스트
├── Vav2UnitTest/                   # Unit Test Project
│   ├── Vav2UnitTest.vcxproj        # 단위 테스트 프로젝트
│   └── tests/                      # VavCore 및 통합 테스트
└── README.md                       # 솔루션 전체 문서
```

### **프로젝트 역할 분리**

#### **VavCore (Static Library)**
- **순수 디코딩 라이브러리**: AV1 디코딩 전문
- **C API 제공**: 플랫폼 독립적 인터페이스
- **검증된 디코더들**: Vav2Player에서 이전한 모든 디코더
- **적응형 품질 제어**: 하드웨어 가속 및 성능 최적화

#### **Vav2Player (GUI Application)**
- **VavCore 소비자**: C API를 통한 디코딩 요청
- **WinUI3 GUI**: 사용자 인터페이스 및 컨트롤
- **D3D12 렌더링**: GPU 기반 비디오 렌더링
- **통합 테스트**: 실제 사용자 경험 검증

#### **Vav2PlayerHeadless (Console Application)**
- **VavCore 테스트**: 순수 디코딩 성능 벤치마킹
- **자동화 테스트**: CI/CD 파이프라인 통합
- **성능 측정**: 디코딩 전용 성능 분석

#### **Vav2UnitTest (Test Project)**
- **VavCore 단위 테스트**: 디코더별 개별 테스트
- **통합 테스트**: GUI와 헤드리스 모드 통합 검증
- **성능 회귀 테스트**: 버전별 성능 비교

## 🎯 **C API 설계 - Godot/C# 통합 최적화**

### **핵심 C API**
```cpp
// Library initialization
VAVCORE_API VavCoreResult vavcore_initialize(void);
VAVCORE_API void vavcore_cleanup(void);

// Player lifecycle
VAVCORE_API VavCorePlayer* vavcore_create_player(void);
VAVCORE_API void vavcore_destroy_player(VavCorePlayer* player);

// File operations
VAVCORE_API VavCoreResult vavcore_open_file(VavCorePlayer* player, const char* filepath);
VAVCORE_API VavCoreResult vavcore_decode_next_frame(VavCorePlayer* player, VavCoreVideoFrame* frame);

// Quality control (from adaptive decoders)
VAVCORE_API VavCoreResult vavcore_set_quality_mode(VavCorePlayer* player, VavCoreQualityMode mode);
VAVCORE_API VavCoreResult vavcore_get_performance_metrics(VavCorePlayer* player, VavCorePerformanceMetrics* metrics);
```

### **C# 래핑 라이브러리 설계 (인하우스 전용)**
```csharp
// VavCore.Wrapper - 내부 프로젝트용 C# 래퍼
namespace VavCore.Wrapper
{
    public static class VavCoreLibrary
    {
        [DllImport("VavCore.dll")]
        private static extern VavCoreResult vavcore_initialize();

        [DllImport("VavCore.dll")]
        private static extern IntPtr vavcore_create_player();

        [DllImport("VavCore.dll")]
        private static extern VavCoreResult vavcore_decode_next_frame(
            IntPtr player, out VavCoreVideoFrame frame);

        public static bool Initialize() =>
            vavcore_initialize() == VavCoreResult.Success;
    }

    public class VavCorePlayer : IDisposable
    {
        private IntPtr _playerHandle;

        public VavCorePlayer()
        {
            _playerHandle = VavCoreLibrary.vavcore_create_player();
        }

        public bool OpenFile(string filepath) =>
            VavCoreLibrary.vavcore_open_file(_playerHandle, filepath) == VavCoreResult.Success;

        public bool DecodeNextFrame(out VavCoreVideoFrame frame) =>
            VavCoreLibrary.vavcore_decode_next_frame(_playerHandle, out frame) == VavCoreResult.Success;

        // Godot 특화 메서드 - YUV 데이터 직접 제공
        public bool GetYUVFrameData(out VavCoreVideoFrame yuvFrame)
        {
            return DecodeNextFrame(out yuvFrame);
        }

        public void Dispose() => VavCoreLibrary.vavcore_destroy_player(_playerHandle);
    }
}
```

## 📦 **Godot 통합 전략**

### **렌더링 분리 설계 철학**
VavCore는 **디코딩 전용**으로 설계되어 Godot의 렌더링 시스템과 완벽하게 분리됩니다.

#### **VavCore 역할**: 디코딩 및 데이터 제공
- ✅ AV1 비디오 디코딩 (YUV 프레임 생성)
- ✅ 적응형 품질 제어
- ✅ 하드웨어 가속 디코딩
- ✅ C API를 통한 YUV 데이터 제공

#### **Godot 역할**: 렌더링 및 표시
- ✅ **YUV 텍스처 생성**: 3개 텍스처 (Y, U, V 플레인)로 GPU 업로드
- ✅ **GPU 셰이더 변환**: YUV → RGB 변환을 GPU 셰이더에서 실시간 처리
- ✅ **렌더링 파이프라인**: Godot 네이티브 렌더링 시스템 활용
- ✅ **UI 통합**: VideoStreamPlayer 또는 커스텀 Control 노드 사용
- ✅ **성능 최적화**: GPU 병렬 처리로 고성능 변환 및 렌더링

### **Vav2Player 렌더링 코드 활용 전략**

#### **직접 사용하지 않는 이유**
- ❌ **플랫폼 종속성**: D3D12/WinUI는 Godot과 호환 불가
- ❌ **아키텍처 충돌**: Godot 렌더링 시스템과 간섭
- ❌ **복잡성 증가**: 두 렌더링 파이프라인 동시 관리

#### **재활용 가능한 핵심 알고리즘 (참조용)**
```glsl
// Vav2Player SimpleGPURenderer에서 추출 가능한 렌더링 로직들
1. GPU 셰이더 YUV→RGB 변환 (BT.709 변환 매트릭스)
2. AspectFit 계산 로직 (비율 유지 렌더링)
3. YUV 텍스처 업로드 최적화 패턴
4. 프레임 버퍼링 및 동기화 전략

// Godot 셰이더 예시 (Vav2Player 로직 기반)
shader_type canvas_item;

uniform sampler2D y_texture : source_color;
uniform sampler2D u_texture : source_color;
uniform sampler2D v_texture : source_color;

void fragment() {
    float y = texture(y_texture, UV).r;
    float u = texture(u_texture, UV).r;
    float v = texture(v_texture, UV).r;

    // BT.709 YUV to RGB conversion (from SimpleGPURenderer)
    y = (y - 16.0/255.0) * 255.0/(235.0-16.0);
    u = (u - 128.0/255.0);
    v = (v - 128.0/255.0);

    vec3 rgb;
    rgb.r = y + 1.5748 * v;
    rgb.g = y - 0.1873 * u - 0.4681 * v;
    rgb.b = y + 1.8556 * u;

    COLOR = vec4(rgb, 1.0);
}
```

### **단계별 Godot 통합 방안**

#### **Phase 1: 올바른 GPU 기반 통합 (권장 방식)**
```csharp
// VavCore YUV 데이터 → Godot GPU 텍스처 파이프라인
using Godot;
using VavCore.Net;

public partial class VideoPlayer : Control
{
    private VavCorePlayer _vavPlayer;
    private ShaderMaterial _yuvShaderMaterial;
    private TextureRect _videoDisplay;

    // YUV 텍스처들 (GPU 업로드용)
    private ImageTexture _yTexture, _uTexture, _vTexture;

    public override void _Ready()
    {
        VavCoreLibrary.Initialize();
        _vavPlayer = new VavCorePlayer();
        _vavPlayer.OpenFile("res://video.webm");

        // YUV to RGB 셰이더 로드
        var shader = GD.Load<Shader>("res://shaders/yuv_to_rgb.gdshader");
        _yuvShaderMaterial = new ShaderMaterial();
        _yuvShaderMaterial.Shader = shader;

        // VideoDisplay 설정
        _videoDisplay = GetNode<TextureRect>("VideoDisplay");
        _videoDisplay.Material = _yuvShaderMaterial;

        // YUV 텍스처 초기화
        _yTexture = new ImageTexture();
        _uTexture = new ImageTexture();
        _vTexture = new ImageTexture();
    }

    public override void _Process(double delta)
    {
        if (_vavPlayer.GetYUVFrameData(out var yuvFrame))
        {
            // Y, U, V 플레인을 각각 텍스처로 업로드
            UpdateYUVTextures(yuvFrame);

            // 셰이더에 YUV 텍스처 전달 (GPU에서 RGB 변환)
            _yuvShaderMaterial.SetShaderParameter("y_texture", _yTexture);
            _yuvShaderMaterial.SetShaderParameter("u_texture", _uTexture);
            _yuvShaderMaterial.SetShaderParameter("v_texture", _vTexture);
        }
    }

    private void UpdateYUVTextures(VavCoreVideoFrame yuvFrame)
    {
        // Y 플레인 (전체 해상도)
        var yImage = Image.CreateFromData(yuvFrame.Width, yuvFrame.Height,
                                         false, Image.Format.R8, yuvFrame.YPlaneData);
        _yTexture.SetImage(yImage);

        // U 플레인 (1/2 해상도)
        var uImage = Image.CreateFromData(yuvFrame.Width/2, yuvFrame.Height/2,
                                         false, Image.Format.R8, yuvFrame.UPlaneData);
        _uTexture.SetImage(uImage);

        // V 플레인 (1/2 해상도)
        var vImage = Image.CreateFromData(yuvFrame.Width/2, yuvFrame.Height/2,
                                         false, Image.Format.R8, yuvFrame.VPlaneData);
        _vTexture.SetImage(vImage);
    }
}
```

**✅ 핵심 장점**:
- **GPU 기반 변환**: YUV → RGB 변환이 GPU 셰이더에서 병렬 처리
- **메모리 효율성**: YUV 원본 데이터만 유지, RGB 중간 버퍼 불필요
- **고성능**: GPU 텍스처 업로드 + 실시간 셰이더 변환
- **Godot 네이티브**: Godot 렌더링 파이프라인과 완벽 통합

#### **Phase 2: 고급 최적화 (성능 극대화)**
```csharp
// 텍스처 풀링 및 멀티스레딩 최적화
public partial class AdvancedVideoPlayer : Control
{
    private VavCorePlayer _vavPlayer;
    private TexturePool _texturePool;
    private Task _decodingTask;

    // 백그라운드 디코딩 + 텍스처 스트리밍
    private async Task BackgroundDecoding()
    {
        while (_isPlaying)
        {
            if (_vavPlayer.GetYUVFrameData(out var yuvFrame))
            {
                // 텍스처 풀에서 재사용 가능한 텍스처 획득
                var textures = _texturePool.GetTextures(yuvFrame.Width, yuvFrame.Height);

                // 백그라운드 스레드에서 텍스처 업데이트
                await UpdateTexturesAsync(yuvFrame, textures);

                // 메인 스레드로 렌더링 큐 전달
                CallDeferred(nameof(ApplyTexturesToShader), textures);
            }
        }
    }
}
```

**✅ 고급 최적화 기법**:
- **텍스처 풀링**: 메모리 재할당 최소화 (Vav2Player FramePool 패턴)
- **비동기 디코딩**: UI 스레드 블로킹 방지
- **백그라운드 텍스처 업데이트**: GPU 업로드 병렬화
- **Zero-Copy 패턴**: 불필요한 메모리 복사 제거

### **렌더링 성능 최적화 전략**

#### **Vav2Player에서 승계할 최적화 기법**
1. **YUV→RGB 변환 최적화**:
   - BT.709 색공간 변환 매트릭스
   - SIMD 최적화된 변환 알고리즘

2. **AspectFit 계산**:
   - 비율 유지 렌더링 수식
   - UV 좌표 스케일링 로직

3. **메모리 최적화**:
   - 텍스처 풀링 시스템
   - Zero-Copy 버퍼 관리

4. **성능 모니터링**:
   - 프레임 드롭 감지
   - 렌더링 성능 메트릭

### **C# 중심 아키텍처 설계**

#### **인하우스 Godot 프로젝트 구조**
```
MyGodotProject/
├── VavCore/                        # Git 서브모듈 (from Vav2Player Solution)
│   ├── include/VavCore/VavCore.h   # C API 헤더
│   ├── lib/
│   │   ├── VavCore.lib             # Static library (Windows)
│   │   ├── libVavCore.a            # Static library (Linux)
│   │   └── libVavCore.a            # Static library (macOS)
│   └── src/                        # 전체 소스코드 (디버깅용)
├── Scripts/                        # Godot C# 스크립트들
│   ├── VavCore/
│   │   ├── VavCoreLibrary.cs       # P/Invoke 래퍼
│   │   ├── VavCorePlayer.cs        # 고수준 플레이어 API
│   │   ├── VavCoreTypes.cs         # 데이터 구조체
│   │   └── GodotVideoPlayer.cs     # Godot 특화 비디오 플레이어
│   └── Game/
│       └── VideoPlayerScene.cs     # 실제 게임에서 사용
└── project.godot                   # Godot 프로젝트 파일

# VavCore는 Vav2Player 솔루션의 서브모듈로 관리됨
```

### **통합 개발 워크플로우**

#### **단일 솔루션 개발 사이클**
1. **VavCore 수정**: Vav2Player 솔루션에서 디코더 개선
2. **Vav2Player 테스트**: GUI에서 즉시 성능/기능 검증
3. **헤드리스 벤치마킹**: 순수 디코딩 성능 측정
4. **Godot 프로젝트 업데이트**: Git 서브모듈 최신화
5. **통합 테스트**: 모든 플랫폼에서 일관된 성능 확인

#### **Godot C# 통합 예제**
```csharp
// 내부 Godot 프로젝트에서 사용
using Godot;
using VavCore.Wrapper;

public partial class GameVideoPlayer : Control
{
    private GodotVideoPlayer _videoPlayer;
    private TextureRect _videoDisplay;

    public override void _Ready()
    {
        _videoDisplay = GetNode<TextureRect>("VideoDisplay");
        _videoPlayer = new GodotVideoPlayer();

        // 적응형 품질 설정
        _videoPlayer.SetQualityMode(VavCoreQualityMode.Fast);
        _videoPlayer.OpenFile("res://cutscenes/intro.webm");
    }

    public override void _Process(double delta)
    {
        // 자동으로 ImageTexture 업데이트
        if (_videoPlayer.UpdateFrame())
        {
            _videoDisplay.Texture = _videoPlayer.CurrentTexture;
        }

        // 성능 모니터링
        var metrics = _videoPlayer.GetPerformanceMetrics();
        GD.Print($"FPS: {metrics.CurrentFps:F1}, Quality: {metrics.CurrentQualityLevel}");
    }
}
```

### **인하우스 배포 전략**
1. **Git 서브모듈** - VavCore를 서브모듈로 Godot 프로젝트에 포함
2. **로컬 라이브러리** - 빌드된 VavCore.dll을 프로젝트 디렉토리에 직접 배치
3. **C# 스크립트** - VavCore 래퍼 클래스들을 프로젝트 Scripts 폴더에 포함
4. **버전 관리** - 팀 내부 Git 저장소를 통한 버전 관리

## 🔧 **검증된 핵심 기능들**

### **적응형 품질 제어 (from Vav2Player)**
- ✅ **3단계 품질 모드**: CONSERVATIVE, FAST, ULTRA_FAST
- ✅ **실시간 성능 모니터링**: 30프레임 이동평균 기반
- ✅ **동적 해상도 조정**: 5%-100% 범위 스케일링
- ✅ **4K AV1 성능**: 27.7fps 달성 (ULTRA_FAST 모드)

### **하드웨어 가속 지원 (from Vav2Player)**
- ✅ **NVDEC**: NVIDIA GPU 하드웨어 디코딩
- ✅ **Media Foundation**: Intel QSV, AMD VCN 지원
- ✅ **자동 Fallback**: NVDEC → Media Foundation → dav1d
- ✅ **성능 검증**: 하드웨어 가속으로 2-3배 성능 향상

### **안정성 검증 (from Vav2Player)**
- ✅ **47개 단위 테스트** (95.7% 통과율)
- ✅ **메모리 관리**: RAII 패턴, 메모리 풀 최적화
- ✅ **에러 처리**: 완전한 예외 처리 및 복구 메커니즘

## ⚠️ **중요 설계 원칙: VavCore 역할 분리**

### **❌ 피해야 할 불필요한 기능들**

#### **YUV to RGB 변환 불필요**
**잘못된 접근**: VavCore에서 CPU 기반 YUV → RGB 변환 제공
- ❌ **성능 오버헤드**: CPU 변환으로 인한 불필요한 연산
- ❌ **메모리 낭비**: RGB 변환된 데이터 추가 저장
- ❌ **아키텍처 위반**: 렌더링 책임을 라이브러리가 담당

**올바른 접근**: 각 엔진에서 GPU 셰이더로 YUV → RGB 변환
- ✅ **VavCore 책임**: YUV420P 원본 데이터 제공
- ✅ **Godot 책임**: GPU 셰이더로 YUV → RGB 변환 + 렌더링
- ✅ **성능 최적화**: GPU 병렬 처리로 실시간 변환
- ✅ **메모리 효율성**: YUV 원본 데이터만 유지

**구체적 통합 시나리오**:
```cpp
// VavCore: YUV 데이터 제공
VavCoreVideoFrame frame;
vavcore_decode_next_frame(player, &frame);

// Godot: 3개의 텍스처로 GPU 업로드
auto y_texture = create_texture_from_data(frame.y_plane, frame.y_stride, frame.height);
auto u_texture = create_texture_from_data(frame.u_plane, frame.u_stride, frame.height/2);
auto v_texture = create_texture_from_data(frame.v_plane, frame.v_stride, frame.height/2);

// Godot 셰이더: GPU에서 YUV → RGB 변환
// shader: "YUV_to_RGB.gdshader" 사용
```

**핵심 교훈**:
- **VavCore**: 디코딩 전문 라이브러리
- **게임 엔진**: 렌더링 전문 시스템
- **역할 분리**: 각자 전문 영역에서 최적화

## 🚀 **실제 구현 로드맵**

### **✅ Phase 1: 핵심 모듈 추출 완료**
- [x] Vav2Player에서 검증된 디코더 모듈들 복사
- [x] WebMFileReader, VideoDecoderFactory 이전
- [x] VideoTypes.h, IVideoDecoder.h 인터페이스 추출
- [x] 디렉토리 구조 생성 및 파일 정리

### **✅ Phase 2: C API 구현 완료**
- [x] VavCore.h C API 헤더 설계
- [x] VavCore.cpp C API 구현체 작성
- [x] Godot/C# 호환 데이터 구조체 정의
- [x] 에러 처리 및 메모리 관리 API

### **✅ Phase 3: VavCore Visual Studio 프로젝트 생성 완료**
- [x] **VavCore.vcxproj** 생성 (Static Library)
- [x] **Vav2Player 솔루션에 추가** 및 프로젝트 참조 설정
- [x] **기존 디코더 코드** VavCore 프로젝트로 이전
- [x] **C API 헤더 및 구현** 완성
- [x] **Common 유틸리티** 추가 (D3D12Helpers.h)
- [x] **빌드 성공** VavCore.lib 생성 확인

### **📋 Phase 4: Vav2Player 리팩토링 (다음 단계)**
1. **Vav2Player를 VavCore 소비자로 전환**
2. **기존 디코더 직접 호출** → **VavCore C API 호출**
3. **중복 코드 제거** 및 렌더링 전용 코드만 유지
4. **성능 동등성 검증** (리팩토링 전후 비교)

### **📋 Phase 5: 헤드리스 프로젝트 통합 (다음 단계)**
1. **Vav2PlayerHeadless를 VavCore 기반으로 재작성**
2. **순수 디코딩 벤치마킹** 도구 구현
3. **자동화 테스트 스크립트** 작성
4. **CI/CD 파이프라인** 통합

### **📋 Phase 6: Godot C# 통합 (다음 단계)**
1. **C# 래퍼 클래스** 작성 및 P/Invoke 구현
2. **GodotVideoPlayer 클래스** 구현
3. **Git 서브모듈** 설정으로 VavCore 연동
4. **Godot 테스트 프로젝트** 생성 및 검증

### **📋 Phase 7: 최적화 및 프로덕션 준비 (최종 단계)**
1. **성능 최적화** 및 메모리 사용량 개선
2. **크로스 플랫폼 빌드** 시스템 구축
3. **통합 문서화** 및 개발 가이드 작성
4. **전체 시스템 성능 벤치마킹**

## 💡 **Vav2Player 기반의 차별화 요소**

### **검증된 성능**
- **4K AV1 디코딩**: 27.7fps (이미 달성)
- **메모리 효율성**: Zero-copy 디코딩, 메모리 풀 최적화
- **안정성**: 수개월간 개발/테스트로 검증된 코드베이스

### **고급 기능**
- **적응형 품질 제어**: 실시간 성능에 따른 자동 품질 조정
- **하이브리드 디코딩**: GPU/CPU 자동 전환
- **실시간 메트릭**: FPS, 디코딩 시간, 프레임 드롭 모니터링

### **Godot 최적화**
- **C API**: P/Invoke를 통한 완벽한 C# 통합
- **플랫폼 독립**: 헤드리스 빌드로 GUI 의존성 제거
- **GDExtension 준비**: Godot 4.x 네이티브 확장 지원

## 📊 **성능 목표 (Vav2Player 기반)**

### **4K AV1 디코딩 성능 (이미 달성)**
- **CONSERVATIVE 모드**: 25+ FPS (안정성 우선)
- **FAST 모드**: 35+ FPS (성능-품질 균형)
- **ULTRA_FAST 모드**: 28+ FPS (극한 최적화)

### **메모리 사용량**
- **Base Memory**: 50MB 이하
- **Frame Buffer**: 설정 가능 (기본 30프레임)
- **Peak Usage**: 200MB 이하 (4K 기준)

## 🧪 **개발 전략의 핵심 장점**

### **시간 효율성**
- ✅ **즉시 활용 가능**: 검증된 코드 재사용으로 개발 시간 90% 단축
- ✅ **빠른 프로토타이핑**: 2-3주 내 Godot 통합 가능

### **안정성 보장**
- ✅ **검증된 디코딩 로직**: 이미 테스트된 AV1 디코더들
- ✅ **에러 처리**: 완전한 예외 상황 대응 메커니즘
- ✅ **메모리 안전성**: RAII 패턴과 스마트 포인터 활용

### **확장성**
- ✅ **모듈형 설계**: 필요한 디코더만 선택적 사용
- ✅ **플러그인 아키텍처**: 새로운 코덱 추가 용이
- ✅ **크로스 플랫폼**: Windows, Linux, macOS 지원 준비

## 🔥 **다음 개발 단계**

### **즉시 진행 가능**
1. **VavCore.vcxproj** 생성 및 Vav2Player 솔루션에 추가
2. **기존 디코더 코드** VavCore 프로젝트로 이전
3. **C API 구현** 완료 및 Static Library 빌드

### **통합 개발 단계**
1. **Vav2Player 리팩토링**: VavCore C API 기반으로 전환
2. **헤드리스 테스트**: VavCore 전용 성능 벤치마킹
3. **Godot 통합**: Git 서브모듈을 통한 VavCore 활용

---

## 🎯 **핵심 설계 결론**

### **통합 아키텍처의 핵심 장점**
VavCore는 **Vav2Player 솔루션 내의 Static Library**로 설계되어 다음과 같은 이점을 제공합니다:

#### **단일 소스 관리**
1. **코드 중복 제거**: 디코딩 로직을 VavCore에서 한 번만 구현
2. **일관된 품질**: Vav2Player와 Godot에서 동일한 디코더 사용
3. **유지보수 효율성**: 버그 수정이나 최적화가 모든 곳에 자동 적용
4. **통합 테스트**: 단일 솔루션에서 모든 시나리오 검증

#### **개발 워크플로우 최적화**
1. **즉시 검증**: VavCore 수정 → Vav2Player에서 즉시 테스트
2. **성능 벤치마킹**: 헤드리스 모드로 순수 디코딩 성능 측정
3. **통합 디버깅**: Visual Studio에서 전체 스택 디버깅 가능
4. **버전 일관성**: Git 서브모듈을 통한 Godot 프로젝트 동기화

#### **Vav2Player 자산 완전 활용**
- ✅ **검증된 디코더**: 모든 AV1 디코더를 그대로 재사용
- ✅ **적응형 품질 제어**: 4K 27.7fps 성능을 모든 플랫폼에서 활용
- ✅ **하드웨어 가속**: NVDEC, Media Foundation 지원 유지
- ✅ **최적화 기법**: Zero-copy, 메모리 풀 등 모든 최적화 승계

#### **확장 가능한 아키텍처**
- **Vav2Player**: WinUI3 GUI 개발/테스트 플랫폼
- **헤드리스 모드**: 자동화 테스트 및 성능 측정
- **Godot 통합**: 게임 엔진에서 동일한 고성능 디코더 활용
- **미래 확장**: 다른 플랫폼(Unity, Unreal 등)에도 동일하게 적용 가능

**결론**: 통합 아키텍처를 통해 Vav2Player의 모든 기술적 자산을 보존하면서도, 단일 소스로 여러 플랫폼을 지원하는 최적의 개발 환경을 구축했습니다. 이는 기존 투자를 완전히 활용하면서도 새로운 요구사항에 효율적으로 대응할 수 있는 전략적 설계입니다.

**문서 버전**: 2.0 (실제 구현 기반)
**작성일**: 2025-09-24
**최종 수정**: 2025-09-24