AR session フロー制御

このドキュメントでは、AR sessionの作成、開始、停止、破棄を含むフロー制御について説明します。

開始前に

AR sessionの概念とフローを理解する

作成

設定内のクラウド位置特定ライブラリ appId、クラウドサービス serverAddress、クラウドサービス apiKey および apiSecret を使用して APIKeyAccessData を作成します。

次に、作成した APIKeyAccessData を使用して MegaTrackerConfigs を作成します。

さらに MegaTrackerConfigs と設定の licenseKey を使用して SessionConfigs を作成します。

最終的に xr-frame シーン内にアタッチされた EasyARMegaComponent の createSession(sessionConfigs) メソッドを使用して session を作成します。

createSession() {
    // シーン内にアタッチされた megaComponent を取得
    const megaElement = scene.getElementById('easyar-mega');
    const megaComponent = megaElement.getComponent("easyar-mega") as easyar.EasyARMegaComponent;
    // MegaTracker クラウドサービス認証設定
    const apiKeyAccess = new mega.APIKeyAccessData(this.data.appId, this.data.serverAddress, this.data.apiKey, this.data.apiSecret);
    const megaTrackerConfigs: easyar.MegaTrackerConfigs = {
        access: apiKeyAccess
    }
    // Session 設定
    const sessionConfigs: easyar.SessionConfigs = {
        megaTrackerConfigs: megaTrackerConfigs,
        licenseKey: settings.EasyARLicenseKey
    }
    // インスタンスを作成
    session = megaComponent.createSession(sessionConfigs);
}

このコードは、シーンから megaComponent を取得した後、設定を使用して session インスタンスを作成する方法を示しています。

注意

単一インスタンス制限: 1つのシーンで許可される session インスタンスは1つだけです。新しい session を作成する前に、closeSession() を呼び出して古いインスタンスを破棄していることを確認する必要があります。そうしないと作成に失敗します。

開始

通常、xr-frame の AR システム準備完了コールバックで EasyARSession の start(options) メソッドを使用して session を開始します。

警告

MegaTracker は平面 AR トラッカーが提供するデータに依存しており、平面トラッカーの初期化が完了するまでは機能しません。

WXML で bind:ready="handleReady" を使用して AR システム準備完了イベントを登録します:

<xr-scene ar-system="modes:Plane; planeMode: 1" bind:ready="handleReady">

xr-frame コンポーネント内のコールバック関数 handleReady で EasyARSession の start(options) メソッドを使用して session を開始します。

handleReady: function(event) {
    try {
        //Session を開始、デフォルトで5回再試行
        await session.start();
    } catch (err) {
        console.error(`EasyAR Session の初期化に失敗しました: ${err.message}`);
        return;
    }
}

停止と破棄

xr-frame シーン内にアタッチされた EasyARMegaComponent の closeSession() メソッドを使用して session を破棄します。

ページ離脱時（コンポーネントインスタンスがページノードツリーから削除される時）に確実に破棄されるよう、xr-frame コンポーネントライフサイクルの detached で呼び出すことを推奨します。

lifetimes: {
    detached: function() {
        const megaElement = scene.getElementById('easyar-mega');
        const megaComponent = megaElement.getComponent("easyar-mega") as easyar.EasyARMegaComponent;
        megaComponent.closeSession();
    }
}

フォアグラウンド/バックグラウンド切り替え

ページがバックグラウンドに移動する際、EasyARSession の pause() メソッドを使用して session を一時停止します。ページがフォアグラウンドに戻る際、EasyARSession の resume() メソッドを使用して session を再開します。

/** ミニプログラムページの呼び出し*/
onHide() {
    if (this.ar) {
        this.ar.pauseSession();
    }
},
onShow() {
    if (this.ar) {
        this.ar.resumeSession();
    }
}
/** xr-frame コンポーネント内の関数*/
pauseSession(): void {
    if (!session) { console.error("EasyAR Session が準備できていません"); return;}
    session.pause();
},
resumeSession(): void {
    if (!session) { console.error("EasyAR Session が準備できていません"); return;}
    session.resume();
}

このコードでは、xr-frame コンポーネントが pauseSession() と resumeSession() の2つの関数を公開しています。

ミニプログラムページで onHide（ミニプログラムがフォアグラウンドからバックグラウンドに入る時）に pauseSession() を呼び出して session を一時停止します。

onShow（ミニプログラムがバックグラウンドからフォアグラウンドに入る時）に resumeSession() を呼び出して session を再開します。

Table of Contents

AR session フロー制御

開始前に

作成

注意

開始

警告

停止と破棄

フォアグラウンド/バックグラウンド切り替え