ArCamera

Provides information about the camera that is used to capture images.

Summary

Typedefs

ArCamera typedef
struct ArCamera_
The virtual and physical camera (reference type, long-lived).

Functions

ArCamera_getDisplayOrientedPose(const ArSession *session, const ArCamera *camera, ArPose *out_pose)
void
Sets out_pose to the virtual camera pose in world space for rendering AR content onto the latest frame.
ArCamera_getImageIntrinsics(const ArSession *session, const ArCamera *camera, ArCameraIntrinsics *out_camera_intrinsics)
void
Retrieves the unrotated and uncropped intrinsics for the image (CPU) stream.
ArCamera_getPose(const ArSession *session, const ArCamera *camera, ArPose *out_pose)
void
Sets out_pose to the pose of the physical camera in world space for the latest frame.
ArCamera_getProjectionMatrix(const ArSession *session, const ArCamera *camera, float near, float far, float *dest_col_major_4x4)
void
Computes a projection matrix for rendering virtual content on top of the camera image.
ArCamera_getTextureIntrinsics(const ArSession *session, const ArCamera *camera, ArCameraIntrinsics *out_camera_intrinsics)
void
Retrieves the unrotated and uncropped intrinsics for the GPU texture stream.
ArCamera_getTrackingFailureReason(const ArSession *session, const ArCamera *camera, ArTrackingFailureReason *out_tracking_failure_reason)
void
ArCamera_getTrackingState(const ArSession *session, const ArCamera *camera, ArTrackingState *out_tracking_state)
void
Gets the current motion tracking state of this camera.
ArCamera_getViewMatrix(const ArSession *session, const ArCamera *camera, float *out_col_major_4x4)
void
Returns the view matrix for the camera for this frame.
ArCamera_release(ArCamera *camera)
void
Releases a reference to the camera.

Typedefs

ArCamera

struct ArCamera_ ArCamera

The virtual and physical camera (reference type, long-lived).

Functions

ArCamera_getDisplayOrientedPose

void ArCamera_getDisplayOrientedPose(
  const ArSession *session,
  const ArCamera *camera,
  ArPose *out_pose
)

Sets out_pose to the virtual camera pose in world space for rendering AR content onto the latest frame.

This is an OpenGL camera pose with +X pointing right, +Y pointing up, and -Z pointing in the direction the camera is looking, with "right" and "up" being relative to current logical display orientation.

See Also:

Note: This pose is only useful when ArCamera_getTrackingState returns AR_TRACKING_STATE_TRACKING and otherwise should not be used.

Details
Parameters
session
The ARCore session
camera
The session's camera (retrieved from any frame).
out_pose
An already-allocated ArPose object into which the pose will be stored.

ArCamera_getImageIntrinsics

void ArCamera_getImageIntrinsics(
  const ArSession *session,
  const ArCamera *camera,
  ArCameraIntrinsics *out_camera_intrinsics
)

Retrieves the unrotated and uncropped intrinsics for the image (CPU) stream.

The intrinsics may change per frame, so this should be called on each frame to get the intrinsics for the current frame.

Details
Parameters
session
The ARCore session
camera
The session's camera.
out_camera_intrinsics

ArCamera_getPose

void ArCamera_getPose(
  const ArSession *session,
  const ArCamera *camera,
  ArPose *out_pose
)

Sets out_pose to the pose of the physical camera in world space for the latest frame.

This is an OpenGL camera pose with +X pointing right, +Y pointing right up, -Z pointing in the direction the camera is looking, with "right" and "up" being relative to the image readout in the usual left-to-right top-to-bottom order. Specifically, this is the camera pose at the center of exposure of the center row of the image.

For applications using the SDK for ARCore 1.5.0 and earlier, the returned pose is rotated around the Z axis by a multiple of 90 degrees so that the axes correspond approximately to those of the Android Sensor Coordinate System.

See Also:

Note: This pose is only useful when ArCamera_getTrackingState returns AR_TRACKING_STATE_TRACKING and otherwise should not be used.

Details
Parameters
session
The ARCore session
camera
The session's camera (retrieved from any frame).
out_pose
An already-allocated ArPose object into which the pose will be stored.

ArCamera_getProjectionMatrix

void ArCamera_getProjectionMatrix(
  const ArSession *session,
  const ArCamera *camera,
  float near,
  float far,
  float *dest_col_major_4x4
)

Computes a projection matrix for rendering virtual content on top of the camera image.

Note that the projection matrix reflects the current display geometry and display rotation.

Note: When using the front-facing (selfie) camera, the returned projection matrix will incorporate a horizontal flip.

Details
Parameters
session
The ARCore session
camera
The session's camera.
near
Specifies the near clip plane, in meters
far
Specifies the far clip plane, in meters
dest_col_major_4x4
Pointer to an array of 16 floats, to be filled with a column-major homogenous transformation matrix, as used by OpenGL.

ArCamera_getTextureIntrinsics

void ArCamera_getTextureIntrinsics(
  const ArSession *session,
  const ArCamera *camera,
  ArCameraIntrinsics *out_camera_intrinsics
)

Retrieves the unrotated and uncropped intrinsics for the GPU texture stream.

The intrinsics may change per frame, so this should be called on each frame to get the intrinsics for the current frame.

Details
Parameters
session
The ARCore session
camera
The session's camera.
out_camera_intrinsics

ArCamera_getTrackingFailureReason

void ArCamera_getTrackingFailureReason(
  const ArSession *session,
  const ArCamera *camera,
  ArTrackingFailureReason *out_tracking_failure_reason
)

Gets the reason that ArCamera_getTrackingState is AR_TRACKING_STATE_PAUSED.

Note: This function returns AR_TRACKING_FAILURE_REASON_NONE briefly after ArSession_resume while the motion tracking is initializing. This function always returns AR_TRACKING_FAILURE_REASON_NONE when ArCamera_getTrackingState is AR_TRACKING_STATE_TRACKING.

If multiple potential causes for motion tracking failure are detected, this reports the most actionable failure reason.

ArCamera_getTrackingState

void ArCamera_getTrackingState(
  const ArSession *session,
  const ArCamera *camera,
  ArTrackingState *out_tracking_state
)

Gets the current motion tracking state of this camera.

If this state is anything other than AR_TRACKING_STATE_TRACKING the pose should not be considered useful. Use ArCamera_getTrackingFailureReason to determine the best recommendation to provide to the user to restore motion tracking.

Note: Starting in ARCore 1.12, changing the active camera config using ArSession_setCameraConfig may cause the tracking state on certain devices to become permanently AR_TRACKING_STATE_PAUSED. For consistent behavior across all supported devices, release any previously created anchors and trackables when setting a new camera config.

ArCamera_getViewMatrix

void ArCamera_getViewMatrix(
  const ArSession *session,
  const ArCamera *camera,
  float *out_col_major_4x4
)

Returns the view matrix for the camera for this frame.

This matrix performs the inverse transform as the pose provided by ArCamera_getDisplayOrientedPose.

Details
Parameters
session
The ARCore session
camera
The session's camera.
out_col_major_4x4
Pointer to an array of 16 floats, to be filled with a column-major homogenous transformation matrix, as used by OpenGL.

ArCamera_release

void ArCamera_release(
  ArCamera *camera
)

Releases a reference to the camera.

This must match a call to ArFrame_acquireCamera.

This function may safely be called with NULL - it will do nothing.