BitmapPixelTestUtil

Artifact: androidx.media3:media3-test-utils

View Source

---

Kotlin |Java

@UnstableApi
class BitmapPixelTestUtil

---

Utilities for pixel tests.

Summary

Nested types
class BitmapPixelTestUtil.ImageBuffer Represents a ByteBuffer read from an Image.

Constants
const Float	MAXIMUM_AVERAGE_PIXEL_ABSOLUTE_DIFFERENCE Maximum allowed average pixel difference between bitmaps generated.
const Float	MAXIMUM_AVERAGE_PIXEL_ABSOLUTE_DIFFERENCE_DIFFERENT_DEVICE Maximum allowed average pixel difference between bitmaps generated using devices.
const Float	MAXIMUM_AVERAGE_PIXEL_ABSOLUTE_DIFFERENCE_DIFFERENT_DEVICE_FP16 = 0.01f Maximum allowed average pixel difference between bitmaps with 16-bit primaries generated using devices.
const Float	MAXIMUM_AVERAGE_PIXEL_ABSOLUTE_DIFFERENCE_LUMA = 8.0f Maximum allowed average pixel difference between bitmaps generated from luma values.

Public functions
java-static BitmapPixelTestUtil.ImageBuffer!	copyByteBufferFromRbga8888Image(image: Image!) Returns the ImageBuffer that is copied from the Image's internal buffer.
java-static Unit	copyRbga8888BitmapToImage(bitmap: Bitmap!, image: Image!) Copies image data from the specified Bitmap into the Image, which must be an RGBA_8888 image.
java-static Bitmap!	createArgb8888BitmapFromFocusedGlFramebuffer(width: Int, height: Int) Creates a ARGB_8888 bitmap with the values of the focused OpenGL framebuffer.
java-static Bitmap!	createArgb8888BitmapFromRgba8888Image(image: Image!) Returns a bitmap with the same information as the provided alpha/red/green/blue 8-bits per component image.
java-static Bitmap!	createArgb8888BitmapFromRgba8888ImageBuffer(     imageBuffer: BitmapPixelTestUtil.ImageBuffer! )
java-static Bitmap!	createArgb8888BitmapWithSolidColor(width: Int, height: Int, color: Int) Returns a solid Bitmap with every pixel having the same color.
java-static Bitmap!	@RequiresApi(value = 26) createFp16BitmapFromFocusedGlFramebuffer(width: Int, height: Int) Creates a RGBA_F16 bitmap with the values of the focused OpenGL framebuffer.
java-static Int	createGlTextureFromBitmap(bitmap: Bitmap!) Creates a 2-dimensional OpenGL texture with the bitmap's contents.
java-static Bitmap!	createGrayscaleBitmapFromYuv420888Image(     image: Image!,     bitmapConfig: Bitmap.Config! ) Returns a grayscale bitmap from the Luma channel in the YUV_420_888 image.
java-static Bitmap!	createUnpremultipliedArgb8888BitmapFromFocusedGlFramebuffer(     width: Int,     height: Int ) Creates a ARGB_8888 bitmap with the values of the focused OpenGL framebuffer.
java-static Bitmap!	flipBitmapVertically(bitmap: Bitmap!)
java-static Float	getBitmapAveragePixelAbsoluteDifferenceArgb8888(     expected: Bitmap!,     actual: Bitmap!,     testId: String? ) Returns the average difference between the expected and actual bitmaps, calculated using the maximum difference across all color channels for each pixel, then divided by the total number of pixels in the image, without saving the difference bitmap.
java-static Float	getBitmapAveragePixelAbsoluteDifferenceArgb8888(     expected: Bitmap!,     actual: Bitmap!,     testId: String?,     differencesBitmapPath: String? ) Returns the average difference between the expected and actual bitmaps.
java-static Float	@RequiresApi(value = 29) getBitmapAveragePixelAbsoluteDifferenceFp16(     expected: Bitmap!,     actual: Bitmap! ) Returns the average difference between the expected and actual bitmaps.
java-static Unit	maybeSaveTestBitmap(     testId: String!,     bitmapLabel: String!,     bitmap: Bitmap!,     path: String? ) Tries to save the Bitmap as a PNG to the <path>, and if not provided, tries to save to the cache directory.
java-static Bitmap!	readBitmap(assetString: String!) Reads a bitmap from the specified asset location.
java-static Bitmap!	readBitmapUnpremultipliedAlpha(assetString: String!) Reads a bitmap with unpremultiplied alpha from the specified asset location.

