#include <Ultralight/Bitmap.h>

Overview

A container for pixel data.

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

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

Accessing Pixel Data

You can access the underlying pixel data by using the LockPixelsSafe() method. An example follows:

auto bitmap = Bitmap::Create(100, 100, BitmapFormat::BGRA8_UNORM_SRGB);
auto pixels = bitmap->LockPixelsSafe();
if (pixels && pixels.data()) {
  // Zero out the pixel buffer by setting every byte to 0.
  memset(pixels.data(), 0, pixels.size());
}
 
// 'pixels' is automatically unlocked when it goes out of scope.

Inheritance diagram for Bitmap:

Static Public Member Functions
static RefPtr< Bitmap >	Create ()
	Create an empty Bitmap.
static RefPtr< Bitmap >	Create (uint32_t width, uint32_t height, BitmapFormat format)
	Create a Bitmap with a certain configuration.
static RefPtr< Bitmap >	Create (uint32_t width, uint32_t height, BitmapFormat format, uint32_t alignment)
	Create an aligned Bitmap with a certain configuration.
static RefPtr< Bitmap >	Create (uint32_t width, uint32_t height, BitmapFormat format, uint32_t row_bytes, const void *pixels, size_t size, bool should_copy=true)
	Create a Bitmap with existing pixel data, a copy will be made unless should_copy is false.
static RefPtr< Bitmap >	Create (uint32_t width, uint32_t height, BitmapFormat format, uint32_t row_bytes, const void pixels, size_t size, void user_data, DestroyBitmapCallback destruction_callback)
	Create a Bitmap that wraps existing pixel data, a user-defined destruction callback will be called when the Bitmap wants to destroy the data.
static RefPtr< Bitmap >	Create (const Bitmap &bitmap)
	Create a bitmap from a deep copy of another Bitmap.

Public Member Functions
virtual uint32_t	width () const =0
	Get the width in pixels.
virtual uint32_t	height () const =0
	Get the height in pixels.
virtual IntRect	bounds () const =0
	Get the bounds as an IntRect.
virtual BitmapFormat	format () const =0
	Get the pixel format.
virtual uint32_t	bpp () const =0
	Get the number of bytes per pixel.
virtual uint32_t	row_bytes () const =0
	Get the number of bytes between each row of pixels.
virtual size_t	size () const =0
	Get the size in bytes of the pixel buffer.
virtual bool	owns_pixels () const =0
	Whether or not this Bitmap owns the pixel buffer and will destroy it at the end of its lifetime.
virtual LockedPixels< RefPtr< Bitmap > >	LockPixelsSafe () const =0
	Lock the pixel buffer for reading/writing (safe version, automatically unlocks).
virtual void *	LockPixels ()=0
	Lock the pixel buffer for reading/writing.
virtual void	UnlockPixels ()=0
	Unlock the pixel buffer.
virtual const void *	LockPixels () const =0
	Lock the pixel buffer for reading/writing.
virtual void	UnlockPixels () const =0
	Unlock the pixel buffer.
virtual void *	raw_pixels ()=0
	Get the raw pixel buffer.
virtual bool	IsEmpty () const =0
	Whether or not this Bitmap is empty (no pixels allocated).
virtual void	Erase ()=0
	Erase the Bitmap (set all pixels to 0).
virtual void	Set (RefPtr< Bitmap > bitmap)=0
	Assign another bitmap to this one.
virtual bool	DrawBitmap (IntRect src_rect, IntRect dest_rect, RefPtr< Bitmap > src, bool pad_repeat)=0
	Draw another bitmap to this bitmap.
virtual RefPtr< Buffer >	EncodePNG (bool convert_to_rgba=true, bool convert_to_straight_alpha=true) const =0
	Encode this Bitmap as a PNG image and store the encoded bytes in a Buffer.
virtual bool	WritePNG (const char *path, bool convert_to_rgba=true, bool convert_to_straight_alpha=true) const =0
	Write this Bitmap out to a PNG image.
