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
    }
  }
}

플러그인 로드

plugin 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" />

type object를 사용해야 할 때는 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