Constants

MAXIMUM_AVERAGE_PIXEL_ABSOLUTE_DIFFERENCE

const val MAXIMUM_AVERAGE_PIXEL_ABSOLUTE_DIFFERENCE: Float

Maximum allowed average pixel difference between bitmaps generated.

This value is for for 8-bit primaries in pixel difference-based tests.

The value is chosen so that differences in decoder behavior across devices don't affect whether the test passes, but substantial distortions introduced by changes in tested components will cause the test to fail.

When the difference is close to the threshold, manually inspect expected/actual bitmaps to confirm failure, as it's possible this is caused by a difference in the codec or graphics implementation as opposed to an issue in the tested component.

The value is the same as MAXIMUM_AVERAGE_PIXEL_ABSOLUTE_DIFFERENCE_DIFFERENT_DEVICE if running on physical devices.

MAXIMUM_AVERAGE_PIXEL_ABSOLUTE_DIFFERENCE_DIFFERENT_DEVICE

const val MAXIMUM_AVERAGE_PIXEL_ABSOLUTE_DIFFERENCE_DIFFERENT_DEVICE: Float

Maximum allowed average pixel difference between bitmaps generated using devices.

This value is for for 8-bit primaries in pixel difference-based tests.

The value is chosen so that differences in decoder behavior across devices don't affect whether the test passes, but substantial distortions introduced by changes in tested components will cause the test to fail.

When the difference is close to the threshold, manually inspect expected/actual bitmaps to confirm failure, as it's possible this is caused by a difference in the codec or graphics implementation as opposed to an issue in the tested component.

This value is larger than MAXIMUM_AVERAGE_PIXEL_ABSOLUTE_DIFFERENCE to support the larger variance in decoder outputs between different physical devices and emulators.

MAXIMUM_AVERAGE_PIXEL_ABSOLUTE_DIFFERENCE_DIFFERENT_DEVICE_FP16

const val MAXIMUM_AVERAGE_PIXEL_ABSOLUTE_DIFFERENCE_DIFFERENT_DEVICE_FP16 = 0.01f: Float

Maximum allowed average pixel difference between bitmaps with 16-bit primaries generated using devices.

The value is chosen so that differences in decoder behavior across devices in pixel difference-based tests don't affect whether the test passes, but substantial distortions introduced by changes in tested components will cause the test to fail.

When the difference is close to the threshold, manually inspect expected/actual bitmaps to confirm failure, as it's possible this is caused by a difference in the codec or graphics implementation as opposed to an issue in the tested component.

This value is larger than MAXIMUM_AVERAGE_PIXEL_ABSOLUTE_DIFFERENCE to support the larger variance in decoder outputs between different physical devices and emulators.

MAXIMUM_AVERAGE_PIXEL_ABSOLUTE_DIFFERENCE_LUMA

const val MAXIMUM_AVERAGE_PIXEL_ABSOLUTE_DIFFERENCE_LUMA = 8.0f: Float

Maximum allowed average pixel difference between bitmaps generated from luma values.

See also
MAXIMUM_AVERAGE_PIXEL_ABSOLUTE_DIFFERENCE

Public functions

copyByteBufferFromRbga8888Image

java-static fun copyByteBufferFromRbga8888Image(image: Image!): BitmapPixelTestUtil.ImageBuffer!

