video-v1/vav2/platforms/android/godot-plugin

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 라이브러리 빌드

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

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

2. Android 플러그인 빌드

# Android Studio 또는 Gradle로 빌드
cd plugin
./gradlew assembleRelease

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

3. Godot 프로젝트에 통합

# 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에서 사용

# 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. 고급 설정

# 디코더 타입 지정
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()

📊 성능 모니터링

# 실시간 성능 통계
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)

🐛 문제 해결

빌드 오류

# VavCore 라이브러리 확인
ls ../vavcore/libs/arm64-v8a/libVavCore.so

# Android NDK 경로 확인
echo $ANDROID_NDK_ROOT

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

런타임 오류

# 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 최적화로 최고 성능!