Google is committed to advancing racial equity for Black communities. See how.

GARSession Class

GARSession Class Reference

Overview

ARCore Cloud Anchors session class.

Adds ARCore features to an app using ARKit. All NSError's returned by methods in this class have domain GARSessionErrorDomain and code a value of GARSessionErrorCode - see GARSessionError.h. For Augmented Faces, see GARAugmentedFaceSession.

Inherits NSObject.

Instance Method Summary

(void) - setAuthToken:
 Provide an auth token to use when authenticating with the ARCore Cloud Anchor service. More...
 
(GARFrame *_Nullable) - update:error:
 Updates the GARSession with an ARFrame. More...
 
(void) - removeAnchor:
 Removes an anchor from the session. More...
 
(GARAnchor *_Nullable) - hostCloudAnchor:error:
 Hosts a new Cloud Anchor based on an ARAnchor. More...
 
(GARAnchor *_Nullable) - hostCloudAnchor:TTLDays:error:
 This will create a new Cloud Anchor with a given lifetime in days, using the transform of the provided anchor. More...
 
(GARFeatureMapQuality) - estimateFeatureMapQualityForHosting:error:
 Estimates the quality of the visual features seen by ARCore in the preceding few seconds and visible from the provided camera transform. More...
 
(GARAnchor *_Nullable) - resolveCloudAnchorWithIdentifier:error:
 Resolves a Cloud Anchor with a given identifier. More...
 

Class Method Summary

(instancetype _Nullable) + sessionWithAPIKey:bundleIdentifier:error:
 Creates a GARSession with an API key and bundle identifier. More...
 
(instancetype _Nullable) + sessionWithError:
 Creates a GARSession. More...
 

Property Summary

GARFramePaircurrentFramePair
 The most recent frame pair, containing the most recent ARFrame passed into update:error: and the corresponding returned GARFrame. More...
 
id< GARSessionDelegatedelegate
 The delegate for receiving callbacks about the GARSession. More...
 
dispatch_queue_t delegateQueue
 The dispatch queue on which the delegate receives calls. More...
 

Method Detail

+ (instancetype _Nullable) sessionWithAPIKey: (NSString *)  apiKey
bundleIdentifier: (NSString *_Nullable)  bundleIdentifier
error: (NSError **)  error 

Creates a GARSession with an API key and bundle identifier.

Parameters
apiKeyYour API key for Google Cloud Services.
bundleIdentifierThe bundle identifier associated to your API key. If nil, defaults to [[NSBundle mainBundle] bundleIdentifier].
errorOut parameter for an NSError. Possible errors: GARSessionErrorCodeDeviceNotCompatible - this device or OS version is not currently supported. GARSessionErrorCodeInvalidArgument - API key is nil or empty.
Returns
The new GARSession, or nil if there is an error.
+ (instancetype _Nullable) sessionWithError: (NSError **)  error

Creates a GARSession.

To authenticate with the Cloud Anchor Service, use setAuthToken:.

Parameters
errorOut parameter for an NSError. Possible errors: GARSessionErrorCodeDeviceNotCompatible - this device or OS version is not currently supported.
Returns
The new GARSession, or nil if there is an error.
- (void) setAuthToken: (NSString *)  authToken

Provide an auth token to use when authenticating with the ARCore Cloud Anchor service.

If the session was created with an API Key, the token will be ignored and an error will be logged. Otherwise, the most recent valid auth token passed in will be used. Call this method each time you refresh your token.

Parameters
authTokenToken to use when authenticating with the ARCore Cloud Anchor service. This must be a nonempty ASCII string with no spaces or control characters. This will be used until another token is passed in. See documentation for supported token types.
- (GARFrame *_Nullable) update: (ARFrame *)  frame
error: (NSError **)  error 

Updates the GARSession with an ARFrame.

Call this method with every ARFrame to keep the sessions synced. Can be called on any thread. Normally, this should be called from your ARSessionDelegate's session:didUpdateFrame: method.

Parameters
frameThe next ARFrame from ARKit.
errorOut parameter for NSError. Possible errors: GARSessionErrorCodeInvalidArgument - invalid (nil) frame. GARSessionErrorCodeFrameOutOfOrder - frame has a smaller timestamp than previous.
Returns
The GARFrame corresponding to the ARFrame passed in, or nil if there is an error.
- (void) removeAnchor: (GARAnchor *)  anchor

