2 * Copyright 2017 Google Inc. All Rights Reserved.
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
16 #ifndef ARCORE_C_API_H_
17 #define ARCORE_C_API_H_
22 /// @defgroup concepts Concepts
23 /// High-Level concepts of ARCore
25 /// @section ownership Object ownership
27 /// ARCore has two categories of objects: "value types" and "reference types".
29 /// - Value types are owned by application. They are created and destroyed using
30 /// the @c create / @c destroy methods, and are populated by ARCore using
31 /// methods with @c get in the method name.
33 /// - Reference types are owned by ARCore. A reference is acquired by one of the
34 /// @c acquire methods. For each call to the @c acquire method, the
35 /// application must call the matching @c release method. Note that even if
36 /// last reference is released, ARCore may continue to hold a reference to the
37 /// object at ARCore's discretion.
39 /// Reference types are further split into:
41 /// - Long-lived objects. These objects persist across frames, possibly for the
42 /// life span of the application or session. Acquire may fail if ARCore is in
43 /// an incorrect state, e.g. not tracking. Acquire from list always succeeds,
44 /// as the object already exists.
46 /// - Transient large data. These objects are usually acquired per-frame and are
47 /// a limited resource. The @c acquire call may fail if the resource is
48 /// exhausted (too many are currently held), deadline exceeded (the target of
49 /// the acquire was already released), or the resource is not yet available.
51 /// Note: Lists are value types (owned by application), but can hold references
52 /// to long-lived objects. This means that the references held by a list are not
53 /// released until either the list is destroyed, or is re-populated by another
56 /// For example, ::ArAnchorList, which is a value type, will hold references to
57 /// Anchors, which are long-lived objects.
59 /// @section spaces Poses and Coordinate Spaces
61 /// An @c ArPose describes an rigid transformation from one coordinate space to
62 /// another. As provided from all ARCore APIs, Poses always describe the
63 /// transformation from object's local coordinate space to the <b>world
64 /// coordinate space</b> (see below). That is, Poses from ARCore APIs can be
65 /// thought of as equivalent to OpenGL model matrices.
67 /// The transformation is defined using a quaternion rotation about the origin
68 /// followed by a translation.
70 /// The coordinate system is right-handed, like OpenGL conventions.
72 /// Translation units are meters.
74 /// @section worldcoordinates World Coordinate Space
76 /// As ARCore's understanding of the environment changes, it adjusts its model
77 /// of the world to keep things consistent. When this happens, the numerical
78 /// location (coordinates) of the camera and anchors can change significantly to
79 /// maintain appropriate relative positions of the physical locations they
82 /// These changes mean that every frame should be considered to be in a
83 /// completely unique world coordinate space. The numerical coordinates of
84 /// anchors and the camera should never be used outside the rendering frame
85 /// during which they were retrieved. If a position needs to be considered
86 /// beyond the scope of a single rendering frame, either an anchor should be
87 /// created or a position relative to a nearby existing anchor should be used.
89 /// @defgroup common Common Definitions
90 /// Shared types and constants
92 /// @defgroup anchor Anchor
93 /// Describes a fixed location and orientation in the real world.
95 /// @defgroup arcoreapk ArCoreApk
96 /// Management of the ARCore service APK
98 /// @defgroup augmented_image AugmentedImage
99 /// An image being detected and tracked by ARCore.
101 /// @defgroup augmented_image_database AugmentedImageDatabase
102 /// Database containing a list of images to be detected and tracked by ARCore.
104 /// @defgroup camera Camera
105 /// Provides information about the camera that is used to capture images.
107 /// @defgroup cloud Cloud Anchors
108 /// The cloud state and configuration of an Anchor and the AR Session.
110 /// @defgroup config Configuration
111 /// Session configuration.
113 /// @defgroup frame Frame
116 /// @defgroup hit HitResult
117 /// Defines an intersection between a ray and estimated real-world geometry.
119 /// @defgroup image ImageMetadata
120 /// Provides access to metadata from the camera image capture result.
122 /// @defgroup light LightEstimate
123 /// Holds information about the estimated lighting of the real scene.
125 /// @defgroup plane Plane
126 /// Describes the current best knowledge of a real-world planar surface.
128 /// @defgroup point Point
129 /// Represents a point in space that ARCore is tracking.
131 /// @defgroup pointcloud PointCloud
132 /// Contains a set of observed 3D points and confidence values.
134 /// @defgroup pose Pose
135 /// Represents an immutable rigid transformation from one coordinate
136 /// space to another.
138 /// @defgroup session Session
139 /// Session management.
141 /// @defgroup trackable Trackable
142 /// Something that can be tracked and that Anchors can be attached to.
144 /// @defgroup cpp_helpers C++ helper functions
146 /// @addtogroup config
149 /// An opaque session configuration object (@ref ownership "value type").
151 /// Create with ArConfig_create()<br>
152 /// Release with ArConfig_destroy()
153 typedef struct ArConfig_ ArConfig;
157 /// @addtogroup session
160 /// The ArCore session (@ref ownership "value type").
162 /// Create with ArSession_create()<br>
163 /// Release with ArSession_destroy()
164 typedef struct ArSession_ ArSession;
171 /// A structured rigid transformation (@ref ownership "value type").
173 /// Allocate with ArPose_create()<br>
174 /// Release with ArPose_destroy()
175 typedef struct ArPose_ ArPose;
181 /// @addtogroup camera
184 /// The virtual and physical camera
185 /// (@ref ownership "reference type, long-lived").
187 /// Acquire with ArFrame_acquireCamera()<br>
188 /// Release with ArCamera_release()
189 typedef struct ArCamera_ ArCamera;
193 // Frame and frame objects.
195 /// @addtogroup frame
198 /// The world state resulting from an update (@ref ownership "value type").
200 /// Allocate with ArFrame_create()<br>
201 /// Populate with ArSession_update()<br>
202 /// Release with ArFrame_destroy()
203 typedef struct ArFrame_ ArFrame;
209 /// @addtogroup light
212 /// An estimate of the real-world lighting (@ref ownership "value type").
214 /// Allocate with ArLightEstimate_create()<br>
215 /// Populate with ArFrame_getLightEstimate()<br>
216 /// Release with ArLightEstimate_destroy()
217 typedef struct ArLightEstimate_ ArLightEstimate;
223 /// @addtogroup pointcloud
226 /// A cloud of tracked 3D visual feature points
227 /// (@ref ownership "reference type, large data").
229 /// Acquire with ArFrame_acquirePointCloud()<br>
230 /// Release with ArPointCloud_release()
231 typedef struct ArPointCloud_ ArPointCloud;
237 /// @addtogroup image
240 /// Camera capture metadata (@ref ownership "reference type, large data").
242 /// Acquire with ArFrame_acquireImageMetadata()<br>
243 /// Release with ArImageMetadata_release()
244 typedef struct ArImageMetadata_ ArImageMetadata;
246 /// Accessing CPU image from the tracking camera
247 /// (@ref ownership "reference type, large data").
249 /// Acquire with ArFrame_acquireCameraImage()<br>
250 /// Convert to NDK AImage with ArImage_getNdkImage()<br>
251 /// Release with ArImage_release().
252 typedef struct ArImage_ ArImage;
254 /// Forward declaring the AImage struct from Android NDK, which is used
255 /// in ArImage_getNdkImage().
256 typedef struct AImage AImage;
261 /// @addtogroup trackable
264 /// Trackable base type (@ref ownership "reference type, long-lived").
265 typedef struct ArTrackable_ ArTrackable;
267 /// A list of ArTrackables (@ref ownership "value type").
269 /// Allocate with ArTrackableList_create()<br>
270 /// Release with ArTrackableList_destroy()
271 typedef struct ArTrackableList_ ArTrackableList;
277 /// @addtogroup plane
280 /// A detected planar surface (@ref ownership "reference type, long-lived").
282 /// Trackable type: #AR_TRACKABLE_PLANE <br>
283 /// Release with: ArTrackable_release()
284 typedef struct ArPlane_ ArPlane;
290 /// @addtogroup point
293 /// An arbitrary point in space (@ref ownership "reference type, long-lived").
295 /// Trackable type: #AR_TRACKABLE_POINT <br>
296 /// Release with: ArTrackable_release()
297 typedef struct ArPoint_ ArPoint;
303 /// @addtogroup augmented_image
306 /// An image that has been detected and tracked (@ref ownership "reference type,
309 /// Trackable type: #AR_TRACKABLE_AUGMENTED_IMAGE <br>
310 /// Release with: ArTrackable_release()
311 typedef struct ArAugmentedImage_ ArAugmentedImage;
315 // Augmented Image Database
316 /// @addtogroup augmented_image_database
319 /// A database of images to be detected and tracked by ARCore (@ref ownership
322 /// An image database supports up to 1000 images. A database can be generated by
323 /// the `arcoreimg` command-line database generation tool provided in the SDK,
324 /// or dynamically created at runtime by adding individual images.
326 /// Only one image database can be active in a session. Any images in the
327 /// currently active image database that have a TRACKING/PAUSED state will
328 /// immediately be set to the STOPPED state if a different or null image
329 /// database is made active in the current session Config.
331 /// Create with ArAugmentedImageDatabase_create() or
332 /// ArAugmentedImageDatabase_deserialize()<br>
333 /// Release with: ArAugmentedImageDatabase_destroy()
334 typedef struct ArAugmentedImageDatabase_ ArAugmentedImageDatabase;
340 /// @addtogroup anchor
343 /// A position in space attached to a trackable
344 /// (@ref ownership "reference type, long-lived").
346 /// Create with ArSession_acquireNewAnchor() or
347 /// ArHitResult_acquireNewAnchor()<br>
348 /// Release with ArAnchor_release()
349 typedef struct ArAnchor_ ArAnchor;
351 /// A list of anchors (@ref ownership "value type").
353 /// Allocate with ArAnchorList_create()<br>
354 /// Release with ArAnchorList_destroy()
355 typedef struct ArAnchorList_ ArAnchorList;
359 // Hit result functionality.
364 /// A single trackable hit (@ref ownership "value type").
366 /// Allocate with ArHitResult_create()<br>
367 /// Populate with ArHitResultList_getItem()<br>
368 /// Release with ArHitResult_destroy()
369 typedef struct ArHitResult_ ArHitResult;
371 /// A list of hit test results (@ref ownership "value type").
373 /// Allocate with ArHitResultList_create()<br>
374 /// Release with ArHitResultList_destroy()<br>
375 typedef struct ArHitResultList_ ArHitResultList;
379 /// @cond EXCLUDE_FROM_DOXYGEN
381 // Forward declaring the ACameraMetadata struct from Android NDK, which is used
382 // in ArImageMetadata_getNdkCameraMetadata
383 typedef struct ACameraMetadata ACameraMetadata;
387 /// @addtogroup cpp_helpers
389 /// These methods expose allowable type conversions as C++ helper functions.
390 /// This avoids having to explicitly @c reinterpret_cast in most cases.
392 /// Note: These methods only change the type of a pointer - they do not change
393 /// the reference count of the referenced objects.
395 /// Note: There is no runtime checking that casts are correct. Call @ref
396 /// ArTrackable_getType() beforehand to figure out the correct cast.
399 /// Upcasts to ArTrackable
400 inline ArTrackable *ArAsTrackable(ArPlane *plane) {
401 return reinterpret_cast<ArTrackable *>(plane);
404 /// Upcasts to ArTrackable
405 inline ArTrackable *ArAsTrackable(ArPoint *point) {
406 return reinterpret_cast<ArTrackable *>(point);
409 /// Upcasts to ArTrackable
410 inline ArTrackable *ArAsTrackable(ArAugmentedImage *augmented_image) {
411 return reinterpret_cast<ArTrackable *>(augmented_image);
414 /// Downcasts to ArPlane.
415 inline ArPlane *ArAsPlane(ArTrackable *trackable) {
416 return reinterpret_cast<ArPlane *>(trackable);
419 /// Downcasts to ArPoint.
420 inline ArPoint *ArAsPoint(ArTrackable *trackable) {
421 return reinterpret_cast<ArPoint *>(trackable);
424 /// Downcasts to ArAugmentedImage.
425 inline ArAugmentedImage *ArAsAugmentedImage(ArTrackable *trackable) {
426 return reinterpret_cast<ArAugmentedImage *>(trackable);
431 // If compiling for C++11, use the 'enum underlying type' feature to enforce
432 // size for ABI compatibility. In pre-C++11, use int32_t for fixed size.
433 #if __cplusplus >= 201100
434 #define AR_DEFINE_ENUM(_type) enum _type : int32_t
436 #define AR_DEFINE_ENUM(_type) \
437 typedef int32_t _type; \
441 #if defined(__GNUC__) && !defined(AR_DEPRECATED_SUPPRESS)
442 #define AR_DEPRECATED(_deprecation_string) \
443 __attribute__((deprecated(_deprecation_string)));
445 #define AR_DEPRECATED(_deprecation_string)
448 /// @ingroup trackable
449 /// Object types for heterogeneous query/update lists.
450 AR_DEFINE_ENUM(ArTrackableType){
451 /// The base Trackable type. Can be passed to ArSession_getAllTrackables()
452 /// and ArFrame_getUpdatedTrackables() as the @c filter_type to get
453 /// all/updated Trackables of all types.
454 AR_TRACKABLE_BASE_TRACKABLE = 0x41520100,
456 /// The ::ArPlane subtype of Trackable.
457 AR_TRACKABLE_PLANE = 0x41520101,
459 /// The ::ArPoint subtype of Trackable.
460 AR_TRACKABLE_POINT = 0x41520102,
462 /// The ::ArAugmentedImage subtype of Trackable.
463 AR_TRACKABLE_AUGMENTED_IMAGE = 0x41520104,
465 /// An invalid Trackable type.
466 AR_TRACKABLE_NOT_VALID = 0};
469 /// Return code indicating success or failure of a method.
470 AR_DEFINE_ENUM(ArStatus){
471 /// The operation was successful.
474 /// One of the arguments was invalid, either null or not appropriate for the
475 /// operation requested.
476 AR_ERROR_INVALID_ARGUMENT = -1,
478 /// An internal error occurred that the application should not attempt to
482 /// An operation was attempted that requires the session be running, but the
483 /// session was paused.
484 AR_ERROR_SESSION_PAUSED = -3,
486 /// An operation was attempted that requires the session be paused, but the
487 /// session was running.
488 AR_ERROR_SESSION_NOT_PAUSED = -4,
490 /// An operation was attempted that the session be in the TRACKING state,
491 /// but the session was not.
492 AR_ERROR_NOT_TRACKING = -5,
494 /// A texture name was not set by calling ArSession_setCameraTextureName()
495 /// before the first call to ArSession_update()
496 AR_ERROR_TEXTURE_NOT_SET = -6,
498 /// An operation required GL context but one was not available.
499 AR_ERROR_MISSING_GL_CONTEXT = -7,
501 /// The configuration supplied to ArSession_configure() was unsupported.
502 /// To avoid this error, ensure that Session_checkSupported() returns true.
503 AR_ERROR_UNSUPPORTED_CONFIGURATION = -8,
505 /// The android camera permission has not been granted prior to calling
506 /// ArSession_resume()
507 AR_ERROR_CAMERA_PERMISSION_NOT_GRANTED = -9,
509 /// Acquire failed because the object being acquired is already released.
510 /// For example, this happens if the application holds an ::ArFrame beyond
511 /// the next call to ArSession_update(), and then tries to acquire its point
513 AR_ERROR_DEADLINE_EXCEEDED = -10,
515 /// There are no available resources to complete the operation. In cases of
516 /// @c acquire methods returning this error, This can be avoided by
517 /// releasing previously acquired objects before acquiring new ones.
518 AR_ERROR_RESOURCE_EXHAUSTED = -11,
520 /// Acquire failed because the data isn't available yet for the current
521 /// frame. For example, acquire the image metadata may fail with this error
522 /// because the camera hasn't fully started.
523 AR_ERROR_NOT_YET_AVAILABLE = -12,
525 /// The android camera has been reallocated to a higher priority app or is
526 /// otherwise unavailable.
527 AR_ERROR_CAMERA_NOT_AVAILABLE = -13,
529 /// The host/resolve function call failed because the Session is not
530 /// configured for cloud anchors.
531 AR_ERROR_CLOUD_ANCHORS_NOT_CONFIGURED = -14,
533 /// ArSession_configure() failed because the specified configuration
534 /// required the Android INTERNET permission, which the application did not
536 AR_ERROR_INTERNET_PERMISSION_NOT_GRANTED = -15,
538 /// HostCloudAnchor() failed because the anchor is not a type of anchor that
539 /// is currently supported for hosting.
540 AR_ERROR_ANCHOR_NOT_SUPPORTED_FOR_HOSTING = -16,
542 /// An image with insufficient quality (e.g. too few features) was attempted
543 /// to be added to the image database.
544 AR_ERROR_IMAGE_INSUFFICIENT_QUALITY = -17,
546 /// The data passed in for this operation was not in a valid format.
547 AR_ERROR_DATA_INVALID_FORMAT = -18,
549 /// The data passed in for this operation is not supported by this version
551 AR_ERROR_DATA_UNSUPPORTED_VERSION = -19,
553 /// The ARCore APK is not installed on this device.
554 AR_UNAVAILABLE_ARCORE_NOT_INSTALLED = -100,
556 /// The device is not currently compatible with ARCore.
557 AR_UNAVAILABLE_DEVICE_NOT_COMPATIBLE = -101,
559 /// The ARCore APK currently installed on device is too old and needs to be
561 AR_UNAVAILABLE_APK_TOO_OLD = -103,
563 /// The ARCore APK currently installed no longer supports the ARCore SDK
564 /// that the application was built with.
565 AR_UNAVAILABLE_SDK_TOO_OLD = -104,
567 /// The user declined installation of the ARCore APK during this run of the
568 /// application and the current request was not marked as user-initiated.
569 AR_UNAVAILABLE_USER_DECLINED_INSTALLATION = -105};
572 /// Describes the tracking state of a @c Trackable, an ::ArAnchor or the
574 AR_DEFINE_ENUM(ArTrackingState){
575 /// The object is currently tracked and its pose is current.
576 AR_TRACKING_STATE_TRACKING = 0,
578 /// ARCore has paused tracking this object, but may resume tracking it in
579 /// the future. This can happen if device tracking is lost, if the user
580 /// enters a new space, or if the Session is currently paused. When in this
581 /// state, the positional properties of the object may be wildly inaccurate
582 /// and should not be used.
583 AR_TRACKING_STATE_PAUSED = 1,
585 /// ARCore has stopped tracking this Trackable and will never resume
587 AR_TRACKING_STATE_STOPPED = 2};
590 /// Describes the current cloud state of an @c Anchor.
591 AR_DEFINE_ENUM(ArCloudAnchorState){
592 /// The anchor is purely local. It has never been hosted using
593 /// hostCloudAnchor, and has not been acquired using acquireCloudAnchor.
594 AR_CLOUD_ANCHOR_STATE_NONE = 0,
596 /// A hosting/resolving task for the anchor is in progress. Once the task
597 /// completes in the background, the anchor will get a new cloud state after
598 /// the next update() call.
599 AR_CLOUD_ANCHOR_STATE_TASK_IN_PROGRESS = 1,
601 /// A hosting/resolving task for this anchor completed successfully.
602 AR_CLOUD_ANCHOR_STATE_SUCCESS = 2,
604 /// A hosting/resolving task for this anchor finished with an internal
605 /// error. The app should not attempt to recover from this error.
606 AR_CLOUD_ANCHOR_STATE_ERROR_INTERNAL = -1,
608 /// The app cannot communicate with the ARCore Cloud because of an invalid
609 /// or unauthorized API key in the manifest, or because there was no API key
610 /// present in the manifest.
611 AR_CLOUD_ANCHOR_STATE_ERROR_NOT_AUTHORIZED = -2,
613 /// The ARCore Cloud was unreachable. This can happen because of a number of
614 /// reasons. The request sent to the server could have timed out with no
615 /// response, there could be a bad network connection, DNS unavailability,
616 /// firewall issues, or anything that could affect the device's ability to
617 /// connect to the ARCore Cloud.
618 AR_CLOUD_ANCHOR_STATE_ERROR_SERVICE_UNAVAILABLE = -3,
620 /// The application has exhausted the request quota allotted to the given
621 /// API key. The developer should request additional quota for the ARCore
622 /// Cloud for their API key from the Google Developers Console.
623 AR_CLOUD_ANCHOR_STATE_ERROR_RESOURCE_EXHAUSTED = -4,
625 /// Hosting failed, because the server could not successfully process the
626 /// dataset for the given anchor. The developer should try again after the
627 /// device has gathered more data from the environment.
628 AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_DATASET_PROCESSING_FAILED = -5,
630 /// Resolving failed, because the ARCore Cloud could not find the provided
632 AR_CLOUD_ANCHOR_STATE_ERROR_CLOUD_ID_NOT_FOUND = -6,
634 /// The server could not match the visual features provided by ARCore
635 /// against the localization dataset of the requested cloud anchor ID. This
636 /// means that the anchor pose being requested was likely not created in the
637 /// user's surroundings.
638 AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_LOCALIZATION_NO_MATCH = -7,
640 /// The anchor could not be resolved because the SDK used to host the anchor
641 /// was newer than and incompatible with the version being used to acquire
643 AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_OLD = -8,
645 /// The anchor could not be acquired because the SDK used to host the anchor
646 /// was older than and incompatible with the version being used to acquire
648 AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_NEW = -9};
650 /// @ingroup arcoreapk
651 /// Describes the current state of ARCore availability on the device.
652 AR_DEFINE_ENUM(ArAvailability){
653 /// An internal error occurred while determining ARCore availability.
654 AR_AVAILABILITY_UNKNOWN_ERROR = 0,
655 /// ARCore is not installed, and a query has been issued to check if ARCore
657 AR_AVAILABILITY_UNKNOWN_CHECKING = 1,
658 /// ARCore is not installed, and the query to check if ARCore is supported
659 /// timed out. This may be due to the device being offline.
660 AR_AVAILABILITY_UNKNOWN_TIMED_OUT = 2,
661 /// ARCore is not supported on this device.
662 AR_AVAILABILITY_UNSUPPORTED_DEVICE_NOT_CAPABLE = 100,
663 /// The device and Android version are supported, but the ARCore APK is not
665 AR_AVAILABILITY_SUPPORTED_NOT_INSTALLED = 201,
666 /// The device and Android version are supported, and a version of the
667 /// ARCore APK is installed, but that ARCore APK version is too old.
668 AR_AVAILABILITY_SUPPORTED_APK_TOO_OLD = 202,
669 /// ARCore is supported, installed, and available to use.
670 AR_AVAILABILITY_SUPPORTED_INSTALLED = 203};
672 /// @ingroup arcoreapk
673 /// Indicates the outcome of a call to ArCoreApk_requestInstall().
674 AR_DEFINE_ENUM(ArInstallStatus){
675 /// The requested resource is already installed.
676 AR_INSTALL_STATUS_INSTALLED = 0,
677 /// Installation of the resource was requested. The current activity will be
679 AR_INSTALL_STATUS_INSTALL_REQUESTED = 1};
681 /// @ingroup arcoreapk
682 /// Controls the behavior of the installation UI.
683 AR_DEFINE_ENUM(ArInstallBehavior){
684 /// Hide the Cancel button during initial prompt and prevent user from
685 /// exiting via tap-outside.
687 /// Note: The BACK button or tapping outside of any marketplace-provided
688 /// install dialog will still decline the installation.
689 AR_INSTALL_BEHAVIOR_REQUIRED = 0,
690 /// Include Cancel button in initial prompt and allow easily backing out
691 /// after installation has been initiated.
692 AR_INSTALL_BEHAVIOR_OPTIONAL = 1};
694 /// @ingroup arcoreapk
695 /// Controls the message displayed by the installation UI.
696 AR_DEFINE_ENUM(ArInstallUserMessageType){
697 /// Display a localized message like "This application requires ARCore...".
698 AR_INSTALL_USER_MESSAGE_TYPE_APPLICATION = 0,
699 /// Display a localized message like "This feature requires ARCore...".
700 AR_INSTALL_USER_MESSAGE_TYPE_FEATURE = 1,
701 /// Application has explained why ARCore is required prior to calling
702 /// ArCoreApk_requestInstall(), skip user education dialog.
703 AR_INSTALL_USER_MESSAGE_TYPE_USER_ALREADY_INFORMED = 2};
706 /// Select the behavior of the lighting estimation subsystem.
707 AR_DEFINE_ENUM(ArLightEstimationMode){
708 /// Lighting estimation is disabled.
709 AR_LIGHT_ESTIMATION_MODE_DISABLED = 0,
710 /// Lighting estimation is enabled, generating a single-value intensity
712 AR_LIGHT_ESTIMATION_MODE_AMBIENT_INTENSITY = 1};
715 /// Select the behavior of the plane detection subsystem.
716 AR_DEFINE_ENUM(ArPlaneFindingMode){
717 /// Plane detection is disabled.
718 AR_PLANE_FINDING_MODE_DISABLED = 0,
719 /// Detection of only horizontal planes is enabled.
720 AR_PLANE_FINDING_MODE_HORIZONTAL = 1,
721 /// Detection of only vertical planes is enabled.
722 AR_PLANE_FINDING_MODE_VERTICAL = 2,
723 /// Detection of horizontal and vertical planes is enabled.
724 AR_PLANE_FINDING_MODE_HORIZONTAL_AND_VERTICAL = 3};
727 /// Selects the behavior of ArSession_update().
728 AR_DEFINE_ENUM(ArUpdateMode){
729 /// @c update() will wait until a new camera image is available, or until
730 /// the built-in timeout (currently 66ms) is reached. On most
731 /// devices the camera is configured to capture 30 frames per second.
732 /// If the camera image does not arrive by the built-in timeout, then
733 /// @c update() will return the most recent ::ArFrame object.
734 AR_UPDATE_MODE_BLOCKING = 0,
735 /// @c update() will return immediately without blocking. If no new camera
736 /// image is available, then @c update() will return the most recent
737 /// ::ArFrame object.
738 AR_UPDATE_MODE_LATEST_CAMERA_IMAGE = 1};
741 /// Simple summary of the normal vector of a plane, for filtering purposes.
742 AR_DEFINE_ENUM(ArPlaneType){
743 /// A horizontal plane facing upward (for example a floor or tabletop).
744 AR_PLANE_HORIZONTAL_UPWARD_FACING = 0,
745 /// A horizontal plane facing downward (for example a ceiling).
746 AR_PLANE_HORIZONTAL_DOWNWARD_FACING = 1,
747 /// A vertical plane (for example a wall).
748 AR_PLANE_VERTICAL = 2};
751 /// Tracks the validity of a light estimate.
752 AR_DEFINE_ENUM(ArLightEstimateState){
753 /// The light estimate is not valid this frame and should not be used for
755 AR_LIGHT_ESTIMATE_STATE_NOT_VALID = 0,
756 /// The light estimate is valid this frame.
757 AR_LIGHT_ESTIMATE_STATE_VALID = 1};
760 /// Indicates the orientation mode of the ::ArPoint.
761 AR_DEFINE_ENUM(ArPointOrientationMode){
762 /// The orientation of the ::ArPoint is initialized to identity but may
763 /// adjust slightly over time.
764 AR_POINT_ORIENTATION_INITIALIZED_TO_IDENTITY = 0,
765 /// The orientation of the ::ArPoint will follow the behavior described in
766 /// ArHitResult_getHitPose().
767 AR_POINT_ORIENTATION_ESTIMATED_SURFACE_NORMAL = 1};
770 /// Indicates the cloud configuration of the ::ArSession.
771 AR_DEFINE_ENUM(ArCloudAnchorMode){
772 /// Anchor Hosting is disabled. This is the value set in the default
774 AR_CLOUD_ANCHOR_MODE_DISABLED = 0,
775 /// Anchor Hosting is enabled. Setting this value and calling @c configure()
776 /// will require that the application have the Android INTERNET permission.
777 AR_CLOUD_ANCHOR_MODE_ENABLED = 1};
779 #undef AR_DEFINE_ENUM
785 // Note: destroy methods do not take ArSession* to allow late destruction in
786 // finalizers of garbage-collected languages such as Java.
788 /// @addtogroup arcoreapk
791 /// Determines if ARCore is supported on this device. This may initiate a query
792 /// with a remote service to determine if the device is compatible, in which
793 /// case it will return immediately with @c out_availability set to
794 /// #AR_AVAILABILITY_UNKNOWN_CHECKING.
796 /// For ARCore-required apps (as indicated by the <a
797 /// href="https://developers.google.com/ar/develop/c/enable-arcore#ar_required">manifest
798 /// meta-data</a>) this method will assume device compatibility and will always
799 /// immediately return one of #AR_AVAILABILITY_SUPPORTED_INSTALLED,
800 /// #AR_AVAILABILITY_SUPPORTED_APK_TOO_OLD, or
801 /// #AR_AVAILABILITY_SUPPORTED_NOT_INSTALLED.
803 /// Note: A result #AR_AVAILABILITY_SUPPORTED_INSTALLED only indicates presence
804 /// of a suitably versioned ARCore APK. Session creation may still fail if the
805 /// ARCore APK has been sideloaded onto an incompatible device.
807 /// May be called prior to ArSession_create().
809 /// @param[in] env The application's @c JNIEnv object
810 /// @param[in] application_context A @c jobject referencing the application's
811 /// Android @c Context.
812 /// @param[out] out_availability A pointer to an ArAvailability to receive
814 void ArCoreApk_checkAvailability(void *env,
815 void *application_context,
816 ArAvailability *out_availability);
818 /// Initiates installation of ARCore if needed. When your apllication launches
819 /// or enters an AR mode, it should call this method with @c
820 /// user_requested_install = 1.
822 /// If ARCore is installed and compatible, this function will set @c
823 /// out_install_status to #AR_INSTALL_STATUS_INSTALLED.
825 /// If ARCore is not currently installed or the installed version not
826 /// compatible, the function will set @c out_install_status to
827 /// #AR_INSTALL_STATUS_INSTALL_REQUESTED and return immediately. Your current
828 /// activity will then pause while the user is informed about the requierment of
829 /// ARCore and offered the opportunity to install it.
831 /// When your activity resumes, you should call this method again, this time
832 /// with @c user_requested_install = 0. This will either set
833 /// @c out_install_status to #AR_INSTALL_STATUS_INSTALLED or return an error
834 /// code indicating the reason that installation could not be completed.
836 /// ARCore-optional applications must ensure that ArCoreApk_checkAvailability()
837 /// returns one of the <tt>AR_AVAILABILITY_SUPPORTED_...</tt> values before
838 /// calling this method.
841 /// href="https://github.com/google-ar/arcore-android-sdk/tree/master/samples">
842 /// our sample code</A> for an example of how an ARCore-required application
843 /// should use this function.
845 /// May be called prior to ArSession_create().
847 /// For more control over the message displayed and ease of exiting the process,
848 /// see ArCoreApk_requestInstallCustom().
850 /// <b>Caution:</b> The value of <tt>*out_install_status</tt> should only be
851 /// considered when #AR_SUCCESS is returned. Otherwise this value must be
854 /// @param[in] env The application's @c JNIEnv object
855 /// @param[in] application_activity A @c jobject referencing the application's
856 /// current Android @c Activity.
857 /// @param[in] user_requested_install if set, override the previous installation
858 /// failure message and always show the installation interface.
859 /// @param[out] out_install_status A pointer to an ArInstallStatus to receive
860 /// the resulting install status, if successful. Note: this value is only
861 /// valid with the return value is #AR_SUCCESS.
862 /// @return #AR_SUCCESS, or any of:
863 /// - #AR_ERROR_FATAL if an error occurs while checking for or requesting
865 /// - #AR_UNAVAILABLE_DEVICE_NOT_COMPATIBLE if ARCore is not supported
867 /// - #AR_UNAVAILABLE_USER_DECLINED_INSTALLATION if the user previously declined
869 ArStatus ArCoreApk_requestInstall(void *env,
870 void *application_activity,
871 bool user_requested_install,
872 ArInstallStatus *out_install_status);
874 /// Initiates installation of ARCore if required, with configurable behavior.
876 /// This is a more flexible version of ArCoreApk_requestInstall() allowing the
877 /// application control over the initial informational dialog and ease of
878 /// exiting or cancelling the installation.
880 /// See ArCoreApk_requestInstall() for details of use and behavior.
882 /// May be called prior to ArSession_create().
884 /// @param[in] env The application's @c JNIEnv object
885 /// @param[in] application_activity A @c jobject referencing the application's
886 /// current Android @c Activity.
887 /// @param[in] user_requested_install if set, override the previous installation
888 /// failure message and always show the installation interface.
889 /// @param[in] install_behavior controls the presence of the cancel button at
890 /// the user education screen and if tapping outside the education screen or
891 /// install-in-progress screen causes them to dismiss.
892 /// @param[in] message_type controls the text of the of message displayed
893 /// before showing the install prompt, or disables display of this message.
894 /// @param[out] out_install_status A pointer to an ArInstallStatus to receive
895 /// the resulting install status, if successful. Note: this value is only
896 /// valid with the return value is #AR_SUCCESS.
897 /// @return #AR_SUCCESS, or any of:
898 /// - #AR_ERROR_FATAL if an error occurs while checking for or requesting
900 /// - #AR_UNAVAILABLE_DEVICE_NOT_COMPATIBLE if ARCore is not supported
902 /// - #AR_UNAVAILABLE_USER_DECLINED_INSTALLATION if the user previously declined
904 ArStatus ArCoreApk_requestInstallCustom(void *env,
905 void *application_activity,
906 int32_t user_requested_install,
907 ArInstallBehavior install_behavior,
908 ArInstallUserMessageType message_type,
909 ArInstallStatus *out_install_status);
912 /// @addtogroup session
915 /// Attempts to create a new ARCore session.
917 /// This is the entry point of ARCore. This function MUST be the first ARCore
918 /// call made by an application.
920 /// @param[in] env The application's @c JNIEnv object
921 /// @param[in] application_context A @c jobject referencing the application's
922 /// Android @c Context
923 /// @param[out] out_session_pointer A pointer to an @c ArSession* to receive
924 /// the address of the newly allocated session.
925 /// @return #AR_SUCCESS or any of:
926 /// - #AR_UNAVAILABLE_ARCORE_NOT_INSTALLED
927 /// - #AR_UNAVAILABLE_DEVICE_NOT_COMPATIBLE
928 /// - #AR_UNAVAILABLE_APK_TOO_OLD
929 /// - #AR_UNAVAILABLE_SDK_TOO_OLD
930 /// - #AR_ERROR_CAMERA_PERMISSION_NOT_GRANTED
931 ArStatus ArSession_create(void *env,
932 void *application_context,
933 ArSession **out_session_pointer);
937 // === ArConfig methods ===
939 /// @addtogroup config
942 /// Creates a new configuration object and initializes it to a sensible default
943 /// configuration. Plane detection and lighting estimation are enabled, and
944 /// blocking update is selected. This configuration is guaranteed to be
945 /// supported on all devices that support ARCore.
946 void ArConfig_create(const ArSession *session, ArConfig **out_config);
948 /// Releases memory used by the provided configuration object.
949 void ArConfig_destroy(ArConfig *config);
951 /// Stores the currently configured lighting estimation mode into
952 /// @c *light_estimation_mode.
953 void ArConfig_getLightEstimationMode(
954 const ArSession *session,
955 const ArConfig *config,
956 ArLightEstimationMode *light_estimation_mode);
958 /// Sets the lighting estimation mode that should be used. See
959 /// ::ArLightEstimationMode for available options.
960 void ArConfig_setLightEstimationMode(
961 const ArSession *session,
963 ArLightEstimationMode light_estimation_mode);
965 /// Stores the currently configured plane finding mode into
966 /// @c *plane_finding_mode.
967 void ArConfig_getPlaneFindingMode(const ArSession *session,
968 const ArConfig *config,
969 ArPlaneFindingMode *plane_finding_mode);
971 /// Sets the plane finding mode that should be used. See
972 /// ::ArPlaneFindingMode for available options.
973 void ArConfig_setPlaneFindingMode(const ArSession *session,
975 ArPlaneFindingMode plane_finding_mode);
977 /// Stores the currently configured behavior of @ref ArSession_update() into
979 void ArConfig_getUpdateMode(const ArSession *session,
980 const ArConfig *config,
981 ArUpdateMode *update_mode);
983 /// Sets the behavior of @ref ArSession_update(). See
984 /// ::ArUpdateMode for available options.
985 void ArConfig_setUpdateMode(const ArSession *session,
987 ArUpdateMode update_mode);
989 /// Gets the current cloud anchor mode from the ::ArConfig.
990 void ArConfig_getCloudAnchorMode(const ArSession *session,
991 const ArConfig *config,
992 ArCloudAnchorMode *out_cloud_anchor_mode);
994 /// Sets the cloud configuration that should be used. See ::ArCloudAnchorMode
995 /// for available options.
996 void ArConfig_setCloudAnchorMode(const ArSession *session,
998 ArCloudAnchorMode cloud_anchor_mode);
1000 /// Sets the image database in the session configuration.
1002 /// Any images in the currently active image database that have a
1003 /// TRACKING/PAUSED state will immediately be set to the STOPPED state if a
1004 /// different or null image database is set.
1006 /// This function makes a copy of the image database.
1007 void ArConfig_setAugmentedImageDatabase(
1008 const ArSession *session,
1010 const ArAugmentedImageDatabase *augmented_image_database);
1012 /// Returns the image database from the session configuration.
1014 /// This function returns a copy of the internally stored image database.
1015 void ArConfig_getAugmentedImageDatabase(
1016 const ArSession *session,
1017 const ArConfig *config,
1018 ArAugmentedImageDatabase *out_augmented_image_database);
1022 // === ArSession methods ===
1024 /// @addtogroup session
1027 /// Releases resources used by an ARCore session.
1028 void ArSession_destroy(ArSession *session);
1030 /// Before release 1.2.0: Checks if the provided configuration is usable on the
1031 /// this device. If this method returns #AR_ERROR_UNSUPPORTED_CONFIGURATION,
1032 /// calls to ArSession_configure(Config) with this configuration will fail.
1034 /// This function now always returns true. See documentation for each
1035 /// configuration entry to know which configuration options & combinations are
1038 /// @param[in] session The ARCore session
1039 /// @param[in] config The configuration to test
1040 /// @return #AR_SUCCESS or:
1041 /// - #AR_ERROR_INVALID_ARGUMENT if any of the arguments are null.
1042 /// @deprecated in release 1.2.0. Please refer to the release notes
1044 /// href="https://github.com/google-ar/arcore-android-sdk/releases/tag/v1.2.0">release
1045 /// notes 1.2.0</a>)
1047 ArStatus ArSession_checkSupported(const ArSession *session,
1048 const ArConfig *config)
1050 "deprecated in release 1.2.0. Please see function documentation");
1052 /// Configures the session with the given config.
1053 /// Note: a session is always initially configured with the default config.
1054 /// This should be called if a configuration different than default is needed.
1056 /// @return #AR_SUCCESS or any of:
1057 /// - #AR_ERROR_FATAL
1058 /// - #AR_ERROR_UNSUPPORTED_CONFIGURATION
1059 ArStatus ArSession_configure(ArSession *session, const ArConfig *config);
1061 /// Starts or resumes the ARCore Session.
1063 /// Typically this should be called from <a
1064 /// href="https://developer.android.com/reference/android/app/Activity.html#onResume()"
1065 /// ><tt>Activity.onResume()</tt></a>.
1067 /// @returns #AR_SUCCESS or any of:
1068 /// - #AR_ERROR_FATAL
1069 /// - #AR_ERROR_CAMERA_PERMISSION_NOT_GRANTED
1070 /// - #AR_ERROR_CAMERA_NOT_AVAILABLE
1071 ArStatus ArSession_resume(ArSession *session);
1073 /// Pause the current session. This method will stop the camera feed and release
1074 /// resources. The session can be restarted again by calling ArSession_resume().
1076 /// Typically this should be called from <a
1077 /// href="https://developer.android.com/reference/android/app/Activity.html#onPause()"
1078 /// ><tt>Activity.onPause()</tt></a>.
1080 /// @returns #AR_SUCCESS or any of:
1081 /// - #AR_ERROR_FATAL
1082 ArStatus ArSession_pause(ArSession *session);
1084 /// Sets the OpenGL texture name (id) that will allow GPU access to the camera
1085 /// image. The provided ID should have been created with @c glGenTextures(). The
1086 /// resulting texture must be bound to the @c GL_TEXTURE_EXTERNAL_OES target for
1087 /// use. Shaders accessing this texture must use a @c samplerExternalOES
1088 /// sampler. See sample code for an example.
1089 void ArSession_setCameraTextureName(ArSession *session, uint32_t texture_id);
1091 /// Sets the aspect ratio, coordinate scaling, and display rotation. This data
1092 /// is used by UV conversion, projection matrix generation, and hit test logic.
1094 /// Note: this function doesn't fail. If given invalid input, it logs a error
1095 /// and doesn't apply the changes.
1097 /// @param[in] session The ARCore session
1098 /// @param[in] rotation Display rotation specified by @c android.view.Surface
1099 /// constants: @c ROTATION_0, @c ROTATION_90, @c ROTATION_180 and
1101 /// @param[in] width Width of the view, in pixels
1102 /// @param[in] height Height of the view, in pixels
1103 void ArSession_setDisplayGeometry(ArSession *session,
1108 /// Updates the state of the ARCore system. This includes: receiving a new
1109 /// camera frame, updating the location of the device, updating the location of
1110 /// tracking anchors, updating detected planes, etc.
1112 /// This call may cause off-screen OpenGL activity. Because of this, to avoid
1113 /// unnecessary frame buffer flushes and reloads, this call should not be made
1114 /// in the middle of rendering a frame or offscreen buffer.
1116 /// This call may update the pose of all created anchors and detected planes.
1117 /// The set of updated objects is accessible through
1118 /// ArFrame_getUpdatedTrackables().
1120 /// @c update() in blocking mode (see ::ArUpdateMode) will wait until a
1121 /// new camera image is available, or until the built-in timeout
1122 /// (currently 66ms) is reached.
1123 /// If the camera image does not arrive by the built-in timeout, then
1124 /// @c update() will return the most recent ::ArFrame object. For some
1125 /// applications it may be important to know if a new frame was actually
1126 /// obtained (for example, to avoid redrawing if the camera did not produce a
1127 /// new frame). To do that, compare the current frame's timestamp, obtained via
1128 /// @c ArFrame_getTimestamp, with the previously recorded frame timestamp. If
1129 /// they are different, this is a new frame.
1131 /// @param[in] session The ARCore session
1132 /// @param[inout] out_frame The Frame object to populate with the updated world
1133 /// state. This frame must have been previously created using
1134 /// ArFrame_create(). The same ArFrame instance may be used when calling
1135 /// this repeatedly.
1137 /// @return #AR_SUCCESS or any of:
1138 /// - #AR_ERROR_FATAL
1139 /// - #AR_ERROR_SESSION_PAUSED
1140 /// - #AR_ERROR_TEXTURE_NOT_SET
1141 /// - #AR_ERROR_MISSING_GL_CONTEXT
1142 /// - #AR_ERROR_CAMERA_NOT_AVAILABLE - camera was removed during runtime.
1143 ArStatus ArSession_update(ArSession *session, ArFrame *out_frame);
1145 /// Defines a tracked location in the physical world.
1147 /// @return #AR_SUCCESS or any of:
1148 /// - #AR_ERROR_NOT_TRACKING
1149 /// - #AR_ERROR_SESSION_PAUSED
1150 /// - #AR_ERROR_RESOURCE_EXHAUSTED
1151 ArStatus ArSession_acquireNewAnchor(ArSession *session,
1153 ArAnchor **out_anchor);
1155 /// Returns all known anchors, including those not currently tracked. Anchors
1156 /// forgotten by ARCore due to a call to ArAnchor_detach() or entering the
1157 /// #AR_TRACKING_STATE_STOPPED state will not be included.
1159 /// @param[in] session The ARCore session
1160 /// @param[inout] out_anchor_list The list to fill. This list must have already
1161 /// been allocated with ArAnchorList_create(). If previously used, the list
1162 /// will first be cleared.
1163 void ArSession_getAllAnchors(const ArSession *session,
1164 ArAnchorList *out_anchor_list);
1166 /// Returns the list of all known @ref trackable "trackables". This includes
1167 /// ::ArPlane objects if plane detection is enabled, as well as ::ArPoint
1168 /// objects created as a side effect of calls to ArSession_acquireNewAnchor() or
1169 /// ArFrame_hitTest().
1171 /// @param[in] session The ARCore session
1172 /// @param[in] filter_type The type(s) of trackables to return. See
1173 /// ::ArTrackableType for legal values.
1174 /// @param[inout] out_trackable_list The list to fill. This list must have
1175 /// already been allocated with ArTrackableList_create(). If previously
1176 /// used, the list will first be cleared.
1177 void ArSession_getAllTrackables(const ArSession *session,
1178 ArTrackableType filter_type,
1179 ArTrackableList *out_trackable_list);
1181 /// This will create a new cloud anchor using pose and other metadata from
1184 /// If the function returns #AR_SUCCESS, the cloud state of @c out_cloud_anchor
1185 /// will be set to #AR_CLOUD_ANCHOR_STATE_TASK_IN_PROGRESS and the initial pose
1186 /// will be set to the pose of @c anchor. However, the new @c out_cloud_anchor
1187 /// is completely independent of @c anchor, and the poses may diverge over time.
1188 /// If the return value of this function is not #AR_SUCCESS, then
1189 /// @c out_cloud_anchor will be set to null.
1191 /// @param[in] session The ARCore session
1192 /// @param[in] anchor The anchor to be hosted
1193 /// @param[inout] out_cloud_anchor The new cloud anchor
1194 /// @return #AR_SUCCESS or any of:
1195 /// - #AR_ERROR_NOT_TRACKING
1196 /// - #AR_ERROR_SESSION_PAUSED
1197 /// - #AR_ERROR_CLOUD_ANCHORS_NOT_CONFIGURED
1198 /// - #AR_ERROR_RESOURCE_EXHAUSTED
1199 /// - #AR_ERROR_ANCHOR_NOT_SUPPORTED_FOR_HOSTING
1200 ArStatus ArSession_hostAndAcquireNewCloudAnchor(ArSession *session,
1201 const ArAnchor *anchor,
1202 ArAnchor **out_cloud_anchor);
1204 /// This will create a new cloud anchor, and schedule a resolving task to
1205 /// resolve the anchor's pose using the given cloud anchor ID.
1207 /// If this function returns #AR_SUCCESS, the cloud state of @c out_cloud_anchor
1208 /// will be #AR_CLOUD_STATE_TASK_IN_PROGRESS, and its tracking state will be
1209 /// #AR_TRACKING_STATE_PAUSED. This anchor will never start tracking until its
1210 /// pose has been successfully resolved. If the resolving task ends in an error,
1211 /// the tracking state will be set to #AR_TRACKING_STATE_STOPPED. If the return
1212 /// value is not #AR_SUCCESS, then @c out_cloud_anchor will be set to null.
1214 /// @param[in] session The ARCore session
1215 /// @param[in] cloud_anchor_id The cloud ID of the anchor to be resolved
1216 /// @param[inout] out_cloud_anchor The new cloud anchor
1217 /// @return #AR_SUCCESS or any of:
1218 /// - #AR_ERROR_NOT_TRACKING
1219 /// - #AR_ERROR_SESSION_PAUSED
1220 /// - #AR_ERROR_CLOUD_ANCHORS_NOT_CONFIGURED
1221 /// - #AR_ERROR_RESOURCE_EXHAUSTED
1222 ArStatus ArSession_resolveAndAcquireNewCloudAnchor(ArSession *session,
1223 const char *cloud_anchor_id,
1224 ArAnchor **out_cloud_anchor);
1228 // === ArPose methods ===
1230 /// @addtogroup pose
1233 /// Allocates and initializes a new pose object. @c pose_raw points to an array
1234 /// of 7 floats, describing the rotation (quaternion) and translation of the
1235 /// pose in the same order as the first 7 elements of the Android
1236 /// @c Sensor.TYPE_POSE_6DOF values documented on <a
1237 /// href="https://developer.android.com/reference/android/hardware/SensorEvent.html#values"
1238 /// >@c SensorEvent.values() </a>
1240 /// The order of the values is: qx, qy, qz, qw, tx, ty, tz.
1242 /// If @c pose_raw is null, initializes with the identity pose.
1243 void ArPose_create(const ArSession *session,
1244 const float *pose_raw,
1247 /// Releases memory used by a pose object.
1248 void ArPose_destroy(ArPose *pose);
1250 /// Extracts the quaternion rotation and translation from a pose object.
1251 /// @param[in] session The ARCore session
1252 /// @param[in] pose The pose to extract
1253 /// @param[out] out_pose_raw Pointer to an array of 7 floats, to be filled with
1254 /// the quaternion rotation and translation as described in ArPose_create().
1255 void ArPose_getPoseRaw(const ArSession *session,
1257 float *out_pose_raw);
1259 /// Converts a pose into a 4x4 transformation matrix.
1260 /// @param[in] session The ARCore session
1261 /// @param[in] pose The pose to convert
1262 /// @param[out] out_matrix_col_major_4x4 Pointer to an array of 16 floats, to be
1263 /// filled with a column-major homogenous transformation matrix, as used by
1265 void ArPose_getMatrix(const ArSession *session,
1267 float *out_matrix_col_major_4x4);
1271 // === ArCamera methods ===
1273 /// @addtogroup camera
1276 /// Sets @c out_pose to the pose of the user's device in the world coordinate
1277 /// space at the time of capture of the current camera texture. The position and
1278 /// orientation of the pose follow the device's physical camera (they are not
1279 /// affected by display orientation) and uses OpenGL camera conventions (+X
1280 /// right, +Y up, -Z in the direction the camera is looking).
1282 /// Note: This pose is only useful when ArCamera_getTrackingState() returns
1283 /// #AR_TRACKING_STATE_TRACKING and otherwise should not be used.
1285 /// @param[in] session The ARCore session
1286 /// @param[in] camera The session's camera (retrieved from any frame).
1287 /// @param[inout] out_pose An already-allocated ArPose object into which the
1288 /// pose will be stored.
1289 void ArCamera_getPose(const ArSession *session,
1290 const ArCamera *camera,
1293 /// Sets @c out_pose to the pose of the user's device in the world coordinate
1294 /// space at the time of capture of the current camera texture. The position of
1295 /// the pose is located at the device's camera, while the orientation
1296 /// approximately matches the orientation of the display (considering display
1297 /// rotation), using OpenGL camera conventions (+X right, +Y up, -Z in the
1298 /// direction the camera is looking).
1300 /// Note: This pose is only useful when ArCamera_getTrackingState() returns
1301 /// #AR_TRACKING_STATE_TRACKING and otherwise should not be used.
1303 /// See also: ArCamera_getViewMatrix()
1305 /// @param[in] session The ARCore session
1306 /// @param[in] camera The session's camera (retrieved from any frame).
1307 /// @param[inout] out_pose An already-allocated ArPose object into which the
1308 /// pose will be stored.
1309 void ArCamera_getDisplayOrientedPose(const ArSession *session,
1310 const ArCamera *camera,
1313 /// Returns the view matrix for the camera for this frame. This matrix performs
1314 /// the inverse transfrom as the pose provided by
1315 /// ArCamera_getDisplayOrientedPose().
1317 /// @param[in] session The ARCore session
1318 /// @param[in] camera The session's camera.
1319 /// @param[inout] out_col_major_4x4 Pointer to an array of 16 floats, to be
1320 /// filled with a column-major homogenous transformation matrix, as used by
1322 void ArCamera_getViewMatrix(const ArSession *session,
1323 const ArCamera *camera,
1324 float *out_col_major_4x4);
1326 /// Gets the current state of the pose of this camera. If this state is anything
1327 /// other than #AR_TRACKING_STATE_TRACKING the Camera's pose should not be
1328 /// considered useful.
1329 void ArCamera_getTrackingState(const ArSession *session,
1330 const ArCamera *camera,
1331 ArTrackingState *out_tracking_state);
1333 /// Computes a projection matrix for rendering virtual content on top of the
1334 /// camera image. Note that the projection matrix reflects the current display
1335 /// geometry and display rotation.
1337 /// @param[in] session The ARCore session
1338 /// @param[in] camera The session's camera.
1339 /// @param[in] near Specifies the near clip plane, in meters
1340 /// @param[in] far Specifies the far clip plane, in meters
1341 /// @param[inout] dest_col_major_4x4 Pointer to an array of 16 floats, to
1342 /// be filled with a column-major homogenous transformation matrix, as used
1344 void ArCamera_getProjectionMatrix(const ArSession *session,
1345 const ArCamera *camera,
1348 float *dest_col_major_4x4);
1350 /// Releases a reference to the camera. This must match a call to
1351 /// ArFrame_acquireCamera().
1353 /// This method may safely be called with @c nullptr - it will do nothing.
1354 void ArCamera_release(ArCamera *camera);
1358 // === ArFrame methods ===
1360 /// @addtogroup frame
1363 /// Allocates a new ArFrame object, storing the pointer into @c *out_frame.
1365 /// Note: the same ArFrame can be used repeatedly when calling ArSession_update.
1366 void ArFrame_create(const ArSession *session, ArFrame **out_frame);
1368 /// Releases an ArFrame and any references it holds.
1369 void ArFrame_destroy(ArFrame *frame);
1371 /// Checks if the display rotation or viewport geometry changed since the
1372 /// previous call to ArSession_update(). The application should re-query
1373 /// ArCamera_getProjectionMatrix() and ArFrame_transformDisplayUvCoords()
1374 /// whenever this emits non-zero.
1375 void ArFrame_getDisplayGeometryChanged(const ArSession *session,
1376 const ArFrame *frame,
1377 int32_t *out_geometry_changed);
1379 /// Returns the timestamp in nanoseconds when this image was captured. This can
1380 /// be used to detect dropped frames or measure the camera frame rate. The time
1381 /// base of this value is specifically <b>not</b> defined, but it is likely
1382 /// similar to <tt>clock_gettime(CLOCK_BOOTTIME)</tt>.
1383 void ArFrame_getTimestamp(const ArSession *session,
1384 const ArFrame *frame,
1385 int64_t *out_timestamp_ns);
1387 /// Transform the given texture coordinates to correctly show the background
1388 /// image. This will account for the display rotation, and any additional
1389 /// required adjustment. For performance, this function should be called only if
1390 /// ArFrame_hasDisplayGeometryChanged() emits true.
1392 /// @param[in] session The ARCore session
1393 /// @param[in] frame The current frame.
1394 /// @param[in] num_elements The number of floats to transform. Must be
1395 /// a multiple of 2. @c uvs_in and @c uvs_out must point to arrays of at
1396 /// least this many floats.
1397 /// @param[in] uvs_in Input UV coordinates in normalized screen space.
1398 /// @param[inout] uvs_out Output UV coordinates in texture coordinates.
1399 void ArFrame_transformDisplayUvCoords(const ArSession *session,
1400 const ArFrame *frame,
1401 int32_t num_elements,
1402 const float *uvs_in,
1405 /// Performs a ray cast from the user's device in the direction of the given
1406 /// location in the camera view. Intersections with detected scene geometry are
1407 /// returned, sorted by distance from the device; the nearest intersection is
1410 /// Note: Significant geometric leeway is given when returning hit results. For
1411 /// example, a plane hit may be generated if the ray came close, but did not
1412 /// actually hit within the plane extents or plane bounds
1413 /// (ArPlane_isPoseInExtents() and ArPlane_isPoseInPolygon() can be used to
1414 /// determine these cases). A point (point cloud) hit is generated when a point
1415 /// is roughly within one finger-width of the provided screen coordinates.
1417 /// The resulting list is ordered by distance, with the nearest hit first
1419 /// Note: If not tracking, the hit_result_list will be empty. <br>
1420 /// Note: If called on an old frame (not the latest produced by
1421 /// ArSession_update() the hit_result_list will be empty).
1423 /// @param[in] session The ARCore session.
1424 /// @param[in] frame The current frame.
1425 /// @param[in] pixel_x Logical X position within the view, as from an
1426 /// Android UI event.
1427 /// @param[in] pixel_y Logical X position within the view.
1428 /// @param[inout] hit_result_list The list to fill. This list must have been
1429 /// previously allocated using ArHitResultList_create(). If the list has
1430 /// been previously used, it will first be cleared.
1431 void ArFrame_hitTest(const ArSession *session,
1432 const ArFrame *frame,
1435 ArHitResultList *hit_result_list);
1437 /// Gets the current ambient light estimate, if light estimation was enabled.
1439 /// @param[in] session The ARCore session.
1440 /// @param[in] frame The current frame.
1441 /// @param[inout] out_light_estimate The light estimate to fill. This object
1442 /// must have been previously created with ArLightEstimate_create().
1443 void ArFrame_getLightEstimate(const ArSession *session,
1444 const ArFrame *frame,
1445 ArLightEstimate *out_light_estimate);
1447 /// Acquires the current set of estimated 3d points attached to real-world
1448 /// geometry. A matching call to PointCloud_release() must be made when the
1449 /// application is done accessing the point cloud.
1451 /// Note: This information is for visualization and debugging purposes only. Its
1452 /// characteristics and format are subject to change in subsequent versions of
1455 /// @param[in] session The ARCore session.
1456 /// @param[in] frame The current frame.
1457 /// @param[out] out_point_cloud Pointer to an @c ArPointCloud* receive the
1458 /// address of the point cloud.
1459 /// @return #AR_SUCCESS or any of:
1460 /// - #AR_ERROR_DEADLINE_EXCEEDED if @c frame is not the latest frame from
1461 /// by ArSession_update().
1462 /// - #AR_ERROR_RESOURCE_EXHAUSTED if too many point clouds are currently held.
1463 ArStatus ArFrame_acquirePointCloud(const ArSession *session,
1464 const ArFrame *frame,
1465 ArPointCloud **out_point_cloud);
1467 /// Returns the camera object for the session. Note that this Camera instance is
1468 /// long-lived so the same instance is returned regardless of the frame object
1469 /// this method was called on.
1470 void ArFrame_acquireCamera(const ArSession *session,
1471 const ArFrame *frame,
1472 ArCamera **out_camera);
1474 /// Gets the camera metadata for the current camera image.
1476 /// @return #AR_SUCCESS or any of:
1477 /// - #AR_ERROR_DEADLINE_EXCEEDED if @c frame is not the latest frame from
1478 /// by ArSession_update().
1479 /// - #AR_ERROR_RESOURCE_EXHAUSTED if too many metadata objects are currently
1481 /// - #AR_ERROR_NOT_YET_AVAILABLE if the camera failed to produce metadata for
1482 /// the given frame. Note: this will commonly happen for few frames right
1483 /// after @c ArSession_resume() due to the camera stack bringup.
1484 ArStatus ArFrame_acquireImageMetadata(const ArSession *session,
1485 const ArFrame *frame,
1486 ArImageMetadata **out_metadata);
1488 /// Gets the set of anchors that were changed by the ArSession_update() that
1489 /// produced this Frame.
1491 /// @param[in] session The ARCore session
1492 /// @param[in] frame The current frame.
1493 /// @param[inout] out_anchor_list The list to fill. This list must have
1494 /// already been allocated with ArAnchorList_create(). If previously
1495 /// used, the list will first be cleared.
1496 void ArFrame_getUpdatedAnchors(const ArSession *session,
1497 const ArFrame *frame,
1498 ArAnchorList *out_anchor_list);
1500 /// Gets the set of trackables of a particular type that were changed by the
1501 /// ArSession_update() call that produced this Frame.
1503 /// @param[in] session The ARCore session
1504 /// @param[in] frame The current frame.
1505 /// @param[in] filter_type The type(s) of trackables to return. See
1506 /// ::ArTrackableType for legal values.
1507 /// @param[inout] out_trackable_list The list to fill. This list must have
1508 /// already been allocated with ArTrackableList_create(). If previously
1509 /// used, the list will first be cleared.
1510 void ArFrame_getUpdatedTrackables(const ArSession *session,
1511 const ArFrame *frame,
1512 ArTrackableType filter_type,
1513 ArTrackableList *out_trackable_list);
1516 // === ArPointCloud methods ===
1518 /// @addtogroup pointcloud
1521 /// Retrieves the number of points in the point cloud.
1523 void ArPointCloud_getNumberOfPoints(const ArSession *session,
1524 const ArPointCloud *point_cloud,
1525 int32_t *out_number_of_points);
1527 /// Retrieves a pointer to the point cloud data.
1529 /// Each point is represented by four consecutive values in the array; first the
1530 /// X, Y, Z position coordinates, followed by a confidence value. This is the
1531 /// same format as described in <a
1532 /// href="https://developer.android.com/reference/android/graphics/ImageFormat.html#DEPTH_POINT_CLOUD"
1533 /// >DEPTH_POINT_CLOUD</a>.
1535 /// The pointer returned by this function is valid until ArPointCloud_release()
1536 /// is called. The application must copy the data if they wish to retain it for
1537 /// longer. The points are in world coordinates consistent with the frame it was
1538 /// obtained from. If the number of points is zero, then the value of
1539 /// @c *out_point_cloud_data should is undefined.
1540 void ArPointCloud_getData(const ArSession *session,
1541 const ArPointCloud *point_cloud,
1542 const float **out_point_cloud_data);
1544 /// Returns the timestamp in nanoseconds when this point cloud was observed.
1545 /// This timestamp uses the same time base as ArFrame_getTimestamp().
1546 void ArPointCloud_getTimestamp(const ArSession *session,
1547 const ArPointCloud *point_cloud,
1548 int64_t *out_timestamp_ns);
1550 /// Releases a reference to the point cloud. This must match a call to
1551 /// ArFrame_acquirePointCloud().
1553 /// This method may safely be called with @c nullptr - it will do nothing.
1554 void ArPointCloud_release(ArPointCloud *point_cloud);
1558 // === Image Metadata methods ===
1560 /// @addtogroup image
1563 /// Retrieves the capture metadata for the current camera image.
1565 /// @c ACameraMetadata is a struct in Android NDK. Include NdkCameraMetadata.h
1566 /// to use this type.
1568 /// Note: that the ACameraMetadata returned from this function will be invalid
1569 /// after its ArImageMetadata object is released.
1570 void ArImageMetadata_getNdkCameraMetadata(
1571 const ArSession *session,
1572 const ArImageMetadata *image_metadata,
1573 const ACameraMetadata **out_ndk_metadata);
1575 /// Releases a reference to the metadata. This must match a call to
1576 /// ArFrame_acquireImageMetadata().
1578 /// This method may safely be called with @c nullptr - it will do nothing.
1579 void ArImageMetadata_release(ArImageMetadata *metadata);
1581 // === CPU Image Access types and methods ===
1582 /// Gets the image of the tracking camera relative to the input session and
1585 /// @returns #AR_SUCCESS or any of:
1586 /// - #AR_ERROR_INVALID_ARGUMENT - one more input arguments are invalid.
1587 /// - #AR_ERROR_DEADLINE_EXCEEDED - the input frame is not the current frame.
1588 /// - #AR_ERROR_RESOURCE_EXHAUSTED - the caller app has exceeded maximum number
1589 /// of images that it can hold without releasing.
1590 /// - #AR_ERROR_NOT_YET_AVAILABLE - image with the timestamp of the input frame
1591 /// was not found within a bounded amount of time, or the camera failed to
1592 /// produce the image
1593 ArStatus ArFrame_acquireCameraImage(ArSession *session,
1595 ArImage **out_image);
1597 /// Converts an ArImage object to an Android NDK AImage object.
1598 void ArImage_getNdkImage(const ArImage *image, const AImage **out_ndk_image);
1600 /// Releases an instance of ArImage returned by ArFrame_acquireCameraImage().
1601 void ArImage_release(ArImage *image);
1604 // === ArLightEstimate methods ===
1606 /// @addtogroup light
1609 /// Allocates a light estimate object.
1610 void ArLightEstimate_create(const ArSession *session,
1611 ArLightEstimate **out_light_estimate);
1613 /// Releases the provided light estimate object.
1614 void ArLightEstimate_destroy(ArLightEstimate *light_estimate);
1616 /// Retrieves the validity state of a light estimate. If the resulting value of
1617 /// @c *out_light_estimate_state is not #AR_LIGHT_ESTIMATE_STATE_VALID, the
1618 /// estimate should not be used for rendering.
1619 void ArLightEstimate_getState(const ArSession *session,
1620 const ArLightEstimate *light_estimate,
1621 ArLightEstimateState *out_light_estimate_state);
1623 /// Retrieves the pixel intensity, in gamma space, of the current camera view.
1624 /// Values are in the range (0.0, 1.0), with zero being black and one being
1626 /// If rendering in gamma space, divide this value by 0.466, which is middle
1627 /// gray in gamma space, and multiply against the final calculated color after
1629 /// If rendering in linear space, first convert this value to linear space by
1630 /// rising to the power 2.2. Normalize the result by dividing it by 0.18 which
1631 /// is middle gray in linear space. Then multiply by the final calculated color
1632 /// after rendering.
1633 void ArLightEstimate_getPixelIntensity(const ArSession *session,
1634 const ArLightEstimate *light_estimate,
1635 float *out_pixel_intensity);
1637 /// Gets the color correction values that are uploaded to the fragment shader.
1638 /// Use the RGB scale factors (components 0-2) to match the color of the light
1639 /// in the scene. Use the pixel intensity (component 3) to match the intensity
1640 /// of the light in the scene.
1642 /// `out_color_correction_4` components are:
1643 /// - `[0]` Red channel scale factor.
1644 /// - `[1]` Green channel scale factor.
1645 /// - `[2]` Blue channel scale factor.
1646 /// - `[3]` Pixel intensity. This is the same value as the one return from
1647 /// ArLightEstimate_getPixelIntensity().
1649 /// The RGB scale factors can be used independently from the pixel intensity
1650 /// value. They are put together for the convenience of only having to upload
1651 /// one float4 to the fragment shader.
1653 /// The RGB scale factors are not intended to brighten nor dim the scene. They
1654 /// are only to shift the color of the virtual object towards the color of the
1655 /// light; not intensity of the light. The pixel intensity is used to match the
1656 /// intensity of the light in the scene.
1658 /// Color correction values are reported in gamma space.
1659 /// If rendering in gamma space, component-wise multiply them against the final
1660 /// calculated color after rendering.
1661 /// If rendering in linear space, first convert the values to linear space by
1662 /// rising to the power 2.2. Then component-wise multiply against the final
1663 /// calculated color after rendering.
1664 void ArLightEstimate_getColorCorrection(const ArSession *session,
1665 const ArLightEstimate *light_estimate,
1666 float *out_color_correction_4);
1670 // === ArAnchorList methods ===
1672 /// @addtogroup anchor
1675 /// Creates an anchor list object.
1676 void ArAnchorList_create(const ArSession *session,
1677 ArAnchorList **out_anchor_list);
1679 /// Releases the memory used by an anchor list object, along with all the anchor
1680 /// references it holds.
1681 void ArAnchorList_destroy(ArAnchorList *anchor_list);
1683 /// Retrieves the number of anchors in this list.
1684 void ArAnchorList_getSize(const ArSession *session,
1685 const ArAnchorList *anchor_list,
1688 /// Acquires a reference to an indexed entry in the list. This call must
1689 /// eventually be matched with a call to ArAnchor_release().
1690 void ArAnchorList_acquireItem(const ArSession *session,
1691 const ArAnchorList *anchor_list,
1693 ArAnchor **out_anchor);
1695 // === ArAnchor methods ===
1697 /// Retrieves the pose of the anchor in the world coordinate space. This pose
1698 /// produced by this call may change each time ArSession_update() is called.
1699 /// This pose should only be used for rendering if ArAnchor_getTrackingState()
1700 /// returns #AR_TRACKING_STATE_TRACKING.
1702 /// @param[in] session The ARCore session.
1703 /// @param[in] anchor The anchor to retrieve the pose of.
1704 /// @param[inout] out_pose An already-allocated ArPose object into which the
1705 /// pose will be stored.
1706 void ArAnchor_getPose(const ArSession *session,
1707 const ArAnchor *anchor,
1710 /// Retrieves the current state of the pose of this anchor.
1711 void ArAnchor_getTrackingState(const ArSession *session,
1712 const ArAnchor *anchor,
1713 ArTrackingState *out_tracking_state);
1715 /// Tells ARCore to stop tracking and forget this anchor. This call does not
1716 /// release the reference to the anchor - that must be done separately using
1717 /// ArAnchor_release().
1718 void ArAnchor_detach(ArSession *session, ArAnchor *anchor);
1720 /// Releases a reference to an anchor. This does not mean that the anchor will
1721 /// stop tracking, as it will be obtainable from e.g. ArSession_getAllAnchors()
1722 /// if any other references exist.
1724 /// This method may safely be called with @c nullptr - it will do nothing.
1725 void ArAnchor_release(ArAnchor *anchor);
1727 /// Acquires the cloud anchor ID of the anchor. The ID acquired is an ASCII
1728 /// null-terminated string. The acquired ID must be released after use by the
1729 /// @c ArString_release function. For anchors with cloud state
1730 /// #AR_CLOUD_ANCHOR_STATE_NONE or #AR_CLOUD_ANCHOR_STATE_TASK_IN_PROGRESS, this
1731 /// will always be an empty string.
1733 /// @param[in] session The ARCore session.
1734 /// @param[in] anchor The anchor to retrieve the cloud ID of.
1735 /// @param[inout] out_cloud_anchor_id A pointer to the acquired ID string.
1736 void ArAnchor_acquireCloudAnchorId(ArSession *session,
1738 char **out_cloud_anchor_id);
1740 /// Gets the current cloud anchor state of the anchor. This state is guaranteed
1741 /// not to change until update() is called.
1743 /// @param[in] session The ARCore session.
1744 /// @param[in] anchor The anchor to retrieve the cloud state of.
1745 /// @param[inout] out_state The current cloud state of the anchor.
1746 void ArAnchor_getCloudAnchorState(const ArSession *session,
1747 const ArAnchor *anchor,
1748 ArCloudAnchorState *out_state);
1752 // === ArTrackableList methods ===
1754 /// @addtogroup trackable
1757 /// Creates a trackable list object.
1758 void ArTrackableList_create(const ArSession *session,
1759 ArTrackableList **out_trackable_list);
1761 /// Releases the memory used by a trackable list object, along with all the
1762 /// anchor references it holds.
1763 void ArTrackableList_destroy(ArTrackableList *trackable_list);
1765 /// Retrieves the number of trackables in this list.
1766 void ArTrackableList_getSize(const ArSession *session,
1767 const ArTrackableList *trackable_list,
1770 /// Acquires a reference to an indexed entry in the list. This call must
1771 /// eventually be matched with a call to ArTrackable_release().
1772 void ArTrackableList_acquireItem(const ArSession *session,
1773 const ArTrackableList *trackable_list,
1775 ArTrackable **out_trackable);
1777 // === ArTrackable methods ===
1779 /// Releases a reference to a trackable. This does not mean that the trackable
1780 /// will necessarily stop tracking. The same trackable may still be included in
1781 /// from other calls, for example ArSession_getAllTrackables().
1783 /// This method may safely be called with @c nullptr - it will do nothing.
1784 void ArTrackable_release(ArTrackable *trackable);
1786 /// Retrieves the type of the trackable. See ::ArTrackableType for valid types.
1787 void ArTrackable_getType(const ArSession *session,
1788 const ArTrackable *trackable,
1789 ArTrackableType *out_trackable_type);
1791 /// Retrieves the current state of ARCore's knowledge of the pose of this
1793 void ArTrackable_getTrackingState(const ArSession *session,
1794 const ArTrackable *trackable,
1795 ArTrackingState *out_tracking_state);
1797 /// Creates an Anchor at the given pose in the world coordinate space, attached
1798 /// to this Trackable, and acquires a reference to it. The type of Trackable
1799 /// will determine the semantics of attachment and how the Anchor's pose will be
1800 /// updated to maintain this relationship. Note that the relative offset between
1801 /// the pose of multiple Anchors attached to a Trackable may adjust slightly
1802 /// over time as ARCore updates its model of the world.
1804 /// @return #AR_SUCCESS or any of:
1805 /// - #AR_ERROR_NOT_TRACKING if the trackable's tracking state was not
1806 /// #AR_TRACKING_STATE_TRACKING
1807 /// - #AR_ERROR_SESSION_PAUSED if the session was paused
1808 /// - #AR_ERROR_RESOURCE_EXHAUSTED if too many anchors exist
1809 ArStatus ArTrackable_acquireNewAnchor(ArSession *session,
1810 ArTrackable *trackable,
1812 ArAnchor **out_anchor);
1814 /// Gets the set of anchors attached to this trackable.
1816 /// @param[in] session The ARCore session
1817 /// @param[in] trackable The trackable to query the anchors of.
1818 /// @param[inout] out_anchor_list The list to fill. This list must have
1819 /// already been allocated with ArAnchorList_create(). If previously
1820 /// used, the list will first be cleared.
1821 void ArTrackable_getAnchors(const ArSession *session,
1822 const ArTrackable *trackable,
1823 ArAnchorList *out_anchor_list);
1827 // === ArPlane methods ===
1829 /// @addtogroup plane
1832 /// Acquires a reference to the plane subsuming this plane.
1834 /// Two or more planes may be automatically merged into a single parent plane,
1835 /// resulting in this method acquiring the parent plane when called with each
1836 /// child plane. A subsumed plane becomes identical to the parent plane, and
1837 /// will continue behaving as if it were independently tracked, for example
1838 /// being included in the output of ArFrame_getUpdatedTrackables().
1840 /// In cases where a subsuming plane is itself subsumed, this function
1841 /// will always return the topmost non-subsumed plane.
1843 /// Note: this function will set @c *out_subsumed_by to NULL if the plane is not
1845 void ArPlane_acquireSubsumedBy(const ArSession *session,
1846 const ArPlane *plane,
1847 ArPlane **out_subsumed_by);
1849 /// Retrieves the type (orientation) of the plane. See ::ArPlaneType.
1850 void ArPlane_getType(const ArSession *session,
1851 const ArPlane *plane,
1852 ArPlaneType *out_plane_type);
1854 /// Returns the pose of the center of the detected plane. The pose's transformed
1855 /// +Y axis will be point normal out of the plane, with the +X and +Z axes
1856 /// orienting the extents of the bounding rectangle.
1858 /// @param[in] session The ARCore session.
1859 /// @param[in] plane The plane for which to retrieve center pose.
1860 /// @param[inout] out_pose An already-allocated ArPose object into which the
1861 /// pose will be stored.
1862 void ArPlane_getCenterPose(const ArSession *session,
1863 const ArPlane *plane,
1866 /// Retrieves the length of this plane's bounding rectangle measured along the
1867 /// local X-axis of the coordinate space defined by the output of
1868 /// ArPlane_getCenterPose().
1869 void ArPlane_getExtentX(const ArSession *session,
1870 const ArPlane *plane,
1871 float *out_extent_x);
1873 /// Retrieves the length of this plane's bounding rectangle measured along the
1874 /// local Z-axis of the coordinate space defined by the output of
1875 /// ArPlane_getCenterPose().
1876 void ArPlane_getExtentZ(const ArSession *session,
1877 const ArPlane *plane,
1878 float *out_extent_z);
1880 /// Retrieves the number of elements (not vertices) in the boundary polygon.
1881 /// The number of vertices is 1/2 this size.
1882 void ArPlane_getPolygonSize(const ArSession *session,
1883 const ArPlane *plane,
1884 int32_t *out_polygon_size);
1886 /// Returns the 2D vertices of a convex polygon approximating the detected
1887 /// plane, in the form <tt>[x1, z1, x2, z2, ...]</tt>. These X-Z values are in
1888 /// the plane's local x-z plane (y=0) and must be transformed by the pose
1889 /// (ArPlane_getCenterPose()) to get the boundary in world coordinates.
1891 /// @param[in] session The ARCore session.
1892 /// @param[in] plane The plane to retrieve the polygon from.
1893 /// @param[inout] out_polygon_xz A pointer to an array of floats. The length of
1894 /// this array must be at least that reported by ArPlane_getPolygonSize().
1895 void ArPlane_getPolygon(const ArSession *session,
1896 const ArPlane *plane,
1897 float *out_polygon_xz);
1899 /// Sets @c *out_pose_in_extents to non-zero if the given pose (usually obtained
1900 /// from a HitResult) is in the plane's rectangular extents.
1901 void ArPlane_isPoseInExtents(const ArSession *session,
1902 const ArPlane *plane,
1904 int32_t *out_pose_in_extents);
1906 /// Sets @c *out_pose_in_extents to non-zero if the given pose (usually obtained
1907 /// from a HitResult) is in the plane's polygon.
1908 void ArPlane_isPoseInPolygon(const ArSession *session,
1909 const ArPlane *plane,
1911 int32_t *out_pose_in_polygon);
1915 // === ArPoint methods ===
1917 /// @addtogroup point
1920 /// Returns the pose of the point.
1921 /// If ArPoint_getOrientationMode() returns ESTIMATED_SURFACE_NORMAL, the
1922 /// orientation will follow the behavior described in ArHitResult_getHitPose().
1923 /// If ArPoint_getOrientationMode() returns INITIALIZED_TO_IDENTITY, then
1924 /// returns an orientation that is identity or close to identity.
1925 /// @param[in] session The ARCore session.
1926 /// @param[in] point The point to retrieve the pose of.
1927 /// @param[inout] out_pose An already-allocated ArPose object into which the
1928 /// pose will be stored.
1929 void ArPoint_getPose(const ArSession *session,
1930 const ArPoint *point,
1933 /// Returns the OrientationMode of the point. For @c Point objects created by
1934 /// ArFrame_hitTest().
1935 /// If OrientationMode is ESTIMATED_SURFACE_NORMAL, then normal of the surface
1936 /// centered around the ArPoint was estimated succesfully.
1938 /// @param[in] session The ARCore session.
1939 /// @param[in] point The point to retrieve the pose of.
1940 /// @param[inout] out_orientation_mode OrientationMode output result for the
1942 void ArPoint_getOrientationMode(const ArSession *session,
1943 const ArPoint *point,
1944 ArPointOrientationMode *out_orientation_mode);
1948 // === ArAugmentedImage methods ===
1950 /// @addtogroup augmented_image
1953 /// Returns the pose of the center of the detected image. The pose's
1954 /// transformed +Y axis will be point normal out of the image.
1956 /// If the tracking state is PAUSED/STOPPED, this returns the pose when the
1957 /// image state was last TRACKING, or the identity pose if the image state has
1958 /// never been TRACKING.
1959 void ArAugmentedImage_getCenterPose(const ArSession *session,
1960 const ArAugmentedImage *augmented_image,
1963 /// Retrieves the estimated width, in metres, of the corresponding physical
1964 /// image, as measured along the local X-axis of the coordinate space with
1965 /// origin and axes as defined by ArAugmentedImage_getCenterPose().
1967 /// ARCore will attempt to estimate the physical image's width and continuously
1968 /// update this estimate based on its understanding of the world. If the
1969 /// optional physical size is specified in the image database, this estimation
1970 /// process will happen more quickly. However, the estimated size may be
1971 /// different from the originally specified size.
1973 /// If the tracking state is PAUSED/STOPPED, this returns the estimated width
1974 /// when the image state was last TRACKING. If the image state has never been
1975 /// TRACKING, this returns 0, even the image has a specified physical size in
1976 /// the image database.
1977 void ArAugmentedImage_getExtentX(const ArSession *session,
1978 const ArAugmentedImage *augmented_image,
1979 float *out_extent_x);
1981 /// Retrieves the estimated height, in metres, of the corresponding physical
1982 /// image, as measured along the local Z-axis of the coordinate space with
1983 /// origin and axes as defined by ArAugmentedImage_getCenterPose().
1985 /// ARCore will attempt to estimate the physical image's height and continuously
1986 /// update this estimate based on its understanding of the world. If an optional
1987 /// physical size is specified in the image database, this estimation process
1988 /// will happen more quickly. However, the estimated size may be different from
1989 /// the originally specified size.
1991 /// If the tracking state is PAUSED/STOPPED, this returns the estimated height
1992 /// when the image state was last TRACKING. If the image state has never been
1993 /// TRACKING, this returns 0, even the image has a specified physical size in
1994 /// the image database.
1995 void ArAugmentedImage_getExtentZ(const ArSession *session,
1996 const ArAugmentedImage *augmented_image,
1997 float *out_extent_z);
1999 /// Returns the zero-based positional index of this image from its originating
2002 /// This index serves as the unique identifier for the image in the database.
2003 void ArAugmentedImage_getIndex(const ArSession *session,
2004 const ArAugmentedImage *augmented_image,
2005 int32_t *out_index);
2007 /// Returns the name of this image.
2009 /// The image name is not guaranteed to be unique.
2011 /// This function will allocate memory for the name string, and set
2012 /// *out_augmented_image_name to point to that string. The caller must release
2013 /// the string using ArString_release when the string is no longer needed.
2014 void ArAugmentedImage_acquireName(const ArSession *session,
2015 const ArAugmentedImage *augmented_image,
2016 char **out_augmented_image_name);
2020 // === ArAugmentedImageDatabase methods ===
2022 /// @addtogroup augmented_image_database
2025 /// Creates a new empty image database.
2026 void ArAugmentedImageDatabase_create(
2027 const ArSession *session,
2028 ArAugmentedImageDatabase **out_augmented_image_database);
2030 /// Creates a new image database from a byte array. The contents of the byte
2031 /// array must have been generated by the command-line database generation tool
2032 /// provided in the SDK, or at runtime from ArAugmentedImageDatabase_serialize.
2034 /// Note: this function takes about 10-20ms for a 5MB byte array. Run this in a
2035 /// background thread if this affects your application.
2037 /// @return #AR_SUCCESS or any of:
2038 /// - #AR_ERROR_DATA_INVALID_FORMAT - the bytes are in an invalid format.
2039 /// - #AR_ERROR_DATA_UNSUPPORTED_VERSION - the database is not supported by
2040 /// this version of the SDK.
2041 ArStatus ArAugmentedImageDatabase_deserialize(
2042 const ArSession *session,
2043 const uint8_t *database_raw_bytes,
2044 int64_t database_raw_bytes_size,
2045 ArAugmentedImageDatabase **out_augmented_image_database);
2047 /// Serializes an image database to a byte array.
2049 /// This function will allocate memory for the serialized raw byte array, and
2050 /// set *out_image_database_raw_bytes to point to that byte array. The caller is
2051 /// expected to release the byte array using ArByteArray_release when the byte
2052 /// array is no longer needed.
2053 void ArAugmentedImageDatabase_serialize(
2054 const ArSession *session,
2055 const ArAugmentedImageDatabase *augmented_image_database,
2056 uint8_t **out_image_database_raw_bytes,
2057 int64_t *out_image_database_raw_bytes_size);
2059 /// Adds a single named image of unknown physical size to an image database,
2060 /// from an array of grayscale pixel values. Returns the zero-based positional
2061 /// index of the image within the image database.
2063 /// If the physical size of the image is known, use
2064 /// ArAugmentedImageDatabase_addImageWithPhysicalSize instead, to improve image
2067 /// For images added via ArAugmentedImageDatabase_addImage, ARCore estimates the
2068 /// physical image's size and pose at runtime when the physical image is visible
2069 /// and is being tracked. This extra estimation step will require the user to
2070 /// move their device to view the physical image from different viewpoints
2071 /// before the size and pose of the physical image can be estimated.
2073 /// This function takes time to perform non-trivial image processing (20ms -
2074 /// 30ms), and should be run on a background thread.
2076 /// The image name is expected to be a null-terminated string in UTF-8 format.
2078 /// @return #AR_SUCCESS or any of:
2079 /// - #AR_ERROR_IMAGE_INSUFFICIENT_QUALITY - image quality is insufficient, e.g.
2080 /// because of lack of features in the image.
2081 ArStatus ArAugmentedImageDatabase_addImage(
2082 const ArSession *session,
2083 ArAugmentedImageDatabase *augmented_image_database,
2084 const char *image_name,
2085 const uint8_t *image_grayscale_pixels,
2086 int32_t image_width_in_pixels,
2087 int32_t image_height_in_pixels,
2088 int32_t image_stride_in_pixels,
2089 int32_t *out_index);
2091 /// Adds a single named image to an image database, from an array of grayscale
2092 /// pixel values, along with a positive physical width in meters for this image.
2093 /// Returns the zero-based positional index of the image within the image
2096 /// If the physical size of the image is not known, use
2097 /// ArAugmentedImageDatabase_addImage instead, at the expense of an increased
2098 /// image detection time.
2100 /// For images added via ArAugmentedImageDatabase_addImageWithPhysicalSize,
2101 /// ARCore can estimate the pose of the physical image at runtime as soon as
2102 /// ARCore detects the physical image, without requiring the user to move the
2103 /// device to view the physical image from different viewpoints. Note that
2104 /// ARCore will refine the estimated size and pose of the physical image as it
2105 /// is viewed from different viewpoints.
2107 /// This function takes time to perform non-trivial image processing (20ms -
2108 /// 30ms), and should be run on a background thread.
2110 /// The image name is expected to be a null-terminated string in UTF-8 format.
2112 /// @return #AR_SUCCESS or any of:
2113 /// - #AR_ERROR_IMAGE_INSUFFICIENT_QUALITY - image quality is insufficient, e.g.
2114 /// because of lack of features in the image.
2115 /// - #AR_ERROR_INVALID_ARGUMENT - image_width_in_meters is <= 0.
2116 ArStatus ArAugmentedImageDatabase_addImageWithPhysicalSize(
2117 const ArSession *session,
2118 ArAugmentedImageDatabase *augmented_image_database,
2119 const char *image_name,
2120 const uint8_t *image_grayscale_pixels,
2121 int32_t image_width_in_pixels,
2122 int32_t image_height_in_pixels,
2123 int32_t image_stride_in_pixels,
2124 float image_width_in_meters,
2125 int32_t *out_index);
2127 /// Returns the number of images in the image database.
2128 void ArAugmentedImageDatabase_getNumImages(
2129 const ArSession *session,
2130 const ArAugmentedImageDatabase *augmented_image_database,
2131 int32_t *out_num_images);
2133 /// Releases memory used by an image database.
2134 void ArAugmentedImageDatabase_destroy(
2135 ArAugmentedImageDatabase *augmented_image_database);
2139 // === ArHitResultList methods ===
2144 /// Creates a hit result list object.
2145 void ArHitResultList_create(const ArSession *session,
2146 ArHitResultList **out_hit_result_list);
2148 /// Releases the memory used by a hit result list object, along with all the
2149 /// trackable references it holds.
2150 void ArHitResultList_destroy(ArHitResultList *hit_result_list);
2152 /// Retrieves the number of hit results in this list.
2153 void ArHitResultList_getSize(const ArSession *session,
2154 const ArHitResultList *hit_result_list,
2157 /// Copies an indexed entry in the list. This acquires a reference to any
2158 /// trackable referenced by the item, and releases any reference currently held
2159 /// by the provided result object.
2161 /// @param[in] session The ARCore session.
2162 /// @param[in] hit_result_list The list from which to copy an item.
2163 /// @param[in] index Index of the entry to copy.
2164 /// @param[inout] out_hit_result An already-allocated ArHitResult object into
2165 /// which the result will be copied.
2166 void ArHitResultList_getItem(const ArSession *session,
2167 const ArHitResultList *hit_result_list,
2169 ArHitResult *out_hit_result);
2171 // === ArHitResult methods ===
2173 /// Allocates an empty hit result object.
2174 void ArHitResult_create(const ArSession *session, ArHitResult **out_hit_result);
2176 /// Releases the memory used by a hit result object, along with any
2177 /// trackable reference it holds.
2178 void ArHitResult_destroy(ArHitResult *hit_result);
2180 /// Returns the distance from the camera to the hit location, in meters.
2181 void ArHitResult_getDistance(const ArSession *session,
2182 const ArHitResult *hit_result,
2183 float *out_distance);
2185 /// Returns the pose of the intersection between a ray and detected real-world
2186 /// geometry. The position is the location in space where the ray intersected
2187 /// the geometry. The orientation is a best effort to face the user's device,
2188 /// and its exact definition differs depending on the Trackable that was hit.
2190 /// ::ArPlane : X+ is perpendicular to the cast ray and parallel to the plane,
2191 /// Y+ points along the plane normal (up, for #AR_PLANE_HORIZONTAL_UPWARD_FACING
2192 /// planes), and Z+ is parallel to the plane, pointing roughly toward the
2196 /// Attempt to estimate the normal of the surface centered around the hit test.
2197 /// Surface normal estimation is most likely to succeed on textured surfaces
2198 /// and with camera motion.
2199 /// If ArPoint_getOrientationMode() returns ESTIMATED_SURFACE_NORMAL,
2200 /// then X+ is perpendicular to the cast ray and parallel to the physical
2201 /// surface centered around the hit test, Y+ points along the estimated surface
2202 /// normal, and Z+ points roughly toward the user's device. If
2203 /// ArPoint_getOrientationMode() returns INITIALIZED_TO_IDENTITY, then X+ is
2204 /// perpendicular to the cast ray and points right from the perspective of the
2205 /// user's device, Y+ points up, and Z+ points roughly toward the user's device.
2207 /// If you wish to retain the location of this pose beyond the duration of a
2208 /// single frame, create an anchor using ArHitResult_acquireNewAnchor() to save
2209 /// the pose in a physically consistent way.
2211 /// @param[in] session The ARCore session.
2212 /// @param[in] hit_result The hit result to retrieve the pose of.
2213 /// @param[inout] out_pose An already-allocated ArPose object into which the
2214 /// pose will be stored.
2215 void ArHitResult_getHitPose(const ArSession *session,
2216 const ArHitResult *hit_result,
2219 /// Acquires reference to the hit trackable. This call must be paired with a
2220 /// call to ArTrackable_release().
2221 void ArHitResult_acquireTrackable(const ArSession *session,
2222 const ArHitResult *hit_result,
2223 ArTrackable **out_trackable);
2225 /// Creates a new anchor at the hit location. See ArHitResult_getHitPose() for
2226 /// details. This is equivalent to creating an anchor on the hit trackable at
2229 /// @return #AR_SUCCESS or any of:
2230 /// - #AR_ERROR_NOT_TRACKING
2231 /// - #AR_ERROR_SESSION_PAUSED
2232 /// - #AR_ERROR_RESOURCE_EXHAUSTED
2233 /// - #AR_ERROR_DEADLINE_EXCEEDED - hit result must be used before the next call
2235 ArStatus ArHitResult_acquireNewAnchor(ArSession *session,
2236 ArHitResult *hit_result,
2237 ArAnchor **out_anchor);
2241 // Utility methods for releasing data.
2243 /// Releases a string acquired using an ARCore API function.
2245 /// @param[in] str The string to be released.
2246 void ArString_release(char *str);
2248 /// Releases a byte array created using an ARCore API function.
2249 void ArByteArray_release(uint8_t *byte_array);
2255 #endif // ARCORE_C_API_H_