Repository navigation
ARKit iOS xcode27.2 b3
Alex Soto edited this page Oct 17, 2026
·
1 revision
#ARKit.framework
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARAnchor.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARAnchor.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARAnchor.h 2026-08-15 23:02:18
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARAnchor.h 2026-10-04 02:32:28
@@ -15,43 +15,103 @@
@class ARAnchor;
/**
- An anchor object that can be copied from values of an existing anchor.
+ Support for custom anchor subclasses.
+
+ An ``ARAnchor`` (or an instance of any anchor subclass) represents a position and orientation in world space, and optionally associates extra
+ information with that point (like a name, or plane or image detection data). Each time ARKit generates an ``ARFrame`` object (describing the current
+ environment as of a specific frame of live camera video), ARKit updates the ``ARFrame/anchors`` associated with the session as of that moment.
+ Because anchor objects are immutable, ARKit must copy them to make changes from one ``ARFrame`` to the next.
+
+ If you create your own ARAnchor subclass, you must implement the ``init(anchor:)`` initializer required by this protocol. To ensure that any custom
+ information in your subclass is maintained between successive frames, your implementation should copy any custom properties it declares.
*/
API_AVAILABLE(ios(12.0))
@protocol ARAnchorCopying <NSCopying>
/**
- Initializes a new anchor object copying values from an existing anchor.
+ Initializes a new anchor by copying custom information from another anchor.
- This initializer will be called any time copy is called on anchor of this class.
- This method must be implemented for any ARAnchor subclasses that adds properties.
+ Each time ARKit generates a new ``ARFrame`` object (corresponding to an incoming frame of live camera video at 60 fps), ARKit calls this initializer
+ to copy each of the ``ARFrame/anchors`` associated with the previous frame.
- - Parameter anchor: The anchor from which to copy values.
+ > Note:
+ > ARKit always calls this initializer with an `anchor` parameter of the same class as `self`.
- - Returns: An initialized anchor object.
+ If you subclass ``ARAnchor`` to add extra properties, your implementation of this initializer should copy the values of those properties, then chain
+ to the superclass initializer. For example, an AR game might define a `BoardAnchor` class to encode the position and size of a game board, so its
+ version of this initializer would copy that `size` property:
+
+ ```swift
+ required init(anchor: ARAnchor) {
+ let other = anchor as! BoardAnchor
+ self.size = other.size
+ super.init(anchor: other)
+ }
+ ```
+
+ > Important:
+ > Carefully consider performance and your app's data model when storing references to other objects in anchors. Copying custom values might be
+ expensive, but multiple references to the same data might or might not be correct for your app.
+
+ - Parameter anchor: The other anchor from which to copy information.
*/
- (instancetype)initWithAnchor:(ARAnchor *)anchor;
@end
/**
- A real world object or location in the scene that is being tracked.
+ An interface for objects that track the location of real-world objects or locations.
+
+ This protocol is adopted by ARKit classes, such as the ``ARFaceAnchor`` class, that represent moving objects in a scene.
+
+ ARKit automatically manages representations of such objects in an active AR session, ensuring that changes in the real-world object's position and
+ orientation (the ``ARAnchor/transform`` property for anchors) are reflected in corresponding ARKit objects. The ``isTracked`` property indicates
+ whether the current transform is valid with respect to movement of the real-world object.
+
+ Trackable anchor classes affect other ARKit behaviors:
+
+ - The ``ARSession/getCurrentWorldMap(completionHandler:)`` method automatically includes only non-trackable anchors in the ``ARWorldMap`` it creates.
+ (After you create a world map, you can add other anchors to it if you choose.)
+ - ``ARSCNView`` and ``ARSKView`` automatically hide the nodes for anchors whose ``isTracked`` property is
+ <doc://com.apple.documentation/documentation/swift/false>.
+ - World-tracking sessions use non-trackable anchors to optimize tracking quality in the area around each anchor. Trackable anchors do not affect
+ world tracking.
*/
API_AVAILABLE(ios(11.0))
@protocol ARTrackable <NSObject>
/**
- Tracking state of the anchor.
+ A Boolean value that indicates whether the object's transform is valid.
- The `isTracked` value is used to determine the anchor transform's validity. When the object being tracked is no longer detected in the
- camera image, its anchor will return `NO` for `isTracked`.
+ If this value is <doc://com.apple.documentation/documentation/swift/true>, the object's transform currently matches the position and orientation of
+ the real-world object it represents.
+
+ If this value is <doc://com.apple.documentation/documentation/swift/false>, the object is not guaranteed to match the movement of its corresponding
+ real-world feature, even if it remains in the visible scene. When the tracked object is no longer detected in the camera image, its anchor reports
+ `NO` for `isTracked`.
*/
@property (nonatomic, readonly) BOOL isTracked;
@end
/**
- Object representing a physical location and orientation in 3D space.
+ An object that specifies the position and orientation of an item in the physical environment.
+
+ To track the static positions and orientations of real or virtual objects relative to the camera, create anchor objects and use the ``ARSession/add(anchor:)`` method to add them to your AR session.
+
+ > Tip:
+ > Adding an anchor to the session helps ARKit to optimize world-tracking accuracy in the area around that anchor, so that virtual objects appear to stay in place relative to the real world. If a virtual object moves, remove the corresponding anchor from the old position and add one at the new position.
+
+ Some ARKit features automatically add special anchors to a session. World-tracking sessions can add ``ARPlaneAnchor``, ``ARObjectAnchor``, and ``ARImageAnchor`` objects if you enable the corresponding features; face-tracking sessions add ``ARFaceAnchor`` objects.
+
+ ### Subclassing Notes
+
+ In addition to creating your own `ARAnchor` instances to track the real-world positions of your virtual content, you can also subclass `ARAnchor` to associate custom data with anchors you create. Ensure that your anchor classes behave correctly when ARKit updates frames or saves and loads anchors in an ``ARWorldMap``:
+
+ - Anchor subclasses must fulfill the requirements of the ``ARAnchorCopying`` protocol. ARKit calls ``ARAnchorCopying/init(anchor:)`` (on a background thread) to copy instances of your anchor class from each ``ARFrame`` to the next. Your implementation of this initializer should copy the values of any custom properties your subclass adds.
+ - Anchor subclasses must also adopt the <doc://com.apple.documentation/documentation/foundation/nssecurecoding> protocol. Override <doc://com.apple.documentation/documentation/foundation/nscoding/encode(with:)> and <doc://com.apple.documentation/documentation/foundation/nscoding/init(coder:)> to save and restore the values of your subclass's custom properties when ARKit saves and loads them in a world map.
+ - Anchors are considered equal based on their ``identifier`` property.
+ - Only anchors that do not adopt ``ARTrackable`` are included when you save a world map.
*/
API_AVAILABLE(ios(11.0))
NS_SWIFT_SENDABLE
@@ -60,44 +120,62 @@
>
/**
- Unique identifier of the anchor.
+ A unique identifier for the anchor.
+
+ Whether an anchor is created manually (with the ``ARAnchor/init(transform:)`` initializer) or automatically by ARKit (and provided to you through
+ ``ARSessionDelegate``, ``ARSCNViewDelegate``, or ``ARSKViewDelegate`` methods), each anchor automatically receives a unique identifier value.
+
+ You can use this value to determine which anchors accompanying a specific ``ARFrame`` capture correspond to anchors in frames captured previously.
*/
@property (nonatomic, readonly) NSUUID *identifier;
/**
- An optional name used to associate with the anchor.
+ A descriptive name for the anchor.
+
+ To name an anchor, create one with the ``ARAnchor/init(name:transform:)`` initializer. This property is `nil` for anchors created otherwise.
+
+ ARKit does not display the name to users, but your app can use it to identify anchors for debugging.
*/
@property (nonatomic, nullable, readonly) NSString *name API_AVAILABLE(ios(12.0)) API_UNAVAILABLE(visionos);
/**
- Identifier of the session that owns the anchor.
+ The unique identifier of the session that owns this anchor.
- The session identifier will be assigned to anchor when added to the session.
+ ARKit sets this property when a user first adds an anchor to a session. In multiuser experiences, use this ID to identify the user that created the
+ anchor.
*/
@property (nonatomic, nullable, readonly) NSUUID *sessionIdentifier API_AVAILABLE(ios(13.0));
/**
- The transformation matrix that defines the anchor’s rotation, translation and scale in world coordinates.
+ A matrix encoding the position, orientation, and scale of the anchor relative to the world coordinate space of the AR session the anchor is placed
+ in.
+
+ World coordinate space in ARKit always follows a right-handed convention, but is oriented based on the session configuration. For details, see
+ <doc:understanding-world-tracking>.
*/
@property (nonatomic, readonly) simd_float4x4 transform;
/**
- Initializes a new anchor object.
+ Creates a new anchor object with the specified transform.
- - Parameter transform: The transformation matrix that defines the anchor's rotation, translation and scale in world coordinates.
+ Use the ``ARSession/add(anchor:)`` method to begin tracking your custom anchor in an AR session.
- - Returns: An initialized anchor object.
+ - Parameter transform: A matrix encoding the position, orientation, and scale of the anchor relative to the world coordinate space of the AR session
+ the anchor is placed in. World coordinate space in ARKit always follows a right-handed convention, but is oriented based on the session
+ configuration. For details, see <doc:understanding-world-tracking>.
*/
- (instancetype)initWithTransform:(simd_float4x4)transform;
/**
- Initializes a new anchor object with the provided identifier and name.
+ Creates a new anchor object with the specified transform and a descriptive name.
- - Parameters:
- - name: A name to associate with the anchor.
- - transform: The transformation matrix that defines the anchor's rotation, translation and scale in world coordinates.
+ Use the ``ARSession/add(anchor:)`` method to begin tracking your custom anchor in an AR session.
- - Returns: An initialized anchor object.
+ - Parameters:
+ - name: A descriptive name for the anchor. ARKit does not display the name to users, but your app can use it to identify anchors for debugging.
+ - transform: A matrix encoding the position, orientation, and scale of the anchor relative to the world coordinate space of the AR session the
+ anchor is placed in. World coordinate space in ARKit always follows a right-handed convention, but is oriented based on the session configuration.
+ For details, see <doc:understanding-world-tracking>.
*/
- (instancetype)initWithName:(NSString *)name transform:(simd_float4x4)transform API_AVAILABLE(ios(12.0))API_UNAVAILABLE(visionos);
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARAppClipCodeAnchor.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARAppClipCodeAnchor.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARAppClipCodeAnchor.h 2026-08-15 23:02:19
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARAppClipCodeAnchor.h 2026-10-04 02:32:28
@@ -14,39 +14,114 @@
API_UNAVAILABLE_BEGIN(visionos)
/**
-A value describing app clip code URL decoding state.
+ The states in the process of decoding an App Clip Code URL.
*/
API_AVAILABLE(ios(14.3))
typedef NS_ENUM(NSInteger, ARAppClipCodeURLDecodingState) {
- /** App clip code tracking is attempting to decode the URL. */
+ /**
+ A state that indicates the continuing process of decoding an App Clip Code's URL.
+
+ The App Clip Code anchor's ``ARAppClipCodeAnchor/url`` is `nil` in this state.
+ */
ARAppClipCodeURLDecodingStateDecoding,
- /** App clip code tracking failed to decode the URL. */
+ /**
+ A state that indicates the failure to decode an App Clip Code's URL.
+
+ The decoding of an App Clip Code URL fails under these circumstances:
+
+ - The full app or App Clip is missing the associated-domains entitlement from its code signature.
+ - The host of the resource identified by the App Clip Code URL doesn't vend an Apple App Site Association (AASA) file.
+ - The AASA file hosted at the App Clip Code URL's domain lacks the App Clip's fully-qualified application identifier.
+ - The App Clip Code is not associated to the App Clip in an App Clip experience in App Store Connect.
+
+ For more information, see <doc://com.apple.documentation/documentation/appclip/configuring-the-launch-experience-of-your-app-clip>.
+ */
ARAppClipCodeURLDecodingStateFailed,
- /** App clip code tracking decoded the URL. */
+ /**
+ A state that indicates the completed decoding of an App Clip Code URL.
+
+ The App Clip Code anchor's ``ARAppClipCodeAnchor/url`` is defined in this state.
+ */
ARAppClipCodeURLDecodingStateDecoded
} NS_SWIFT_NAME(ARAppClipCodeAnchor.URLDecodingState);
/**
- An anchor representing an app clip code in the world.
+ An anchor that tracks the position and orientation of an App Clip Code in the physical environment.
+
+ Your App Clip gives users immediate access to critical or context-specific parts of your app's AR experience, and makes it easy for them to download
+ and launch your full app if they choose.
+
+ You can use physical App Clip Codes in the real world to enable users to discover your App Clip. An App Clip Code includes a unique URL and can
+ incorporate an NFC tag. When users hold their iPhone near the code or scan it with the camera or Code Scanner in Control Center, the system offers to
+ launch the code's associated App Clip.
+
+ For more on App Clip Codes, see <doc://com.apple.documentation/documentation/appclip>. For an app that reacts to App Clip Codes in AR, see
+ <doc://com.apple.documentation/documentation/appclip/interacting-with-app-clip-codes-in-ar>.
+
+ ### Distinguish Between App Clip Codes
+
+ There may be multiple App Clip Codes visible in the camera feed that share the same ``url``, so ARKit also relies on the App Clip Code's location
+ (see ``ARAnchor/transform``) to distinguish different App Clip Codes in the physical environment.
+
+ When the framework recognizes an App Clip Code, it initializes an ``ARAppClipCodeAnchor`` and passes it to the session delegate via
+ ``ARSessionDelegate/session(_:didAdd:)``. If a recognized App Clip Code becomes obscured or is no longer visible in the camera feed, the framework
+ sets the anchor's ``ARTrackable/isTracked`` property to <doc://com.apple.documentation/documentation/swift/false> and passes it into the
+ ``ARSessionDelegate/session(_:didUpdate:)-3qtt8`` callback. If the same App Clip Code becomes visible once again:
+
+ - ARKit sets ``ARTrackable/isTracked`` to <doc://com.apple.documentation/documentation/swift/true> if the App Clip Code maintained its relative
+ position in the physical environment.
+ - ARKit initializes a new ``ARAppClipCodeAnchor`` if the App Clip Code position in the physical environment changed significantly.
+
+ ### Remove App Clip Codes
+
+ To prevent App Clip Codes from accumulating in the session, ARKit removes anchors by passing them in to the
+ ``ARSessionDelegate/session(_:didRemove:)`` callback. ARKit removes an ``ARAppClipCodeAnchor`` if all of the following conditions are true:
+
+ - The framework instantiates a new ``ARAppClipCodeAnchor``.
+ - The new anchor's ``url`` matches one or more existing anchors with substantially different positions in the physical environment.
+ - The existing anchors are untracked (``ARTrackable/isTracked`` is <doc://com.apple.documentation/documentation/swift/false>).
*/
API_AVAILABLE(ios(14.3))
NS_SWIFT_SENDABLE
@interface ARAppClipCodeAnchor : ARAnchor <ARTrackable>
/**
-The URL encoded in this app clip code. Not nil only if urlDecodingState is .decoded.
+ The URL encoded in an App Clip Code.
+
+ To enable users to decode your App Clip code's URL from an App Clip or within an AR app, associate your App Clip with its App Clip Code(s) in App
+ Store Connect; for more information, see [set up an App Clip experience](https://help.apple.com/app-store-connect/#/dev5b665db74). Because each App
+ Clip Code belongs to a specific App Clip experience, you can decode an App Clip Code URL in a full app's AR experience only after first providing an
+ accompanying App Clip.
+
+ This property is `nil` by default. The framework sets a value for this property when ``ARAppClipCodeAnchor/urlDecodingState`` is
+ ``ARAppClipCodeAnchor/URLDecodingState/decoded``. This property remains `nil` for App Clip Codes that belong to another App Clip experience or
+ development team.
+
+ ### Distribute Your App and App Clip for Testing
+
+ Although you can launch an App Clip from the camera after creating an App Clip local experience, ARKit checks the App Clip experience registry in App
+ Store Connect to determine if your App Clip associates to a particular App Clip Code URL. When ARKit confirms that an App Clip Code in the physical
+ environment belongs to your App Clip experience, the framework sets the value of this property.
+
+ After setting up an App Clip experience, distribute your app to testers; for more information, see
+ <doc://com.apple.documentation/documentation/appclip/testing-the-launch-experience-of-your-app-clip>.
*/
@property (nonatomic, copy, nullable, readonly) NSURL *url;
/**
- The URL decoding state of the app clip code.
+ A state that indicates the process of decoding an App Clip Code URL.
+
+ The initial value of this property is ``ARAppClipCodeAnchor/URLDecodingState/decoding``.
*/
@property (nonatomic, assign, readonly) ARAppClipCodeURLDecodingState urlDecodingState;
/**
-The estimated radius of the app clip code in meters.
+ The App Clip Code's radius in meters.
+
+ ARKit estimates the value of this property at runtime. As the user views an App Clip Code from different angles, ARKit refines its estimate of the
+ true radius of the App Clip Code.
*/
@property (nonatomic, assign, readonly) float radius;
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARBody2D.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARBody2D.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARBody2D.h 2026-08-15 23:02:19
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARBody2D.h 2026-10-04 02:32:29
@@ -14,14 +14,18 @@
API_UNAVAILABLE_BEGIN(visionos)
/**
- Representation of a body in 2D.
+ The screen-space representation of a person ARKit recognizes in the camera feed.
+
+ When ARKit recognizes a person in the camera feed, it estimates the screen-space
+ location of the body's joints and provides the location to you through the current
+ frame's <doc://com.apple.documentation/documentation/arkit/arframe/detectedbody>.
*/
API_AVAILABLE(ios(13.0))
NS_SWIFT_SENDABLE
@interface ARBody2D : NSObject
/**
- The body's skeleton.
+ An object that contains the screen position of a body's joints.
*/
@property (nonatomic, readonly) ARSkeleton2D *skeleton;
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARBodyAnchor.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARBodyAnchor.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARBodyAnchor.h 2026-08-15 23:02:19
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARBodyAnchor.h 2026-10-04 02:32:28
@@ -17,23 +17,57 @@
@class ARSkeleton3D;
/**
- An anchor representing a body in the world.
+ An anchor that tracks the position and movement of a human body in the rear-facing camera.
+
+ This ``ARAnchor`` subclass tracks the movement of a single person. You enable body tracking by running your session using
+ ``ARBodyTrackingConfiguration``.
+
+ When ARKit recognizes a person in the back camera feed, it calls your delegate's ``ARSessionDelegate/session(_:didAdd:)`` function with
+ ``ARBodyAnchor``. A body anchor's ``ARAnchor/transform`` position defines the world position of the body's hip joint.
+
+ You can also check within the frame's ``ARFrame/anchors`` for a body that ARKit is tracking.
+
+ ### Place a Skeleton on a Surface
+
+ Because a body anchor's origin maps to the hip joint, you calculate the current offset of the feet to the hip to place the body's skeleton on a
+ surface. By passing the foot joint index to ``ARSkeleton3D/jointModelTransforms-dno4``, you get the foot's offset from skeleton's origin.
+
+ ```swift
+ static var hipToFootOffset: Float {
+ // Get an index for a foot.
+ let footIndex = ARSkeletonDefinition.defaultBody3D.index(for: .leftFoot)
+ // Get the foot's world-space offset from the hip.
+ let footTransform = ARSkeletonDefinition.defaultBody3D.neutralBodySkeleton3D!.jointModelTransforms[footIndex]
+ // Return the height by getting just the y-value.
+ let distanceFromHipOnY = abs(footTransform.columns.3.y)
+ return distanceFromHipOnY
+ }
+ ```
*/
API_AVAILABLE(ios(13.0))
NS_SWIFT_SENDABLE
@interface ARBodyAnchor : ARAnchor <ARTrackable>
/**
- The tracked skeleton in 3D.
+ The tracked body in 3D.
+
+ Use this property to interpret motion information in 3D space.
+
- Note: The default height of this skeleton, measured from lowest to highest joint in standing position, is defined to be 1.71 meters.
*/
@property (nonatomic, strong, readonly) ARSkeleton3D *skeleton;
/**
- The factor between estimated physical size and default size of the skeleton.
+ A factor that relates the body's default height with the height ARKit estimates at runtime.
- This value will be estimated if `automaticSkeletonScaleEstimationEnabled` is set to `true` on the `ARBodyTrackingConfiguration`.
- It is used to correct the transform's translation. Default value is `1.0`.
+ The default value is 1.0. If you set ``ARBodyTrackingConfiguration/automaticSkeletonScaleEstimationEnabled`` to
+ <doc://com.apple.documentation/documentation/swift/true> on ``ARBodyTrackingConfiguration``, ARKit sets this property to a scale factor that
+ relates the estimated height of the person in the camera feed to the default body height.
+
+ ARKit must know the height of a person in the camera feed to estimate an accurate world position for the person's body anchor. ARKit uses the value
+ of ``ARBodyAnchor/estimatedScaleFactor`` to correct the body anchor's position in the physical environment.
+
+ The default body is 1.71 meters tall.
- SeeAlso: ``ARSkeletonDefinition/neutralBodySkeleton3D``
*/
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARCamera.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARCamera.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARCamera.h 2026-08-15 23:02:19
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARCamera.h 2026-10-04 02:32:28
@@ -18,72 +18,105 @@
API_UNAVAILABLE_BEGIN(visionos)
/**
- A model representing the camera and its parameters.
+ Information about the camera position and imaging characteristics for a given frame.
+
+ You get camera information from the `ARFrame.camera` property of each `ARFrame` ARKit delivers.
*/
API_AVAILABLE(ios(11.0))
NS_SWIFT_SENDABLE
@interface ARCamera : NSObject <NSCopying>
/**
- The transformation matrix that defines the camera’s rotation and translation in world coordinates.
+ The position and orientation of the camera in world coordinate space.
+
+ World coordinate space in ARKit always follows a right-handed convention, but is oriented based on the session configuration. For details, see
+ <doc:understanding-world-tracking>.
+
+ This transform creates a local coordinate space for the camera that is constant with respect to device orientation.
+ In camera space, the x-axis points to the right when the device is in
+ <doc://com.apple.documentation/documentation/uikit/uideviceorientation/landscapeleft> orientation—that is, the x-axis always points along the long
+ axis of the device, from the front-facing camera toward the Home button. The y-axis points upward (with respect to
+ <doc://com.apple.documentation/documentation/uikit/uideviceorientation/landscapeleft> orientation), and the z-axis points away from the device on the
+ screen side.
*/
@property (nonatomic, readonly) simd_float4x4 transform;
/**
- The camera’s orientation defined as Euler angles.
+ The orientation of the camera, expressed as roll, pitch, and yaw values.
- @dicussion The order of components in this vector matches the axes of rotation:
- 1. Pitch (the x component) is the rotation about the node’s x-axis (in radians)
- 2. Yaw (the y component) is the rotation about the node’s y-axis (in radians)
- 3. Roll (the z component) is the rotation about the node’s z-axis (in radians)
- ARKit applies these rotations in the following order:
- 1. first roll
- 2. then pitch
- 3. then yaw
+ The order of components in this vector matches the axes of rotation:
+ 1. Pitch (the x component) is the rotation about the node’s x-axis (in radians)
+ 2. Yaw (the y component) is the rotation about the node’s y-axis (in radians)
+ 3. Roll (the z component) is the rotation about the node’s z-axis (in radians)
+ ARKit applies these rotations in the following order:
+ 1. first roll
+ 2. then pitch
+ 3. then yaw
*/
@property (nonatomic, readonly) simd_float3 eulerAngles;
/**
- The tracking state of the camera.
+ The general quality of position tracking available when the camera captured a frame.
*/
@property (nonatomic, readonly) ARTrackingState trackingState NS_REFINED_FOR_SWIFT;
/**
- The reason for the camera’s current tracking state.
+ A possible diagnosis for limited position-tracking quality as of when the camera captured a frame.
*/
@property (nonatomic, readonly) ARTrackingStateReason trackingStateReason NS_REFINED_FOR_SWIFT;
/**
- The camera intrinsics.
+ A matrix that converts between the 2D camera plane and 3D world coordinate space.
+ The intrinsic matrix (commonly represented in equations as `K`) is based on physical characteristics of the device camera and a pinhole camera model.
+ You can use the matrix to transform 3D coordinates to 2D coordinates on an image plane.
+
The matrix has the following contents:
fx 0 px
0 fy py
0 0 1
- fx and fy are the focal length in pixels.
- px and py are the coordinates of the principal point in pixels.
- The origin is at the center of the upper-left pixel.
+ The values `fx` and `fy` are the pixel focal length, and are identical for square pixels. The values `px` and `py` are the coordinates of the
+ principal point—the offsets of the principal point from the top-left corner of the image frame. All values are expressed in pixels. The origin is at
+ the center of the upper-left pixel.
*/
@property (nonatomic, readonly) simd_float3x3 intrinsics;
/**
- The camera image resolution in pixels.
+ The width and height, in pixels, of the captured camera image.
+
+ This size describes the image in the `ARFrame.capturedImage` buffer, which contains image data in the camera device's native sensor orientation. To
+ convert image coordinates to match a specific display orientation of that image, use the ``viewMatrixForOrientation:`` or
+ ``projectPoint:orientation:viewportSize:`` method.
*/
@property (nonatomic, readonly) CGSize imageResolution;
/**
- The camera exposure duration in seconds.
+ A value you use to effect motion blur when rendering your app's virtual content.
+
+ If you display an AR experience using a custom Metal renderer, use this value to determine how much motion blur to apply to your virtual content.
+
+ If `ARSCNView` is your renderer, SceneKit automatically applies motion blur to your virtual content. For more information, see
+ `ARSCNView.rendersMotionBlur`.
*/
@property (nonatomic, readonly) NSTimeInterval exposureDuration API_AVAILABLE(ios(13.0));
/**
- The camera exposure offset in EV (exposure value) units.
+ A value you supply to your custom renderer to light your scene.
+
+ If your app displays an AR experience using a custom Metal renderer, use this value to light your scene during its post-processed lighting stage.
+
+ Lighting a scene using ``exposureOffset`` is normally more performant than scaling each light source in your scene based on the value of the frame's
+ `ARFrame.lightEstimate`.
*/
@property (nonatomic, readonly) float exposureOffset API_AVAILABLE(ios(13.0));
/**
- The projection matrix of the camera.
+ A transform matrix appropriate for rendering 3D content to match the image captured by the camera.
+ Reading this property's value is equivalent to calling the ``projectionMatrixForOrientation:viewportSize:zNear:zFar:`` method, using the camera's
+ ``imageResolution`` and ``intrinsics`` properties to derive size and orientation, and passing default values of `0.001` and `1000.0` for the near and
+ far clipping planes.
+
The projection matrix assumes no far clipping plane limit.
*/
@property (nonatomic, readonly) simd_float4x4 projectionMatrix;
@@ -95,18 +128,21 @@
typedef NS_ENUM(NSInteger, UIInterfaceOrientation);
/**
- Creates a projection matrix for the camera given rendering parameters.
+ Returns a transform matrix appropriate for rendering 3D content to match the image captured by the camera, using the specified parameters.
+ This method has no effect on ARKit, and the `zNear` and `zFar` parameters have no relationships to ARKit camera state. Instead, this method uses
+ those parameters as well as the camera's state to construct a projection matrix for use in your own rendering code.
+
The projection matrix returned provides an aspect fill for the provided viewport size and orientation.
If zFar is set to 0, an infinite projection matrix will be returned.
- Parameters:
- - orientation: Viewport orientation.
- - viewportSize: Viewport size.
- - zNear: Near depth limit.
- - zFar: Far depth limit.
+ - orientation: The orientation in which the camera image is to be presented.
+ - viewportSize: The size, in points, of the view in which the camera image is to be presented.
+ - zNear: The distance from the camera to the near clipping plane.
+ - zFar: The distance from the camera to the far clipping plane.
- - Returns: The projection matrix for the given parameters.
+ - Returns: A projection matrix that provides an aspect fill and rotation for the provided viewport size and orientation.
*/
- (simd_float4x4)projectionMatrixForOrientation:(UIInterfaceOrientation)orientation
viewportSize:(CGSize)viewportSize
@@ -139,14 +175,19 @@
API_AVAILABLE(ios(27.0));
/**
- Project a 3D point in world coordinate system into 2D viewport space.
+ Returns the projection of a point from the 3D world space detected by ARKit into the 2D space of a view rendering the scene.
+ If you display AR content with SceneKit, the `ARSCNView` class provides an otherwise equivalent
+ <doc://com.apple.documentation/documentation/scenekit/scnscenerenderer/projectpoint(_:)> method that requires fewer parameters (because the view can
+ infer its orientation and size).
+
- Parameters:
- - point: 3D point in world coordinate system.
- - orientation: Viewport orientation.
- - viewportSize: Viewport (or image) size.
+ - point: The 3D world-space point to project into 2D view space.
+ - orientation: The orientation in which the camera image is to be presented.
+ - viewportSize: The size, in points, of the view in which the camera image is to be presented.
- - Returns: 2D point in viewport coordinate system with origin at top-left.
+ - Returns: The projection of the specified point into a 2D pixel coordinate space whose origin is in the upper left corner and whose size matches
+ that of the `viewportSize` parameter.
*/
- (CGPoint)projectPoint:(simd_float3)point
orientation:(UIInterfaceOrientation)orientation
@@ -169,17 +210,25 @@
- (CGPoint)projectPoint:(simd_float3)point viewRotationAngle:(CGFloat)viewRotationAngle viewportSize:(CGSize)viewportSize API_AVAILABLE(ios(27.0));
/**
- Unproject a 2D point from the viewport onto a plane in 3D world coordinates.
+ Returns the projection of a point from the 2D space of a view rendering the scene onto a plane in the 3D world space detected by ARKit.
- A 2D point in the viewport coordinate space can refer to any point along a line segment
- in the 3D coordinate space. Unprojecting calculates the 3D position of the point along this line segment that intersects the provided plane.
+ A 2D point in the viewport coordinate space can refer to any point along a line segment in the 3D coordinate space. Unprojecting calculates the 3D
+ position of the point along this line segment that intersects the provided plane.
+ If you display AR content with SceneKit, the `ARSCNView` class provides an otherwise equivalent `ARSCNView.unprojectPoint(_:ontoPlane:)` method that
+ requires fewer parameters (because the view can infer its orientation and size).
+
- Parameters:
- - point: A point in the viewport coordinate system with origin at top-left.
- - planeTransform: The transform used to define the coordinate system of the plane.
- The coordinate system's positive Y axis is assumed to be the normal of the plane.
+ - point: The point in 2D view space to project onto a plane.
- - Returns: 3D position in world coordinates or `NAN` values if unprojection is not possible.
+ The coordinate space for this point has its origin in the upper left corner and a size matching the `viewportSize` parameter.
+ - planeTransform: A transform matrix specifying the position and orientation of a plane (with infinite extent) in 3D world space. The plane is the
+ xz-plane of the local coordinate space this transform defines.
+ - orientation: The orientation in which the camera image is to be presented.
+ - viewportSize: The size, in points, of the view in which the camera image is to be presented.
+
+ - Returns: The 3D point in world space where a ray projected from the specified 2D point intersects the specified plane. If the ray does not
+ intersect the plane, this method returns a `float3` vector where all elements are `NaN`.
*/
- (simd_float3)unprojectPoint:(CGPoint)point
ontoPlaneWithTransform:(simd_float4x4)planeTransform
@@ -212,13 +261,16 @@
viewportSize:(CGSize)viewportSize API_AVAILABLE(ios(27.0))NS_REFINED_FOR_SWIFT;
/**
- Returns the view matrix for the camera with a given interface orientation.
+ Returns a transform matrix for converting from world space to camera space.
+ This method has no effect on ARKit. Instead, this method uses the orientation parameter and the camera's state to construct a view matrix for your
+ own rendering code.
+
The view matrix can be used to transform geometry from world space into camera space for a given orientation.
- - Parameter orientation: The interface orientation that will be used to render the camera's view.
+ - Parameter orientation: The orientation in which the camera image is to be presented.
- - Returns: The view matrix for the given orientation.
+ - Returns: A view matrix appropriate for the camera with the specified orientation.
*/
- (simd_float4x4)viewMatrixForOrientation:(UIInterfaceOrientation)orientation API_DEPRECATED("Use viewMatrixForViewRotationAngle:", ios(11.0, 27.0));
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARCoachingOverlayView.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARCoachingOverlayView.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARCoachingOverlayView.h 2026-08-15 23:13:05
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARCoachingOverlayView.h 2026-10-04 02:39:15
@@ -18,93 +18,187 @@
@protocol ARSessionProviding;
/**
- A value describing the context required for successful coaching
+ The options that specify your app's tracking requirements.
+
+ This enumeration lists the available goals you can set on a coaching overlay's ``ARCoachingOverlayView/goal-swift.property``. The coaching overlay
+ adjusts its messaging to the user based on the value.
*/
API_AVAILABLE(ios(13.0))
typedef NS_ENUM(NSInteger, ARCoachingGoal) {
- /** Session requires normal tracking */
+ /**
+ A goal that specifies your app requires basic world tracking.
+
+ When you use this goal, coaching overlay won't hide until the user has moved their device in a way that facilitates ARKit starting up a basic
+ world tracking session.
+ */
ARCoachingGoalTracking,
- /** Session requires a horizontal plane */
+ /**
+ A goal that specifies your app requires a horizontal plane.
+
+ When you use this goal, coaching overlay won't hide until the user has moved their device in a way that facilitates ARKit finding at least one
+ horizontal surface.
+ */
ARCoachingGoalHorizontalPlane,
- /** Session requires a vertical plane */
+ /**
+ A goal that specifies your app requires a vertical plane.
+
+ When you use this goal, coaching overlay won't hide until the user has moved their device in a way that facilitates ARKit finding at least one
+ vertical surface.
+ */
ARCoachingGoalVerticalPlane,
- /** Session requires one plane of any type */
+ /**
+ A goal that specifies your app requires a plane of any type.
+
+ When you use this goal, coaching overlay won't hide until the user has moved their device in a way that facilitates ARKit finding at least one
+ surface. For the available surface types, see ``ARPlaneClassification``.
+ */
ARCoachingGoalAnyPlane,
- /** Session requires geo tracking */
+ /**
+ A goal that specifies your app requires a precise geographic location.
+
+ When you set this goal, the coaching overlay provides the user instructions when they start a geotracking session, or when they go off course
+ during a session.
+ */
ARCoachingGoalGeoTracking,
} NS_SWIFT_NAME(ARCoachingOverlayView.Goal);
/**
- A view that guides users through session initialization
+ A view that displays standardized onboarding instructions to direct users toward a specific goal.
- The view will use context aware messaging and animations to instruct the user on gathering required info for the AR session.
+ This view offers your users a standardized onboarding routine. You can configure this view to automatically display during session initialization and
+ in limited tracking situations, while giving the user specific instructions that best facilitate ARKit's world tracking.
+
+ When you start your app, the coaching overlay asks the user to move the device in ways that help ARKit establish tracking. When you choose a specific
+ goal like finding a plane, the view tailors its instructions accordingly. After the coaching overlay determines the goal has been met and no further
+ coaching is required, it hides from the user's view.
+
+ For an example app that uses the coaching overlay, see <doc:placing-objects-and-handling-3d-interaction>.
+
+ ### Supporting Automatic Coaching
+
+ By default, ``activatesAutomatically`` is enabled and therefore you should override
+ ``ARCoachingOverlayViewDelegate/coachingOverlayViewWillActivate(_:)`` to determine whether coaching is in progress. Coordinate your actions to help
+ the user focus on these instructions, for example, by hiding any UI that's not necessary while the session reinitializes.
+
+ ### Relocalizing After an Interruption
+
+ If relocalization is enabled (see ``ARSessionObserver/sessionShouldAttemptRelocalization(_:)``), ARKit attempts to restore your session if any
+ interruptions degrade your app's tracking state. In this event, the coaching overlay presents itself and gives the user instructions to assist ARKit
+ with relocalizing.
+
+ During this time, the coaching overlay includes a button that lets the user indicate they'd like to start over rather than restore the session.
+
+ ARKit notifies you when the user presses Start Over by calling your delegate's
+ ``ARCoachingOverlayViewDelegate/coachingOverlayViewDidRequestSessionReset(_:)`` function. Implement this callback if your app requires any custom
+ actions to restart the AR experience.
+
+ ```swift
+ func coachingOverlayViewDidRequestSessionReset(_ coachingOverlayView: ARCoachingOverlayView) {
+
+ // Reset the session.
+ let configuration = ARWorldTrackingConfiguration()
+ configuration.planeDetection = [.horizontal, .vertical]
+ session.run(configuration, options: [.resetTracking])
+
+ // Custom actions to restart the AR experience.
+ // ...
+ }
+ ```
+
+ If you do not implement ``ARCoachingOverlayViewDelegate/coachingOverlayViewDidRequestSessionReset(_:)``, the coaching overlay responds to the Start
+ Over button by resetting tracking, which also removes any existing anchors.
+
+ For more information about relocalization, see <doc:managing-session-life-cycle-and-tracking-quality>.
*/
API_AVAILABLE(ios(13.0))
API_DEPRECATED("This API is deprecated on visionOS.", visionos(1.0, 1.0))
@interface ARCoachingOverlayView : UIView
/**
- Specifies the delegate used for callbacks
+ An object you supply that implements coaching event callbacks.
+
+ Normally, you set the value of this property to your app's view controller.
*/
@property (nonatomic, weak, nullable) IBOutlet id<ARCoachingOverlayViewDelegate> delegate;
/**
- A provider of a session to use
+ An object you designate that provides the current session.
- This property can be used to set the `session` when loading from a storyboard. Setting this property at runtime will also
- set the `session` property.
+ Use this property to set the coaching overlay's ``ARCoachingOverlayView/session`` when loading from a storyboard. If you set this property at
+ runtime, the coaching overlay keeps its ``ARCoachingOverlayView/session`` property up to date for you. If your app recreates its ``ARSession`` at any
+ point, you may find it convenient to set the ``ARCoachingOverlayView/sessionProvider`` once rather than update the coaching overlay's
+ ``ARCoachingOverlayView/session`` manually.
*/
@property (nonatomic, weak, nullable) IBOutlet NSObject<ARSessionProviding> *sessionProvider;
/**
- The session that the view uses to update coaching
+ The session this view uses to provide coaching.
+
+ The coaching overlay monitors your app's ``ARSession`` and reacts according to its tracking status. You don't need to set this property if you set
+ ``ARCoachingOverlayView/sessionProvider`` instead.
*/
@property (nonatomic, strong, nullable) ARSession *session;
/**
- The coaching type used to resolve what messaging to display to the user while activated
- Defaults to `ARCoachingGoalTracking`
+ A field that indicates your app's tracking requirements.
+
+ The goal you choose determines the particular instructions the coaching overlay presents to the user.
*/
@property (nonatomic, assign) ARCoachingGoal goal;
/**
- Whether or not the view should activate/deactivate automatically, depending on the current state of the session
+ A flag that indicates whether the coaching view activates automatically, depending on the current session state.
- Defaults to `YES`
-
- When set to automatically activate, the view will transition to active when the session loses normal tracking for a set amount
- of time.
- When tracking resumes and other requirements (based on `goal`) are met, the view will deactivate.
+ The default value is <doc://com.apple.documentation/documentation/swift/true>. If enabled, the coaching overlay sets
+ ``ARCoachingOverlayView/isActive`` automatically, depending on whether it needs user intervention to meet the current
+ ``ARCoachingOverlayView/goal-swift.property``. The coaching overlay activates when the session is initializing or when tracking conditions have
+ degraded past a certain threshold.
*/
@property (nonatomic, assign) BOOL activatesAutomatically;
/**
- Whether or not the view is currently active.
+ A flag that indicates whether coaching is in progress.
- - SeeAlso: ``ARCoachingOverlayView/setActive:animated:``
+ If ``ARCoachingOverlayView/activatesAutomatically`` is enabled, this flag tells you whether coaching is in progress. Assign a
+ ``ARCoachingOverlayView/delegate`` to coordinate your actions with the coaching overlay and allow
+ ``ARCoachingOverlayViewDelegate/coachingOverlayViewWillActivate(_:)`` to notify you when the coaching overlay is active.
+
+ When the coaching overlay is deactivating, ``ARCoachingOverlayView/isActive`` is <doc://com.apple.documentation/documentation/swift/false>. If the
+ `animated` property of ``ARCoachingOverlayView/setActive(_:animated:)`` is <doc://com.apple.documentation/documentation/swift/true>,
+ ``ARCoachingOverlayView/isActive`` and <doc://com.apple.documentation/documentation/uikit/uiview/ishidden> are
+ <doc://com.apple.documentation/documentation/swift/false> while the coaching overlay is fading out. When the coaching overlay is deactivated without
+ animation, or when the animation finishes, ARKit notifies you by calling ``ARCoachingOverlayViewDelegate/coachingOverlayViewDidDeactivate(_:)``.
*/
@property (nonatomic, readonly) BOOL isActive;
/**
- Transition the view to either an activated or deactivated state
+ Controls whether coaching is in progress.
On activation the view will check the current session, and if relocalization is needed it will present a modified UI with
relocalization coaching and a reset button.
- On deactivation the view will become hidden
+ On deactivation the view will become hidden.
- - Parameters:
- - active: Whether the view should activate, or deactivate.
- - animated: Whether the view animated to activated/deactivated states, or transitions instantly.
+ If the `animated` property of ``ARCoachingOverlayView/setActive(_:animated:)`` is <doc://com.apple.documentation/documentation/swift/true>,
+ ``ARCoachingOverlayView/isActive`` and <doc://com.apple.documentation/documentation/uikit/uiview/ishidden> are
+ <doc://com.apple.documentation/documentation/swift/false> while the coaching overlay is fading out. When the coaching overlay is deactivated without
+ animation, or when the animation finishes, ARKit notifies you by calling ``ARCoachingOverlayViewDelegate/coachingOverlayViewDidDeactivate(_:)``.
- - SeeAlso: ``ARCoachingOverlayViewDelegate/coachingOverlayViewDidRequestSessionReset:``
+ - Parameters:
+ - active: A flag you set to indicate whether the coaching overlay should activate or deactivate.
+ - animated: A flag that when <doc://com.apple.documentation/documentation/swift/true>, fades the coaching overlay in or out. When you pass a value
+ of <doc://com.apple.documentation/documentation/swift/false>, the coaching overlay shows or hides instantly.
*/
- (void)setActive:(BOOL)active animated:(BOOL)animated;
@end
/**
- A delegate protocol for receiving coaching overlay view events.
+ A set of callbacks you implement to be notified of coaching events.
+
+ Implement a delegate to coordinate your app's actions with coaching overlay. For example, when the coaching overlay determines the user needs
+ guidance, you hide your app's UI to allow the user to focus on the coaching experience. When the coaching overlay determines the
+ ``ARCoachingOverlayView/goal-swift.property`` is met, you show your app's UI and begin your app's AR experience.
*/
API_AVAILABLE(ios(13.0))
API_DEPRECATED("This API is deprecated on visionOS.", visionos(1.0, 1.0))
@@ -113,28 +207,38 @@
@optional
/**
- This is called when the user taps the reset button in the relocalization state
+ Tells you when the user taps the coaching overlay view's Start Over button while the session is relocalizing.
- By default, when the relocalization reset button is tapped, the overlay will call run on the session using the current
- `configuration`, and the `ARSessionRunOptionResetTracking` and `ARSessionRunOptionRemoveExistingAnchors` options. The delegate may
- implement this method to override this behavior. The delegate is then responsible for resetting the session.
+ Implement this function to do the actions your app requires to restart the AR experience. For example, you might hide custom relocalization UI,
+ deallocate resources, or restore virtual content to a starting location.
+ If you don't implement this function, the coaching overlay resets the session for you––equivalent to calling ``ARSession/run(_:options:)`` with the
+ ``ARSession/RunOptions/resetTracking`` option––when the user taps Start Over.
+
- Parameter coachingOverlayView: The view currently active.
*/
- (void)coachingOverlayViewDidRequestSessionReset:(ARCoachingOverlayView *)coachingOverlayView;
/**
- This is called when the view activate, either manually or automatically
+ Tells you when the coaching overlay view activates.
- The Developer may hide their application UI in this callback, and take other appropriate actions to allow
- `ARCoachingOverlayView` to take over the full screen.
+ Override this function to hide your app's UI while the coaching overlay is active.
- Parameter coachingOverlayView: The view that will be activated.
*/
- (void)coachingOverlayViewWillActivate:(ARCoachingOverlayView *)coachingOverlayView;
/**
- This is called when the view has been deactivated, either manually or automatically.
+ Tells you when the coaching experience is completely deactivated.
+
+ Implement this function to do any custom actions your app requires to begin the AR experience. For example, when coaching is deactivated, your app
+ might restore custom UI.
+
+ When the coaching overlay is deactivating, ``ARCoachingOverlayView/isActive`` is <doc://com.apple.documentation/documentation/swift/false>. If the
+ `animated` property of ``ARCoachingOverlayView/setActive(_:animated:)`` is <doc://com.apple.documentation/documentation/swift/true>,
+ ``ARCoachingOverlayView/isActive`` and <doc://com.apple.documentation/documentation/uikit/uiview/ishidden> are
+ <doc://com.apple.documentation/documentation/swift/false> while the coaching overlay is fading out. When the coaching overlay is deactivated without
+ animation, or when the animation finishes, ARKit sends a ``ARCoachingOverlayViewDelegate/coachingOverlayViewDidDeactivate(_:)`` notification.
- Parameter coachingOverlayView: The view that was deactivated.
*/
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARCollaborationData.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARCollaborationData.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARCollaborationData.h 2026-08-15 23:02:18
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARCollaborationData.h 2026-10-04 02:32:28
@@ -14,24 +14,39 @@
API_UNAVAILABLE_BEGIN(visionos)
/**
- A value describing the priority of the collaboration data.
+ Options that help you choose the appropriate network protocol or settings for a given data instance.
+
+ When you send an `ARCollaborationData` instance over the network by using a protocol that allows you to specify varying reliability, this
+ enumeration lists the priority options that hint at which reliability setting to use for a given collaboration data instance. Depending on its
+ priority, you may also choose to send a given collaboration data instance using different protocols.
*/
API_AVAILABLE(ios(13.0))
typedef NS_ENUM(NSInteger, ARCollaborationDataPriority) {
- /// The data is important for establishing or continuing a collaborative session. For best results, use network transmission mechanisms that
- /// ensure delivery, such as MCSessionSendDataModeReliable.
+ /**
+ A priority that indicates that collaboration depends on this data.
+
+ ARKit sets the data priority to critical when the data is important for establishing or continuing a collaborative session. For best results,
+ use network transmission mechanisms that ensure delivery, such as MCSessionSendDataModeReliable.
+ */
ARCollaborationDataPriorityCritical,
- /// The data is time-sensitive but not important to collaborative session quality. Timely synchronization of this data between participants
- /// produces a smoother shared session, but the session can continue if the data is not received. For best results, use network transmission
- /// mechanisms that prioritize speed over delivery guarantees, such as MCSessionSendDataModeUnreliable.
+ /**
+ A priority that indicates that collaboration can continue without this data.
+
+ ARKit sets the data priority to optional when the data is time-sensitive but not important to collaborative session quality. Timely
+ synchronization of this data between participants produces a smoother shared session, but the session can continue if the data is not received.
+ For best results, use network transmission mechanisms that prioritize speed over delivery guarantees, such as MCSessionSendDataModeUnreliable.
+ */
ARCollaborationDataPriorityOptional,
} NS_SWIFT_NAME(ARCollaborationData.Priority);
/**
- Object representing data for collaborative session.
+ An object that holds information that a user has collected about the physical environment.
- This data needs to be sent to each participant in the collaborative session.
+ To create a multiuser AR experience, you enable collaboration on a world tracking session. ARKit regularly outputs `ARCollaborationData`
+ that users share with each other, which enables everyone to view the same virtual content from their own perspective. This data needs to be
+ sent to each participant in the collaborative session. For more information, see
+ <doc://com.apple.documentation/documentation/arkit/arworldtrackingconfiguration/iscollaborationenabled>.
*/
API_AVAILABLE(ios(13.0))
NS_SWIFT_NAME(ARSession.CollaborationData)
@@ -39,9 +54,13 @@
@interface ARCollaborationData : NSObject <NSSecureCoding>
/**
- Network priority of the data.
+ A property that gives you a hint about how to send a given data instance over the network.
- The network implementation should respect this flag and choose the appropriate protocol.
+ If you have reliability options in the network protocol you choose to transport `ARCollaborationData` among peers, the priority property gives
+ you a hint about which reliability option to choose for a given collaboration data instance. For example, if you use MultipeerConnectivity to
+ send collaboration data over the network, choose <doc://com.apple.documentation/documentation/multipeerconnectivity/mcsessionsenddatamode/reliable>
+ when calling <doc://com.apple.documentation/documentation/multipeerconnectivity/mcsession/send(_:topeers:with:)> after ARKit gives you a
+ collaboration data instance with priority ARCollaborationDataPriorityCritical.
*/
@property (nonatomic, readonly) ARCollaborationDataPriority priority;
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARConfiguration.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARConfiguration.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARConfiguration.h 2026-08-15 23:02:18
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARConfiguration.h 2026-10-04 02:32:28
@@ -22,7 +22,9 @@
@class ARWorldMap;
/**
-Option set indicating semantic understanding types of the image frame.
+ Types of optional frame features you can enable in your app.
+
+ A frame semantic represents 2D information that ARKit extracts from a frame.
*/
API_AVAILABLE(ios(13.0))
typedef NS_OPTIONS(NSUInteger, ARFrameSemantics) {
@@ -30,30 +32,45 @@
ARFrameSemanticNone = 0,
/**
- Person segmentation.
+ An option that indicates that people occlude your app's virtual content.
- A pixel in the image frame that gets classified as person will have an intensity value equal to 'ARSegmentationClassPerson'.
+ The `ARFrameSemanticPersonSegmentation` frame semantic specifies that any person ARKit detects in the camera feed occludes virtual
+ content, regardless of the person's depth in the scene.
+ When this option is enabled, ARKit sets the ``ARFrame/estimatedDepthData`` and ``ARFrame/segmentationBuffer`` properties to serve as a
+ foundation for people occlusion. The standard renderers (<doc://com.apple.documentation/documentation/realitykit/arview>, and
+ ``ARSCNView``) use those properties to implement people occlusion for you. See ``ARConfiguration/frameSemantics`` for more information.
+
+ In the ``ARFrame/segmentationBuffer``, every pixel ARKit classifies as a person has an intensity value equal to ``ARSegmentationClassPerson``.
+
- SeeAlso: ``ARFrame/segmentationBuffer``
- SeeAlso: ``ARSegmentationClass``
*/
ARFrameSemanticPersonSegmentation = (1 << 0),
/**
- Person segmentation with depth.
+ An option that indicates that people occlude your app's virtual content depending on depth.
- A pixel in the image frame that gets classified as person will have an intensity value equal to 'ARSegmentationClassPerson'.
- Additionally, every pixel in the image frame that gets classified as person will also have a depth value.
+ The `ARFrameSemanticPersonSegmentationWithDepth` frame semantic specifies that any person ARKit detects in the camera feed should occlude
+ virtual content, depending on the person's depth in the scene.
+ When this option is enabled, ARKit sets the ``ARFrame/estimatedDepthData`` and ``ARFrame/segmentationBuffer`` properties to serve as a
+ foundation for people occlusion. The standard renderers (<doc://com.apple.documentation/documentation/realitykit/arview>, and
+ ``ARSCNView``) use those properties to implement people occlusion for you. See ``ARConfiguration/frameSemantics`` for more information.
+
+ In the ``ARFrame/segmentationBuffer``, every pixel ARKit classifies as a person has an intensity value equal to ``ARSegmentationClassPerson`` and
+ an accompanying depth value in ``ARFrame/estimatedDepthData``.
+
- SeeAlso: ``ARFrame/estimatedDepthData``
- SeeAlso: ``ARFrame/segmentationBuffer``
*/
ARFrameSemanticPersonSegmentationWithDepth = (1 << 1) | (1 << 0),
/**
- Body detection.
+ An option that indicates that 2D body detection is enabled.
- Once activated an `ARFrame` will contain information about a detected body.
+ When you set this option in your configuration's ``ARConfiguration/frameSemantics`` property, ARKit describes the joint positions of a
+ body it detects in the camera image, using normalized coordinates. See ``ARFrame/detectedBody`` for more information.
- SeeAlso: ``ARFrame/detectedBody``
- SeeAlso: ``ARBody2D``
@@ -61,19 +78,39 @@
ARFrameSemanticBodyDetection = (1 << 2),
/**
- Scene Depth.
+ An option that provides the distance from the device to real-world objects viewed through the camera.
- Each `capturedImage` will have an associated scene depth data.
+ Enable this option on a world-tracking configuration (``ARWorldTrackingConfiguration``) to instruct ARKit to provide your app with the
+ distance between the user's device and the real-world objects in the camera feed. ARKit samples this distance using the LiDAR scanner and
+ provides the results through the ``ARFrame/sceneDepth`` property on the session's ``ARSession/currentFrame``.
+ ARKit creates this object from LiDAR readings at the same time as the current frame. The data in ``ARFrame/sceneDepth`` reflects the distance
+ from the device to real-world objects pictured in the frame's ``ARFrame/capturedImage``. Alternatively, ARKit provides a
+ ``ARFrameSemanticSmoothedSceneDepth`` property that minimizes the difference in LiDAR readings across frames.
+
+ ARKit supports scene depth only on LiDAR-capable devices, so call ``ARConfiguration/supportsFrameSemantics:`` to ensure device support
+ before attempting to enable scene depth.
+
- SeeAlso: ``ARFrame/sceneDepth``
*/
ARFrameSemanticSceneDepth API_AVAILABLE(ios(14.0)) = (1 << 3),
/**
- Smoothed Scene Depth.
+ An option that provides the distance from the device to real-world objects, averaged across several frames.
- Each `capturedImage` will have an associated scene depth data that is temporally smoothed.
+ Enable this option on a world-tracking configuration (``ARWorldTrackingConfiguration``) to instruct ARKit to provide your app with the
+ distance between the user's device and the real-world objects pictured in the frame's ``ARFrame/capturedImage``. ARKit samples this
+ distance using the LiDAR scanner and provides the results through the ``ARFrame/smoothedSceneDepth`` property on the session's
+ ``ARSession/currentFrame``.
+ To minimize the difference in LiDAR readings across frames, ARKit processes the data as an average. The averaged readings reduce
+ flickering to create a smoother motion effect when depicting objects with depth, as demonstrated in
+ <doc:creating-a-fog-effect-using-scene-depth>. Alternatively, to access a discrete LiDAR reading at the instant the framework creates the
+ current frame, use ``ARFrame/sceneDepth``.
+
+ ARKit supports scene depth only on LiDAR-capable devices, so call ``ARConfiguration/supportsFrameSemantics:`` to ensure device support
+ before attempting to enable scene depth.
+
- SeeAlso: ``ARFrame/smoothedSceneDepth``
*/
ARFrameSemanticSmoothedSceneDepth API_AVAILABLE(ios(14.0)) = (1 << 4),
@@ -81,67 +118,189 @@
} NS_SWIFT_NAME(ARConfiguration.FrameSemantics);
/**
- Enum constants for indicating the world alignment.
+ Options for how ARKit constructs a scene coordinate system based on real-world device motion.
*/
API_AVAILABLE(ios(11.0))
typedef NS_ENUM(NSInteger, ARWorldAlignment) {
- /** Aligns the world with gravity that is defined by vector (0, -1, 0). */
+ /**
+ The coordinate system's y-axis is parallel to gravity, and its origin is the initial position of the device.
+
+ The y-axis matches the direction of gravity as detected by the device's motion sensing hardware; that is, the vector `(0,-1,0)` points
+ downward.
+
+ The position and orientation of the device as of when the session configuration is first run determine the rest of the coordinate system:
+ For the z-axis, ARKit chooses a basis vector `(0,0,-1)` pointing in the direction the device camera faces and perpendicular to the gravity
+ axis. ARKit chooses a x-axis based on the z- and y-axes using the right hand rule—that is, the basis vector `(1,0,0)` is orthogonal to the
+ other two axes, and (for a viewer looking in the negative-z direction) points toward the right.
+ */
ARWorldAlignmentGravity,
- /** Aligns the world with gravity that is defined by the vector (0, -1, 0)
- and heading (w.r.t. True North) that is given by the vector (0, 0, -1). */
+ /**
+ The coordinate system's y-axis is parallel to gravity, its x- and z-axes are oriented to compass heading, and its origin is the initial
+ position of the device.
+
+ The y-axis matches the direction of gravity as detected by the device's motion sensing hardware; that is, the vector `(0,-1,0)` points
+ downward.
+
+ The x- and z-axes match the longitude and latitude directions as measured by Location Services. The vector `(0,0,-1)` points to true north
+ and the vector `(-1,0,0)` points west. (That is, the positive x-, y-, and z-axes point east, up, and south, respectively.)
+
+ Although this option fixes the _directions_ of the three coordinate axes to real-world directions, the _location_ of the coordinate
+ system's origin is still relative to the device, matching the device's position as of when the session configuration is first run.
+
+ - Note: Using gravity and heading alignment requires tracking the device's geographic location. Your app's Info.plist must include
+ user-facing text for the
+ [NSLocationUsageDescription](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html#//apple_ref/doc/plist/info/NSLocationUsageDescription)
+ or
+ [NSLocationWhenInUseUsageDescription](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html#//apple_ref/doc/plist/info/NSLocationWhenInUseUsageDescription)
+ key so that the user can grant your app permission for location tracking.
+ */
ARWorldAlignmentGravityAndHeading,
- /** Aligns the world with the camera’s orientation. */
+ /**
+ The scene coordinate system is locked to match the orientation of the camera.
+
+ Camera alignment defines a coordinate system based on the native sensor orientation of the device camera. Relative to a
+ <doc://com.apple.documentation/documentation/avfoundation/avcapturevideoorientation/landscaperight>-oriented camera image, the x-axis
+ points to the right, the y-axis points up, and the z-axis points out the front of the device (toward the user).
+
+ When this alignment is active, ARKit performs no device motion tracking. That is, world-space positions are effectively always relative to
+ the current position and orientation of the device. (For example, a SceneKit object placed in an ``ARSCNView`` will thus maintain the same
+ position on screen, even as the camera image changes while the device moves.)
+
+ - Note: This coordinate system is always the same regardless of device or user interface orientation. That is, the x-axis always points
+ along the long axis of the device, even if that direction is "down" relative to the user.
+ */
ARWorldAlignmentCamera
} NS_SWIFT_NAME(ARConfiguration.WorldAlignment);
/**
- Enum constants for indicating the mode of environment texturing to run.
+ The available environment texturing options for world tracking.
+
+ Environment textures are cube-map textures that depict the view in all directions from a specific point in a scene. In 3D asset rendering,
+ environment textures are the basis for image-based lighting algorithms where surfaces can realistically reflect light from their surroundings.
+ ARKit generates environment textures during an AR session using camera imagery, allowing SceneKit or a custom-rendering engine to provide
+ realistic image-based lighting for virtual objects in your AR experience.
+
+ To enable texture map generation for your configuration, change this property (from its default value of `AREnvironmentTexturingNone`):
+
+ - With `AREnvironmentTexturingManual` environment texturing, you identify points in the scene for which you want light probe texture maps by
+ creating ``AREnvironmentProbeAnchor`` objects and adding them to the session.
+ - With `AREnvironmentTexturingAutomatic` environment texturing, ARKit automatically creates, positions, and adds ``AREnvironmentProbeAnchor``
+ objects to the session.
+
+ In both cases, ARKit automatically generates environment textures as the session collects camera imagery. Use a delegate method such as
+ ``ARSessionDelegate/session:didUpdateAnchors:`` to find out when a texture is available, and access it from the anchor's
+ ``AREnvironmentProbeAnchor/environmentTexture`` property.
+
+ If you display AR content using ``ARSCNView`` and the ``ARSCNView/automaticallyUpdatesLighting`` option, SceneKit automatically retrieves
+ ``AREnvironmentProbeAnchor`` texture maps and uses them to light the scene.
*/
API_AVAILABLE(ios(12.0))
typedef NS_ENUM(NSInteger, AREnvironmentTexturing) {
- /** No texture information is gathered. */
+ /** The framework doesn't generate environment textures. */
AREnvironmentTexturingNone,
- /** Texture information is gathered for the environment.
- Environment textures will be generated for AREnvironmentProbes added to the session. */
+ /**
+ The framework generates environment textures only for probe anchors you explicitly add to the session.
+
+ When you use this environment texturing option, you must manually choose when and where to generate environment map textures:
+
+ 1. Create an ``AREnvironmentProbeAnchor`` object with a `transform` indicating its position in the scene.
+ 2. Add the probe anchor to the session with the ``ARSession/addAnchor:`` method.
+
+ If you display AR content using ``ARSCNView``, SceneKit automatically retrieves texture maps from probe anchors and uses them to light the
+ scene. Otherwise, use a delegate method such as ``ARSessionDelegate/session:didUpdateAnchors:`` to find out when the probe anchor's texture
+ has been updated and access the ``AREnvironmentProbeAnchor/environmentTexture`` property.
+ */
AREnvironmentTexturingManual,
- /** Texture information is gathered for the environment and probes automatically placed in the scene. */
+ /**
+ The framework automatically determines when and where to generate environment textures.
+
+ When you use this environment texturing option, ARKit automatically chooses positions in the scene to generate environment textures based
+ on the camera imagery it has collected and the other anchors you've placed.
+
+ If you display AR content using ``ARSCNView``, SceneKit automatically retrieves texture maps from probe anchors and uses them to light the
+ scene. Otherwise, use a delegate method such as ``ARSessionDelegate/session:didUpdateAnchors:`` to find out when the probe anchor's texture
+ has been updated and access the ``AREnvironmentProbeAnchor/environmentTexture`` property.
+ */
AREnvironmentTexturingAutomatic
} NS_SWIFT_NAME(ARWorldTrackingConfiguration.EnvironmentTexturing);
/**
- Types of scene reconstruction.
+ Options that enable ARKit to detect the shape of the physical environment.
+
+ When you set one of the these values onto a world-tracking configuration's ``ARWorldTrackingConfiguration/sceneReconstruction`` property,
+ ARKit provides you with a mesh that models the real-world surrounding the user.
*/
API_AVAILABLE(ios(13.4))
typedef NS_OPTIONS(NSUInteger, ARSceneReconstruction) {
/** No scene reconstruction is run. */
ARSceneReconstructionNone = 0,
- /** Scene reconstruction generates a mesh of the world */
+ /** A polygonal mesh approximation of the physical environment. */
ARSceneReconstructionMesh = (1 << 0),
- /** Scene reconstruction generates a mesh of the world with classification for each face. */
+ /** An approximate shape of the physical environment, including classification of the real-world objects within it. */
ARSceneReconstructionMeshWithClassification = (1 << 1) | (1 << 0)
} NS_SWIFT_NAME(ARConfiguration.SceneReconstruction);
/**
- An object to describe and configure the Augmented Reality techniques to be used in an ARSession.
+ The base object that contains information about how to configure an augmented reality session.
+
+ ``ARConfiguration`` defines a base class for the different options you can configure in your AR experience.
+
+ All AR configurations establish a correspondence between the real world that the device inhabits and the virtual 3D-coordinate space, where
+ you model content. When your app mixes virtual content with a live-camera image, the user experiences the illusion that your virtual content
+ is part of the real world.
+
+ To acquire the live-camera imagery, ARKit manages a camera-capture pipeline for you. Depending on the configuration you choose, it determines
+ the cameras that capture imagery, and which camera feed the app displays.
+
+ AR apps recognize real-world regions of interest. At runtime, ARKit generates an ``ARAnchor`` for a real-world object it recognizes, which
+ allows an app to refer to its details, such as size and physical location. The configuration you choose determines the kinds of real-world
+ objects ARKit recognizes and makes available to your app.
+
+ Don't allocate ``ARConfiguration`` yourself; instead, instantiate one of its subclasses.
+
+ For more information about the camera-capture pipeline, see <doc:choosing-which-camera-feed-to-augment>.
*/
API_AVAILABLE(ios(11.0))
@interface ARConfiguration : NSObject <NSCopying>
/**
- Determines whether this device supports the ARConfiguration.
+ A Boolean value indicating whether the current device supports this session configuration class.
+
+ Different types of AR experiences (which you configure using concrete ``ARConfiguration`` subclasses) can have different hardware
+ requirements.
+
+ Before attempting to create an AR configuration, verify that the user's device supports the configuration you plan to use by checking the
+ ``ARConfiguration/isSupported`` property of the corresponding configuration class. If this property's value is
+ <doc://com.apple.documentation/documentation/swift/false>, the current device does not support the requested configuration.
+
+ - Important: All ARKit configurations require an iOS device with an A9 or later processor. If your app otherwise supports other devices and
+ offers augmented reality as a secondary feature, use this property to determine whether to offer AR-based features to the user.
+
+ If your app requires ARKit for its core functionality, use the `arkit` key in the
+ <doc://com.apple.documentation/documentation/bundleresources/information-property-list/uirequireddevicecapabilities> section of your app's
+ Info.plist to make your app available only on devices that support ARKit.
*/
@property (class, nonatomic, readonly) BOOL isSupported;
/**
- A list of supported video formats for this configuration and device.
+ The set of video capture formats available on the current device.
- The first element in the list is the default format for session output.
+ By default, the ``ARConfiguration/videoFormat`` property for a new session configuration matches the first video capture format in this
+ array. To change the video format for a session, change that property's value to one of the other ``ARVideoFormat`` objects in this array.
+
+ - Important: ``ARConfiguration`` is an abstract base class, so its implementation of this property always returns an empty array. Read this
+ property from the configuration subclass you plan to use for your AR session, such as ``ARWorldTrackingConfiguration`` or
+ ``ARFaceTrackingConfiguration``.
+
+ Different devices and iOS versions offer different sets of supported video formats, but the order of this array always puts higher-quality
+ formats before lower-quality formats. For best results across all devices and versions, choose formats based on their order in the array
+ rather than on hard-coded minimum resolution or frame rate values.
*/
@property (class, nonatomic, readonly) NSArray<ARVideoFormat *> *supportedVideoFormats API_AVAILABLE(ios(11.3));
@@ -151,82 +310,152 @@
@property (nonatomic, strong) ARVideoFormat *videoFormat API_AVAILABLE(ios(11.3));
/**
- Determines how the coordinate system should be aligned with the world.
+ A value specifying how the session maps real-world device motion into a 3D scene coordinate system.
- The default is `ARWorldAlignmentGravity`.
+ Creating an AR experience depends on being able to construct a coordinate system for placing objects in a virtual 3D world that maps to the
+ real-world position and motion of the device. When you run a session configuration, ARKit creates a scene coordinate system based on the
+ position and orientation of the device; any ``ARAnchor`` objects you create or that the AR session detects are positioned relative to that
+ coordinate system.
+
+ See ``ARWorldAlignment`` for possible values. The default is `ARWorldAlignmentGravity`.
*/
@property (nonatomic, assign) ARWorldAlignment worldAlignment;
/**
- Enable or disable light estimation.
+ A Boolean value specifying whether ARKit analyzes scene lighting in captured camera images.
- Enabled by default.
+ When this value is <doc://com.apple.documentation/documentation/swift/true> (the default), a running AR session provides scene lighting
+ information in the ``ARFrame/lightEstimate`` property of each ``ARFrame`` object it captures.
+
+ If you render your own overlay graphics for the AR scene, you can use this information in shading algorithms to help make those graphics match
+ the real-world lighting conditions of the scene captured by the camera. (A
+ <doc://com.apple.documentation/documentation/realitykit/realityview> or <doc://com.apple.documentation/documentation/realitykit/arview>
+ automatically uses this information to configure RealityKit lighting.)
*/
@property (nonatomic, assign, getter=isLightEstimationEnabled) BOOL lightEstimationEnabled;
/**
- Determines whether to capture and provide audio data.
+ A Boolean value that specifies whether to capture audio during the AR session.
- Disabled by default.
+ To receive and handle captured audio data, your session delegate must implement the
+ ``ARSessionObserver/session:didOutputAudioSampleBuffer:`` method. Disabled by default.
*/
@property (nonatomic, assign) BOOL providesAudioData;
/**
- The type of semantic understanding to provide with each frame.
+ The set of frame semantics you want ARKit to provide with each frame.
- Use the `supportsFrameSemantics` class method to check if the configuration type you intend to run supports the set of frame semantics.
- For example, when running a session with a configuration of type `ARWorldTrackingConfiguration` one would need to use `+[
- ARWorldTrackingConfiguration supportsFrameSemantics:]` to perform said check. An exception is thrown if the option is not supported. Defaults to
+ You can choose whether ARKit reports information about a particular per-frame metric, or _semantic_. Before enabling a frame semantic, call
+ ``ARConfiguration/supportsFrameSemantics:`` to ensure device support. An exception is thrown if the option is not supported. Defaults to
`ARFrameSemanticNone`.
+ ### Enable 2D Body Detection
+
+ To get information about the 2D location of a person that ARKit recognizes in a frame, you enable the ``ARFrameSemanticBodyDetection`` frame
+ semantic.
+
+ ```swift
+ if let config = mySession.configuration as? ARBodyTrackingConfiguration {
+ config.frameSemantics.insert(.bodyDetection)
+ // Run the configuration to effect a frame semantics change.
+ mySession.run(config)
+ }
+ ```
+
+ ### Enable People Occlusion
+
+ People occlusion is a feature that enables people in the camera feed to cover your app's virtual content.
+
+ To indicate that a person should overlap your app's virtual content when the person is closer to the camera than the virtual content, add the
+ ``ARFrameSemanticPersonSegmentationWithDepth`` option to your configuration's frame semantics.
+
+ ```swift
+ if let config = mySession.configuration as? ARWorldTrackingConfiguration {
+ config.frameSemantics.insert(.personSegmentationWithDepth)
+ // Run the configuration to effect a frame semantics change.
+ mySession.run(config)
+ }
+ ```
+
+ To indicate that a person should overlap your app's virtual content regardless of the person's depth in the scene, use the
+ ``ARFrameSemanticPersonSegmentation`` frame semantic instead. This option is particularly appropriate for green-screen scenarios.
+
+ Standard renderers (<doc://com.apple.documentation/documentation/realitykit/arview>, and ``ARSCNView``) implement people occlusion for you.
+ See <doc:occluding-virtual-content-with-people> for a sample app that demonstrates people occlusion in RealityKit.
+
+ If you implement your own renderer, use ``ARFrame/segmentationBuffer`` and ``ARFrame/estimatedDepthData`` to implement people occlusion
+ yourself. ``ARMatteGenerator`` helps you by providing masks. For a sample app that demonstrates matte generator and people occlusion, see
+ <doc:effecting-people-occlusion-in-custom-renderers>.
+
+ If you enable Scene Reconstruction, ARKit adjusts the mesh according to any people ARKit may detect in the camera feed. ARKit removes any part
+ of the scene mesh that overlaps with people, as defined by the with- or without-depth frame semantics. For more information about scene
+ reconstruction, see <doc:visualizing-and-interacting-with-a-reconstructed-scene>.
+
- SeeAlso: ``ARFrameSemantics``
- SeeAlso: ``ARConfiguration/supportsFrameSemantics:``
*/
@property (nonatomic, assign) ARFrameSemantics frameSemantics API_AVAILABLE(ios(13.0));
/**
- Determines whether the type of frame semantics is supported by the device and ARConfiguration class.
+ Checks whether the device and configuration support a frame semantic.
- Semantic frame understanding is not supported on all devices. Use the `supportsFrameSemantics` class method to check if the configuration
- type you intend to run supports the set of frame semantics. For example, when running a session with a configuration of type
- ARWorldTrackingConfiguration one would need to use
- `+[ ARWorldTrackingConfiguration supportsFrameSemantics:]` to perform said check.
+ Call this function before attempting to enable a frame semantic on your app's configuration. For example, if you call
+ `supportsFrameSemantics(.sceneDepth)` on ``ARWorldTrackingConfiguration``, the function returns
+ <doc://com.apple.documentation/documentation/swift/true> on devices that support the LiDAR scanner's depth buffer.
- - Parameter frameSemantics: The frame semantics to check for support.
+ - Parameter frameSemantics: The frame semantics for which to check device support.
- - Returns: `YES` if the frame semantics are supported on this device and configuration class, `NO` otherwise.
+ - Returns: A boolean value that indicates whether the device supports the argument frame semantics.
+ - Warning: Do not call this function on the superclass, ``ARConfiguration``. Only configuration subclasses support frame semantics.
+
- SeeAlso: ``ARFrameSemantics``
*/
+ (BOOL)supportsFrameSemantics:(ARFrameSemantics)frameSemantics API_AVAILABLE(ios(13.0));
/**
- Returns a pointer to the capture device of the camera that's used for rendering, so developers can adjust capture settings.
+ An object that enables you to alter the appearance of a frame's captured image.
- Note: Modifying capture settings can impact performance of tracking or other algorithms, particularly on devices with a single rear camera.
+ This property provides the underlying capture device for the framework's camera feed. By altering the device's configuration, your app
+ indirectly adjusts the visual properties of the each AR frame's ``ARFrame/capturedImage``.
+
+ Alter the device's settings with caution, as extreme changes can affect ARKit's features that rely on the ``ARFrame/capturedImage`` and depend
+ on its integrity, such as people occlusion that uses ``ARFrameSemanticPersonSegmentation``.
+
+ - Important: This property is `nil` on devices that aren't equipped with an ultra-wide camera.
*/
@property (class, nonatomic, nullable, readonly) AVCaptureDevice *configurableCaptureDeviceForPrimaryCamera API_AVAILABLE(ios(16.0));
/**
- Returns a video format using a 4K resolution from the list of supported video formats.
+ Provides a 4K video format if the device and configuration support it.
- May return `nil` if 4K is not supported for this configuration or device.
+ If the device and configuration support 4K, the returned video format is also present in the configuration's
+ ``ARConfiguration/supportedVideoFormats`` array.
+
+ This function returns `nil` if the device or configuration doesn't support 4K, so you can call this function to determine whether to enable 4K
+ for your session.
*/
@property (class, nonatomic, nullable, readonly) ARVideoFormat *recommendedVideoFormatFor4KResolution API_AVAILABLE(ios(16.0));
/**
- Returns a recommended video format that supports capturing high resolution frames with a significantly higher resolution than the streaming camera
- resolution.
+ Returns a video format that the framework recommends for high-resolution-still-image capture.
- Using this format may consume more power. Other video formats may support capturing high resolution frames as well, albeit at a lower
- quality or resolution.
+ The framework determines the resolution of the camera feed and still-image capture for this format. Call this function when your app requires
+ a high-resolution still capture regardless of format specifics. If instead, your app requires a particular resolution, iterate over the
+ ``ARConfiguration/supportedVideoFormats`` array and choose a format with the desired configuration where
+ ``ARVideoFormat/isRecommendedForHighResolutionFrameCapturing`` is `true`.
+ Other video formats may support still-image capture but at a lower quality or resolution.
+
- SeeAlso: ``ARSession/captureHighResolutionFrameWithCompletion:``
*/
@property (class, nonatomic, nullable, readonly) ARVideoFormat *recommendedVideoFormatForHighResolutionFrameCapturing API_AVAILABLE(ios(16.0));
/**
- Whether HDR capturing is allowed if the current video format supports it. Defaults to `NO`.
+ Enables high dynamic range (HDR) for the session's camera feed.
+
+ Before calling this function, check whether the session configuration's video format supports HDR first by calling
+ ``ARVideoFormat/isVideoHDRSupported``. Defaults to `NO`.
*/
@property (nonatomic, assign, readwrite) BOOL videoHDRAllowed API_AVAILABLE(ios(16.0));
@@ -247,83 +476,174 @@
@end
/**
- A configuration for running world tracking.
+ A configuration that tracks the position of a device in relation to objects in the environment.
- World tracking provides `6` degrees of freedom tracking of the device.
- By finding feature points in the scene, world tracking enables performing hit-tests against the frame.
- Tracking can no longer be resumed once the session is paused.
+ The ``ARWorldTrackingConfiguration`` class tracks the device's movement with six degrees of freedom (6DOF): the three rotation axes (roll,
+ pitch, and yaw), and three translation axes (movement in x, y, and z).
+
+ This kind of tracking can create immersive AR experiences: A virtual object can appear to stay in the same place relative to the real world,
+ even as the user tilts the device to look above or below the object, or moves the device around to see the object's sides and back.
+
+ Tracking can no longer be resumed once you pause the session.
+
+ World-tracking sessions also provide several ways for your app to recognize or interact with elements of the real-world scene visible to the
+ camera:
+
+ - Find real-world horizontal or vertical surfaces with ``planeDetection``. Add the surfaces to the session as ``ARPlaneAnchor`` objects.
+ - Recognize and track the movement of 2D images with ``detectionImages``. Add 2D images to the scene as ``ARImageAnchor`` objects.
+ - Recognize 3D objects with ``detectionObjects``. Add 3D objects to the scene as ``ARObjectAnchor`` objects.
+ - Find the 3D positions of real-world features that correspond to a touch point on the device's screen with ray casting.
*/
API_AVAILABLE(ios(11.0))
@interface ARWorldTrackingConfiguration : ARConfiguration
/**
- Enable or disable continuous auto focus.
+ A Boolean value that determines whether the device camera uses fixed focus or autofocus behavior.
- Enabled by default.
+ For apps deployed to iOS 11.3 or later, ARKit enables autofocus by default.
*/
@property (nonatomic, assign, getter=isAutoFocusEnabled) BOOL autoFocusEnabled API_AVAILABLE(ios(11.3));
/**
- The mode of environment texturing to run.
+ An option that determines how the framework generates environment textures.
- If set, texture information will be accumulated and updated. Adding an `AREnvironmentProbeAnchor` to the session
- will get the current environment texture available from that probe's perspective which can be used for lighting
- virtual objects in the scene. Defaults to `AREnvironmentTexturingNone`.
+ Environment textures are cube-map textures that depict the view in all directions from a specific point in a scene. In 3D asset rendering,
+ environment textures are the basis for image-based lighting algorithms where surfaces can realistically reflect light from their surroundings.
+ ARKit generates environment textures during an AR session using camera imagery, allowing SceneKit or a custom-rendering engine to provide
+ realistic image-based lighting for virtual objects in your AR experience.
+
+ To enable texture map generation for your configuration, change this property (from its default value of ``AREnvironmentTexturingNone``):
+
+ - With ``AREnvironmentTexturingManual`` environment texturing, you identify points in the scene for which you want light probe texture maps by
+ creating ``AREnvironmentProbeAnchor`` objects and adding them to the session.
+ - With ``AREnvironmentTexturingAutomatic`` environment texturing, ARKit automatically creates, positions, and adds ``AREnvironmentProbeAnchor``
+ objects to the session.
+
+ In both cases, ARKit automatically generates environment textures as the session collects camera imagery. Use a delegate method such as
+ ``ARSessionDelegate/session:didUpdateAnchors:`` to find out when a texture is available, and access it from the anchor's
+ ``AREnvironmentProbeAnchor/environmentTexture`` property.
+
+ If you display AR content using ``ARSCNView`` and the ``ARSCNView/automaticallyUpdatesLighting`` option, SceneKit automatically retrieves
+ ``AREnvironmentProbeAnchor`` texture maps and uses them to light the scene.
*/
@property (nonatomic, assign) AREnvironmentTexturing environmentTexturing API_AVAILABLE(ios(12.0));
/**
- Determines whether environment textures will be provided with high dynamic range. Enabled by default.
+ A flag that instructs the framework to create environment textures in HDR format.
+
+ If you set ``environmentTexturing`` to `.automatic` in iOS 12 or later, ARKit gives you environment textures you cast on your app's virtual
+ content to create realistic reflections. By default, the framework sets ``wantsHDREnvironmentTextures`` to
+ <doc://com.apple.documentation/documentation/swift/true>. When your renderer supports HDR environment textures in iOS 13, it enables your
+ lighting engine to output more colors, with a more realistic result.
+
+ Both <doc://com.apple.documentation/documentation/realitykit/arview> and ``ARSCNView`` support HDR environment textures. For more information,
+ see <doc:adding-realistic-reflections-to-an-ar-experience>.
+
+ For a Metal app that doesn't yet support HDR environment textures, you can use the following code to receive LDR environment textures until
+ you're ready to update your renderer for HDR.
+
+ ```swift
+ if #available(iOS 13, *) {
+ configuration.wantsHDREnvironmentTextures = false
+ }
+ ```
*/
@property (nonatomic, assign) BOOL wantsHDREnvironmentTextures API_AVAILABLE(ios(13.0));
/**
- Type of planes to detect in the scene.
+ The configuration's plane detection options.
- If set, new planes will continue to be detected and updated over time. Detected planes will be added to the session as
- ARPlaneAnchor objects. In the event that two planes are merged, the newer plane will be removed. Defaults to ARPlaneDetectionNone.
+ If set, new planes will continue to be detected and updated over time. Detected planes will be added to the session as ``ARPlaneAnchor``
+ objects. In the event that two planes are merged, the newer plane will be removed. Defaults to `ARPlaneDetectionNone`.
*/
@property (nonatomic, assign) ARPlaneDetection planeDetection;
/**
- The initial map of the physical space that world tracking will localize to and track.
+ The state from a previous AR session to attempt to resume with this session configuration.
- If set, the session will attempt to localize to the provided map with
- a limited tracking state until localization is successful or run is called again
- with a different (or no) initial map specified. Once localized, the map will be extended
- and can again be saved using the `getCurrentWorldMap` method on the session.
+ An ``ARWorldMap`` encapsulates the state of a running ``ARSession``. This state includes ARKit's awareness of the physical space the user
+ moves the device in (which ARKit uses to determine the device's position and orientation), as well as any ``ARAnchor`` objects added to the
+ session (which can represent detected real-world features or virtual content placed by your app). After you use
+ ``ARSession/getCurrentWorldMap:`` to save a session's world map, you can assign it to a configuration's ``initialWorldMap`` property and use
+ ``ARSession/runWithConfiguration:options:`` to start another session with the same spatial awareness and anchors.
+
+ By saving world maps and using them to start new sessions, your app can add new AR capabilities:
+
+ - **Multiuser AR experiences.** Create a shared frame of reference by sending archived ``ARWorldMap`` objects to a nearby user's device. With
+ two devices tracking the same world map, you can build a networked experience where both users can see and interact with the same virtual
+ content.
+ - **Persistent AR experiences.** Save a world map when your app becomes inactive, then restore it the next time your app launches in the same
+ physical environment. You can use anchors from the resumed world map to place the same virtual content at the same positions from the saved
+ session.
+
+ When you run a session with an initial world map, the session starts in the limited (relocalizing) tracking state while ARKit attempts to
+ reconcile the recorded world map with the current environment. If successful, the tracking state becomes normal after a short time, indicating
+ that the current world coordinate system and anchors match those from the recorded world map.
+
+ If ARKit cannot reconcile the recorded world map with the current environment (for example, if the device is in an entirely different place
+ from where the world map was recorded), the session remains in the relocalizing state indefinitely.
*/
@property (nonatomic, strong, nullable) ARWorldMap *initialWorldMap API_AVAILABLE(ios(12.0));
/**
- Images to detect in the scene.
+ A set of images that ARKit searches for in the user's environment.
- If set the session will attempt to detect the specified images. When an image is detected an `ARImageAnchor` will be added to the session.
+ Add members to this set for each image that ARKit searches for in the user's environment. When ARKit _detects_ a matching image, the
+ framework creates an ``ARImageAnchor`` object and adds it to the session.
+
+ To define the reference images that this property contains, create an asset catalog in Xcode or create ``ARReferenceImage`` objects
+ programmatically. For more information, see <doc:detecting-images-in-an-ar-experience>.
+
+ If you set a nonzero value for ``maximumNumberOfTrackedImages``, ARKit enables image _tracking_, which continuously updates the transform for
+ up to four of the reference image anchors as the session progresses. For an example, see <doc:tracking-and-altering-images>.
+
+ ### Limit Reference Images for Performance
+
+ Image detection accuracy and performance may decline as the number of images in this set increases. For best results, limit your detection
+ image count to no more than around 100.
+
+ To detect more than 100 images, your app can allocate a certain amount of time for the first 100 images before moving on to the next 100, and
+ so on. When you update the contents of this property, call ``ARSession/runWithConfiguration:options:`` again with your app's configuration to
+ effect the change.
*/
@property (nonatomic, copy, null_resettable) NSSet<ARReferenceImage *> *detectionImages API_AVAILABLE(ios(11.3));
/**
- Enables the estimation of a scale factor which may be used to correct the physical size of an image.
+ A flag that instructs the framework to estimate and set the scale of a detected or tracked image on your behalf.
- If set to `true` ARKit will attempt to use the computed camera positions in order to compute the scale by which the given physical size
- differs from the estimated one. The information about the estimated scale can be found as the property estimatedScaleFactor on the ARImageAnchor.
+ If set to <doc://com.apple.documentation/documentation/swift/true>, ARKit uses its knowledge of the world to set an image anchor's
+ ``ARImageAnchor/estimatedScaleFactor`` property, which corrects the image anchor's position in the physical environment.
- - Note: When set to true the transform of a returned `ARImageAnchor` will use the estimated scale factor to correct the translation. Default value is
- `NO`.
+ Enable this property when you want to detect different-sized versions of a reference image. ARKit must know the physical size of an image in
+ the real world to accurately estimate its real-world position. Enable this property to tell ARKit to estimate a recognized image's physical
+ size before it calculates the real-world position.
+
+ - Note: When set to true the transform of a returned `ARImageAnchor` will use the estimated scale factor to correct the translation. Default
+ value is `NO`.
*/
@property (nonatomic, assign) BOOL automaticImageScaleEstimationEnabled API_AVAILABLE(ios(13.0));
/**
- Maximum number of images to track simultaneously.
+ The number of image anchors to monitor closely for position and orientation updates.
- Setting the maximum number of tracked images will limit the number of images that can be tracked in a given frame.
- If more than the maximum is visible, only the images already being tracked will continue to track until tracking is lost or another image is removed.
- Images will continue to be detected regardless of images tracked. Default value is zero.
+ When you set a nonzero value for this property, the framework keeps that many image anchors up to date as the session progresses. The
+ framework can track a maximum of four images simultaneously.
+
+ The word _track_ in the property name refers to how the framework closely monitors the image's physical position and orientation for any
+ changes. If the image moves, the framework updates the associated ``ARImageAnchor`` transform with the new pose. ARKit checks for changes
+ every frame.
+
+ ARKit tracks the first images it observes in the physical environment from the ``detectionImages`` set. When a session reaches the maximum
+ number of tracked images, the framework attempts to track another member of the set only after one of the existing tracked images leaves the
+ device's view.
+
+ The default value is `0`, which disables image tracking. If you add reference images to ``detectionImages`` with this property set to `0`,
+ ARKit creates image anchors for observed reference images but their positions only update infrequently, such as once every couple of seconds.
*/
@property (nonatomic, assign) NSInteger maximumNumberOfTrackedImages API_AVAILABLE(ios(12.0));
/**
- Objects to detect in the scene.
+ A set of 3D objects that the framework attempts to detect in the user's environment.
The system keeps the object's pose stable in world space, consuming less power. Virtual content stays aligned with the
object as long as it doesn't move; if the object moves, the system may delay the pose update. When an object is
@@ -353,44 +673,112 @@
@property (nonatomic, copy) NSSet<ARReferenceObject *> *trackingObjects API_AVAILABLE(ios(27.0));
/**
- Enable/disable a collaborative session. Disabled by default.
+ A flag that opts you in to a peer-to-peer multiuser AR experience.
- When enabled, `ARSession` will output collaboration data for other participants using its delegate `didOutputCollaborationData`.
- It is the responsibility of the caller to send the data to each participant. When data is received by a participant, it
- should be passed to the ARSession by calling updateWithCollaborationData.
+ The default value of this property is <doc://com.apple.documentation/documentation/swift/false>. When you enable collaboration, ARKit invokes
+ ``ARSessionObserver/session:didOutputCollaborationData:`` periodically, providing you with collaboration data to share with peers.
+ Collaboration data contains information about the real-world surfaces ARKit detects, your position in relation to them, and any anchors you
+ may have created.
+
+ Multiple users sharing collaboration data with each other results in an AR experience in which the users interact by sharing and manipulating
+ anchors. By including information that describes a user's unique view of the world, collaboration data enhances ARKit's understanding of the
+ layout of the physical environment much more quickly than is possible with only one user.
+
+ For more information, see <doc:creating-a-collaborative-session>.
+
+ - Important: Collaborative sessions work best with up to four participants.
+
+ ### Sharing Collaboration Data Over the Network
+
+ You are responsible for sending collaboration data over the network, including choosing the network framework and implementing the code. See
+ <doc:creating-a-multiuser-ar-experience> for an example app that shares a world map among users via
+ <doc://com.apple.documentation/documentation/multipeerconnectivity>. Although <doc:creating-a-multiuser-ar-experience> demonstrates sharing
+ world data among peer users, it does so using a host-guest model. The primary advantage of collaboration data is that it enables you to share
+ world data peer-to-peer.
+
+ The data you send is a serialized version of the ``ARSession/CollaborationData`` object provided by your session. You serialize it using
+ <doc://com.apple.documentation/documentation/foundation/nskeyedarchiver>.
+
+ ```swift
+ func session(_ session: ARSession, didOutputCollaborationData data: ARSession.CollaborationData) {
+ if let collaborationDataEncoded = try? NSKeyedArchiver.archivedData(withRootObject: data, requiringSecureCoding: true) {
+ multipeerSession.sendToAllPeers(collaborationDataEncoded)
+ } else {
+ fatalError("An error occurred while encoding collaboration data.")
+ }
+ }
+ ```
+
+ ### Updating Your Session with Collaboration Data
+
+ When you receive collaboration data from other people, you instantiate an ``ARSession/CollaborationData`` object with it and pass the object
+ to your session with ``ARSession/updateWithCollaborationData:``. For optimum performance, it's helpful if the participants in a collaborative
+ session are on the same OS version. Unarchiving `ARSession.CollaborationData` received from a device running a different OS version may fail.
+
+ ```swift
+ func receivedData(_ data: Data) {
+ if let collaborationData = try? NSKeyedUnarchiver.unarchivedObject(ofClass: ARSession.CollaborationData.self, from: data) {
+ session.update(with: collaborationData)
+ } else {
+ print("A device running an incompatible OS version is in the collaborative session.")
+ }
+ }
+ ```
*/
@property (nonatomic, assign, getter=isCollaborationEnabled) BOOL collaborationEnabled API_AVAILABLE(ios(13.0));
/**
- Indicates whether user face tracking using the front facing camera can be enabled on this device.
+ A Boolean value that tells you whether the iOS device supports tracking the user's face during a world-tracking session.
+
+ Check the value of this property first, before you enable face tracking using ``userFaceTrackingEnabled``.
*/
@property (class, nonatomic, readonly) BOOL supportsUserFaceTracking API_AVAILABLE(ios(13.0));
/**
- Enable or disable running Face Tracking using the front facing camera. Disabled by default.
+ A flag that determines whether ARKit tracks the user's face in a world-tracking session.
- When enabled, ARSession detects faces (if visible in the front-facing camera image) and adds to its list of anchors,
- an ARFaceAnchor object representing each face.
+ When enabled, ARKit provides you with an ``ARFaceAnchor`` that represents the user's face during your world tracking session. For example, you
+ can share avatar expressions with multiple users in a multiplayer game, or enable the player to control a virtual object in the physical
+ environment using facial expressions.
- The transform of the `ARFaceAnchor` objects will be in the world coordinate space.
+ Check whether the device supports tracking of the user's face by using ``supportsUserFaceTracking`` before enabling this property. Disabled by
+ default. The transform of the ``ARFaceAnchor`` objects will be in the world coordinate space.
- SeeAlso: ``ARFaceAnchor``
*/
@property (nonatomic, assign, getter=userFaceTrackingEnabled) BOOL userFaceTrackingEnabled API_AVAILABLE(ios(13.0));
/**
- Enable or disable app clip code tracking. Disabled by default. When enabled, detected app clip codes will be surfaced as an ARAppClipCodeAnchor.
+ A Boolean value that indicates if the framework searches the physical environment for App Clip Codes.
+
+ When this property's value is <doc://com.apple.documentation/documentation/swift/true>, the session delegate receives an
+ ``ARAppClipCodeAnchor`` via ``ARSessionDelegate/session:didAddAnchors:`` for every App Clip Code that ARKit detects in the physical
+ environment. The default value is <doc://com.apple.documentation/documentation/swift/false>.
+
+ Before calling this function, check that the configuration supports App Clip Code tracking by calling ``supportsAppClipCodeTracking``.
+
+ To avoid scanning a physical code that's not connected to an App Clip, the system ensures that an app provides an App Clip before allowing the
+ app to interact with App Clip Codes. Without providing an App Clip, the app can recognize codes in the environment by determining their
+ physical location (``ARAnchor/transform``), but code URLs (``ARAppClipCodeAnchor/url``) remain `nil`.
*/
@property (nonatomic, assign) BOOL appClipCodeTrackingEnabled API_AVAILABLE(ios(14.3));
/**
- Indicates whether app clip code tracking can be enabled on this device.
+ A flag that indicates if the device tracks App Clip Codes.
+
+ Devices require the Apple Neural Engine (ANE) to track App Clip Codes. The system sets this property to
+ <doc://com.apple.documentation/documentation/swift/true> if the device contains the ANE chip. The default value of this property is
+ <doc://com.apple.documentation/documentation/swift/false>.
+
+ Call this function before setting ``appClipCodeTrackingEnabled``.
*/
@property (class, nonatomic, readonly) BOOL supportsAppClipCodeTracking API_AVAILABLE(ios(14.3));
/**
- Indicates whether the scene reconstruction type is supported for the configuration on this device.
+ Checks if the device supports scene reconstruction.
+ Scene reconstruction requires a device with a LiDAR Scanner, such as the fourth-generation iPad Pro.
+
- Parameter sceneReconstruction: The scene reconstruction type to check for support.
- Returns: `YES` if the scene reconstruction type is supported on this device, `NO` otherwise.
@@ -398,96 +786,139 @@
+ (BOOL)supportsSceneReconstruction:(ARSceneReconstruction)sceneReconstruction API_AVAILABLE(ios(13.4));
/**
- Type of scene reconstruction to run. Defaults to ARSceneReconstructionNone.
+ A flag that enables scene reconstruction.
- If set to a value other than `ARSceneReconstructionNone`, output of scene reconstruction will be added to the session as
- ARMeshAnchor objects.
+ When you enable scene reconstruction, ARKit provides a polygonal mesh that estimates the shape of the physical environment. Before setting
+ this property, call ``supportsSceneReconstruction:`` to ensure device support. For a sample app that demonstrates scene reconstruction, see
+ <doc:visualizing-and-interacting-with-a-reconstructed-scene>.
+ If you enable plane detection, ARKit applies that information to the mesh. Where the LiDAR scanner may produce a slightly uneven mesh on a
+ real-world surface, ARKit smooths out the mesh where it detects a plane on that surface.
+
+ If you enable people occlusion, ARKit adjusts the mesh according to any people it detects in the camera feed. ARKit removes any part of the
+ scene mesh that overlaps with people, as defined by the ``ARFrameSemanticPersonSegmentation`` or ``ARFrameSemanticPersonSegmentationWithDepth``
+ frame semantics.
+
+ If set to a value other than `ARSceneReconstructionNone`, output of scene reconstruction will be added to the session as ``ARMeshAnchor``
+ objects. Defaults to `ARSceneReconstructionNone`.
+
- SeeAlso: ``ARMeshAnchor``
*/
@property (nonatomic, assign) ARSceneReconstruction sceneReconstruction API_AVAILABLE(ios(13.4));
/**
- Initializes a new world tracking configuration.
+ Initializes a new world-tracking configuration.
- - Returns: An initialized world tracking configuration.
+ To use the configuration in an AR experience, pass it as an argument to your app's ``ARSession/runWithConfiguration:options:`` function.
*/
- (instancetype)init;
/**
- Unavailable. Use init instead.
+ Creates a new world-tracking configuration.
- - Returns: This method is unavailable.
+ To use the configuration in an AR experience, pass it as an argument to your app's ``ARSession/runWithConfiguration:options:`` function.
*/
+ (instancetype)new NS_SWIFT_UNAVAILABLE("Use init() instead");
@end
/**
- A configuration for running orientation tracking.
+ A configuration that tracks only the device's orientation using the rear-facing camera.
- Orientation tracking provides `3` degrees of freedom tracking of the device.
+ All AR configurations establish a correspondence between the real world the device inhabits and a virtual 3D coordinate space where you can
+ model content. When your app displays that content together with a live camera image, the user experiences the illusion that your virtual
+ content is part of the real world.
+
+ Creating and maintaining this correspondence between spaces requires tracking the device's motion. The ``AROrientationTrackingConfiguration``
+ class tracks the device's movement with three degrees of freedom (3DOF): specifically, the three rotation axes (roll, pitch, and yaw).
+
+ This basic level of motion tracking can create limited AR experiences: A virtual object can appear to be part of the real world, even as the
+ user rotates the device to look above, below, or beside that object. However, this configuration cannot track movement of the device:
+ non-trivially changing the device's position breaks the AR illusion, causing virtual content to appear to drift relative to the real world.
+ For example, the user cannot walk around to see the sides and back of a virtual object. Additionally, 3DOF tracking does not support plane
+ detection or hit testing.
+
+ - Important: Because 3DOF tracking creates limited AR experiences, you should generally not use the ``AROrientationTrackingConfiguration``
+ class directly. Instead, use ``ARWorldTrackingConfiguration`` for six degrees of freedom (6DOF) plane detection and hit testing. Use 3DOF
+ tracking only as a fallback in situations where 6DOF tracking is temporarily unavailable.
*/
API_AVAILABLE(ios(11.0))
@interface AROrientationTrackingConfiguration : ARConfiguration
/**
- Enable or disable continuous auto focus.
+ A Boolean value that determines whether the device camera uses fixed focus or autofocus behavior.
- Enabled by default.
+ In apps linked against the iOS 11.3 SDK or later, ARKit enables autofocus by default.
*/
@property (nonatomic, assign, getter=isAutoFocusEnabled) BOOL autoFocusEnabled API_AVAILABLE(ios(11.3));
/**
Initializes a new orientation tracking configuration.
- - Returns: An initialized orientation tracking configuration.
+ To use the configuration in an AR session, pass it to the ``ARSession`` ``ARSession/runWithConfiguration:options:`` method.
*/
- (instancetype)init;
/**
- Unavailable. Use init instead.
+ Creates a new orientation tracking configuration.
- - Returns: This method is unavailable.
+ To use the configuration in an AR session, pass it to the ``ARSession`` ``ARSession/runWithConfiguration:options:`` method.
*/
+ (instancetype)new NS_SWIFT_UNAVAILABLE("Use init() instead");
@end
/**
- A configuration for running face tracking.
+ A configuration that tracks facial movement and expressions using the front camera.
- Face tracking uses the front facing camera to track the face in 3D providing details on the topology and expression of the face.
- A detected face will be added to the session as an ARFaceAnchor object which contains information about head pose, mesh, eye pose, and blend shape
- coefficients. If light estimation is enabled the detected face will be treated as a light probe and used to estimate the direction of incoming light.
+ A face-tracking configuration detects faces within 3 meters of the device's front camera. When ARKit detects a face, it creates an
+ ``ARFaceAnchor`` object that provides information about a person's facial position, orientation, topology, and expressions.
+
+ Face tracking supports devices with Apple Neural Engine in iOS 14 and iPadOS 14 and requires a device with a TrueDepth camera on iOS 13 and
+ iPadOS 13 and earlier. To determine whether the device supports face tracking, call ``ARConfiguration/isSupported`` on
+ ``ARFaceTrackingConfiguration`` before attempting to use this configuration.
+
+ When you enable the ``ARConfiguration/isLightEstimationEnabled`` setting, a face-tracking configuration estimates directional and
+ environmental lighting (an ``ARDirectionalLightEstimate`` object) by referring to the detected face as a light probe.
+
+ - Note: Because face tracking provides your app with personal facial information, your app must include a privacy policy describing to users
+ how you intend to use face tracking and face data. For details, see the
+ [Apple Developer Program License Agreement](https://developer.apple.com/terms/).
*/
API_AVAILABLE(ios(11.0))
@interface ARFaceTrackingConfiguration : ARConfiguration
/**
- Maximum number of faces which can be tracked simultaneously.
+ The maximum number of faces that the framework can track.
+
+ Do not exceed this value when you set ``maximumNumberOfTrackedFaces``.
*/
@property (class, nonatomic, readonly) NSInteger supportedNumberOfTrackedFaces API_AVAILABLE(ios(13.0));
/**
- Maximum number of faces to track simultaneously.
+ The number of faces to track during the session.
- Setting the maximum number of tracked faces will limit the number of faces that can be tracked in a given frame.
- If more than the maximum is visible, only the faces already being tracked will continue to track until tracking is lost or another face is removed.
- Default value is one.
+ The default value is one. Set the maximum number of tracked faces to limit the number of faces that can be tracked in a given frame. Check
+ the value of ``supportedNumberOfTrackedFaces`` before setting this property.
+
+ No new anchors will be provided to your delegate's ``ARSessionDelegate/session:didAddAnchors:`` if more than the maximum number of faces are
+ visible in the camera feed. In that case, ARKit continues to track the faces that already have associated face anchors.
*/
@property (nonatomic, assign) NSInteger maximumNumberOfTrackedFaces API_AVAILABLE(ios(13.0));
/**
- Indicates whether world tracking can be enabled on this device.
+ A Boolean value that indicates whether the iOS device supports tracking the world in a face-tracking session.
+
+ Check this property before attempting to enable world tracking in a face tracking configuration using ``isWorldTrackingEnabled``.
*/
@property (class, nonatomic, readonly) BOOL supportsWorldTracking API_AVAILABLE(ios(13.0));
/**
- Enable or disable World Tracking. Disabled by default.
+ A Boolean value that instructs a session to provide the app with the device's six degrees of freedom pose during a face-tracking session.
- When enabled, `ARSession` uses the back facing camera to track the device's orientation and position in the world. The camera transform and
- the ARFaceAnchor transform will be in the world coordinate space.
+ Before attempting to enable this property, check whether the iOS device supports user-face tracking in a world-tracking session, by calling
+ ``supportsWorldTracking``. Disabled by default. When enabled, `ARSession` uses the back facing camera to track the device's orientation and
+ position in the world. The camera transform and the ``ARFaceAnchor`` transform will be in the world coordinate space.
*/
@property (nonatomic, assign, getter=isWorldTrackingEnabled) BOOL worldTrackingEnabled API_AVAILABLE(ios(13.0));
@@ -499,113 +930,166 @@
@property (nonatomic, assign, getter=isEnvironmentTexturingEnabled) BOOL environmentTexturingEnabled API_AVAILABLE(ios(27.0));
/**
- Initializes a new face tracking configuration.
+ Creates a new face-tracking configuration.
- - Returns: An initialized face tracking configuration.
+ To use the configuration in an AR session, pass it to the ``ARSession`` ``ARSession/runWithConfiguration:options:`` method.
*/
- (instancetype)init;
/**
- Unavailable. Use init instead.
+ Allocates and initializes a new face-tracking configuration.
- - Returns: This method is unavailable.
+ To use the configuration in an AR session, pass it to the ``ARSession`` ``ARSession/runWithConfiguration:options:`` method.
*/
+ (instancetype)new NS_SWIFT_UNAVAILABLE("Use init() instead");
@end
/**
- A configuration for running image tracking.
+ A configuration that tracks known images using the rear-facing camera.
- Image tracking provides 6 degrees of freedom tracking of known images. Four images may be tracked simultaneously.
+ All AR configurations establish a correspondence between the real world the device inhabits and a virtual 3D coordinate space where you can
+ model content. When your app displays that content together with a live camera image, the user experiences the illusion that your virtual
+ content is part of the real world.
+
+ With ``ARImageTrackingConfiguration``, ARKit establishes a 3D space not by tracking the motion of the device relative to the world, but solely
+ by detecting and tracking the motion of known 2D images in view of the camera. ``ARWorldTrackingConfiguration`` can also detect images, but
+ each configuration has its own strengths:
+
+ - World tracking has a higher performance cost than image-only tracking, so your session can reliably track more images at once with
+ ``ARImageTrackingConfiguration``.
+ - Image-only tracking lets you anchor virtual content to known images only when those images are in view of the camera. World tracking with
+ image detection lets you use known images to add virtual content to the 3D world, and continues to track the position of that content in
+ world space even after the image is no longer in view.
+ - World tracking works best in a stable, nonmoving environment. You can use image-only tracking to add virtual content to known images in more
+ situations—for example, an advertisement inside a moving subway car.
+
+ When an image-tracking configuration detects known images, it tracks their movement with six degrees of freedom (6DOF): specifically, the
+ three rotation axes (roll, pitch, and yaw), and three translation axes (movement in x, y, and z).
+
+ To use ``ARImageTrackingConfiguration``, define ``ARReferenceImage`` objects (either at runtime or by bundling them in your Xcode asset
+ catalog) and assign them to the configuration's ``trackingImages`` property. Then, as with any AR configuration, pass the configuration to
+ your session's ``ARSession/runWithConfiguration:options:`` method.
*/
API_AVAILABLE(ios(12.0))
@interface ARImageTrackingConfiguration : ARConfiguration
/**
- Enable or disable continuous auto focus.
+ A Boolean value that determines whether the device camera uses fixed focus or autofocus behavior.
- Enabled by default.
+ Autofocus is enabled by default.
*/
@property (nonatomic, assign, getter=isAutoFocusEnabled) BOOL autoFocusEnabled;
/**
- Images to track in the scene.
- */
+ A set of images that ARKit searches for and tracks in the user's environment.
+
+ Add members to this set for each image that ARKit searches for in the user's environment. When ARKit observes a matching image, the framework
+ creates an ``ARImageAnchor`` object and adds it to the session. If you set ``maximumNumberOfTrackedImages`` to a value greater than `1`, ARKit
+ tracks multiple images as the session progresses, up to a maximum of four.
+
+ To define the reference images that this property contains, create an asset catalog in Xcode or create ``ARReferenceImage`` objects
+ programmatically. For an example, see <doc:tracking-and-altering-images>.
+*/
@property (nonatomic, copy) NSSet<ARReferenceImage *> *trackingImages;
/**
- Maximum number of images to track simultaneously.
+ The number of image anchors to monitor closely for position and orientation updates.
- Setting the maximum number of tracked images will limit the number of images that can be tracked in a given frame.
- If more than the maximum is visible, only the images already being tracked will continue to track until tracking is lost or another image is removed.
- Default value is one.
+ When you set a nonzero value for this property, the framework keeps that many image anchors up to date as the session progresses. The
+ framework can track a maximum of four images simultaneously.
+
+ The word _track_ in the property name refers to how the framework closely monitors the image's physical position and orientation for any
+ changes. If the image moves, the framework updates the associated ``ARImageAnchor`` transform with the new pose. ARKit checks for changes
+ every frame.
+
+ ARKit tracks the first images it observes in the physical environment from the ``trackingImages`` set. When a session reaches the maximum
+ number of tracked images, the framework attempts to track another member of the set only after one of the existing tracked images leaves the
+ device's view.
+
+ The default value is `1`.
*/
@property (nonatomic, assign) NSInteger maximumNumberOfTrackedImages;
/**
- Initializes a new image tracking configuration.
+ Initializes a new image-tracking configuration.
- - Returns: An initialized image tracking configuration.
+ To use the configuration in an AR session, pass it to the ``ARSession`` ``ARSession/runWithConfiguration:options:`` method.
*/
- (instancetype)init;
/**
- Unavailable. Use init instead.
+ Creates a new image-tracking configuration.
- - Returns: This method is unavailable.
+ To use the configuration in an AR session, pass it to the ``ARSession`` ``ARSession/runWithConfiguration:options:`` method.
*/
+ (instancetype)new NS_SWIFT_UNAVAILABLE("Use init() instead");
@end
/**
- A configuration for scanning objects.
+ A configuration that recognizes objects and collects high-fidelity data about specific objects using the rear-facing camera.
- The object scanning configuration runs world tracking, capturing additional detail in order to create reference objects.
- Running object scanning will consume additional power in order to provide more detailed features.
- The createReferenceObject method can be called on the session to capture a scan of an object in the world.
+ To create an app that recognizes objects in the physical environment, first you scan them during development using
+ `ARObjectScanningConfiguration`. After you've scanned an object, call
+ ``ARSession/createReferenceObjectWithTransform:center:extent:completionHandler:`` to turn it into an ``ARReferenceObject`` that you can use to detect
+ it again at run-time. When users run your app, you ask ARKit to look for your scanned objects by running a world tracking configuration and assigning
+ reference objects to its
+ ``ARWorldTrackingConfiguration/detectionObjects`` property.
+
+ - Important: `ARObjectScanningConfiguration` is for use only in development scenarios. Because the high-fidelity spatial mapping required by
+ object scanning has a high performance and energy cost, many ARKit features are disabled that aren't required for object scanning.
*/
API_DEPRECATED("Please consider migrating to the new reference object format.", ios(12.0, 27.0));
@interface ARObjectScanningConfiguration : ARConfiguration
/**
- Enable or disable continuous auto focus.
+ A Boolean value that determines whether the device camera uses fixed focus or autofocus behavior.
- Enabled by default.
+ Autofocus is enabled by default.
*/
@property (nonatomic, assign, getter=isAutoFocusEnabled) BOOL autoFocusEnabled;
/**
- Type of planes to detect in the scene.
+ A value specifying whether and how the session attempts to automatically detect flat surfaces in the camera-captured image.
- If set, new planes will continue to be detected and updated over time. Detected planes will be added to the session as
- ARPlaneAnchor objects. In the event that two planes are merged, the newer plane will be removed. Defaults to ARPlaneDetectionNone.
+ By default, plane detection is off. If you enable ``ARPlaneDetectionHorizontal`` or ``ARPlaneDetectionVertical`` plane detection, the session
+ adds ``ARPlaneAnchor`` objects and notifies your ``ARSessionDelegate``, ``ARSCNViewDelegate``, or ``ARSKViewDelegate`` object whenever its
+ analysis of captured video images detects an area that appears to be a flat surface.
+
+ In an object-scanning session, you can use detected planes to help determine where the origin (anchor point) for a scanned object should be
+ relative to its extent.
*/
@property (nonatomic, assign) ARPlaneDetection planeDetection;
/**
Initializes a new object scanning configuration.
- - Returns: An initialized object scanning configuration.
+ To use the configuration in an AR session, pass it to the ``ARSession`` ``ARSession/runWithConfiguration:options:`` method.
*/
- (instancetype)init;
/**
- Unavailable. Use init instead.
+ Creates a new object scanning configuration.
- - Returns: This method is unavailable.
+ To use the configuration in an AR session, pass it to the ``ARSession`` ``ARSession/runWithConfiguration:options:`` method.
*/
+ (instancetype)new NS_SWIFT_UNAVAILABLE("Use init() instead");
@end
/**
- A configuration for running body tracking.
+ A configuration that tracks human body poses, planar surfaces, and images using the rear-facing camera.
- Body tracking provides 6 degrees of freedom tracking of a detected body in the scene. By default, `ARFrameSemanticBodyDetection` will be
- enabled.
+ When ARKit identifies a person in the rear camera's feed, it calls ``ARSessionDelegate/session:didAddAnchors:``, passing an ``ARBodyAnchor``
+ you can use to track the body's movement.
+ When you enable plane detection and image detection, you can use a body anchor to display a virtual character and set the character on a
+ surface or image that you choose.
+
+ By default, ``ARConfiguration/frameSemantics`` includes ``ARFrameSemanticBodyDetection``, which gives you access to the joint positions of a
+ person that ARKit detects in the camera feed via the frame's ``ARFrame/detectedBody``.
+
- SeeAlso: ``ARBodyAnchor``
- SeeAlso: ``ARFrame/detectedBody``
*/
@@ -613,154 +1097,287 @@
@interface ARBodyTrackingConfiguration : ARConfiguration
/**
- Enable or disable continuous auto focus.
+ A Boolean value that determines whether the device camera uses fixed focus or autofocus behavior.
- Enabled by default.
+ For apps deployed to iOS 11.3 or later, ARKit enables autofocus by default.
*/
@property (nonatomic, assign, getter=isAutoFocusEnabled) BOOL autoFocusEnabled;
/**
- The initial map of the physical space that world tracking will localize to and track.
+ The state from a previous AR session to attempt to resume with this session configuration.
- If set, the session will attempt to localize to the provided map with
- a limited tracking state until localization is successful or run is called again
- with a different (or no) initial map specified. Once localized, the map will be extended
- and can again be saved using the `getCurrentWorldMap` method on the session.
+ An ``ARWorldMap`` encapsulates the state of a running ``ARSession``. This state includes ARKit's awareness of the physical space the user
+ moves the device in (which ARKit uses to determine the device's position and orientation), as well as any ``ARAnchor`` objects added to the
+ session (which can represent detected real-world features or virtual content placed by your app). After you use
+ ``ARSession/getCurrentWorldMap:`` to save a session's world map, you can assign it to a configuration's ``initialWorldMap`` property and use
+ ``ARSession/runWithConfiguration:options:`` to start another session with the same spatial awareness and anchors.
+
+ By saving world maps and using them to start new sessions, your app can add new AR capabilities:
+
+ - **Multiuser AR experiences.** Create a shared frame of reference by sending archived ``ARWorldMap`` objects to a nearby user's device. With
+ two devices tracking the same world map, you can build a networked experience where both users can see and interact with the same virtual
+ content.
+ - **Persistent AR experiences.** Save a world map when your app becomes inactive, then restore it the next time your app launches in the same
+ physical environment. You can use anchors from the resumed world map to place the same virtual content at the same positions from the saved
+ session.
+
+ When you run a session with an initial world map, the session starts in the limited (relocalizing) tracking state while ARKit attempts to
+ reconcile the recorded world map with the current environment. If successful, the tracking state becomes normal after a short time, indicating
+ that the current world coordinate system and anchors match those from the recorded world map.
+
+ If ARKit cannot reconcile the recorded world map with the current environment (for example, if the device is in an entirely different place
+ from where the world map was recorded), the session remains in the relocalizing state indefinitely.
*/
@property (nonatomic, strong, nullable) ARWorldMap *initialWorldMap;
/**
- The mode of environment texturing to run.
+ The behavior ARKit uses for generating environment textures.
- If set, texture information will be accumulated and updated. Adding an `AREnvironmentProbeAnchor` to the session
- will get the current environment texture available from that probe's perspective which can be used for lighting
- virtual objects in the scene. Defaults to AREnvironmentTexturingNone.
+ Environment textures are cube-map textures that depict the view in all directions from a specific point in a scene. In 3D asset rendering,
+ environment textures are the basis for image-based lighting algorithms where surfaces can realistically reflect light from their surroundings.
+ ARKit can generate environment textures during an AR session using camera imagery, allowing SceneKit or a custom rendering engine to provide
+ realistic image-based lighting for virtual objects in your AR experience.
+
+ To enable texture map generation for your configuration, change this property (from its default value of ``AREnvironmentTexturingNone``):
+
+ - With ``AREnvironmentTexturingManual`` environment texturing, you identify points in the scene for which you want light probe texture maps by
+ creating ``AREnvironmentProbeAnchor`` objects and adding them to the session.
+ - With ``AREnvironmentTexturingAutomatic`` environment texturing, ARKit automatically creates, positions, and adds ``AREnvironmentProbeAnchor``
+ objects to the session.
+
+ In both cases, ARKit automatically generates environment textures as the session collects camera imagery. Use a delegate method such as
+ ``ARSessionDelegate/session:didUpdateAnchors:`` to find out when a texture is available, and access it from the anchor's
+ ``AREnvironmentProbeAnchor/environmentTexture`` property.
+
+ If you display AR content using ``ARSCNView`` and the ``ARSCNView/automaticallyUpdatesLighting`` option, SceneKit automatically retrieves
+ ``AREnvironmentProbeAnchor`` texture maps and uses them to light the scene.
*/
@property (nonatomic, assign) AREnvironmentTexturing environmentTexturing;
/**
- Determines whether environment textures will be provided with high dynamic range. Enabled by default.
+ A flag that instructs ARKit to create environment textures in HDR format.
+
+ The default value is <doc://com.apple.documentation/documentation/swift/true>. If your renderer supports HDR environment textures, this
+ feature effects more realistic reflections.
+
+ RealityKit and SceneKit both support HDR environment textures. For more information, see
+ <doc:adding-realistic-reflections-to-an-ar-experience>.
*/
@property (nonatomic, assign) BOOL wantsHDREnvironmentTextures;
/**
- Type of planes to detect in the scene.
+ A value specifying whether and how the session attempts to automatically detect flat surfaces in the camera-captured image.
- If set, new planes will continue to be detected and updated over time. Detected planes will be added to the session as
- ARPlaneAnchor objects. In the event that two planes are merged, the newer plane will be removed. Defaults to ARPlaneDetectionNone.
+ By default, plane detection is off. If you enable ``ARPlaneDetectionHorizontal`` or ``ARPlaneDetectionVertical`` plane detection, the session
+ adds ``ARPlaneAnchor`` objects and notifies your ``ARSessionDelegate``, ``ARSCNViewDelegate``, or ``ARSKViewDelegate`` object whenever its
+ analysis of captured video images detects an area that appears to be a flat surface.
*/
@property (nonatomic, assign) ARPlaneDetection planeDetection;
/**
- Images to detect in the scene.
+ A set of images that ARKit searches for in the user's environment.
- If set the session will attempt to detect the specified images. When an image is detected an `ARImageAnchor` will be added to the session.
+ Add members to this set for each image that ARKit searches for in the user's environment. When ARKit _detects_ a matching image, the
+ framework creates an ``ARImageAnchor`` object and adds it to the session.
+
+ To define the reference images that this property contains, create an asset catalog in Xcode or create ``ARReferenceImage`` objects
+ programmatically. For more information, see <doc:detecting-images-in-an-ar-experience>.
+
+ If you set a nonzero value for ``maximumNumberOfTrackedImages``, ARKit enables image _tracking_, which continuously updates the transform for
+ up to four of the reference image anchors as the session progresses. For an example, see <doc:tracking-and-altering-images>.
+
+ ### Limit Reference Images for Performance
+
+ Image detection accuracy and performance may decline as the number of images in this set increases. For best results, limit your detection
+ image count to no more than around 100.
+
+ To detect more than 100 images, your app can allocate a certain amount of time for the first 100 images before moving on to the next 100, and
+ so on. When you update the contents of this property, call ``ARSession/runWithConfiguration:options:`` again with your app's configuration to
+ effect the change.
*/
@property (nonatomic, copy) NSSet<ARReferenceImage *> *detectionImages;
/**
- Enables the estimation of a scale factor which may be used to correct the physical size of an image.
+ A flag that instructs ARKit to estimate and set the scale of a tracked image on your behalf.
- If set to true ARKit will attempt to use the computed camera positions in order to compute the scale by which the given physical size
- differs from the estimated one. The information about the estimated scale can be found as the property estimatedScaleFactor on the ARImageAnchor.
+ If set to <doc://com.apple.documentation/documentation/swift/true>, ARKit uses its knowledge of the world to set an image anchor's
+ ``ARImageAnchor/estimatedScaleFactor`` property, which corrects the image anchor's position in the physical environment.
- - Note: When set to true the transform of a returned `ARImageAnchor` will use the estimated scale factor to correct the translation. Default value is
- `NO`.
+ Enable this property when you want to detect different sized versions of a reference image. ARKit must know the physical size of an image in
+ the real world to accurately estimate its real-world position. You enable this property to tell ARKit to estimate a recognized image's
+ physical size before it calculates the real-world position.
+
+ - Note: When set to true the transform of a returned `ARImageAnchor` will use the estimated scale factor to correct the translation. Default
+ value is `NO`.
*/
@property (nonatomic, assign) BOOL automaticImageScaleEstimationEnabled;
/**
- Enables the estimation of a scale factor which may be used to correct the physical size of a skeleton in 3D.
+ A flag that determines whether ARKit estimates the height of a body that it's tracking.
- If set to true ARKit will attempt to use the computed camera positions in order to compute the scale by which the given physical size
- differs from the default one. The information about the estimated scale can be found as the property estimatedScaleFactor on the ARBodyAnchor.
+ When you assign this property a value of <doc://com.apple.documentation/documentation/swift/true>, you instruct ARKit to compute a value for
+ ``ARBodyAnchor/estimatedScaleFactor`` for a person's body anchor. ARKit must know the physical height of a person in the real world to
+ accurately estimate the person's real-world position. You enable this property to tell ARKit to estimate a recognized person's physical height
+ before it assigns the body anchor's position.
- - Note: When set to true the transform of a returned `ARBodyAnchor` will use the estimated scale factor to correct the translation. Default value is
- `NO`.
+ - Note: When set to true the transform of a returned `ARBodyAnchor` will use the estimated scale factor to correct the translation. Default
+ value is `NO`.
*/
@property (nonatomic, assign) BOOL automaticSkeletonScaleEstimationEnabled;
/**
- Maximum number of images to track simultaneously.
+ The number of image anchors to monitor closely for position and orientation updates.
- Setting the maximum number of tracked images will limit the number of images that can be tracked in a given frame.
- If more than the maximum is visible, only the images already being tracked will continue to track until tracking is lost or another image is removed.
- Images will continue to be detected regardless of images tracked. Default value is zero.
+ When you set a nonzero value for this property, the framework keeps that many image anchors up to date as the session progresses. The
+ framework can track a maximum of four images simultaneously.
+
+ The word _track_ in the property name refers to how the framework closely monitors the image's physical position and orientation for any
+ changes. If the image moves, the framework updates the associated ``ARImageAnchor`` transform with the new pose. ARKit checks for changes
+ every frame.
+
+ ARKit tracks the first images it observes in the physical environment from the ``detectionImages`` set. When a session reaches the maximum
+ number of tracked images, the framework attempts to track another member of the set only after one of the existing tracked images leaves the
+ device's view.
+
+ The default value is `0`, which disables image tracking. If you add reference images to ``detectionImages`` with this property set to `0`,
+ ARKit creates image anchors for observed reference images but their positions only update infrequently, such as once every couple of seconds.
*/
@property (nonatomic, assign) NSInteger maximumNumberOfTrackedImages;
/**
- Enable or disable app clip code tracking. Disabled by default. When enabled, detected app clip codes will be surfaced as an ARAppClipCodeAnchor.
+ A Boolean value that indicates if the framework searches the physical environment for App Clip Codes.
+
+ When this property's value is <doc://com.apple.documentation/documentation/swift/true>, the session delegate receives an
+ ``ARAppClipCodeAnchor`` via ``ARSessionDelegate/session:didAddAnchors:`` for every App Clip Code that ARKit detects in the physical
+ environment. The default value is `false`.
+
+ Before calling this function, check that the configuration supports App Clip Code tracking by calling ``supportsAppClipCodeTracking``.
+
+ To avoid scanning a physical code that's not connected to an App Clip, the system ensures that an app provides an App Clip before allowing the
+ app to interact with App Clip Codes. Without providing an App Clip, the app can recognize codes in the environment by determining their
+ physical location (``ARAnchor/transform``), but code URLs (``ARAppClipCodeAnchor/url``) remain `nil`.
*/
@property (nonatomic, assign) BOOL appClipCodeTrackingEnabled API_AVAILABLE(ios(14.3));
/**
- Indicates whether app clip code tracking can be enabled on this device.
+ A flag that indicates if the device tracks App Clip Codes.
+
+ Devices require the Apple Neural Engine (ANE) to track App Clip Codes. The system sets this property to
+ <doc://com.apple.documentation/documentation/swift/true> if the device contains the ANE chip. The default value of this property is
+ <doc://com.apple.documentation/documentation/swift/false>.
+
+ Call this function before setting ``appClipCodeTrackingEnabled``.
*/
@property (class, nonatomic, readonly) BOOL supportsAppClipCodeTracking API_AVAILABLE(ios(14.3));
/**
- Initializes a new body tracking configuration.
-
- - Returns: An initialized body tracking configuration.
+ Creates a new body tracking configuration.
*/
- (instancetype)init;
/**
- Unavailable. Use init instead.
-
- - Returns: This method is unavailable.
+ Creates a new body tracking configuration.
*/
+ (instancetype)new NS_SWIFT_UNAVAILABLE("Use init() instead");
@end
/**
- A configuration for running positional tracking.
+ A configuration that tracks only the device's position in 3D space.
- Positional tracking provides `6` degrees of freedom tracking of the device by running the camera at lowest possible resolution and frame
- rate.
+ Enables 6 degrees of freedom tracking of the iOS device by running the camera at lowest possible resolution and frame rate. Use this
+ configuration when you don't need to parse the camera feed, such as for example, virtual reality scenarios.
*/
API_AVAILABLE(ios(13.0))
@interface ARPositionalTrackingConfiguration : ARConfiguration
/**
- Type of planes to detect in the scene.
+ A value that specifies if and how the session automatically attempts to detect flat surfaces in the camera-captured image.
- If set, new planes will continue to be detected and updated over time. Detected planes will be added to the session as
- ARPlaneAnchor objects. In the event that two planes are merged, the newer plane will be removed. Defaults to ARPlaneDetectionNone.
+ By default, this configuration disables plane detection. If you enable ``ARPlaneDetectionHorizontal`` or ``ARPlaneDetectionVertical`` plane
+ detection, the session adds ``ARPlaneAnchor`` objects and notifies your ``ARSessionDelegate``, ``ARSCNViewDelegate``, or ``ARSKViewDelegate``
+ object when its analysis of captured video images detects an area that appears to be a flat surface.
*/
@property (nonatomic, assign) ARPlaneDetection planeDetection;
/**
- The initial map of the physical space that world tracking will localize to and track.
+ The state from a previous AR session to attempt to resume with this session configuration.
- If set, the session will attempt to localize to the provided map with
- a limited tracking state until localization is successful or run is called again
- with a different (or no) initial map specified. Once localized, the map will be extended
- and can again be saved using the `getCurrentWorldMap` method on the session.
+ An ``ARWorldMap`` encapsulates the state of a running ``ARSession``. This state includes ARKit's awareness of the physical space the user
+ moves the device in (which ARKit uses to determine the device's position and orientation), as well as any ``ARAnchor`` objects added to the
+ session (which can represent detected real-world features or virtual content placed by your app). After you use
+ ``ARSession/getCurrentWorldMap:`` to save a session's world map, you can assign it to a configuration's ``initialWorldMap`` property and use
+ ``ARSession/runWithConfiguration:options:`` to start another session with the same spatial awareness and anchors.
+
+ By saving world maps and using them to start new sessions, your app can add new AR capabilities:
+
+ - **Multiuser AR experiences.** Create a shared frame of reference by sending archived ``ARWorldMap`` objects to a nearby user's device. With
+ two devices tracking the same world map, you can build a networked experience where both users can see and interact with the same virtual
+ content.
+ - **Persistent AR experiences.** Save a world map when your app becomes inactive, then restore it the next time your app launches in the same
+ physical environment. You can use anchors from the resumed world map to place the same virtual content at the same positions from the saved
+ session.
+
+ When you run a session with an initial world map, the session starts in the limited (relocalizing) tracking state while ARKit attempts to
+ reconcile the recorded world map with the current environment. If successful, the tracking state becomes normal after a short time, indicating
+ that the current world coordinate system and anchors match those from the recorded world map.
+
+ If ARKit cannot reconcile the recorded world map with the current environment (for example, if the device is in an entirely different place
+ from where the world map was recorded), the session remains in the relocalizing state indefinitely.
*/
@property (nonatomic, strong, nullable) ARWorldMap *initialWorldMap;
/**
- Initializes a new positional tracking configuration.
-
- - Returns: An initialized positional tracking configuration.
+ Creates a new positional tracking configuration.
*/
- (instancetype)init;
/**
- Unavailable. Use init instead.
-
- - Returns: This method is unavailable.
+ Creates a new positional tracking configuration.
*/
+ (instancetype)new NS_SWIFT_UNAVAILABLE("Use init() instead");
@end
/**
- A configuration for running geographical world tracking.
+ A configuration that tracks locations with GPS, map data, and a device's compass.
- It allows placing geo-referenced anchors (ARGeoAnchor) in the scene by running world tracking with location and compass.
+ This configuration creates location anchors (``ARGeoAnchor``) that specify a particular latitude, longitude, and optionally, altitude to
+ enable an app to track geographic areas of interest in an AR experience.
+
+ - Important: The ``ARConfiguration/isSupported`` property returns <doc://com.apple.documentation/documentation/swift/true> for this class on
+ iOS 14 & iPadOS 14 devices that have an A12 chip or later and cellular (GPS) capability. Geotracking is available in specific geographic
+ locations. To determine availability at the user's location at runtime, call ``checkAvailabilityWithCompletionHandler:``.
+
+ Geotracking occurs exclusively outdoors. If a geotracking app navigates users between waypoints, your app needs to handle any events along a
+ route. The user must have an internet connection, and you can provide them information about data usage, as described in ``ARGeoAnchor``.
+
+ ### Encourage user safety
+
+ To keep your users' focus on the road while traveling, discourage them from looking at the device when in motion, such as while riding a bike.
+ Keep users informed when navigating through unfamiliar territory. For instance, you can recommend they steer clear of private property, or
+ remind them to check their device's battery level before beginning a long route.
+
+ ### Refine the user's position with imagery
+
+ To place location anchors with precision, geotracking requires a better understanding of the user's geographic location than is possible with
+ GPS alone. Based on the user's GPS coordinates, ARKit downloads imagery that depicts the physical environment in that area. Apple collects
+ this _localization imagery_ in advance by capturing photos of the view from the street and recording the geographic position at each photo. By
+ comparing the device's current camera image with this imagery, the session matches the user's precise geographic location with the scene's
+ local coordinates. For information about the user's position in local space, see ``ARCamera/transform``.
+
+ Localization imagery captures views from public streets and routes accessible by car, but doesn't include images of gated or pedestrian-only
+ areas.
+
+ Geotracking sessions use localization imagery in the ``ARGeoTrackingStatus/State/localizing`` state.
+
+ ### Supported areas and cities
+
+ Localization imagery is available for specific areas in over 20 countries, including many metropolitan areas in Australia, Europe, Japan, and
+ North America. To check availability in a particular location, see the ``checkAvailabilityWithCompletionHandler:`` function.
+
+ - Tip: You can share an experience of geotracking with developers who live outside an area that supports it. Record a session in your app in
+ an area that supports localization imagery for developers to create and test their geotracking app. For more information, see
+ <doc:recording-and-replaying-ar-session-data>.
*/
API_AVAILABLE(ios(14.0))
@interface ARGeoTrackingConfiguration : ARConfiguration
@@ -769,56 +1386,119 @@
@property (nonatomic, assign) ARWorldAlignment worldAlignment NS_UNAVAILABLE;
/**
- The mode of environment texturing to run.
+ An option that determines how the framework generates environment textures.
- If set, texture information will be accumulated and updated. Adding an `AREnvironmentProbeAnchor` to the session
- will get the current environment texture available from that probe's perspective which can be used for lighting
- virtual objects in the scene. Defaults to AREnvironmentTexturingNone.
+ Environment textures are cube-map textures that depict the view in all directions from a specific point in a scene. In 3D asset rendering,
+ environment textures are the basis for image-based lighting algorithms where surfaces can realistically reflect light from their surroundings.
+ ARKit generates environment textures during an AR session using camera imagery, allowing SceneKit or a custom-rendering engine to provide
+ realistic image-based lighting for virtual objects in your AR experience.
+
+ To enable texture map generation for your configuration, change this property (from its default value of ``AREnvironmentTexturingNone``):
+
+ - With ``AREnvironmentTexturingManual`` environment texturing, you identify points in the scene for which you want light probe texture maps by
+ creating ``AREnvironmentProbeAnchor`` objects and adding them to the session.
+ - With ``AREnvironmentTexturingAutomatic`` environment texturing, ARKit automatically creates, positions, and adds ``AREnvironmentProbeAnchor``
+ objects to the session.
+
+ In both cases, ARKit automatically generates environment textures as the session collects camera imagery. Use a delegate method such as
+ ``ARSessionDelegate/session:didUpdateAnchors:`` to find out when a texture is available, and access it from the anchor's
+ ``AREnvironmentProbeAnchor/environmentTexture`` property.
+
+ If you display AR content using ``ARSCNView`` and the ``ARSCNView/automaticallyUpdatesLighting`` option, SceneKit automatically retrieves
+ ``AREnvironmentProbeAnchor`` texture maps and uses them to light the scene.
*/
@property (nonatomic, assign) AREnvironmentTexturing environmentTexturing;
/**
- Determines whether environment textures will be provided with high dynamic range. Enabled by default.
+ A flag that instructs the framework to create environment textures in HDR format.
+
+ If you set ``environmentTexturing`` to `.automatic` in iOS 12 or later, ARKit gives you environment textures you cast on your app's virtual
+ content to create realistic reflections. By default, the framework sets ``wantsHDREnvironmentTextures`` to
+ <doc://com.apple.documentation/documentation/swift/true>. When your renderer supports HDR environment textures in iOS 13, it enables your
+ lighting engine to output more colors, with a more realistic result.
+
+ Both <doc://com.apple.documentation/documentation/realitykit/arview> and ``ARSCNView`` support HDR environment textures. For more information,
+ see <doc:adding-realistic-reflections-to-an-ar-experience>.
+
+ For a Metal app that doesn't yet support HDR environment textures, you can use the following code to receive LDR environment textures until
+ you're ready to update your renderer for HDR.
+
+ ```swift
+ if #available(iOS 13, *) {
+ configuration.wantsHDREnvironmentTextures = false
+ }
+ ```
*/
@property (nonatomic, assign) BOOL wantsHDREnvironmentTextures;
/**
- Type of planes to detect in the scene.
+ A value that specifies whether and how the session automatically attempts to detect flat surfaces in the camera-captured image.
- If set, new planes will continue to be detected and updated over time. Detected planes will be added to the session as
- ARPlaneAnchor objects. In the event that two planes are merged, the newer plane will be removed. Defaults to ARPlaneDetectionNone.
+ By default, this configuration disables plane detection. If you enable ``ARPlaneDetectionHorizontal`` or ``ARPlaneDetectionVertical`` plane
+ detection, the session adds ``ARPlaneAnchor`` objects and notifies your ``ARSessionDelegate``, ``ARSCNViewDelegate``, or ``ARSKViewDelegate``
+ object when its analysis of captured video images detects an area that appears to be a flat surface.
*/
@property (nonatomic, assign) ARPlaneDetection planeDetection;
/**
- Images to detect in the scene.
+ A set of images that ARKit searches for in the user's environment.
- If set the session will attempt to detect the specified images. When an image is detected an `ARImageAnchor` will be added to the session.
+ Add members to this set for each image that ARKit searches for in the user's environment. When ARKit _detects_ a matching image, the
+ framework creates an ``ARImageAnchor`` object and adds it to the session.
+
+ To define the reference images that this property contains, create an asset catalog in Xcode or create ``ARReferenceImage`` objects
+ programmatically. For more information, see <doc:detecting-images-in-an-ar-experience>.
+
+ If you set a nonzero value for ``maximumNumberOfTrackedImages``, ARKit enables image _tracking_, which continuously updates the transform for
+ up to four of the reference image anchors as the session progresses. For an example, see <doc:tracking-and-altering-images>.
+
+ ### Limit Reference Images for Performance
+
+ Image detection accuracy and performance may decline as the number of images in this set increases. For best results, limit your detection
+ image count to no more than around 100.
+
+ To detect more than 100 images, your app can allocate a certain amount of time for the first 100 images before moving on to the next 100, and
+ so on. When you update the contents of this property, call ``ARSession/runWithConfiguration:options:`` again with your app's configuration to
+ effect the change.
*/
@property (nonatomic, copy, null_resettable) NSSet<ARReferenceImage *> *detectionImages;
/**
- Enables the estimation of a scale factor which may be used to correct the physical size of an image.
+ A flag that instructs the framework to estimate and set the scale of a detected or tracked image on your behalf.
- If set to true ARKit will attempt to use the computed camera positions in order to compute the scale by which the given physical size
- differs from the estimated one. The information about the estimated scale can be found as the property estimatedScaleFactor on the ARImageAnchor.
+ If set to <doc://com.apple.documentation/documentation/swift/true>, ARKit uses its knowledge of the world to set an image anchor's
+ ``ARImageAnchor/estimatedScaleFactor`` property, which corrects the image anchor's position in the physical environment.
- - Note: When set to true the transform of a returned `ARImageAnchor` will use the estimated scale factor to correct the translation. Default value is
- `NO`.
+ Enable this property when you want to detect different-sized versions of a reference image. ARKit must know the physical size of an image in
+ the real world to accurately estimate its real-world position. Enable this property to tell ARKit to estimate a recognized image's physical
+ size before it calculates the real-world position.
+
+ - Note: When set to true the transform of a returned `ARImageAnchor` will use the estimated scale factor to correct the translation. Default
+ value is `NO`.
*/
@property (nonatomic, assign) BOOL automaticImageScaleEstimationEnabled;
/**
- Maximum number of images to track simultaneously.
+ The number of image anchors to monitor closely for position and orientation updates.
- Setting the maximum number of tracked images will limit the number of images that can be tracked in a given frame.
- If more than the maximum is visible, only the images already being tracked will continue to track until tracking is lost or another image is removed.
- Images will continue to be detected regardless of images tracked. Default value is zero.
+ When you set a nonzero value for this property, the framework keeps that many image anchors up to date as the session progresses. The
+ framework can track a maximum of four images simultaneously.
+
+ The word _track_ in the property name refers to how the framework closely monitors the image's physical position and orientation for any
+ changes. If the image moves, the framework updates the associated ``ARImageAnchor`` transform with the new pose. ARKit checks for changes
+ every frame.
+
+ ARKit tracks the first images it observes in the physical environment from the ``detectionImages`` set. When a session reaches the maximum
+ number of tracked images, the framework attempts to track another member of the set only after one of the existing tracked images leaves the
+ device's view.
+
+ The default value is `0`, which disables image tracking. If you add reference images to ``detectionImages`` with this property set to `0`,
+ ARKit creates image anchors for observed reference images but their positions only update infrequently, such as once every couple of seconds.
*/
@property (nonatomic, assign) NSInteger maximumNumberOfTrackedImages;
/**
- Objects to detect in the scene.
+ A set of 3D objects that the framework attempts to detect in the user's environment.
The system keeps the object's pose stable in world space, consuming less power. Virtual content stays aligned with the
object as long as it doesn't move; if the object moves, the system may delay the pose update. When an object is
@@ -848,49 +1528,82 @@
@property (nonatomic, copy) NSSet<ARReferenceObject *> *trackingObjects API_AVAILABLE(ios(27.0));
/**
- Enable or disable app clip code tracking. Disabled by default. When enabled, detected app clip codes will be surfaced as an ARAppClipCodeAnchor.
+ A Boolean value that indicates if the framework searches the physical environment for App Clip Codes.
+
+ When this property's value is <doc://com.apple.documentation/documentation/swift/true>, the session delegate receives an
+ ``ARAppClipCodeAnchor`` via ``ARSessionDelegate/session:didAddAnchors:`` for every App Clip Code that ARKit detects in the physical
+ environment. The default value is `false`.
+
+ Before calling this function, check that the configuration supports App Clip Code tracking by calling ``supportsAppClipCodeTracking``.
+
+ To avoid scanning a physical code that's not connected to an App Clip, the system ensures that an app provides an App Clip before allowing the
+ app to interact with App Clip Codes. Without providing an App Clip, the app can recognize codes in the environment by determining their
+ physical location (``ARAnchor/transform``), but code URLs (``ARAppClipCodeAnchor/url``) remain `nil`.
*/
@property (nonatomic, assign) BOOL appClipCodeTrackingEnabled API_AVAILABLE(ios(14.3));
/**
- Indicates whether app clip code tracking can be enabled on this device.
+ A flag that indicates if the device tracks App Clip Codes.
+
+ Devices require the Apple Neural Engine (ANE) to track App Clip Codes. The system sets this property to
+ <doc://com.apple.documentation/documentation/swift/true> if the device contains the ANE chip. The default value of this property is
+ <doc://com.apple.documentation/documentation/swift/false>.
+
+ Call this function before setting ``appClipCodeTrackingEnabled``.
*/
@property (class, nonatomic, readonly) BOOL supportsAppClipCodeTracking API_AVAILABLE(ios(14.3));
/**
- Determines the availability of geo tracking at the current location.
+ Determines if geotracking supports the user's current location.
- This method will attempt to acquire a location fix on a background thread, then check availability.
+ This function returns <doc://com.apple.documentation/documentation/swift/false> under the following circumstances:
- - Parameter completionHandler: Completion handler that is called when availability has been determined. This handler is executed on an arbitrary
- serial queue. It takes the following parameters: isAvailable - True if geo tracking is available at the current location, otherwise false. error - An
- error that indicates why geo tracking is not available at the current location.
+ - ARKit lacks localization imagery for the user's geographic position.
+ - A network connection is unavailable to download localization imagery.
+ - The device lacks cellular (GPS) capability.
+
+ To determine availability at a different location than the device's current location, call
+ ``checkAvailabilityAtCoordinate:completionHandler:`` instead.
+
+ For a list of supported areas and cities, see ``ARGeoTrackingConfiguration``.
+
+ - Parameter completionHandler: Code you supply that runs after the function returns. The closure takes a Boolean argument (`isAvailable`) that
+ indicates whether geotracking is available, and an `NSError` argument that describes the failure if the check could not be completed. This handler is
+ executed on an arbitrary serial queue.
*/
+ (void)checkAvailabilityWithCompletionHandler:(void (^)(BOOL isAvailable, NSError *_Nullable error))completionHandler NS_SWIFT_DISABLE_ASYNC;
/**
- Determines the availability of geo tracking at the given location.
+ Determines if geotracking supports a particular location.
+ This function returns <doc://com.apple.documentation/documentation/swift/false> under the following circumstances:
+
+ - ARKit lacks localization imagery for the argument GPS coordinate.
+ - A network connection is unavailable to download localization imagery.
+ - The device lacks cellular (GPS) capability.
+
+ To determine availability at the user's GPS coordinate, use ``checkAvailabilityWithCompletionHandler:`` instead.
+
+ For a list of supported areas and cities, see ``ARGeoTrackingConfiguration``.
+
- Parameters:
- - coordinate: Location at which to check.
- - completionHandler: Completion handler that is called when availability has been determined. This handler is executed on an arbitrary serial
- queue. It takes the following parameters: isAvailable - True if geo tracking is available at the given location, otherwise false. error - An error
- that indicates why geo tracking is not available at the given location.
+ - coordinate: The GPS location that the framework checks for availability.
+ - completionHandler: Code you supply that runs after the function returns. The closure takes a Boolean argument (`isAvailable`) that indicates
+ whether geotracking is available, and an `NSError` argument that describes the failure if the check could not be completed. This handler is
+ executed on an arbitrary serial queue.
*/
+ (void)checkAvailabilityAtCoordinate:(CLLocationCoordinate2D)coordinate
completionHandler:(void (^)(BOOL isAvailable, NSError *_Nullable error))completionHandler NS_SWIFT_DISABLE_ASYNC;
/**
- Initializes a new geo tracking configuration.
+ Initializes a new geotracking configuration.
- - Returns: An initialized geo tracking configuration.
+ To use the configuration in an AR experience, pass it as an argument to your app's ``ARSession/runWithConfiguration:options:`` function.
*/
- (instancetype)init;
/**
- Unavailable. Use init instead.
-
- - Returns: This method is unavailable.
+ Instantiates a new geotracking configuration.
*/
+ (instancetype)new NS_SWIFT_UNAVAILABLE("Use init() instead");
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARDepthData.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARDepthData.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARDepthData.h 2026-08-15 22:27:52
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARDepthData.h 2026-10-04 01:38:17
@@ -13,28 +13,66 @@
NS_ASSUME_NONNULL_BEGIN
/**
- Constants indicating the confidence level of per-pixel depth data.
+ Degrees to which the framework is confident about depth-data accuracy.
*/
typedef NS_ENUM(NSInteger, ARConfidenceLevel) {
+ /**
+ Depth-value accuracy in which the framework is less confident.
+ */
ARConfidenceLevelLow,
+ /**
+ Depth-value accuracy in which the framework is moderately confident.
+ */
ARConfidenceLevelMedium,
+ /**
+ Depth-value accuracy in which the framework is fairly confident.
+ */
ARConfidenceLevelHigh,
} API_AVAILABLE(ios(14.0));
/**
- A container for depth data and its associated confidence.
+ An object that describes the distance to regions of the real world from the plane of the camera.
+
+ This object contains the following depth information that the LiDAR scanner captures at runtime:
+
+ - Every pixel in the ``depthMap`` maps to a region of the visible scene (``ARFrame/capturedImage``), where the pixel value defines that region's
+ distance from the plane of the camera in meters.
+ - The ``confidenceMap`` property measures the accuracy of the corresponding depth data in ``depthMap``, and is useful in filtering out lower-accuracy
+ depth values if an app's algorithm required it.
+
+ ``ARWorldTrackingConfiguration`` exposes this depth information in the ``ARFrame/sceneDepth`` property which it updates every frame. To enable scene
+ depth, add the ``ARConfiguration/FrameSemantics/sceneDepth`` frame semantic to a world-tracking configuration's ``ARConfiguration/frameSemantics``
+ and frames vended by the session contain ``ARDepthData`` captured by the LiDAR scanner.
*/
API_AVAILABLE(ios(14.0))
NS_SWIFT_SENDABLE
@interface ARDepthData : NSObject
/**
- A pixel buffer that contains per-pixel depth data (in meters).
+ The estimated distance from the device to its environment, in meters.
+
+ For custom renderers, if you create a texture to send depth data to the GPU, choose a
+ <doc://com.apple.documentation/documentation/metal/mtlpixelformat> according to the ``ARDepthData/depthMap`` pixel format. Call
+ <doc://com.apple.documentation/documentation/corevideo/cvpixelbuffergetpixelformattype(_:)> on the ``ARDepthData/depthMap`` to get its format. For
+ example, if at runtime the ``ARDepthData/depthMap`` format is <doc://com.apple.documentation/documentation/corevideo/kcvpixelformattype_depthfloat32>
+ (<doc://com.apple.documentation/documentation/kernel/ostype> \``fdep`\`), use
+ <doc://com.apple.documentation/documentation/metal/mtlpixelformat/r32float>.
*/
@property (nonatomic, assign, readonly) CVPixelBufferRef depthMap;
/**
- A pixel buffer containing the confidence level for each depth value in the `depthMap`.
+ The framework's confidence in the accuracy of the depth-map data.
+
+ The natural light of the physical environment affects the ``ARDepthData/depthMap`` property such that ARKit is less confident about the accuracy of
+ the LiDAR Scanner's depth measurements for surfaces that are highly reflective, or that have high light absorption. This property measures the
+ accuracy of the scene depth-data by containing an ``ARConfidenceLevel`` raw-value for every component in ``ARDepthData/depthMap``.
+
+ Custom renderers that process confidence data on the GPU should choose a <doc://com.apple.documentation/documentation/metal/mtlpixelformat> according
+ to the ``ARDepthData/confidenceMap`` pixel format the app reads at runtime. Call
+ <doc://com.apple.documentation/documentation/corevideo/cvpixelbuffergetpixelformattype(_:)> on the ``ARDepthData/confidenceMap`` to get its format.
+ If, for example, the ``ARDepthData/confidenceMap`` format is <doc://com.apple.documentation/documentation/corevideo/kcvpixelformattype_onecomponent8>
+ (<doc://com.apple.documentation/documentation/kernel/ostype> \``L008`\`), create a Metal texture with format
+ <doc://com.apple.documentation/documentation/metal/mtlpixelformat/r8uint> to send confidence data to the GPU.
@see ARConfidenceLevel
*/
@property (nonatomic, assign, nullable, readonly) CVPixelBufferRef confidenceMap;
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/AREnvironmentProbeAnchor.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/AREnvironmentProbeAnchor.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/AREnvironmentProbeAnchor.h 2026-08-15 23:02:19
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/AREnvironmentProbeAnchor.h 2026-10-04 02:32:29
@@ -15,50 +15,86 @@
API_UNAVAILABLE_BEGIN(visionos)
/**
- An object representing an environment probe in the world.
+ An object that provides environmental lighting information for a specific area of space in a world-tracking AR session.
- Environment probes are used to light virtual geometry by producing environment
- textures from the probe's location in the world.
+ Environment textures depict the view in all directions from a specific point in a scene. In 3D asset rendering, environment textures are the basis
+ for image-based lighting algorithms where surfaces can realistically reflect light from their surroundings. ARKit can generate environment textures
+ during an AR session using camera imagery, allowing SceneKit or a custom-rendering engine to provide realistic image-based lighting for virtual
+ objects in your AR experience.
+
+ To enable texture map generation for an AR session, set the ``ARWorldTrackingConfiguration/environmentTexturing`` property:
+
+ - With ``ARWorldTrackingConfiguration/EnvironmentTexturing/manual`` environment texturing, you identify points in the scene for which you want light
+ probe texture maps by creating ``AREnvironmentProbeAnchor`` objects and adding them to the session.
+ - With ``ARWorldTrackingConfiguration/EnvironmentTexturing/automatic`` environment texturing, ARKit automatically creates, positions, and adds
+ ``AREnvironmentProbeAnchor`` objects to the session.
+
+ In both cases, ARKit automatically generates environment textures as the session collects camera imagery. Use a delegate method such as
+ ``ARSessionDelegate/session(_:didUpdate:)-3qtt8`` to find out when a texture is available, and access it from the anchor's ``environmentTexture``
+ property.
+
+ If you display AR content using ``ARSCNView`` and the ``ARSCNView/automaticallyUpdatesLighting`` option, SceneKit automatically retrieves
+ ``AREnvironmentProbeAnchor`` texture maps and uses them to light the scene.
*/
API_AVAILABLE(ios(12.0))
NS_SWIFT_SENDABLE
@interface AREnvironmentProbeAnchor : ARAnchor
/**
- The environment texture of the probe.
+ A cube-map texture that represents the view in all directions from the probe anchor's position.
- The texture is provided as a cube using MTLTextureTypeCube.
+ This texture is in the format <doc://com.apple.documentation/documentation/metal/mtlpixelformat/bgra8unorm_srgb>.
*/
@property (nonatomic, strong, nullable, readonly) id<MTLTexture> environmentTexture;
/**
- The extent of the probe in the anchor's coordinate space.
+ The area around the anchor's position that contains the texture.
- This is the size of the box that is assumed when projecting the environment texture for parallax correction.
- The extent defaults to infinity for probes that do not need parallax correction.
+ Rendering reflective objects may involve projecting the ``AREnvironmentProbeAnchor/environmentTexture`` onto a proxy geometry centered on the
+ anchor's position, then sampling from the projected texture.
+
+ An environment probe anchor may have an infinite extent, which indicates that its texture is a global lighting environment, or a finite extent, which
+ indicates that its texture represents the local lighting conditions in a specific area of the scene.
*/
@property (nonatomic, readonly) simd_float3 extent;
/**
- Initializes a new environment probe anchor with the provided transform and extent.
+ Creates a new environment probe anchor.
- Parameters:
- - transform: The transformation matrix that defines the anchor's rotation, translation and scale in world coordinates.
- - extent: The extent of the probe in the anchor's coordinate space.
+ - transform: A matrix that encodes the position, orientation, and scale of the anchor, relative to the world coordinate space of the AR session in
+ which you place the anchor.
- - Returns: An initialized environment probe anchor.
+ World coordinate space in ARKit always follows a right-handed convention, but is oriented based on the session configuration. For details, see
+ <doc:understanding-world-tracking>.
+ - extent: The area around the anchor's position that contains the texture.
+
+ Use the ``ARSession/add(anchor:)`` method to begin tracking your custom anchor in an AR session. After you add an environment probe anchor to the
+ scene, ARKit begins generating environment textures for it. To be notified when the anchor has a new ``AREnvironmentProbeAnchor/environmentTexture``,
+ implement the ``ARSessionDelegate/session(_:didUpdate:)-3qtt8``, ``ARSCNViewDelegate/renderer(_:didUpdate:for:)``, or
+ ``ARSKViewDelegate/view(_:didUpdate:for:)`` delegate method.
*/
- (instancetype)initWithTransform:(simd_float4x4)transform extent:(simd_float3)extent;
/**
- Initializes a new environment probe anchor with the provided name, transform, and extent.
+ Creates a new anchor object with a descriptive name.
- Parameters:
- - name: A name to associate with the anchor.
- - transform: The transformation matrix that defines the anchor's rotation, translation and scale in world coordinates.
- - extent: The extent of the probe in the anchor's coordinate space.
+ - name: A descriptive name for the anchor. ARKit doesn't display the name to users, but your app can use it to identify anchors for debugging.
+ - transform: A matrix that encodes the position, orientation, and scale of the anchor, relative to the world coordinate space of the AR session in
+ which you place the anchor.
- - Returns: An initialized environment probe anchor.
+ World coordinate space in ARKit always follows a right-handed convention, but is oriented based on the session configuration. For details, see
+ <doc:understanding-world-tracking>.
+ - extent: The area around the anchor's position that contains the texture.
+
+ An environment probe anchor may have an infinite extent, which indicates that its texture is a global lighting environment, or a finite extent,
+ which indicates that its texture represents the local lighting conditions in a specific area of the scene.
+
+ Use the ``ARSession/add(anchor:)`` method to begin tracking your custom anchor in an AR session. After you add an environment probe anchor to the
+ scene, ARKit begins generating environment textures for it. To be notified when the anchor has a new ``AREnvironmentProbeAnchor/environmentTexture``,
+ implement the ``ARSessionDelegate/session(_:didUpdate:)-3qtt8``, ``ARSCNViewDelegate/renderer(_:didUpdate:for:)``, or
+ ``ARSKViewDelegate/view(_:didUpdate:for:)`` delegate method.
*/
- (instancetype)initWithName:(NSString *)name transform:(simd_float4x4)transform extent:(simd_float3)extent API_UNAVAILABLE(visionos);
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARError.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARError.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARError.h 2026-08-15 23:02:19
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARError.h 2026-10-04 02:32:28
@@ -13,72 +13,171 @@
API_UNAVAILABLE_BEGIN(visionos)
+/**
+ The domain for error objects produced by an AR session.
+ */
API_AVAILABLE(ios(11.0))
FOUNDATION_EXTERN NSString *const ARErrorDomain;
+/**
+ Codes that identify errors in ARKit.
+ */
API_AVAILABLE(ios(11.0))
typedef NS_ERROR_ENUM(ARErrorDomain, ARErrorCode){
- /** Unsupported configuration. */
+ /**
+ An error that indicates the device lacks support for the session's configuration.
+
+ Call ``ARConfiguration/isSupported`` on an ``ARConfiguration`` to ensure it's supported
+ before attempting to create and run it on the session with ``ARSession/runWithConfiguration:``.
+ */
ARErrorCodeUnsupportedConfiguration = 100,
- /** A sensor required to run the session is not available. */
+ /**
+ An error that indicates the framework fails to access a required sensor.
+ */
ARErrorCodeSensorUnavailable = 101,
- /** A sensor failed to provide the required input. */
+ /**
+ An error that indicates a sensor fails to provide required input.
+ */
ARErrorCodeSensorFailed = 102,
- /** App does not have permission to use the camera. The user may change this in settings. */
+ /**
+ An error that indicates the app lacks user permission for the camera.
+
+ To use the device's camera:
+
+ - Your app's Info.plist file must provide a message for the
+ [NSCameraUsageDescription](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html#//apple_ref/doc/plist/info/NSCameraUsageDescription)
+ key. If this key is missing, any attempt to run an AR session fails with this error.
+ - When your app first attempts to run an AR session or otherwise use the camera, iOS automatically shows an alert with your camera usage
+ description message, asking the user to grant camera permission to your app. If the user accepts this request, the session begins; otherwise the
+ session fails with this error.
+ - If the user has previously denied camera permission for your app, all attempts to run an AR session or otherwise use the camera fail with this
+ error. To grant camera permission, the user must explicitly enable your app in the iOS Settings app, under Privacy > Camera.
+ */
ARErrorCodeCameraUnauthorized = 103,
- /** App does not have permission to use the microphone. The user may change this in settings. */
+ /**
+ An error that indicates the app lacks user permission for the microphone.
+
+ When this error occurs, the app needs to prompt the user to give permission to use the
+ microphone in Settings.
+ */
ARErrorCodeMicrophoneUnauthorized = 104,
- /** App does not have permission to use the location data of the device. The user may change this in settings. */
+ /**
+ An error that indicates the app lacks user permission for the device's current location.
+
+ To resolve this issue, the app needs to ask the user to enable location access for this
+ app in Settings.
+ */
ARErrorCodeLocationUnauthorized API_AVAILABLE(ios(14.0)) = 105,
- /** A high-resolution frame is requested while another one is being captured. */
+ /**
+ An error that indicates the system needs to finish a high-resolution frame request before accepting another request.
+
+ The system provides this error to the completion handler of
+ ``ARSession/captureHighResolutionFrame(completion:)`` for failed operations.
+ */
ARErrorCodeHighResolutionFrameCaptureInProgress API_AVAILABLE(ios(16.0)) = 106,
- /** High-resolution frame capture failed. */
+ /**
+ An error that indicates a problem in the system's capture pipeline.
+
+ The system provides this error to the completion handler of
+ ``ARSession/captureHighResolutionFrame(completion:)`` for failed operations.
+ */
ARErrorCodeHighResolutionFrameCaptureFailed API_AVAILABLE(ios(16.0)) = 107,
- /** World tracking has encountered a fatal error. */
+ /**
+ An error that indicates world tracking experienced an unrecoverable problem.
+ */
ARErrorCodeWorldTrackingFailed = 200,
- /** Geo tracking is not available at this location. */
+ /**
+ An error that indicates a location lacks geotracking support.
+
+ This error code indicates that ARKit does not have the necessary localization imagery to
+ support geo tracking at the user's current location. See
+ ``ARGeoTrackingConfiguration/checkAvailability(completionHandler:)`` for more information.
+
+ If ``ARGeoTrackingConfiguration/checkAvailability(completionHandler:)`` returns
+ <doc://com.apple.documentation/documentation/swift/true> and an app begins a geo-tracking
+ session, ARKit provides this error when the user has moved to an unsupported area.
+ */
ARErrorCodeGeoTrackingNotAvailableAtLocation API_AVAILABLE(ios(14.0)) = 201,
- /** Geo tracking has encountered a runtime error. */
+ /**
+ An error that indicates localization imagery fails to match the device's camera captures.
+
+ ARKit returns this error code when visual localization is taking too long.
+ This situation indicates that the app has met all requirements for geo tracking except for
+ visual localization. To try again, the app needs to ask the user pan the device around the
+ physical environment to acquire different camera-feed imagery. For more information, see
+ <doc:ARGeoTrackingStatus/State/localizing#Assisting-the-User-with-Visual-Localization>.
+ */
ARErrorCodeGeoTrackingFailed API_AVAILABLE(ios(14.0)) = 202,
- /** Invalid reference image */
+ /**
+ An error that indicates the framework fails to process a reference image.
+
+ This error occurs when you supply a reference image to the configuration's
+ ``ARWorldTrackingConfiguration/detectionImages`` but ARKit determined it's unusable. This can
+ happen when the image data doesn't contain enough features to identify a unique picture, for
+ example, it's all white.
+ */
ARErrorCodeInvalidReferenceImage API_AVAILABLE(ios(11.3)) = 300,
- /** Invalid reference object. Occurs when the framework can't load a reference object,
- when the reference object's format doesn't support a requested operation, or when a
- configuration mixes legacy `.arobject` and `.referenceobject` reference objects in
- the same session. Inspect `userInfo` for the specific reason. */
+ /**
+ An error that indicates the framework fails to process a reference object.
+
+ Occurs when the framework can't load a reference object, when the reference object's format
+ doesn't support a requested operation, or when a configuration mixes legacy `.arobject` and
+ `.referenceobject` reference objects in the same session. Inspect `userInfo` for the specific
+ reason.
+ */
ARErrorCodeInvalidReferenceObject API_AVAILABLE(ios(12.0)) = 301,
- /** Invalid world map. */
+ /**
+ An error that indicates the framework fails to process a world map.
+ */
ARErrorCodeInvalidWorldMap API_AVAILABLE(ios(12.0)) = 302,
- /** Invalid configuration. */
+ /**
+ An error that indicates the configuration contains ambiguous or erroneous data.
+ */
ARErrorCodeInvalidConfiguration API_AVAILABLE(ios(12.0)) = 303,
- /** Invalid collaboration data.*/
+ /**
+ An error that indicates the framework fails to parse collaboration data the app receives over the network.
+
+ ARKit produces this error when an app passes invalid data into the ``ARSession/update(with:)``
+ function.
+ */
ARErrorCodeInvalidCollaborationData API_AVAILABLE(ios(13.2)) = 304,
- /** Insufficient features. */
+ /**
+ An error that indicates the framework requires more features to complete a task.
+
+ For more information about a session's feature requirements, see
+ <doc:managing-session-life-cycle-and-tracking-quality>.
+ */
ARErrorCodeInsufficientFeatures API_AVAILABLE(ios(12.0)) = 400,
- /** Object merge failed. */
+ /**
+ An error that indicates the framework fails to merge a detected object.
+ */
ARErrorCodeObjectMergeFailed API_AVAILABLE(ios(12.0)) = 401,
- /** Unable to read or write to file. */
+ /**
+ An error that indicates a file access fails to read or write.
+ */
ARErrorCodeFileIOFailed API_AVAILABLE(ios(12.0)) = 500,
- /** Generic request failure. */
+ /**
+ An error that indicates a request fails.
+ */
ARErrorCodeRequestFailed API_AVAILABLE(ios(14.0)) = 501,
};
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARFaceAnchor.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARFaceAnchor.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARFaceAnchor.h 2026-08-15 23:02:19
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARFaceAnchor.h 2026-10-04 02:32:28
@@ -14,103 +14,242 @@
API_UNAVAILABLE_BEGIN(visionos)
/**
- Blend shape locations of a face geometry.
+ Identifiers for specific facial features, for use with coefficients describing the relative movements of those features.
- Each location defines an area of the face that can be displaced with a provided coefficient.
+ The ``ARFaceAnchor/blendShapes`` dictionary provided by an ``ARFaceAnchor`` object describes the facial expression of a detected face in terms of the
+ movements of specific facial features. For each key in the dictionary, the corresponding value is a floating point number indicating the current
+ position of that feature relative to its neutral configuration, ranging from `0.0` (neutral) to `1.0` (maximum movement).
+ ARKit provides many blend shape coefficients, resulting in a detailed model of a facial expression; however, you can use as many or as few of the
+ coefficients as you desire to create a visual effect. For example, you might animate a simple cartoon character using only the ``jawOpen``,
+ ``eyeBlinkLeft``, and ``eyeBlinkRight`` coefficients. A professional 3D artist could create a detailed character model rigged for realistic animation
+ using a larger set, or the entire set, of coefficients.
+
+ > Note:
+ > In the naming of blend shape coefficients, the left and right directions are relative to the face. That is, the ``eyeBlinkRight`` coefficient
+ refers to the face's right eye. ARKit views running a face-tracking session mirror the camera image, so the face's right eye appears on the right
+ side in the view.
+
- Note: Blend shapes are computed based on the captured image. For example, if the detected person has a closed right eye, the eye on the left side
of the captured image will appear closed and reported as blend shape activation by ARKit.
- SeeAlso: ``ARFrame/capturedImage``
*/
typedef NSString *ARBlendShapeLocation NS_STRING_ENUM NS_SWIFT_NAME(ARFaceAnchor.BlendShapeLocation) API_AVAILABLE(ios(11.0));
+/** The coefficient describing downward movement of the outer portion of the left eyebrow. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationBrowDownLeft API_AVAILABLE(ios(11.0));
+/** The coefficient describing downward movement of the outer portion of the right eyebrow. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationBrowDownRight API_AVAILABLE(ios(11.0));
+/** The coefficient describing upward movement of the inner portion of both eyebrows. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationBrowInnerUp API_AVAILABLE(ios(11.0));
+/** The coefficient describing upward movement of the outer portion of the left eyebrow. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationBrowOuterUpLeft API_AVAILABLE(ios(11.0));
+/** The coefficient describing upward movement of the outer portion of the right eyebrow. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationBrowOuterUpRight API_AVAILABLE(ios(11.0));
+/** The coefficient describing outward movement of both cheeks. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationCheekPuff API_AVAILABLE(ios(11.0));
+/** The coefficient describing upward movement of the cheek around and below the left eye. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationCheekSquintLeft API_AVAILABLE(ios(11.0));
+/** The coefficient describing upward movement of the cheek around and below the right eye. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationCheekSquintRight API_AVAILABLE(ios(11.0));
+/** The coefficient describing closure of the eyelids over the left eye. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationEyeBlinkLeft API_AVAILABLE(ios(11.0));
+/** The coefficient describing closure of the eyelids over the right eye. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationEyeBlinkRight API_AVAILABLE(ios(11.0));
+/** The coefficient describing movement of the left eyelids consistent with a downward gaze. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationEyeLookDownLeft API_AVAILABLE(ios(11.0));
+/** The coefficient describing movement of the right eyelids consistent with a downward gaze. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationEyeLookDownRight API_AVAILABLE(ios(11.0));
+/** The coefficient describing movement of the left eyelids consistent with a rightward gaze. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationEyeLookInLeft API_AVAILABLE(ios(11.0));
+/** The coefficient describing movement of the right eyelids consistent with a leftward gaze. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationEyeLookInRight API_AVAILABLE(ios(11.0));
+/** The coefficient describing movement of the left eyelids consistent with a leftward gaze. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationEyeLookOutLeft API_AVAILABLE(ios(11.0));
+/** The coefficient describing movement of the right eyelids consistent with a rightward gaze. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationEyeLookOutRight API_AVAILABLE(ios(11.0));
+/** The coefficient describing movement of the left eyelids consistent with an upward gaze. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationEyeLookUpLeft API_AVAILABLE(ios(11.0));
+/** The coefficient describing movement of the right eyelids consistent with an upward gaze. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationEyeLookUpRight API_AVAILABLE(ios(11.0));
+/** The coefficient describing contraction of the face around the left eye. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationEyeSquintLeft API_AVAILABLE(ios(11.0));
+/** The coefficient describing contraction of the face around the right eye. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationEyeSquintRight API_AVAILABLE(ios(11.0));
+/** The coefficient describing a widening of the eyelids around the left eye. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationEyeWideLeft API_AVAILABLE(ios(11.0));
+/** The coefficient describing a widening of the eyelids around the right eye. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationEyeWideRight API_AVAILABLE(ios(11.0));
+/** The coefficient describing forward movement of the lower jaw. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationJawForward API_AVAILABLE(ios(11.0));
+/** The coefficient describing leftward movement of the lower jaw. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationJawLeft API_AVAILABLE(ios(11.0));
+/** The coefficient describing an opening of the lower jaw. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationJawOpen API_AVAILABLE(ios(11.0));
+/** The coefficient describing rightward movement of the lower jaw. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationJawRight API_AVAILABLE(ios(11.0));
+/**
+ The coefficient describing closure of the lips _independent of jaw position_.
+
+ This coefficient describes a closing of the lips without relation to the position of the jaw (the ``ARFaceAnchor/BlendShapeLocation/jawOpen``
+ coefficient), so some values of the ``ARFaceAnchor/BlendShapeLocation/mouthClose`` coefficient can produce unrealistic facial expressions unless
+ other coefficients are also set to realistic values.
+*/
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthClose API_AVAILABLE(ios(11.0));
+/** The coefficient describing backward movement of the left corner of the mouth. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthDimpleLeft API_AVAILABLE(ios(11.0));
+/** The coefficient describing backward movement of the right corner of the mouth. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthDimpleRight API_AVAILABLE(ios(11.0));
+/** The coefficient describing downward movement of the left corner of the mouth. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthFrownLeft API_AVAILABLE(ios(11.0));
+/** The coefficient describing downward movement of the right corner of the mouth. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthFrownRight API_AVAILABLE(ios(11.0));
+/** The coefficient describing contraction of both lips into an open shape. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthFunnel API_AVAILABLE(ios(11.0));
+/** The coefficient describing leftward movement of both lips together. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthLeft API_AVAILABLE(ios(11.0));
+/** The coefficient describing downward movement of the lower lip on the left side. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthLowerDownLeft API_AVAILABLE(ios(11.0));
+/** The coefficient describing downward movement of the lower lip on the right side. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthLowerDownRight API_AVAILABLE(ios(11.0));
+/** The coefficient describing upward compression of the lower lip on the left side. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthPressLeft API_AVAILABLE(ios(11.0));
+/** The coefficient describing upward compression of the lower lip on the right side. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthPressRight API_AVAILABLE(ios(11.0));
+/** The coefficient describing contraction and compression of both closed lips. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthPucker API_AVAILABLE(ios(11.0));
+/** The coefficient describing rightward movement of both lips together. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthRight API_AVAILABLE(ios(11.0));
+/** The coefficient describing movement of the lower lip toward the inside of the mouth. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthRollLower API_AVAILABLE(ios(11.0));
+/** The coefficient describing movement of the upper lip toward the inside of the mouth. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthRollUpper API_AVAILABLE(ios(11.0));
+/** The coefficient describing outward movement of the lower lip. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthShrugLower API_AVAILABLE(ios(11.0));
+/** The coefficient describing outward movement of the upper lip. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthShrugUpper API_AVAILABLE(ios(11.0));
+/** The coefficient describing upward movement of the left corner of the mouth. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthSmileLeft API_AVAILABLE(ios(11.0));
+/** The coefficient describing upward movement of the right corner of the mouth. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthSmileRight API_AVAILABLE(ios(11.0));
+/** The coefficient describing leftward movement of the left corner of the mouth. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthStretchLeft API_AVAILABLE(ios(11.0));
+/** The coefficient describing rightward movement of the right corner of the mouth. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthStretchRight API_AVAILABLE(ios(11.0));
+/** The coefficient describing upward movement of the upper lip on the left side. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthUpperUpLeft API_AVAILABLE(ios(11.0));
+/** The coefficient describing upward movement of the upper lip on the right side. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationMouthUpperUpRight API_AVAILABLE(ios(11.0));
+/** The coefficient describing a raising of the left side of the nose around the nostril. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationNoseSneerLeft API_AVAILABLE(ios(11.0));
+/** The coefficient describing a raising of the right side of the nose around the nostril. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationNoseSneerRight API_AVAILABLE(ios(11.0));
+/** The coefficient describing extension of the tongue. */
FOUNDATION_EXTERN ARBlendShapeLocation const ARBlendShapeLocationTongueOut API_AVAILABLE(ios(12.0));
@class ARFaceGeometry;
/**
- An anchor representing a face and its geometry.
+ An anchor for a unique face that is visible in the front-facing camera.
+
+ The session automatically adds an ``ARFaceAnchor`` object to its list of anchors when it detects a unique face in the front camera feed.
+
+ When you track faces using ``ARFaceTrackingConfiguration``, ARKit can track multiple faces simultaneously. Alternatively, you can enable face
+ tracking with a world tracking configuration.
+
+ ### Tracking Face Position and Orientation
+
+ The inherited ``ARAnchor/transform`` property describes the face's current position and orientation in world coordinates; that is, in a coordinate
+ space relative to that specified by the ``ARConfiguration/worldAlignment`` property of the session configuration. Use this transform matrix to
+ position virtual content you want to "attach" to the face in your AR scene.
+
+ This transform matrix creates a face coordinate system for positioning other elements relative to the face. Units of face coordinate space are in
+ meters, with the origin centered behind the face.
+
+ The coordinate system is right-handed—the positive x direction points to the viewer's right (that is, the face's own left), the positive y direction
+ points up (relative to the face itself, not to the world), and the positive z direction points outward from the face (toward the viewer).
+
+ ### Using Face Topology
+
+ The ``geometry`` property provides an ``ARFaceGeometry`` object representing detailed topology for the face, which conforms a generic face model to
+ match the dimensions, shape, and current expression of the detected face.
+
+ You can use this model as the basis for overlaying content that follows the shape of the user's face—for example, to apply virtual makeup or tattoos.
+ You can also use this model to create _occlusion geometry_—a 3D model that doesn't render any visible content (allowing the camera image to show
+ through), but that obstructs the camera's view of other virtual content in the scene.
+
+ ### Tracking Facial Expressions
+
+ The ``blendShapes`` property provides a high-level model of the current facial expression, described via a series of many named coefficients that
+ represent the movement of specific facial features relative to their neutral configurations. You can use blend shape coefficients to animate 2D or 3D
+ content, such as a character or avatar, in ways that follow the user's facial expressions.
*/
API_AVAILABLE(ios(11.0))
NS_SWIFT_SENDABLE
@interface ARFaceAnchor : ARAnchor <ARTrackable>
/**
- The face geometry updated based on the computed blend shapes.
+ A coarse triangle mesh representing the topology of the detected face.
+
+ This mesh provides vertex, index, and texture coordinate buffers describing the 3D shape of the face, conforming a generic face model to match the
+ dimensions, shape, and current expression of the detected face.
+
+ You can visualize the face geometry by passing these buffers to your preferred rendering engine. To visualize a face geometry using SceneKit, create
+ an ``ARSCNFaceGeometry`` instance and use its ``ARSCNFaceGeometry/update(from:)`` method to update it to match the face geometry.
*/
@property (nonatomic, strong, readonly) ARFaceGeometry *geometry;
/**
- The left eye’s rotation and translation relative to the anchor’s origin.
+ A transform matrix indicating the position and orientation of the face's left eye.
+
+ The translation aspect of this matrix indicates the position of the center of the eyeball, relative to the position represented by the anchor's
+ ``ARAnchor/transform``. The positive z-axis points from the center of the eyeball in the direction of the pupil.
+
+ Rotational aspects of the matrix indicate the orientation of the eyeball—for example, a rotation about the x-axis directs the pupil upward or
+ downward. The eye does not rotate about the z-axis.
*/
@property (nonatomic, assign, readonly) simd_float4x4 leftEyeTransform API_AVAILABLE(ios(12.0));
/**
- The right eye’s rotation and translation relative to the anchor’s origin.
+ A transform matrix indicating the position and orientation of the face's right eye.
+
+ The translation aspect of this matrix indicates the position of the center of the eyeball, relative to the position represented by the anchor's
+ ``ARAnchor/transform``. The positive z-axis points from the center of the eyeball in the direction of the pupil.
+
+ Rotational aspects of the matrix indicate the orientation of the eyeball—for example, a rotation about the x-axis directs the pupil upward or
+ downward. The eye does not rotate about the z-axis.
*/
@property (nonatomic, assign, readonly) simd_float4x4 rightEyeTransform API_AVAILABLE(ios(12.0));
/**
- Look-at point relative to the anchor’s origin.
+ A position in face coordinate space estimating the direction of the face's gaze.
+
+ This vector abstracts from the ``leftEyeTransform`` and ``rightEyeTransform`` matrices to estimate what point, relative to the face, the user's eyes
+ are focused upon. For example:
+
+ - If the user is looking to the left, the vector has a positive x-axis component.
+ - If the user is focused on a nearby object, the vector's length is shorter.
+ - If the user is focused on a faraway object, the vector's length is longer.
*/
@property (nonatomic, assign, readonly) simd_float3 lookAtPoint API_AVAILABLE(ios(12.0));
/**
- A dictionary of blend shape coefficients for each blend shape location.
+ A dictionary of named coefficients representing the detected facial expression in terms of the movement of specific facial features.
- Blend shapes coefficients define the amount of displacement of a neutral shape at a specific location on the face.
-*/
+ Each key in this dictionary (an ``ARFaceAnchor/BlendShapeLocation`` constant) represents one of many specific facial features recognized by ARKit.
+ The corresponding value for each key is a floating point number indicating the current position of that feature relative to its neutral
+ configuration, ranging from `0.0` (neutral) to `1.0` (maximum movement).
+
+ You can use blend shape coefficients to animate a 2D or 3D character in ways that follow the user's facial expressions. ARKit provides many blend
+ shape coefficients, resulting in a detailed model of a facial expression; however, you can use as many or as few of the coefficients as you desire to
+ create a visual effect. For example, you might animate a simple cartoon character using only the ``ARFaceAnchor/BlendShapeLocation/jawOpen``,
+ ``ARFaceAnchor/BlendShapeLocation/eyeBlinkLeft``, and ``ARFaceAnchor/BlendShapeLocation/eyeBlinkRight`` coefficients. A professional 3D artist could
+ create a detailed character model rigged for realistic animation using a larger set, or the entire set, of coefficients.
+
+ You can also use blend shape coefficients to record a specific facial expression and reuse it later. The ``ARFaceGeometry``
+ ``ARFaceGeometry/init(blendShapes:)`` initializer creates a detailed 3D mesh from a dictionary equivalent to this property's value; the serialized
+ form of a blend shapes dictionary is more portable than that of the face mesh those coefficients describe.
+ */
@property (nonatomic, strong, readonly) NSDictionary<ARBlendShapeLocation, NSNumber *> *blendShapes;
/**
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARFaceGeometry.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARFaceGeometry.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARFaceGeometry.h 2026-08-15 23:02:19
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARFaceGeometry.h 2026-10-04 02:32:29
@@ -18,53 +18,106 @@
API_UNAVAILABLE_BEGIN(visionos)
/**
- An object representing the geometry of a face.
+ A 3D mesh describing face topology for use in face-tracking AR sessions.
- The face geometry will have a constant number of triangles
- and vertices, updating only the vertex positions from frame to frame.
+ This class provides a general model for the detailed topology of a face, in the form of a 3D mesh appropriate for use with various rendering
+ technologies or for exporting 3D assets. (For a quick way to visualize a face geometry using SceneKit, see the ``ARSCNFaceGeometry`` class.)
+
+ When you obtain a face geometry from an ``ARFaceAnchor`` object in a face-tracking AR session, the model conforms to match the dimensions, shape, and
+ current expression of the detected face. You can also create a face mesh using a dictionary of named blend shape coefficients, which provides a
+ detailed, but more efficient, description of the face's current expression.
+
+ In an AR session, you can use this model as the basis for overlaying content that follows the shape of the user's face—for example, to apply virtual
+ makeup or tattoos. You can also use this model to create occlusion geometry, which hides other virtual content behind the 3D shape of the detected
+ face in the camera image.
+
+ > Note:
+ > Face mesh topology is constant across ``ARFaceGeometry`` instances. That is, the values of the ``vertexCount``, ``textureCoordinateCount``, and
+ ``triangleCount`` properties never change, the ``triangleIndices-3tb1o`` buffer always describes the same arrangement of vertices, and the
+ ``textureCoordinates-8ahq1`` buffer always maps the same vertex indices to the same texture coordinates.
+ >
+ > Only the ``vertices-fhdb`` buffer changes between face meshes provided by an AR session, indicating the change in vertex positions as ARKit adapts
+ the mesh to the shape and expression of the user's face.
*/
API_AVAILABLE(ios(11.0))
NS_SWIFT_SENDABLE
@interface ARFaceGeometry : NSObject <NSSecureCoding, NSCopying>
/**
-The number of mesh vertices of the geometry.
+ The number of elements in the ``ARFaceGeometry/vertices-fhdb`` buffer.
+
+ Face mesh topology is constant across ``ARFaceGeometry`` instances, so the value of this property is the same for all instances.
*/
@property (nonatomic, readonly) NSUInteger vertexCount NS_REFINED_FOR_SWIFT;
/**
- The mesh vertices of the geometry.
+ A buffer of vertex positions for each point in the face mesh.
+
+ Each `float3` value in this buffer represents the position of a vertex in the mesh, in face coordinates. (See
+ <doc:ARFaceAnchor#Tracking-Face-Position-and-Orientation>.)
+
+ The ``ARFaceGeometry/vertexCount`` property provides the number of elements in the buffer.
*/
@property (nonatomic, readonly) const simd_float3 *vertices NS_REFINED_FOR_SWIFT;
/**
- The number of texture coordinates of the face geometry.
+ The number of elements in the ``ARFaceGeometry/textureCoordinates-8ahq1`` buffer.
+
+ Face mesh topology is constant across ``ARFaceGeometry`` instances, so the value of this property is the same for all instances.
*/
@property (nonatomic, readonly) NSUInteger textureCoordinateCount NS_REFINED_FOR_SWIFT;
/**
- The texture coordinates of the geometry.
+ A buffer of texture coordinate values for each point in the face mesh.
+
+ Each `float2` value in this buffer represents the UV texture coordinates for the vertex at the corresponding index in the
+ ``ARFaceGeometry/vertices-fhdb`` buffer.
+
+ The ``ARFaceGeometry/textureCoordinateCount`` property provides the number of elements in the buffer.
+
+ Face mesh topology is constant across ``ARFaceGeometry`` instances, so the data in this buffer always maps the same vertex indices to the same
+ texture coordinates.
*/
@property (nonatomic, readonly) const simd_float2 *textureCoordinates NS_REFINED_FOR_SWIFT;
/**
- The number of triangles of the face geometry.
+ The number of triangles described by the ``ARFaceGeometry/triangleIndices-3tb1o`` buffer.
+
+ Each set of three indices forms a triangle, so the number of indices in the ``ARFaceGeometry/triangleIndices-3tb1o`` buffer is three times the
+ ``ARFaceGeometry/triangleCount`` value.
+
+ Face mesh topology is constant across ``ARFaceGeometry`` instances, so the value of this property is the same for all instances.
*/
@property (nonatomic, readonly) NSUInteger triangleCount;
/**
- The triangle indices of the geometry.
+ A buffer of indices describing the triangle mesh formed by the face geometry's vertex data.
+
+ Each 16-bit integer value in this buffer represents an index into the ``ARFaceGeometry/vertices-fhdb`` and
+ ``ARFaceGeometry/textureCoordinates-8ahq1`` buffers. Each set of three indices identifies the vertices that form a single triangle in the mesh. (That
+ is, this buffer is appropriate for use as an index buffer for a triangle mesh in GPU-based rendering or creating 3D model asset files.)
+
+ Each set of three indices forms a triangle, so the number of indices in the ``ARFaceGeometry/triangleIndices-3tb1o`` buffer is three times the
+ ``ARFaceGeometry/triangleCount`` value.
+
+ Face mesh topology is constant across ``ARFaceGeometry`` instances, so this buffer always describes the same arrangement of vertices. Only the
+ ``ARFaceGeometry/vertices-fhdb`` buffer changes between face meshes provided by an AR session, indicating the change in vertex positions as ARKit
+ adapts the mesh to the shape and expression of the user's face.
*/
@property (nonatomic, readonly) const int16_t *triangleIndices NS_REFINED_FOR_SWIFT;
/**
- Creates and returns a face geometry by applying a set of given blend shape coefficients.
+ Creates a face geometry matching the facial expression described in the specified dictionary.
- An empty dictionary can be provided to create a neutral face geometry.
+ Each key in the `blendShapes` dictionary is an ``ARFaceAnchor/BlendShapeLocation`` constant identifying a facial feature. The corresponding value is
+ the position of that feature relative to its neutral configuration, ranging from `0.0` (neutral) to `1.0` (maximum movement).
- - Parameter blendShapes: A dictionary of blend shape coefficients.
+ The format of this dictionary is identical to that provided by the ``ARFaceAnchor`` ``ARFaceAnchor/blendShapes`` property. You can use that property
+ and this initializer to efficiently save and restore facial expression data; the serialized form of a blend shapes dictionary is more portable than
+ that of the face mesh those coefficients describe.
- - Returns: Face geometry after applying the blend shapes.
+ - Parameter blendShapes: A dictionary of blend shape coefficients describing a facial expression in terms of the positions of specific facial
+ features. For any coefficient not specified in this dictionary, ARKit assumes a value of `0.0`.
*/
- (nullable instancetype)initWithBlendShapes:(NSDictionary<ARBlendShapeLocation, NSNumber *> *)blendShapes;
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARFrame.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARFrame.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARFrame.h 2026-08-15 23:02:19
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARFrame.h 2026-10-04 02:32:28
@@ -30,20 +30,20 @@
API_UNAVAILABLE_BEGIN(visionos)
/**
- Segmentation classes which defines a pixel's semantic label.
+ A categorization of a pixel that defines a type of content you use to occlude your app's virtual content.
- When running a configuration with 'ARFrameSemanticPersonSegmentation' every pixel in the
- segmentationBuffer on the ARFrame will conform to one of these classes.
+ ARKit applies the categories defined in this class based on its interpretation of the camera feed's pixel data. Only people are identified in a
+ camera feed, and therefore the available pixel classifications are either ``person`` or ``none``.
- SeeAlso: ``ARConfiguration/frameSemantics``
- SeeAlso: ``ARFrame/segmentationBuffer``
*/
API_AVAILABLE(ios(13.0))
typedef NS_ENUM(uint8_t, ARSegmentationClass) {
- /* Pixel has been not been classified. */
+ /** A classification of a pixel in the segmentation buffer as unidentified. */
ARSegmentationClassNone = 0,
- /* Pixel has been classified as person. */
+ /** A classification of a pixel in the segmentation buffer as part of a person. */
ARSegmentationClassPerson = 255
} NS_SWIFT_NAME(ARFrame.SegmentationClass);
@@ -53,156 +53,311 @@
*/
API_AVAILABLE(ios(12.0))
typedef NS_ENUM(NSInteger, ARWorldMappingStatus) {
- /** World mapping is not available. */
+ /** No world map is available.
+
+ When the ``ARFrame/worldMappingStatus`` of the session's ``ARSession/currentFrame`` is ``ARFrame/WorldMappingStatus/notAvailable``, the session
+ has no internal map of the real-world space around the device, nor the scene visible to the camera. Calling
+ ``ARSession/getCurrentWorldMap(completionHandler:)`` at this time results in an error.
+
+ This status occurs shortly after starting a new session. To save or share a world map, wait for the user to explore their surroundings and the
+ session's status to change to ``ARFrame/WorldMappingStatus/mapped`` or ``ARFrame/WorldMappingStatus/extending``. */
ARWorldMappingStatusNotAvailable,
- /** World mapping is available but has limited features.
- For the device's current position, the session’s world map is not recommended for relocalization. */
+ /** World tracking has not yet sufficiently mapped the area around the current device position.
+
+ When the ``ARFrame/worldMappingStatus`` of the session's ``ARSession/currentFrame`` is ``ARFrame/WorldMappingStatus/limited``, the session has
+ not yet fully mapped the real-world space around the device, nor the scene visible to the camera.
+
+ Although it is possible at this time to save a world map by calling ``ARSession/getCurrentWorldMap(completionHandler:)``, the resulting
+ ``ARWorldMap`` is unlikely to be useful for relocalization in the real-world space near the device's current position.
+
+ To produce a higher quality world map, wait for the user to explore more of their surroundings and the session's status to change to
+ ``ARFrame/WorldMappingStatus/mapped`` or ``ARFrame/WorldMappingStatus/extending``. */
ARWorldMappingStatusLimited,
- /** World mapping is actively extending the map with the user's motion.
- The world map will be relocalizable for previously visited areas but is still being updated for the current space. */
+ /** World tracking has mapped recently visited areas, but is still mapping around the current device position.
+
+ When the ``ARFrame/worldMappingStatus`` of the session's ``ARSession/currentFrame`` is ``ARFrame/WorldMappingStatus/extending``, the session has
+ produced a high-fidelity internal map of the real-world spaces the device has recently passed through, but is still collecting data to map the
+ area around the device's current position and the scene visible to the camera.
+
+ This status provides moderate to high reliability for relocalizing to a saved world map, provided that:
+
+ 1. You call ``ARSession/getCurrentWorldMap(completionHandler:)`` to save the world map while the status of the ``ARSession/currentFrame`` is
+ ``ARFrame/WorldMappingStatus/extending``.
+ 2. When you run a new session (later or on another device) from that ``ARWorldMap``, the device running the new session passes through positions
+ and orientations that were visited by the device that saved the session.
+
+ Saving or sharing a world map at this time is likely to produce adequate results, but a higher quality world map may be possible if you wait
+ until the user explores more of their surroundings and the status changes to ``ARFrame/WorldMappingStatus/mapped``. */
ARWorldMappingStatusExtending,
- /** World mapping has adequately mapped the visible area.
- The map can be used to relocalize for the device's current position. */
+ /** World tracking has adequately mapped the visible area.
+
+ When the ``ARFrame/worldMappingStatus`` of the session's ``ARSession/currentFrame`` is ``ARFrame/WorldMappingStatus/mapped``, the session has
+ produced a high-fidelity internal map of the real-world space around the device's current position and the scene visible to the camera.
+
+ This status provides the highest reliability for relocalizing to a saved world map, provided that:
+
+ 1. You call ``ARSession/getCurrentWorldMap(completionHandler:)`` to save the world map while the status of the ``ARSession/currentFrame`` is
+ ``ARFrame/WorldMappingStatus/mapped``.
+ 2. When you run a new session (later or on another device) from that ``ARWorldMap``, the device running the new session is at a real-world
+ position and orientation similar to that when the world map was saved. */
ARWorldMappingStatusMapped
} NS_SWIFT_NAME(ARFrame.WorldMappingStatus);
/**
- An object encapsulating the state of everything being tracked for a given moment in time.
+ A video image captured as part of a session with position-tracking information.
- The model provides a snapshot of all data needed to render a given frame.
+ A running session continuously captures video frames from the device's camera while ARKit analyzes the captures to determine the user's position in
+ the world. ARKit can provide this information to you in the form of an ``ARFrame`` in two ways:
+
+ - Occasionally, by accessing an ``ARSession`` object's ``ARSession/currentFrame``
+ - Constantly, as a stream of frames through the ``ARSessionDelegate/session(_:didUpdate:)-9v2kw`` callback
+
+ To automatically receive all frames as ARKit captures them, make one of your objects the ``ARSession/delegate`` of your app's ``ARSession``.
+
+ Each frame can contain additional data, for example, EXIF (``exifData``), or data based on any particular ``ARConfiguration/frameSemantics`` that you
+ enable.
*/
API_AVAILABLE(ios(11.0))
NS_SWIFT_SENDABLE
@interface ARFrame : NSObject <NSCopying>
/**
- A timestamp identifying the frame.
+ The time at which the frame was captured.
*/
@property (nonatomic, readonly) NSTimeInterval timestamp;
/**
- The frame’s captured image.
+ A pixel buffer containing the image captured by the camera.
+
+ ARKit captures pixel buffers in a full-range planar YCbCr format (also known as YUV) format according to the ITU R. 601-4 standard. (You can verify
+ this by checking the <doc://com.apple.documentation/documentation/corevideo/kcvimagebufferycbcrmatrixkey> pixel buffer attachment.)
+
+ Unlike some uses of that standard, ARKit captures full-range color space values, not video-range values. To correctly render these images on a device
+ display, you'll need to access the luma and chroma planes of the pixel buffer and convert full-range YCbCr values to an sRGB (or ITU R. 709) format
+ according to the ITU-T T.871 specification.
+
+ The following matrix (shown in Metal shader syntax) performs this conversion when multiplied by a 4-element vector (containing Y', Cb, Cr values and
+ an "alpha" value of 1.0):
+
+ ```cpp
+ const float4x4 ycbcrToRGBTransform = float4x4(
+ float4(+1.0000f, +1.0000f, +1.0000f, +0.0000f),
+ float4(+0.0000f, -0.3441f, +1.7720f, +0.0000f),
+ float4(+1.4020f, -0.7141f, +0.0000f, +0.0000f),
+ float4(-0.7010f, +0.5291f, -0.8860f, +1.0000f)
+ );
+ ```
+
+ For more details, see <doc:displaying-an-ar-experience-with-metal>, or use the Metal variant of the AR app template when creating a new project in
+ Xcode.
*/
@property (nonatomic, readonly) CVPixelBufferRef capturedImage;
/**
- A dictionary of EXIF metadata for the captured image.
+ Auxiliary data for the captured image.
+
+ The system's image capture pipeline produces pixel data and auxiliary information for each exposure. The AR frame exposes this pixel data through
+ ``ARFrame/capturedImage`` and the auxiliary info through this property (``ARFrame/exifData``). Example EXIF data includes camera manufacturer,
+ orientation, compression, resolution, exposure, and the date and time that the exposure occurred.
*/
@property (nonatomic, strong, readonly) NSDictionary<NSString *, id> *exifData API_AVAILABLE(ios(16.0));
/**
- A tileable texture that contains image noise matching the current camera stream's noise properties.
+ A tileable Metal texture created by ARKit to match the visual characteristics of the current video stream.
- A camera stream depicts image noise that gives the captured image
- a grainy look and varies with light conditions.
- The variations are stored along the depth dimension of the camera grain texture
- and can be selected at runtime using the camera grain intensity of the current frame.
+ Camera grain enhances the visual cohesion of the real and augmented aspects of your user experience by enabling your app's virtual content to take on
+ similar image noise characteristics that naturally occur in the camera feed.
+
+ 
+
+ If ``ARSCNView`` is your renderer, SceneKit applies camera grain to your app's virtual content by default. For more information, see
+ ``ARSCNView/rendersCameraGrain``.
+
+ ### Enable Image Noise on a Custom Renderer
+
+ For apps that display an AR experience using a custom Metal renderer, ARKit provides you with an ``ARFrame/cameraGrainTexture`` that matches the
+ noise it detects in the current video stream. Set the noise texture onto your renderer to apply its characteristics to your virtual content.
+
+ The depth dimension of the image noise texture contains variations that you select at runtime based on the ``ARFrame/cameraGrainIntensity`` of the
+ current frame.
*/
@property (nonatomic, nullable, readonly) id<MTLTexture> cameraGrainTexture API_AVAILABLE(ios(13.0));
/**
- The frame’s camera grain intensity in range 0 to 1.
+ A value that specifies the amount of grain present in the camera grain texture.
- A camera stream depicts image noise that gives the captured image
- a grainy look and varies with light conditions.
- The camera grain intensity can be used to select a texture slice from the frames
- camera grain texture.
+ This property is normalized within the range [0..1], where zero specifies no grain, and one specifies the maximum amount of grain.
+
+ When you apply this value to the depth component of the ``ARFrame/cameraGrainTexture``, you select among variations of visual image noise data stored
+ in the Metal texture that conceptually match this level of intensity.
*/
@property (nonatomic, readonly) float cameraGrainIntensity API_AVAILABLE(ios(13.0));
/**
- The frame’s captured depth data.
+ Depth data captured in front-camera experiences.
- Depth data is only provided with face tracking on frames where depth data was captured.
+ Frames vended by the session contain a depth map captured by the depth sensor in addition to the color pixel buffer (see ``ARFrame/capturedImage``)
+ captured by the color camera. The depth-sensing camera provides data at a different frame rate than the color camera, so this property's value can be
+ `nil` if no depth data was captured at the same time as the current color image.
+
+ This depth data is available only in face-based experiences (see ``ARFaceTrackingConfiguration``) using the device's front TrueDepth camera. This
+ property's value is `nil` when running other AR configurations.
*/
@property (nonatomic, strong, nullable, readonly) AVDepthData *capturedDepthData;
/**
- A timestamp identifying the depth data.
+ The time at which depth data for the frame (if any) was captured.
+
+ Face-based AR (see ``ARFaceTrackingConfiguration``) uses the front-facing, depth-sensing camera on compatible devices. When running such a
+ configuration, frames vended by the session contain a depth map captured by the depth camera in addition to the color pixel buffer (see
+ ``ARFrame/capturedImage``) captured by the color camera. This property's value is always zero when running other AR configurations.
+
+ The depth-sensing camera provides data at a different frame rate than the color camera, so this property's value may not exactly match the
+ ``ARFrame/timestamp`` property for the image captured by the color camera, and can also be zero if no depth data was captured at the same time as the
+ current color image.
*/
@property (nonatomic, readonly) NSTimeInterval capturedDepthDataTimestamp;
/**
- The camera used to capture the frame’s image.
-
- The camera provides the device’s position and orientation as well as camera parameters.
+ Information about the camera position, orientation, and imaging parameters used to capture the frame.
*/
@property (nonatomic, copy, readonly) ARCamera *camera;
/**
- A list of anchors in the scene.
+ The list of anchors representing positions tracked or objects detected in the scene.
+
+ You can manually add or remove anchors to track locations in the scene using the ``ARSession`` class. Depending on session configuration, ARKit may
+ also add anchors, such as the origin of the world coordinate system or automatically detected planes.
*/
@property (nonatomic, copy, readonly) NSArray<__kindof ARAnchor *> *anchors;
/**
- A light estimate representing the light in the scene.
+ An estimate of lighting conditions based on the camera image.
- Returns `nil` if there is no light estimation.
+ If you render your own overlay graphics for the AR scene, you can use this information in shading algorithms to help make those graphics match the
+ real-world lighting conditions of the scene captured by the camera. (The ``ARSCNView`` class automatically uses this information to configure
+ SceneKit lighting.)
+
+ This property's value is `nil` if the ``ARConfiguration/isLightEstimationEnabled`` property of the session configuration that captured this frame is
+ <doc://com.apple.documentation/documentation/swift/false>.
*/
@property (nonatomic, strong, nullable, readonly) ARLightEstimate *lightEstimate;
/**
- Feature points in the scene with respect to the frame’s origin.
+ The current intermediate results of the scene analysis ARKit uses to perform world tracking.
- The feature points are only provided for configurations using world tracking.
+ These points represent notable features detected in the camera image. Their positions in 3D world coordinate space are extrapolated as part of the
+ image analysis that ARKit performs in order to accurately track the device's position, orientation, and movement. Taken together, these points
+ loosely correlate to the contours of real-world objects in view of the camera.
+
+ ARKit does not guarantee that the number and arrangement of raw feature points will remain stable between software releases, or even between
+ subsequent frames in the same session. Regardless, the point cloud can sometimes prove useful when debugging your app's placement of virtual objects
+ into the real-world scene.
+
+ If you display AR content with SceneKit using the ``ARSCNView`` class, you can display this point cloud with the
+ ``ARSCNDebugOptionShowFeaturePoints`` debug option.
+
+ Feature point detection requires a ``ARWorldTrackingConfiguration`` session.
*/
@property (nonatomic, strong, nullable, readonly) ARPointCloud *rawFeaturePoints;
/**
- The status of world mapping for the area visible to the frame.
+ The feasibility of generating or relocalizing a world map for this frame.
- This can be used to identify the state of the world map for the visible area and if additional scanning
- should be done before saving a world map.
+ Every world-tracking session builds an internal world map, which ARKit uses to determine the device's position in the user's environment. You can
+ save a snapshot of that internal state as an ``ARWorldMap`` object, which you can use later to resume the saved session or share between devices to
+ create a multiuser AR experience.
+
+ While you can call ``ARSession/getCurrentWorldMap(completionHandler:)`` at any time during a session, some times are better than others. Use this
+ property to determine whether the session currently has enough data to generate a useful ``ARWorldMap`` or if it's better to wait for the session to
+ map more of the user's local environment first.
*/
@property (nonatomic, readonly) ARWorldMappingStatus worldMappingStatus API_AVAILABLE(ios(12.0));
/**
- A buffer that represents the segmented content of the capturedImage.
+ A buffer that contains pixel information identifying the shape of objects from the camera feed that you use to occlude virtual content.
- In order to identify to which class a pixel has been classified one needs to compare its intensity value with the values
- found in `ARSegmentationClass`.
+ ARKit generates the contents of this buffer by processing the camera feed.
+ If you implement a custom renderer, you apply this property by using alpha and depth mattes provided with ``ARMatteGenerator``.
+
+ Apps using one of the standard renderers don't need this property to occlude virtual content with people. The standard renderers
+ (<doc://com.apple.documentation/documentation/realitykit/arview>, ``ARSCNView``, and ``ARSKView``) enable people occlusion when you add
+ ``ARConfiguration/FrameSemantics/personSegmentation`` or ``ARConfiguration/FrameSemantics/personSegmentationWithDepth`` to your configuration's
+ ``ARConfiguration/frameSemantics``.
+
- SeeAlso: ``ARSegmentationClass``
- SeeAlso: ``ARConfiguration/frameSemantics``
*/
@property (nonatomic, nullable, readonly) CVPixelBufferRef segmentationBuffer API_AVAILABLE(ios(13.0));
/**
- A buffer that represents the estimated depth values for a performed segmentation.
+ A buffer that represents the estimated depth values from the camera feed that you use to occlude virtual content.
- For each non-background pixel in the segmentation buffer the corresponding depth value can be accessed in this buffer.
+ Each non-background pixel in the segmentation buffer maps to a depth value in this buffer. Use this to occlude people from the rendering of your
+ app's virtual content.
+ If you implement a custom renderer, you apply this property by using alpha and depth mattes provided with ``ARMatteGenerator``.
+
+ Apps using one of the standard renderers don't need this property to occlude virtual content with people. The standard renderers
+ (<doc://com.apple.documentation/documentation/realitykit/arview>, ``ARSCNView``, and ``ARSKView``) enable people occlusion when you add
+ ``ARConfiguration/FrameSemantics/personSegmentation`` or ``ARConfiguration/FrameSemantics/personSegmentationWithDepth`` to your configuration's
+ ``ARConfiguration/frameSemantics``.
+
- SeeAlso: ``ARConfiguration/frameSemantics``
- SeeAlso: ``ARFrame/segmentationBuffer``
*/
@property (nonatomic, nullable, readonly) CVPixelBufferRef estimatedDepthData API_AVAILABLE(ios(13.0));
/**
- A detected body in the current frame.
+ The screen position information of a body that ARKit recognizes in the camera image.
+ To enable 2D body detection, you add the ``ARConfiguration/FrameSemantics/bodyDetection`` frame semantic to your configuration's
+ ``ARConfiguration/frameSemantics`` property, or run your session with an ``ARBodyTrackingConfiguration``, in which body detection is enabled by
+ default.
+
- SeeAlso: ``ARConfiguration/frameSemantics``
*/
@property (nonatomic, nullable, readonly) ARBody2D *detectedBody API_AVAILABLE(ios(13.0));
/**
- The status of geo tracking.
+ The session's condition with respect to geographic tracking at the time the session captured the frame.
+
+ For the current geo-tracking status, check the value of this property on the session's ``ARSession/currentFrame``. ARKit populates this property only
+ for ``ARGeoTrackingConfiguration`` sessions.
*/
@property (nonatomic, strong, nullable, readonly) ARGeoTrackingStatus *geoTrackingStatus API_AVAILABLE(ios(14.0));
/**
- Scene depth data.
+ Data on the distance between a device's rear camera and real-world objects in an AR experience.
+ This property describes the distance between a device's camera and objects or areas in the real world, including ARKit's confidence in the estimated
+ distance.
+
+ This property is `nil` by default. Add the ``ARConfiguration/FrameSemantics/sceneDepth`` frame semantic to your configuration's
+ ``ARConfiguration/frameSemantics`` to instruct the framework to populate this value with ``ARDepthData`` captured by the LiDAR scanner.
+
+ Call ``ARConfiguration/supportsFrameSemantics(_:)`` on your app's configuration to support scene depth on select devices and configurations.
+
- SeeAlso: ``ARFrameSemanticSceneDepth``
- SeeAlso: ``ARConfiguration/frameSemantics``
*/
@property (nonatomic, strong, nullable, readonly) ARDepthData *sceneDepth API_AVAILABLE(ios(14.0));
/**
- Scene depth data, smoothed for temporal consistency.
+ An average of distance measurements between a device's rear camera and real-world objects that creates smoother visuals in an AR experience.
+ This property describes the distance between a device's camera and objects or areas in the real world, including ARKit's confidence in the estimated
+ distance. This is similar to ``ARFrame/sceneDepth`` except that the framework smoothes the depth data over time to lessen its frame-to-frame delta.
+
+ This property is `nil` by default. Add the ``ARConfiguration/FrameSemantics/smoothedSceneDepth`` frame semantic to your configuration's
+ ``ARConfiguration/frameSemantics`` to instruct the framework to populate this value with ``ARDepthData`` captured by the LiDAR scanner.
+
+ Call ``ARConfiguration/supportsFrameSemantics(_:)`` on your app's configuration to support smoothed scene depth on select devices and configurations.
+
- SeeAlso: ``ARFrameSemanticSmoothedSceneDepth``
- SeeAlso: ``ARConfiguration/frameSemantics``
*/
@@ -219,33 +374,39 @@
@property (nonatomic, strong, readonly) NSArray<__kindof AVMetadataObject *> *metadataObjects API_AVAILABLE(ios(27.0)) API_UNAVAILABLE(visionos);
/**
- Searches the frame for objects corresponding to a point in the captured image.
+ Searches for real-world objects or AR anchors in the captured camera image.
- A 2D point in the captured image’s coordinate space can refer to any point along a line segment
- in the 3D coordinate space. Hit-testing is the process of finding objects in the world located along this line segment.
+ Hit testing searches for real-world objects or surfaces detected through the AR session's processing of the camera image. A 2D point in the image
+ coordinates can refer to any point along a 3D line that starts at the device camera and extends in a direction determined by the device orientation
+ and camera projection. This method searches along that line, returning all objects that intersect it in order of distance from the camera.
+ > Note:
+ > If you use ARKit with a SceneKit or SpriteKit view, the ``ARSCNView`` ``ARSCNView/hitTest(_:types:)`` or ``ARSKView``
+ ``ARSKView/hitTest(_:types:)`` method lets you specify a search point in view coordinates.
+
+ The behavior of a hit test depends on which `types` you specify and the order you specify them in. For details, see ``ARHitTestResult`` and the
+ various ``ARHitTestResult/ResultType`` options.
+
- Parameters:
- - point: A point in the image-space coordinate system of the captured image.
- Values should range from (0,0) - upper left corner to (1,1) - lower right corner.
- - types: The types of results to search for.
+ - point: A point in normalized image coordinate space. (The point `(0,0)` represents the top left corner of the image, and the point `(1,1)`
+ represents the bottom right corner.)
+ - types: The types of hit-test result to search for.
- - Returns: An array of all hit-test results sorted from nearest to farthest.
+ - Returns: A list of results, sorted from nearest to farthest (in distance from the camera).
*/
- (NSArray<ARHitTestResult *> *)hitTest:(CGPoint)point types:(ARHitTestResultType)types API_DEPRECATED("Use [ARSession raycast:]", ios(11.0, 14.0));
/**
- Creates a raycast query originating from the point on the captured image, aligned along the center of the field of view of the camera.
+ Creates a raycast query for a screen point.
- A 2D point in the captured image's coordinate space and the field of view of the frame's camera is used to create a ray in the 3D
- coordinate space originating at the point.
+ To cast the ray, you pass the resulting query to your current session via ``ARSession/raycast(_:)`` or
+ ``ARSession/trackedRaycast(_:updateHandler:)``.
- Parameters:
- - point: A point in the image-space coordinate system of the captured image.
- Values should range from (0,0) - upper left corner to (1,1) - lower right corner.
- - target: Type of target where the ray should terminate.
- - alignment: Alignment of the target.
-
- - Returns: A raycast query configured with the specified parameters.
+ - point: A normalized coordinate in the UI system, where 0 is top-left, and 1 is bottom-right.
+ - target: The type of surface the raycast query can terminate on.
+ - alignment: An alignment with respect to gravity a plane must have to intersect this ray.
+- Returns: A raycast query configured with the specified parameters.
*/
- (ARRaycastQuery *)raycastQueryFromPoint:(CGPoint)point
allowingTarget:(ARRaycastTarget)target
@@ -258,17 +419,23 @@
typedef NS_ENUM(NSInteger, UIInterfaceOrientation);
/**
- Returns a display transform for the provided viewport size and orientation.
+ Returns an affine transform for converting between normalized image coordinates and a coordinate space appropriate for rendering the camera image
+ onscreen.
- The display transform can be used to convert normalized points in the image-space coordinate system
- of the captured image to normalized points in the view's coordinate space. The transform provides the correct rotation
- and aspect-fill for presenting the captured image in the given orientation and size.
+ Normalized image coordinates range from `(0,0)` in the upper left corner of the image to `(1,1)` in the lower right corner.
+ This method creates an affine transform representing the rotation and aspect-fit crop operations necessary to adapt the camera image to the specified
+ orientation and to the aspect ratio of the specified viewport. The affine transform does not scale to the viewport's pixel size.
+
+ The ``ARFrame/capturedImage`` pixel buffer is the original image captured by the device camera, and thus not adjusted for device orientation or view
+ aspect ratio.
+
- Parameters:
- - orientation: The orientation of the viewport.
- - viewportSize: The size of the viewport.
+ - orientation: The orientation intended for presenting the view.
+ - viewportSize: The size, in points, of the view intended for rendering the camera image.
- - Returns: The display transform matrix.
+ - Returns: A transform matrix that converts from normalized image coordinates in the captured image to normalized image coordinates that account for
+ the specified parameters.
*/
- (CGAffineTransform)displayTransformForOrientation:(UIInterfaceOrientation)orientation
viewportSize:(CGSize)viewportSize
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARGeoAnchor.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARGeoAnchor.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARGeoAnchor.h 2026-08-15 23:02:19
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARGeoAnchor.h 2026-10-04 02:32:29
@@ -15,79 +15,113 @@
API_UNAVAILABLE_BEGIN(visionos)
/**
- An anchor representing a geographical location in the world.
+ An anchor that identifies a geographic location using latitude, longitude, and altitude data.
- The anchor's transform will be automatically updated by the session based on location and heading.
- The session needs to be configured with ARGeoTrackingConfiguration.
+ A _geographic anchor_ (also known as _location anchor_) identifies a specific area in the world that the app can refer to in an AR experience. As a
+ user moves around the scene, the session updates a location anchor's ``ARAnchor/transform`` based on the anchor's ``coordinate`` and the device's
+ compass heading.
+
+ ARKit aligns location anchors to an East-North-Up orientation, with its x- and z-axes matching the longitude and latitude directions. For more
+ information, see ``ARConfiguration/WorldAlignment/gravityAndHeading``.
+
+ ARKit sets the anchor's vertical position to the altitude you pass in to ``initWithCoordinate:altitude:``. If you initialize a location anchor using
+ ``initWithCoordinate:`` instead, ARKit sets the anchor's altitude to ground level.
+
+ > Important:
+ > Location anchors are available only in geotracking sessions, and geotracking is available in specific areas; for more information, see
+ ``ARGeoTrackingConfiguration``.
+
+ ### Communicate Data Usage
+
+ Location anchors consume data from Apple Maps called _localization imagery_ (for more information, see ``ARGeoTrackingConfiguration``). As the user
+ moves, the framework downloads localization imagery to refine the user's precise geographic position. The amount of data the session requires depends
+ on the user's movement and distance they travel. To make the user aware of potential fees, you can notify the user of their data usage.
+
+ ### Manage Location Anchor Availability
+
+ When an app creates a location anchor, it's invisible to the user until the framework _populates_ the anchor in the scene. When an anchor populates
+ successfully, the session passes the anchor into the delegate's ``ARSessionDelegate/session(_:didAdd:)`` callback.
+
+ If ARKit fails to populate a location anchor, the session calls ``ARSessionDelegate/session(_:didRemove:)`` to notify your delegate. A location
+ anchor may fail to populate when:
+
+ - The network is unavailable. If you create a location anchor without providing an altitude, ARKit defaults the altitude to ground level, and may
+ query the server to check the topography at the anchor's geographic coordinate. If the network is unavailable, ask the user to restore a connection
+ by disabling Airplane Mode, enabling WiFi, or moving to a location that provides service. If the network is available but slow, an altitude query
+ response may be delayed. Consider pausing a navigation or presenting visual feedback for the anchor's tentative placement, such as by displaying a
+ status indicator.
+ - The location anchor is too far from the user. If users can create location anchors in your app, let them know to position the coordinates of each
+ anchor within 0.05 degrees (~5 kilometers) of themselves and their device.
+ - The server prevents the location anchor's position, such as in a large body of water.
*/
API_AVAILABLE(ios(14.0))
NS_SWIFT_SENDABLE
@interface ARGeoAnchor : ARAnchor <ARTrackable>
/**
- The coordinate where this anchor will be placed.
+ The latitude and longitude of the anchor's geographic location.
- The anchor's transform will be automatically updated by the session when `ARGeoTrackingConfiguration` is set.
+ This property is set by the app at anchor initialization. The anchor's transform will be automatically updated by the session when
+ `ARGeoTrackingConfiguration` is set.
*/
@property (nonatomic, readonly) CLLocationCoordinate2D coordinate;
/**
- The distance to mean sea level, in meters (negative values indicate it's below sea level).
+ Vertical distance, in meters, between this anchor and sea level.
- Only valid when `altitudeSource` is not `ARAltitudeSourceUnknown`.
+ Negative values indicate below sea level. This property is valid only when ``ARGeoAnchor/altitudeSource`` is a value other than
+ ``ARGeoAnchor/AltitudeSource/unknown``.
*/
@property (nonatomic, readonly) CLLocationDistance altitude NS_REFINED_FOR_SWIFT;
/**
- The source of altitude information. If the user did not provide the altitude, ARKit populates this property to indicate the expected accuracy
- depending on the available altitude data.
+ A record of the source from which an altitude came.
+
+ The value of this property is ``ARGeoAnchor/AltitudeSource/userDefined`` if you set the altitude yourself (see
+ ``ARSession/getGeoLocation(forPoint:completionHandler:)``).
+
+ If your app doesn't set the altitude, ARKit populates this property to indicate the altitude's expected accuracy (either
+ ``ARGeoAnchor/AltitudeSource/precise``, or ``ARGeoAnchor/AltitudeSource/coarse``), depending on the level of confidence ARKit has with the altitude
+ data that's available at the time.
*/
@property (nonatomic, readonly) ARAltitudeSource altitudeSource;
/**
- Initializes a new ARGeoAnchor with the given coordinates.
+ Initializes a new location anchor with the given coordinates.
- ARKit will query the ground level altitude during runtime, and populate the altitude as soon as that information becomes available.
+ Because this initializer does not take an altitude argument, ARKit sets the anchor's ``altitude`` to ground level.
- - Parameter coordinate: The coordinates.
-
- - Returns: An initialized geo anchor.
+ - Parameter coordinate: Latitude and longitude of the anchor's geographic location.
*/
- (instancetype)initWithCoordinate:(CLLocationCoordinate2D)coordinate NS_REFINED_FOR_SWIFT;
/**
- Initializes a new ARGeoAnchor with the given coordinates and altitude.
+ Initializes a location anchor with the given coordinate and altitude.
- Parameters:
- - coordinate: The coordinates.
- - altitude: Altitude in meters.
-
- - Returns: An initialized geo anchor.
+ - coordinate: Latitude and longitude of the anchor's geographic location.
+ - altitude: Vertical distance, in meters, between this anchor and sea level.
*/
- (instancetype)initWithCoordinate:(CLLocationCoordinate2D)coordinate altitude:(CLLocationDistance)altitude NS_REFINED_FOR_SWIFT;
/**
- Initializes a new named ARGeoAnchor with the given coordinates.
+ Initializes a named location anchor with the given coordinates.
- ARKit will query the ground level altitude during runtime, and populate the altitude as soon as that information becomes available.
+ Because this initializer does not take an altitude argument, ARKit sets the anchor's ``altitude`` to ground level.
- Parameters:
- name: Name of the anchor.
- - coordinate: The coordinates.
-
- - Returns: An initialized geo anchor.
+ - coordinate: Latitude and longitude of the anchor's geographic location.
*/
- (instancetype)initWithName:(NSString *)name coordinate:(CLLocationCoordinate2D)coordinate NS_REFINED_FOR_SWIFT API_UNAVAILABLE(visionos);
/**
- Initializes a new named ARGeoAnchor with the given coordinates and altitude.
+ Initializes a named location anchor with the given coordinate and altitude.
- Parameters:
- name: Name of the anchor.
- - coordinate: The coordinates.
- - altitude: Altitude in meters.
-
- - Returns: An initialized geo anchor.
+ - coordinate: Latitude and longitude of the anchor's geographic location.
+ - altitude: Vertical distance, in meters, between this anchor and sea level.
*/
- (instancetype)initWithName:(NSString *)name
coordinate:(CLLocationCoordinate2D)coordinate
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARGeoTrackingTypes.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARGeoTrackingTypes.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARGeoTrackingTypes.h 2026-08-15 23:02:19
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARGeoTrackingTypes.h 2026-10-04 02:32:28
@@ -13,112 +13,225 @@
API_UNAVAILABLE_BEGIN(visionos)
/**
- Keeps track of where an altitude value came from and informs the user about the expected accuracy.
+ Options for setting a location anchor's altitude.
+
+ Each altitude source has unique performance and accuracy characteristics.
*/
API_AVAILABLE(ios(14.0))
typedef NS_ENUM(NSInteger, ARAltitudeSource) {
- /** Altitude could not be determined (yet). */
+ /** Altitude isn't yet set. */
ARAltitudeSourceUnknown,
- /** ARKit determined altitude based on a coarse digital elevation model. The provided value is too imprecise to be used at close range, but is
- * sufficient to anchor far away content. */
+ /** The framework sets the altitude using a coarse digital-elevation model.
+
+ The accuracy of this altitude is noticeably imprecise at close range, but it's sufficient from far away. Use this option to save computational
+ resources for anchors that are far off in the distance. */
ARAltitudeSourceCoarse,
- /** ARKit determined altitude based on a high resolution digital elevation model. */
+ /** The framework sets the altitude using a high-resolution digital-elevation model. */
ARAltitudeSourcePrecise,
- /** Altitude was provided by the user. */
+ /** The app defines the altitude.
+
+ ARKit records this altitude source when your app defines a geo anchor's altitude.
+
+ You may acquire altitude by providing a particular scene coordinate to the session using
+ ``ARSession/getGeoLocation(forPoint:completionHandler:)``.
+
+ For example, your app might set a geo anchor's altitude by raycasting a surface, then adding an arbitrary `y-`amount to make the anchor more
+ visible from afar. */
ARAltitudeSourceUserDefined
} NS_SWIFT_NAME(ARGeoAnchor.AltitudeSource);
/**
- A value describing geo tracking state.
+ Values that are possible for the current state of geo tracking.
+
+ For any ``ARGeoTrackingStatus/state`` in a frame's ``ARFrame/geoTrackingStatus``, ARKit provides a ``ARGeoTrackingStatus/stateReason``. A given
+ geo tracking status may intermix states and reasons, so the reasons are not tied to specific states.
*/
API_AVAILABLE(ios(14.0))
typedef NS_ENUM(NSInteger, ARGeoTrackingState) {
- /** Geo tracking is not available. */
+ /** Geo tracking is not available.
+
+ This state occurs when ARKit doesn't have the landscape data necessary for visual localization at the user's location. For more information, see
+ ``ARGeoTrackingStatus/State/localizing``. */
ARGeoTrackingStateNotAvailable,
- /** Geo tracking is being initialized. */
+ /** The session is initializing geo tracking.
+
+ In this state, the session is preparing tracking and an app has the opportunity to onboard users to the experience. The app watches for changes
+ in ``ARGeoTrackingStatus/stateReason`` and coaches the user accordingly to expedite initialization. */
ARGeoTrackingStateInitializing,
- /** Geo tracking is attempting to localize against a Map. */
+ /** Geo tracking is attempting to localize against a map.
+
+ In this state, the session downloads localization imagery for the user's geographic location and compares it with captures from the device's
+ camera. This process is referred to as _visual localization_. When ARKit succeeds in matching this imagery with captures from the camera, the
+ state moves to ``ARGeoTrackingStatus/State/localized`` and the app is free to create location anchors. For more information about localization
+ imagery, see <doc:ARGeoTrackingConfiguration#Refine-the-users-position-with-imagery>.
+
+ ### Assisting the User with Visual Localization
+
+ To establish visual localization, the user must move the camera so it acquires the captures that ARKit needs. To elicit the right user movements
+ in this state, the app needs to advise the user to:
+
+ - Point the camera at buildings and other visual landmarks to help ARKit match the live camera data with its preexisting landscape-data.
+ - Avoid pointing the device at objects that are too general, like trees. It's better to focus on distinct visuals, like structures, or signs.
+ - Avoid pointing the device at real-world objects that are transient, like parked cars, or a construction site.
+ - Because lighting conditions can affect visual localization, avoid geo tracking at night. */
ARGeoTrackingStateLocalizing,
- /** Geo tracking is localized. */
+ /** Geo tracking is localized.
+
+ In this state, ARKit has completed visual localization and the app is free to place location anchors (``ARGeoAnchor``). */
ARGeoTrackingStateLocalized,
} NS_SWIFT_NAME(ARGeoTrackingStatus.State);
/**
- A value describing geo tracking accuracy.
+ Values that are possible for the current accuracy of geo tracking.
+
+ To ensure the best possible user experience, an app must monitor and react to the geo tracking accuracy. When accuracy is
+ ``ARGeoTrackingStatus/Accuracy/low``, the app needs to show content that's more forgiving if ARKit is off by a small distance. For example, if
+ accuracy is ``ARGeoTrackingStatus/Accuracy/low``, rendering a location anchor as a large ball several meters in the air is more appropriate than
+ rendering an arrow that rests its point on a real-world surface. Because a larger ball isn't meant to mark a precise location, any offset that
+ results from low accuracy will be less noticeable to the user.
+
+ Apps that need higher-precision location anchors need to wait for ``ARGeoTrackingStatus/Accuracy/medium`` or ``ARGeoTrackingStatus/Accuracy/high``
+ accuracy before revealing rendered location-anchors, or dismissing user instructions.
*/
API_AVAILABLE(ios(14.0))
typedef NS_ENUM(NSInteger, ARGeoTrackingAccuracy) {
- /** Geo tracking has not localized yet. Accuracy is indeterminate. */
+ /** Geo tracking accuracy is undetermined.
+
+ This value indicates that because the session has not completed visual localization, geo tracking accuracy is indeterminate. */
ARGeoTrackingAccuracyUndetermined,
- /** Localized with low accuracy. */
+ /** Geo tracking accuracy is low.
+
+ This value indicates that visual localization is complete and geo tracking accuracy is low.
+
+ One technique an app can use to deal with low accuracy is to render location anchors with an asset that's more forgiving, like a large ball. If
+ an app renders the ball further in the air, any offset that results from low accuracy will be less noticeable, and less critical to the user. */
ARGeoTrackingAccuracyLow,
- /** Localized with medium accuracy. */
+ /** Geo tracking accuracy is average.
+
+ This value indicates that visual localization is complete and geo tracking accuracy is average. */
ARGeoTrackingAccuracyMedium,
- /** Localized with high accuracy. */
+ /** Geo tracking accuracy is high.
+
+ This value indicates that visual localization is complete and geo tracking accuracy is very good. */
ARGeoTrackingAccuracyHigh
} NS_SWIFT_NAME(ARGeoTrackingStatus.Accuracy);
/**
- Reasons for geo tracking failure states.
+ The reasons that describe a geo tracking session's status.
+
+ These possible values of ``ARGeoTrackingStatus/stateReason`` provide more information about a geo tracking session's current
+ ``ARGeoTrackingStatus/state``.
*/
API_AVAILABLE(ios(14.0))
typedef NS_ENUM(NSInteger, ARGeoTrackingStateReason) {
- /** No issues reported. */
+ /** No issues reported.
+
+ This reason indicates that there is no user action currently needed to improve the geo tracking state. */
ARGeoTrackingStateReasonNone,
- /** Geo tracking is not available at the location. */
+ /** The location doesn't provide geo tracking.
+
+ This reason indicates that ARKit does not have the necessary landscape data to support geo tracking at the user's current location. See
+ ``ARGeoTrackingConfiguration/checkAvailability(completionHandler:)`` for more information.
+
+ If ``ARGeoTrackingConfiguration/checkAvailability(completionHandler:)`` returns <doc://com.apple.documentation/documentation/swift/true> and an
+ app begins a geo tracking session, ARKit provides this state reason when the user has moved to an unsupported area. */
ARGeoTrackingStateReasonNotAvailableAtLocation,
- /** Geo tracking needs location permissions from the user. */
+ /** The location requires user permission for geo tracking.
+
+ This reason indicates that the user has not given this app permission to access the user's location. To enable geo tracking, an app needs to ask
+ the user to enable location sharing for this app in Settings. */
ARGeoTrackingStateReasonNeedLocationPermissions,
- /** World tracking pose is not valid yet. */
+ /** The position or motion of the device makes geo tracking unstable.
+
+ This reason indicates that ARKit's local-space tracking is functioning at a limited capacity. To retrieve more information about the cause, an
+ app needs to refer to the camera's ``ARCamera/trackingState-9pgmq``. For the possible causes of this state, see ``ARTrackingState`` and
+ ``ARTrackingStateReason``. */
ARGeoTrackingStateReasonWorldTrackingUnstable,
- /** Waiting for a location point that meets accuracy threshold before starting geo tracking. */
+ /** A state in which the framework performs a check for the user's GPS position.
+
+ While in this state, the app needs to wait for the Core Location subsystem to provide the user's GPS location. Inform the user of the check in
+ progress; for instance, present a message alerting them to the geo tracking initialization process. */
ARGeoTrackingStateReasonWaitingForLocation,
- /** Waiting for availability check on first location point to complete. */
+ /** A state in which the framework performs a check for geo tracking availability at the user's location.
+
+ While in this state, the app waits for the geo tracking subsystem to determine geo tracking availability at the user's GPS location. Inform the
+ user of the check in progress; for instance, present a message alerting them to the geo tracking initialization process. */
ARGeoTrackingStateReasonWaitingForAvailabilityCheck,
- /** Geo tracking data hasn't been downloaded yet. */
+ /** A state in which the framework downloads localization imagery.
+
+ ARKit provides this reason in state ``ARGeoTrackingStatus/State/localizing`` when the session is actively attempting to download localization
+ imagery (see <doc:ARGeoTrackingConfiguration#Refine-the-users-position-with-imagery>).
+
+ If this state persists for too long, it may indicate a network issue. If a reasonable amount of time elapses in this state reason, the app may
+ consider requesting that the user check their internet connection. */
ARGeoTrackingStateReasonGeoDataNotLoaded,
- /** The device is pointed at an angle too far down to use geo tracking. */
+ /** The position of the device is too low for geo tracking.
+
+ ARKit provides the app with this reason when the app is in state ``ARGeoTrackingStatus/State/localizing`` and the device is not capturing enough
+ of the necessary live-camera imagery needed for visual localization because the user is pointing the camera too low. To resolve the issue, the
+ app needs to instruct the user to raise the device and follow the guidance in
+ <doc:ARGeoTrackingStatus/State/localizing#Assisting-the-User-with-Visual-Localization>. */
ARGeoTrackingStateReasonDevicePointedTooLow,
- /** Visual localization failed, but no errors were found in the input. */
+ /** Localization imagery failed to match the view from the device's camera.
+
+ ARKit provides this reason when visual localization is taking too long. This indicates that the app has met all requirements for geo tracking,
+ except for visual localization. In this situation, the app needs to ask the user to pan the device around the physical environment to acquire
+ more camera-feed imagery. For more information, see <doc:ARGeoTrackingStatus/State/localizing#Assisting-the-User-with-Visual-Localization>. */
ARGeoTrackingStateReasonVisualLocalizationFailed
} NS_SWIFT_NAME(ARGeoTrackingStatus.StateReason);
/**
- Collection of fields to give information on geo tracking status.
+ The state, accuracy, and reason that are possible for geo tracking's current condition.
+
+ Geo tracking requires coordination with the user at various phases of the geo tracking lifecycle. To elicit the right user actions, an app needs to
+ provide clear instructions to the user based on the current frame's ``ARFrame/geoTrackingStatus``:
+
+ - Geo tracking ``state`` most notably regards the important process in which ARKit acquires a better understanding of the user's geographic location
+ and orientation than is possible with GPS and the compass heading alone. See ``State/localizing`` for more information.
+ - Given a particular ``state``, the app needs to tailor its user messaging according to the ``stateReason``.
+ - An app may need to monitor ``accuracy`` closely if it requires high-precision localization.
*/
API_AVAILABLE(ios(14.0))
NS_SWIFT_SENDABLE
@interface ARGeoTrackingStatus : NSObject <NSCopying, NSSecureCoding>
/**
- The state of geo tracking.
+ A value that describes the session's current geo tracking state.
+
+ For any ``ARGeoTrackingStatus/state`` in a frame's ``ARFrame/geoTrackingStatus``, ARKit provides a ``ARGeoTrackingStatus/stateReason``. A given
+ geo tracking status may intermix states and reasons, so the reasons are not tied to specific states.
*/
@property (nonatomic, readonly) ARGeoTrackingState state;
/**
- The accuracy of geo tracking.
+ The accuracy of geo tracking at the time the session captured the frame.
+
+ ARKit populates this property after reaching ``ARGeoTrackingStatus/State/localized``. To ensure the best possible user experience, an app must
+ monitor and react to the geo tracking accuracy. For more information, see ``ARGeoTrackingStatus/Accuracy``.
*/
@property (nonatomic, readonly) ARGeoTrackingAccuracy accuracy;
/**
- Reason for geo tracking state.
+ The reasons for the app's geo tracking status.
+
+ These possible values provide more information about a geo tracking session's current ``state``.
*/
@property (nonatomic, readonly) ARGeoTrackingStateReason stateReason;
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARHitTestResult.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARHitTestResult.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARHitTestResult.h 2026-08-15 23:02:19
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARHitTestResult.h 2026-10-04 02:32:28
@@ -13,26 +13,125 @@
@class ARAnchor;
/**
- Option set of hit-test result types.
+ Possible types for specifying a hit-test search, or for the result of a hit-test search.
*/
API_DEPRECATED("Use raycasting", ios(11.0, 14.0))
typedef NS_OPTIONS(NSUInteger, ARHitTestResultType) {
- /** Result type from intersecting the nearest feature point. */
+ /**
+ A point on a surface detected by ARKit, but not part of any detected planes.
+
+ During a world-tracking AR session, ARKit builds a coarse point cloud representing its rough
+ understanding of the 3D world around the user (see ``ARFrame/rawFeaturePoints``). Individual
+ feature points represent parts of the camera image likely to be part of a real-world surface,
+ but not necessarily a planar surface.
+
+ When you search using this hit-test option, ARKit finds the feature point nearest to the
+ hit-test ray (the extension of the 2D hit-test point into 3D world space), then returns the
+ point on the ray nearest to that feature point.
+ */
ARHitTestResultTypeFeaturePoint = (1 << 0),
- /** Result type from intersecting a horizontal plane estimate, determined for the current frame. */
+ /**
+ A point on a real-world planar surface detected during the search, whose orientation is
+ perpendicular to gravity.
+
+ ARKit provides two ways to locate real-world flat surfaces in a scene. _Plane detection_
+ (enabled with ``ARWorldTrackingConfiguration/planeDetection`` on your session configuration) is
+ an ongoing process, continuously analyzing the scene to accurately map the position and extent
+ of any planes in view. Because plane detection takes time, you can fall back to _plane
+ estimation_ to get an instant, but less accurate, indication of whether a 2D point in the
+ camera image corresponds to a real-world flat surface.
+
+ Because plane detection results are more accurate than plane estimation results, ARKit prefers
+ the former when searching for both. If your hit-test search includes both
+ ``ARHitTestResult/ResultType/estimatedHorizontalPlane`` and one or more
+ ``ARHitTestResult/ResultType/existingPlane`` types, and the search finds any already detected
+ plane anchors, the search returns only the existing plane(s) and no estimated plane.
+
+ An estimated plane search returns at most one result—the best estimate for a horizontal plane
+ intersecting the hit-test ray.
+ */
ARHitTestResultTypeEstimatedHorizontalPlane = (1 << 1),
- /** Result type from intersecting a vertical plane estimate, determined for the current frame. */
+ /**
+ A point on a real-world planar surface detected during the search, whose orientation is
+ parallel to gravity.
+
+ ARKit provides two ways to locate real-world flat surfaces in a scene. _Plane detection_
+ (enabled with ``ARWorldTrackingConfiguration/planeDetection`` on your session configuration) is
+ an ongoing process, continuously analyzing the scene to accurately map the position and extent
+ of any planes in view. Because plane detection takes time, you can fall back to _plane
+ estimation_ to get an instant, but less accurate, indication of whether a 2D point in the
+ camera image corresponds to a real-world flat surface.
+
+ Because plane detection results are more accurate than plane estimation results, ARKit prefers
+ the former when searching for both. If your hit-test search includes both
+ ``ARHitTestResult/ResultType/estimatedVerticalPlane`` and one or more
+ ``ARHitTestResult/ResultType/existingPlane`` types, and the search finds any already detected
+ plane anchors, the search returns only the existing plane(s) and no estimated plane.
+
+ An estimated plane search returns at most one result—the best estimate for a vertical plane
+ intersecting the hit-test ray.
+ */
ARHitTestResultTypeEstimatedVerticalPlane API_AVAILABLE(ios(11.3)) = (1 << 2),
- /** Result type from intersecting with an existing plane anchor. */
+ /**
+ A point on a real-world plane (already detected with the
+ ``ARWorldTrackingConfiguration/planeDetection`` option), without considering the plane's size.
+
+ When searching for this result type, ARKit can return any point coplanar with an already
+ detected plane, regardless of whether that plane's already detected ``ARPlaneAnchor/extent`` or
+ ``ARPlaneAnchor/geometry`` includes that point. (That is, this result type searches the infinite
+ extensions of detected planes.)
+
+ An existing plane search can return any number of results, depending on how many
+ already-detected planes the hit test ray intersects (if any).
+ */
ARHitTestResultTypeExistingPlane = (1 << 3),
- /** Result type from intersecting with an existing plane anchor, taking into account the plane’s extent. */
+ /**
+ A point on a real-world plane (already detected with the
+ ``ARWorldTrackingConfiguration/planeDetection`` option), respecting the plane's estimated size.
+
+ When searching for this result type, ARKit returns a point coplanar with an already detected
+ plane only if that point lies within the area defined by the plane's ``ARPlaneAnchor/center``
+ and ``ARPlaneAnchor/extent`` properties. Those properties (together with the anchor's
+ ``ARAnchor/transform``) define the smallest rectangular area that includes all regions ARKit
+ estimates to be a part of the plane.
+
+ However, that rectangular area may contain regions that are not part of the same real-world
+ surface. There may also be parts of the same real-world surface that lie outside the rectangle
+ because ARKit has not yet recognized them as part of the same plane. To get a more precise
+ result that follows the plane's actual shape, test with the
+ ``ARHitTestResult/ResultType/existingPlaneUsingGeometry`` type. To ignore the plane's estimated
+ size and treat it as an infinite plane, test with the
+ ``ARHitTestResult/ResultType/existingPlane`` type.
+
+ An existing plane search can return any number of results, depending on how many
+ already-detected planes the hit test ray intersects (if any).
+ */
ARHitTestResultTypeExistingPlaneUsingExtent = (1 << 4),
- /** Result type from intersecting with an existing plane anchor, taking into account the plane’s geometry. */
+ /**
+ A point on a real-world plane (already detected with the
+ ``ARWorldTrackingConfiguration/planeDetection`` option), respecting the plane's estimated size
+ and shape.
+
+ When searching for this result type, ARKit returns a point coplanar with an already detected
+ plane only if that point lies within the area defined by the plane's ``ARPlaneAnchor/geometry``.
+ That property (together with the anchor's ``ARAnchor/transform``) defines the smallest polygonal
+ area that includes all regions ARKit estimates to be a part of the plane.
+
+ Because that polygon is always convex, it may contain regions that are not part of the same
+ real-world surface. (It does, however, provide a more precise estimate than a bounding rectangle
+ provided by the ``ARHitTestResult/ResultType/existingPlaneUsingExtent`` type.) There may also be
+ parts of the same real-world surface that lie outside the polygon because ARKit has not yet
+ recognized them as part of the same plane. You extend your hit test to an infinite plane by
+ using the ``ARHitTestResult/ResultType/existingPlane`` type.
+
+ An existing plane search can return any number of results, depending on how many
+ already-detected planes the hit test ray intersects (if any).
+ */
ARHitTestResultTypeExistingPlaneUsingGeometry API_AVAILABLE(ios(11.3)) = (1 << 5),
} NS_SWIFT_NAME(ARHitTestResult.ResultType);
@@ -41,37 +140,77 @@
API_UNAVAILABLE_BEGIN(visionos)
/**
- A result of an intersection found during a hit-test.
+ Information about a real-world surface found by examining a point on the screen.
+
+ If you use SceneKit or SpriteKit as your renderer, you can search for real-world surfaces at a
+ screen point using:
+
+ - ``ARSCNView`` ``ARSCNView/hitTest(_:types:)``
+ - ``ARSKView`` ``ARSKView/hitTest(_:types:)``
+
+ Otherwise, you can search the camera image for real-world content using the ``ARFrame``
+ ``ARFrame/hitTest(_:types:)`` method. Because a frame is independent of a view, for this method you
+ pass a point specified in normalized image coordinates (where `(0,0)` is the top left corner of the
+ image and `(1,1)` is the lower right).
+
+ All these methods return an array of ``ARHitTestResult`` objects describing the content found. The
+ number and order of results in the array depends on the search types you specify and the order you
+ specify them in. For example, consider the code below:
+
+ ```swift
+ let results = view.hitTest(point, [.existingPlaneUsingGeometry, .estimatedHorizontalPlane])
+ ```
+
+ This ``ARSCNView/hitTest(_:types:)`` call searches first for plane anchors already present in the
+ session (according to the session configuration's ``ARWorldTrackingConfiguration/planeDetection``
+ settings); returning any such results (in order of distance from the camera) as the first elements
+ in the array. This call also (due to the ``ResultType/estimatedHorizontalPlane`` request) attempts
+ to determine whether the hit test ray intersects any horizontal surface not already found by plane
+ detection, and returns that result (if any) as the last element in the array.
*/
API_DEPRECATED("Use raycasting", ios(11.0, 14.0))
@interface ARHitTestResult : NSObject
/**
- The type of the hit-test result.
+ The kind of detected feature the search result represents.
+
+ You specify one or more result types to search for when calling a hit-testing method. A result
+ object has only one result type.
*/
@property (nonatomic, readonly) ARHitTestResultType type;
/**
- The distance from the camera to the intersection in meters.
+ The distance, in meters, from the camera to the detected surface.
*/
@property (nonatomic, readonly) CGFloat distance;
/**
- The transformation matrix that defines the intersection’s rotation, translation and scale
- relative to the anchor or nearest feature point.
+ The position and orientation of the result relative to the nearest anchor or feature point.
+
+ This transform matrix indicates the intersection point between the detected surface and the ray
+ that created the hit-test result. A hit-test projects a 2D point in the image or view coordinate
+ system along a ray into the 3D world space and reports results where that line intersects detected
+ surfaces.
*/
@property (nonatomic, readonly) simd_float4x4 localTransform;
/**
- The transformation matrix that defines the intersection’s rotation, translation and scale
- relative to the world.
+ The position and orientation of the result relative to the world coordinate system.
+
+ This transform matrix indicates the intersection point between the detected surface and the ray
+ that created the hit-test result. A hit-test projects a 2D point in the image or view coordinate
+ system along a ray into the 3D world space and reports results where that line intersects detected
+ surfaces.
+
+ The session configuration's ``ARConfiguration/worldAlignment`` property defines the world
+ coordinate system.
*/
@property (nonatomic, readonly) simd_float4x4 worldTransform;
/**
- The anchor that the hit-test intersected.
+ The anchor representing the detected surface, if any.
- An anchor will only be provided for existing plane result types.
+ ARKit provides an anchor only for existing-plane result types. Feature-point and estimated-plane results don't include an anchor.
*/
@property (nonatomic, strong, nullable, readonly) ARAnchor *anchor;
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARImageAnchor.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARImageAnchor.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARImageAnchor.h 2026-08-15 23:02:19
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARImageAnchor.h 2026-10-04 02:32:28
@@ -16,22 +16,38 @@
API_UNAVAILABLE_BEGIN(visionos)
/**
- An anchor representing an image in the world.
+ An anchor for a known image that ARKit detects in the physical environment.
+
+ When you run a world-tracking AR session and specify ``ARReferenceImage`` objects for the session configuration's
+ ``ARWorldTrackingConfiguration/detectionImages`` property, ARKit searches for those images in the real-world environment. When the session recognizes
+ an image, it automatically adds an ``ARImageAnchor`` for each detected image to its list of anchors.
+
+ To find the extent of a recognized image in the scene, use the inherited ``ARAnchor/transform`` property together with the
+ ``ARReferenceImage/physicalSize`` of the anchor's ``referenceImage``.
*/
API_AVAILABLE(ios(11.3))
NS_SWIFT_SENDABLE
@interface ARImageAnchor : ARAnchor <ARTrackable>
/**
- Reference to the detected image.
+ The detected image referenced by the image anchor.
+
+ This object is always one of the ``ARReferenceImage`` objects you provided in the ``ARWorldTrackingConfiguration/detectionImages`` array when
+ configuring the session.
*/
@property (nonatomic, strong, readonly) ARReferenceImage *referenceImage;
/**
- The factor between estimated physical size and provided size.
+ A factor between the initial size and the estimated physical size.
- This value will be estimated if `automaticImageScaleEstimationEnabled` is set to `true` on the `ARWorldTrackingConfiguration`. It is used to
- correct the transform's translation. Default value is `1.0`.
+ The default value is 1.0, which means that a version of this image that ARKit recognizes in the physical environment exactly matches its reference
+ image ``ARReferenceImage/physicalSize``. ARKit only estimates this value when you set
+ ``ARWorldTrackingConfiguration/automaticImageScaleEstimationEnabled`` to `true`; otherwise it remains 1.0.
+
+ ARKit automatically corrects the image anchor's transform when `estimatedScaleFactor` is a value other than 1.0. This adjustment, in turn,
+ corrects ARKit's understanding of where the image anchor is located in the physical environment.
+
+ See ``ARWorldTrackingConfiguration/automaticImageScaleEstimationEnabled``.
*/
@property (nonatomic, readonly) CGFloat estimatedScaleFactor API_AVAILABLE(ios(13.0));
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARLightEstimate.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARLightEstimate.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARLightEstimate.h 2026-08-15 23:02:19
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARLightEstimate.h 2026-10-04 02:32:28
@@ -15,23 +15,42 @@
API_UNAVAILABLE_BEGIN(visionos)
/**
- A light estimate representing the light in the scene.
+ Estimated scene lighting information associated with a captured video frame in an AR session.
+
+ If you enable the ``ARConfiguration/isLightEstimationEnabled`` setting, ARKit provides light estimates in the ``ARFrame/lightEstimate`` property of
+ each ``ARFrame`` it delivers.
+
+ If you render your own overlay graphics for the AR scene, you can use this information in shading algorithms to help make those graphics match the
+ real-world lighting conditions of the scene captured by the camera. The ``ARSCNView`` class automatically uses this information to configure SceneKit
+ lighting.
*/
API_AVAILABLE(ios(11.0))
NS_SWIFT_SENDABLE
@interface ARLightEstimate : NSObject
/**
- Ambient intensity of the lighting.
+ The estimated intensity, in lumens, of ambient light throughout the scene.
- In a well lit environment, this value is close to `1000`. It typically ranges from `0` (very dark) to around `2000` (very bright).
+ This value is based on the internal exposure compensation of the camera device, and scaled to be appropriate for use in rendering architectures that
+ use realistic lighting metrics. A value of 1000 represents "neutral" lighting, and the value typically ranges from 0 (very dark) to around 2000 (very
+ bright).
+
+ For example, you can pass this value directly to the <doc://com.apple.documentation/documentation/scenekit/scnlight/intensity> property of a SceneKit
+ ambient light for lighting results that roughly match those of the real-world scene captured by the device camera. (However, passing this value to
+ SceneKit is generally not necessary; the ``ARSCNView`` class automatically sets SceneKit lighting based on this value.)
*/
@property (nonatomic, readonly) CGFloat ambientIntensity;
/**
- The ambient color temperature of the lighting.
+ The estimated color temperature, in degrees Kelvin, of ambient light throughout the scene.
- This specifies the ambient color temperature of the lighting in Kelvin (`6500` corresponds to pure white).
+ This value is based on the internal white balance compensation of the camera device, and scaled to be appropriate for use in rendering architectures
+ that use realistic lighting metrics. A value of 6500 represents neutral (pure white) lighting; lower values indicate a "warmer" yellow or orange
+ tint, and higher values indicate a "cooler" blue tint.
+
+ For example, you can pass this value directly to the <doc://com.apple.documentation/documentation/scenekit/scnlight/temperature> property of a
+ SceneKit ambient light for lighting results that roughly match those of the real-world scene captured by the device camera. (However, passing this
+ value to SceneKit is generally not necessary; the ``ARSCNView`` class automatically sets SceneKit lighting based on this value.)
*/
@property (nonatomic, readonly) CGFloat ambientColorTemperature;
@@ -52,27 +71,61 @@
@end
/**
- A directional light estimate representing the light intensity and direction in the scene.
+ Estimated environmental lighting information associated with a captured video frame in a face-tracking AR session.
+
+ When you run a face tracking AR session (see ``ARFaceTrackingConfiguration``) with the ``ARConfiguration/isLightEstimationEnabled`` property set to
+ <doc://com.apple.documentation/documentation/swift/true>, ARKit uses the detected face as a light probe to estimate the directional lighting
+ environment in the scene. The ``ARFrame/lightEstimate`` property of each frame vended by the session contains an ``ARDirectionalLightEstimate``
+ instance containing this information.
+
+ If you render your own overlay graphics for the AR scene, you can use this information in shading algorithms to help make those graphics match the
+ real-world lighting conditions of the scene captured by the camera. (The ``ARSCNView`` class automatically uses this information to configure
+ SceneKit lighting.)
*/
API_AVAILABLE(ios(11.0))
NS_SWIFT_SENDABLE
@interface ARDirectionalLightEstimate : ARLightEstimate
/**
- Second degree spherical harmonics coefficients representing the intensity of light.
+ Data describing the estimated lighting environment in all directions.
- The data is an array of `27` 32-bit floating-point values, containing three non-interleaved data sets
- corresponding to the red, green, and blue sets of coefficients.
+ Spherical harmonics provide a compact mathematical model for the global lighting environment around a point in space, describing the distribution and
+ colors of multiple directional light sources. When used in a renderer that supports environment-based lighting, spherical harmonics provide much less
+ high-frequency detail than a cube map texture, but make much more efficient use of GPU resources.
+
+ ARKit provides second-level spherical harmonics in separate red, green, and blue data planes. Thus, this data buffer contains 3 sets of 9
+ coefficients, or a total of 27 values of 32-bit floating point type.
*/
@property (nonatomic, copy, readonly) NSData *sphericalHarmonicsCoefficients;
/**
- The primary direction of light.
+ A vector indicating the orientation of the strongest directional light source in the scene.
+
+ When ARKit analyzes the directional lighting environment for a detected face, the resulting lighting estimate can represent the influence of multiple
+ light sources with different directions and intensities. To access this level of detail for use in your custom rendering code, use the
+ ``ARDirectionalLightEstimate/sphericalHarmonicsCoefficients`` property.
+
+ If your app displays AR content using a technology that doesn't support environment-based lighting, this
+ ``ARDirectionalLightEstimate/primaryLightDirection`` property represents the average of directional light sources in the scene. This vector is
+ normalized and in world coordinate space.
*/
@property (nonatomic, readonly) simd_float3 primaryLightDirection;
/**
- The intensity of light in the primary direction.
+ The estimated intensity, in lumens, of the strongest directional light source in the scene.
+
+ When ARKit analyzes the directional lighting environment for a detected face, the resulting lighting estimate can represent the influence of multiple
+ light sources with different directions and intensities. To access this level of detail for use in your custom rendering code, use the
+ ``ARDirectionalLightEstimate/sphericalHarmonicsCoefficients`` property.
+
+ If your app displays AR content using a technology that doesn't support environment-based lighting, this
+ ``ARDirectionalLightEstimate/primaryLightIntensity`` property represents the average of directional light sources in the scene. This value is scaled
+ to be appropriate for use in rendering architectures that use realistic lighting metrics, with a value of 1000 representing neutral lighting.
+
+ For example, you can pass this value directly to the <doc://com.apple.documentation/documentation/scenekit/scnlight/intensity> property of a SceneKit
+ directional light for lighting results that roughly match those of the real-world scene captured by the device camera. (However, passing this value
+ to SceneKit is generally not necessary; the ``ARSCNView`` class automatically sets SceneKit lighting based on the
+ ``ARDirectionalLightEstimate/sphericalHarmonicsCoefficients`` property.)
*/
@property (nonatomic, readonly) CGFloat primaryLightIntensity;
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARMatteGenerator.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARMatteGenerator.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARMatteGenerator.h 2026-08-15 23:02:18
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARMatteGenerator.h 2026-10-04 02:32:28
@@ -19,42 +19,45 @@
API_UNAVAILABLE_BEGIN(visionos)
/**
- The resolution at which the matte is to be generated.
+ A resolution for a matte texture.
- The matte generated per frame can be full resolution of the captured camera image or half resolution. The caller chooses one of the
- options from ARMatteResolution during initialization.
+ You generate a matte texture every frame, specifying whether its resolution is the full size or half of the camera image.
*/
API_AVAILABLE(ios(13.0))
typedef NS_ENUM(NSInteger, ARMatteResolution) {
- /* Matte generated at camera image resolution. */
+ /** An option that specifies the full camera image resolution. */
ARMatteResolutionFull = 0,
- /* Matte generated at half the camera image resolution. */
+ /** An option that specifies half of the camera image resolution. */
ARMatteResolutionHalf = 1
} NS_SWIFT_NAME(ARMatteGenerator.Resolution);
/**
- An object designed to generate either full resolution or half resolution matte given the ARFrame.
+ An object that creates matte textures you use to occlude your app's virtual content with people that ARKit recognizes in the camera feed.
- The caller initializes the object once and calls the alpha matte generation API for every `ARFrame` with the captured image and
- segmentation stencil.
+ Use this class when you want full control over occluding your app's virtual content, based on people ARKit recognizes in the camera feed.
+
+ > Note:
+ > Apps using one of the standard renderers (`ARView` or ``ARSCNView``) don't need this class to effect people occlusion. See
+ ``ARConfiguration/frameSemantics`` for more information.
+
+ To assist your custom renderer with people occlusion, matte generator processes alpha and depth information in a frame's
+ ``ARFrame/segmentationBuffer`` and ``ARFrame/estimatedDepthData`` to provide you with matte and depth textures. You use these textures to layer
+ people on top of your app's virtual content.
*/
API_AVAILABLE(ios(13.0))
@interface ARMatteGenerator : NSObject
/**
- Initializes an instance of ARMatteGenerator.
+ Creates an AR matte generator.
- For efficient creation of alpha mattes in real time it is recommended to instantiate this object only once and to generate an alpha matte
- for every incoming frame.
+ To create matte textures in real-time, create this object once and reuse it every frame.
- Parameters:
- device: The device the filter will run on.
- matteResolution: The resolution at which the matte is to be generated. Set using one of the values from 'ARMatteResolution'.
- - Returns: Instance of `ARMatteGenerator`.
-
- SeeAlso: ``ARFrame``
- SeeAlso: ``ARMatteGenerator/generateMatteFromFrame:commandBuffer:``
- SeeAlso: ``ARMatteResolution``
@@ -68,15 +71,15 @@
- frame: Current `ARFrame` containing camera image and segmentation stencil. The caller is to ensure that a valid segmentation buffer is present.
- commandBuffer: Metal command buffer for encoding matting related operations. The command buffer is committed by the caller externally.
- - Returns: Alpha matte `MTLTexture` for the given `ARFrame` at full resolution or half resolution as chosen by the caller during initialization.
+ - Returns: An alpha matte `MTLTexture` for the given `ARFrame` at the resolution you chose at initialization.
*/
- (id<MTLTexture>)generateMatteFromFrame:(ARFrame *)frame commandBuffer:(id<MTLCommandBuffer>)commandBuffer;
/**
Generates dilated depth at the resolution of the segmentation stencil.
- The caller can use depth information when compositing a virtual object with the captured scene. This API returns the dilated linear depth
- to the caller. The reprojection of this depth to the caller's scene space is carried out externally.
+ You use the linear depth information this function provides when compositing a virtual object with the camera image. The reprojection of this depth
+ to the caller's scene space is carried out externally.
- Parameters:
- frame: Current `ARFrame` containing camera image and estimated depth buffer. The caller is to ensure that a valid depth buffer is present.
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARMeshAnchor.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARMeshAnchor.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARMeshAnchor.h 2026-08-15 23:02:19
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARMeshAnchor.h 2026-10-04 02:32:28
@@ -14,15 +14,23 @@
@class ARMeshGeometry;
-/*
- An anchor representing a mesh in the world.
+/**
+ An anchor for a physical object that ARKit detects and recreates virtually using a polygonal mesh.
+
+ ARKit subdivides the reconstructed, real-world scene surrounding the user into mesh anchors.
+
+ Mesh anchors constantly update their data as ARKit refines its understanding of the real world. Although ARKit updates a mesh to reflect a change in
+ the physical environment (such as when a person pulls out a chair), the mesh's subsequent change is not intended to reflect in real time.
*/
API_AVAILABLE(ios(13.4))
NS_SWIFT_SENDABLE
@interface ARMeshAnchor : ARAnchor
/**
- Geometry of the mesh in anchor's coordinate system.
+ 3D information about the mesh such as its shape and classifications.
+
+ Contains the anchor's portion of mesh data that, with any other mesh anchors in the AR session, collectively reconstruct the scene around the user.
+ The mesh anchor records this data in its own coordinate system.
*/
@property (nonatomic, readonly) ARMeshGeometry *geometry;
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARMeshGeometry.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARMeshGeometry.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARMeshGeometry.h 2026-08-15 23:02:19
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARMeshGeometry.h 2026-10-04 02:32:28
@@ -14,39 +14,55 @@
API_UNAVAILABLE_BEGIN(visionos)
/**
- A container for vector data of a geometry.
+ Mesh data in a buffer-based array.
+
+ Mesh-anchor geometry (``ARMeshGeometry``) uses geometry sources to hold 3D data like vertices, and normals, in an efficient, array-like format. A
+ Metal buffer wraps the data, and other properties specify how to interpret that data.
+
+ In the case that ``componentsPerVector`` is greater than 1, the element type of the geometry-source array is itself a sequence (pairs, triplets, and
+ so on).
*/
API_AVAILABLE(ios(13.4))
NS_SWIFT_SENDABLE
@interface ARGeometrySource : NSObject <NSSecureCoding>
/**
- A Metal buffer containing per-vector data for the source.
+ A Metal buffer that contains a list of vectors.
+
+ Each vector in the buffer is of the type defined by ``ARGeometrySource/format``. Every vector may itself contain multiple scalars, defined by
+ ``ARGeometrySource/componentsPerVector``.
+
+ The buffer's <doc://com.apple.documentation/documentation/metal/mtlresource/storagemode> is
+ <doc://com.apple.documentation/documentation/metal/mtlstoragemode/shared> which allows it to be accessed on both, the CPU, and GPU.
*/
@property (nonatomic, strong, readonly) id<MTLBuffer> buffer;
/**
- The number of vectors in the source.
+ The number of vectors in the buffer.
*/
@property (nonatomic, assign, readonly) NSInteger count;
/**
- The type of per-vector data in the buffer.
+ The type of vector data in the buffer.
*/
@property (nonatomic, assign, readonly) MTLVertexFormat format;
/**
The number of scalar components in each vector.
+
+ In the case that ``ARGeometrySource/componentsPerVector`` is greater than 1, the element type of the geometry-source array is itself, a sequence.
*/
@property (nonatomic, assign, readonly) NSInteger componentsPerVector;
/**
- The offset (in bytes) from the beginning of the buffer.
+ The offset, in bytes, from the beginning of the buffer.
*/
@property (nonatomic, assign, readonly) NSInteger offset;
/**
- The number of bytes from a vector to the next one in the buffer.
+ The length, in bytes, of the start of one vector in the buffer to the start of the next vector.
+
+ Stride may contain padding, so it's not always equal to the vector-format's total size in bytes.
*/
@property (nonatomic, assign, readonly) NSInteger stride;
@@ -67,25 +83,40 @@
@end
/**
-The primitive that defines how vertices are connected.
+ The kind of connection between vertices.
+
+ When you enable ``ARWorldTrackingConfiguration/sceneReconstruction`` on a world-tracking configuration, ARKit provides a wireframe mesh that models
+ the shape of the real world using a collection of connected vertices. ARKit uses ``ARGeometryPrimitiveType`` to indicate how a particular property of
+ that mesh is interpreted. For example, a mesh geometry's ``ARMeshGeometry/faces`` property specifies that each face within the geometry is of type
+ ``triangle``.
*/
API_AVAILABLE(ios(13.4))
typedef NS_ENUM(NSInteger, ARGeometryPrimitiveType) {
- /// The geometry element is a sequence of line segments, where each line segment is described by two new vertices.
+ /** A line segment in which a line connects two vertices. */
ARGeometryPrimitiveTypeLine,
- /// The geometry element is a sequence of triangles, where each triangle is described by three new vertices.
+ /** Three vertices that connect to form a triangle. */
ARGeometryPrimitiveTypeTriangle
};
/**
- A container for index data describing how vertices connect to define a geometry.
+ A container for index data, such as vertex indices of a face.
+
+ ``ARMeshGeometry`` uses geometry-elements to store face data (see ``ARMeshGeometry/faces``). Each face is defined by the primitive type, for example,
+ ``ARGeometryPrimitiveType/triangle``.
+
+ To demonstrate, an ``ARMeshGeometry`` instance with two triangle-type faces results in the following configuration:
+
+ - `faces` ``count`` `= 2`
+ - `faces` ``indexCountPerPrimitive`` `= 3` (because ``primitiveType`` is ``ARGeometryPrimitiveType/triangle``)
+ - `faces` ``bytesPerIndex`` `= 4` (because vertex indices are the type <doc://com.apple.documentation/documentation/swift/uint32>)
+ - The buffer's total size in bytes `=` ``count`` `*` ``indexCountPerPrimitive`` `*` ``bytesPerIndex`` (which in this case, is `2 * 3 * 4 = 24` bytes)
*/
API_AVAILABLE(ios(13.4))
NS_SWIFT_SENDABLE
@interface ARGeometryElement : NSObject <NSSecureCoding>
/**
- A Metal buffer containing index data that defines the geometry.
+ A Metal buffer containing primitive data.
*/
@property (nonatomic, strong, readonly) id<MTLBuffer> buffer;
@@ -95,21 +126,20 @@
@property (nonatomic, assign, readonly) NSInteger count;
/**
- The number of bytes that represent an index value.
+ The number of bytes for each index.
*/
@property (nonatomic, assign, readonly) NSInteger bytesPerIndex;
/**
The number of indices for each primitive.
- This is based on the primitiveType. For `ARGeometryPrimitiveTypeTriangle` the value is `3`.
-
- - SeeAlso: ``ARGeometryPrimitiveType``
+ The value of this property relates to the ``ARGeometryElement/primitiveType``. For ``ARGeometryPrimitiveType/triangle``, the value is 3. For more
+ information, see ``ARGeometryPrimitiveType``.
*/
@property (nonatomic, assign, readonly) NSInteger indexCountPerPrimitive;
/**
- The type of the geometry element.
+ The geometry's type of data (triangle, or line).
*/
@property (nonatomic, assign, readonly) ARGeometryPrimitiveType primitiveType;
@@ -130,22 +160,41 @@
@end
/**
- A value describing the classification of a mesh face.
+ Enumeration of different classes of real-world objects that ARKit can identify.
+
+ When you enable ``ARWorldTrackingConfiguration/sceneReconstruction`` on a world-tracking configuration, ARKit provides several mesh anchors
+ (``ARMeshAnchor``) that collectively estimate the shape of the physical environment. Within that model of the real world, ARKit may identify specific
+ objects, like seats, windows, tables, or walls. ARKit shares that information by exposing one or more ``ARMeshClassification`` instances in a mesh's
+ ``ARMeshAnchor/geometry`` property.
+
+ For a sample app that demonstrates mesh classification, see <doc:visualizing-and-interacting-with-a-reconstructed-scene>.
*/
API_AVAILABLE(ios(13.4))
typedef NS_ENUM(NSInteger, ARMeshClassification) {
+ /** A face ARKit can't classify. */
ARMeshClassificationNone = 0,
+ /** The face is a part of a real-world wall. */
ARMeshClassificationWall,
+ /** The face is a part of a real-world floor. */
ARMeshClassificationFloor,
+ /** The face is a part of a real-world ceiling. */
ARMeshClassificationCeiling,
+ /** The face is a part of a real-world table. */
ARMeshClassificationTable,
+ /** The face is a part of a real-world seat. */
ARMeshClassificationSeat,
+ /** The face is a part of a real-world window. */
ARMeshClassificationWindow,
+ /** The face is a part of a real-world door. */
ARMeshClassificationDoor,
};
/**
-A three-dimensional shape that represents the geometry of a mesh.
+ Mesh information stored in an efficient, array-based format.
+
+ The information in this class holds the geometry data for a single anchor of the scene mesh. Each vertex in the anchor's mesh represents one
+ connection point. Every three-vertex combination forms a unique triangle called a _face_. Each face includes an outside-directional normal and a
+ ``classification``. If ARKit cannot classify a particular face, the value is `0` — the raw value for ``ARMeshClassification/none``.
*/
API_AVAILABLE(ios(13.4))
NS_SWIFT_SENDABLE
@@ -153,21 +202,76 @@
/**
The vertices of the mesh.
+
+ The ``ARGeometrySource/count`` equals the total number of vertices. Since each vertex is the type `SIMD3<Float>`,
+ ``ARGeometrySource/componentsPerVector`` is three.
+
+ The following code demonstrates retrieving a vertex at a particular index.
+
+ ```swift
+ extension ARMeshGeometry {
+ func vertex(at index: UInt32) -> SIMD3<Float> {
+ assert(vertices.format == MTLVertexFormat.float3, "Expected three floats (twelve bytes) per vertex.")
+ let vertexPointer = vertices.buffer.contents().advanced(by: vertices.offset + (vertices.stride * Int(index)))
+ let vertex = vertexPointer.assumingMemoryBound(to: SIMD3<Float>.self).pointee
+ return vertex
+ }
+ }
+ ```
*/
@property (nonatomic, strong, readonly) ARGeometrySource *vertices;
/**
- Normal of each vertex in the mesh.
+ Rays that define which direction is outside for each vertex.
*/
@property (nonatomic, strong, readonly) ARGeometrySource *normals;
/**
- A list of all faces in the mesh.
+ An object that contains a buffer of vertex indices of the geometry's faces.
+
+ Each element of the buffer-based array is a three-index combination that forms a unique triangle, or _face_. The index refers to that vertex's
+ position in the ``ARMeshGeometry/vertices`` array. The ``ARGeometryElement/count`` of this property represents the number of faces.
+
+ The following code demonstrates getting the vertices of a particular face:
+
+ ```swift
+ extension ARMeshGeometry {
+ func vertexIndicesOf(faceWithIndex index: Int) -> [Int] {
+ let indicesPerFace = faces.indexCountPerPrimitive
+ let facesPointer = faces.buffer.contents()
+ var vertexIndices = [Int]()
+ for offset in 0..<indicesPerFace {
+ let vertexIndexAddress = facesPointer.advanced(by: (index * indicesPerFace + offset) * MemoryLayout<UInt32>.size)
+ vertexIndices.append(Int(vertexIndexAddress.assumingMemoryBound(to: UInt32.self).pointee))
+ }
+ return vertexIndices
+ }
+ }
+ ```
*/
@property (nonatomic, strong, readonly) ARGeometryElement *faces;
/**
Classification for each face in the mesh.
+
+ Each element of the array is a face classification value (``ARMeshClassification``) that corresponds to one face in the geometry. The
+ ``ARGeometrySource/count`` of this property represents the number of faces in the geometry. The default value at each index is `0` — the raw value
+ for ``ARMeshClassification/none``.
+
+ The following code demonstrates retrieving a classification for a particular face:
+
+ ```swift
+ extension ARMeshGeometry {
+ func classificationOf(faceWithIndex index: Int) -> ARMeshClassification {
+ guard let classification = classification else { return .none }
+ let classificationAddress = classification.buffer.contents().advanced(by: index)
+ let classificationValue = Int(classificationAddress.assumingMemoryBound(to: UInt8.self).pointee)
+ return ARMeshClassification(rawValue: classificationValue) ?? .none
+ }
+ }
+ ```
+
+ For a sample app that demonstrates classification, see <doc:visualizing-and-interacting-with-a-reconstructed-scene>.
*/
@property (nonatomic, strong, readonly, nullable) ARGeometrySource *classification;
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARObjectAnchor.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARObjectAnchor.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARObjectAnchor.h 2026-08-15 23:02:19
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARObjectAnchor.h 2026-10-04 02:32:29
@@ -42,7 +42,11 @@
@interface ARObjectAnchor : ARAnchor <ARTrackable>
/**
- Reference to the detected object.
+ The detected object referenced by the object anchor.
+
+ This object is always one of the ``ARReferenceObject`` objects you provided in
+ the ``ARWorldTrackingConfiguration/detectionObjects`` array when configuring the
+ session.
*/
@property (nonatomic, strong, readonly) ARReferenceObject *referenceObject;
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARParticipantAnchor.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARParticipantAnchor.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARParticipantAnchor.h 2026-08-15 23:02:19
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARParticipantAnchor.h 2026-10-04 02:32:29
@@ -13,10 +13,11 @@
API_UNAVAILABLE_BEGIN(visionos)
/**
- This anchor represents the physical position and orientation of another participant in the collaborative session.
+ An anchor for another user in multiuser augmented reality experiences.
- The participant anchors are automatically added to the `ARSession` and are updated with each frame.
- The participant can be identified by `sessionIdentifier` property of the anchor.
+ When you set ``ARWorldTrackingConfiguration/isCollaborationEnabled`` to true, ARKit calls ``ARSessionDelegate/session(_:didAdd:)`` with an
+ ``ARParticipantAnchor`` for every user it detects in your physical environment, providing you with their world position. Identify the participant by
+ the anchor's ``ARAnchor/sessionIdentifier`` property.
*/
API_AVAILABLE(ios(13.0))
NS_SWIFT_SENDABLE
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARPlaneAnchor.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARPlaneAnchor.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARPlaneAnchor.h 2026-08-15 23:02:19
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARPlaneAnchor.h 2026-10-04 02:32:28
@@ -15,118 +15,301 @@
@class ARPlaneGeometry;
/**
- A value describing the alignment of a plane anchor.
+ The kinds of alignment — horizontal or vertical — that a plane anchor can have.
*/
API_AVAILABLE(ios(11.0))
typedef NS_ENUM(NSInteger, ARPlaneAnchorAlignment) {
- /** A plane that is horizontal with respect to gravity. */
+ /**
+ The plane is perpendicular to gravity.
+
+ The ``ARAnchor/transform`` property for a horizontal plane anchor includes no rotation about the x- or z-axis. Thus, using this anchor's
+ transform to place a 3D model asset in your scene results in the model appearing "right side up".
+ */
ARPlaneAnchorAlignmentHorizontal,
- /** A plane that is vertical with respect to gravity. */
+ /**
+ The plane is parallel to gravity.
+
+ The ``ARAnchor/transform`` property for a vertical plane anchor includes a rotation component. That is, the transform matrix represents the
+ result of rotating a horizontal plane to match the orientation of the detected surface.
+ */
ARPlaneAnchorAlignmentVertical API_AVAILABLE(ios(11.3)),
} NS_SWIFT_NAME(ARPlaneAnchor.Alignment);
/**
- A value describing the classification status of a plane anchor.
+ Possible states of ARKit's process for classifying plane anchors.
+
+ You get values of this type from a plane anchor's ``ARPlaneAnchor/classificationStatus`` property, describing the state of ARKit's plane
+ classification process.
*/
API_AVAILABLE(ios(12.0))
typedef NS_ENUM(NSInteger, ARPlaneClassificationStatus) {
- /** Plane classification is currently unavailable. */
+ /**
+ ARKit cannot currently provide plane classification information.
+
+ Plane classification is available on iOS devices with an A12 Bionic chip or later. On other devices, all plane anchors always indicate a
+ classification status of ``ARPlaneClassificationStatus/ARPlaneClassificationStatusNotAvailable``.
+
+ A classification status of ``ARPlaneClassificationStatus/ARPlaneClassificationStatusNotAvailable`` can also occur if the plane classification
+ process is temporarily unavailable.
+ */
ARPlaneClassificationStatusNotAvailable = 0,
- /** ARKit has not yet determined the classification of this plane. */
+ /**
+ ARKit has not yet produced a classification for the plane anchor.
+
+ This status occurs when ARKit is still in the process of plane classification. To be notified when ARKit produces a classification, observe the
+ same plane anchor in a later frame (for example, in the ``ARSessionDelegate/session(_:didUpdate:)-3qtt8`` or
+ ``ARSCNViewDelegate/renderer(_:didUpdate:for:)`` delegate method).
+ */
ARPlaneClassificationStatusUndetermined,
- /** ARKit is confident the plane is not any of the known classes. */
+ /**
+ ARKit has completed its classification process for the plane anchor, but the result is inconclusive.
+
+ ARKit attempts to classify detected planes using a finite set of common categories. However, a detected plane may not be a real object fitting
+ any of those categories, or the plane classification process may not be able to recognize it. In such cases, the plane anchor's
+ ``ARPlaneAnchor/classification-2hi2p`` is ``ARPlaneClassification/ARPlaneClassificationNone`` and its ``ARPlaneAnchor/classificationStatus`` is
+ ``ARPlaneClassificationStatus/ARPlaneClassificationStatusUnknown``.
+ */
ARPlaneClassificationStatusUnknown,
- /** ARKit has a classification for the plane it is confident in. */
+ /**
+ ARKit has completed its classification process for the plane anchor.
+
+ See the ``ARPlaneAnchor/classification-2hi2p`` property to identify the detected surface.
+ */
ARPlaneClassificationStatusKnown
} NS_REFINED_FOR_SWIFT;
/**
- A value describing the classification of a plane anchor.
+ Possible characterizations of real-world surfaces represented by plane anchors.
+
+ You get values of this type from a plane anchor's ``ARPlaneAnchor/classification-2hi2p`` property, identifying the likely type of real-world surface
+ for a detected plane anchor.
*/
API_AVAILABLE(ios(12.0))
typedef NS_ENUM(NSInteger, ARPlaneClassification) {
- /** The classification is not any of the known classes. */
+ /**
+ No classification is available for the plane anchor.
+
+ When a plane anchor has no classification, the ``ARPlaneAnchor/classificationStatus`` property indicates the reason: the classification process
+ might be unavailable or incomplete, or ARKit may not have been able to conclusively identify the plane.
+ */
ARPlaneClassificationNone = 0,
+ /** The plane anchor represents a real-world wall or similar large vertical surface. */
ARPlaneClassificationWall,
+ /** The plane anchor represents a real-world floor, ground plane, or similar large horizontal surface. */
ARPlaneClassificationFloor,
+ /** The plane anchor represents a real-world ceiling or similar overhead horizontal surface. */
ARPlaneClassificationCeiling,
+ /** The plane anchor represents a real-world table, desk, bar, or similar flat surface. */
ARPlaneClassificationTable,
+ /** The plane anchor represents a real-world chair, stool, bench or similar flat surface. */
ARPlaneClassificationSeat,
+ /** The plane anchor fits the description of a real-world window. */
ARPlaneClassificationWindow,
+ /** The plane anchor represents a real-world door, or similar archway. */
ARPlaneClassificationDoor
} NS_REFINED_FOR_SWIFT;
/**
- Represents the extents of a plane.
+ The size and y-axis rotation of a detected plane.
+
+ A plane anchor (``ARPlaneAnchor``) describes its size and orientation on the y-axis using the ``ARPlaneAnchor/planeExtent`` property of this type.
+
+ At runtime, ARKit continually updates the anchor's width and height as the framework refines its knowledge of the plane's shape in the environment.
+
+ Similarly, as the session runs, the framework may update the plane's y-rotation to better fit its rectangular area in the environment. In iOS 15 and
+ earlier, the framework rotates the plane anchor according to that angle. In iOS 16, the framework doesn't rotate the anchor automatically and its
+ transform matrix remains unchanged. Instead, the framework exposes the angle ``rotationOnYAxis`` that you apply to any plane extent geometry in your
+ app.
+
+ > Important:
+ > Apps that run on iOS 16 with a deployment target less than iOS 16 preserve the prior y-axis rotation behavior.
+
+ ### Size and Rotate an Entity to a Plane's Extent
+
+ The following code defines a RealityKit entity sized to the plane extent's width and height. The helper function also applies the extent's suggested
+ y-axis rotation by setting its transform `yaw` value to ``rotationOnYAxis``.
+
+ ```swift
+ func createPlane(for planeAnchor: ARPlaneAnchor, material: Material) -> ModelEntity {
+
+ // Get the plane's extent.
+ let extent = planeAnchor.planeExtent
+
+ // Create a model entity sized to the plane's extent.
+ let planeEntity = ModelEntity(mesh: .generatePlane (width: extent.width, depth: extent.height),
+ materials: [material])
+
+ // Orient the entity according to the extent's y-axis rotation.
+ planeEntity.transform = Transform(pitch: 0, yaw: extent.rotationOnYAxis, roll: 0)
+
+ // Center the entity on the plane.
+ planeEntity.transform.translation = planeAnchor.center
+
+ return planeEntity
+ }
+ ```
*/
API_AVAILABLE(ios(16.0))
NS_SWIFT_SENDABLE
@interface ARPlaneExtent : NSObject <NSSecureCoding>
/**
- The rotation angle in radians of the extents around the y-axis in the anchor’s coordinate space.
+ A radian value that indicates a plane's y-axis orientation.
+
+ As the session runs, the framework may update the plane's y-rotation to better fit its rectangular area in the environment. In iOS 15 and earlier,
+ the framework rotates the plane anchor according to that angle. In iOS 16, the framework doesn't rotate the anchor automatically and its transform
+ matrix remains unchanged. Instead, the framework exposes the angle in ``ARPlaneExtent/rotationOnYAxis`` that you apply to any plane extent geometry
+ in your app.
+
+ > Important:
+ > Apps that run on iOS 16 with a deployment target less than iOS 16 preserve the prior y-axis rotation behavior.
*/
@property (nonatomic, readonly) float rotationOnYAxis;
/**
- The width of the plane. Corresponds to the length of the plane along the x-axis prior to applying .rotationOnYAxis.
+ The estimated width of the plane.
+
+ This corresponds to the length of the plane along the x-axis, prior to applying `rotationOnYAxis`.
*/
@property (nonatomic, readonly) float width;
/**
- The height the plane. Corresponds to the length of the plane along the z-axis prior to applying .rotationOnYAxis.
+ The estimated height of the plane.
+
+ This corresponds to the length of the plane along the z-axis, prior to applying `rotationOnYAxis`.
*/
@property (nonatomic, readonly) float height;
@end
/**
- An anchor representing a planar surface in the world.
+ An anchor for a 2D planar surface that ARKit detects in the physical environment.
- Planes are defined in the X and Z direction, where Y is the surface’s normal.
+ When you enable ``ARWorldTrackingConfiguration/planeDetection`` in a world tracking session, ARKit notifies your app of all the surfaces it observes
+ using the device's back camera. ARKit calls your delegate's ``ARSessionDelegate/session(_:didAdd:)`` with an ``ARPlaneAnchor`` for each unique
+ surface. Each plane anchor provides details about the surface, like its real-world position and shape.
+
+ The width and length of a plane (the ``planeExtent``) span the xz-plane of an ``ARPlaneAnchor`` instance's local coordinate system. The y-axis of the
+ plane anchor is the plane's normal vector.
*/
API_AVAILABLE(ios(11.0))
NS_SWIFT_SENDABLE
@interface ARPlaneAnchor : ARAnchor
/**
- Determines whether plane classification is supported on this device.
+ A Boolean value that indicates whether plane classification is available on the current device.
+
+ Plane classification is available on iOS devices with an A12 Bionic chip or later.
+
+ On devices without plane classification support, all plane anchors report a ``ARPlaneAnchor/classification-2hi2p`` value of
+ ``ARPlaneClassification/ARPlaneClassificationNone`` and a ``ARPlaneAnchor/classificationStatus`` value of
+ ``ARPlaneClassificationStatus/ARPlaneClassificationStatusNotAvailable``.
*/
@property (class, nonatomic, readonly, getter=isClassificationSupported) BOOL classificationSupported API_AVAILABLE(ios(12.0));
/**
- The alignment of the plane.
+ The general orientation of the detected plane with respect to gravity.
*/
@property (nonatomic, readonly) ARPlaneAnchorAlignment alignment;
/**
- The center of the plane in the anchor’s coordinate space.
+ The center point of the plane relative to its anchor position.
+
+ When ARKit first detects a plane, the resulting ``ARPlaneAnchor`` object has a ``ARPlaneAnchor/center`` value of `(0,0,0)`, indicating that the
+ translation portion of the anchor's ``ARAnchor/transform`` value locates the plane's center point.
+
+ As scene analysis and plane detection continues, ARKit may determine that a previously detected plane anchor is part of a larger real-world surface,
+ increasing the ``ARPlaneAnchor/extent`` width and length values. The plane's new boundaries may not be symmetric around its initial position, so the
+ ``ARPlaneAnchor/center`` point changes relative to the anchor's (unchanged) ``ARAnchor/transform`` matrix.
+
+ Although the type of this property is <doc://com.apple.documentation/documentation/simd/vector_float3>, a plane anchor is always two-dimensional, and
+ is always positioned in only the x and z directions relative to its ``ARAnchor/transform`` position. (That is, the y-component of this vector is
+ always zero.)
*/
@property (nonatomic, readonly) simd_float3 center;
/**
- The extent of the plane in the anchor’s coordinate space.
+ The estimated width and length of the detected plane.
+
+ > Warning:
+ > In iOS 16, use ``ARPlaneAnchor/planeExtent`` instead.
+
+ The framework sets the x and z components to the width and length of the plane, respectively. The y-component is unused, with a constant value of
+ `0`.
*/
@property (nonatomic, readonly) simd_float3 extent API_DEPRECATED_WITH_REPLACEMENT("planeExtent", ios(11.0, 16.0));
/**
- The extent of the plane in the anchor’s coordinate space.
+ The estimated width, length, and y-axis rotation of the detected plane.
+
+ When ARKit first detects a plane, the resulting ``ARPlaneAnchor`` object has a ``ARPlaneAnchor/center`` value of `(0,0,0)`, indicating that the
+ translation portion of the anchor's ``ARAnchor/transform`` value locates the plane's center point.
+
+ As the session runs, ARKit may determine that a previously detected plane anchor is part of a larger real-world surface, increasing the
+ ``ARPlaneAnchor/planeExtent`` width and height values. The plane's new boundaries may not be symmetric around its initial position, so the
+ ``ARPlaneAnchor/center`` point changes relative to the anchor's unchanged ``ARAnchor/transform`` matrix.
+
+ Similarly, as the session runs, the framework may update the plane's y-rotation to better fit its rectangular area in the environment. In iOS 15 and
+ earlier, the framework rotates the plane anchor according to that angle. In iOS 16, the framework doesn't rotate the anchor automatically and its
+ transform matrix remains unchanged. Instead, the framework exposes the angle in ``ARPlaneExtent/rotationOnYAxis`` that you apply to any plane extent
+ geometry in your app.
+
+ > Important:
+ > Apps that run on iOS 16 with a deployment target less than iOS 16 preserve the prior y-axis rotation behavior.
*/
@property (nonatomic, readonly) ARPlaneExtent *planeExtent API_AVAILABLE(ios(16.0));
/**
- Geometry of the plane in the anchor's coordinate space.
+ A coarse triangle mesh representing the general shape of the detected plane.
+
+ This mesh provides vertex, index, and texture coordinate buffers describing the estimated 2D footprint of the plane.
+
+ You can visualize the plane geometry by passing these buffers to your preferred rendering engine. To visualize a plane geometry using SceneKit,
+ create an ``ARSCNPlaneGeometry`` instance and use its ``ARSCNPlaneGeometry/update(from:)`` method to update it to match the plane geometry.
*/
@property (nonatomic, strong, readonly) ARPlaneGeometry *geometry API_AVAILABLE(ios(11.3));
/**
- Classification status of the plane.
+ The current state of ARKit's process for classifying the plane anchor.
+
+ On supported devices, ARKit automatically attempts to characterize each detected plane, describing it as a real-world surface such as a wall, floor,
+ or table. You can then use this information to enhance the realism of your AR experience; for example, by placing certain virtual content only on
+ floors.
+
+ When this property's value is ``ARPlaneClassificationStatus/ARPlaneClassificationStatusKnown``, the ``ARPlaneAnchor/classification-2hi2p`` property
+ represents ARKit's characterization of the real-world surface corresponding to the plane anchor.
+
+ Plane classification can take longer than plane detection, and ARKit reports classifications only for planes where it has a high confidence in the
+ result, so you can use other values of this property to keep track of ARKit's classification process:
+
+ - If ARKit is still working to classify a plane, the classification is ``ARPlaneClassification/ARPlaneClassificationNone`` and the status is
+ ``ARPlaneClassificationStatus/ARPlaneClassificationStatusUndetermined``.
+ - If ARKit cannot characterize a plane with high confidence, the classification is ``ARPlaneClassification/ARPlaneClassificationNone`` and the status
+ is ``ARPlaneClassificationStatus/ARPlaneClassificationStatusUnknown``.
+
+ Plane classification is available on iOS devices with an A12 Bionic chip or later. Before using classification results, check the
+ ``ARPlaneAnchor/isClassificationSupported`` class property to make sure you're on a supported device.
*/
@property (nonatomic, assign, readonly) ARPlaneClassificationStatus classificationStatus API_AVAILABLE(ios(12.0)) NS_REFINED_FOR_SWIFT;
/**
- Classification of the plane.
+ A general characterization of what kind of real-world surface the plane anchor represents.
+
+ On supported devices, ARKit automatically attempts to characterize each detected plane, describing it as a real-world surface such as a wall, floor,
+ or table. You can then use this information to enhance the realism of your AR experience; for example, by placing certain virtual content only on
+ floors.
+
+ Plane classification can take longer than plane detection, and ARKit reports classifications only for planes where it has a high confidence in the
+ result. Use this property together with the ``ARPlaneAnchor/classificationStatus`` property to keep track of ARKit's classification process:
+
+ - If ARKit is still working to classify a plane, the classification is ``ARPlaneClassification/ARPlaneClassificationNone`` and the status is
+ ``ARPlaneClassificationStatus/ARPlaneClassificationStatusUndetermined``.
+ - If ARKit cannot characterize a plane with high confidence, the classification is ``ARPlaneClassification/ARPlaneClassificationNone`` and the status
+ is ``ARPlaneClassificationStatus/ARPlaneClassificationStatusUnknown``.
+
+ Plane classification is available on iOS devices with an A12 Bionic chip or later. Before using classification results, check the
+ ``ARPlaneAnchor/isClassificationSupported`` class property to make sure you're on a supported device.
*/
@property (nonatomic, assign, readonly) ARPlaneClassification classification API_AVAILABLE(ios(12.0)) NS_REFINED_FOR_SWIFT;
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARPlaneDetectionTypes.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARPlaneDetectionTypes.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARPlaneDetectionTypes.h 2026-08-15 23:02:19
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARPlaneDetectionTypes.h 2026-10-04 02:32:29
@@ -15,7 +15,7 @@
*/
API_AVAILABLE(ios(11.0))
typedef NS_OPTIONS(NSUInteger, ARPlaneDetection) {
- /** No plane detection is run. */
+ /** Plane detection is disabled. */
ARPlaneDetectionNone = 0,
/** Plane detection determines horizontal planes in the scene. */
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARPlaneGeometry.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARPlaneGeometry.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARPlaneGeometry.h 2026-08-15 23:02:18
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARPlaneGeometry.h 2026-10-04 02:32:28
@@ -16,52 +16,95 @@
API_UNAVAILABLE_BEGIN(visionos)
/**
- Object representing the geometry of a plane.
+ A 3D mesh describing the shape of a detected plane in world-tracking AR sessions.
- The plane geometry will have a growing number of triangles
- and vertices updated from frame to frame.
+ This class provides the estimated general shape of a detected plane, in the form of a detailed 3D mesh appropriate for use with various rendering
+ technologies or for exporting 3D assets. (For a quick way to visualize a plane geometry using SceneKit, see the ``ARSCNPlaneGeometry`` class.)
+
+ Unlike the ``ARPlaneAnchor`` ``ARPlaneAnchor/center`` and ``ARPlaneAnchor/planeExtent`` properties, which estimate only a rectangular area for a
+ detected plane, a plane anchor's ``ARPlaneAnchor/geometry`` property provides a more detailed estimate of the 2D area covered by that plane. For
+ example, if ARKit detects a circular tabletop, the resulting ``ARPlaneGeometry`` objects roughly match the general shape of the table. As the session
+ continues to run, ARKit provides updated plane anchors whose associated geometry refines the estimated shape of the plane.
+
+ You can use this model to more precisely place 3D content that should appear only on a detected flat surface. For example, to ensure that virtual
+ objects don't fall off the edge of a table. You can also use this model to create occlusion geometry, which hides other virtual content behind the
+ detected surface in the camera image.
+
+ The shape of a plane geometry is always convex. That is, the boundary polygon for a plane geometry is a minimal convex hull enclosing all points that
+ ARKit recognizes or estimates are part of the plane.
*/
API_AVAILABLE(ios(11.3))
NS_SWIFT_SENDABLE
@interface ARPlaneGeometry : NSObject <NSSecureCoding>
/**
- The number of mesh vertices of the geometry.
+ The number of elements in the ``ARPlaneGeometry/vertices-3kgkm`` buffer.
*/
@property (nonatomic, readonly) NSUInteger vertexCount NS_REFINED_FOR_SWIFT;
/**
- The mesh vertices of the geometry.
+ A buffer of vertex positions for each point in the plane mesh.
+
+ Each `float3` value in this buffer represents the position of a vertex in the mesh. The owning plane anchor's ``ARAnchor/transform`` matrix defines
+ the coordinate system for these points.
+
+ The ``ARPlaneGeometry/vertexCount`` property provides the number of elements in the buffer.
+
+ This buffer, together with the ``ARPlaneGeometry/triangleIndices-1azi3`` buffer, describes a mesh covering the entire surface of the plane. Use this
+ mesh for purposes that involve the filled shape, such as rendering a solid 3D representation of the surface. If, instead, you only need to know the
+ outline of the shape, see the ``ARPlaneGeometry/boundaryVertices-6nbee`` property.
*/
@property (nonatomic, readonly) const simd_float3 *vertices NS_REFINED_FOR_SWIFT;
/**
- The number of texture coordinates of the geometry.
+ The number of elements in the ``ARPlaneGeometry/textureCoordinates-91pbc`` buffer.
*/
@property (nonatomic, readonly) NSUInteger textureCoordinateCount NS_REFINED_FOR_SWIFT;
/**
- The texture coordinates of the geometry.
+ A buffer of texture coordinate values for each point in the plane mesh.
+
+ Each `float2` value in this buffer represents the UV texture coordinates for the vertex at the corresponding index in the
+ ``ARPlaneGeometry/vertices-3kgkm`` buffer.
*/
@property (nonatomic, readonly) const simd_float2 *textureCoordinates NS_REFINED_FOR_SWIFT;
/**
- The number of triangles of the geometry.
+ The number of triangles described by the ``ARPlaneGeometry/triangleIndices-1azi3`` buffer.
+
+ Each set of three indices forms a triangle, so the number of indices in the ``ARPlaneGeometry/triangleIndices-1azi3`` buffer is three times the
+ ``ARPlaneGeometry/triangleCount`` value.
*/
@property (nonatomic, readonly) NSUInteger triangleCount;
/**
- The triangle indices of the geometry.
+ A buffer of indices describing the triangle mesh formed by the plane geometry's vertex data.
+
+ Each 16-bit integer value in this buffer represents an index into the ``ARPlaneGeometry/vertices-3kgkm`` and
+ ``ARPlaneGeometry/textureCoordinates-91pbc`` buffers. Each set of three indices identifies the vertices that form a single triangle in the mesh. You
+ can use this buffer as an index buffer for a triangle mesh in GPU-based rendering or to create 3D model asset files.
+
+ Each set of three indices forms a triangle, so the number of indices in the ``ARPlaneGeometry/triangleIndices-1azi3`` buffer is three times the
+ ``ARPlaneGeometry/triangleCount`` value.
*/
@property (nonatomic, readonly) const int16_t *triangleIndices NS_REFINED_FOR_SWIFT;
/**
- The number of boundary vertices of the geometry.
+ The number of elements in the ``ARPlaneGeometry/boundaryVertices-6nbee`` buffer.
*/
@property (nonatomic, readonly) NSUInteger boundaryVertexCount NS_REFINED_FOR_SWIFT;
/**
- The vertices of the geometry's outermost boundary.
+ A buffer of vertex positions for each point along the plane's boundary.
+
+ Each `float3` value in this buffer represents the position of a vertex along the boundary polygon of the estimated plane. The owning plane anchor's
+ ``ARAnchor/transform`` matrix defines the coordinate system for these points.
+
+ The ``ARPlaneGeometry/boundaryVertexCount`` property provides the number of elements in the buffer.
+
+ This buffer defines the boundary polygon of the plane. Use it for purposes that require only that polygon's definition, such as rendering an outline
+ of the plane's estimated shape or testing whether a point is inside the bounded region. If, instead, you need the filled shape (for example, to
+ render a solid 3D representation of the surface), see the ``ARPlaneGeometry/vertices-3kgkm`` property.
*/
@property (nonatomic, readonly) const simd_float3 *boundaryVertices NS_REFINED_FOR_SWIFT;
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARPointCloud.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARPointCloud.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARPointCloud.h 2026-08-15 23:02:19
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARPointCloud.h 2026-10-04 02:32:28
@@ -14,7 +14,10 @@
API_UNAVAILABLE_BEGIN(visionos)
/**
- A collection of 3D points representing features in the environment.
+ A collection of points in the world coordinate space of the AR session.
+
+ Use the ``ARFrame`` ``ARFrame/rawFeaturePoints`` property to obtain a point cloud representing intermediate results of the scene analysis ARKit uses
+ to perform world tracking.
*/
API_AVAILABLE(ios(11.0))
NS_SWIFT_SENDABLE
@@ -26,12 +29,14 @@
@property (nonatomic, readonly) NSUInteger count NS_REFINED_FOR_SWIFT;
/**
- The 3D points comprising the point cloud.
+ The list of detected points.
*/
@property (nonatomic, readonly) const simd_float3 *points NS_REFINED_FOR_SWIFT;
/**
- The 3D point identifiers comprising the point cloud.
+ A list of unique identifiers corresponding to detected feature points.
+
+ Each identifier in this list corresponds to the point vector at the same index in the ``ARPointCloud/points`` array.
*/
@property (nonatomic, readonly) const uint64_t *identifiers NS_REFINED_FOR_SWIFT;
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARRaycastQuery.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARRaycastQuery.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARRaycastQuery.h 2026-08-15 23:02:19
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARRaycastQuery.h 2026-10-04 02:32:28
@@ -14,78 +14,101 @@
API_UNAVAILABLE_BEGIN(visionos)
/**
- A value describing the target of a ray used for raycasting.
+ The types of surface you allow a raycast to intersect with.
+
+ The available target types are plane, infinite plane, and estimated plane.
*/
API_AVAILABLE(ios(13.0))
typedef NS_ENUM(NSInteger, ARRaycastTarget) {
- /** Ray's target is an already detected plane, considering the plane's estimated size and shape. */
+ /** A raycast target that requires a plane to have a definitive size and shape. */
ARRaycastTargetExistingPlaneGeometry,
- /** Ray's target is an already detected plane, without considering the plane's size. */
+ /** A raycast target that specifies a detected plane, regardless of its size and shape. */
ARRaycastTargetExistingPlaneInfinite,
/**
- Ray's target is a plane that is estimated using the feature points around the ray.
- When alignment is ARRaycastTargetAlignmentAny, alignment of estimated planes is based on the normal of the real world
- surface corresponding to the estimated plane.
+ A raycast target that specifies nonplanar surfaces, or planes about which ARKit can only estimate.
+
+ A raycast with this target intersects feature points around the ray that ARKit estimates may be a real-world surface.
+
+ When combined with ``ARRaycastQuery/TargetAlignment/any``, ARKit bases estimated plane alignment on the normal of the surface.
+
+ When you set your world-tracking configuration's ``ARWorldTrackingConfiguration/sceneReconstruction`` to one of the `mesh` options, ARKit allows
+ a raycast with this target (and target-alignment ``ARRaycastQuery/TargetAlignment/any``) to intersect the scene mesh. Then the raycast result can
+ include points even on nonplanar surfaces or surfaces that have few or no features, such as a white wall. If you set
+ ``ARWorldTrackingConfiguration/sceneReconstruction`` to ``ARSceneReconstruction/ARSceneReconstructionNone``, raycasts ignore the scene mesh.
*/
ARRaycastTargetEstimatedPlane,
} NS_SWIFT_NAME(ARRaycastQuery.Target);
/**
- A value describing the alignment of a target.
+ A specification that indicates a target's alignment with respect to gravity.
+
+ A raycast ignores potential targets with an alignment different than the one you specify in the raycast query.
*/
API_AVAILABLE(ios(13.0))
typedef NS_ENUM(NSInteger, ARRaycastTargetAlignment) {
- /** A target that is horizontal with respect to gravity. */
+ /** The case that indicates a target is aligned horizontally with respect to gravity. */
ARRaycastTargetAlignmentHorizontal,
- /** A target that is vertical with respect to gravity. */
+ /** The case that indicates a target is aligned vertically with respect to gravity. */
ARRaycastTargetAlignmentVertical,
- /** A target that is in any alignment, inclusive of horizontal and vertical. */
+ /** The case that indicates a target may be aligned in any way with respect to gravity. */
ARRaycastTargetAlignmentAny
} NS_SWIFT_NAME(ARRaycastQuery.TargetAlignment);
/**
- Representation of a ray and its target which is used for raycasting.
+ A mathematical ray you use to find 3D positions on real-world surfaces.
- Represents a 3D ray and its target which is used to perform raycasting.
+ You create a raycast query by providing a 3D vector and starting place.
+
+ To create a raycast query using a 2D screen location and default vector that casts outward in the z-direction from the user, use the convenience
+ functions, <doc://com.apple.documentation/documentation/realitykit/arview/makeraycastquery(from:allowing:alignment:)> on
+ <doc://com.apple.documentation/documentation/realitykit/arview>, or ``ARSCNView/raycastQuery(from:allowing:alignment:)`` on ``ARSCNView``.
+
+ Raycasts can intersect with planes (flat surfaces) or meshes (uneven surfaces). To intersect with planes, see ``Target``. To intersect with meshes,
+ see ``Target/estimatedPlane``.
*/
API_AVAILABLE(ios(13.0))
@interface ARRaycastQuery : NSObject
/**
- Origin of the ray.
+ A 3D coordinate that defines the ray's starting place.
*/
@property (nonatomic, readonly) simd_float3 origin;
/**
- Direction of the ray.
+ A vector that describes the ray's trajectory in 3D space.
*/
@property (nonatomic, readonly) simd_float3 direction;
/**
- Type of target where the ray should terminate.
+ A plane type that allows the raycast to terminate if it's encountered.
+
+ The available target types are plane, infinite plane, and estimated plane.
*/
@property (nonatomic, readonly) ARRaycastTarget target;
/**
- The alignment of the target that should be considered for raycasting.
+ The target's alignment with respect to gravity.
+
+ The available options are horizontal, vertical, or any.
*/
@property (nonatomic, readonly) ARRaycastTargetAlignment targetAlignment;
/**
- Create a new ARRaycastQuery with the provided origin, direction, allowed target and its alignment.
+ Creates a new raycast query.
- - Parameters:
- - origin: Origin of the ray.
- - direction: Direction of the ray.
- - target: Type of target where the ray is allowed to terminate.
- - alignment: Alignment of the target that should be considered for raycasting.
+ This creates a query by supplying a 3D starting place and vector. To acquire a raycast query using a screen point and vector that points outward from
+ the user, call ``ARSCNView/raycastQuery(from:allowing:alignment:)`` on ``ARSCNView``.
- - Returns: An initialized raycast query.
+ - Parameters:
+ - origin: A 3D position that describes the raycast's starting point.
+ - direction: A 3D vector that describes the raycast's direction.
+ - target: The type of plane with which you allow the raycast to intersect.
+ - alignment: The target's alignment with respect to gravity with which you allow the raycast to intersect.
*/
- (instancetype)initWithOrigin:(simd_float3)origin
direction:(simd_float3)direction
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARRaycastResult.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARRaycastResult.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARRaycastResult.h 2026-08-15 23:02:19
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARRaycastResult.h 2026-10-04 02:32:28
@@ -17,31 +17,43 @@
API_UNAVAILABLE_BEGIN(visionos)
/**
- Result of a raycast on a single target.
+ Information about a real-world surface found by examining a point on the screen.
+
+ A raycast projects a ray from a screen point into the physical environment and returns an ``ARRaycastResult`` describing each real-world surface the
+ ray intersects.
+
+ If you use <doc://com.apple.documentation/documentation/realitykit/arview> as your renderer, you can raycast from a screen point directly with
+ <doc://com.apple.documentation/documentation/realitykit/arview/raycast(from:allowing:alignment:)>. With ``ARSCNView`` or a custom renderer, you
+ first build a query and then run it:
+
+ - Create a query with ``ARSCNView/raycastQuery(from:allowing:alignment:)`` or ``ARFrame/raycastQuery(from:allowing:alignment:)``.
+ - Search for surfaces by passing that query to ``ARSession/raycast(_:)``.
+
+ For tracked raycasting, you call ``ARSession/trackedRaycast(_:updateHandler:)`` on your app's current ``ARSession``.
*/
API_AVAILABLE(ios(13.0))
@interface ARRaycastResult : NSObject
/**
- The transformation matrix that defines the raycast result's rotation, translation and scale relative to the world.
+ The position, rotation, and scale, of the ray's intersection with the target.
*/
@property (nonatomic, readonly) simd_float4x4 worldTransform;
/**
- Type of the target where the ray terminated.
+ The type of surface that the ray intersects.
*/
@property (nonatomic, readonly, assign) ARRaycastTarget target;
/**
- Alignment of the target.
+ The alignment of the plane that the ray intersected.
*/
@property (nonatomic, readonly, assign) ARRaycastTargetAlignment targetAlignment;
/**
- The anchor that the ray intersected.
+ The anchor for the plane that the ray intersected.
- In case of an existing plane target, an anchor will always be provided. In case of an estimated plane target,
- an anchor may be provided if the ray hit an existing plane.
+ If you chose an existing plane target, ARKit provides its anchor. If you choose an estimated plane target, ARKit provides an anchor only if the ray
+ intersects an existing plane.
*/
@property (nonatomic, readonly, strong, nullable) ARAnchor *anchor;
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARReferenceImage.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARReferenceImage.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARReferenceImage.h 2026-08-15 23:02:19
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARReferenceImage.h 2026-10-04 02:32:28
@@ -18,77 +18,125 @@
API_UNAVAILABLE_BEGIN(visionos)
/**
- A reference image to be detected in the scene.
+ A 2D image that you want ARKit to detect in the physical environment.
+
+ To accurately detect the position and orientation of a 2D image in the real world, ARKit requires
+ preprocessed image data and knowledge of the image's real-world dimensions. The `ARReferenceImage`
+ class encapsulates this information. To enable image detection in an AR session, pass a collection
+ of reference images to your session configuration's ``ARWorldTrackingConfiguration/detectionImages`` property.
+
+ Typically, you create reference images in your Xcode project's asset catalog:
+
+ 1. In your asset catalog, use the Add (+) button to create an AR Resource Group.
+ 2. Drag image files into the resource group to create AR Reference Image entries in the asset catalog.
+ 3. For each reference image, use the Xcode inspector panel to provide the real-world size at which you
+ want ARKit to recognize the image. (You can also provide a descriptive name, which appears as the
+ ``name`` property at runtime and can be useful for debugging.)
*/
API_AVAILABLE(ios(11.3))
NS_SWIFT_SENDABLE
@interface ARReferenceImage : NSObject
/**
- An optional name used to identify the image.
+ A descriptive name for the image.
+
+ For reference images loaded from an Xcode asset catalog, this property is the name assigned in the
+ asset catalog. For programmatically created reference images, this value is `nil`.
+
+ - Note: This string is not localized text intended for user display. However, in debugging you can
+ use this property to indicate which image was detected.
*/
@property (nonatomic, copy, nullable) NSString *name;
/**
- The physical size of the image in meters.
+ The real-world dimensions, in meters, of the image.
+
+ To accurately recognize the position and orientation of an image in the AR environment, ARKit must
+ know the image's physical size. You provide this information when creating an AR reference image in
+ your Xcode project's asset catalog, or when programmatically creating an `ARReferenceImage`.
+
+ When you want to recognize different-sized versions of a reference image, you set
+ ``ARWorldTrackingConfiguration/automaticImageScaleEstimationEnabled`` to <doc://com.apple.documentation/documentation/swift/true>,
+ and in this case, ARKit disregards `physicalSize`.
*/
@property (nonatomic, readonly) CGSize physicalSize;
/**
The AR resource group name for this image.
- If this image was loaded via an AR resource group in the Xcode asset catalogue this property will have the name of the resource group,
- else be set to nil.
+ If ARKit loaded this image from an AR resource group in an asset catalog, ARKit sets the value of
+ this property to the resource group's name. Otherwise, the value of this property is `nil`.
*/
@property (nonatomic, strong, nullable, readonly) NSString *resourceGroupName API_AVAILABLE(ios(13.0));
/**
- Validate if this image can be used for image detection or tracking.
+ Determines whether the reference image is valid.
- When loading reference images from the asset catalog this verification is not needed as the same verification happens
- at compile time.
+ ARKit considers certain images invalid for image tracking (for example, an image that's all white).
+ Call this function on a reference image you create programmatically to make sure ARKit can track it,
+ before passing it in to your session's ``ARWorldTrackingConfiguration/detectionImages`` array.
+ You only need this function when you create a reference image programmatically, because Xcode performs
+ this validation for you when you create a reference image in an asset catalog.
+
- Parameter completionHandler: Completion handler invoked when validation is done. The completion handler takes the following parameters:
error - An error that indicates why the image is not suitable for tracking, or `nil` if no error occurred.
*/
- (void)validateWithCompletionHandler:(void (^)(NSError *_Nullable error))completionHandler API_AVAILABLE(ios(13.0));
/**
- Creates a new reference image.
+ Creates a new reference image from a Core Graphics image object.
- - Parameters:
- - image: The reference image as `CGImage`.
- - orientation: The image orientation.
- - physicalWidth: The width in meters of the physical object.
+ To accurately recognize the position and orientation of an image in the AR environment, ARKit must
+ know the image's physical size. When you call this initializer, ARKit uses the `physicalWidth`
+ measurement and `orientation` you provide together with the aspect ratio of the image itself to
+ calculate the physical height. Use the ``ARReferenceImage/physicalSize`` property of the created
+ ``ARReferenceImage`` object to retrieve these values.
- - Returns: An initialized reference image.
+ > Important: ARKit preprocesses reference images before using them for image detection. To provide reference images bundled with your app, create AR
+ reference image assets in your Xcode asset catalog, and use the ``ARReferenceImage/referenceImages(inGroupNamed:bundle:)`` method to load them.
+
+ - Parameters:
+ - image: A Core Graphics image object.
+ - orientation: The intended display orientation for the image.
+ - physicalWidth: The real-world width, in meters, of the image.
*/
- (instancetype)initWithCGImage:(CGImageRef)image
orientation:(CGImagePropertyOrientation)orientation
physicalWidth:(CGFloat)physicalWidth NS_SWIFT_NAME(init(_:orientation:physicalWidth:));
/**
- Creates a new reference image.
+ Creates a new reference image from a Core Video pixel buffer.
- - Parameters:
- - pixelBuffer: The reference image as `CVPixelBuffer`.
- - physicalWidth: The width in meters of the physical object.
- - orientation: The image orientation.
+ To accurately recognize the position and orientation of an image in the AR environment, ARKit must
+ know the image's physical size. When you call this initializer, ARKit uses the `physicalWidth`
+ measurement and `orientation` you provide together with the aspect ratio of the image itself to
+ calculate the physical height. Use the ``ARReferenceImage/physicalSize`` property of the created
+ ``ARReferenceImage`` object to retrieve these values.
- - Returns: An initialized reference image.
+ > Important: ARKit preprocesses reference images before using them for image detection. To provide reference images bundled with your app, create AR
+ reference image assets in your Xcode asset catalog, and use the ``ARReferenceImage/referenceImages(inGroupNamed:bundle:)`` method to load them.
+
+ - Parameters:
+ - pixelBuffer: A Core Video pixel buffer containing the image data for the new image.
+ - orientation: The intended display orientation for the image.
+ - physicalWidth: The real-world width, in meters, of the image.
*/
- (instancetype)initWithPixelBuffer:(CVPixelBufferRef)pixelBuffer
orientation:(CGImagePropertyOrientation)orientation
physicalWidth:(CGFloat)physicalWidth NS_SWIFT_NAME(init(_:orientation:physicalWidth:));
/**
- Returns the set of ARReferenceImages in the specified resource group and bundle.
+ Loads all reference images in the specified AR Resource Group in your Xcode project's asset catalog.
+ To use the images for image detection in a world-tracking AR session, provide this set for your
+ session configuration's ``ARWorldTrackingConfiguration/detectionImages`` property.
+
- Parameters:
- - name: The name of the resource group.
- - bundle: The bundle containing the image file or asset catalog. Specify `nil` to search the app’s main bundle.
+ - name: The name of an AR Resource Group from your Xcode project's main asset catalog.
+ - bundle: The bundle from which to load asset catalog resources, or `nil` to use your app's main bundle.
- - Returns: The set of reference images or `nil` on error.
+ - Returns: A set of all unique reference images in the specified group.
*/
+ (nullable NSSet<ARReferenceImage *> *)referenceImagesInGroupNamed:(NSString *)name bundle:(nullable NSBundle *)bundle;
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARReferenceObject.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARReferenceObject.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARReferenceObject.h 2026-08-15 23:02:19
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARReferenceObject.h 2026-10-04 02:32:29
@@ -15,6 +15,11 @@
API_UNAVAILABLE_BEGIN(visionos)
+/**
+ The standard filename extension for exported ``ARReferenceObject`` instances.
+
+ Use this filename extension when constructing a URL to save a reference object file with the ``ARReferenceObject/export(to:previewImage:)`` method.
+ */
API_AVAILABLE(ios(12.0))
FOUNDATION_EXTERN NSString *const ARReferenceObjectArchiveExtension NS_SWIFT_NAME(ARReferenceObject.archiveExtension)
API_DEPRECATED("Only supported for legacy reference objects.",
@@ -52,39 +57,62 @@
@interface ARReferenceObject : NSObject <NSSecureCoding>
/**
- An optional name used to identify the object.
+ A descriptive name for the reference object.
+
+ For a reference object loaded from an Xcode asset catalog, this property is the name assigned in the asset catalog. You can also use this property to
+ assign a name to an object you've recorded in an AR session using ``ARSession/createReferenceObject(transform:center:extent:completionHandler:)``.
+
+ - Note: This string is not localized text intended for user display. However, in debugging you can use this property to indicate which reference
+ object was detected.
*/
@property (nonatomic, copy, nullable) NSString *name;
/**
- The center of the object in the object’s local coordinate space.
+ The center point of the reference object's space-mapping data.
+
+ The ``extent`` and ``center`` properties together define a bounding box for the data recorded in the reference object in its local coordinate system.
+ You define that coordinate system with the transform parameter when calling
+ ``ARSession/createReferenceObject(transform:center:extent:completionHandler:)``, and can modify it by creating another reference object with
+ ``ARReferenceObject/applyingTransform(_:)``.
*/
@property (nonatomic, readonly) simd_float3 center;
/**
- The extent of the object in the object’s local coordinate space.
+ The size of the reference object's space-mapping data.
+
+ The ``extent`` and ``center`` properties together define a bounding box for the data recorded in the reference object in its local coordinate system.
+ You define that coordinate system with the transform parameter when calling
+ ``ARSession/createReferenceObject(transform:center:extent:completionHandler:)``, and can modify it by creating another reference object with
+ ``ARReferenceObject/applyingTransform(_:)``.
*/
@property (nonatomic, readonly) simd_float3 extent;
/**
- The scale of the object’s local coordinate space.
+ A scale factor for the local coordinate space the reference object defines.
- Multiplying the extent by this scale will result in the physical extent of the object, measured in meters.
+ Multiplying the ``extent`` by this scale results in the physical size of the object in meters.
*/
@property (nonatomic, readonly) simd_float3 scale;
/**
The AR resource group name for this object.
- If this object was loaded via an AR resource group in the Xcode asset catalogue this property will have the name of the resource group,
- else be set to `nil`.
+ If ARKit loaded this object from an AR resource group in an asset catalog, ARKit sets the value of this property to the resource group's name.
+ Otherwise, the value of this property is `nil`.
*/
@property (nonatomic, strong, nullable, readonly)
NSString *resourceGroupName API_DEPRECATED("Only supported for legacy reference objects.", ios(13.0, 27.0));
/**
- The feature points of the object.
+ A coarse representation of the space-mapping data contained in the reference object.
+ These points represent notable features detected in camera imagery during the session that recorded the reference object. ARKit extrapolates the
+ locations of these features in 3D world coordinate space as part of the image and motion analysis that tracks the device's movement in a session.
+ Taken together, these points loosely correlate to the contours of real-world objects that were in view of the camera during the session.
+
+ ARKit does not guarantee that the number and arrangement of raw feature points will remain stable between software releases. However, you can
+ visualize the point cloud to debug your app's object recording or detection, or inspect its size to estimate the quality of a recorded object.
+
For reference objects loaded from a `.referenceobject` file, this property returns an empty point cloud.
*/
@property (nonatomic, strong, readonly) ARPointCloud *rawFeaturePoints API_DEPRECATED("Only supported for legacy reference objects.", ios(12.0, 27.0))
@@ -98,41 +126,54 @@
/**
Returns the set of ARReferenceObjects in the specified resource group and bundle.
+ To use the objects for detection in a world-tracking AR session, provide this set for your session configuration's
+ ``ARWorldTrackingConfiguration/detectionObjects`` property.
+
- Parameters:
- - name: The name of the resource group.
- - bundle: The bundle containing the image file or asset catalog. Specify `nil` to search the app’s main bundle.
+ - name: The name of an AR Resource Group from your Xcode project's main asset catalog.
+ - bundle: The bundle from which to load asset catalog resources, or `nil` to use your app's main bundle.
- - Returns: The set of reference objects or `nil` on error.
+ - Returns: A set of all unique reference objects in the specified group, or `nil` on error.
*/
+ (nullable NSSet<ARReferenceObject *> *)referenceObjectsInGroupNamed:(NSString *)name
bundle:(nullable NSBundle *)bundle
API_DEPRECATED("Only supported for legacy reference objects.", ios(12.0, 27.0));
/**
- Initializes a new reference object with the contents of an archive at the specified URL.
+ Loads a reference object from the specified file URL.
+ To use the object for detection in a world-tracking AR session, add it to the ``ARWorldTrackingConfiguration/detectionObjects`` set in your session
+ configuration.
+
- Parameters:
- url: The local file `URL` from which to read data (`.arobject` or `.referenceobject` archive).
- - error: The error to populate if the object could not be initialized.
-
- - Returns: An initialized reference object.
+ - error: A pointer to an <doc://com.apple.documentation/documentation/foundation/nserror> object. If this method returns `nil`, check this pointer
+ for an error describing the failure.
*/
- (nullable instancetype)initWithArchiveURL:(NSURL *)url error:(NSError **)error;
/**
- Exports the object as an archive at the given URL.
+ Writes a binary representation of the object to the specified file URL.
+ After exporting a reference object from your object-scanning app to a file, you can bundle that reference object into other apps you create by
+ inserting it into an Xcode asset catalog.
+
The `URL` path should use `ARReferenceObjectArchiveExtension` (.arobject) for the file extension.
If serialization across devices is desired, NSKeyedArchiver should be used instead.
You can't export reference objects loaded from a `.referenceobject` file.
- Parameters:
- - url: The `URL` at which to write the exported object.
- - previewImage: An optional preview image to include in the archive.
- - error: The error to populate if the write is not successful.
+ - url: The file `URL` at which to write the reference object data.
+ - previewImage: A thumbnail image to be embedded in the reference object's filesystem representation.
- - Returns: `YES` if the location is written successfully, otherwise `NO`.
+ ARKit ignores preview images when loading reference objects. Instead, this image helps make reference object files visually identifiable in
+ external tools like Xcode, Finder, and Quick Look.
+ - error: A pointer to an <doc://com.apple.documentation/documentation/foundation/nserror>. On completion, if the method returns
+ <doc://com.apple.documentation/documentation/swift/false>, the pointer is populated with an object describing the failure.
+
+ - Returns: <doc://com.apple.documentation/documentation/swift/true> if the operation succeeded. If
+ <doc://com.apple.documentation/documentation/swift/false>, check the `error` parameter for failure details.
*/
- (BOOL)exportObjectToURL:(NSURL *)url
previewImage:(nullable UIImage *)previewImage
@@ -141,31 +182,47 @@
/**
Returns a new reference object by applying the specified transform to the object's origin.
- This can be used to change the reference object's origin with respect to the physical object. Providing
- a transform local to the current object's coordinate space will return an object with the transform's position and orientation as the origin.
+ You define the local coordinate space of a reference object with the transform parameter when you create it with
+ ``ARSession/createReferenceObject(transform:center:extent:completionHandler:)``. If an existing reference object has a local coordinate origin that
+ doesn't fit well with the object's intended use, call this method to change the reference object's origin with respect to the physical object it
+ represents.
+ When ARKit detects a reference object, the ``ARAnchor/transform`` of the resulting ``ARObjectAnchor`` is based on the origin of the reference
+ object's coordinate system. For example, if a reference object represents a physical item that sits on a horizontal surface, virtual content should
+ appear to sit on whatever surface the physical object does. As such, it's typically useful to align a reference object's coordinate origin with the
+ bottom of the physical object.
+
For reference objects loaded from a `.referenceobject` file, this method returns the same reference object unchanged.
- - Parameter transform: The rotation and translation to apply to the object's origin.
+ - Parameter transform: A transform matrix in the local coordinate space of the reference object.
- - Returns: A reference object with updated origin.
+ - Returns: The transformed reference object.
*/
- (ARReferenceObject *)referenceObjectByApplyingTransform:(simd_float4x4)transform
API_DEPRECATED("Only supported for legacy reference objects.", ios(12.0, 27.0));
/**
- Returns a new reference object by aligning and merging the provided object with this reference.
+ Returns a new reference object that combines spatial information from both this reference object and another.
- This can be used to combine multiple scans of the same object for detection in different conditions. The object being merged
- must share similar feature points for the merge to succeed.
+ The accuracy of 3D object detection depends on similarity of lighting and environmental conditions between when you scan a real object (producing an
+ ``ARReferenceObject``) and when a user of your app attempts to detect that object. If, for example, you scan an object in a bright environment, then
+ a user attempts to detect it in a dark environment, ARKit may fail to recognize that the real object matches the reference object, or may not detect
+ the object quickly.
+ To make a reference object that is more robust in a wide variety of detection conditions, scan the same real-world object multiple times: For each
+ scan, vary the lighting conditions or the background environment to capture the variety of situations in which your app might attempt to detect the
+ same real object. Then, use this method to combine those scan results into a single ``ARReferenceObject`` incorporating recognition information for
+ all the conditions you scanned in.
+
You can't merge reference objects loaded from a `.referenceobject` file.
- Parameters:
- - object: The reference object to align and merge.
- - error: The error to populate if the merge is not successful.
+ - object: The other reference object with which to combine this reference object.
+ - error: A pointer to an <doc://com.apple.documentation/documentation/foundation/nserror>. On completion, if the method returns `nil`, this pointer
+ references an object describing the failure.
- - Returns: A new reference object combining features of both scans or `nil` if the merge was not successful.
+ - Returns: A new ``ARReferenceObject`` that includes the spatial information from both objects. From Swift, this method throws an ``ARError`` if the
+ two objects cannot be merged. From Objective-C, it returns `nil` and populates the `error` parameter with a description of the failure.
*/
- (nullable ARReferenceObject *)referenceObjectByMergingObject:(ARReferenceObject *)object
error:(NSError **)error
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARSCNFaceGeometry.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARSCNFaceGeometry.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARSCNFaceGeometry.h 2026-08-15 23:13:05
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARSCNFaceGeometry.h 2026-10-04 02:39:15
@@ -18,42 +18,79 @@
NS_ASSUME_NONNULL_BEGIN
/**
- A SceneKit geometry representing a face.
+ A SceneKit representation of face topology for use with face information that an AR session provides.
+
+ This class is a subclass of <doc://com.apple.documentation/documentation/scenekit/scngeometry> that wraps the mesh data provided by the
+ ``ARFaceGeometry`` class. You can use ``ARSCNFaceGeometry`` to quickly and easily visualize face topology and facial expressions provided by ARKit in
+ a SceneKit view.
+
+ > Important:
+ > ``ARSCNFaceGeometry`` is available only in SceneKit views or renderers that use Metal. This class is not supported for OpenGL-based SceneKit
+ rendering.
+
+ Face mesh topology is constant for the lifetime of an ``ARSCNFaceGeometry`` object. That is, the geometry's single
+ <doc://com.apple.documentation/documentation/scenekit/scngeometryelement> object always describes the same arrangement of vertices, and the
+ <doc://com.apple.documentation/documentation/scenekit/scngeometrysource/semantic-swift.struct/texcoord> geometry source always maps the same vertices
+ to the same texture coordinates.
+
+ When you modify the geometry with the ``update(from:)`` method, only the contents of the
+ <doc://com.apple.documentation/documentation/scenekit/scngeometrysource/semantic-swift.struct/vertex> geometry source change, indicating the
+ difference in vertex positions as ARKit adapts the mesh to the shape and expression of the user's face.
*/
API_AVAILABLE(ios(11.0))
@interface ARSCNFaceGeometry : SCNGeometry
/**
- Creates a new face geometry using a Metal device.
+ Creates a SceneKit face geometry for rendering with the specified Metal device object.
- - Parameter device: A Metal device.
+ A newly created ``ARSCNFaceGeometry`` instance represents a neutral, generic face; use the ``ARSCNFaceGeometry/update(from:)`` method to deform the
+ geometry to match a specific facial expression or face shape.
- - Returns: A new face geometry.
+ The geometry contains a single geometry element; as such, assigning more than one material has no visible effect (see the inherited
+ <doc://com.apple.documentation/documentation/scenekit/scngeometry/materials> property).
+
+ Calling this initializer is equivalent to calling the ``ARSCNFaceGeometry/init(device:fillMesh:)`` initializer and passing
+ <doc://com.apple.documentation/documentation/swift/false> for the `fillMesh` parameter.
+
+ - Parameter device: The Metal device to use for rendering the geometry.
*/
+ (nullable instancetype)faceGeometryWithDevice:(id<MTLDevice>)device;
/**
- Creates a new face geometry using a Metal device.
+ Creates a SceneKit face geometry, optionally filling in gaps in the mesh for the eyes and mouth.
- By default the regions between the eye lids as well as the region
- between the lips are not covered by geometry. For using the face geometry as an
- occlusion geometry set \p fillMesh to YES. This will fill
- in additional geometry into the gaps between the eye lids as well as into the
- gap between the lips.
+ A newly created ``ARSCNFaceGeometry`` instance represents a neutral, generic face; use the ``ARSCNFaceGeometry/update(from:)`` method to deform the
+ geometry to match a specific facial expression or face shape.
+ If the `fillMesh` parameter is <doc://com.apple.documentation/documentation/swift/false>, the geometry contains a single geometry element. If the
+ `fillMesh` parameter is <doc://com.apple.documentation/documentation/swift/true>, the geometry contains four elements in the following order: the
+ face itself, the left and right eyes, and the mouth. (When a SceneKit geometry contains multiple elements, the number and order of materials you
+ assign to its <doc://com.apple.documentation/documentation/scenekit/scngeometry/materials> array determines whether the entire surface has a uniform
+ appearance or different appearances for each geometry element.)
+
- Parameters:
- - device: A Metal device.
- - fillMesh: Whether to fill in additional geometry into the
- gaps between the eye lids as well as into the gap between the lips.
+ - device: The Metal device to use for rendering the geometry.
+ - fillMesh: If <doc://com.apple.documentation/documentation/swift/false>, the mesh doesn't include the eye and mouth areas of the face topology—as
+ a result, if you render the face geometry for a face anchor atop the camera feed in an AR session, the user's eyes and the inside of the user's mouth
+ (when open) are visible through the gaps in the 3D model.
- - Returns: A new face geometry.
+ If <doc://com.apple.documentation/documentation/swift/true>, the mesh fills in the gaps for the eyes and mouth. This option can be useful when
+ using the face geometry for occlusion only—that is, to prevent other 3D content from rendering behind it, while still showing the camera image
+ beneath.
*/
+ (nullable instancetype)faceGeometryWithDevice:(id<MTLDevice>)device fillMesh:(BOOL)fillMesh;
/**
- Updates the geometry with the vertices of a face geometry.
+ Deforms the SceneKit geometry to match the specified face mesh.
- - Parameter faceGeometry: A face geometry.
+ To update a SceneKit model of a face actively tracked in an AR session, call this method in your ``ARSCNViewDelegate`` object's
+ ``ARSCNViewDelegate/renderer(_:didUpdate:for:)`` callback, passing the ``ARFaceAnchor/geometry`` property from the ``ARFaceAnchor`` object that
+ callback provides.
+
+ Alternatively, you can create, configure, and visualize face models independent of an AR session by creating face geometry objects using the
+ ``ARFaceGeometry`` ``ARFaceGeometry/init(blendShapes:)`` initializer and passing them to this method.
+
+ - Parameter faceGeometry: A coarse mesh representation of a face's topology, dimensions, and expression.
*/
- (void)updateFromFaceGeometry:(ARFaceGeometry *)faceGeometry;
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARSCNPlaneGeometry.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARSCNPlaneGeometry.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARSCNPlaneGeometry.h 2026-08-15 23:13:05
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARSCNPlaneGeometry.h 2026-10-04 02:39:15
@@ -18,24 +18,42 @@
NS_ASSUME_NONNULL_BEGIN
/**
- A SceneKit geometry representing a plane.
+ A SceneKit representation of the 2D shape of a plane, for use with plane detection results in an AR session.
+
+ `ARSCNPlaneGeometry` is a subclass of <doc://com.apple.documentation/documentation/scenekit/scngeometry> that wraps the mesh data provided by the
+ ``ARPlaneGeometry`` class. You can use `ARSCNPlaneGeometry` to visualize the plane shape estimates provided by ARKit in a SceneKit view.
+
+ > Important:
+ > `ARSCNPlaneGeometry` is available only in SceneKit views or renderers that use Metal. This class is not supported for OpenGL-based SceneKit
+ rendering.
+
+ As your AR session continues to run, ARKit provides refined estimates of a detected plane's 2D shape. Use the ``updateFromPlaneGeometry:`` method to
+ incorporate those refinements into the plane's SceneKit representation.
*/
API_AVAILABLE(ios(11.3))
@interface ARSCNPlaneGeometry : SCNGeometry
/**
- Creates a new plane geometry using a Metal device.
+ Creates a SceneKit plane geometry for rendering with the specified Metal device object.
- - Parameter device: A Metal device.
+ - Parameter device: The Metal device to use for rendering the geometry.
- - Returns: A new plane geometry.
+ A newly created `ARSCNPlaneGeometry` instance does not represent any specific plane; use the ``updateFromPlaneGeometry:`` method to make the geometry
+ match the estimated shape of a specific plane anchor.
+
+ The geometry contains a single geometry element; as such, assigning more than one material has no visible effect (see the inherited
+ <doc://com.apple.documentation/documentation/scenekit/scngeometry/materials> property).
*/
+ (nullable instancetype)planeGeometryWithDevice:(id<MTLDevice>)device;
/**
- Updates the geometry with the vertices of a plane geometry.
+ Reshapes the SceneKit geometry to match the specified plane mesh.
- - Parameter planeGeometry: A plane geometry.
+ - Parameter planeGeometry: A coarse mesh representation of a detected plane's estimated shape.
+
+ To update a SceneKit model of a plane actively tracked in an AR session, call this method in your ``ARSCNViewDelegate`` object's
+ ``ARSCNViewDelegate/renderer(_:didUpdate:for:)`` callback, passing the ``ARPlaneAnchor/geometry`` property from the ``ARPlaneAnchor`` object that
+ callback provides.
*/
- (void)updateFromPlaneGeometry:(ARPlaneGeometry *)planeGeometry;
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARSCNView.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARSCNView.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARSCNView.h 2026-08-15 23:13:05
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARSCNView.h 2026-10-04 02:39:14
@@ -18,109 +18,155 @@
NS_ASSUME_NONNULL_BEGIN
/**
- A view that integrates ARSession rendering into SceneKit.
+ A view that blends virtual 3D content from SceneKit into your augmented reality experience.
- The view draws the camera background, provides and updates a camera,
- manages nodes for anchors, and updates lighting.
+ > Important: SceneKit is deprecated, use <doc://com.apple.documentation/documentation/realitykit> instead.
+ > For more information, see WWDC25 session 288: [Bring your SceneKit projects to RealityKit](https://developer.apple.com/videos/play/wwdc2025/288/).
+
+ The `ARSCNView` class provides an easy way to create augmented reality experiences that blend virtual 3D content with a device camera view of the
+ real world. When you run the view's provided ``ARSession`` object:
+
+ - The view automatically renders the live video feed from the device camera as the scene background.
+ - The world coordinate system of the view's SceneKit scene directly responds to the AR world coordinate system established by the session
+ configuration.
+ - The view automatically moves its SceneKit camera to match the real-world movement of the device.
+
+ ARKit automatically matches SceneKit's coordinate space to the real world, so after you place your app's virtual content, it maintains the illusion
+ of resting in the real-world as the user moves the device. See <doc:providing-3d-virtual-content-with-scenekit>.
+
+ You don't necessarily need to use the ``ARAnchor`` class to track positions of objects you add to the scene, but by implementing
+ ``ARSCNViewDelegate`` methods, you can add SceneKit content to any anchors that are automatically detected by ARKit.
+
+ Because ARKit requires Metal, use only Metal features of SceneKit. For example:
+
+ - This class supports only <doc://com.apple.documentation/documentation/scenekit/scnprogram> instances with Metal Shading Language code.
+ - If you set the <doc://com.apple.documentation/documentation/scenekit/scnview/option/preferredrenderingapi> property to
+ <doc://com.apple.documentation/documentation/scenekit/scnrenderingapi/opengles2>, the framework reverts the value to
+ <doc://com.apple.documentation/documentation/scenekit/scnrenderingapi/metal>.
*/
API_AVAILABLE(ios(11.0))
API_DEPRECATED_WITH_REPLACEMENT("Please use RealityView instead.", visionos(1.0, 1.0))
@interface ARSCNView : SCNView <ARSessionProviding>
/**
- Specifies the renderer delegate.
+ An object you provide to mediate synchronization of the view's AR scene information with SceneKit content.
*/
@property (nonatomic, weak, nullable) id<ARSCNViewDelegate> delegate;
/**
- The session that the view uses to update the scene.
+ The AR session that manages motion tracking and camera image processing for the view's contents.
+
+ A view creates its own session object; use this property to access and configure the view's session.
*/
@property (nonatomic, strong) ARSession *session;
/**
- Specifies the scene of the view.
+ The SceneKit scene to be displayed in the view.
+
+ > Note:
+ > Unlike the parent <doc://com.apple.documentation/documentation/scenekit/scnview> class, an ``ARSCNView`` object requires a non-`nil` scene to
+ display.
*/
@property (nonatomic, strong) SCNScene *scene;
/**
- Determines whether the view will update the scene’s lighting.
+ A Boolean value that specifies whether ARKit creates and updates SceneKit lights in the view's scene.
- When set, the view will automatically create and update lighting for
- light estimates the session provides. Defaults to `YES`.
+ If this value is <doc://com.apple.documentation/documentation/swift/true> (the default), the view automatically creates one or more
+ <doc://com.apple.documentation/documentation/scenekit/scnlight> objects, adds them to the scene, and updates their properties to reflect estimated
+ lighting information from the camera scene. Set this value to <doc://com.apple.documentation/documentation/swift/false> if you want to directly
+ control all lighting in the SceneKit scene.
*/
@property (nonatomic, assign) BOOL automaticallyUpdatesLighting;
/**
- Determines whether view renders camera grain.
+ A flag that determines whether SceneKit applies image noise characteristics to your app's virtual content.
- When set, the view will automatically add camera grain to rendered
- content that matches the grainy noise of the camera stream. Enabled by default.
+ Enabled by default. When set, SceneKit adds a camera grain effect to your app's virtual content that matches the image noise characteristics ARKit
+ observes in the camera feed.
+
+ 
*/
@property (nonatomic, assign) BOOL rendersCameraGrain API_AVAILABLE(ios(13.0));
/**
- Determines whether view renders motion blur.
+ Determines whether the view renders motion blur.
- When set, the view will automatically add motion blur to rendered
- content that matches the motion blur of the camera stream.
- Overwrites SCNCamera's motionBlurIntensity property. Disabled by default.
+ This property is disabled by default. When set, the view automatically adds motion blur to rendered content which matches the visual characteristics
+ of the motion blur ARKit observes in the camera feed.
+
+ 
+
+ The value of this property overwrites the <doc://com.apple.documentation/documentation/scenekit/scncamera/motionblurintensity> of
+ <doc://com.apple.documentation/documentation/scenekit/scncamera>.
*/
@property (nonatomic, assign) BOOL rendersMotionBlur API_AVAILABLE(ios(13.0));
/**
- Searches the scene hierarchy for an anchor associated with the provided node.
+ Returns the AR anchor associated with the specified SceneKit node, if any.
- - Parameter node: A node in the view's scene.
+ - Parameter node: A SceneKit node in the view's scene.
- - Returns: The anchor associated with the node, or `nil` if none exists.
+ - Returns: The ``ARAnchor`` object tracking the node, or `nil` if the node is not associated with an anchor or not in the view's scene.
*/
- (nullable ARAnchor *)anchorForNode:(SCNNode *)node;
/**
- Returns the node that has been mapped to a specific anchor.
+ Returns the SceneKit node associated with the specified AR anchor, if any.
- - Parameter anchor: An anchor with an existing node mapping.
+ - Parameter anchor: An anchor in the view's AR session.
- - Returns: The node mapped to the anchor, or `nil` if none exists.
+ - Returns: The node whose position in the AR scene the anchor tracks, or `nil` if the anchor has no associated node or is not in the view's AR
+ session.
*/
- (nullable SCNNode *)nodeForAnchor:(ARAnchor *)anchor;
/**
- Searches the current frame for objects corresponding to a point in the view.
+ Searches for real-world objects or AR anchors in the captured camera image corresponding to a point in the SceneKit view.
- A 2D point in the view’s coordinate space can refer to any point along a line segment
- in the 3D coordinate space. Hit-testing is the process of finding objects in the world located along this line segment.
+ Hit testing searches for real-world objects or surfaces detected through the AR session's processing of the camera image. A 2D point in the view's
+ coordinate system can refer to any point along a 3D line that starts at the device camera and extends in a direction determined by the device
+ orientation and camera projection. This method searches along that line, returning all objects that intersect it in order of distance from the
+ camera.
+ > Note:
+ > This method searches for AR anchors and real-world objects detected by the AR session, not SceneKit content displayed in the view. To search for
+ SceneKit objects, use the view's <doc://com.apple.documentation/documentation/scenekit/scnscenerenderer/hittest(_:options:)> method instead.
+
+ The behavior of a hit test depends on which `types` you specify and the order you specify them in. For details, see ``ARHitTestResult`` and the
+ various ``ARHitTestResult/ResultType`` options.
+
- Parameters:
- - point: A point in the view’s coordinate system.
- - types: The types of results to search for.
+ - point: A point in the 2D coordinate system of the view.
+ - types: The types of hit-test result to search for.
- - Returns: An array of all hit-test results sorted from nearest to farthest.
+ - Returns: A list of results, sorted from nearest to farthest (in distance from the camera).
*/
- (NSArray<ARHitTestResult *> *)hitTest:(CGPoint)point
types:(ARHitTestResultType)types
API_DEPRECATED("Use [ARSCNView raycastQueryFromPoint:allowingTarget:alignment]", ios(11.0, 14.0));
/**
- Unproject a 2D point from the view onto a plane in 3D world coordinates.
+ Returns the projection of a point from 2D view onto a plane in the 3D world space detected by ARKit.
- A 2D point in the view’s coordinate space can refer to any point along a line segment
- in the 3D coordinate space. Unprojecting gets the 3D position of the point along this line segment that intersects the provided plane.
-
- Parameters:
- - point: A point in the view’s coordinate system.
- - planeTransform: The transform used to define the coordinate system of the plane. The coordinate system’s positive Y axis is assumed to be the
- normal of the plane.
+ - point: The point in 2D view space to project onto a plane.
- - Returns: 3D position in world coordinates or `NAN` values if unprojection is not possible.
+ The coordinate space for this point has its origin in the upper left corner and a size matching the view's bounds.
+ - planeTransform: A transform matrix specifying the position and orientation of a plane (with infinite extent) in 3D world space. The plane is the
+ xz-plane of the local coordinate space this transform defines.
+
+ - Returns: The 3D point in world space where a ray projected from the specified 2D point intersects the specified plane. If the ray does not
+ intersect the plane, this method returns a `float3` vector where all elements are `NaN`.
*/
- (simd_float3)unprojectPoint:(CGPoint)point ontoPlaneWithTransform:(simd_float4x4)planeTransform API_AVAILABLE(ios(12.0))NS_REFINED_FOR_SWIFT;
/**
- Creates a raycast query originating from the point on view, aligned along the center of the field of view of the camera.
+ Creates a raycast query that originates from a point on the view, aligned with the center of the camera's field of view.
- A 2D point in the view's coordinate space and the frame camera's field of view is used to create a ray in the 3D coordinate space
- originating at the point.
+ When you call this function, ARKit creates a ray that extends in the positive z-direction from the argument screen space point, to determine if any
+ of the argument targets exist in the physical environment anywhere along the ray. If so, ARKit returns a 3D position where the ray intersects the
+ target.
- Parameters:
- point: A point in the view's coordinate system.
@@ -138,7 +184,13 @@
#pragma mark - ARSCNViewDelegate
/**
- A delegate protocol for SceneKit-based AR view events and node mapping.
+ Methods you can implement to mediate the automatic synchronization of SceneKit content with an AR session.
+
+ Implement this protocol to provide SceneKit content corresponding to ``ARAnchor`` objects tracked by the view's AR session, or to manage the view's
+ automatic updating of such content.
+
+ This protocol extends the ``ARSessionObserver`` protocol, so your session delegate can also implement those methods to respond to changes in session
+ status.
*/
API_AVAILABLE(ios(11.0))
API_DEPRECATED_WITH_REPLACEMENT("Please use RealityView instead.", visionos(1.0, 1.0))
@@ -146,72 +198,111 @@
@optional
/**
- Implement this to provide a custom node for the given anchor.
+ Asks the delegate to provide a SceneKit node corresponding to a newly added anchor.
- This node will automatically be added to the scene graph.
- If this method is not implemented, a node will be automatically created.
- If nil is returned the anchor will be ignored.
+ Depending on the session configuration, ARKit may automatically add anchors to a session. ARKit also calls this method to provide visual content for
+ any ``ARAnchor`` objects you manually add using the session's ``ARSession/add(anchor:)`` method.
+ You can implement this method to provide a new <doc://com.apple.documentation/documentation/scenekit/scnnode> object (or instance of an
+ <doc://com.apple.documentation/documentation/scenekit/scnnode> subclass) containing any attachments you plan to use as a visual representation of the
+ anchor. Note that ARKit controls the node's visibility and its <doc://com.apple.documentation/documentation/scenekit/scnnode/transform> property, so
+ you may find it useful to add child nodes or adjust the node's <doc://com.apple.documentation/documentation/scenekit/scnnode/pivot> property to
+ maintain any changes to position or orientation that you make.
+
+ If you return `nil` from this method, no node is added to the scene.
+
+ Alternatively, if you do not implement this method, ARKit creates an empty node, and you can implement the
+ ``ARSCNViewDelegate/renderer(_:didAdd:for:)`` method instead to provide visual content by attaching it to that node.
+
- Parameters:
- - renderer: The renderer that will render the scene.
- - anchor: The added anchor.
+ - renderer: The ``ARSCNView`` object rendering the scene.
+ - anchor: The anchor for which a node is requested.
- - Returns: Node that will be mapped to the anchor or `nil`.
+ - Returns: A new SceneKit node, which ARKit will add to the scene and update to follow its corresponding AR anchor.
*/
- (nullable SCNNode *)renderer:(id<SCNSceneRenderer>)renderer nodeForAnchor:(ARAnchor *)anchor;
/**
- Called when a new node has been mapped to the given anchor.
+ Tells the delegate that a SceneKit node corresponding to a new AR anchor has been added to the scene.
+ Depending on the session configuration, ARKit may automatically add anchors to a session. The view calls this method once for each new anchor. ARKit
+ also calls this method to provide visual content for any ``ARAnchor`` objects you manually add using the session's ``ARSession/add(anchor:)`` method.
+
+ You can provide visual content for the anchor by attaching geometry (or other SceneKit features) to this node or by adding child nodes.
+
+ Alternatively, you can implement the ``ARSCNViewDelegate/renderer(_:nodeFor:)`` method to create your own node (or instance of an
+ <doc://com.apple.documentation/documentation/scenekit/scnnode> subclass) for an anchor.
+
- Parameters:
- - renderer: The renderer that will render the scene.
- - node: The node that maps to the anchor.
- - anchor: The added anchor.
+ - renderer: The ``ARSCNView`` object rendering the scene.
+ - node: The newly added SceneKit node.
+ - anchor: The AR anchor corresponding to the node.
*/
- (void)renderer:(id<SCNSceneRenderer>)renderer didAddNode:(SCNNode *)node forAnchor:(ARAnchor *)anchor;
/**
- Called when a node will be updated with data from the given anchor.
+ Tells the delegate that a SceneKit node's properties will be updated to match the current state of its corresponding anchor.
+ Depending on the session configuration, ARKit may automatically update anchors in a session. The view calls this method once for each updated anchor.
+
- Parameters:
- - renderer: The renderer that will render the scene.
- - node: The node that will be updated.
- - anchor: The anchor that was updated.
+ - renderer: The ``ARSCNView`` object rendering the scene.
+ - node: The updated SceneKit node.
+ - anchor: The AR anchor corresponding to the node.
*/
- (void)renderer:(id<SCNSceneRenderer>)renderer willUpdateNode:(SCNNode *)node forAnchor:(ARAnchor *)anchor;
/**
- Called when a node has been updated with data from the given anchor.
+ Tells the delegate that a SceneKit node's properties have been updated to match the current state of its corresponding anchor.
+ Depending on the session configuration, ARKit may automatically update anchors in a session. The view calls this method once for each updated anchor.
+
- Parameters:
- - renderer: The renderer that will render the scene.
- - node: The node that was updated.
- - anchor: The anchor that was updated.
+ - renderer: The ``ARSCNView`` object rendering the scene.
+ - node: The updated SceneKit node.
+ - anchor: The AR anchor corresponding to the node.
*/
- (void)renderer:(id<SCNSceneRenderer>)renderer didUpdateNode:(SCNNode *)node forAnchor:(ARAnchor *)anchor;
/**
- Called when a mapped node has been removed from the scene graph for the given anchor.
+ Tells the delegate that the SceneKit node corresponding to a removed AR anchor has been removed from the scene.
+ Depending on the session configuration, ARKit may automatically remove anchors from a session. The view calls this method once for each removed
+ anchor.
+
- Parameters:
- - renderer: The renderer that will render the scene.
- - node: The node that was removed.
- - anchor: The anchor that was removed.
+ - renderer: The ``ARSCNView`` object rendering the scene.
+ - node: The removed SceneKit node.
+ - anchor: The AR anchor corresponding to the node.
*/
- (void)renderer:(id<SCNSceneRenderer>)renderer didRemoveNode:(SCNNode *)node forAnchor:(ARAnchor *)anchor;
@end
/**
- Extended debug options for an ARSCNView
+ Options for drawing overlay content to aid debugging of AR tracking in a SceneKit view.
+
+ To use these debugging overlays, add them to the option set in the view's
+ <doc://com.apple.documentation/documentation/scenekit/scnscenerenderer/debugoptions> property (inherited from the
+ <doc://com.apple.documentation/documentation/scenekit/scnview> class).
*/
typedef SCNDebugOptions ARSCNDebugOptions API_AVAILABLE(ios(11.0));
-/** Show the world origin in the scene. */
+/**
+ Display a coordinate axis visualization indicating the position and orientation of the AR world coordinate system.
+
+ This visualization is available to all session configurations and session ``ARConfiguration/worldAlignment`` options, but is most useful with a
+ ``ARWorldTrackingConfiguration`` session. For example, if you start running a session when this option is enabled, then take a step backward, the
+ real-world position tracked by the AR world coordinate system should become visible on your device screen.
+*/
API_AVAILABLE(ios(11.0))
FOUNDATION_EXTERN const SCNDebugOptions ARSCNDebugOptionShowWorldOrigin NS_SWIFT_NAME(ARSCNDebugOptions.showWorldOrigin);
-/** Show detected 3D feature points in the world. */
+/**
+ Display a point cloud showing intermediate results of the scene analysis that ARKit uses to track device position.
+
+ This option is available only when running a ``ARWorldTrackingConfiguration`` session.
+*/
API_AVAILABLE(ios(11.0))
FOUNDATION_EXTERN const SCNDebugOptions ARSCNDebugOptionShowFeaturePoints NS_SWIFT_NAME(ARSCNDebugOptions.showFeaturePoints);
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARSKView.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARSKView.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARSKView.h 2026-08-15 23:13:05
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARSKView.h 2026-10-04 02:39:15
@@ -19,7 +19,13 @@
#pragma mark ARSKViewDelegate
/**
- A delegate protocol for SpriteKit-based AR view events and node mapping.
+ Methods you can implement to mediate the automatic synchronization of SpriteKit content with an AR session.
+
+ Implement this protocol to provide SpriteKit content corresponding to ``ARAnchor`` objects tracked by the view's
+ AR session, or to manage the view's automatic updating of such content.
+
+ This protocol extends the ``ARSessionObserver`` protocol, so your session delegate can also implement those methods
+ to respond to changes in session status.
*/
API_AVAILABLE(ios(11.0))
API_DEPRECATED("This API is deprecated on visionOS.", visionos(1.0, 1.0))
@@ -27,57 +33,86 @@
@optional
/**
- Implement this to provide a custom node for the given anchor.
+ Asks the delegate to provide a SpriteKit node corresponding to a newly added anchor.
- This node will automatically be added to the scene graph.
- If this method is not implemented, a node will be automatically created.
- If nil is returned the anchor will be ignored.
+ Depending on the session configuration, ARKit may automatically add anchors to a session, such as the origin of the
+ world coordinate system and detected planes. ARKit also calls this method to provide visual content for any
+ ``ARAnchor`` objects you manually add using the session's ``ARSession/add(anchor:)`` method.
+ You can implement this method to provide a new <doc://com.apple.documentation/documentation/spritekit/sknode> object
+ (or instance of any system or custom <doc://com.apple.documentation/documentation/spritekit/sknode> subclass) you plan
+ to use as a visual representation of the anchor.
+
+ Note that ARKit controls the node's position, rotation, and scale to simulate a billboarded 3D effect even for 2D
+ sprites. If you provide a `SKTransformNode` node, ARKit applies a 3D transformation.
+
+ Alternatively, if you do not implement this method, ARKit creates an empty node, and you can implement the
+ ``ARSKViewDelegate/view(_:didAdd:for:)`` method instead to provide visual content by adding children to that node.
+
- Parameters:
- - view: The view that will render the scene.
- - anchor: The added anchor.
+ - view: The ``ARSKView`` object rendering the scene.
+ - anchor: The anchor for which a node is requested.
- - Returns: Node that will be mapped to the anchor or `nil`.
+ - Returns: A new SpriteKit node, which ARKit will add to the scene and update to follow its corresponding AR anchor, or `nil` to have ARKit ignore
+ the anchor (no node is created for it).
*/
- (nullable SKNode *)view:(ARSKView *)view nodeForAnchor:(ARAnchor *)anchor;
/**
- Called when a new node has been mapped to the given anchor.
+ Tells the delegate that a SpriteKit node corresponding to a new AR anchor has been added to the scene.
+ Depending on the session configuration, ARKit may automatically add anchors to a session. The view calls this method
+ once for each new anchor. ARKit also calls this method to provide visual content for any ``ARAnchor`` objects you
+ manually add using the session's ``ARSession/add(anchor:)`` method.
+
+ You can provide visual content for the anchor by adding child nodes.
+
+ Alternatively, you can implement the ``ARSKViewDelegate/view(_:nodeFor:)`` method to create your own node (or instance
+ of an <doc://com.apple.documentation/documentation/spritekit/sknode> subclass) for an anchor.
+
- Parameters:
- - view: The view that will render the scene.
- - node: The node that maps to the anchor.
- - anchor: The added anchor.
+ - view: The ``ARSKView`` object rendering the scene.
+ - node: The newly added SpriteKit node.
+ - anchor: The AR anchor corresponding to the node.
*/
- (void)view:(ARSKView *)view didAddNode:(SKNode *)node forAnchor:(ARAnchor *)anchor;
/**
- Called when a node will be updated with data from the given anchor.
+ Tells the delegate that a SpriteKit node's properties will be updated to match the current state of its corresponding anchor.
+ Depending on the session configuration, ARKit may automatically update anchors in a session. The view calls this
+ method once for each updated anchor.
+
- Parameters:
- - view: The view that will render the scene.
- - node: The node that will be updated.
- - anchor: The anchor that was updated.
+ - view: The ``ARSKView`` object rendering the scene.
+ - node: The updated SpriteKit node.
+ - anchor: The AR anchor corresponding to the node.
*/
- (void)view:(ARSKView *)view willUpdateNode:(SKNode *)node forAnchor:(ARAnchor *)anchor;
/**
- Called when a node has been updated with data from the given anchor.
+ Tells the delegate that a SpriteKit node's properties have been updated to match the current state of its corresponding anchor.
+ Depending on the session configuration, ARKit may automatically update anchors in a session. The view calls this
+ method once for each updated anchor.
+
- Parameters:
- - view: The view that will render the scene.
- - node: The node that was updated.
- - anchor: The anchor that was updated.
+ - view: The ``ARSKView`` object rendering the scene.
+ - node: The updated SpriteKit node.
+ - anchor: The AR anchor corresponding to the node.
*/
- (void)view:(ARSKView *)view didUpdateNode:(SKNode *)node forAnchor:(ARAnchor *)anchor;
/**
- Called when a mapped node has been removed from the scene graph for the given anchor.
+ Tells the delegate that the SpriteKit node corresponding to an AR anchor has been removed from the scene.
+ Depending on the session configuration, ARKit may automatically remove anchors from a session. The view calls this
+ method once for each removed anchor.
+
- Parameters:
- - view: The view that will render the scene.
- - node: The node that was removed.
- - anchor: The anchor that was removed.
+ - view: The ``ARSKView`` object rendering the scene.
+ - node: The removed SpriteKit node.
+ - anchor: The AR anchor corresponding to the node.
*/
- (void)view:(ARSKView *)view didRemoveNode:(SKNode *)node forAnchor:(ARAnchor *)anchor;
@@ -86,53 +121,73 @@
#pragma mark ARSKView
/**
- A view that integrates ARSession rendering into SpriteKit.
+ A view that blends virtual 2D content from SpriteKit into the 3D space of an augmented reality experience.
- The view draws the camera background, and projects and maps anchors to nodes.
+ Use the ``ARSKView`` class to create augmented reality experiences that position 2D elements in 3D space within a
+ device camera view of the real world. When you run the view's provided ``ARSession`` object:
+
+ - The view automatically renders the live video feed from the device camera as the scene background.
+ - When you implement ``ARSKViewDelegate`` methods to associate SpriteKit content with real-world positions, the view
+ automatically scales and rotates those SpriteKit nodes so that they appear to track the real world seen by the camera.
*/
API_AVAILABLE(ios(11.0))
API_DEPRECATED("This API is deprecated on visionOS.", visionos(1.0, 1.0))
@interface ARSKView : SKView <ARSessionProviding>
/**
- Specifies the view’s delegate.
+ An object you provide to mediate synchronization of the view's AR scene information with SpriteKit content.
*/
@property (nonatomic, weak, nullable) NSObject<ARSKViewDelegate> *delegate;
/**
- The session that the view uses to update the view.
+ The AR session that manages motion tracking and camera image processing for the view's contents.
+
+ A view creates its own session object; use this property to access and configure the view's session.
*/
@property (nonatomic, strong) ARSession *session;
/**
- Searches the scene hierarchy for an anchor associated with the provided node.
+ Returns the AR anchor associated with the specified SpriteKit node, if any.
- - Parameter node: A node in the view's scene.
+ - Parameters:
+ - node: A SpriteKit node in the view's scene.
- - Returns: The anchor associated with the node, or `nil` if none exists.
+ - Returns: The ``ARAnchor`` object tracking the node, or `nil` if the node is not associated with an anchor or not in the view's scene.
*/
- (nullable ARAnchor *)anchorForNode:(SKNode *)node;
/**
- Returns the node that has been mapped to a specific anchor.
+ Returns the SpriteKit node associated with the specified AR anchor, if any.
- - Parameter anchor: An anchor with an existing node mapping.
+ - Parameters:
+ - anchor: An anchor in the view's AR session.
- - Returns: The node mapped to the anchor, or `nil` if none exists.
+ - Returns: The node whose position in the AR scene the anchor tracks, or `nil` if the anchor has no associated node or is not in the view's AR
+ session.
*/
- (nullable SKNode *)nodeForAnchor:(ARAnchor *)anchor;
/**
- Searches the current frame for objects corresponding to a point in the view.
+ Searches for real-world objects or AR anchors in the captured camera image corresponding to a point in the SpriteKit view.
- A 2D point in the view’s coordinate space can refer to any point along a line segment
- in the 3D coordinate space. Hit-testing is the process of finding objects in the world located along this line segment.
+ Hit testing searches for real-world objects or surfaces detected through the AR session's processing of the camera
+ image. A 2D point in the view's coordinate system can refer to any point along a 3D line that starts at the device
+ camera and extends in a direction determined by the device orientation and camera projection. This method searches
+ along that line, returning all objects that intersect it in order of distance from the camera.
+ > Note:
+ > This method searches for AR anchors and real-world objects detected by the AR session, not SpriteKit content
+ > displayed in the view. To search for SpriteKit objects, use the
+ > <doc://com.apple.documentation/documentation/spritekit/sknode/nodes(at:)> method of the view's SpriteKit scene.
+
+ The behavior of a hit test depends on which `types` you specify and the order you specify them in. For details, see
+ ``ARHitTestResult`` and the various ``ARHitTestResult/ResultType`` options.
+
- Parameters:
- - point: A point in the view’s coordinate system.
- - types: The types of results to search for.
+ - point: A point in the 2D coordinate system of the view.
+ - types: The types of hit-test result to search for.
- - Returns: An array of all hit-test results sorted from nearest to farthest.
+ - Returns: A list of results, sorted from nearest to farthest (in distance from the camera).
*/
- (NSArray<ARHitTestResult *> *)hitTest:(CGPoint)point types:(ARHitTestResultType)types API_DEPRECATED("Use raycasting", ios(11.0, 14.0));
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARSession.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARSession.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARSession.h 2026-08-15 23:02:19
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARSession.h 2026-10-04 02:32:29
@@ -28,150 +28,301 @@
@protocol ARSessionDelegate;
/**
- Set of options for running the session.
+ Options for transitioning an AR session's current state when you change its configuration.
- These options alter the behavior of calling run on a session.
- Providing no options will result in the default behavior of resuming tracking
- from the last known position and keeping all existing anchors.
+ If you provide no options, the session uses its default behavior: it resumes tracking from the last known position and keeps all existing anchors.
*/
API_AVAILABLE(ios(11.0))
typedef NS_OPTIONS(NSUInteger, ARSessionRunOptions) {
- /** The session will reset tracking. */
+ /**
+ An option to reset the device's position from the session's previous run.
+
+ By default, when you call the ``ARSession/run(_:options:)`` method on a session that has run before or is already
+ running, the session resumes device position tracking from its last known state. (For example, an ``ARAnchor``
+ object keeps its apparent position relative to the camera.) When you call the ``ARSession/run(_:options:)`` method
+ with a configuration of the same type as the session's current configuration, you can add this option to force
+ device position tracking to return to its initial state.
+
+ When you call the ``ARSession/run(_:options:)`` method with a configuration of a different type than the session's
+ current configuration, the session always resets tracking (that is, this option is implicitly enabled).
+
+ In either case, when you reset tracking, ARKit also removes any existing anchors from the session.
+ */
ARSessionRunOptionResetTracking = (1 << 0),
- /** The session will remove existing anchors. */
+ /**
+ An option to remove any anchor objects associated with the session's previous run.
+
+ By default, when you call the ``ARSession/run(_:options:)`` method on a session that has run before or is already
+ running, the session keeps any ``ARAnchor`` objects that you previously added. That is, objects in the AR scene
+ keep their apparent real-world positions relative to the device (unless you enable the
+ ``ARSessionRunOptionResetTracking`` option).
+
+ Enable the ``ARSessionRunOptionRemoveExistingAnchors`` option if changing session configurations should invalidate
+ the apparent real-world positions of objects in the AR scene. For example, if you've added virtual content to the
+ AR scene whose positions are correlated to real-world objects, remove those anchors so you can reevaluate
+ appropriate real-world positions. On the other hand, if the virtual content in your scene needs to track real-world
+ positions only when that content first appears and can move freely thereafter, you can disable this option to keep
+ the anchors.
+ */
ARSessionRunOptionRemoveExistingAnchors = (1 << 1),
- /** The session will stop currently active tracked raycasts. */
+ /**
+ An option to stop all active tracked raycasts.
+
+ By default, when you call the ``ARSession/run(_:options:)`` method on a session that is running or has run before,
+ the session keeps tracking any ``ARTrackedRaycast`` objects that you previously added by calling
+ ``ARSession/trackedRaycast(_:updateHandler:)``.
+
+ Use ``ARSessionRunOptionStopTrackedRaycasts`` if you want to stop all active tracked raycasts. Alternatively, you
+ can stop individual raycasts by calling ``ARTrackedRaycast/stopTracking()`` on individual raycasts.
+ */
ARSessionRunOptionStopTrackedRaycasts = (1 << 2),
- /** The session will reset scene reconstruction. */
+ /**
+ An option to reset the scene mesh.
+
+ When you reset scene reconstruction, ARKit removes any existing mesh anchors (``ARMeshAnchor``) from the session.
+ */
ARSessionRunOptionResetSceneReconstruction = (1 << 3)
} NS_SWIFT_NAME(ARSession.RunOptions);
/**
- The ARSession class configures and runs different Augmented Reality techniques on a device.
+ The object that manages the major tasks associated with every AR experience, such as motion tracking, camera
+ passthrough, and image analysis.
+
+ An `ARSession` object coordinates the major processes that ARKit performs on your behalf to create an augmented reality
+ experience. These processes include reading data from the device's motion sensing hardware, controlling the device's
+ built-in camera, and performing image analysis on captured camera images. The session synthesizes all of these results
+ to establish a correspondence between the real-world space the device inhabits and a virtual space where you model AR
+ content.
+
+ ### Create a Session
+
+ Every AR experience requires an `ARSession`. If you implement a custom renderer, you instantiate the session yourself.
+
+ ```swift
+ let session = ARSession()
+ session.delegate = self
+ ```
+
+ If you use one of the standard renderers (like <doc://com.apple.documentation/documentation/realitykit/arview>,
+ ``ARSCNView``, or ``ARSKView``), the renderer creates a session object for you. When you want to interact with your
+ app's session, you access it on your app's renderer.
+
+ ```swift
+ let session = myView.session
+ ```
+
+ ### Run a Session
+
+ Running a session requires a configuration. Subclasses of ``ARConfiguration`` determine how ARKit tracks a device's
+ position and motion relative to the real world, and thus it determines the kinds of AR experiences you create. For
+ example, ``ARWorldTrackingConfiguration`` enables you to augment the user's view of the world around them though the
+ device's back camera.
*/
API_AVAILABLE(ios(11.0))
API_DEPRECATED_WITH_REPLACEMENT("Please use ar_session_t in C and ARKitSession in Swift instead.", visionos(1.0, 1.0))
@interface ARSession : NSObject
/**
- Unique identifier of the running session.
+ A unique identifier of the running session.
- The identifier may change after calling `runWithConfiguration`.
+ This property might change after you call the run function, but not immediately. Therefore, to get the new value,
+ listen for its change using key-value observation.
+
+ ```swift
+ // Use key-value observation to monitor my ARSession's identifier.
+ var sessionIDObservation: NSKeyValueObservation?
+ ...
+ sessionIDObservation = observe(
+ \.arView.session.identifier,
+ options: [.old, .new]) {
+ object, change in
+ print("SessionID changed to: \(change.newValue!)")
+ }
+ ```
*/
@property (atomic, strong, readonly) NSUUID *identifier API_AVAILABLE(ios(13.0));
/**
- A delegate for receiving ARSession updates.
+ An object you provide to receive captured video images and tracking information, or to respond to changes in session
+ status.
+
+ If you use the ``ARSCNView`` or ``ARSKView`` class to display your AR experience, a session delegate isn't necessary.
+ Those views automatically display captured video images and coordinate SceneKit or SpriteKit content to track device
+ and camera motion.
+
+ If you create your own visualization for an AR experience using Metal or other rendering technologies, set a session
+ delegate. Your delegate object periodically receives ``ARFrame`` objects captured by the session. These objects contain
+ video frame images for you to display and AR scene information you can use to coordinate display of the scene elements
+ you render.
*/
@property (nonatomic, weak, nullable) id<ARSessionDelegate> delegate;
/**
- The dispatch queue on which the delegate calls are performed.
+ The dispatch queue through which the session calls your delegate methods.
- If not provided or `nil`, delegate calls will be performed on the main queue.
+ If this value is `nil` (the default), the session calls your delegate methods on the main queue.
*/
@property (nonatomic, strong, nullable) dispatch_queue_t delegateQueue;
/**
- The current frame of the session.
+ The most recent still frame captured by the active camera feed, including ARKit's interpretation of it.
*/
@property (nonatomic, copy, nullable, readonly) ARFrame *currentFrame;
/**
- The configuration currently being used by the session.
+ An object that defines motion and scene tracking behaviors for the session.
*/
@property (nonatomic, copy, nullable, readonly) ARConfiguration *configuration;
/**
- Runs the session with the provided configuration.
+ Starts AR processing for the session with the specified configuration.
- Calling run on a session that has already started will
- transition immediately to using the new configuration.
+ The session tracks device motion, captures and processes scene imagery from the device camera, and coordinates with
+ your ``ARSession/delegate`` object or ``ARSCNView`` or ``ARSKView`` view only when running.
- - Parameter configuration: The configuration to use.
+ Calling this method on a session that has already started transitions immediately to the new session configuration.
+ After you call this method, the session runs asynchronously.
+
+ To determine how existing session state transitions to the new configuration, use the ``ARSession/run(_:options:)``
+ method instead. Calling ``ARSession/runWithConfiguration:`` is equivalent to calling ``ARSession/run(_:options:)`` with
+ no options enabled.
+
+ - Parameter configuration: An object that defines motion and scene tracking behaviors for the session.
*/
- (void)runWithConfiguration:(ARConfiguration *)configuration NS_SWIFT_UNAVAILABLE("Use run(_:options:) instead");
/**
- Runs the session with the provided configuration and options.
+ Starts AR processing for the session with the specified configuration and options.
- Calling run on a session that has already started will
- transition immediately to using the new configuration. Options
- can be used to alter the default behavior when transitioning configurations.
+ The session tracks device motion, captures and processes scene imagery from the device camera, and coordinates with
+ your ``ARSession/delegate`` object or ``ARSCNView`` or ``ARSKView`` view only when running.
+ Calling this method on a session that has already started transitions immediately to the new session configuration.
+ The `options` parameter determines how existing session state transitions to the new configuration. By default, the
+ session resumes device position tracking from the last known state and keeps any anchors already included in the
+ session (those you've added manually with ``ARSession/add(anchor:)``, as well as those added automatically by ARKit
+ features such as plane detection or face tracking).
+
+ This method returns immediately when called, but the session continues to run.
+
- Parameters:
- - configuration: The configuration to use.
- - options: The run options to use.
+ - configuration: An object that defines motion and scene tracking behaviors for the session.
+ - options: Options affecting how existing session state (if any) transitions to the new configuration.
+
+ If the session is running for the first time, this parameter has no effect.
*/
- (void)runWithConfiguration:(ARConfiguration *)configuration options:(ARSessionRunOptions)options NS_SWIFT_NAME(run(_:options:));
/**
- Pauses the session.
+ Pauses processing in the session.
- Once paused, no more updates will be received from the
- session until `run` is called again.
+ While paused, the session doesn't track device motion or capture scene imagery, nor does it coordinate with its
+ ``ARSession/delegate`` object or update any associated
+ <doc://com.apple.documentation/documentation/realitykit/realityview> or
+ <doc://com.apple.documentation/documentation/realitykit/arview> object.
*/
- (void)pause;
/**
- Adds an anchor to the session.
+ Adds the specified anchor to be tracked by the session.
- The anchor will be added in the next frame update.
+ Changes to anchor tracking take effect when the next frame is captured.
- Parameter anchor: The anchor to add.
*/
- (void)addAnchor:(__kindof ARAnchor *)anchor NS_SWIFT_NAME(add(anchor:));
/**
- Removes an anchor from the session.
+ Removes the specified anchor from tracking by the session.
- The anchor will be removed from subsequent frame updates.
+ Changes to anchor tracking take effect when the next frame is captured.
- Parameter anchor: The anchor to remove.
*/
- (void)removeAnchor:(__kindof ARAnchor *)anchor NS_SWIFT_NAME(remove(anchor:));
/**
- Sets the world origin of the session to be at the position and orientation specified by the provided transform.
+ Changes the basis for the AR world coordinate space using the specified transform.
- - Parameter relativeTransform: The rotation and translation from the current world origin to the desired world origin.
- Any scale on the transform is ignored.
+ ARKit defines a world coordinate space for you to use to place virtual content and locate detected objects in an AR
+ experience. By default, this space is based on the initial position and orientation of the device when the session
+ begins. However, after a session begins and has detected useful reference points (such as a plane or image), you may
+ find it helpful to redefine the world coordinate system based on those reference points.
+
+ - Parameter relativeTransform: A transform matrix encoding a translation and orientation relative to the session's
+ current world coordinate space. Any scale component of the transform is ignored.
*/
- (void)setWorldOrigin:(simd_float4x4)relativeTransform NS_SWIFT_NAME(setWorldOrigin(relativeTransform:)) API_AVAILABLE(ios(11.3));
/**
- Copies the current state of the world being tracked by the session.
+ Returns an object encapsulating the world-tracking session's space-mapping state and set of anchors.
- A world map is only provided when running an `ARWorldTrackingConfiguration`.
+ An ``ARWorldMap`` encapsulates the state of a running ``ARSession``. This state includes ARKit's awareness of the
+ physical space the user moves the device in (which ARKit uses to determine the device's position and orientation), as
+ well as any ``ARAnchor`` objects added to the session (which can represent detected real-world features or virtual
+ content placed by your app). After you use this method to save a session's world map, you can assign it to a
+ configuration's ``ARWorldTrackingConfiguration/initialWorldMap`` property and use ``ARSession/run(_:options:)`` to start
+ another session with the same spatial awareness and anchors.
- - Parameter completionHandler: The completion handler to call when the get has completed. This handler is executed
- on the session's delegate queue. The completion handler takes the following parameters:
- worldMap - The current world map or `nil` if unavailable.
- error - An error that indicates why the world map is unavailable, or `nil` if a world map was provided.
+ By saving world maps and using them to start new sessions, your app can add new AR capabilities:
+
+ - **Multiuser AR experiences.** Create a shared frame of reference by sending archived ``ARWorldMap`` objects to a
+ nearby user's device. With two devices tracking the same world map, you can build a networked experience where both
+ users can see and interact with the same virtual content.
+ - **Persistent AR experiences.** Save a world map when your app becomes inactive, then restore it the next time your
+ app launches in the same physical environment. You can use anchors from the resumed world map to place the same
+ virtual content at the same positions from the saved session.
+
+ Before saving a world map, monitor the ``ARFrame/worldMappingStatus`` property to verify that ARKit has an adequate
+ understanding of the user's environment, ensuring that you can reliably make use of the saved map on a different device
+ or at a later time.
+
+ World map generation requires a world-tracking AR session. If you call this method on an ``ARSession`` not run with
+ ``ARWorldTrackingConfiguration``, it invokes your completion handler immediately, providing no world map and an error.
+
+ > Important:
+ > ARKit calls your `completionHandler` on the session's ``ARSession/delegateQueue`` (if set; on the main queue
+ > otherwise). If you need to perform expensive work from this handler (such as archiving and saving or sending the
+ > world map), do so on an appropriate dispatch queue to avoid disrupting performance.
+
+ - Parameter completionHandler: A closure to be invoked asynchronously after ARKit finishes generating the world map.
+ The closure takes two parameters: worldMap - The generated ``ARWorldMap``, or `nil` if a map could not be generated.
+ error - If the `worldMap` is `nil`, an error object describing the failure.
*/
- (void)getCurrentWorldMapWithCompletionHandler:(void (^)(ARWorldMap *_Nullable worldMap, NSError *_Nullable error))completionHandler
API_AVAILABLE(ios(12.0));
/**
- Creates a new reference object from scanned features within the provided bounds.
+ Creates a reference object (for 3D object detection) from the specified region of the session's world space.
- Reference objects can be stored and used to track 3D objects from previously scanned data.
- Creation requires that an ARObjectScanningConfiguration is used so that sufficient features are scanned.
+ > Important: This method is valid only when running a session with ``ARObjectScanningConfiguration``, which enables the
+ > high-fidelity spatial data collection needed for scanning reference objects. Calling this method on a session with a
+ > different configuration immediately invokes your `completionHandler` with an error.
+ To use the extracted reference object for 3D object detection, assign it to the
+ ``ARWorldTrackingConfiguration/detectionObjects`` property of a world tracking configuration. You can bundle reference
+ objects in an app by saving them to files and adding them to an Xcode asset catalog.
+
+ When ARKit detects a reference object, the transform of the resulting ``ARObjectAnchor`` is based on the origin of the
+ reference object's coordinate system—the transform you specify when extracting the reference object. For example, if a
+ reference object represents a physical item that sits on a horizontal surface, virtual content should appear to sit on
+ whatever surface the physical object does. To adjust a reference object's origin after extracting it, use the
+ ``ARReferenceObject/applyingTransform(_:)`` method.
+
- Parameters:
- - transform: The transformation matrix that defines the rotation and translation of the bounds in
- world coordinates. This will be used as the reference object's transform, defining its coordinate space.
- - center: The center of the object's bounds in the transform's coordinate space. A zero vector will
- define the object's origin centered within its extent.
- - extent: The extent of the object's bounds in the transform's coordinate space. This defines the bounds'
- size in each dimension.
- - completionHandler: The completion handler to call when the creation has completed. This handler is executed
- on the session's delegate queue. The completion handler takes the following parameters:
- referenceObject - The reference object created or `nil` if unavailable.
- error - An error that indicates why creation failed, or `nil` if a reference object was provided.
+ - transform: A transform matrix defining the origin and orientation of the local coordinate system for the region to
+ extract.
+ - center: A point, relative to the origin specified by `transform`, that defines the center of the bounding box for
+ the region to extract.
+ - extent: The width, height, and depth of the region to extract, centered on the `center` point and oriented to the
+ local coordinate system specified by `transform`.
+ - completionHandler: A handler to be invoked asynchronously after ARKit finishes creating the reference object. The
+ handler takes two parameters: referenceObject - A ``ARReferenceObject`` that represents the specified region of the
+ world map, or `nil` if a reference object could not be created. error - If the `referenceObject` is `nil`, an
+ ``ARError`` describing the failure.
*/
- (void)createReferenceObjectWithTransform:(simd_float4x4)transform
center:(simd_float3)center
@@ -183,27 +334,38 @@
#pragma mark - Raycasting
/**
- Perform a raycast.
+ Checks once for intersections between a ray and real-world surfaces.
- - Parameter query: Raycast query used for raycasting.
+ Ray casting provides a 3D location in physical space that corresponds to a given 2D location on the screen. When you
+ call this function, it succeeds in returning a result when a mathematical ray that ARKit casts outward from the user
+ intersects with any real-world surfaces that ARKit detects in the physical environment.
- - Returns: List of raycast results, sorted from nearest to farthest (in distance from the camera). The results could be empty if raycast fails.
+ - Parameter query: The ray you create from a screen point you're interested in.
+
+ - Returns: An array of ray-cast results, sorted from nearest to furthest from the camera. The array is empty if the ray
+ cast fails to find an intersection between the query's ray and a real-world surface.
*/
- (NSArray<ARRaycastResult *> *)raycast:(ARRaycastQuery *)query API_AVAILABLE(ios(13.0));
/**
- Perform a tracked raycast.
+ Repeats a ray-cast query over time to notify you of updated surfaces in the physical environment.
- The session performs continuous raycasting and calls the update handler with the updated results.
- The ARTrackedRaycast object returned can be used to update the raycast with a new raycast query or stop raycasting.
+ A tracked ray cast wraps a ray-cast query that the session calls repeatedly, each time invoking your update handler to
+ provide you with new results.
+ When you're ready to stop a tracked ray cast, call ``ARTrackedRaycast/stopTracking()``.
+
- Parameters:
- - query: Raycast query used for raycasting.
- - updateHandler: Update handler where updated list of results, sorted from nearest to farthest (in distance from
- the camera) are delivered. `updateHandler` will be called on session's delegate queue.
+ - query: The ray-cast query that ARKit will repeat. If you use a standard renderer, you ask the standard renderer to
+ provide the ray-cast query; see Finding Real-World Surfaces of ``ARSCNView``. If you use a custom renderer, you
+ create a ray-cast query by specifying a point on a particular frame; see `Finding Real-World Surfaces` in
+ ``ARFrame``.
+ - updateHandler: A closure you provide that ARKit calls every time it has an updated ray-cast result for you. Use
+ this opportunity to update the position of any virtual content your app may have placed using the prior results of
+ the tracked ray cast. ARKit invokes this closure on your session's delegate queue.
- - Returns: Tracked raycast object used to update or stop raycasting. This could be `nil` if the raycast fails or if the configuration is not
- `ARWorldTrackingConfiguration` or its subclasses.
+ - Returns: The tracked ray cast, or `nil` if the ray cast fails or the session's configuration isn't ``ARWorldTrackingConfiguration`` or one of its
+ subclasses.
*/
- (nullable ARTrackedRaycast *)trackedRaycast:(ARRaycastQuery *)query
updateHandler:(void (^)(NSArray<ARRaycastResult *> *))updateHandler API_AVAILABLE(ios(13.0));
@@ -211,10 +373,15 @@
#pragma mark - Collaboration
/**
- Update session with collaboration data.
+ Updates your session with information about the physical environment that is collected by another user.
- Use this to update the session with collaboration data received from other participants.
+ Call this function to update a session when the app receives collaboration data from other users that are participating
+ in a multiuser AR experience. Your app receives this data when multiple users scan different parts of an environment
+ and share that information with your app over the network. For more information, see
+ ``ARWorldTrackingConfiguration/isCollaborationEnabled``.
+ Collaboration is supported for world tracking configurations only.
+
- Parameter collaborationData: Collaboration data for updating the session.
*/
- (void)updateWithCollaborationData:(ARCollaborationData *)collaborationData API_AVAILABLE(ios(13.0));
@@ -222,14 +389,19 @@
#pragma mark - Geo Tracking
/**
- Converts a position in world coordinate system into latitude, longitude and altitude.
+ Converts a position in the framework's local coordinate system to latitude, longitude and altitude.
- This method requires the session to be running a geo tracking configuration which is in state `ARGeoTrackingStateLocalized`.
+ ARKit refers to its local coordinate space as "world" coordinate space, but this is different from geographic
+ coordinates. For more information on ARKit's coordinate space, see ``ARSession/setWorldOrigin(relativeTransform:)``.
+ To succeed, this function requires an ``ARGeoTrackingConfiguration`` session with state equal to
+ ``ARGeoTrackingStatus/State/localized``.
+
- Parameters:
- - position: Position in world coordinate system to be converted.
- - completionHandler: Completion handler to be called with the result. This handler is executed on the session's delegate queue. It has the
- parameters: coordinate - Location coordinates. altitude - Altitude. error - Error if conversion is not available.
+ - position: Position in local coordinates to convert.
+ - completionHandler: Code that control will execute when this function returns. The session runs this code on its
+ delegate queue. The parameters are: coordinate - Location coordinates (latitude, longitude). altitude - The
+ altitude. error - The reason, if conversion fails.
*/
- (void)getGeoLocationForPoint:(simd_float3)position
completionHandler:(void (^)(CLLocationCoordinate2D coordinate, CLLocationDistance altitude, NSError *_Nullable error))completionHandler
@@ -238,13 +410,34 @@
#pragma mark - High Resolution Frame Capturing
/**
- Requests a single, high resolution frame to be captured.
+ Requests a frame outside of the normal frequency that contains a high-resolution captured image.
- Some video formats do not support a significantly higher still image resolution than the streaming camera resolution. Use the
- `isRecommendedForHighResolutionFrameCapturing` method on the video format to check if the format is recommended.
- - SeeAlso: ``ARVideoFormat/isRecommendedForHighResolutionFrameCapturing``
+ If the function succeeds, the completion handler's frame contains a high quality, high resolution
+ ``ARFrame/capturedImage``.
- - Parameter completion: Block being called when the call completes.
+ In the event of failure, the completion block receives a non-`nil` error object. A call may fail if a previous request
+ for a high resolution capture hasn't completed yet, or an underlying problem occurs in the system's capture pipeline.
+ You can identify the failure reason in either case by checking for ``ARError/highResolutionFrameCaptureInProgress`` or
+ ``ARError/highResolutionFrameCaptureFailed``, respectively.
+
+ ARKit populates the frame's properties other than pixel data, including pose information, anchors, and frame semantics.
+ The system provides the frame to your completion handler asynchronously.
+
+ You can call this function at any time during a session. The system delivers a high-resolution frame out-of-band, which
+ means that it doesn't affect the other frames that the session receives at a regular interval, such as
+ ``ARSession/currentFrame`` or the frame argument to ``ARSessionDelegate/session(_:didUpdate:)-9v2kw``.
+
+ For the highest resolution captured image, choose a non-binned ``ARConfiguration/videoFormat`` in your session's
+ configuration. You can call ``ARConfiguration/recommendedVideoFormatForHighResolutionFrameCapturing`` to select the
+ best option for you.
+
+ For the highest resolution still images, choose a ``ARConfiguration/videoFormat`` among your configuration's
+ ``ARConfiguration/supportedVideoFormats`` that returns `true` for
+ ``ARConfiguration/VideoFormat/isRecommendedForHighResolutionFrameCapturing``. If your app doesn't have specific
+ resolution requirements, you can use the framework-recommended format that
+ ``ARConfiguration/recommendedVideoFormatForHighResolutionFrameCapturing`` returns.
+
+ - Parameter completion: Code you provide that the framework runs after attempting to generate the frame.
*/
- (void)captureHighResolutionFrameWithCompletion:(void (^)(ARFrame *_Nullable frame, NSError *_Nullable error))completion API_AVAILABLE(ios(16.0));
@@ -286,7 +479,10 @@
#pragma mark - ARSessionObserver
/**
- A protocol for observing session state and receiving updates.
+ Methods you can implement to respond to changes in the state of an AR session.
+
+ This protocol defines optional methods common to the ``ARSessionDelegate``, ``ARSCNViewDelegate``, and
+ ``ARSKViewDelegate`` protocols. You can implement this protocol's methods when adopting one of those protocols.
*/
API_AVAILABLE(ios(11.0))
API_DEPRECATED_WITH_REPLACEMENT("Please use ar_session_t in C and ARKitSession in Swift instead.", visionos(1.0, 1.0))
@@ -295,92 +491,139 @@
@optional
/**
- This is called when a session fails.
+ Tells the delegate that the session has stopped running due to an error.
On failure the session will be paused.
- Parameters:
- - session: The session that failed.
- - error: The error being reported (see ARError.h).
+ - session: The session providing information.
+ - error: An object describing the failure.
*/
- (void)session:(ARSession *)session didFailWithError:(NSError *)error;
/**
- This is called when the camera’s tracking state has changed.
+ Informs the delegate of changes to the quality of ARKit's device position tracking.
+ ARKit tracks the position and orientation of the device relative to a virtual scene through a combination of motion
+ sensing and image processing. As such, factors that affect signal quality from the device's motion sensing hardware or
+ that interfere with scene detection in the camera image can result in poor estimates of the device position relative to
+ the virtual scene.
+
- Parameters:
- - session: The session being run.
- - camera: The camera that changed tracking states.
+ - session: The session providing information.
+ - camera: The camera whose tracking parameters have changed. (Equivalent to
+ ``ARSession/currentFrame``.``ARFrame/camera``.)
*/
- (void)session:(ARSession *)session cameraDidChangeTrackingState:(ARCamera *)camera;
/**
- This is called when a session is interrupted.
+ Tells the delegate that the session has temporarily stopped processing frames and tracking device position.
- A session will be interrupted and no longer able to track when
- it fails to receive required sensor data. This happens when video capture is interrupted,
- for example when the application is sent to the background or when there are
- multiple foreground applications (see AVCaptureSessionInterruptionReason).
- No additional frame updates will be delivered until the interruption has ended.
+ A session is interrupted when it fails to receive camera or motion sensing data. Session interruptions occur whenever
+ camera capture is not available—for example, when your app is in the background or there are multiple foreground
+ apps—or when the device is too busy to process motion sensor data.
- - Parameter session: The session that was interrupted.
+ > Important:
+ > An interruption is equivalent to manually pausing the session. Do not call ``ARSession/pause()`` in response to this
+ > callback, as that prevents your app from being notified when the interruption ends.
+
+ - Parameter session: The session providing information.
*/
- (void)sessionWasInterrupted:(ARSession *)session;
/**
- This is called when a session interruption has ended.
+ Tells the delegate that the session has resumed processing frames and tracking device position.
- A session will continue running from the last known state once
- the interruption has ended. If the device has moved, anchors will be misaligned.
- To avoid this, some applications may want to reset tracking (see ARSessionRunOptions)
- or attempt to relocalize (see `-[ARSessionObserver sessionShouldAttemptRelocalization:]`).
+ After a session has been interrupted (see the ``ARSessionObserver/sessionWasInterrupted(_:)`` delegate method), it
+ automatically resumes running whenever the conditions that caused the interruption improve.
- - Parameter session: The session that was interrupted.
+ When a session resumes, it continues tracking from its last known state. However, if the device has moved since the
+ interruption began, the ARKit world coordinate system and anchor positions no longer match their original real-world
+ frame of reference. To attempt recovery of world tracking from before the interruption, implement the
+ ``ARSessionObserver/sessionShouldAttemptRelocalization(_:)`` delegate method.
+
+ - Parameter session: The session providing information.
*/
- (void)sessionInterruptionEnded:(ARSession *)session;
/**
- This is called after a session resumes from a pause or interruption to determine whether or not the session should attempt to relocalize.
+ Asks the delegate whether to attempt recovery of world-tracking state after an interruption.
- To avoid misaligned anchors, apps may wish to attempt a relocalization after
- a session pause or interruption. If YES is returned: the session will begin relocalizing
- and tracking state will switch to limited with reason relocalizing. If successful, the
- session's tracking state will return to normal. Because relocalization depends on
- the user's location, it can run indefinitely. Apps that wish to give up on relocalization
- may call run with `ARSessionRunOptionResetTracking` at any time.
+ When ARKit loses track of the device's position or orientation, ARKit calls
+ ``ARSessionObserver/sessionShouldAttemptRelocalization(_:)`` to try to resume the experience where the user left off.
+ This process is called _relocalization_. ARKit relocalizes when it loses access to the camera or other sensors on the
+ device, such as when your app calls ``ARSession/pause()``, or when the user switches to another app and back.
- - Parameter session: The session to relocalize.
+ When relocalization succeeds, your app's virtual content appears in the same position it was in before the
+ interruption. But if your app fails to relocalize, the world coordinate system and anchor positions are likely out of
+ sync with the real world.
+ Here are the possible scenarios:
+
+ - If by default you don't implement this function, ARKit spends a few seconds trying to relocalize before restarting
+ your session.
+ - If you implement this function and return <doc://com.apple.documentation/documentation/swift/false>, ARKit does not
+ attempt to relocalize after an interruption, and the session restarts immediately.
+ - If you implement this function and return <doc://com.apple.documentation/documentation/swift/true>, you allow the
+ user more time to find the location they were in and resume where they left off, but you're responsible for
+ restarting the session when it's prudent to do so.
+
+ When you return <doc://com.apple.documentation/documentation/swift/true>, guide the user to facilitate relocalization;
+ for example, by presenting a UI that asks them to return to their previous location. Relocalization works when ARKit
+ recognizes the physical environment it observed before the interruption. If the user does not return to their previous
+ location, the app stays in ``ARCamera/TrackingState/Reason/relocalizing`` state indefinitely. It's important to give
+ the user a way to restart if they choose to. Using ``ARCoachingOverlayView`` makes much of this functionality
+ available.
+
+ To respond to failed relocalization, call the session's ``ARSession/run(_:options:)`` method with the
+ ``ARSession/RunOptions/resetTracking`` option. Resetting tracking during relocalization discards all world-tracking
+ state from before the interruption, but keeps world-tracking results obtained during the relocalization attempt.
+
+ - Parameter session: The session providing information.
+
- Returns: Return YES to begin relocalizing.
*/
- (BOOL)sessionShouldAttemptRelocalization:(ARSession *)session API_AVAILABLE(ios(11.3));
/**
- This is called when the session outputs a new audio sample buffer.
+ Tells the delegate that a new sample buffer of recorded audio is available.
+ ARKit calls this method on your delegate object only if you're running an AR session with a configuration whose
+ ``ARConfiguration/providesAudioData`` setting is <doc://com.apple.documentation/documentation/swift/true>.
+
- Parameters:
- - session: The session being run.
- - audioSampleBuffer: The captured audio sample buffer.
+ - session: The session providing information.
+ - audioSampleBuffer: The sample buffer that was output.
*/
- (void)session:(ARSession *)session didOutputAudioSampleBuffer:(CMSampleBufferRef)audioSampleBuffer;
/**
- This is called when the session generated new collaboration data.
+ Provides information for nearby users about your perspective in the environment.
- This data should be sent to all participants.
+ The data parameter contains information about your perspective in the physical environment. When ARKit invokes this
+ function, send the `data` object to nearby users. The users update their session with your data to gain your app's
+ model of the physical environment in addition to their own. For more information, see
+ ``ARWorldTrackingConfiguration/isCollaborationEnabled``.
+ For an example app that implements this callback, see <doc:creating-a-collaborative-session>.
+
- Parameters:
- - session: The session that produced world tracking collaboration data.
- - data: Collaboration data to be sent to participants.
+ - session: The app's collaborative session.
+ - data: The information to share with participants.
*/
- (void)session:(ARSession *)session didOutputCollaborationData:(ARCollaborationData *)data API_AVAILABLE(ios(13.0));
/**
- This is called when geo tracking status changes.
+ Listen and react to geo-tracking state changes.
+ To create and maintain an effective geo-tracking session, an app must react promptly when ARKit changes the
+ geo-tracking status. For more information, see ``ARGeoTrackingStatus``.
+
+ ARKit invokes this callback only for ``ARGeoTrackingConfiguration`` sessions.
+
- Parameters:
- - session: The session being run.
- - geoTrackingStatus: Latest geo tracking status.
+ - session: The geo-tracking session.
+ - geoTrackingStatus: The new status.
*/
- (void)session:(ARSession *)session didChangeGeoTrackingStatus:(ARGeoTrackingStatus *)geoTrackingStatus API_AVAILABLE(ios(14.0));
@@ -402,7 +645,15 @@
#pragma mark - ARSessionDelegate
/**
- A delegate protocol for receiving AR session updates including frames and anchors.
+ Methods you can implement to receive captured video frame images and tracking state from an AR session.
+
+ Implement this protocol if you need to work directly with ``ARFrame`` objects captured by the session or directly
+ follow changes to the session's set of tracked ``ARAnchor`` objects. Typically, you adopt this protocol when building a
+ custom view for displaying AR content—if you display content with SceneKit or SpriteKit, the ``ARSCNViewDelegate`` and
+ ``ARSKViewDelegate`` protocols provide similar information and integrate with those technologies.
+
+ This protocol extends the ``ARSessionObserver`` protocol, so your session delegate can also implement those methods to
+ respond to changes in session status.
*/
API_AVAILABLE(ios(11.0))
API_DEPRECATED_WITH_REPLACEMENT("Please use ar_session_t in C and ARKitSession in Swift instead.", visionos(1.0, 1.0))
@@ -411,53 +662,88 @@
@optional
/**
- This is called when a new frame has been updated.
+ Provides a newly captured camera image and accompanying AR information to the delegate.
+ Implement this method if you provide your own display for rendering an AR experience. The provided ``ARFrame`` object
+ contains the latest image captured from the device camera, which you can render as a scene background, as well as
+ information about camera parameters and anchor transforms you can use for rendering virtual content on top of the
+ camera image.
+
- Parameters:
- - session: The session being run.
- - frame: The frame that has been updated.
+ - session: The session providing information.
+ - frame: An object containing the new camera image and AR information.
*/
- (void)session:(ARSession *)session didUpdateFrame:(ARFrame *)frame;
/**
- This is called when new anchors are added to the session.
+ Tells the delegate that one or more anchors have been added to the session.
+ Depending on the session configuration, ARKit may automatically add anchors to a session.
+
+ If you display an AR experience using SceneKit or SpriteKit, you can instead implement one of the following methods
+ instead to track not only the addition of anchors to the session but also how to add SceneKit or SpriteKit content to
+ the corresponding scene:
+
+ - ``ARSCNView``: ``ARSCNViewDelegate/renderer(_:nodeFor:)`` or ``ARSCNViewDelegate/renderer(_:didAdd:for:)``
+ - ``ARSKView``: ``ARSKView/node(for:)`` or ``ARSKViewDelegate/view(_:didAdd:for:)``
+
- Parameters:
- - session: The session being run.
- - anchors: An array of added anchors.
+ - session: The session providing information.
+ - anchors: The anchors newly added to the session.
*/
- (void)session:(ARSession *)session didAddAnchors:(NSArray<__kindof ARAnchor *> *)anchors;
/**
- This is called when anchors are updated.
+ Tells the delegate that the session has adjusted the properties of one or more anchors.
+ Depending on the session configuration, ARKit may automatically update the properties of anchors in a session.
+
+ If you display an AR experience using SceneKit or SpriteKit, you can implement one of the following methods instead to
+ track not only the anchors in the session but also any corresponding SceneKit or SpriteKit content:
+
+ - ``ARSCNView``: ``ARSCNViewDelegate/renderer(_:willUpdate:for:)`` or ``ARSCNViewDelegate/renderer(_:didUpdate:for:)``
+ - ``ARSKView``: ``ARSKViewDelegate/view(_:willUpdate:for:)`` or ``ARSKViewDelegate/view(_:didUpdate:for:)``
+
- Parameters:
- - session: The session being run.
- - anchors: An array of updated anchors.
+ - session: The session providing information.
+ - anchors: The anchors whose properties have changed.
*/
- (void)session:(ARSession *)session didUpdateAnchors:(NSArray<__kindof ARAnchor *> *)anchors;
/**
- This is called when anchors are removed from the session.
+ Tells the delegate that one or more anchors have been removed from the session.
+ Depending on the session configuration, ARKit may automatically remove anchors from a session.
+
+ If you display an AR experience using SceneKit or SpriteKit, you can instead implement one of the following methods
+ instead to track not only the anchors in the session but also any corresponding SceneKit or SpriteKit content:
+
+ - ``ARSCNView``: ``ARSCNViewDelegate/renderer(_:didRemove:for:)``
+ - ``ARSKView``: ``ARSKViewDelegate/view(_:didRemove:for:)``
+
- Parameters:
- - session: The session being run.
- - anchors: An array of removed anchors.
+ - session: The session providing information.
+ - anchors: The anchors newly removed from the session.
*/
- (void)session:(ARSession *)session didRemoveAnchors:(NSArray<__kindof ARAnchor *> *)anchors;
@end
/**
- A data source for an ARSession
+ An object that provides a session.
+
+ As an example usage, ``ARCoachingOverlayView`` exposes ``ARCoachingOverlayView/sessionProvider`` to access your app's
+ current session.
*/
API_DEPRECATED_WITH_REPLACEMENT("Please use ar_session_t in C and ARKitSession in Swift instead.", visionos(1.0, 1.0))
@protocol ARSessionProviding <NSObject>
/**
- The AR session instance.
+ A contract to declare an AR session.
- To ensure session changes are detected, Swift classes should mark this property as `@objc` and `dynamic`.
+ Some clients may use key-value observation (KVO) to be notified when this property changes values. To support KVO,
+ Swift classes that adopt ``ARSessionProviding`` should mark its ``ARSessionProviding/session`` as `@objc` and
+ `dynamic`.
*/
@property (readonly) ARSession *session;
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARSkeleton.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARSkeleton.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARSkeleton.h 2026-08-15 23:02:19
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARSkeleton.h 2026-10-04 02:32:29
@@ -16,10 +16,16 @@
API_UNAVAILABLE_BEGIN(visionos)
/**
- An object representing a skeleton.
+ The interface for the skeleton of a tracked body.
- A skeleton's structure is defined by a skeleton definition.
+ As a collection of joints, this class describes the state of a human body whose movements ARKit can track.
+ The ``ARSkeleton3D`` subclass provides you with the position of a tracked body's joints in 3D space, specifically with its
+ ``ARSkeleton3D/jointLocalTransforms`` and ``ARSkeleton3D/jointModelTransforms`` properties.
+
+ The ``ARSkeleton2D`` subclass provides you with the position of a tracked body's joints in 2D space, by way of its ``ARSkeleton2D/jointLandmarks``
+ property.
+
- SeeAlso: ``ARSkeletonDefinition``
*/
API_AVAILABLE(ios(13.0))
@@ -27,18 +33,20 @@
@interface ARSkeleton : NSObject
/**
- Skeleton definition.
+ The particular configuration of joints that define a body's current state.
*/
@property (nonatomic, readonly) ARSkeletonDefinition *definition;
/**
- The number of joints.
+ The skeleton's total number of joints.
*/
@property (nonatomic, readonly) NSUInteger jointCount NS_REFINED_FOR_SWIFT;
/**
- Tracking state for a given joint.
+ Tells you whether ARKit tracks a joint at a particular index.
+ Use this function to determine which joints ARKit tracks using a particular index.
+
- Parameter jointIndex: The index of the joint.
- Returns: `YES` if the joint is tracked. `NO` otherwise.
@@ -62,7 +70,11 @@
@end
/**
- An object representing a skeleton in 3D.
+ The skeleton of a human body that ARKit tracks in 3D space.
+
+ An ``ARBodyAnchor`` contains one instance of this ``ARSkeleton`` subclass to provide its joint positions in 3D space. The ``jointLocalTransforms``
+ property describes a joint's 3D offset from its parent joint. The ``jointModelTransforms`` property describes a joint's 3D offset from the body
+ anchor's ``ARAnchor/transform``.
*/
API_AVAILABLE(ios(13.0))
NS_SWIFT_SENDABLE
@@ -70,18 +82,23 @@
/**
The model space transforms for each joint.
+
+ Model space refers to a joint's position relative to the hip joint. Note, the hip joint is located at the body anchor's origin.
*/
@property (nonatomic, readonly) const simd_float4x4 *jointModelTransforms NS_REFINED_FOR_SWIFT;
/**
- The local space joint data for each joint.
+ The local space transforms for each joint.
+
+ Local space refers to a joint's position relative to its parent joint.
*/
@property (nonatomic, readonly) const simd_float4x4 *jointLocalTransforms NS_REFINED_FOR_SWIFT;
/**
Returns the model transform for a joint with a given name.
- If an invalid joint name is passed the returned matrix will be filled with `NaN` values.
+ Model space refers to the joint's position relative to its hip joint. If an invalid joint name is passed in, the returned matrix will be filled with
+ `NaN` values.
- Parameter jointName: The name of the joint.
@@ -92,7 +109,8 @@
/**
Returns the local transform for a joint with a given name.
- If an invalid joint name is passed the returned matrix will be filled with `NaN` values.
+ Local space refers to the joint's position relative to its parent joint. If an invalid joint name is passed the returned matrix will be filled with
+ `NaN` values.
- Parameter jointName: The name of the joint.
@@ -117,7 +135,14 @@
@end
/**
- An object representing a skeleton in 2D.
+ An object that describes the locations of a body's joints in the camera feed.
+
+ ``ARSkeleton2D`` provides you with a 2D body's joints in a flat hierarchy so you can access them efficiently. The joint locations are normalized
+ within the range [0..1] in the coordinate space of the current frame's camera image, where 0 is the upper left, and 1 is the bottom right.
+
+ To access a skeleton's joints by name, you use ``landmarkForJointNamed:``. To access a named joint by index (for example, for performance reasons),
+ you query the definition for the named joint index using ``ARSkeletonDefinition/indexForJointName:``, then access ``jointLandmarks`` using the
+ resulting index.
*/
API_AVAILABLE(ios(13.0))
NS_SWIFT_SENDABLE
@@ -126,16 +151,18 @@
/**
The joint landmarks in normalized coordinates.
- The joint landmarks are detected in the captured image on the `ARFrame`.
+ The joint landmarks are detected in the captured image on the `ARFrame`. The joint landmarks are normalized within the range [0..1] in the coordinate
+ space of the current frame's camera image, where 0 is the upper left, and 1 is the bottom right.
- SeeAlso: ``ARFrame/capturedImage``
*/
@property (nonatomic, readonly) const simd_float2 *jointLandmarks NS_REFINED_FOR_SWIFT;
/**
- Returns the landmark point for a joint with a given name.
+ Returns the location of a joint with a given name.
- If an invalid joint name is passed the returned point will be filled with `NaN` values.
+ Joint landmarks are normalized within the range [0..1] and are in the coordinate space of the current frame's camera image, where 0 is the upper
+ left, and 1 is the bottom right. If an invalid joint name is passed the returned point will be filled with `NaN` values.
- Parameter jointName: The name of the joint.
@@ -160,11 +187,13 @@
@end
/**
- Returns the landmark joint name that corresponds to a key point defined in Vision framework.
+ Returns a joint name that corresponds to a key point defined in a human body pose.
- If an invalid key point is passed the returned point will be `nil`.
+ This function matches human body key points defined by the Vision framework with joint names defined by ARKit. This function may return `nil` if the
+ key point doesn't map to a joint name. For more information about key points, see
+ <doc://com.apple.documentation/documentation/vision/detecting-human-body-poses-in-images>.
- - Parameter recognizedPointKey: Recognized key point.
+ - Parameter recognizedPointKey: The argument key point.
- Returns: Joint name that could be mapped to a `ARSkeleton2D`. `nil` if no mapping exists.
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARSkeletonDefinition.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARSkeletonDefinition.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARSkeletonDefinition.h 2026-08-15 23:02:19
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARSkeletonDefinition.h 2026-10-04 02:32:28
@@ -12,31 +12,81 @@
API_UNAVAILABLE_BEGIN(visionos)
+/**
+ A name identifier for a joint.
+
+ Use this type to access information about a named joint, such as its index in a skeleton's array of joints, or its position on the screen or in the
+ physical environment.
+
+ When you're tracking a body in 2D space, you get the screen-space position of a named joint by using the ``ARSkeleton2D/landmark(for:)`` function.
+
+ When you're tracking a body in 3D space, you get a named joint's position in either local or model space by using the
+ ``ARSkeleton3D/localTransform(for:)`` or ``ARSkeleton3D/modelTransform(for:)`` functions, respectively.
+*/
typedef NSString *ARSkeletonJointName NS_TYPED_ENUM NS_SWIFT_NAME(ARSkeleton.JointName) API_AVAILABLE(ios(13.0));
+
+/**
+ A skeletal joint that's the root of all other joints.
+
+ The root skeletal joint is at the hip, and is located at the origin of its associated body anchor.
+*/
FOUNDATION_EXTERN ARSkeletonJointName const ARSkeletonJointNameRoot API_AVAILABLE(ios(13.0));
+
+/**
+ A skeletal joint that ARKit tracks representing the head.
+*/
FOUNDATION_EXTERN ARSkeletonJointName const ARSkeletonJointNameHead API_AVAILABLE(ios(13.0));
+
+/**
+ A skeletal joint that ARKit tracks representing the left hand.
+*/
FOUNDATION_EXTERN ARSkeletonJointName const ARSkeletonJointNameLeftHand API_AVAILABLE(ios(13.0));
+
+/**
+ A skeletal joint that ARKit tracks representing the right hand.
+*/
FOUNDATION_EXTERN ARSkeletonJointName const ARSkeletonJointNameRightHand API_AVAILABLE(ios(13.0));
+
+/**
+ A skeletal joint that ARKit tracks representing the left foot.
+*/
FOUNDATION_EXTERN ARSkeletonJointName const ARSkeletonJointNameLeftFoot API_AVAILABLE(ios(13.0));
+
+/**
+ A skeletal joint that ARKit tracks representing the right foot.
+*/
FOUNDATION_EXTERN ARSkeletonJointName const ARSkeletonJointNameRightFoot API_AVAILABLE(ios(13.0));
+
+/**
+ A skeletal joint that ARKit tracks representing the left shoulder.
+*/
FOUNDATION_EXTERN ARSkeletonJointName const ARSkeletonJointNameLeftShoulder API_AVAILABLE(ios(13.0));
+
+/**
+ A skeletal joint that ARKit tracks representing the right shoulder.
+*/
FOUNDATION_EXTERN ARSkeletonJointName const ARSkeletonJointNameRightShoulder API_AVAILABLE(ios(13.0));
@class ARSkeleton2D;
@class ARSkeleton3D;
/**
- Definition of a skeleton.
+ The hierarchy of joints and their names.
- A skeleton consists of a set of labeled joints that are defined in a certain hierarchy, i.e. joints are parented to other joints.
- One may use the parentIndices property to identify the hierarchy for a given skeleton definition.
+ A skeleton definition establishes the relationship of joints that make up a 3D or 2D body's ``ARBodyAnchor/skeleton`` or ``ARBody2D/skeleton``, in
+ which joints connect to other joints to compose a single skeleton in a parent-child hierarchy. Use ``parentIndices`` to identify the hierarchy for a
+ given skeleton definition.
+
+ ARKit names particular joints that are crucial to body tracking. You can access named joints by calling ``indexForJointName:`` and passing in one of
+ the available ``jointNames`` identifiers.
*/
API_AVAILABLE(ios(13.0))
NS_SWIFT_SENDABLE
@interface ARSkeletonDefinition : NSObject
/**
- Default skeleton definition for bodies defined in 3D.
+ The default skeleton definition for bodies defined in 3D.
+
- Note: The default height of this skeleton, measured from lowest to highest joint in standing position, is defined to be `1.71` meters.
- SeeAlso: ``ARSkeleton3D``
@@ -44,42 +94,44 @@
@property (class, nonatomic, readonly) ARSkeletonDefinition *defaultBody3DSkeletonDefinition;
/**
- Default skeleton definition for bodies defined in 2D.
+ The default skeleton definition for bodies defined in 2D.
- SeeAlso: ``ARBody2D``
*/
@property (class, nonatomic, readonly) ARSkeletonDefinition *defaultBody2DSkeletonDefinition;
/**
- The number of joints.
+ The skeleton's total number of joints.
*/
@property (nonatomic, readonly) NSUInteger jointCount;
/**
- The joint names.
+ A collection of unique joint names.
+
+ Refer to this array to convert a joint index to a joint identifier.
*/
@property (nonatomic, readonly) NSArray<NSString *> *jointNames;
/**
The parent index for each joint.
- This property may be used to identify the hierarchical dependency between joints. If a line is drawn for every joint and its parent joint
- the result is a visualization of the underlying skeleton. The joint with no parent is denoted as the root joint. The root joint's parent index has
- a value of `-1`.
+ This property may be used to identify the hierarchical dependency between joints. If a line is drawn for every joint and its parent joint, the result
+ is a visualization of the underlying skeleton. The joint with no parent is denoted as the root joint. The root joint's parent index is `-1`.
*/
@property (nonatomic, readonly) NSArray<NSNumber *> *parentIndices NS_REFINED_FOR_SWIFT;
/**
The 3D skeleton in neutral pose.
- The neutral skeleton pose assumes a standardized size of the skeleton in meters. The neutral pose is defined as the skeleton's T-pose.
+ The neutral skeleton pose assumes a standardized size of the skeleton in meters. The neutral pose is defined as the skeleton's T-pose. This skeleton
+ is provided to you for reference to all other possible skeleton poses.
*/
@property (nonatomic, nullable, readonly) ARSkeleton3D *neutralBodySkeleton3D;
/**
Returns the index for a given joint identifier.
- This function returns `NSNotFound` if an invalid joint name is passed.
+ This function returns `NSNotFound` if an invalid joint name is passed in.
- Parameter jointName: Name of a given joint.
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARTrackedRaycast.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARTrackedRaycast.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARTrackedRaycast.h 2026-08-15 23:02:19
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARTrackedRaycast.h 2026-10-04 02:32:28
@@ -15,16 +15,25 @@
API_UNAVAILABLE_BEGIN(visionos)
/**
- A tracked raycast representation.
+ A raycast query that ARKit repeats in succession to give you refined results over time.
+
+ Tracked raycasting improves hit-testing techniques by repeating the query for a 3D position in succession. ARKit provides you with an updated
+ position as it refines its understanding of world over time.
+
+ To start a tracked raycast, you call <doc://com.apple.documentation/documentation/arkit/arsession/trackedraycast(_:updatehandler:)> on your app's
+ current <doc://com.apple.documentation/documentation/arkit/arsession>.
*/
API_AVAILABLE(ios(13.0))
@interface ARTrackedRaycast : NSObject
/**
- Stop raycasting.
+ Stops repeating the raycast query.
- The raycast will be continuously tracked until stopped.
- Resetting session's tracking, changing its configuration or deallocation of ARTrackedRaycast object cause the raycast to stop.
+ A tracked raycast updates continuously until you stop it explicitly by calling `stopTracking`. A raycast will automatically stop when:
+
+ - You reset the session's tracking, or pass the `ARSessionRunOptionStopTrackedRaycasts` run option to `run(_:options:)`.
+ - You change the session's configuration.
+ - You deallocate the `ARTrackedRaycast`.
*/
- (void)stopTracking;
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARTrackingStatusTypes.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARTrackingStatusTypes.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARTrackingStatusTypes.h 2026-08-15 23:02:19
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARTrackingStatusTypes.h 2026-10-04 02:32:28
@@ -11,38 +11,71 @@
API_UNAVAILABLE_BEGIN(visionos)
/**
- A value describing the camera’s tracking state.
+ Possible values for position-tracking quality.
*/
API_AVAILABLE(ios(11.0))
typedef NS_ENUM(NSInteger, ARTrackingState) {
- /** Tracking is not available. */
+ /** Camera position tracking is not available. */
ARTrackingStateNotAvailable,
- /** Tracking is limited. See tracking reason for details. */
+ /**
+ Tracking is available, but the quality of results is questionable.
+
+ In this state, the positions and transforms of anchors in the scene (especially detected planes) may not be accurate or consistent from one
+ captured frame to the next.
+
+ See the associated ``ARTrackingStateReason`` value for information you can present to the user for improving tracking quality.
+ */
ARTrackingStateLimited,
- /** Tracking is Normal. */
+ /** Camera position tracking is providing optimal results. */
ARTrackingStateNormal,
} NS_REFINED_FOR_SWIFT;
/**
- A reason describing why the camera’s tracking state is limited.
+ Possible causes for limited position-tracking quality.
*/
API_AVAILABLE(ios(11.0))
typedef NS_ENUM(NSInteger, ARTrackingStateReason) {
- /** Tracking is not limited. */
+ /**
+ The current tracking state is not limited.
+
+ This value occurs when the ``ARCamera/trackingState-9pgmq`` property is ``ARTrackingState/ARTrackingStateNotAvailable`` or
+ ``ARTrackingState/ARTrackingStateNormal``.
+ */
ARTrackingStateReasonNone,
- /** Tracking is limited due to initialization in progress. */
+ /**
+ The AR session has not yet gathered enough camera or motion data to provide tracking information.
+
+ This value occurs temporarily after starting a new AR session or changing configurations.
+ */
ARTrackingStateReasonInitializing,
- /** Tracking is limited due to a excessive motion of the camera. */
+ /** The device is moving too fast for accurate image-based position tracking. */
ARTrackingStateReasonExcessiveMotion,
- /** Tracking is limited due to a lack of features visible to the camera. */
+ /** The scene visible to the camera does not contain enough distinguishable features for image-based position tracking. */
ARTrackingStateReasonInsufficientFeatures,
- /** Tracking is limited due to a relocalization in progress. */
+ /**
+ The AR session is attempting to resume after an interruption.
+
+ ARKit cannot track device position or orientation when the session has been interrupted (for example, by dismissing the view hosting an AR
+ session or switching to another app). When resuming the session after an interruption, you cannot be certain that the world coordinate system
+ (used for placing anchors) matches the device's real-world environment.
+
+ If your session or view delegate implements the ``ARSessionObserver/sessionShouldAttemptRelocalization(_:)`` method and returns
+ <doc://com.apple.documentation/documentation/swift/true>, ARKit attempts to reconcile pre- and post-interruption world tracking state. During
+ this process, called _relocalization_, world tracking quality is ``ARTrackingState/ARTrackingStateLimited``, with
+ ``ARTrackingStateReason/ARTrackingStateReasonRelocalizing`` as the reason for limited quality.
+
+ If successful, the relocalization process ends after a short time, tracking quality returns to the ``ARTrackingState/ARTrackingStateNormal``
+ state, and the world coordinate system and anchor positions generally reflect their state before the interruption.
+
+ However, the speed and success rate of relocalization can vary depending on real-world conditions. You may wish to hide AR content or disable UI
+ during relocalization, and reset tracking if relocalization doesn't succeed within a time frame appropriate for your app.
+ */
ARTrackingStateReasonRelocalizing API_AVAILABLE(ios(11.3)),
} NS_REFINED_FOR_SWIFT;
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARVideoFormat.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARVideoFormat.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARVideoFormat.h 2026-08-15 23:02:18
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARVideoFormat.h 2026-10-04 02:32:28
@@ -17,39 +17,66 @@
@class AVCapturePhotoSettings;
/**
- A video format supported by an AR configuration.
+ A video size and frame rate specification for use with an AR session.
+
+ This class is immutable; to set the frame rate and video resolution for an AR session, set your configuration's ``ARConfiguration/videoFormat``
+ property to one of the formats in the ``ARConfiguration/supportedVideoFormats`` array.
*/
API_AVAILABLE(ios(11.3))
NS_SWIFT_NAME(ARConfiguration.VideoFormat)
@interface ARVideoFormat : NSObject <NSCopying>
/**
- Indicates the physical position of an AVCaptureDevice's hardware on the system.
+ The position of the capture device.
*/
@property (nonatomic, readonly) AVCaptureDevicePosition captureDevicePosition API_AVAILABLE(ios(13.0));
/**
- Indicates the type of AVCaptureDevice.
+ The camera that supplies the video format.
+
+ To specify a particular video format, select from your configuration's ``ARConfiguration/supportedVideoFormats`` and set the desired format to the
+ configuration's ``ARConfiguration/videoFormat`` property.
+
+ For example, to specify the ultra-wide camera in a face-tracking session, search the supported video formats for the
+ <doc://com.apple.documentation/documentation/avfoundation/avcapturedevice/devicetype-swift.struct/builtinultrawidecamera> capture device.
+
+ ```swift
+ let config = ARFaceTrackingConfiguration()
+ for videoFormat in ARFaceTrackingConfiguration.supportedVideoFormats {
+ if videoFormat.captureDeviceType == .builtInUltraWideCamera {
+ config.videoFormat = videoFormat
+ break
+ }
+ }
+ session.run(config)
+ ```
+
+ > Important:
+ > AR frames only contain depth data (``ARFrame/capturedDepthData``) in face-tracking sessions that use the TrueDepth camera.
*/
@property (nonatomic, readonly) AVCaptureDeviceType captureDeviceType API_AVAILABLE(ios(14.5));
/**
- Image resolution.
+ The size, in pixels, of video images captured in the session.
+
+ Video format sizes are relative to the native sensor orientation of the device camera, and as such are always landscape-oriented.
*/
@property (nonatomic, readonly) CGSize imageResolution;
/**
- Frame rate.
+ The rate at which the session captures video and provides AR frame information.
*/
@property (nonatomic, readonly) NSInteger framesPerSecond;
/**
- Indicates if the video format is recommended for capturing high resolution frames.
+ Determines whether the framework considers a format suitable for high-resolution frame capture.
*/
@property (nonatomic, readonly) BOOL isRecommendedForHighResolutionFrameCapturing API_AVAILABLE(ios(16.0));
/**
- Indicates if the video format supports high dynamic range (HDR) streaming.
+ Determines whether the format supports high dynamic range (HDR).
+
+ Read this property before setting ``ARConfiguration/videoHDRAllowed`` to `true` to first check whether a video format supports HDR.
*/
@property (nonatomic, readonly, getter=isVideoHDRSupported) BOOL videoHDRSupported API_AVAILABLE(ios(16.0));
diff -ruN /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARWorldMap.h /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARWorldMap.h
--- /Applications/Xcode_27.1.0.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARWorldMap.h 2026-08-15 23:02:19
+++ /Applications/Xcode_27.2.0-beta3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks/ARKit.framework/Headers/ARWorldMap.h 2026-10-04 02:32:28
@@ -17,32 +17,106 @@
API_UNAVAILABLE_BEGIN(visionos)
/**
- Object representing the mapping of a physical 3D space.
+ The space-mapping state and set of anchors from a world-tracking AR session.
- `ARWorldMap` supports archiving and unarchiving across devices
- and versions with NSDecodingFailurePolicySetErrorAndReturn, providing an error
- if the map format is not supported.
+ The session state in a world map includes ARKit's awareness of the physical space in which the user moves the device. ARKit uses the details of the
+ user's physical space to determine the device's position and orientation, as well as any ``ARAnchor`` objects added to the session that can represent
+ detected real-world features or virtual content placed by your app.
+
+ `ARWorldMap` supports archiving and unarchiving across devices and versions with `NSDecodingFailurePolicySetErrorAndReturn`, providing an error if
+ the map format is not supported.
+
+ ### Serialize and Deserialize a World Map
+
+ When your app quits, you can save the current world map (acquired using ``ARSession/getCurrentWorldMap(completionHandler:)``). Because ``ARWorldMap``
+ conforms to <doc://com.apple.documentation/documentation/foundation/nssecurecoding>, you serialize it using
+ <doc://com.apple.documentation/documentation/foundation/nskeyedarchiver>.
+
+ ```swift
+ func writeWorldMap(_ worldMap: ARWorldMap, to url: URL) throws {
+ let data = try NSKeyedArchiver.archivedData(withRootObject: worldMap, requiringSecureCoding: true)
+ try data.write(to: url)
+ }
+ ```
+
+ To restore the world map the next time your app launches, use <doc://com.apple.documentation/documentation/foundation/nskeyedunarchiver>.
+
+ ```swift
+ func loadWorldMap(from url: URL) throws -> ARWorldMap {
+ let mapData = try Data(contentsOf: url)
+ guard let worldMap = try NSKeyedUnarchiver.unarchivedObject(ofClass: ARWorldMap.self, from: mapData)
+ else { throw ARError(.invalidWorldMap) }
+ return worldMap
+ }
+ ```
+
+ You can use anchors from a resumed world map to place the same virtual content at the same positions from the saved session, if the app launches in
+ the same physical environment.
+
+ For more information, see <doc:saving-and-loading-world-data>.
+
+ ### Share a Saved World Map
+
+ With two devices tracking the same world map, you can build a networked experience in which both users can see and interact with the same virtual
+ content. To send an ``ARWorldMap`` to another device:
+
+ 1. On one device, use <doc://com.apple.documentation/documentation/foundation/nskeyedarchiver> to convert the world map to a data object. You don't
+ need to write the data to a file to send it over the network.
+ 2. Use the networking technology of your choice to send the resulting data to another device. For example, in a
+ <doc://com.apple.documentation/documentation/multipeerconnectivity> session, call
+ <doc://com.apple.documentation/documentation/multipeerconnectivity/mcsession/send(_:topeers:with:)> to send data, and implement
+ <doc://com.apple.documentation/documentation/multipeerconnectivity/mcsessiondelegate> methods on the other device to receive data.
+ 3. On the receiving device, use <doc://com.apple.documentation/documentation/foundation/nskeyedunarchiver> to instantiate an ``ARWorldMap`` from the
+ data.
+
+ For more information, see <doc:creating-a-multiuser-ar-experience>.
+
+ ### Run a Deserialized World Map
+
+ To begin a new session from an existing ``ARWorldMap``, set a world-tracking configuration's ``ARWorldTrackingConfiguration/initialWorldMap``
+ property and use ``ARSession/run(_:options:)``. This starts a new session using the same spatial awareness and anchors loaded from the saved world
+ map.
*/
API_AVAILABLE(ios(12.0))
@interface ARWorldMap : NSObject <NSCopying, NSSecureCoding>
/**
- The position of the center of the mapped world in meters.
+ The center point of the world map's space-mapping data, in meters, relative to the world coordinate origin of the session the map was recorded in.
+
+ The ``ARWorldMap/extent`` and ``ARWorldMap/center`` properties together define a bounding box for the data recorded in the world map.
*/
@property (nonatomic, readonly) simd_float3 center;
/**
- The extent of the mapped world in meters.
+ The size of the world map's space-mapping data, in meters, relative to the world coordinate origin of the session the map was recorded in.
+
+ The ``ARWorldMap/extent`` and ``ARWorldMap/center`` properties together define a bounding box for the data recorded in the world map.
*/
@property (nonatomic, readonly) simd_float3 extent;
/**
- A list of anchors in the map.
+ The set of anchors recorded in the world map.
+
+ This array is a snapshot of ``ARAnchor`` objects (including subclasses of ``ARAnchor``) in the session as of when the world map was captured,
+ including the ``ARAnchor/transform`` for each. When you create a world map, ARKit automatically includes all anchors whose positions are assumed to
+ be static with respect to the environment—that is, anchor classes that don't conform to ``ARTrackable``. After you create a world map, you can choose
+ to add more anchors to, or remove anchors from, this list before saving or sharing the map.
+
+ When you run a session from a world map (and after ARKit successfully reconciles the map to the user's current environment), the session
+ automatically includes all anchors from that world map. You can then use those anchors to recreate the placement of virtual content so that it
+ matches the session the world map was captured in.
*/
@property (nonatomic, copy) NSArray<__kindof ARAnchor *> *anchors;
/**
- The feature points in the map.
+ A coarse representation of the space-mapping data recorded in the world map.
+
+ These points represent notable features detected in camera imagery during the session that recorded the world map. ARKit extrapolates the locations
+ of these features in 3D world coordinate space as part of the image and motion analysis that tracks the device's movement in a session. Taken
+ together, these points loosely correlate to the contours of real-world objects that were in view of the camera during the session.
+
+ ARKit does not guarantee that the number and arrangement of raw feature points will remain stable between software releases. However, you can
+ visualize the point cloud to debug your world map recording, or inspect its size to estimate the quality of a recorded world map.
*/
@property (nonatomic, strong, readonly) ARPointCloud *rawFeaturePoints;