Removes an anchor from the session.

Parameters
anchorThe anchor to remove.
- (GARAnchor *_Nullable) hostCloudAnchor: (ARAnchor *)  anchor
error: (NSError **)  error 

Hosts a new Cloud Anchor based on an ARAnchor.

The new anchor will have a cloud state of GARCloudAnchorStateTaskInProgress and its initial transform will be set to that of the passed-in anchor. However, the two transforms may differ over time.

Parameters
anchorThe ARAnchor to host.
errorOut parameter for an NSError. Possible errors: GARSessionErrorCodeInvalidArgument - invalid (nil) anchor. GARSessionErrorCodeNotTracking - bad current ARTrackingState. GARSessionErrorCodeResourceExhausted - tried to create too many Cloud Anchors.
Returns
The new GARAnchor, or nil if there is an error.
- (GARAnchor *_Nullable) hostCloudAnchor: (ARAnchor *)  anchor
TTLDays: (NSInteger)  TTLDays
error: (NSError **)  error 

This will create a new Cloud Anchor with a given lifetime in days, using the transform of the provided anchor.

The cloud state of the returned anchor will be set to GARCloudAnchorStateTaskInProgress and the initial transform will be set to the transform of the provided anchor. However, the returned anchor is completely independent of the original anchor, and the two transforms might diverge over time.

Hosting requires an active session for which the tracking state is ARTrackingStateNormal, as well as a working internet connection. ARCore will continue to retry silently in the background if it is unable to establish a connection to the ARCore Cloud Anchor service.

Parameters
anchorThe ARAnchor with the desired transform to be used to create a hosted Cloud Anchor.
TTLDaysThe lifetime of the anchor in days. Must be positive. The maximum allowed value is 1 if using an API Key to authenticate with the ARCore Cloud Anchor service, otherwise the maximum allowed value is 365.
errorOut parameter for an NSError. Possible errors: GARSessionErrorCodeInvalidArgument - invalid (nil) anchor or invalid TTL. GARSessionErrorCodeNotTracking - bad current ARTrackingState. GARSessionErrorCodeResourceExhausted - tried to create too many Cloud Anchors.
Returns
The new GARAnchor, or nil if there is an error.
- (GARFeatureMapQuality) estimateFeatureMapQualityForHosting: (simd_float4x4)  transform
error: (NSError **)  error 

Estimates the quality of the visual features seen by ARCore in the preceding few seconds and visible from the provided camera transform.

Cloud Anchors hosted using higher quality features will generally result in easier and more accurately resolved Cloud Anchor transforms.

Parameters
transformThe camera transform to use in estimating the quality.
errorOut parameter for an NSError. Possible errors: GARSessionErrorCodeNotTracking - bad current ARTrackingState.
Returns
The estimated quality of the visual features seen by ARCore in the preceding few seconds and visible from the provided camera transform.
- (GARAnchor *_Nullable) resolveCloudAnchorWithIdentifier: (NSString *)  identifier
error: (NSError **)  error 

Resolves a Cloud Anchor with a given identifier.

The new anchor is immediately added to the session and returned, but without a valid transform. You don’t need to wait for a call to resolve a Cloud Anchor to complete before initiating another call. A session can be resolving up to 20 Cloud Anchors at a given time. If resolving fails, the anchor will be automatically removed from the session.

Parameters
identifierThe Cloud Anchor identifier for the anchor.
errorOut parameter for an NSError. Possible errors: GARSessionErrorCodeInvalidArgument - invalid (nil or empty) identifier. GARSessionErrorCodeResourceExhausted - tried to create too many Cloud Anchors.
Returns
The new GARAnchor, or nil if there is an error.

Property Detail

- (GARFramePair*) currentFramePair
readatomicassign

The most recent frame pair, containing the most recent ARFrame passed into update:error: and the corresponding returned GARFrame.

- (id<GARSessionDelegate>) delegate
readwriteatomicweak

The delegate for receiving callbacks about the GARSession.

- (dispatch_queue_t) delegateQueue
readwriteatomicassign

The dispatch queue on which the delegate receives calls.

If nil, callbacks happen on the main thread.