Интеграция Google VR SDK в мобильное приложение

Интеграция Google VR SDK в мобильное приложение

Google VR SDK (он же Cardboard SDK после ребрендинга 2021 года) — официальная библиотека для добавления Cardboard VR в мобильные приложения на iOS и Android. SDK берёт на себя lens distortion, head tracking, стереопроекцию и QR-сканирование профиля устройства.

Текущий статус: Cardboard SDK vs deprecated Google VR SDK

Важный момент: оригинальный Google VR SDK (gvr-android-sdk) объявлен deprecated с 2019 года. Актуальная версия — открытый Google Cardboard SDK, который активно поддерживается. Если в проекте используется старый com.google.vr.sdk — рекомендуется миграция.

Новый Cardboard SDK поддерживает:

• Unity через UPM пакет com.google.cardboard
• Нативный Android (C++ через JNI + Java wrapper)
• Нативный iOS (Objective-C/Swift)

Интеграция в Unity

Самый распространённый путь. Через Package Manager добавляем com.google.cardboard из git URL:

https://github.com/googlevr/cardboard.git#upm

После установки в сцену добавляем CardboardCamera компонент на Main Camera. SDK автоматически:

• Разбивает экран пополам для стереорендеринга
• Применяет lens distortion correction
• Читает head tracking из IMU
• Обрабатывает trigger button

// Первый запуск: показываем UI для сканирования QR
void Start() {
    if (!CardboardQrCode.IsDeviceParamsSet()) {
        Cardboard.SDK.ScanDeviceParams();
    }
}

// Recenter по нажатию кнопки
void Update() {
    if (CardboardInput.GetButtonDown()) {
        Cardboard.SDK.Recenter();
    }
}

Нативная интеграция Android (Java/Kotlin)

Для нативных приложений без Unity:

// build.gradle
implementation 'com.google.cardboard:sdk:1.21.0'

Ключевые компоненты SDK:

// Инициализация в Activity
private CardboardHeadTracker headTracker;
private CardboardLensDistortion lensDistortion;
private CardboardDistortionRenderer distortionRenderer;

@Override
protected void onCreate(Bundle savedInstanceState) {
    CardboardSdk.initializeOnce(this, "your-app-name");
    headTracker = CardboardHeadTracker.create();
    // ...
}

// В render loop (вызывается из GLSurfaceView)
@Override
public void onDrawFrame(GL10 gl) {
    // Получаем матрицы для каждого глаза
    long monotonic_time_ns = System.nanoTime();
    float[] leftEyeViewMatrix  = new float[16];
    float[] rightEyeViewMatrix = new float[16];

    headTracker.getPose(monotonic_time_ns, leftEyeViewMatrix, rightEyeViewMatrix);

    // Рендеринг каждого глаза...

    // Применяем lens distortion через SDK
    distortionRenderer.renderEyeToDisplay(
        /* display */ 0, /* x */ 0, /* y */ 0,
        /* width */ displayWidth, /* height */ displayHeight,
        /* leftEyeParams */ leftEyeParams,
        /* rightEyeParams */ rightEyeParams
    );
}

Нативная интеграция iOS (Swift)

// Podfile или SPM
pod 'GoogleCardboard', '~> 1.21'

// CardboardV1API — основной entry point
import CardboardSDK

class VRViewController: UIViewController {
    private var renderer: CardboardRenderer!

    override func viewDidLoad() {
        super.viewDidLoad()
        CardboardQrCode.getSavedDeviceParams { [weak self] params in
            if params == nil {
                CardboardQrCode.scanQrCodeAndSaveDeviceParams(from: self)
            }
            self?.initRenderer()
        }
    }
}

QR-сканирование: обработка edge cases

QR-сканер открывается при первом запуске или по явному запросу пользователя. Потенциальные проблемы:

• Пользователь отказался сканировать → SDK использует дефолтные параметры Cardboard v1. Lens distortion будет некорректной для нестандартных корпусов.
• QR-код не читается (плохое освещение, повреждённый код) → кнопка «ввести вручную» или «использовать стандартный Cardboard».
• После смены корпуса → в настройках приложения кнопка «изменить гарнитуру», вызывает CardboardQrCode.scanQrCodeAndSaveDeviceParams().

Режим split-screen и fullscreen

Cardboard SDK ожидает ландшафтную ориентацию. На iOS это означает блокировку UIInterfaceOrientationMask на .landscapeRight. На Android — android:screenOrientation="landscape" в манifest + обработка onConfigurationChanged чтобы не пересоздавать activity.

Экранные вырезы (notch, Dynamic Island) в ландшафтном режиме могут перекрывать часть VR-картинки. Используем WindowInsets.displayCutout (Android) и safeAreaInsets (iOS) для правильного позиционирования рендер-области.

Типичные проблемы при интеграции

IllegalStateException: Surface is not valid при старте на Android — GLSurfaceView не готов к моменту инициализации Cardboard. Решается инициализацией в surfaceCreated() callback, а не в onCreate().

SDK не компилируется с новым NDK — Cardboard SDK имеет нативную C++ часть, иногда требует явного abiFilters "armeabi-v7a", "arm64-v8a" в gradle.

На iOS 17+ CMMotionManager требует NSMotionUsageDescription в Info.plist — без него краш при старте VR-режима.

Процесс работы

Аудит существующего проекта: Unity или нативный, текущие зависимости, целевые iOS/Android версии.

Интеграция Cardboard SDK, настройка QR-сканирования.

Адаптация рендеринга: split-screen, lens distortion, стерео проекции.

Gaze interaction и Cardboard button.

Тестирование на реальных устройствах разных производителей.

Ориентиры по срокам

Базовая интеграция Cardboard SDK в Unity-проект — 2–3 дня. Нативная интеграция с кастомным рендерером для iOS или Android — 3–5 дней.