virtual bool	Resample (RefPtr< Bitmap > destination, bool high_quality)=0
	Make a resized copy of this bitmap by writing to a pre-allocated destination bitmap.
virtual void	SwapRedBlueChannels ()=0
	Convert a BGRA bitmap to RGBA bitmap and vice-versa by swapping the red and blue channels.
virtual void	ConvertToStraightAlpha ()=0
	Convert a BGRA bitmap from premultiplied alpha (the default) to straight alpha.
virtual void	ConvertToPremultipliedAlpha ()=0
	Convert a BGRA bitmap from straight alpha to premultiplied alpha.
virtual bool	is_compressed () const =0
	Whether or not this Bitmap uses a block-compressed (BCn) format.
Public Member Functions inherited from WeakRefCounted
virtual WeakControlBlock *	weak_control_block () const override=0
	Get the control block used to track weak references to this object (never nullptr).
Public Member Functions inherited from RefCounted
virtual void	AddRef () const =0
	Increment the reference count (thread-safe).
virtual void	Release () const =0
	Decrement the reference count (thread-safe).
virtual int	ref_count () const =0
	Get the current reference count.

Static Public Attributes
static constexpr uint32_t	MaxDimension = 16384
	Maximum supported width or height, in pixels.

Protected Member Functions
	Bitmap ()
virtual	~Bitmap ()
	Bitmap (const Bitmap &)
void	operator= (const Bitmap &)
Protected Member Functions inherited from WeakRefCounted
virtual	~WeakRefCounted ()=default
Protected Member Functions inherited from RefCounted
virtual	~RefCounted ()

Constructor & Destructor Documentation

◆ Bitmap() [1/2]

Bitmap ( )

protected

◆ ~Bitmap()

virtual ~Bitmap ( )

protectedvirtual

◆ Bitmap() [2/2]

Bitmap ( const Bitmap & )

protected

Member Function Documentation

◆ bounds()

virtual IntRect bounds ( ) const

pure virtual

Get the bounds as an IntRect.

◆ bpp()

virtual uint32_t bpp ( ) const

pure virtual

Get the number of bytes per pixel.

◆ ConvertToPremultipliedAlpha()

virtual void ConvertToPremultipliedAlpha ( )

pure virtual

Convert a BGRA bitmap from straight alpha to premultiplied alpha.

Note: Only valid if the format is BitmapFormat::BGRA8_UNORM_SRGB.

◆ ConvertToStraightAlpha()

virtual void ConvertToStraightAlpha ( )

pure virtual

Convert a BGRA bitmap from premultiplied alpha (the default) to straight alpha.

Note: Only valid if the format is BitmapFormat::BGRA8_UNORM_SRGB.

◆ Create() [1/6]

RefPtr< Bitmap > Create ( )

static

Create an empty Bitmap.

No pixels will be allocated.

Returns: Returns a ref-pointer to a new Bitmap instance.

◆ Create() [2/6]

RefPtr< Bitmap > Create ( const Bitmap & bitmap )

static

Create a bitmap from a deep copy of another Bitmap.

Parameters

bitmap The bitmap to copy from.

Returns: Returns a ref-pointer to a new Bitmap instance.

◆ Create() [3/6]

RefPtr< Bitmap > Create	(	uint32_t	width,
		uint32_t	height,
		BitmapFormat	format )

static

Create a Bitmap with a certain configuration.

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 ref-pointer to a new Bitmap instance.

◆ Create() [4/6]

RefPtr< Bitmap > Create	(	uint32_t	width,
		uint32_t	height,
		BitmapFormat	format,
		uint32_t	alignment )

static

Create an aligned Bitmap with a certain configuration.

Pixels will be allocated but not initialized. Row bytes will be padded to reach the specified alignment.

Parameters