Returns the ImageBuffer that is copied from the Image's internal buffer.

copyRbga8888BitmapToImage

java-static fun copyRbga8888BitmapToImage(bitmap: Bitmap!, image: Image!): Unit

Copies image data from the specified Bitmap into the Image, which must be an RGBA_8888 image.

createArgb8888BitmapFromFocusedGlFramebuffer

java-static fun createArgb8888BitmapFromFocusedGlFramebuffer(width: Int, height: Int): Bitmap!

Creates a ARGB_8888 bitmap with the values of the focused OpenGL framebuffer.

This method may block until any previously called OpenGL commands are complete.

This method incorrectly marks the output Bitmap as premultiplied, even though OpenGL typically outputs only non-premultiplied alpha. Use createUnpremultipliedArgb8888BitmapFromFocusedGlFramebuffer to properly handle alpha.

Parameters
width: Int	The width of the pixel rectangle to read.
height: Int	The height of the pixel rectangle to read.

Returns
Bitmap!	A Bitmap with the framebuffer's values.

Throws
androidx.media3.common.util.GlUtil.GlException

createArgb8888BitmapFromRgba8888Image

java-static fun createArgb8888BitmapFromRgba8888Image(image: Image!): Bitmap!

Returns a bitmap with the same information as the provided alpha/red/green/blue 8-bits per component image.

createArgb8888BitmapFromRgba8888ImageBuffer

java-static fun createArgb8888BitmapFromRgba8888ImageBuffer(
    imageBuffer: BitmapPixelTestUtil.ImageBuffer!
): Bitmap!

createArgb8888BitmapWithSolidColor

java-static fun createArgb8888BitmapWithSolidColor(width: Int, height: Int, color: Int): Bitmap!

Returns a solid Bitmap with every pixel having the same color.

Parameters
width: Int	The width of image to create, in pixels.
height: Int	The height of image to create, in pixels.
color: Int	An RGBA color created by Color.

createFp16BitmapFromFocusedGlFramebuffer

@RequiresApi(value = 26)
java-static fun createFp16BitmapFromFocusedGlFramebuffer(width: Int, height: Int): Bitmap!

Creates a RGBA_F16 bitmap with the values of the focused OpenGL framebuffer.

This method may block until any previously called OpenGL commands are complete.

This method incorrectly marks the output Bitmap as premultiplied, even though OpenGL typically outputs only non-premultiplied alpha. Call setPremultiplied with false on the output bitmap to properly handle alpha.

Parameters
width: Int	The width of the pixel rectangle to read.
height: Int	The height of the pixel rectangle to read.

Returns
Bitmap!	A Bitmap with the framebuffer's values.

Throws
androidx.media3.common.util.GlUtil.GlException

createGlTextureFromBitmap

java-static fun createGlTextureFromBitmap(bitmap: Bitmap!): Int

Creates a 2-dimensional OpenGL texture with the bitmap's contents.

Parameters
bitmap: Bitmap!	A Bitmap.

Returns
Int	The identifier of the newly created texture.

Throws
androidx.media3.common.util.GlUtil.GlException

createGrayscaleBitmapFromYuv420888Image

java-static fun createGrayscaleBitmapFromYuv420888Image(
    image: Image!,
    bitmapConfig: Bitmap.Config!
): Bitmap!

Returns a grayscale bitmap from the Luma channel in the YUV_420_888 image.

createUnpremultipliedArgb8888BitmapFromFocusedGlFramebuffer

java-static fun createUnpremultipliedArgb8888BitmapFromFocusedGlFramebuffer(
    width: Int,
    height: Int
): Bitmap!

Creates a ARGB_8888 bitmap with the values of the focused OpenGL framebuffer.

This method may block until any previously called OpenGL commands are complete.

Parameters
width: Int	The width of the pixel rectangle to read.
height: Int	The height of the pixel rectangle to read.

Returns
Bitmap!	A Bitmap with the framebuffer's values.

