ImageWrapper

Kotlin |Java

interface ImageWrapper : UnsafeWrapper, AutoCloseable

Known direct subclasses

ImageProxy, MutableImageWrapper

`ImageProxy`	An image proxy which has a similar interface as `android.media.Image`.
`MutableImageWrapper`	A mutable extension of `ImageWrapper` that allows modifying properties of the image.

Known indirect subclasses

FakeImage

FakeImage

Fake implementation of MutableImageWrapper for testing.

A wrapper interface that mirrors the primary read-only properties of Image.

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

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

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
`Unit`	`close()` Closes the underlying image and releases any associated resources.

Public properties
`Rect`	`cropRect` The crop rectangle of the image.
`open Int`	`dataSpace` The dataspace associated with this image.
`Int`	`format` The format of the image.
`open HardwareBuffer?`	`hardwareBuffer` The handle to the underlying image's hardware buffer, or `null` if this image does not support hardware buffers.
`Int`	`height` The height of the image in pixels.
`List<ImagePlane>`	`imagePlanes` The list of pixel planes for this image.
`open SyncFence?`	`syncFence` The sync fence associated with this image, or `null` if there is no fence.
`Long`	`timestamp` The timestamp associated with this image, in nanoseconds.
`Int`	`width` The width of the image in pixels.

Inherited functions

From androidx.camera.common.UnsafeWrapper

`T?`	`<T : Any> unwrapAs(type: Class<T>)` Attempts to unwrap this object into the specified underlying `type`.

Public functions

close

Added in 1.7.0-rc01

fun close(): Unit

Closes the underlying image and releases any associated resources.

Overridden to remove the checked Exception from the throws clause for Java callers.

Public properties

cropRect

Added in 1.7.0-rc01

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
`getCropRect`

dataSpace

Added in 1.7.0-rc01

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 ImageDataSpace.

See also
`getDataSpace`
`ImageDataSpace`

format

Added in 1.7.0-rc01

val format: Int

The format of the image.

The value returned is one of the constants defined in ImageFormat.

See also
`getFormat`
`ImageFormat`

hardwareBuffer

Added in 1.7.0-rc01

open val hardwareBuffer: HardwareBuffer?

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

The HardwareBuffer follows the lifecycle of its associated ImageWrapper. It is not required to be closed explicitly; however, the ImageWrapper must not be closed while the hardware buffer is still in use.

See also
`getHardwareBuffer`

height

Added in 1.7.0-rc01

val height: Int

The height of the image in pixels.

See also
`getHeight`

imagePlanes

Added in 1.7.0-rc01

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
`getPlanes`

syncFence

Added in 1.7.0-rc01

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
`getFence`

timestamp

Added in 1.7.0-rc01

val timestamp: Long

The timestamp associated with this image, in nanoseconds.

See also
`getTimestamp`

width

Added in 1.7.0-rc01

val width: Int

The width of the image in pixels.

See also
`getWidth`