width	The width in pixels.
height	The height in pixels.
format	The pixel format to use.
alignment	The alignment (in bytes) to use. Row bytes will be padded to reach a multiple of this value and the underlying storage will be allocated with this alignment.

Returns: Returns a ref-pointer to a new Bitmap instance.

◆ Create() [5/6]

RefPtr< Bitmap > Create	(	uint32_t	width,
		uint32_t	height,
		BitmapFormat	format,
		uint32_t	row_bytes,
		const void *	pixels,
		size_t	size,
		bool	should_copy = true )

static

Create a Bitmap with existing pixel data, a copy will be made unless should_copy is false.

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 GetBitmapFormatInfo()).
pixels	Pointer to raw pixel buffer.
size	Size of the raw pixel buffer.
should_copy	Whether or not a copy should be made of the pixels. If this is false the returned Bitmap will use the raw pixels passed in as its own, but you are still responsible for destroying your buffer afterwards.

Returns: Returns a ref-pointer to a new Bitmap instance.

◆ Create() [6/6]

RefPtr< Bitmap > Create	(	uint32_t	width,
		uint32_t	height,
		BitmapFormat	format,
		uint32_t	row_bytes,
		const void *	pixels,
		size_t	size,
		void *	user_data,
		DestroyBitmapCallback	destruction_callback )

static

Create a Bitmap that wraps existing pixel data, a user-defined destruction callback will be called when the Bitmap wants to destroy the data.

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 GetBitmapFormatInfo()).
pixels	Pointer to raw pixel buffer.
size	Size of the raw pixel buffer.
user_data	Optional user data that will be passed to destruction_callback when the Bitmap wants to destroy the pixel data. (Pass nullptr to ignore)
destruction_callback	Callback that will be called upon destruction.

Returns: Returns a ref-pointer to a new Bitmap instance.

◆ DrawBitmap()

virtual bool DrawBitmap	(	IntRect	src_rect,
		IntRect	dest_rect,
		RefPtr< Bitmap >	src,
		bool	pad_repeat )

pure virtual

Draw another bitmap to this bitmap.

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

Parameters

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

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

◆ EncodePNG()

virtual RefPtr< Buffer > EncodePNG	(	bool	convert_to_rgba = true,
		bool	convert_to_straight_alpha = true ) const

pure virtual

Encode this Bitmap as a PNG image and store the encoded bytes in a Buffer.

Parameters

convert_to_rgba	The PNG format expects RGBA format but our 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 encoded bytes, or a null ref-pointer on failure.

◆ Erase()

virtual void Erase ( )

pure virtual

Erase the Bitmap (set all pixels to 0).

◆ format()

virtual BitmapFormat format ( ) const

pure virtual

Get the pixel format.

◆ height()

virtual uint32_t height ( ) const

pure virtual

Get the height in pixels.

◆ is_compressed()

virtual bool is_compressed ( ) const

pure virtual

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. Erase(), DrawBitmap(), Resample(), and the channel/alpha conversions are no-ops or fail on a compressed Bitmap.

◆ IsEmpty()

virtual bool IsEmpty ( ) const

pure virtual

Whether or not this Bitmap is empty (no pixels allocated).

◆ LockPixels() [1/2]

virtual const void * LockPixels ( ) const

pure virtual

Lock the pixel buffer for reading/writing.

(const)

Returns: Returns a const pointer to the pixel buffer.

◆ LockPixels() [2/2]

virtual void * LockPixels ( )

pure virtual

Lock the pixel buffer for reading/writing.

Returns: Returns a pointer to the pixel buffer.

◆ LockPixelsSafe()

virtual LockedPixels< RefPtr< Bitmap > > LockPixelsSafe ( ) const

pure virtual

Lock the pixel buffer for reading/writing (safe version, automatically unlocks).

Returns: Returns a managed container that can be used to access the pixels (LockedPixels::data()). This container will automatically unlock the pixels when it goes out of scope.

◆ operator=()

