AR session 流程控制

這篇文件將介紹 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 實例。

注意

單實例限制：一個場景中僅允許存在一個 session 實例。在創建新 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 initialization failed: ${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 is not ready"); return;}
    session.pause();
},
resumeSession(): void {
    if (!session) { console.error("EasyAR session is not ready"); return;}
    session.resume();
}

這段程式碼中 xr-frame 元件暴露了 pauseSession() 和 resumeSession() 兩個函式。

在小程式頁面中在 onHide 即小程式從前台進入後台時調用 pauseSession() 暫停 session。

在 onShow 即小程式從後台進入前台時調用 resumeSession() 恢復 session。