Throws
androidx.media3.common.util.GlUtil.GlException

flipBitmapVertically

java-static fun flipBitmapVertically(bitmap: Bitmap!): Bitmap!

getBitmapAveragePixelAbsoluteDifferenceArgb8888

java-static fun getBitmapAveragePixelAbsoluteDifferenceArgb8888(
    expected: Bitmap!,
    actual: Bitmap!,
    testId: String?
): Float

Returns the average difference between the expected and actual bitmaps, calculated using the maximum difference across all color channels for each pixel, then divided by the total number of pixels in the image, without saving the difference bitmap. See getBitmapAveragePixelAbsoluteDifferenceArgb8888.

This method is the overloaded version of getBitmapAveragePixelAbsoluteDifferenceArgb8888 without a specified saved path.

getBitmapAveragePixelAbsoluteDifferenceArgb8888

java-static fun getBitmapAveragePixelAbsoluteDifferenceArgb8888(
    expected: Bitmap!,
    actual: Bitmap!,
    testId: String?,
    differencesBitmapPath: String?
): Float

Returns the average difference between the expected and actual bitmaps.

Calculated using the maximum difference across all color channels for each pixel, then divided by the total number of pixels in the image. Bitmap resolutions must match and must use configuration ARGB_8888.

Tries to save a difference bitmap between expected and actual bitmaps.

Parameters
expected: Bitmap!	The expected Bitmap.
actual: Bitmap!	The actual Bitmap produced by the test.
testId: String?	The name of the test that produced the Bitmap, or null if the differences bitmap should not be saved to cache.
differencesBitmapPath: String?	Folder path for the produced pixel-wise difference Bitmap to be saved in or null if the assumed default save path should be used.

Returns
Float	The average of the maximum absolute pixel-wise differences between the expected and actual bitmaps.

getBitmapAveragePixelAbsoluteDifferenceFp16

@RequiresApi(value = 29)
java-static fun getBitmapAveragePixelAbsoluteDifferenceFp16(
    expected: Bitmap!,
    actual: Bitmap!
): Float

Returns the average difference between the expected and actual bitmaps.

Calculated using the maximum difference across all color channels for each pixel, then divided by the total number of pixels in the image. Bitmap resolutions must match and must use configuration RGBA_F16.

Parameters
expected: Bitmap!	The expected Bitmap.
actual: Bitmap!	The actual Bitmap produced by the test.

Returns
Float	The average of the maximum absolute pixel-wise differences between the expected and actual bitmaps.

maybeSaveTestBitmap

java-static fun maybeSaveTestBitmap(
    testId: String!,
    bitmapLabel: String!,
    bitmap: Bitmap!,
    path: String?
): Unit

Tries to save the Bitmap as a PNG to the <path>, and if not provided, tries to save to the cache directory.

File name will be <testId>_<bitmapLabel>.png. If the file failed to write, any IOException will be caught and logged. The path will be logged regardless of success.

Parameters
testId: String!	Name of the test that produced the Bitmap.
bitmapLabel: String!	Label to identify the bitmap.
bitmap: Bitmap!	The Bitmap to save.
path: String?	Folder path for the supplied Bitmap to be saved in or null if the cache directory should be saved in.

readBitmap

java-static fun readBitmap(assetString: String!): Bitmap!

Reads a bitmap from the specified asset location.

Parameters
assetString: String!	Relative path to the asset within the assets directory.

Returns
Bitmap!	A Bitmap.

Throws
java.io.IOException	If the bitmap can't be read.

readBitmapUnpremultipliedAlpha

java-static fun readBitmapUnpremultipliedAlpha(assetString: String!): Bitmap!

Reads a bitmap with unpremultiplied alpha from the specified asset location.

Parameters
assetString: String!	Relative path to the asset within the assets directory.

Returns
Bitmap!	A Bitmap.

Throws
java.io.IOException	If the bitmap can't be read.