# ArImage

Provides access to CPU camera images.

## Summary

| ### Enumerations ||
|---|---|
| `https://developers.google.com/ar/reference/c/group/ar-image#arimageformat{ https://developers.google.com/ar/reference/c/group/ar-image#ar_image_format_invalid = 0, https://developers.google.com/ar/reference/c/group/ar-image#ar_image_format_yuv_420_888 = 0x23, https://developers.google.com/ar/reference/c/group/ar-image#ar_image_format_depth16 = 0x44363159, https://developers.google.com/ar/reference/c/group/ar-image#ar_image_format_d_16 = 0x00000030, https://developers.google.com/ar/reference/c/group/ar-image#ar_image_format_y8 = 0x20203859, https://developers.google.com/ar/reference/c/group/ar-image#ar_image_format_rgba_fp16 = 0x16 }` | enumImage formats produced by ARCore. |

| ### Typedefs ||
|---|---|
| `https://developers.google.com/ar/reference/c/group/ar-image#arimage` | typedef `struct ArImage_` Accessing CPU image from the camera ([reference type, large data](https://developers.google.com/ar/reference/c/group/concepts#object-ownership)). |
| `https://developers.google.com/ar/reference/c/group/ar-image#arimagecubemap[6]` | typedef `https://developers.google.com/ar/reference/c/group/ar-image#arimage *` Convenient definition for cubemap image storage where it is a fixed size array of 6 `https://developers.google.com/ar/reference/c/group/ar-image#arimage`. |

| ### Functions ||
|---|---|
| `https://developers.google.com/ar/reference/c/group/ar-image#arimage_getformat(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-image#arimage *image, https://developers.google.com/ar/reference/c/group/ar-image#arimageformat *out_format)` | `void` Gets the image format of the provided `https://developers.google.com/ar/reference/c/group/ar-image#arimage`. |
| `https://developers.google.com/ar/reference/c/group/ar-image#arimage_getheight(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-image#arimage *image, int32_t *out_height)` | `void` Gets the height of the input `https://developers.google.com/ar/reference/c/group/ar-image#arimage`. |
| `https://developers.google.com/ar/reference/c/group/ar-image#arimage_getnumberofplanes(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-image#arimage *image, int32_t *out_num_planes)` | `void` Gets the number of planes in the provided `https://developers.google.com/ar/reference/c/group/ar-image#arimage`. |
| `https://developers.google.com/ar/reference/c/group/ar-image#arimage_getplanedata(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-image#arimage *image, int32_t plane_index, const uint8_t **out_data, int32_t *out_data_length)` | `void` Gets the data pointer of the provided image for direct application access. |
| `https://developers.google.com/ar/reference/c/group/ar-image#arimage_getplanepixelstride(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-image#arimage *image, int32_t plane_index, int32_t *out_pixel_stride)` | `void` Gets the byte distance between the start of two consecutive pixels in the image. |
| `https://developers.google.com/ar/reference/c/group/ar-image#arimage_getplanerowstride(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-image#arimage *image, int32_t plane_index, int32_t *out_row_stride)` | `void` Gets the number of bytes between the start of two consecutive rows of pixels in the image. |
| `https://developers.google.com/ar/reference/c/group/ar-image#arimage_gettimestamp(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-image#arimage *image, int64_t *out_timestamp_ns)` | `void` Gets the source-specific timestamp of the provided `https://developers.google.com/ar/reference/c/group/ar-image#arimage` in nanoseconds. |
| `https://developers.google.com/ar/reference/c/group/ar-image#arimage_getwidth(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-image#arimage *image, int32_t *out_width)` | `void` Gets the width of the input `https://developers.google.com/ar/reference/c/group/ar-image#arimage`. |
| `https://developers.google.com/ar/reference/c/group/ar-image#arimage_release(https://developers.google.com/ar/reference/c/group/ar-image#arimage *image)` | `void` Releases an instance of `https://developers.google.com/ar/reference/c/group/ar-image#arimage` returned by `https://developers.google.com/ar/reference/c/group/ar-frame#arframe_acquirecameraimage`. |

## Enumerations

### ArImageFormat

```
 ArImageFormat
```
Image formats produced by ARCore.

| Properties ||
|---|---|
| `AR_IMAGE_FORMAT_DEPTH16` | Produced by `https://developers.google.com/ar/reference/c/group/ar-frame#arframe_acquiredepthimage` and `https://developers.google.com/ar/reference/c/group/ar-frame#arframe_acquirerawdepthimage`. Integer value equal to [DEPTH16](https://developer.android.com/reference/android/graphics/ImageFormat#DEPTH16). |
| `AR_IMAGE_FORMAT_D_16` | Produced by `https://developers.google.com/ar/reference/c/group/ar-frame#arframe_acquiredepthimage16bits` and `https://developers.google.com/ar/reference/c/group/ar-frame#arframe_acquirerawdepthimage16bits`. Depth range values in units of millimeters. Integer value equal to [D_16](https://developer.android.com/reference/android/hardware/HardwareBuffer#D_16). |
| `AR_IMAGE_FORMAT_INVALID` | Invalid image format. Produced by ARCore when an invalid session/image is given to `https://developers.google.com/ar/reference/c/group/ar-image#arimage_getformat`. |
| `AR_IMAGE_FORMAT_RGBA_FP16` | Produced by `https://developers.google.com/ar/reference/c/group/ar-light-estimate#arlightestimate_acquireenvironmentalhdrcubemap`. Integer value equal to Android NDK `https://developer.android.com/ndk/reference/group/media#group___media_1gga9c3dace30485a0f28163a882a5d65a19aa0f5b9a07c9f3dc8a111c0098b18363a. ` |
| `AR_IMAGE_FORMAT_Y8` | Produced by `https://developers.google.com/ar/reference/c/group/ar-frame#arframe_acquirerawdepthconfidenceimage`. Integer value equal to `https://developer.android.com/reference/android/graphics/ImageFormat#Y8. ` |
| `AR_IMAGE_FORMAT_YUV_420_888` | Produced by `https://developers.google.com/ar/reference/c/group/ar-frame#arframe_acquirecameraimage`. Integer value equal to Android NDK `` https://developer.android.com/ndk/reference/group/media#group___media_1gga9c3dace30485a0f28163a882a5d65a19aea9797f9b5db5d26a2055a43d8491890 and `https://developer.android.com/reference/android/graphics/ImageFormat#YUV_420_888. ` `` |

## Typedefs

### ArImage

```
struct ArImage_ ArImage
```
Accessing CPU image from the camera ([reference type, large data](https://developers.google.com/ar/reference/c/group/concepts#object-ownership)).


- Acquire with: `https://developers.google.com/ar/reference/c/group/ar-frame#arframe_acquirecameraimage`
- Release with: `https://developers.google.com/ar/reference/c/group/ar-image#arimage_release`.

<br />

### ArImageCubemap

```
ArImage * ArImageCubemap[6]
```
Convenient definition for cubemap image storage where it is a fixed size array of 6 `https://developers.google.com/ar/reference/c/group/ar-image#arimage`.

## Functions

### ArImage_getFormat

```
void ArImage_getFormat(
  const ArSession *session,
  const ArImage *image,
  ArImageFormat *out_format
)
```
Gets the image format of the provided `https://developers.google.com/ar/reference/c/group/ar-image#arimage`.


Details Parameters `session` The ARCore session. `image` The `https://developers.google.com/ar/reference/c/group/ar-image#arimage` of interest. `out_format` The image format, one of `https://developers.google.com/ar/reference/c/group/ar-image#arimageformat` values.

### ArImage_getHeight

```
void ArImage_getHeight(
  const ArSession *session,
  const ArImage *image,
  int32_t *out_height
)
```
Gets the height of the input `https://developers.google.com/ar/reference/c/group/ar-image#arimage`.


Details Parameters `session` The ARCore session. `image` The `https://developers.google.com/ar/reference/c/group/ar-image#arimage` of interest. `out_height` The height of the image in pixels.

### ArImage_getNumberOfPlanes

```
void ArImage_getNumberOfPlanes(
  const ArSession *session,
  const ArImage *image,
  int32_t *out_num_planes
)
```
Gets the number of planes in the provided `https://developers.google.com/ar/reference/c/group/ar-image#arimage`.

The number of planes and format of data in each plane is format dependent. Use `https://developers.google.com/ar/reference/c/group/ar-image#arimage_getformat` to determine the format.


Details Parameters `session` The ARCore session. `image` The `https://developers.google.com/ar/reference/c/group/ar-image#arimage` of interest. `out_num_planes` The number of planes in the image.

### ArImage_getPlaneData

```
void ArImage_getPlaneData(
  const ArSession *session,
  const ArImage *image,
  int32_t plane_index,
  const uint8_t **out_data,
  int32_t *out_data_length
)
```
Gets the data pointer of the provided image for direct application access.

Note that once the `https://developers.google.com/ar/reference/c/group/ar-image#arimage` data is released with `https://developers.google.com/ar/reference/c/group/ar-image#arimage_release`, the data pointer from the corresponding `https://developers.google.com/ar/reference/c/group/ar-image#arimage_getplanedata` call becomes invalid. Do NOT use it after the `https://developers.google.com/ar/reference/c/group/ar-image#arimage` is released.


Details Parameters `session` The ARCore session. `image` The `https://developers.google.com/ar/reference/c/group/ar-image#arimage` of interest. `plane_index` The index of the plane, between 0 and n-1, where n is number of planes for this image. `out_data` The data pointer to the image. `out_data_length` The length of data in bytes.

### ArImage_getPlanePixelStride

```
void ArImage_getPlanePixelStride(
  const ArSession *session,
  const ArImage *image,
  int32_t plane_index,
  int32_t *out_pixel_stride
)
```
Gets the byte distance between the start of two consecutive pixels in the image.

The pixel stride is always greater than 0.


Details Parameters `session` The ARCore session. `image` The `https://developers.google.com/ar/reference/c/group/ar-image#arimage` of interest. `plane_index` The index of the plane, between 0 and n-1, where n is number of planes for this image. `out_pixel_stride` The plane stride of the image in bytes.

### ArImage_getPlaneRowStride

```
void ArImage_getPlaneRowStride(
  const ArSession *session,
  const ArImage *image,
  int32_t plane_index,
  int32_t *out_row_stride
)
```
Gets the number of bytes between the start of two consecutive rows of pixels in the image.

The row stride is always greater than 0.


Details Parameters `session` The ARCore session. `image` The `https://developers.google.com/ar/reference/c/group/ar-image#arimage` of interest. `plane_index` The index of the plane, between 0 and n-1, where n is number of planes for this image. `out_row_stride` The row stride of the image in bytes.

### ArImage_getTimestamp

```
void ArImage_getTimestamp(
  const ArSession *session,
  const ArImage *image,
  int64_t *out_timestamp_ns
)
```
Gets the source-specific timestamp of the provided `https://developers.google.com/ar/reference/c/group/ar-image#arimage` in nanoseconds.

The timestamp is normally monotonically increasing. The timestamps for the images from different sources may have different timebases and should not be compared with each other. The specific meaning and timebase of the returned timestamp depends on the source providing images.


Details Parameters `session` The ARCore session. `image` The `https://developers.google.com/ar/reference/c/group/ar-image#arimage` of interest. `out_timestamp_ns` The timestamp of the image in nanoseconds.

### ArImage_getWidth

```
void ArImage_getWidth(
  const ArSession *session,
  const ArImage *image,
  int32_t *out_width
)
```
Gets the width of the input `https://developers.google.com/ar/reference/c/group/ar-image#arimage`.


Details Parameters `session` The ARCore session. `image` The `https://developers.google.com/ar/reference/c/group/ar-image#arimage` of interest. `out_width` The width of the image in pixels.

### ArImage_release

```
void ArImage_release(
  ArImage *image
)
```
Releases an instance of `https://developers.google.com/ar/reference/c/group/ar-image#arimage` returned by `https://developers.google.com/ar/reference/c/group/ar-frame#arframe_acquirecameraimage`.