219 lines
6.1 KiB
Markdown
219 lines
6.1 KiB
Markdown
|
# 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 디코딩 라이브러리**
|
||
|
|
⚡ **하드웨어 가속과 크로스 플랫폼 호환성을 동시에!**
|