Table of Contents

AR Session フロー制御

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

始める前に

作成

設定内の cloud localization library appId、cloud service serverAddress、cloud service 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 つのシーンには 1 つの Session インスタンスのみ存在できます。新しい Session を作成する前に、必ず closeSession() を呼び出して古いインスタンスを破棄してください。そうしないと作成に失敗します。

開始

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

警告

MegaTracker は planar AR tracker が提供するデータに依存しており、planar tracker の初期化完了前には動作できません。

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

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

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

handleReady: function(event) {
    try {
        //Session を開始。デフォルトでは失敗時に 5 回再試行
        await session.start();
    } catch (err) {
        console.error(`EasyAR Session initialization failed: ${err.message}`);
        return;
    }
}

停止と破棄

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

ページを離れるとき、つまりコンポーネントインスタンスがページノードツリーから削除されるときに破棄されるよう、xr-frame コンポーネント lifecycle の 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 を再開します。

/** Mini Program ページからの呼び出し*/
onHide() {
    if (this.ar) {
        this.ar.pauseSession();
    }
},
onShow() {
    if (this.ar) {
        this.ar.resumeSession();
    }
}
/** xr-frame コンポーネント内の関数*/
pauseSession(): void {
    if (!session) { console.error("EasyAR Session is not ready"); return;}
    session.pause();
},
resumeSession(): void {
    if (!session) { console.error("EasyAR Session is not ready"); return;}
    session.resume();
}

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

Mini Program ページでは、onHide、つまり Mini Program がフォアグラウンドからバックグラウンドに入るときに pauseSession() を呼び出して session を一時停止します。

onShow、つまり Mini Program がバックグラウンドからフォアグラウンドに戻るときに resumeSession() を呼び出して session を再開します。