Mega プラグインを WeChat Mini Program に組み込む

このドキュメントでは、xr-frame Mini Program 環境で Mega プラグインを組み込む手順を説明します。

始める前に

xr-frame 開発ガイドと xr-frame 公式サンプルを参照し、WeChat が公式に提供する XR-3D engine の使い方を学習してください。内容は次のとおりです。
- 通常の WeChat Mini Program ページに xr-frame コンポーネントを導入する方法。
- xr-frame コンポーネントと Mini Program の従来コンポーネントとの通信方法。
- scene から要素を取得または作成し、Transform など一部のプロパティを変更する方法。
- GLTF model などの resource の読み込みと解放。

グローバル設定

Mini Program ルートディレクトリのグローバル設定ファイル app.json に Mega Mini Program プラグインへの依存関係を追加し、依存関係の読み込みを オンデマンド注入 に変更します。

{
  "lazyCodeLoading": "requiredComponents",
  "plugins": {
    "easyar-wechat-miniprogram": {
      "version": "2.0.2", //最新の plugin バージョンを使用
      "provider": "wx27fa3b52b5462e8f" // Mega Mini Program plugin の固定 id
    }
  }
}

プラグインを読み込む

プラグイン interfaceでプラグインを導入し、プラグインの一部メソッドを直接使用して、正しく読み込まれているか確認できます。

たとえば、WeChat が提供する requirePlugin(string path) interface で EasyARWechatMiniprogramPlugin を取得した後、その isMegaTrackerSupported メソッドを使ってデバイスが対応しているか判定します。

//typings ファイルをすでに導入している場合
//const easyarPlugin: easyar.EasyARWechatMiniprogramPlugin = requirePlugin("easyar-wechat-miniprogram") as easyar.EasyARWechatMiniprogramPlugin;
const easyarPlugin = requirePlugin("easyar-wechat-miniprogram") as any;
//isMegaTrackerSupported を呼び出して現在のデバイスがサポートされているか判断し、非対応ならポップアップで通知
if (!easyarPlugin.isMegaTrackerSupported()) {
    const message = `当前设备不支持 VK v1 和 v2，请参考微信官方文档：https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/visionkit/plane.html`;
    wx.showModal({
        title: "设备不支持",
        content: message,
        showCancel: false,
    });
    console.error(message);
    return;
}

この例では、まず WeChat が提供する requirePlugin(string path) interface で、プラグインが公開する interface object である easyarPlugin を取得します。その後、提供されている isMegaTrackerSupported メソッドを呼び出し、現在の実行環境で利用可能か判定します。利用できない場合はモーダルで通知します。

型を導入する

開発には Typescript の使用を推奨します。

サンプルプロジェクト内のパス: /typings/types/easyar/lib.easyar.d.ts。

同じディレクトリにコピーし、/typings/types/index.d.ts で triple-slash directive として参照します。

/// <reference path="./easyar/lib.easyar.d.ts" />

型オブジェクトを使用する必要がある場合は、getMegaSystem から EasyAR Mega WeChat Mini Program プラグインの type system IMegaSystem を取得できます。

const mega: easyar.IMegaSystem = easyarPlugin.getMegaSystem();

その後、IMegaSystem で公開されている型を使って型比較を行えます。たとえば、state と mega.SessionState.Running を比較して、session の初期化が成功したかを判定できます。

const newState: easyar.SessionState = event.detail.value;
if (newState === mega.SessionState.Running) {
    console.log("EasyAR Session initialized succeeded. Start running.");
}

xr-frame scene の構築 (WXML)

ページの WXML ファイルでは、xr-easyar-mega コンポーネントは xr-scene の child node として配置し、camera と tracker の id を正しくバインドする必要があります。id を指定しない場合、コンポーネントは scene 内で最初に見つかった xr-camera と xr-ar-tracker コンポーネントを使用します。

<xr-scene id="xr-scene" ar-system="modes:Plane; planeMode: 1" bind:ready="handleReady">
    <xr-easyar-mega
        id="easyar-mega"
        camera-id="xrCamera"
        ar-tracker-id="xrARTracker"
    ></xr-easyar-mega>
    <xr-node>
        <xr-ar-tracker id="xrARTracker" mode="Plane"></xr-ar-tracker>
        <xr-camera id="xrCamera" node-id="xrCamera" clear-color="0.925 0.925 0.925 1" background="ar" is-ar-camera></xr-camera>
    </xr-node>
    <xr-shadow id="shadow-root" node-id="xrShadow"></xr-shadow>
</xr-scene>

注意

ar-system の planeMode は 1 に設定する必要があります

Mega プラグインの event callback を登録する

<xr-easyar-mega
    id="easyar-mega"
    camera-id="xrCamera"
    ar-tracker-id="xrARTracker"
    bind:sessionStateChange="onSessionStateChange"
    bind:megaLocalizationResult="onMegaLocalizationResult"
    bind:postSessionUpdate="onPostSessionUpdate"
></xr-easyar-mega>

WXML で、xr-frame Element proxy が配信する event をバインドします。xr-frame の event 配信メカニズムについては、xr-frame event メカニズムを参照してください。

プラグインが配信する event は次のとおりです。

event 名	パラメータ型	説明
`SessionStateChange`	SessionState	Session 状態が変化したとき直ちに発火します。パラメータは Session の新しい状態で、Session 初期化開始と成功の callback 処理に使用します。
`MegaLocalizationResult`	MegaLocalizationResult	Mega localization 結果を受け取った rendering frame の更新完了後に発火します。event 発火時、その rendering frame 内で EasyAR が制御するすべての Transform 変更は完了しています。
`PostSessionUpdate`	パラメータなし	Session がその rendering frame で更新を完了した直後に発火します。この時点で、その frame 内で EasyAR が制御するすべての Transform 変更は完了しています。

AR Session

session の作成、起動、破棄については AR Session フロー制御を参照してください。

sessionStateChange event callback で初期化が成功したか確認します。状態が Running になったら、ARSession は準備完了と見なせます。

WXML では、bind:sessionStateChange="onSessionStateChange" により、xr-frame コンポーネント内の onSessionStateChange() 関数を sessionStateChange event の callback として登録します。

<xr-easyar-mega
    bind:sessionStateChange="onSessionStateChange"
></xr-easyar-mega>

xr-frame コンポーネント内の callback 関数 onSessionStateChange() で、session 状態を SessionState の各 enum と比較することで、現在の session 状態を判定できます。

onSessionStateChange(event) {
    const newState: easyar.SessionState = event.detail.value;
    console.log(`EasyAR Session state changed to: ${mega.SessionState[newState]}`);
    let displayInfoStr: string = "";
    if (newState === mega.SessionState.None) {
        displayInfoStr = "EasyAR Session is inactive.";
    } else if (newState === mega.SessionState.Initializing) {
        displayInfoStr = "EasyAR Session is initializing...";
    } else if (newState === mega.SessionState.Running) {
        displayInfoStr = "EasyAR Session initialized succeeded. Start running.";
    }
    this.triggerEvent("sessionDisplayInfoEvent", displayInfoStr);
}

上記コードでは、初期化完了後に console に "EasyAR Session initialized succeeded. Start running." と出力されます。

Table of Contents