Overview

A container for pixel data.

#include <Ultralight/CAPI/CAPI_Bitmap.h>

The bitmap class is used to store pixel data in a variety of formats. It intelligently manages the lifetime of the pixel buffer and serializes access to it while the bitmap owns the pixels.

Thread Safety

ulBitmapLockPixels() and ulBitmapUnlockPixels() take the bitmap's internal lock only when the bitmap owns its pixel buffer, ie. one created by a creation function that allocates, or one that copied the pixels you passed in. A bitmap that wraps memory you still own– created with should_copy = false– does no locking at all, so you must serialize access to that buffer yourself.

Accessing Pixel Data

To access the pixel data, you must first lock the pixels using ulBitmapLockPixels(). This will return a pointer to the pixel buffer. An example follows:

void* pixels = ulBitmapLockPixels(bitmap);
if (pixels) {
  // Zero out the pixel buffer
  memset(pixels, 0, ulBitmapGetSize(bitmap));
}
 
// Unlock the pixels when you're done.
ulBitmapUnlockPixels(bitmap);

Classes
struct	ULBitmapFormatInfo
	Block geometry of a pixel format. More...

Functions
ULBitmapFormatInfo	ulGetBitmapFormatInfo (ULBitmapFormat format)
	Get the block geometry for a given pixel format.
bool	ulIsCompressedFormat (ULBitmapFormat format)
	Whether or not a given pixel format is block-compressed (a BCn format).
ULBitmap	ulCreateEmptyBitmap (void)
	Create an empty bitmap.
ULBitmap	ulCreateBitmap (unsigned int width, unsigned int height, ULBitmapFormat format)
	Create bitmap with certain dimensions and pixel format.
ULBitmap	ulCreateBitmapAligned (unsigned int width, unsigned int height, ULBitmapFormat format, unsigned int alignment)
	Create bitmap with certain dimensions, pixel format, and row byte alignment.
ULBitmap	ulCreateBitmapFromPixels (unsigned int width, unsigned int height, ULBitmapFormat format, unsigned int row_bytes, const void *pixels, size_t size, bool should_copy)
	Create a bitmap from an existing pixel buffer.
ULBitmap	ulCreateBitmapFromCopy (ULBitmap existing_bitmap)
	Create a bitmap from a deep copy of another bitmap.
void	ulDestroyBitmap (ULBitmap bitmap)
	Destroy a bitmap.
unsigned int	ulBitmapGetWidth (ULBitmap bitmap)
	Get the width in pixels.
unsigned int	ulBitmapGetHeight (ULBitmap bitmap)
	Get the height in pixels.
ULIntRect	ulBitmapGetBounds (ULBitmap bitmap)
	Get the bounds as a ULIntRect.
ULBitmapFormat	ulBitmapGetFormat (ULBitmap bitmap)
	Get the pixel format.
unsigned int	ulBitmapGetBpp (ULBitmap bitmap)
	Get the bytes per pixel.
unsigned int	ulBitmapGetRowBytes (ULBitmap bitmap)
	Get the number of bytes per row.
size_t	ulBitmapGetSize (ULBitmap bitmap)
	Get the size in bytes of the underlying pixel buffer.
bool	ulBitmapOwnsPixels (ULBitmap bitmap)
	Whether or not this bitmap owns its own pixel buffer.
bool	ulBitmapIsCompressed (ULBitmap bitmap)
	Whether or not this bitmap uses a block-compressed (BCn) format.
unsigned int	ulBitmapMaxDimension (void)
	Get the maximum supported width or height, in pixels.
void *	ulBitmapLockPixels (ULBitmap bitmap)
	Lock the pixel buffer for reading/writing.
void	ulBitmapUnlockPixels (ULBitmap bitmap)
	Unlock pixels after locking.
void *	ulBitmapRawPixels (ULBitmap bitmap)
	Get the raw pixel buffer.
bool	ulBitmapIsEmpty (ULBitmap bitmap)
	Whether or not this bitmap is empty.
void	ulBitmapErase (ULBitmap bitmap)
	Reset bitmap pixels to 0.
void	ulBitmapSet (ULBitmap bitmap, ULBitmap source)
	Assign another bitmap to this one.
bool	ulBitmapDrawBitmap (ULBitmap bitmap, ULIntRect src_rect, ULIntRect dest_rect, ULBitmap src, bool pad_repeat)
	Draw another bitmap to this bitmap.
bool	ulBitmapWritePNG (ULBitmap bitmap, const char *path)
	Write bitmap to a PNG on disk.
bool	ulBitmapWritePNGEx (ULBitmap bitmap, const char *path, bool convert_to_rgba, bool convert_to_straight_alpha)
	Write bitmap to a PNG on disk with explicit conversion control.
