Vuforia官方文档-03-Vuforia Engine 生命周期

Vuforia官方文档自学，只为学习交流，肯定会有错误与肤浅之处，仅供参考

Vuforia Engine LifeCycle：

• Vuforia引擎生命周期官方文档：Vuforia Engine Lifecycle in Unity | VuforiaLibrary

1、Vuforia Engine Workflow（工作流程）：

• vuforia引擎工作流程大致如下：
  • 配置和创建引擎Engine
  • 配置和创建观察员Observer
  • 解析状态State，检索观察结果Observations
  • 基于观察结果增强渲染

2、Unity中管理Vuforia Engine：

• Vuforia Engine提供了一个API，该API使用Vuforia Engine对象和脚本类扩展Unity编辑器。使用Vuforia Engine创建AR体验的大多数创作任务都可以直接在Unity编辑器中使用Vuforia Engine游戏对象完成。脚本API提供了扩展选项和对AR应用程序的控制。

• 管理Vuforia Engine生命周期：

  • 默认管理Vuforia Engine：

    • 在Unity中，默认情况下会自动管理Vuforia Engine生命周期：
      • Vuforia Engine在应用程序启动时自动初始化一次
      • 退出应用程序时，Vuforia Engine会被取消初始化
      • 加载带有任何Vuforia Engine游戏对象（如目标观察者target observers或ARCamera）的Unity场景时，将启动Vuforia Engine，停止场景则停止Vuforia Engine。此功能与主摄像头上的VuforiaBehaviour组件耦合。如果一个场景使用了Vuforia游戏对象但不具有VuforiaBehaviour组件，则将自动创建一个VuforiaBehaviour并附加到主摄影机对象main camera object上，启动Vuforia并负责摄影机控制和视频背景渲染。

  • 覆盖默认管理：

    • 有几种方法可以覆盖默认情况下的Vuforia Engine生命周期管理：

      • 延迟Vuforia Engine初始化：

        • 在Vuforia配置中勾选延迟初始化复选框：
        • 
        • 
        • 如果应用程序中存在一种特殊的AR模式，且不是每个用户最终都需要使用到这种模式，那么延迟Engine初始化这种方法是有意义的。
        • 对于这种情况，加载包含Vuforia Engine功能的第一个场景之前，可以从脚本API手动初始化Vuforia引擎：VuforiaApplication.Instance.Initialize();

      • 禁用Vuforia Engine启动：

        • 在加载包含Vuforia Engine游戏对象（如Targets或ARCamera）的场景时，可以通过禁用ARCamera上的VuforiaBehaviour组件阻止Vuforia Engine启动
        • 
        • 之后可以在脚本代码中启用VuforiaBehaviour来启动Vuforia Engine
      • 在Inspector面板的VuforiaConfiguration中配置管理Vuforia Engine：
        • VuforiaConfiguration：其他Vuforia配置选项可以在Inspector面板的VuforiaConfiguration中找到，可从ARCamera GameObject或Unity中的窗口->Vuforia配置获得
        • 
        • 初始化Vuforia Engine需要某些设置，如应用程序许可证密钥。其他配置如ARCore需求设置，是在构建Unity应用程序时评估的构建时设置……
        • 最后，在Unity场景中启动Vuforia Engine之前，会评估一些设置，如跟踪设备姿势device pose
        • 
      • 在程序运行时使用代码管理Engine Vuforia：
        • 在程序运行时也可以使用代码管理Engine Vuforia，例如从某些密钥存储设置许可证密钥或禁用某些场景的设备跟踪：

        • VuforiaConfiguration.Instance.Vuforia.LicenseKey = "myLicenseKey";
          VuforiaConfiguration.Instance.DeviceTracker.AutoInitAndStartTracker = false;
          

      • 在程序运行之前，除了在Unity编辑器中覆盖管理Vuforia Engine，也可以在在代码中覆盖管理。

3、在代码中覆盖管理Vuforia Engine：

1、在某些情况下，有必要在Vuforia引擎生命周期的某一处执行Vuforia Engine相关代码。比如：

• Vuforia引擎尝试初始化后检查初始化错误
• 在运行时创建观察者Observer以跟踪目标或在Vuforia Engine启动后访问观察者Observer的属性
• 在Vuforia引擎启动后设置特定的摄像头聚焦模式
• Vuforia引擎完全停止或取消初始化后删除应用程序级资源

2、VuforiaApplication实例为所有这些生命周期事件提供回调，可以从应用程序级脚本订阅它们：

• Vuforia Engine已初始化：订阅VuforiaApplication.Instance.OnVuforia initialized以运行需要初始化Vuforia引擎的代码：

void Awake()
{
    VuforiaApplication.Instance.OnVuforiaInitialized += OnVuforiaInitialized;
}
void OnVuforiaInitialized(VuforiaInitError error)
{
    if (error != VuforiaInitError.NONE)
    {
        // Handle initialization errors
    }
}