void operator= ( const Bitmap & )

protected

◆ owns_pixels()

virtual bool owns_pixels ( ) const

pure virtual

Whether or not this Bitmap owns the pixel buffer and will destroy it at the end of its lifetime.

◆ raw_pixels()

virtual void * raw_pixels ( )

pure virtual

Get the raw pixel buffer.

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

◆ Resample()

virtual bool Resample	(	RefPtr< Bitmap >	destination,
		bool	high_quality )

pure virtual

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

Parameters

destination	The bitmap to store the result in, the width and height of the destination will be used.
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 BitmapFormat::BGRA8_UNORM_SRGB and the source and destination are non-empty.

◆ row_bytes()

virtual uint32_t row_bytes ( ) const

pure virtual

Get the number of bytes between each row of pixels.

Note: This value is usually calculated as width * bytes_per_pixel (bpp) but it may be larger due to alignment rules in the allocator.

◆ Set()

virtual void Set ( RefPtr< Bitmap > bitmap )

pure virtual

Assign another bitmap to this one.

Parameters

bitmap The 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 and no destruction callback) is aliased instead, so that buffer must outlive this Bitmap.

◆ size()

virtual size_t size ( ) const

pure virtual

Get the size in bytes of the pixel buffer.

Note: Size is calculated as row_bytes() * height().

◆ SwapRedBlueChannels()

virtual void SwapRedBlueChannels ( )

pure virtual

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

Note: Only valid if the format is BitmapFormat::BGRA8_UNORM_SRGB.

◆ UnlockPixels() [1/2]

virtual void UnlockPixels ( ) const

pure virtual

Unlock the pixel buffer.

(const)

◆ UnlockPixels() [2/2]

virtual void UnlockPixels ( )

pure virtual

Unlock the pixel buffer.

◆ width()

virtual uint32_t width ( ) const

pure virtual

Get the width in pixels.

◆ WritePNG()

virtual bool WritePNG	(	const char *	path,
		bool	convert_to_rgba = true,
		bool	convert_to_straight_alpha = true ) const

pure virtual

Write this Bitmap out to a PNG image.

Parameters

path	The filepath to write to (opened with fopen())
convert_to_rgba	The PNG format expects RGBA format but our 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.

Member Data Documentation

◆ MaxDimension

uint32_t MaxDimension = 16384

staticconstexpr

Maximum supported width or height, in pixels.

Create() returns a null ref-pointer if either dimension exceeds this limit.

The largest possible allocation, MaxDimension by MaxDimension at 4 bytes per pixel, is about 1 GB.

The documentation for this class was generated from the following file:

Ultralight/Bitmap.h

Overview

Thread Safety

Accessing Pixel Data

Static Public Member Functions

Public Member Functions

Static Public Attributes

Protected Member Functions

Constructor & Destructor Documentation

◆ Bitmap() [1/2]

◆ ~Bitmap()

◆ Bitmap() [2/2]

Member Function Documentation

◆ bounds()

◆ bpp()

◆ ConvertToPremultipliedAlpha()

◆ ConvertToStraightAlpha()

◆ Create() [1/6]

◆ Create() [2/6]

◆ Create() [3/6]

◆ Create() [4/6]

◆ Create() [5/6]

◆ Create() [6/6]

◆ DrawBitmap()

◆ EncodePNG()

◆ Erase()

◆ format()

◆ height()

◆ is_compressed()

◆ IsEmpty()

◆ LockPixels() [1/2]

◆ LockPixels() [2/2]

◆ LockPixelsSafe()

◆ operator=()

◆ owns_pixels()

◆ raw_pixels()

◆ Resample()

◆ row_bytes()

◆ Set()

◆ size()

◆ SwapRedBlueChannels()

◆ UnlockPixels() [1/2]

◆ UnlockPixels() [2/2]

◆ width()

◆ WritePNG()

Member Data Documentation

◆ MaxDimension