ULBuffer	ulBitmapEncodePNG (ULBitmap bitmap)
	Encode this bitmap as a PNG image and return the encoded bytes in a buffer.
ULBuffer	ulBitmapEncodePNGEx (ULBitmap bitmap, bool convert_to_rgba, bool convert_to_straight_alpha)
	Encode this bitmap as a PNG image with explicit conversion control and return the encoded bytes in a buffer.
bool	ulBitmapResample (ULBitmap bitmap, ULBitmap destination, bool high_quality)
	Make a resized copy of this bitmap by writing to a pre-allocated destination bitmap.
void	ulBitmapConvertToStraightAlpha (ULBitmap bitmap)
	Convert a BGRA bitmap from premultiplied alpha to straight alpha.
void	ulBitmapConvertToPremultipliedAlpha (ULBitmap bitmap)
	Convert a BGRA bitmap from straight alpha to premultiplied alpha.
void	ulBitmapSwapRedBlueChannels (ULBitmap bitmap)
	This converts a BGRA bitmap to RGBA bitmap and vice-versa by swapping the red and blue channels.

Function Documentation

◆ ulBitmapConvertToPremultipliedAlpha()

void ulBitmapConvertToPremultipliedAlpha ( ULBitmap bitmap )

Convert a BGRA bitmap from straight alpha to premultiplied alpha.

Note: Only valid if the bitmap format is kBitmapFormat_BGRA8_UNORM_SRGB.

◆ ulBitmapConvertToStraightAlpha()

void ulBitmapConvertToStraightAlpha ( ULBitmap bitmap )

Convert a BGRA bitmap from premultiplied alpha to straight alpha.

Note: Only valid if the bitmap format is kBitmapFormat_BGRA8_UNORM_SRGB.

◆ ulBitmapDrawBitmap()

bool ulBitmapDrawBitmap	(	ULBitmap	bitmap,
		ULIntRect	src_rect,
		ULIntRect	dest_rect,
		ULBitmap	src,
		bool	pad_repeat )

Draw another bitmap to this bitmap.

Note: Formats do not need to match. Bitmap formats will be converted to one another automatically.

Parameters

bitmap	The destination bitmap.
src_rect	The source rectangle, relative to the source bitmap.
dest_rect	The destination rectangle, relative to this bitmap.
src	The source bitmap to draw.
pad_repeat	Whether or not to pad the drawn bitmap by one pixel of repeated edge pixels.

Returns: Returns whether or not the operation succeeded (this can fail if the src_rect and/or dest_rect are invalid).

◆ ulBitmapEncodePNG()

ULBuffer ulBitmapEncodePNG ( ULBitmap bitmap )

Encode this bitmap as a PNG image and return the encoded bytes in a buffer.

Parameters

bitmap The bitmap to encode.

Returns: Returns a buffer containing the PNG-encoded bytes, or NULL on failure. You must call ulDestroyBuffer() on the returned buffer when finished.

Note: This automatically converts BGRA to RGBA and premultiplied alpha to straight alpha. Use ulBitmapEncodePNGEx() if you need to control these conversions.

◆ ulBitmapEncodePNGEx()

ULBuffer ulBitmapEncodePNGEx	(	ULBitmap	bitmap,
		bool	convert_to_rgba,
		bool	convert_to_straight_alpha )

Encode this bitmap as a PNG image with explicit conversion control and return the encoded bytes in a buffer.

Parameters

bitmap	The bitmap to encode.
convert_to_rgba	The PNG format expects RGBA format but the bitmap is stored as BGRA, set this to true to perform the conversion automatically.
convert_to_straight_alpha	The PNG format expects semi-transparent values to be stored as straight alpha instead of premultiplied alpha, set this to true to perform the conversion automatically.

Returns: Returns a buffer containing the PNG-encoded bytes, or NULL on failure. You must call ulDestroyBuffer() on the returned buffer when finished.

◆ ulBitmapErase()

void ulBitmapErase ( ULBitmap bitmap )

Reset bitmap pixels to 0.

◆ ulBitmapGetBounds()

ULIntRect ulBitmapGetBounds ( ULBitmap bitmap )

Get the bounds as a ULIntRect.

◆ ulBitmapGetBpp()

unsigned int ulBitmapGetBpp ( ULBitmap bitmap )

Get the bytes per pixel.

◆ ulBitmapGetFormat()

ULBitmapFormat ulBitmapGetFormat ( ULBitmap bitmap )

Get the pixel format.

◆ ulBitmapGetHeight()

unsigned int ulBitmapGetHeight ( ULBitmap bitmap )

Get the height in pixels.

◆ ulBitmapGetRowBytes()