• Vuforia Engine已启动：订阅OnVuforiaStarted以在Vuforia启动后运行事件

void Start()
{
    //订阅OnVuforiaStarted事件
    VuforiaApplication.Instance.OnVuforiaStarted += OnVuforiaStarted;
}
void OnVuforiaStarted()
{
    // turn device flashlight on 在Vuforia启动后打开设备手电筒
    VuforiaBehaviour.Instance.CameraDevice.SetFlash(true);
}

• Vuforia Engine已停止：订阅OnVuforiaStopped 以在Vuforia停止后运行事件

  void Start()
  {
       VuforiaApplication.Instance.OnVuforiaStopped += OnVuforiaStopped;
  }
  

• Vuforia Engine已暂停或恢复：通过将VuforiaBehaviour组件设置为disabled暂停Vuforia Engine和跟踪活动，并通过将其设置为enabled恢复AR跟踪体验。

VuforiaBehaviour.Instance.enabled

        不应使用OnVuforiaDeinitialized，因为会破坏包括注册目标在内的存储资源

• 订阅OnVuforiaPaused 可在Vuforia暂停或恢复后运行事件，比如为了在应用程序暂停后再次设置特定的焦点模式：

  void Start()
  {
       VuforiaApplication.Instance.OnVuforiaPaused += OnVuforiaPaused;
  }
  void OnVuforiaPaused(bool paused)
  {
      if (!paused)
          // set focus to infinity:将焦点设置为无穷大
          VuforiaBehaviour.Instance.CameraDevice.SetFocusMode(FocusMode.FOCUS_MODE_INFINITY);
  }
  

• Vuforia Engine已取消初始化：使用subscriber方法订阅OnVuForiIAdeInitialized，以终止VuforiaBehaviour和所有跟踪操作。Vuforia引擎解除初始化时，应执行诸如设置文件驱动程序或fusion provider程序之类的事件。

  void Start()
  {
      VuforiaApplication.Instance.OnVuforiaDeinitialized += OnVuforiaDeinitialized;
  }
  void OnVuforiaDeinitialized()
  {
      FusionProviderOption fusionProviderOption = FusionProviderOption.PREFER_PLATFORM_FUSION_PROVIDER;
      /* Set VuforiaFusionProvider */
      VuforiaApplication.Instance.Initialize(fusionProviderOption);
  }
  

  4、在Unity中管理Vuforia Engine State：

1、在Unity中，Vuforia Engine会每帧自动更新所有Target和Observer的当前观察状态State。对Unity场景的更改（如目标位置）会自动应用到State。因此，手动检索更新不需要特定的API调用。

2、对于某些需求，在Vuforia Engine每帧更新State后运行你的应用程序逻辑非常重要。如：

• 根据两个目标的最新位置计算它们之间的距离
• 从VuforiaBehaviour.Instance.World.IlluminationData访问照明数据
• 从VuforiaBehaviour.Instance.CameraDevice.GetCameraImage（…）访问最新的camera image

3、出于这些目的，请使用OnStateUpdated。

• 详情参见Vuforia核心示例中的AmbientLightManager.cs(处理照明值)或reference API.
• AmbientLightManager.cs在官方案例中

void Start()
{
    //订阅OnStateUpdated事件
    VuforiaBehaviour.Instance.World.OnStateUpdated += OnStateUpdated;
}
void OnStateUpdated()
{
    /* Get IlluminationData when ARKit is used by Vuforia Fusion */
    //当Vuforia Fusion使用ARKit来获取照明数据时
    float intensity = VuforiaBehaviour.Instance.World.IlluminationData.AmbientIntensity.Value;
    float temperature = VuforiaBehaviour.Instance.World.IlluminationData.AmbientColorTemperature.Value;
    /* Get IlluminationData when ARCore is used by Vuforia Fusion */
    //当Vuforia Fusion使用ARCore来获取照明数据时
    Vector4 colorCorrection = VuforiaBehaviour.Instance.World.IlluminationData.ColorCorrection.Value;
    float intensityCorrection = VuforiaBehaviour.Instance.World.IlluminationData.IntensityCorrection.Value;
}

 5、创建Observer：

1、作为在Unity Editor中使用Vuforia游戏对象设置Target的替代方法，可以使用ObserverFactory类在运行时加载和观察Target。它的成员函数都采用不同数量的重载来创建Target。例如，从设备数据库创建图像目标如下所示：

var mImageTarget = VuforiaBehaviour.Instance.ObserverFactory.CreateImageTarget(
            "Vuforia/VuforiaMars_Images.xml ",
            "Astronaut");

使用true和false激活和停用Target：

mImageTarget.enabled = true;

6、检索Target Status和Status Info：

