{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}

ImageBitmap

public interface ImageBitmap


Graphics object that represents a 2 dimensional array of pixel information represented as ARGB values

Summary

Nested types

public static class ImageBitmap.Companion

Provide an empty companion object to hang platform-specific companion extensions onto.

Public methods

abstract @NonNull ColorSpace

ColorSpace the Image renders in

abstract @NonNull ImageBitmapConfig

Returns the current configuration of this Image, either:

abstract boolean

Determines whether or not the ImageBitmap contains an alpha channel

abstract int

The number of image pixels along the ImageBitmap's vertical axis.

abstract int

The number of image pixels along the ImageBitmap's horizontal axis.

abstract void

Builds caches associated with the ImageBitmap that are used for drawing it.

abstract void
readPixels(
    @NonNull int[] buffer,
    int startX,
    int startY,
    int width,
    int height,
    int bufferOffset,
    int stride
)

Copies the pixel data within the ImageBitmap into the given array.

Extension functions

default final @NonNull Bitmap
default final @NonNull PixelMap
ImageBitmapKt.toPixelMap(
    @NonNull ImageBitmap receiver,
    int startX,
    int startY,
    int width,
    int height,
    @NonNull int[] buffer,
    int bufferOffset,
    int stride
)

Convenience method to extract pixel information from the given ImageBitmap into a PixelMap that supports for querying pixel information based on

Public methods

getColorSpace

abstract @NonNull ColorSpace getColorSpace()

ColorSpace the Image renders in

getConfig

abstract @NonNull ImageBitmapConfig getConfig()

Returns the current configuration of this Image, either:

getHasAlpha

abstract boolean getHasAlpha()

Determines whether or not the ImageBitmap contains an alpha channel

getHeight

abstract int getHeight()

The number of image pixels along the ImageBitmap's vertical axis.

getWidth

abstract int getWidth()

The number of image pixels along the ImageBitmap's horizontal axis.

prepareToDraw

abstract void prepareToDraw()

Builds caches associated with the ImageBitmap that are used for drawing it. This method can be used as a signal to upload textures to the GPU to eventually be rendered

readPixels

abstract void readPixels(
    @NonNull int[] buffer,
    int startX,
    int startY,
    int width,
    int height,
    int bufferOffset,
    int stride
)

Copies the pixel data within the ImageBitmap into the given array. Each value is represented as ARGB values packed into an Int. The stride parameter allows the caller to allow for gaps in the returned pixels array between rows. For normal packed, results, the stride value is equivalent to the width of the ImageBitmap. The returned colors are non-premultiplied ARGB values in the ColorSpaces.Srgb color space.

Note this method can block so it is recommended to not invoke this method in performance critical code paths

import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.ImageBitmap
import androidx.compose.ui.graphics.PixelMap

val imageBitmap = createImageBitmap()

val buffer = IntArray(20 * 10)
imageBitmap.readPixels(
    buffer = buffer,
    startX = 8,
    startY = 9,
    width = 20,
    height = 10
)

val pixelmap = PixelMap(
    buffer = buffer,
    width = 20,
    height = 10,
    stride = 20,
    bufferOffset = 0
)

// create a histogram to count the number of occurrences of a color within the specified
// subsection of the provided ImageBitmap
val histogram = HashMap<Color, Int>()
for (x in 0 until pixelmap.width) {
    for (y in 0 until pixelmap.height) {
        val color = pixelmap[x, y]
        val colorCount = histogram[color] ?: 0
        histogram[color] = (colorCount + 1)
    }
}
Parameters
@NonNull int[] buffer

The array to store the ImageBitmap's colors. By default this allocates an IntArray large enough to store all the pixel information. Consumers of this API are advised to use the smallest IntArray necessary to extract relevant pixel information, that is the 2 dimensional area of the section of the ImageBitmap to be queried.

int startX

The x-coordinate of the first pixel to read from the ImageBitmap

int startY

The y-coordinate of the first pixel to read from the ImageBitmap

int width

The number of pixels to read from each row

int height

The number of rows to read

int bufferOffset

The first index to write into the buffer array, this defaults to 0

int stride

The number of entries in buffer to skip between rows (must be >= width

Extension functions

AndroidImageBitmapKt.asAndroidBitmap

default final @NonNull Bitmap AndroidImageBitmapKt.asAndroidBitmap(@NonNull ImageBitmap receiver)
Throws
kotlin.UnsupportedOperationException

if this ImageBitmap is not backed by an android.graphics.Bitmap

ImageBitmapKt.toPixelMap

default final @NonNull PixelMap ImageBitmapKt.toPixelMap(
    @NonNull ImageBitmap receiver,
    int startX,
    int startY,
    int width,
    int height,
    @NonNull int[] buffer,
    int bufferOffset,
    int stride
)

Convenience method to extract pixel information from the given ImageBitmap into a PixelMap that supports for querying pixel information based on

Note this method can block so it is recommended to not invoke this method in performance critical code paths

import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.ImageBitmap
import androidx.compose.ui.graphics.PixelMap
import androidx.compose.ui.graphics.toPixelMap

val imageBitmap = createImageBitmap()

// Sample a 3 by 2 subsection of the given ImageBitmap
// starting at the coordinate (48, 49)
val pixelmap = imageBitmap.toPixelMap(
    startX = 48,
    startY = 49,
    width = 3,
    height = 2
)

// create a histogram to count the number of occurrences of a color within the specified
// subsection of the provided ImageBitmap
val histogram = HashMap<Color, Int>()
for (x in 0 until pixelmap.width) {
    for (y in 0 until pixelmap.height) {
        val color = pixelmap[x, y]
        val colorCount = histogram[color] ?: 0
        histogram[color] = (colorCount + 1)
    }
}
Parameters
int startX

The x-coordinate of the first pixel to read from the ImageBitmap

int startY

The y-coordinate of the first pixel to read from the ImageBitmap

int width

The number of pixels to read from each row

int height

The number of rows to read

@NonNull int[] buffer

The array to store the ImageBitmap's colors. By default this allocates an IntArray large enough to store all the pixel information. Consumers of this API are advised to use the smallest IntArray necessary to extract relevant pixel information

int bufferOffset

The first index to write into the buffer array, this defaults to 0

int stride

The number of entries in buffer to skip between rows (must be >= width

See also
readPixels