ARSession Class

Description

在场景中控制AR会话的 MonoBehaviour 。一个会话包含一组组装成 ARAssembly 的组件,并控制整个生命周期的数据流。这个组件是AR的入口。同一时刻不允许出现多个active的实例。

EasyAR组件的所有功能必须在 ARSession.StartSession 之后才能使用。

Camera 和一部分AR组件之间的相对transform是受session控制的,其中的一个物体被称为 ARSession.CenterObject ,它在场景中不动,其它物体相对这个 ARSession.CenterObject 运动。这个物体是根据 ARSession.CenterMode 的数值进行选择的。更详细的说明可以查看 ARSession.ARCenterMode 的描述。


Enums

public enum ARSession.ARCenterMode

AR中心模式。

public enum ARSession.ARHorizontalFlipMode

水平镜像渲染模式。

public enum ARSession.SessionState

Session的状态。


Classes

public class ARSession.FlipOptions

镜像渲染选项。


MonoBehaviour Messages

private void Awake()

private void OnEnable()

private void Start()

private void Update()

private void OnDisable()

private void OnDestroy()


Fields

AutoStart

C#

public bool AutoStart

MonoBehaviour .Start时自动启动session。如果设置为false,你需要手动调用 ARSession.StartSession 来启动session。

CenterMode

C#

public ARSession.ARCenterMode CenterMode

AR中心模式。可随时修改,立即生效。如果指定的模式不可用,它将会被自动修改为可用的模式。

HorizontalFlip

C#

public ARSession.FlipOptions HorizontalFlip

水平镜像渲染模式。可随时修改,立即生效。仅在使用图像或物体跟踪时可用。


Properties

SpecificTargetCenter

C#

public GameObject SpecificTargetCenter { get; set; }

手动指定的中心物体。 ARSession.CenterMode == ARSession.ARCenterMode.SpecificTargetARSession.CenterObject 将被设成这个物体。可随时修改,立即生效。

该物体必须包含以下任一组件: TargetController , SparseSpatialMapRootController 或 Scene.BlockRootController 。

CenterObject

C#

public GameObject CenterObject { get; }

这个session在当前帧使用的中心物体。

这个物体表示在Unity空间中不运动的物体或这个物体的父节点。它可能是 ARSession.OriginARAssembly.Camera 或某个 targetTarget 可以是包含以下任一组件的物体: TargetController , SparseSpatialMapRootController 或 Scene.BlockRootController 。在使用稀疏空间地图和EasyAR Mega的时候,实际的中心 GameObject 是root节点下具体定位到的map或block物体, ARSession.CenterObject 是这个物体的父节点。更详细的说明可以查看 ARSession.ARCenterMode 的描述。

Assembly

C#

public ARAssembly Assembly { get; }

AR组件的组装体。

Diagnostics

C#

public DiagnosticsController Diagnostics { get; }

Session诊断组件。

DisplayCompensation

C#

public Quaternion DisplayCompensation { get; }

当前帧的显示补偿旋转。

AvailableCenterMode

C#

public IReadOnlyList< ARSession.ARCenterMode > AvailableCenterMode { get; }

当前session可用的中心模式。

Origin

C#

public GameObject Origin { get; }

It will be selected from the scene or created by EasyAR or 3rdparty frame source extension automatically. XROrigin from Unity XR framework will be selected if built-in frame source is used. Only XR Origin in default tree layout will be selected if AR Foundation package not exist.

在任一运动跟踪功能运行时的session原点。

它将会从场景中被自动选择,如果不存在则会由EasyAR或第三方frame source扩展创建。使用内置frame source时,如果Unity XR框架的XROrigin存在,它会被选择。如果AR Foundation的包不存在,保持默认树结构的XR Origin才会被选择。

TrackingStatus

C#

public Optional< MotionTrackingStatus > TrackingStatus { get; }

在任一运动跟踪功能运行时的运动跟踪状态。

AssembleOptions

C#

public AssembleOptions AssembleOptions { get; }

Session 的组装选项,需要在 ARSession.Assemble (如果之前没有调用, ARSession.StartSession 会隐式调用)前设置。

AutoUnityXRSwitch

C#

public bool AutoUnityXRSwitch { get; }