1. 注意Status不是State，Vuforia中State是归于Engine所有的，用来保存Observer观察到的Observation
2. 默认情况下，Target在被跟踪到的同时会进行渲染增强。DefaultObserverEventHandler是Vuforia提供的组件，它提供了一个接口，用于将操作添加到On-Target Found（当找到Target）和On-Target Lost（当丢失Target）——当找到Target或者丢失Target时执行代码
3. 开发人员可以实现自己的自定义事件处理程序脚本，并更改这些事件以实现自定义行为。

        

        4.Target Status(目标状态)：可以直接注册特定于Observer的状态更改事件，并直接评估当前状态：

ObserverBehaviour modelTargetBehaviour;
void Start()
{
    //注册OnTargetStatusChanged事件
    modelTargetBehaviour.OnTargetStatusChanged += OnTargetStatusChanged;
}

//OnTargetStatusChanged：当Target状态发生改变
//需要传递观察这个Target的Observer的ObserverBehaviour组件对象以及这个Target的状态TargetStatus对象
void OnTargetStatusChanged(ObserverBehaviour observerbehavour, TargetStatus status)
{
    //当Target状态是“已追踪到”并且状态信息正常，则执行……
    if (status.Status == Status.TRACKED && status.StatusInfo == StatusInfo.NORMAL)
    {
        // ...
    }
}

 7、设备跟踪管理：

1. Device Pose Observer：设备姿态观测器The Device Pose Observer用于跟踪设备在环境中的运动，并为观察到的目标提供扩展跟踪Extended Tracking。
2. 可在Vuforia配置中启用设备姿势跟踪device pose tracking，或在运行时使用enabled和Reset（）函数对其进行控制：

                

VuforiaBehaviour.Instance.DevicePoseObserver.enabled = true;

        3.Device Pose Observer提供附加状态信息，这些信息根据设备平台类型（ARKit、ARCore）和设备类型（手持设备、眼镜）的不同而不同。有关详细信息，请参见 Target Poses and Status Info

VuforiaBehaviour.Instance.DeviceBehaviour.OnTargetStatusChanged += OnDevicePoseStatusChanged;

8、将内容附加到Target：

1. 随着Vuforia Engine启动，应用会加载并观察Target，可以在运行时将内容作为子对象添加到Target游戏对象。下面的脚本演示了一个简单的方法，用于在运行时将预制游戏对象添加到从DefaultObserverEventHandler脚本继承的目标上的父目标：
   • 在Unity项目中，创建一个名为MyInstanceor的新脚本
   • 复制下面的代码并保存文件
   • 在场景中，从菜单GameObject->Vuforia Engine->添加Vuforia目标游戏对象
   • 从GameObject中删除现有的DefaultObserverEventHandler组件
   • 将MyPrefactInstancer添加到目标游戏对象
   • 创建一个预置或使用现有预置并将其提交到MyModelPrefact字段
   • 在设备上或在运行模式下测试目标

using UnityEngine;
using Vuforia;

public class MyPrefabInstantiator : DefaultObserverEventHandler
{
    ImageTargetBehaviour mImageTarget;//图像目标行为对象
    public GameObject myModelPrefab;//附加到图片目标的内容Content
 
    //重写OnTrackingFound方法，当追踪到目标时，执行InstantiateContent方法
    protected override void OnTrackingFound()
    {
        InstantiateContent();
    }
 
    //如果myModelPrefab（内容）为空，则实例化内容
    //设置myModelPrefab实例化对象为图像目标的子对象
    //设置myModelPrefab的位置，方向与大小
    //激活myModelPrefab
    void InstantiateContent()
    {
        if (myModelPrefab != null)
        {
            GameObject myModelTrf = Instantiate(myModelPrefab);
            myModelTrf.transform.parent = mImageTarget.transform;
            myModelTrf.transform.localPosition = new Vector3(0f, 0f, 0f);
            myModelTrf.transform.localRotation = Quaternion.identity;
            myModelTrf.transform.localScale = new Vector3(0.1f, 0.1f, 0.1f);
            myModelTrf.transform.gameObject.SetActive(true);
        }
   }
}

9、Error Handling错误处理：

• 使用VuforiaInitError确保Vuforia Engine已正确初始化，如DefaultInitializationHandler脚本中所示：

  void Start()
  {
      //注册OnVuforiaInitialized事件
      VuforiaApplication.Instance.OnVuforiaInitialized += OnVuforiaInitialized;
  }
  
  //当Vuforia引擎实例化时
  void OnVuforiaInitialized(VuforiaInitError error)
  {
      //如果vuforia传递过来的VuforiaInitError--Vuforia实例化错误引用error不为空，说明Vuforia实例化出错，执行错误处理代码
      if(error != VuforiaInitError.NONE)
      {
          // Error handling code
      }
  }