# ArCamera

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

## Summary

| ### Typedefs ||
|---|---|
| `https://developers.google.com/ar/reference/c/group/ar-camera#arcamera` | typedef `struct ArCamera_` The virtual and physical camera ([reference type, long-lived](https://developers.google.com/ar/reference/c/group/concepts#object-ownership)). |

| ### Functions ||
|---|---|
| `https://developers.google.com/ar/reference/c/group/ar-camera#arcamera_getdisplayorientedpose(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-camera#arcamera *camera, https://developers.google.com/ar/reference/c/group/ar-pose#arpose *out_pose)` | `void` Sets `out_pose` to the virtual camera pose in world space for rendering AR content onto the latest frame. |
| `https://developers.google.com/ar/reference/c/group/ar-camera#arcamera_getimageintrinsics(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-camera#arcamera *camera, https://developers.google.com/ar/reference/c/group/ar-camera-intrinsics#arcameraintrinsics *out_camera_intrinsics)` | `void` Retrieves the unrotated and uncropped intrinsics for the image (CPU) stream. |
| `https://developers.google.com/ar/reference/c/group/ar-camera#arcamera_getpose(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-camera#arcamera *camera, https://developers.google.com/ar/reference/c/group/ar-pose#arpose *out_pose)` | `void` Sets `out_pose` to the pose of the physical camera in world space for the latest frame. |
| `https://developers.google.com/ar/reference/c/group/ar-camera#arcamera_getprojectionmatrix(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-camera#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. |
| `https://developers.google.com/ar/reference/c/group/ar-camera#arcamera_gettextureintrinsics(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-camera#arcamera *camera, https://developers.google.com/ar/reference/c/group/ar-camera-intrinsics#arcameraintrinsics *out_camera_intrinsics)` | `void` Retrieves the unrotated and uncropped intrinsics for the GPU texture stream. |
| `https://developers.google.com/ar/reference/c/group/ar-camera#arcamera_gettrackingfailurereason(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-camera#arcamera *camera, https://developers.google.com/ar/reference/c/group/shared-types#artrackingfailurereason *out_tracking_failure_reason)` | `void` Gets the reason that `https://developers.google.com/ar/reference/c/group/ar-camera#arcamera_gettrackingstate` is `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_paused`. |
| `https://developers.google.com/ar/reference/c/group/ar-camera#arcamera_gettrackingstate(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-camera#arcamera *camera, https://developers.google.com/ar/reference/c/group/shared-types#artrackingstate *out_tracking_state)` | `void` Gets the current motion tracking state of this camera. |
| `https://developers.google.com/ar/reference/c/group/ar-camera#arcamera_getviewmatrix(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-camera#arcamera *camera, float *out_col_major_4x4)` | `void` Returns the view matrix for the camera for this frame. |
| `https://developers.google.com/ar/reference/c/group/ar-camera#arcamera_release(https://developers.google.com/ar/reference/c/group/ar-camera#arcamera *camera)` | `void` Releases a reference to the camera. |

## Typedefs

### ArCamera

```
struct ArCamera_ ArCamera
```
The virtual and physical camera ([reference type, long-lived](https://developers.google.com/ar/reference/c/group/concepts#object-ownership)).


- Acquire with: `https://developers.google.com/ar/reference/c/group/ar-frame#arframe_acquirecamera`
- Release with: `https://developers.google.com/ar/reference/c/group/ar-camera#arcamera_release`

<br />

## 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:


- `https://developers.google.com/ar/reference/c/group/ar-camera#arcamera_getviewmatrix` to conveniently compute the OpenGL view matrix.
- `https://developers.google.com/ar/reference/c/group/ar-camera#arcamera_getpose` for the physical pose of the camera. It will differ by a local rotation about the Z axis by a multiple of 90 degrees.
- `https://developers.google.com/ar/reference/c/group/ar-frame#arframe_getandroidsensorpose` for the pose of the android sensor frame. It will differ in both orientation and location.
- `https://developers.google.com/ar/reference/c/group/ar-session#arsession_setdisplaygeometry` to update the display rotation.

<br />

Note: This pose is only useful when `https://developers.google.com/ar/reference/c/group/ar-camera#arcamera_gettrackingstate` returns `https://developers.google.com/ar/reference/c/group/shared-types#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 `https://developers.google.com/ar/reference/c/group/ar-pose#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` The `https://developers.google.com/ar/reference/c/group/ar-camera-intrinsics#arcameraintrinsics` data.

### 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](https://developer.android.com/guide/topics/sensors/sensors_overview#sensors-coords).

See Also:


- `https://developers.google.com/ar/reference/c/group/ar-camera#arcamera_getdisplayorientedpose` for the pose of the virtual camera. It will differ by a local rotation about the Z axis by a multiple of 90 degrees.
- `https://developers.google.com/ar/reference/c/group/ar-frame#arframe_getandroidsensorpose` for the pose of the Android sensor frame. It will differ in both orientation and location.
- `https://developers.google.com/ar/reference/c/group/ar-frame#arframe_transformcoordinates2d` to convert viewport coordinates to texture coordinates.

<br />

Note: This pose is only useful when `https://developers.google.com/ar/reference/c/group/ar-camera#arcamera_gettrackingstate` returns `https://developers.google.com/ar/reference/c/group/shared-types#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 `https://developers.google.com/ar/reference/c/group/ar-pose#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` The `https://developers.google.com/ar/reference/c/group/ar-camera-intrinsics#arcameraintrinsics` data.

### ArCamera_getTrackingFailureReason

```
void ArCamera_getTrackingFailureReason(
  const ArSession *session,
  const ArCamera *camera,
  ArTrackingFailureReason *out_tracking_failure_reason
)
```
Gets the reason that `https://developers.google.com/ar/reference/c/group/ar-camera#arcamera_gettrackingstate` is `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_paused`.

Note: This function returns `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_failure_reason_none` briefly after `https://developers.google.com/ar/reference/c/group/ar-session#arsession_resume` while the motion tracking is initializing. This function always returns `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_failure_reason_none` when `https://developers.google.com/ar/reference/c/group/ar-camera#arcamera_gettrackingstate` is `https://developers.google.com/ar/reference/c/group/shared-types#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 `https://developers.google.com/ar/reference/c/group/shared-types#ar_tracking_state_tracking` the pose should not be considered useful. Use `https://developers.google.com/ar/reference/c/group/ar-camera#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 `https://developers.google.com/ar/reference/c/group/ar-session#arsession_setcameraconfig` may cause the tracking state on certain devices to become permanently `https://developers.google.com/ar/reference/c/group/shared-types#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 `https://developers.google.com/ar/reference/c/group/ar-camera#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 `https://developers.google.com/ar/reference/c/group/ar-frame#arframe_acquirecamera`.

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