ArConfig
Session configuration.
Summary
To configure an ArSession:
- Use
ArConfig_create
to create anArConfig
object. - Call any number of configuration functions on the newly created object.
- To apply the configuration to the session, use
ArSession_configure
. - To release the memory used by the
ArConfig
object, useArConfig_destroy
.
Note: None of the ArConfig_set*()
functions will actually affect the state of the given ArSession
until ArSession_configure
is called.
Typedefs |
|
---|---|
ArConfig
|
typedefstruct ArConfig_
An opaque session configuration object (value type). |
Functions |
|
---|---|
ArConfig_create(const ArSession *session, ArConfig **out_config)
|
void
Creates a new configuration object and initializes it to a sensible default configuration.
|
ArConfig_destroy(ArConfig *config)
|
void
Releases memory used by the provided configuration object.
|
ArConfig_getAugmentedFaceMode(const ArSession *session, const ArConfig *config, ArAugmentedFaceMode *augmented_face_mode)
|
void
Stores the currently configured augmented face mode into
*augmented_face_mode . |
ArConfig_getAugmentedImageDatabase(const ArSession *session, const ArConfig *config, ArAugmentedImageDatabase *out_augmented_image_database)
|
void
Returns the image database from the session configuration.
|
ArConfig_getCloudAnchorMode(const ArSession *session, const ArConfig *config, ArCloudAnchorMode *out_cloud_anchor_mode)
|
void
Gets the current Cloud Anchor mode from the
ArConfig . |
ArConfig_getDepthMode(const ArSession *session, const ArConfig *config, ArDepthMode *out_depth_mode)
|
void
Gets the currently configured desired
ArDepthMode . |
ArConfig_getFocusMode(const ArSession *session, ArConfig *config, ArFocusMode *focus_mode)
|
void
Stores the currently configured desired focus mode into
*focus_mode . |
ArConfig_getGeospatialMode(const ArSession *session, const ArConfig *config, ArGeospatialMode *out_geospatial_mode)
|
void
Gets the current geospatial mode set on the configuration.
|
ArConfig_getInstantPlacementMode(const ArSession *session, const ArConfig *config, ArInstantPlacementMode *instant_placement_mode)
|
void
Gets the current Instant Placement Region mode from the
ArConfig . |
ArConfig_getLightEstimationMode(const ArSession *session, const ArConfig *config, ArLightEstimationMode *light_estimation_mode)
|
void
Stores the currently configured
ArLightEstimationMode mode into *light_estimation_mode . |
ArConfig_getPlaneFindingMode(const ArSession *session, const ArConfig *config, ArPlaneFindingMode *plane_finding_mode)
|
void
Stores the currently configured plane finding mode into
*plane_finding_mode . |
ArConfig_getUpdateMode(const ArSession *session, const ArConfig *config, ArUpdateMode *update_mode)
|
void
Stores the currently configured behavior of
ArSession_update into *update_mode . |
ArConfig_setAugmentedFaceMode(const ArSession *session, ArConfig *config, ArAugmentedFaceMode augmented_face_mode)
|
void
Sets the desired face mode.
|
ArConfig_setAugmentedImageDatabase(const ArSession *session, ArConfig *config, const ArAugmentedImageDatabase *augmented_image_database)
|
void
Sets the image database in the session configuration.
|
ArConfig_setCloudAnchorMode(const ArSession *session, ArConfig *config, ArCloudAnchorMode cloud_anchor_mode)
|
void
Sets the desired cloud configuration.
|
ArConfig_setDepthMode(const ArSession *session, ArConfig *config, ArDepthMode mode)
|
void
Sets the desired
ArDepthMode . |
ArConfig_setFocusMode(const ArSession *session, ArConfig *config, ArFocusMode focus_mode)
|
void
On supported devices, selects the desired camera focus mode.
|
ArConfig_setGeospatialMode(const ArSession *session, ArConfig *config, ArGeospatialMode geospatial_mode)
|
void
Sets the Geospatial mode.
|
ArConfig_setInstantPlacementMode(const ArSession *session, ArConfig *config, ArInstantPlacementMode instant_placement_mode)
|
void
Sets the current Instant Placement mode from the
ArConfig . |
ArConfig_setLightEstimationMode(const ArSession *session, ArConfig *config, ArLightEstimationMode light_estimation_mode)
|
void
Sets the desired
ArLightEstimationMode . |
ArConfig_setPlaneFindingMode(const ArSession *session, ArConfig *config, ArPlaneFindingMode plane_finding_mode)
|
void
Sets the desired plane finding mode.
|
ArConfig_setUpdateMode(const ArSession *session, ArConfig *config, ArUpdateMode update_mode)
|
void
Sets the behavior of
ArSession_update . |
Enumerations
ArAugmentedFaceMode
ArAugmentedFaceMode
Selects the behavior of Augmented Faces subsystem.
Default value is AR_AUGMENTED_FACE_MODE_DISABLED
.
Properties | |
---|---|
AR_AUGMENTED_FACE_MODE_DISABLED
|
Disable augmented face mode. |
AR_AUGMENTED_FACE_MODE_MESH3D
|
Face 3D mesh is enabled. Augmented Faces is currently only supported when using the front-facing (selfie) camera. |
ArDepthMode
ArDepthMode
Selects the desired depth mode.
Not all devices support all modes, use ArSession_isDepthModeSupported
to find whether the current device and the selected camera support a particular depth mode.
Properties | |
---|---|
AR_DEPTH_MODE_AUTOMATIC
|
On supported devices the best possible depth is estimated based on hardware and software sources. Available sources of automatic depth are:
Provides depth estimation for every pixel in the image, and works best for static scenes. For a list of supported devices, see: https://developers.google.com/ar/devices Adds significant computational load. With this mode enabled, |
AR_DEPTH_MODE_DISABLED
|
No depth information will be provided. Calling |
AR_DEPTH_MODE_RAW_DEPTH_ONLY
|
On ARCore supported devices that also support the Depth API, provides a "raw", mostly unfiltered, depth image ( The raw depth image is sparse and does not provide valid depth for all pixels. Pixels without a valid depth estimate have a pixel value of 0. Raw depth data is also available when Raw depth is intended to be used in cases that involve understanding of the geometry in the environment. |
ArFocusMode
ArFocusMode
Selects the desired behavior of the camera focus subsystem.
Properties | |
---|---|
AR_FOCUS_MODE_AUTO
|
Auto-focus is enabled. |
AR_FOCUS_MODE_FIXED
|
Focus is fixed. |
ArGeospatialMode
ArGeospatialMode
Describes the desired behavior of the ARCore Geospatial API.
The Geospatial API uses a combination of Google's Visual Positioning System (VPS) and GPS to determine the geospatial pose.
The Geospatial API is able to provide the best user experience when it is able to generate high accuracy poses. However, the Geospatial API can be used anywhere, as long as the device is able to determine its location, even if the available location information has low accuracy.
- In areas with VPS coverage, the Geospatial API is able to generate high accuracy poses. This can work even where GPS accuracy is low, such as dense urban environments. Under typical conditions, VPS can be expected to provide positional accuracy typically better than 5 meters and often around 1 meter, and a rotational accuracy of better than 5 degrees. Use
ArSession_checkVpsAvailabilityAsync
to determine if a given location has VPS coverage. - In outdoor environments with few or no overhead obstructions, GPS may be sufficient to generate high accuracy poses. GPS accuracy may be low in dense urban environments and indoors.
A small number of ARCore supported devices do not support the Geospatial API. Use ArSession_isGeospatialModeSupported
to determine if the current device is supported. Affected devices are also indicated on the ARCore supported devices page.
The default value is AR_GEOSPATIAL_MODE_DISABLED
. Use ArConfig_setGeospatialMode
to set the desired mode.
Properties | |
---|---|
AR_GEOSPATIAL_MODE_DISABLED
|
The Geospatial API is disabled. When a configuration with |
AR_GEOSPATIAL_MODE_ENABLED
|
The Geospatial API is enabled.
Using this mode requires your app do the following:
Location is tracked only while For more information, see documentation on the Geospatial API on Google Developers. This mode is not compatible with the front-facing (selfie) camera. If Not all devices support |
ArLightEstimationMode
ArLightEstimationMode
Select the behavior of the Lighting Estimation subsystem.
Properties | |
---|---|
AR_LIGHT_ESTIMATION_MODE_AMBIENT_INTENSITY
|
Lighting Estimation is enabled, generating a single-value intensity estimate and three (R, G, B) color correction values. |
AR_LIGHT_ESTIMATION_MODE_DISABLED
|
Lighting Estimation is disabled. |
AR_LIGHT_ESTIMATION_MODE_ENVIRONMENTAL_HDR
|
Lighting Estimation is enabled, generating inferred Environmental HDR Lighting Estimation in linear color space. Note, |
ArPlaneFindingMode
ArPlaneFindingMode
Select the behavior of the plane detection subsystem.
Properties | |
---|---|
AR_PLANE_FINDING_MODE_DISABLED
|
Plane detection is disabled. |
AR_PLANE_FINDING_MODE_HORIZONTAL
|
Detection of only horizontal planes is enabled. |
AR_PLANE_FINDING_MODE_HORIZONTAL_AND_VERTICAL
|
Detection of horizontal and vertical planes is enabled. |
AR_PLANE_FINDING_MODE_VERTICAL
|
Detection of only vertical planes is enabled. |
ArUpdateMode
ArUpdateMode
Selects the behavior of ArSession_update
.
Properties | |
---|---|
AR_UPDATE_MODE_BLOCKING
|
On most devices the camera is configured to capture 30 frames per second. If the camera image does not arrive by the built-in timeout, then |
AR_UPDATE_MODE_LATEST_CAMERA_IMAGE
|
If no new camera image is available, then |
Typedefs
ArConfig
struct ArConfig_ ArConfig
An opaque session configuration object (value type).
- Create with:
ArConfig_create
- Release with:
ArConfig_destroy
Functions
ArConfig_create
void ArConfig_create( const ArSession *session, ArConfig **out_config )
Creates a new configuration object and initializes it to a sensible default configuration.
Plane detection and Lighting Estimation are enabled, and blocking update is selected. This configuration is guaranteed to be supported on all devices that support ARCore.
ArConfig_destroy
void ArConfig_destroy( ArConfig *config )
Releases memory used by the provided configuration object.
ArConfig_getAugmentedFaceMode
void ArConfig_getAugmentedFaceMode( const ArSession *session, const ArConfig *config, ArAugmentedFaceMode *augmented_face_mode )
Stores the currently configured augmented face mode into *augmented_face_mode
.
ArConfig_getAugmentedImageDatabase
void ArConfig_getAugmentedImageDatabase( const ArSession *session, const ArConfig *config, ArAugmentedImageDatabase *out_augmented_image_database )
Returns the image database from the session configuration.
This function returns a copy of the internally stored image database, so any changes to the copy will not affect the current configuration or session.
If no ArAugmentedImageDatabase
has been configured, a new empty database will be constructed using ArAugmentedImageDatabase_create
.
ArConfig_getCloudAnchorMode
void ArConfig_getCloudAnchorMode( const ArSession *session, const ArConfig *config, ArCloudAnchorMode *out_cloud_anchor_mode )
Gets the current Cloud Anchor mode from the ArConfig
.
ArConfig_getDepthMode
void ArConfig_getDepthMode( const ArSession *session, const ArConfig *config, ArDepthMode *out_depth_mode )
Gets the currently configured desired ArDepthMode
.
ArConfig_getFocusMode
void ArConfig_getFocusMode( const ArSession *session, ArConfig *config, ArFocusMode *focus_mode )
Stores the currently configured desired focus mode into *focus_mode
.
Note: The desired focus mode may be different from the actual focus mode. See the ARCore supported devices page for a list of affected devices.
ArConfig_getGeospatialMode
void ArConfig_getGeospatialMode( const ArSession *session, const ArConfig *config, ArGeospatialMode *out_geospatial_mode )
Gets the current geospatial mode set on the configuration.
Details | |||||||
---|---|---|---|---|---|---|---|
Parameters |
|
ArConfig_getInstantPlacementMode
void ArConfig_getInstantPlacementMode( const ArSession *session, const ArConfig *config, ArInstantPlacementMode *instant_placement_mode )
Gets the current Instant Placement Region mode from the ArConfig
.
ArConfig_getLightEstimationMode
void ArConfig_getLightEstimationMode( const ArSession *session, const ArConfig *config, ArLightEstimationMode *light_estimation_mode )
Stores the currently configured ArLightEstimationMode
mode into *light_estimation_mode
.
ArConfig_getPlaneFindingMode
void ArConfig_getPlaneFindingMode( const ArSession *session, const ArConfig *config, ArPlaneFindingMode *plane_finding_mode )
Stores the currently configured plane finding mode into *plane_finding_mode
.
ArConfig_getUpdateMode
void ArConfig_getUpdateMode( const ArSession *session, const ArConfig *config, ArUpdateMode *update_mode )
Stores the currently configured behavior of ArSession_update
into *update_mode
.
ArConfig_setAugmentedFaceMode
void ArConfig_setAugmentedFaceMode( const ArSession *session, ArConfig *config, ArAugmentedFaceMode augmented_face_mode )
Sets the desired face mode.
See ArAugmentedFaceMode
for available options. Augmented Faces is currently only supported when using the front-facing (selfie) camera.
ArConfig_setAugmentedImageDatabase
void ArConfig_setAugmentedImageDatabase( const ArSession *session, ArConfig *config, const ArAugmentedImageDatabase *augmented_image_database )
Sets the image database in the session configuration.
Any images in the currently active image database that have a AR_TRACKING_STATE_TRACKING
or AR_TRACKING_STATE_PAUSED
state will immediately be set to the AR_TRACKING_STATE_STOPPED
state if a different or NULL
image database is set.
This function makes a copy of the image database.
ArConfig_setCloudAnchorMode
void ArConfig_setCloudAnchorMode( const ArSession *session, ArConfig *config, ArCloudAnchorMode cloud_anchor_mode )
Sets the desired cloud configuration.
See ArCloudAnchorMode
for available options.
ArConfig_setDepthMode
void ArConfig_setDepthMode( const ArSession *session, ArConfig *config, ArDepthMode mode )
Sets the desired ArDepthMode
.
Notes:
- Not all devices support all modes. Use
ArSession_isDepthModeSupported
to determine whether the current device and the selected camera support a particular depth mode. - With depth enabled through this call, calls to
ArFrame_acquireDepthImage16Bits
andArFrame_acquireRawDepthImage16Bits
can be made to acquire the latest computed depth image. - With depth enabled through this call, calling
ArFrame_hitTest
generates anArHitResultList
that also includesArDepthPoint
values that are sampled from the latest computed depth image.
ArConfig_setFocusMode
void ArConfig_setFocusMode( const ArSession *session, ArConfig *config, ArFocusMode focus_mode )
On supported devices, selects the desired camera focus mode.
On these devices, the default desired focus mode is currently AR_FOCUS_MODE_FIXED
, although this default might change in the future. See the ARCore supported devices page for a list of devices on which ARCore does not support changing the desired focus mode.
For optimal AR tracking performance, use the focus mode provided by the default session config. While capturing pictures or video, use AR_FOCUS_MODE_AUTO
. For optimal AR tracking, revert to the default focus mode once auto focus behavior is no longer needed. If your app requires fixed focus camera, set AR_FOCUS_MODE_FIXED
before enabling the AR session. This ensures that your app always uses fixed focus, even if the default camera config focus mode changes in a future release.
To determine whether the configured ARCore camera supports auto focus, check ACAMERA_LENS_INFO_MINIMUM_FOCUS_DISTANCE
, which is 0 for fixed-focus cameras.
The desired focus mode is ignored while an MP4 dataset file is being played back.
ArConfig_setGeospatialMode
void ArConfig_setGeospatialMode( const ArSession *session, ArConfig *config, ArGeospatialMode geospatial_mode )
Sets the Geospatial mode.
See ArGeospatialMode
for available options.
ArConfig_setInstantPlacementMode
void ArConfig_setInstantPlacementMode( const ArSession *session, ArConfig *config, ArInstantPlacementMode instant_placement_mode )
Sets the current Instant Placement mode from the ArConfig
.
ArConfig_setLightEstimationMode
void ArConfig_setLightEstimationMode( const ArSession *session, ArConfig *config, ArLightEstimationMode light_estimation_mode )
Sets the desired ArLightEstimationMode
.
See ArLightEstimationMode
for available options.
ArConfig_setPlaneFindingMode
void ArConfig_setPlaneFindingMode( const ArSession *session, ArConfig *config, ArPlaneFindingMode plane_finding_mode )
Sets the desired plane finding mode.
See ArPlaneFindingMode
for available options.
ArConfig_setUpdateMode
void ArConfig_setUpdateMode( const ArSession *session, ArConfig *config, ArUpdateMode update_mode )
Sets the behavior of ArSession_update
.
See ArUpdateMode
for available options.