# ImageWrapper

Artifact: [androidx.camera:camera-common](https://developer.android.com/jetpack/androidx/releases/camera) [View Source](https://cs.android.com/search?q=file:androidx/camera/common/ImageWrapper.kt+class:androidx.camera.common.ImageWrapper) Added in [1.7.0-rc02](https://developer.android.com/jetpack/androidx/releases/camera#1.7.0-rc02)

*** ** * ** ***


```
interface ImageWrapper : UnsafeWrapper, AutoCloseable
```

<br />

Known direct subclasses [ImageProxy](https://developer.android.com/reference/kotlin/androidx/camera/core/ImageProxy), [MutableImageWrapper](https://developer.android.com/reference/kotlin/androidx/camera/common/MutableImageWrapper)

|---|---|
| `https://developer.android.com/reference/kotlin/androidx/camera/core/ImageProxy` | An image proxy which has a similar interface as `https://developer.android.com/reference/android/media/Image.html`. |
| `https://developer.android.com/reference/kotlin/androidx/camera/common/MutableImageWrapper` | A mutable extension of `https://developer.android.com/reference/kotlin/androidx/camera/common/ImageWrapper` that allows modifying properties of the image. |

Known indirect subclasses [FakeImage](https://developer.android.com/reference/kotlin/androidx/camera/common/testing/FakeImage)

|---|---|
| `https://developer.android.com/reference/kotlin/androidx/camera/common/testing/FakeImage` | Fake implementation of `https://developer.android.com/reference/kotlin/androidx/camera/common/MutableImageWrapper` for testing. |

*** ** * ** ***

A wrapper interface that mirrors the primary read-only properties of `https://developer.android.com/reference/android/media/Image.html`.

This wrapper abstracts the underlying platform image format to support common operations and ease testing by allowing mocking.

```kotlin
import androidx.camera.common.ImagePlane
import androidx.camera.common.ImageWrappers
import androidx.camera.common.MutableImageWrapper

// Wrap a native android.media.Image into a MutableImageWrapper.
val imageWrapper: MutableImageWrapper = ImageWrappers.wrap(image)

// Inspect image metadata:
val width: Int = imageWrapper.width
val height: Int = imageWrapper.height
val format: Int = imageWrapper.format
val timestamp: Long = imageWrapper.timestamp
val planes: List<ImagePlane> = imageWrapper.imagePlanes

// Optionally update mutable properties such as cropRect:
imageWrapper.cropRect = Rect(0, 0, width / 2, height / 2)

// Always close the wrapper to release native resources:
imageWrapper.close()
```

```kotlin
import androidx.camera.common.ImagePlane
import androidx.camera.common.MutableImageWrapper
import androidx.camera.common.testing.FakeImage

// Create a FakeImage for unit testing without needing camera hardware or native Image buffers.
val fakeImage: MutableImageWrapper =
    FakeImage(
        width = 1920,
        height = 1080,
        format = ImageFormat.YUV_420_888,
        timestamp = 1_000_000_000L,
        cropRect = Rect(0, 0, 1920, 1080),
    )

// Access planes and pixel buffers in test assertions:
val planes: List<ImagePlane> = fakeImage.imagePlanes
val yBuffer: ByteBuffer = planes[0].buffer
val yRowStride: Int = planes[0].rowStride

// Close the fake image when finished and verify lifecycle state:
fakeImage.close()
```

## Summary

| ### Public functions |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/camera/common/ImageWrapper#close()()` Closes the underlying image and releases any associated resources. |

| ### Public properties |
|---|---|
| `https://developer.android.com/reference/android/graphics/Rect.html` | `https://developer.android.com/reference/kotlin/androidx/camera/common/ImageWrapper#cropRect()` The crop rectangle of the image. |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `https://developer.android.com/reference/kotlin/androidx/camera/common/ImageWrapper#dataSpace()` The dataspace associated with this image. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `https://developer.android.com/reference/kotlin/androidx/camera/common/ImageWrapper#format()` The format of the image. |
| `open https://developer.android.com/reference/android/hardware/HardwareBuffer.html?` | `https://developer.android.com/reference/kotlin/androidx/camera/common/ImageWrapper#hardwareBuffer()` The handle to the underlying image's hardware buffer, or `null` if this image does not support hardware buffers. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `https://developer.android.com/reference/kotlin/androidx/camera/common/ImageWrapper#height()` The height of the image in pixels. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/camera/common/ImagePlane>` | `https://developer.android.com/reference/kotlin/androidx/camera/common/ImageWrapper#imagePlanes()` The list of pixel planes for this image. |
| `open https://developer.android.com/reference/android/hardware/SyncFence.html?` | `https://developer.android.com/reference/kotlin/androidx/camera/common/ImageWrapper#syncFence()` The sync fence associated with this image, or `null` if there is no fence. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html` | `https://developer.android.com/reference/kotlin/androidx/camera/common/ImageWrapper#timestamp()` The timestamp associated with this image, in nanoseconds. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `https://developer.android.com/reference/kotlin/androidx/camera/common/ImageWrapper#width()` The width of the image in pixels. |

### Inherited functions

From [androidx.camera.common.UnsafeWrapper](https://developer.android.com/reference/kotlin/androidx/camera/common/UnsafeWrapper) `T?` `<T : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html> https://developer.android.com/reference/kotlin/androidx/camera/common/UnsafeWrapper#unwrapAs(java.lang.Class)(type: https://developer.android.com/reference/java/lang/Class.html<T>)`

Attempts to unwrap this object into the specified underlying `https://developer.android.com/reference/kotlin/androidx/camera/common/UnsafeWrapper#unwrapAs(java.lang.Class)`.

## Public functions

### close

Added in [1.7.0-rc02](https://developer.android.com/jetpack/androidx/releases/camera#1.7.0-rc02)

```
fun close(): Unit
```

Closes the underlying image and releases any associated resources.

Overridden to remove the checked `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-exception/index.html` from the throws clause for Java callers.

## Public properties

### cropRect

Added in [1.7.0-rc02](https://developer.android.com/jetpack/androidx/releases/camera#1.7.0-rc02)

```
val cropRect: Rect
```

The crop rectangle of the image.

The crop rectangle defines the region of the image that contains valid pixel data. If not set, it defaults to the full size of the image.

| See also |
|---|---|
| `https://developer.android.com/reference/android/media/Image.html#getCropRect()` |   |

### dataSpace

Added in [1.7.0-rc02](https://developer.android.com/jetpack/androidx/releases/camera#1.7.0-rc02)

```
open val dataSpace: Int
```

The dataspace associated with this image.

The dataspace defines how the color components of the image should be interpreted.

The value returned is one of the constants defined in `https://developer.android.com/reference/kotlin/androidx/camera/common/ImageDataSpace`.

Value is one of the following:

- `4096`
- `4098`
- `4100`
- `4101`
- `0`
- `406913024`
- `142671872`
- `411107328`
- `143261696`
- `168165376`
- `163971072`
- `151715840`
- `146931712`
- `281149440`
- `281280512`
- `147193856`
- `281083904`
- `155844608`
- `138477568`

<br />

| See also |
|---|---|
| `https://developer.android.com/reference/android/media/Image.html#getDataSpace()` |   |
| `https://developer.android.com/reference/kotlin/androidx/camera/common/ImageDataSpace` |   |

### format

Added in [1.7.0-rc02](https://developer.android.com/jetpack/androidx/releases/camera#1.7.0-rc02)

```
val format: Int
```

The format of the image.

The value returned is one of the constants defined in `https://developer.android.com/reference/kotlin/androidx/camera/common/ImageFormat`.

| See also |
|---|---|
| `https://developer.android.com/reference/android/media/Image.html#getFormat()` |   |
| `https://developer.android.com/reference/kotlin/androidx/camera/common/ImageFormat` |   |

### hardwareBuffer

Added in [1.7.0-rc02](https://developer.android.com/jetpack/androidx/releases/camera#1.7.0-rc02)

```
open val hardwareBuffer: HardwareBuffer?
```

The handle to the underlying image's hardware buffer, or `null` if this image does not support hardware buffers.

The `https://developer.android.com/reference/android/hardware/HardwareBuffer.html` follows the lifecycle of its associated `https://developer.android.com/reference/kotlin/androidx/camera/common/ImageWrapper`. It is not required to be closed explicitly; however, the `https://developer.android.com/reference/kotlin/androidx/camera/common/ImageWrapper` must not be closed while the hardware buffer is still in use.

| See also |
|---|---|
| `https://developer.android.com/reference/android/media/Image.html#getHardwareBuffer()` |   |

### height

Added in [1.7.0-rc02](https://developer.android.com/jetpack/androidx/releases/camera#1.7.0-rc02)

```
val height: Int
```

The height of the image in pixels.

| See also |
|---|---|
| `https://developer.android.com/reference/android/media/Image.html#getHeight()` |   |

### imagePlanes

Added in [1.7.0-rc02](https://developer.android.com/jetpack/androidx/releases/camera#1.7.0-rc02)

```
val imagePlanes: List<ImagePlane>
```

The list of pixel planes for this image.

The number of planes is determined by the format of the image. For example, YUV images usually have three planes (Y, U, V), while RGB or JPEG images typically have a single plane.

| See also |
|---|---|
| `https://developer.android.com/reference/android/media/Image.html#getPlanes()` |   |

### syncFence

Added in [1.7.0-rc02](https://developer.android.com/jetpack/androidx/releases/camera#1.7.0-rc02)

```
open val syncFence: SyncFence?
```

The sync fence associated with this image, or `null` if there is no fence.

The sync fence is used to coordinate access to the image data, ensuring that the producer has finished writing before the consumer starts reading, or vice versa.

| See also |
|---|---|
| `https://developer.android.com/reference/android/media/Image.html#getFence()` |   |

### timestamp

Added in [1.7.0-rc02](https://developer.android.com/jetpack/androidx/releases/camera#1.7.0-rc02)

```
val timestamp: Long
```

The timestamp associated with this image, in nanoseconds.

| See also |
|---|---|
| `https://developer.android.com/reference/android/media/Image.html#getTimestamp()` |   |

### width

Added in [1.7.0-rc02](https://developer.android.com/jetpack/androidx/releases/camera#1.7.0-rc02)

```
val width: Int
```

The width of the image in pixels.

| See also |
|---|---|
| `https://developer.android.com/reference/android/media/Image.html#getWidth()` |   |