# VavCore Android Build Guide

VavCore는 크로스 플랫폼 AV1 비디오 디코딩 라이브러리입니다. Android에서는 MediaCodec 하드웨어 가속과 dav1d 소프트웨어 fallback을 지원합니다.

## 🎯 Android 지원 기능

### **하드웨어 가속 AV1 디코딩**
- **Android MediaCodec**: 네이티브 하드웨어 가속 (API 29+)
- **자동 SoC 감지**: Snapdragon 8 Gen 1+, Tensor G2+, Dimensity 9200+ 등
- **Godot 4 최적화**: Vulkan > OpenGL ES > ANativeWindow 우선순위

### **소프트웨어 Fallback**
- **dav1d**: 하드웨어 불가능 시 자동 전환
- **모든 기기 지원**: AV1 하드웨어가 없는 구형 기기도 지원

## 📋 빌드 요구사항

### **개발 환경**
- **Android NDK r25+** (권장: r26)
- **CMake 3.18.1+**
- **Android API Level 29+** (Android 10+)

### **지원 아키텍처**
- **arm64-v8a** (64비트 ARM - 권장)
- **armeabi-v7a** (32비트 ARM)
- **x86_64** (Intel 64비트 - 에뮬레이터용)

## 🚀 빌드 방법

### **1. 환경 설정**
```bash
# Android NDK 경로 설정
export ANDROID_NDK_ROOT=/path/to/android-ndk-r26
# 또는
export ANDROID_NDK=/path/to/android-ndk-r26
```

### **2. CMake 빌드 (권장)**
```bash
# 기본 빌드 (arm64-v8a, Release)
./build-android.sh

# 특정 아키텍처 빌드
ANDROID_ABI=armeabi-v7a ./build-android.sh

# Debug 빌드
BUILD_TYPE=Debug ./build-android.sh

# Godot 연동용 빌드
./build-android.sh --copy-to-godot
```

### **3. Android.mk 빌드 (NDK-Build)**
```bash
# VavCore 디렉토리에서
ndk-build

# 또는 특정 아키텍처만
ndk-build APP_ABI=arm64-v8a
```

## 📂 빌드 출력

### **CMake 빌드 결과**
```
VavCore/
├── build-android/          # 빌드 임시 파일
├── android-libs/           # 설치된 라이브러리
│   ├── lib/
│   │   └── libVavCore.so   # Android 공유 라이브러리
│   └── include/            # 헤더 파일들
│       └── VavCore/
└── godot-libs/             # Godot 연동용 (--copy-to-godot 시)
    ├── arm64-v8a/
    │   └── libVavCore.so
    └── include/
```

### **Android.mk 빌드 결과**
```
VavCore/
├── libs/
│   ├── arm64-v8a/
│   │   └── libVavCore.so
│   └── armeabi-v7a/
│       └── libVavCore.so
└── obj/                    # 임시 오브젝트 파일들
```

## 🎮 Godot 4 Android 플러그인 연동

### **1. 플러그인 프로젝트 구조**
```
YourGodotPlugin/
├── android/
│   ├── build.gradle
│   ├── src/main/
│   │   ├── java/          # Java/Kotlin 코드
│   │   └── jniLibs/       # 네이티브 라이브러리
│   │       ├── arm64-v8a/
│   │       │   └── libVavCore.so
│   │       └── armeabi-v7a/
│   │           └── libVavCore.so
│   └── jni/               # JNI 헤더 및 소스
│       └── VavCore/       # VavCore 헤더들
```

### **2. 라이브러리 복사**
```bash
# VavCore 빌드 후
cp android-libs/lib/libVavCore.so your-plugin/android/src/main/jniLibs/arm64-v8a/
cp -r android-libs/include/VavCore your-plugin/android/jni/
```

### **3. Gradle 설정**
```gradle
// android/build.gradle
android {
    compileSdkVersion 34

    defaultConfig {
        minSdkVersion 29  // VavCore Android 최소 요구사항
        targetSdkVersion 34

        ndk {
            abiFilters 'arm64-v8a', 'armeabi-v7a'
        }
    }

    sourceSets {
        main {
            jniLibs.srcDirs = ['src/main/jniLibs']
        }
    }
}
```

## 🔧 개발 가이드

### **VavCore 사용 예제**
```cpp
#include "VavCore/VavCore.h"

// AV1 디코더 생성 (Android에서 MediaCodec 우선 선택)
auto decoder = VavCore::VideoDecoderFactory::CreateDecoder(
    VavCore::VideoCodecType::AV1,
    VavCore::VideoDecoderFactory::DecoderType::AUTO
);

// Godot 최적화 확인
if (auto android_decoder = dynamic_cast<VavCore::AndroidMediaCodecAV1Decoder*>(decoder.get())) {
    if (android_decoder->IsOptimalForGodot()) {
        // Vulkan 또는 OpenGL ES 텍스처로 직접 디코딩 가능
        std::string info = android_decoder->GetGodotIntegrationInfo();
        // "Vulkan VkImage - Direct integration with Godot 4 Forward+/Mobile renderer"
    }
}
```

### **Surface 타입 우선순위 (Godot 최적화)**
```cpp
// VavCore가 자동으로 선택하는 우선순위:
// 1. VAVCORE_SURFACE_VULKAN_IMAGE      (Godot 4 Forward+/Mobile)
// 2. VAVCORE_SURFACE_OPENGL_ES_TEXTURE (Godot 4 Compatibility)
// 3. VAVCORE_SURFACE_ANDROID_NATIVE_WINDOW (일반 비디오 플레이어)
// 4. VAVCORE_SURFACE_CPU (소프트웨어 fallback)
```

## 📱 지원 기기

### **AV1 하드웨어 디코딩 지원**
- **Qualcomm**: Snapdragon 8 Gen 1+ (2022년 이후)
- **Google**: Tensor G2+ (Pixel 7 이후)
- **MediaTek**: Dimensity 9200+ (2023년 이후)
- **Samsung**: Exynos 2200 (제한적 지원)

### **소프트웨어 디코딩 (dav1d)**
- **모든 Android 기기**: API 29+ (Android 10+)
- **성능**: ARM Cortex-A78+ 권장

## 🐛 문제 해결

### **빌드 오류**
```bash
# NDK 경로 확인
echo $ANDROID_NDK_ROOT
echo $ANDROID_NDK

# CMake 버전 확인
cmake --version  # 3.18.1+ 필요

# 권한 설정 (Linux/macOS)
chmod +x build-android.sh
```

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

# MediaCodec 지원 확인
adb shell dumpsys media.codec_list | grep -i av1
```

### **성능 최적화**
- **arm64-v8a 우선 사용**: 64비트가 32비트보다 빠름
- **Release 빌드**: Debug는 성능이 현저히 떨어짐
- **API Level 31+**: 최신 MediaCodec 기능 활용

## 📚 추가 자료

- **VavCore_Android_MediaCodec_Design.md**: 상세한 설계 문서
- **Godot 4 Android 플러그인 가이드**: [Godot 공식 문서](https://docs.godotengine.org/en/stable/tutorials/platform/android/android_plugin.html)
- **Android MediaCodec 문서**: [Android 개발자 가이드](https://developer.android.com/ndk/reference/group/media)

---

🎮 **Godot 게임 개발자를 위한 최적화된 AV1 디코딩 라이브러리**
⚡ **하드웨어 가속과 크로스 플랫폼 호환성을 동시에!**