为__空间映射__提供的低级 API 为复杂系统带来了非常精细的控制。
下面列出的常见使用模式可能很有用：
__空间映射__低级 API 最重要的成员是 SurfaceObserver。此成员可用于深入了解设备对现实世界的理解。
SurfaceObserver 描述世界中的体积，并报告添加、更新或删除了哪些__表面__。应用程序随后可以在有或没有物理碰撞数据的情况下异步请求网格数据。请求完成后，另一个回调会通知应用程序这些数据已就绪。
SurfaceObserver 提供以下基本功能：
1.根据__表面__更改（例如添加、删除和更新）按需发出回调。 1.提供一个接口来请求与已知__表面__相对应的网格数据。 1.当请求的网格数据已可供使用时发出回调。 1.提供定义 SurfaceObserver 的位置和体积的方式。
另一个重要的移动部分是 SurfaceData 对象。此对象包含构建和报告__表面__网格数据所需的所有信息。
填充的 SurfaceData 在 RequestMeshAsync 调用中传递给系统。当网格数据准备就绪时，在请求时提供的“数据就绪”回调中会返回匹配的 SurfaceData。因此，应用程序可以精确确定数据对应的__表面__，不存在任何歧义。
应该根据应用程序所需的信息填充 SurfaceData 游戏对象。这包括传入：
当使用配置有误的 SurfaceData 来调用 RequestMeshAsync 方法时，系统会抛出参数异常。请注意，即使 RequestMeshAsync 没有抛出参数异常，也无法保证创建和返回网格数据。
此示例演示了此 API 的基本用法。
using UnityEngine;
using UnityEngine.XR;
using UnityEngine.XR.WSA;
using UnityEngine.Rendering;
using UnityEngine.Assertions;
using System;
using System.Collections;
using System.Collections.Generic;
public enum BakedState {
NeverBaked = 0,
Baked = 1,
UpdatePostBake = 2
}
// 保留用于确定表面烘焙优先级的数据。
class SurfaceEntry {
public GameObject m_Surface; // 与此表面对应的游戏对象
public int m_Id; // 此表面的 ID
public DateTime m_UpdateTime; // 系统报告的更新时间
public BakedState m_BakedState;
public const float c_Extents = 5.0f;
}
public class SMSample : MonoBehaviour {
// 此观察者是了解空间映射世界的窗口。
SurfaceObserver m_Observer;
// 此字典包含一组已知的空间映射表面。
//定期会更新、添加和删除表面。
Dictionary<int, SurfaceEntry> m_Surfaces;
//这是绘制烘焙表面时使用的材质。
public Material m_drawMat;
// 使用此标志在烘焙正在进行时推迟请求。烘焙网格
// 数据可能需要经过多个帧。此示例基于表面数据表面
// 确定烘焙请求顺序的优先级，并仅在
// 未处理请求时才发出新请求。
bool m_WaitingForBake;
//这是最后一次更新 SurfaceObserver。其更新间隔
// 不超过每两秒钟，因为这样做可能非常耗时。
float m_lastUpdateTime;
void Start () {
m_Observer = new SurfaceObserver ();
m_Observer.SetVolumeAsAxisAlignedBox (new Vector3(0.0f, 0.0f, 0.0f),
new Vector3 (SurfaceEntry.c_Extents, SurfaceEntry.c_Extents, SurfaceEntry.c_Extents));
m_Surfaces = new Dictionary<int, SurfaceEntry> ();
m_WaitingForBake = false;
m_lastUpdateTime = 0.0f;
}
void Update () {
//避免在 SurfaceObserver 上过于频繁调用 Update。
if (m_lastUpdateTime + 2.0f < Time.realtimeSinceStartup) {
//此代码块使观察体跟随摄像机。
Vector3 extents;
extents.x = SurfaceEntry.c_Extents;
extents.y = SurfaceEntry.c_Extents;
extents.z = SurfaceEntry.c_Extents;
m_Observer.SetVolumeAsAxisAlignedBox (Camera.main.transform.position, extents);
try {
m_Observer.Update (SurfaceChangedHandler);
} catch {
//如果指定的回调错误，Update 可抛出异常。
Debug.Log ("Observer update failed unexpectedly!");
}
m_lastUpdateTime = Time.realtimeSinceStartup;
}
if (!m_WaitingForBake) {
//设定从高到低的优先级为旧添加、其他添加和更新。
SurfaceEntry bestSurface = null;
foreach (KeyValuePair<int, SurfaceEntry> surface in m_Surfaces) {
if (surface.Value.m_BakedState != BakedState.Baked) {
if (bestSurface == null) {
bestSurface = surface.Value;
} else {
if (surface.Value.m_BakedState < bestSurface.m_BakedState) {
bestSurface = surface.Value;
} else if (surface.Value.m_UpdateTime < bestSurface.m_UpdateTime) {
bestSurface = surface.Value;
}
}
}
}
if (bestSurface != null) {
//填写并分发请求。
SurfaceData sd;
sd.id.handle = bestSurface.m_Id;
sd.outputMesh = bestSurface.m_Surface.GetComponent<MeshFilter> ();
sd.outputAnchor = bestSurface.m_Surface.GetComponent<WorldAnchor> ();
sd.outputCollider = bestSurface.m_Surface.GetComponent<MeshCollider> ();
sd.trianglesPerCubicMeter = 300.0f;
sd.bakeCollider = true;
try {
if (m_Observer.RequestMeshAsync(sd, SurfaceDataReadyHandler)) {
m_WaitingForBake = true;
} else {
//请求网格时返回值 false
// 通常表示指定的
// 表面 ID 无效。
Debug.Log(System.String.Format ("Bake request for {0} failed.Is {0} a valid Surface ID?", bestSurface.m_Id));
}
}
catch {
//如果未正确填入数据结构，请求可能会
// 失败。
Debug.Log (System.String.Format("Bake for id {0} failed unexpectedly!", bestSurface.m_Id));
}
}
}
}
//此处理程序在表面更改时接收事件，并使用 SurfaceObserver 上的
// Update 方法传播这些事件。
void SurfaceChangedHandler (SurfaceId id, SurfaceChange changeType, Bounds bounds, DateTime updateTime) {
SurfaceEntry entry;
switch (changeType) {
case SurfaceChange.Added:
case SurfaceChange.Updated:
if (m_Surfaces.TryGetValue(id.handle, out entry)) {
// 如果已烘焙此表面，应将其标记为在更新时间外
// 也需要烘焙，因此"下一个要烘焙的表面"逻辑
// 会对其进行正确排序。
if (entry.m_BakedState == BakedState.Baked) {
entry.m_BakedState = BakedState.UpdatePostBake;
entry.m_UpdateTime = updateTime;
}
} else {
// 这是一个全新的表面，所以为其创建一个条目。
entry = new SurfaceEntry ();
entry.m_BakedState = BakedState.NeverBaked;
entry.m_UpdateTime = updateTime;
entry.m_Id = id.handle;
entry.m_Surface = new GameObject (System.String.Format("Surface-{0}", id.handle));
entry.m_Surface.AddComponent<MeshFilter> ();
entry.m_Surface.AddComponent<MeshCollider> ();
MeshRenderer mr = entry.m_Surface.AddComponent<MeshRenderer> ();
mr.shadowCastingMode = ShadowCastingMode.Off;
mr.receiveShadows = false;
entry.m_Surface.AddComponent<WorldAnchor> ();
entry.m_Surface.GetComponent<MeshRenderer> ().sharedMaterial = m_drawMat;
m_Surfaces[id.handle] = entry;
}
break;
case SurfaceChange.Removed:
if (m_Surfaces.TryGetValue(id.handle, out entry)) {
m_Surfaces.Remove (id.handle);
Mesh mesh = entry.m_Surface.GetComponent<MeshFilter> ().mesh;
if (mesh) {
Destroy (mesh);
}
Destroy (entry.m_Surface);
}
break;
}
}
void SurfaceDataReadyHandler(SurfaceData sd, bool outputWritten, float elapsedBakeTimeSeconds) {
m_WaitingForBake = false;
SurfaceEntry entry;
if (m_Surfaces.TryGetValue(sd.id.handle, out entry)) {
// 这两个断言要检查返回的过滤器和 WorldAnchor
// 是否与用于请求数据的对应项相同。除非更改了代码
// 来替换或销毁它们，否则这应该始终为 true。
Assert.IsTrue (sd.outputMesh == entry.m_Surface.GetComponent<MeshFilter>());
Assert.IsTrue (sd.outputAnchor == entry.m_Surface.GetComponent<WorldAnchor>());
entry.m_BakedState = BakedState.Baked;
} else {
Debug.Log (System.String.Format("Paranoia: Couldn't find surface {0} after a bake!", sd.id.handle));
Assert.IsTrue (false);
}
}
}
请注意，调用 Update 方法可能是资源密集型操作，因此调用次数不尽超出应用程序的请求频度。对于大多数用例来说，每三秒调用一次 Update 应该就足够了。