一个可以让你通过RealityKit来展示AR体验的视图


声明

@objc class ARView : ARViewBase

概述

视同一个ARView实例来为用户展示渲染好的3D图形。你通常会添加一个单一视图到你的app的storyboard,然后会在你的代码里为这个视图添加outlet。或者,你可以通过编程在运行时创建并添加一个视图到你的视图层级,同样适用于其他视图。

一个视图拥有一个单一Scene 实例,你可以通过只读的scene 属性来访问这个实例。你通过添加一个或多个AnchorEntity 实例来告知视图的AR会话如何将虚拟内容拴在真实世界的某物体上。对每个锚点来说,你通过附加一些列层级的其他Entity 实例便构建了场景的内容。

此外,你同样可以使用视图来做如下事情:

  • 配置渲染选项,环境特征,和摄像头模式
  • 处理平台适用的用户交互,交互形式如鼠标、键盘或者手势输入
  • 在视图的指定点找到实体
  • 通过访问数据统计和成像来帮助你调试你的app

主题

创建一个视图(### Creating a View)

init(frame: CGRect) 通过特定的维度来创建一个AR视图

init(frame: CGRect, cameraMode: ARView.CameraMode, automaticallyConfigureSession: Bool) 通过特定的维度、摄像头模式和会话配置状态来创建一个AR视图

init?(coder: NSCoder) 通过一个给出的解码器中的数据来初始化一个AR视图

typealias ARViewBase RealityKit将内容呈现到的视图的特定于平台的基类。

init(frame: CGRect, cameraMode: ARView.CameraMode) 通过特性的维度和摄像头模式来创建一个AR视图。【废弃】


处理场景(Working with the Scene)

var scene: Scene 视图渲染和模拟的场景

class Scene 一个保存AR视图渲染的一系列实体的容器

声明
class Scene
概述

你无法直接创建一个场景实例。取而代之的是,你只能获得一个也是唯一一个与来自于ARView实例的scene 属性的视图相关联的场景实体。

为了添加内容到视图的场景,首先你需要添加一个或多个AnchorEntity 实例到场景的anchors 列表中。锚点列表告知RealityKit如何将虚拟内容绑定到真实世界物体上,例如平整的表面或者图像。接下来你便可以为每一个锚点添加一系列其他Entity 实例的层级结构,从而告知RealityKit在一个给出的锚点点上渲染内容时所欲需要的几何形状和行为。

概述
  • 识别场景(Identifying the Scene)

var name: String 场景名称

var id: ObjectIdentifier 与self相关的实体的稳定ID。当Self符合AnyObject类型时

var id: UInt64 场景的稳定ID

typealias Scene.ID 场景使用的唯一标识符类型

  • 添加和移除锚点(Adding and Removing Anchors)

var anchors: Scene.AnchorCollection 场景包含的锚点列表

func addAnchor(HasAnchoring) 向场景的锚点列表添加一个锚点

func removeAnchor(HasAnchoring) 从场景中移除一个指定的锚点

struct Scene.AnchorCollection 锚点实体的列表

  • 找到实体(Finding Entities)

func findEntity(named: String) -> Entity? 通过一个给出的名称搜索场景的锚点实体层级结构并找到该实体。

  • 检测交点(Detecting Intersections)

func raycast(origin: SIMD3<Float>, direction: SIMD3<Float>, length: Float, query: CollisionCastQueryType, mask: CollisionGroup, relativeTo: Entity?) -> [CollisionCastHit] 对场景中的所有几何图形释放凸射线投射,该射线使用了给出的原点、方向和长度

func raycast(from: SIMD3<Float>, to: SIMD3<Float>, query: CollisionCastQueryType, mask: CollisionGroup, relativeTo: Entity?) -> [CollisionCastHit]

对场景中的所有几何图形释放凸射线投射,该射线存在于两个节点之间

func convexCast(convexShape: ShapeResource, fromPosition: SIMD3<Float>, fromOrientation: simd_quatf, toPosition: SIMD3<Float>, toOrientation: simd_quatf, query: CollisionCastQueryType, mask: CollisionGroup, relativeTo: Entity?) -> [CollisionCastHit]

对场景中的所有几何图形释放凸形状射线

struct CollisionCastHit 碰撞射线的撞击结果

enum CollisionCastQueryType 你可以实现的射线和凸形状释放请求的类型

struct CollisionGroup 定义了一个实体所属的碰撞组,和该实体可用来实现碰撞的碰撞组的bitmask

  • 设备之间同步实体(Synchronizing Entities Between Devices)

var synchronizationService: SynchronizationService? 用来进行网络同步的服务

protocol SynchronizationService 在本地的一组节点中启用了实体同步的一个接口

  • 接收和发送事件(Getting and Sending Events)

func publisher<E>(for: E.Type, on: EventSource?) -> Scene.Publisher<E> 为特性类型的事件生成一个发布者

func subscribe<E>(to: E.Type, on: EventSource?, (E) -> Void) -> Cancellable 接收指定类型的事件

struct Scene.Publisher 场景中指定事件类型的发布者

enum SceneEvents 场景触发的事件

enum AnimationEvents 被RealityKit动画系统触发的事件

enum AudioEvents 声音回放相关的事件

enum CollisionEvents 碰撞相关的事件

protocol Event 一个可以被作为事件发送的类型

protocol EventSource 一个可以可以被事件发送和订阅的类型

  • 比较场景

static func == (Scene, Scene) -> Bool 表示两个场景是否相同

static func != (Scene, Scene) -> Bool 表示两个场景是否不相同

func hash(into: inout Hasher) 通过将场景的必要组件作为参数传入散列函数来对其进行散列计算

var hashValue: Int 场景的散列值

配置AR会话(Configuring the AR Session)

var session: ARSession 支撑视图渲染的AR会话

var automaticallyConfigureSession: Bool 是否使用自动配置的AR会话的布尔值

var renderOptions: ARView.RenderOptions 配置视图的AR会话的渲染可选项

struct ARView.RenderOptions 你使用来有选择的禁用特定渲染效果的可用渲染可选项

提供环境上下文(Providing Environmental Context)

var environment: ARView.Environment 视图的背景、光照和声学属性

struct ARView.Environment 视图内容的背景、光照和声学属性的描述

var physicsOrigin: Entity? 定义了场景物理模拟的原点的实体

var audioListener: Entity? 定义了空间声音的监听者位置和方向的实体

管理摄像头(Managing the Camera)

var cameraMode: ARView.CameraMode 一个用来在AR会话所使用的摄像头和虚拟摄像头之间进行选择的设置

enum ARView.CameraMode 可用的摄像头模式

var cameraTransform: Transform 当前激活的摄像头的变换

在视图中的点上寻找实体(Finding Entities at a Point in the View)

func entity(at: CGPoint) -> Entity? 在AR场景中找到离指定点最近的一个实体

func entities(at: CGPoint) -> [Entity] 在AR场景中找到指定点附近的一系列实体

func hitTest(CGPoint, query: CollisionCastQueryType, mask: CollisionGroup) -> [CollisionCastHit] 基于查询请求和一个碰撞掩码在视图中搜索与一个点对应的物体

func hitTest(CGPoint, types: ARHitTestResult.ResultType) -> [ARHitTestResult] 基于一系列结果类型在视图中搜索与一个点对应的物体

func makeRaycastQuery(from: CGPoint, allowing: ARRaycastQuery.Target, alignment: ARRaycastQuery.TargetAlignment) -> ARRaycastQuery? 创建一个源于视图中,摄像头视图域中心的某个点的射线投射查询

func raycast(from: CGPoint, allowing: ARRaycastQuery.Target, alignment: ARRaycastQuery.TargetAlignment) -> [ARRaycastResult] 创建一个射线投射,该射线是从摄像头中心闯过视图中的一个点进入场景的,并且会立即得到结果的返回。

func trackedRaycast(from: CGPoint, allowing: ARRaycastQuery.Target, alignment: ARRaycastQuery.TargetAlignment, updateHandler: ([ARRaycastResult]) -> Void) -> ARTrackedRaycast? 创建一个可追踪的射线投射,该射线是从摄像头中心闯过视图中的一个点进入场景的

为实体添加手势识别

func installGestures(ARView.EntityGestures, for: HasCollision) -> [EntityGestureRecognizer] 为指定的实体加装标准手势,并配置成同步识别

struct ARView.EntityGestures 一系列可能的实体手势识别方法

func gestureRecognizer(UIGestureRecognizer, shouldRecognizeSimultaneouslyWith: UIGestureRecognizer) -> Bool 确定两个手势识别方法是可以否同时识别一个手势的布尔值

class EntityRotationGestureRecognizer 手势识别方法,它使用涉及两次触摸的旋转手势来旋转给定实体

class EntityScaleGestureRecognizer 手势识别方法,它使用一个捏的手势来缩小或者缩放给定实体

class EntityTranslationGestureRecognizer 手势识别方法,它使用一个平移的手势来移动一个实体

protocol EntityGestureRecognizer 在实体上工作的手势识别方法的类型

坐标系之间的映射(Mapping Between Coordinate Spaces)

func project(SIMD3<Float>) -> CGPoint? 从场景中的3D世界坐标系中的一个点投射到视图中的2D像素坐标系中

func unproject(CGPoint, ontoPlane: float4x4) -> SIMD3<Float>? 映射一个视图坐标系中的一个2D点到3D空间的给定平面上

func unproject(CGPoint, viewport: CGRect) -> SIMD3<Float>? 映射一个像素坐标系给定视口中的2D点到3D坐标空间

func ray(through: CGPoint) -> (origin: SIMD3<Float>, direction: SIMD3<Float>)? 明确一个穿过视图2D空间中给定的点的射线的位置和方向

处理触摸输入(Handling Touch Input)

func touchesBegan(Set<UITouch>, with: UIEvent?) 告知视图,发生了一个或多个触摸事件

func touchesMoved(Set<UITouch>, with: UIEvent?) 告知视图,与某个事件相关的一个或多个触摸事件发生了变化

func touchesEnded(Set<UITouch>, with: UIEvent?) 告知视图,一个或多个手指从视图中离开了

func touchesCancelled(Set<UITouch>, with: UIEvent?) 告知视图,一个系统事件(例如系统警告)取消了一个触摸序列

处理键盘输入(Handling Keyboard Input)

var acceptsFirstResponder: Bool 表示视图是否接受首次相应者状态的布尔值

func keyDown(with: NSEvent) 告知视图用户按下了一个按键

func keyUp(with: NSEvent) 告知视图用户释放了一个按键

处理鼠标输入(Handling Mouse Input)

func mouseDown(with: NSEvent) 告知视图用户按压了鼠标左键

func mouseDragged(with: NSEvent) 告知视图用户按住鼠标左键的同时移动了鼠标

func mouseUp(with: NSEvent) 告知视图用户松开了鼠标左键

func mouseMoved(with: NSEvent) 告知视图用户移动了鼠标左键

func rightMouseDown(with: NSEvent) 告知视图用户按压了鼠标右键

func rightMouseDragged(with: NSEvent)告知视图用户按住鼠标右键的同时移动了鼠标

func rightMouseUp(with: NSEvent) 告知视图用户松开了鼠标右键

func otherMouseDown(with: NSEvent) 告知视图用户按压了鼠标除了左、右键之外的其他键

func otherMouseDragged(with: NSEvent) 告知视图用户按住鼠标其他键的同时移动了鼠标

func otherMouseUp(with: NSEvent) 告知视图用户松开了鼠标其他键

func scrollWheel(with: NSEvent) 告知视图用户滚动了鼠标滚轮

管理视图(Managing the View)

var frame: NSRect 帧矩形,描述了视图在其超视图坐标系中的位置和大小

var contentScaleFactor: CGFloat 视图中内容的比例因子

func didMoveToSuperview() 告知视图其超级视图已发生变化

func didMoveToWindow() 告知视图其视窗属性已被设置为新的值

func layoutSubviews() 展示所有的子视图

class var layerClass: AnyClass 用来为视图实例创建层的对象

func makeBackingLayer() -> CALayer 创建视图的背后层

func viewDidChangeBackingProperties() 告知视图其背后存储属性发生了变化

func viewDidMoveToSuperview() 告知视图其拥有了一个新的超级视图或者其超级视图已被移除

创建快照(Taking a Snapshot)

func snapshot(saveToHDR: Bool, completion: (ARView.Image?) -> Void) 在iOS设备上为当前视图做快照

func snapshot(saveToHDR: Bool, completion: (ARView.Image?) -> Void) 在macOS设备上为当前视图做快照

typealias ARView.Image 当你做快照时用来展示图像的平台指定类型

A platform-specific type used to represent an image when you take a snapshot.

调试会话(Debugging the Session)

var debugOptions: ARView.DebugOptions 当前的调试可选项

struct ARView.DebugOptions 场景中用来辅助场景调试而绘制叠加内容的可选项

实例方法(Instance Methods)

func gestureRecognizer(UIGestureRecognizer, shouldReceive: UITouch) -> Bool

func layout()