unsigned int ulBitmapGetRowBytes ( ULBitmap bitmap )

Get the number of bytes per row.

◆ ulBitmapGetSize()

size_t ulBitmapGetSize ( ULBitmap bitmap )

Get the size in bytes of the underlying pixel buffer.

◆ ulBitmapGetWidth()

unsigned int ulBitmapGetWidth ( ULBitmap bitmap )

Get the width in pixels.

◆ ulBitmapIsCompressed()

bool ulBitmapIsCompressed ( ULBitmap bitmap )

Whether or not this bitmap uses a block-compressed (BCn) format.

Note: Compressed bitmaps store 4x4 pixel blocks and don't support per-pixel operations. ulBitmapErase(), ulBitmapDrawBitmap(), ulBitmapResample(), and the channel/alpha conversions are no-ops or fail on a compressed bitmap.

◆ ulBitmapIsEmpty()

bool ulBitmapIsEmpty ( ULBitmap bitmap )

Whether or not this bitmap is empty.

◆ ulBitmapLockPixels()

void * ulBitmapLockPixels ( ULBitmap bitmap )

Lock the pixel buffer for reading/writing.

Returns: Returns a pointer to the pixel buffer.

◆ ulBitmapMaxDimension()

unsigned int ulBitmapMaxDimension ( void )

Get the maximum supported width or height, in pixels.

The bitmap creation functions return NULL if either dimension exceeds this limit.

◆ ulBitmapOwnsPixels()

bool ulBitmapOwnsPixels ( ULBitmap bitmap )

Whether or not this bitmap owns its own pixel buffer.

◆ ulBitmapRawPixels()

void * ulBitmapRawPixels ( ULBitmap bitmap )

Get the raw pixel buffer.

Note: You should only call this if the pixels are already locked.

◆ ulBitmapResample()

bool ulBitmapResample	(	ULBitmap	bitmap,
		ULBitmap	destination,
		bool	high_quality )

Make a resized copy of this bitmap by writing to a pre-allocated destination bitmap.

Parameters

bitmap	The source bitmap.
destination	The destination bitmap, its width and height determine the output size.
high_quality	Whether or not a high quality resampling will be used during the resize. (Otherwise, just uses fast nearest-neighbor sampling)

Returns: Returns whether or not the operation succeeded. This operation is only valid if both formats are kBitmapFormat_BGRA8_UNORM_SRGB and the source and destination are non-empty.

◆ ulBitmapSet()

void ulBitmapSet	(	ULBitmap	bitmap,
		ULBitmap	source )

Assign another bitmap to this one.

Parameters

bitmap	The destination bitmap.
source	The source bitmap to copy from.

Note: The source pixels are deep-copied in every case but one: a source that wraps memory you still own (created with should_copy = false) is aliased instead, so that buffer must outlive the destination bitmap.

◆ ulBitmapSwapRedBlueChannels()

void ulBitmapSwapRedBlueChannels ( ULBitmap bitmap )

This converts a BGRA bitmap to RGBA bitmap and vice-versa by swapping the red and blue channels.

◆ ulBitmapUnlockPixels()

void ulBitmapUnlockPixels ( ULBitmap bitmap )

Unlock pixels after locking.

◆ ulBitmapWritePNG()

bool ulBitmapWritePNG	(	ULBitmap	bitmap,
		const char *	path )

Write bitmap to a PNG on disk.

Parameters

bitmap	The bitmap to write.
path	The file path to write to.

Returns: Returns whether or not the operation succeeded.

Note: This automatically converts BGRA to RGBA and premultiplied alpha to straight alpha. Use ulBitmapWritePNGEx() if you need to control these conversions.

◆ ulBitmapWritePNGEx()

bool ulBitmapWritePNGEx	(	ULBitmap	bitmap,
		const char *	path,
		bool	convert_to_rgba,
		bool	convert_to_straight_alpha )

Write bitmap to a PNG on disk with explicit conversion control.

Parameters

bitmap	The bitmap to write.
path	The file path to write to.
convert_to_rgba	The PNG format expects RGBA format but the bitmap is stored as BGRA, set this to true to perform the conversion automatically.
convert_to_straight_alpha	The PNG format expects semi-transparent values to be stored as straight alpha instead of premultiplied alpha, set this to true to perform the conversion automatically.

Returns: Returns whether or not the operation succeeded.

◆ ulCreateBitmap()

ULBitmap ulCreateBitmap	(	unsigned int	width,
		unsigned int	height,
		ULBitmapFormat	format )

Create bitmap with certain dimensions and pixel format.

Pixels will be allocated but not initialized.

Parameters

width	The width in pixels.
height	The height in pixels.
format	The pixel format to use.