自动切换Unity XR(比如AR Foundation)物体。需要在Unity编辑器中设置。在Android头显上使用AR Foundation或Unity XR Interaction Toolkit时需要关闭此选项(使用Pico会自动关闭)。

如果你需要在运行时自动切换AR Foundation,你需要通过Unity的右键菜单在场景中创建AR Foundation的 ARSessionXR Origin ,并使用AR Foundation的相机。

编辑时, ARSession 会自动禁用AR Foundation的ARSession(也可以手动禁用)。

运行时, ARSession 会在awake时禁用所有Unity XR Core组件及AR Foundation的组件。

运行时,如果被选择的frame source继承自 ARFoundationFrameSource ,则被禁用的Unity XR Core组件及AR Foundation组件将在 ARSession.StartSession 时启用(未被EasyAR禁用的不会启用)。如果被选择的frame source继承自 ExternalDeviceFrameSourceExternalDeviceFrameSource.OriginTypeExternalDeviceFrameSource.DeviceOriginType.XROrigin ,则被禁用的Unity XR Core组件将在 ARSession.StartSession 时启用(未被EasyAR禁用的不会启用)。如果其他frame source被选择,则在 ARSession.StartSession 时会禁用所有Unity XR Core组件及AR Foundation的组件。

运行时,所有Unity XR Core组件及AR Foundation的组件会在 ARSession.StopSession 时禁用。

如果你需要自己控制这些组件的切换,请确保在编辑器中关闭该选项。

需要注意,XR Interaction Toolkit的组件不受该选项控制,但其在EasyAR中是否可用未经验证。理论上对于只使用XROrigin GameObject和其Camera的功能应该可以正常使用,但你可能需要设置 ARSession.CenterModeARSession.ARCenterMode.SessionOrigin 。如果功能不正常,你需要自己管理XR Interaction Toolkit的组件,在frame source不是继承自 ARFoundationFrameSource 时禁用相关组件。

Report

C#

public SessionReport Report { get; }

Session 报告。它在assemble完成后可用查看,且会在session状态改变时更新。它用于查看session损坏的详细信息或组件可用性等详细信息。

State

C#

public ARSession.SessionState State { get; }

当前session的状态。


Events

StateChanged

C#

public event Action< ARSession.SessionState > StateChanged

session ARSession.State 改变的事件。

AssembleUpdate

C#

public event Action< SessionReport.AvailabilityReport > AssembleUpdate

session ARSession.Assemble 更新事件。在一次 ARSession.Assemble (如果之前没有调用, ARSession.StartSession 会隐式调用)中这个事件会被触发1-2次。其中第一次是Assemble完成时。如果Assemble完成时设备列表更新已经完成将不会有第二次调用,否则第二次调用将在设备列表更新完成时发生。

InputFrameUpdate

C#

public event Action< InputFrame > InputFrameUpdate

输入帧更新事件,仅在session显示的 InputFrame 产生变化时触发。头显上不会收到此事件,且如果存在透视图像,其渲染由设备完成。

PostSessionUpdate

C#

public event Action PostSessionUpdate

Session更新完成事件,该事件频率和 MonoBehaviour .Update频率相同(在头显上需要扩展作者正确实现)。在该事件触发时,该帧内所有受EasyAR控制的transform变化已经完成。


Methods

StartSession

C#

public void StartSession()

启动session。如果 ARSession.AutoStart 是true,它会在 MonoBehaviour .Start中自动调用。

Assemble

C#

public System.Collections.IEnumerator Assemble()

使用 ARSession.AssembleOptions 组装session。如果调用过,它会在 ARSession.StartSession 中自动调用。

StopSession

C#

public void StopSession(bool keepLastFrame)

停止启动session。所有transform更新和图像渲染更新将会停止。你可用旋转在停止时保留最后一帧图像,但只能在EasyAR控制图像渲染时有效(AR Foundation和头显等无效)。

ImageCoordinatesFromScreenCoordinates

C#

public Optional< Vector2 > ImageCoordinatesFromScreenCoordinates( Vector2 pointInView)

从屏幕坐标系([0, 1]^2)变换到图像坐标系([0, 1]^2)。 pointInView 需要被归一化到[0, 1]^2。头显上不可用。