601 lines
24 KiB
Markdown
601 lines
24 KiB
Markdown
|
# 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
|