6.1 KiB
6.1 KiB
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. 환경 설정
# Android NDK 경로 설정
export ANDROID_NDK_ROOT=/path/to/android-ndk-r26
# 또는
export ANDROID_NDK=/path/to/android-ndk-r26
2. CMake 빌드 (권장)
# 기본 빌드 (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)
# 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. 라이브러리 복사
# 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 설정
// 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 사용 예제
#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 최적화)
// 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+ 권장
🐛 문제 해결
빌드 오류
# NDK 경로 확인
echo $ANDROID_NDK_ROOT
echo $ANDROID_NDK
# CMake 버전 확인
cmake --version # 3.18.1+ 필요
# 권한 설정 (Linux/macOS)
chmod +x build-android.sh
런타임 오류
# 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 공식 문서
- Android MediaCodec 문서: Android 개발자 가이드
🎮 Godot 게임 개발자를 위한 최적화된 AV1 디코딩 라이브러리 ⚡ 하드웨어 가속과 크로스 플랫폼 호환성을 동시에!