Returns: Returns a new bitmap instance. You must call ulDestroyBitmap() when finished.

◆ ulCreateBitmapAligned()

ULBitmap ulCreateBitmapAligned	(	unsigned int	width,
		unsigned int	height,
		ULBitmapFormat	format,
		unsigned int	alignment )

Create bitmap with certain dimensions, pixel format, and row byte alignment.

Parameters

width	The width in pixels.
height	The height in pixels.
format	The pixel format to use.
alignment	The alignment in bytes. Row bytes will be padded to a multiple of this value.

Returns: Returns a new bitmap instance. You must call ulDestroyBitmap() when finished.

◆ ulCreateBitmapFromCopy()

ULBitmap ulCreateBitmapFromCopy ( ULBitmap existing_bitmap )

Create a bitmap from a deep copy of another bitmap.

Parameters

existing_bitmap The bitmap to copy from.

Returns: Returns a new bitmap instance. You must call ulDestroyBitmap() when finished.

◆ ulCreateBitmapFromPixels()

ULBitmap ulCreateBitmapFromPixels	(	unsigned int	width,
		unsigned int	height,
		ULBitmapFormat	format,
		unsigned int	row_bytes,
		const void *	pixels,
		size_t	size,
		bool	should_copy )

Create a bitmap from an existing pixel buffer.

Parameters

width	The width in pixels.
height	The height in pixels.
format	The pixel format to use.
row_bytes	The number of bytes between each row of pixels. This should be at least width * bytes_per_pixel, or for a block-compressed format, the width in 4x4 blocks times the block size (see ulGetBitmapFormatInfo()).
pixels	Pointer to the raw pixel buffer.
size	Size of the raw pixel buffer in bytes.
should_copy	Whether or not a copy should be made of the pixels. If this is false, the returned bitmap will reference the raw pixels directly and you must keep the buffer alive until the bitmap is destroyed.

Returns: Returns a new bitmap instance. You must call ulDestroyBitmap() when finished.

◆ ulCreateEmptyBitmap()

ULBitmap ulCreateEmptyBitmap ( void )

Create an empty bitmap.

No pixels will be allocated.

Returns: Returns a new bitmap instance. You must call ulDestroyBitmap() when finished.

◆ ulDestroyBitmap()

void ulDestroyBitmap ( ULBitmap bitmap )

Destroy a bitmap.

You should only destroy bitmaps you have explicitly created via one of the creation functions above.

Parameters

bitmap The bitmap to destroy.

◆ ulGetBitmapFormatInfo()

ULBitmapFormatInfo ulGetBitmapFormatInfo ( ULBitmapFormat format )

Get the block geometry for a given pixel format.

Parameters

format The pixel format to query.

Returns: Returns the block width, block height, and block size in bytes for the format.

◆ ulIsCompressedFormat()

bool ulIsCompressedFormat ( ULBitmapFormat format )

Whether or not a given pixel format is block-compressed (a BCn format).

Parameters

format The pixel format to query.

Returns: Returns true for kBitmapFormat_BC1_UNORM, kBitmapFormat_BC2_UNORM, kBitmapFormat_BC3_UNORM, and kBitmapFormat_BC7_UNORM.

Go to the source code of this file.

Overview

Thread Safety

Accessing Pixel Data

Classes

Functions

Function Documentation

◆ ulBitmapConvertToPremultipliedAlpha()

◆ ulBitmapConvertToStraightAlpha()

◆ ulBitmapDrawBitmap()

◆ ulBitmapEncodePNG()

◆ ulBitmapEncodePNGEx()

◆ ulBitmapErase()

◆ ulBitmapGetBounds()

◆ ulBitmapGetBpp()

◆ ulBitmapGetFormat()

◆ ulBitmapGetHeight()

◆ ulBitmapGetRowBytes()

◆ ulBitmapGetSize()

◆ ulBitmapGetWidth()

◆ ulBitmapIsCompressed()

◆ ulBitmapIsEmpty()

◆ ulBitmapLockPixels()

◆ ulBitmapMaxDimension()

◆ ulBitmapOwnsPixels()

◆ ulBitmapRawPixels()

◆ ulBitmapResample()

◆ ulBitmapSet()

◆ ulBitmapSwapRedBlueChannels()

◆ ulBitmapUnlockPixels()

◆ ulBitmapWritePNG()

◆ ulBitmapWritePNGEx()

◆ ulCreateBitmap()

◆ ulCreateBitmapAligned()

◆ ulCreateBitmapFromCopy()

◆ ulCreateBitmapFromPixels()

◆ ulCreateEmptyBitmap()

◆ ulDestroyBitmap()

◆ ulGetBitmapFormatInfo()

◆ ulIsCompressedFormat()