video-v1/vav2/platforms/android/godot-plugin/README.md

# VavCore Godot 4.4.1 Android Plugin

Android 네이티브 플러그인으로 구현된 하드웨어 가속 AV1 비디오 디코더입니다.

## 🎯 **주요 기능**

### **🚀 하드웨어 가속 AV1 디코딩**
- **Android MediaCodec**: 네이티브 하드웨어 가속
- **자동 fallback**: dav1d 소프트웨어 디코더
- **Godot 4.4.1 최적화**: Vulkan/OpenGL ES 직접 통합

### **📱 Android 기기 지원**
- **API Level 29+**: Android 10 이상
- **AV1 하드웨어**: Snapdragon 8 Gen 1+, Tensor G2+, Dimensity 9200+
- **소프트웨어 fallback**: 모든 Android 기기

### **🎮 Godot 4.4.1 통합**
- **네이티브 플러그인**: Java + JNI + C++
- **GDScript API**: 간편한 비디오 플레이어 노드
- **GPU 최적화**: 직접 GPU 텍스처 렌더링

## 📁 **프로젝트 구조**

```
platforms/android/godot-plugin/
├── plugin.cfg                    # Godot 플러그인 설정
├── VavCorePlugin.gd              # Godot 에디터 플러그인
├── plugin/                       # Android 네이티브 플러그인
│   ├── build.gradle              # Android 빌드 설정
│   ├── src/main/java/            # Java 플러그인 코드
│   │   └── org/godotengine/plugin/vavcore/
│   │       ├── VavCorePlugin.java     # 메인 플러그인 클래스
│   │       └── VavCoreNative.java     # JNI 인터페이스
│   └── jni/                      # C++ JNI 구현
│       ├── CMakeLists.txt        # CMake 빌드 설정
│       └── vavcore_jni.cpp       # JNI 네이티브 구현
├── gdscript/                     # GDScript 인터페이스
│   └── VavCorePlayer.gd          # 비디오 플레이어 노드
└── demo/                         # 사용 예제 (예정)
```

## 🚀 **빌드 방법**

### **1. VavCore 라이브러리 빌드**
```bash
# VavCore 플랫폼 라이브러리 먼저 빌드
cd ../vavcore
./build.sh

# 결과: libs/arm64-v8a/libVavCore.so
```

### **2. Android 플러그인 빌드**
```bash
# Android Studio 또는 Gradle로 빌드
cd plugin
./gradlew assembleRelease

# 결과: build/outputs/aar/plugin-release.aar
```

### **3. Godot 프로젝트에 통합**
```bash
# 1. AAR 파일을 Godot 프로젝트에 복사
cp plugin/build/outputs/aar/plugin-release.aar /path/to/godot/project/android/plugins/

# 2. GDScript 파일들을 addon으로 복사
cp -r gdscript/* /path/to/godot/project/addons/vavcore/

# 3. plugin.cfg 복사
cp plugin.cfg /path/to/godot/project/addons/vavcore/
```

## 🎮 **Godot에서 사용법**

### **1. 플러그인 활성화**
```
프로젝트 → 프로젝트 설정 → 플러그인 → VavCore AV1 Decoder 활성화
```

### **2. GDScript에서 사용**
```gdscript
# VavCorePlayer 노드 추가
@onready var video_player = $VavCorePlayer

func _ready():
    # 하드웨어 지원 확인
    var capabilities = video_player.get_hardware_capabilities()
    print("Hardware AV1 support: ", capabilities.hardware_av1_supported)
    print("Optimal for Godot: ", capabilities.optimal_for_godot)

    # 신호 연결
    video_player.video_frame_decoded.connect(_on_frame_decoded)
    video_player.hardware_decoder_available.connect(_on_hardware_available)

    # 비디오 로드 및 재생
    if video_player.load_video("path/to/video.webm"):
        video_player.play()

func _on_frame_decoded(frame_info: Dictionary):
    print("Frame decoded: ", frame_info.width, "x", frame_info.height)

func _on_hardware_available(is_available: bool, decoder_info: String):
    print("Hardware decoder: ", is_available, " - ", decoder_info)
```

### **3. 고급 설정**
```gdscript
# 디코더 타입 지정
video_player.preferred_decoder = VavCorePlayer.DecoderType.MEDIACODEC

# Surface 타입 지정 (Godot 렌더러에 따라)
video_player.preferred_surface = VavCorePlayer.SurfaceType.VULKAN  # Forward+/Mobile
# 또는
video_player.preferred_surface = VavCorePlayer.SurfaceType.OPENGL_ES  # Compatibility

# GPU 표면 설정
video_player.setup_gpu_surface()
```

## 📊 **성능 모니터링**

```gdscript
# 실시간 성능 통계
func _process(_delta):
    var stats = video_player.get_playback_stats()
    print("Frames decoded: ", stats.frames_decoded)
    print("Average decode time: ", stats.average_decode_time, "ms")
    print("Frames dropped: ", stats.frames_dropped)
```

## 🔧 **개발자 가이드**

### **Android 플러그인 아키텍처**
```
GDScript (VavCorePlayer.gd)
    ↓ Engine.get_singleton()
Java (VavCorePlugin.java)
    ↓ JNI calls
C++ (vavcore_jni.cpp)
    ↓ Direct calls
VavCore Library (AndroidMediaCodecAV1Decoder)
```

### **주요 클래스**
- **VavCorePlugin**: Godot Android 플러그인 메인 클래스
- **VavCoreNative**: JNI 네이티브 인터페이스
- **VavCorePlayer**: GDScript 비디오 플레이어 노드

### **Surface 타입 최적화**
- **VULKAN**: Godot 4 Forward+/Mobile (최고 성능)
- **OPENGL_ES**: Godot 4 Compatibility (호환성)
- **ANDROID**: 네이티브 Surface (일반 앱용)
- **CPU**: 소프트웨어 (fallback)

## 🐛 **문제 해결**

### **빌드 오류**
```bash
# VavCore 라이브러리 확인
ls ../vavcore/libs/arm64-v8a/libVavCore.so

# Android NDK 경로 확인
echo $ANDROID_NDK_ROOT

# Gradle 캐시 정리
cd plugin && ./gradlew clean
```

### **런타임 오류**
```bash
# Android 로그 확인
adb logcat | grep -i vavcore

# Godot 로그 확인 (디버그 빌드)
adb logcat | grep -i godot
```

### **성능 이슈**
- **arm64-v8a 우선 사용**: 64비트가 더 빠름
- **Release 빌드**: Debug는 성능이 떨어짐
- **하드웨어 확인**: `isHardwareAV1Supported()` 결과 확인

## 📚 **관련 문서**

- **VavCore 설계**: `../../../VavCore_Android_MediaCodec_Design.md`
- **플랫폼 구조**: `../../README.md`
- **Godot 통합**: `../../../VavCore_Godot_Integration_Design.md`

## 🎯 **다음 단계**

1. **YUV→RGB 변환**: ImageTexture 업데이트 구현
2. **WebM 파일 파싱**: 실제 비디오 파일 로딩
3. **성능 최적화**: GPU 메모리 직접 렌더링
4. **데모 앱**: 완전한 사용 예제

---

🎮 **Godot 4.4.1 Android에서 하드웨어 가속 AV1 비디오를 쉽게!**
⚡ **MediaCodec + Vulkan/OpenGL ES 최적화로 최고 성능!**