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.SpecificTarget 时 ARSession.CenterObject 将被设成这个物体。可随时修改,立即生效。
该物体必须包含以下任一组件: TargetController , SparseSpatialMapRootController 或 Scene.BlockRootController 。
CenterObject¶
- C#
public GameObject CenterObject { get; }
这个session在当前帧使用的中心物体。
这个物体表示在Unity空间中不运动的物体或这个物体的父节点。它可能是 ARSession.Origin , ARAssembly.Camera 或某个 target 。 Target 可以是包含以下任一组件的物体: 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的 ARSession 及 XR 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继承自 ExternalDeviceFrameSource 且 ExternalDeviceFrameSource.OriginType 为 ExternalDeviceFrameSource.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.CenterMode 为 ARSession.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¶
从屏幕坐标系([0, 1]^2)变换到图像坐标系([0, 1]^2)。 pointInView 需要被归一化到[0, 1]^2。头显上不可用。