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

*** ** * ** ***


```
public interface ImageWrapper extends UnsafeWrapper, AutoCloseable
```

<br />

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

|---|---|
| `https://developer.android.com/reference/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/androidx/camera/common/MutableImageWrapper` | A mutable extension of `https://developer.android.com/reference/androidx/camera/common/ImageWrapper` that allows modifying properties of the image. |

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

|---|---|
| `https://developer.android.com/reference/androidx/camera/common/testing/FakeImage` | Fake implementation of `https://developer.android.com/reference/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 methods |
|---|---|
| `abstract void` | `https://developer.android.com/reference/androidx/camera/common/ImageWrapper#close()()` Closes the underlying image and releases any associated resources. |
| `abstract @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/graphics/Rect.html` | `https://developer.android.com/reference/androidx/camera/common/ImageWrapper#getCropRect()()` The crop rectangle of the image. |
| `default int` | `https://developer.android.com/reference/androidx/camera/common/ImageWrapper#getDataSpace()()` The dataspace associated with this image. |
| `abstract int` | `https://developer.android.com/reference/androidx/camera/common/ImageWrapper#getFormat()()` The format of the image. |
| `default https://developer.android.com/reference/android/hardware/HardwareBuffer.html` | `https://developer.android.com/reference/androidx/camera/common/ImageWrapper#getHardwareBuffer()()` The handle to the underlying image's hardware buffer, or `null` if this image does not support hardware buffers. |
| `abstract int` | `https://developer.android.com/reference/androidx/camera/common/ImageWrapper#getHeight()()` The height of the image in pixels. |
| `abstract @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/camera/common/ImagePlane>` | `https://developer.android.com/reference/androidx/camera/common/ImageWrapper#getImagePlanes()()` The list of pixel planes for this image. |
| `default https://developer.android.com/reference/android/hardware/SyncFence.html` | `https://developer.android.com/reference/androidx/camera/common/ImageWrapper#getSyncFence()()` The sync fence associated with this image, or `null` if there is no fence. |
| `abstract long` | `https://developer.android.com/reference/androidx/camera/common/ImageWrapper#getTimestamp()()` The timestamp associated with this image, in nanoseconds. |
| `abstract int` | `https://developer.android.com/reference/androidx/camera/common/ImageWrapper#getWidth()()` The width of the image in pixels. |

### Inherited methods

From [androidx.camera.common.UnsafeWrapper](https://developer.android.com/reference/androidx/camera/common/UnsafeWrapper) `abstract T` `<T extends https://developer.android.com/reference/java/lang/Object.html> https://developer.android.com/reference/androidx/camera/common/UnsafeWrapper#unwrapAs(java.lang.Class)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Class.html<@https://developer.android.com/reference/androidx/annotation/NonNull T> type)`

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

## Public methods

### close

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

```
abstract void close()
```

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.

### getCropRect

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

```
abstract @NonNull Rect getCropRect()
```

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()` |   |

### getDataSpace

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

```
default int getDataSpace()
```

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/androidx/camera/common/ImageDataSpace`.

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

### getFormat

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

```
abstract int getFormat()
```

The format of the image.

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

Value is one of the following:

- `0`
- `4`
- `842094169`
- `538982489`
- `16`
- `17`
- `20`
- `256`
- `1768253795`
- `35`
- `39`
- `40`
- `41`
- `42`
- `32`
- `36`
- `37`
- `38`
- `1144402265`
- `257`
- `34`
- `1212500294`
- `54`
- `4101`
- `4098`
- `4099`
- `540422489`
- `60`
- `4102`
- `56`
- `55`
- `57`
- `58`
- `59`
- `-3`
- `-2`
- `-1`
- `1`
- `2`
- `3`
- `22`
- `43`
- `33`
- `48`
- `49`
- `50`
- `51`
- `52`
- `53`

<br />

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

### getHardwareBuffer

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

```
default HardwareBuffer getHardwareBuffer()
```

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/androidx/camera/common/ImageWrapper`. It is not required to be closed explicitly; however, the `https://developer.android.com/reference/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()` |   |

### getHeight

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

```
abstract int getHeight()
```

The height of the image in pixels.

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

### getImagePlanes

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

```
abstract @NonNull List<@NonNull ImagePlane> getImagePlanes()
```

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()` |   |

### getSyncFence

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

```
default SyncFence getSyncFence()
```

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()` |   |

### getTimestamp

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

```
abstract long getTimestamp()
```

The timestamp associated with this image, in nanoseconds.

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

### getWidth

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

```
abstract int getWidth()
```

The width of the image in pixels.

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