Bitmap

#include <Ultralight/Bitmap.h>

Overview

A thread-safe 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 provides thread-safe access to the pixel data.

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.
Public Member Functions inherited from RefCounted
virtual void	AddRef () const =0
virtual void	Release () const =0
virtual int	ref_count () const =0

Protected Member Functions
	Bitmap ()
virtual	~Bitmap ()
	Bitmap (const Bitmap &)
void	operator= (const Bitmap &)
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]

static RefPtr< Bitmap > Create ( )

static

Create an empty Bitmap.

No pixels will be allocated.

Create() [2/6]

static RefPtr< Bitmap > Create ( const Bitmap & bitmap )

static

Create a bitmap from a deep copy of another Bitmap.

Create() [3/6]

static 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

A ref-pointer to a new Bitmap instance.

Create() [4/6]

static 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

A ref-pointer to a new Bitmap instance.

Create() [5/6]

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 )

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 (note that this value should be >= width * bytes_per_pixel).
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

A ref-pointer to a new Bitmap instance.

Create() [6/6]

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 )

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 (note that this value should be >= width * bytes_per_pixel).
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

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. Note that when converting from BGRA8 to A8, only the Blue channel will be used.

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

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

On success, a buffer containing the encoded bytes, otherwise a null RefPtr.

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.

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

A const pointer to the pixel buffer.

LockPixels() [2/2]

virtual void * LockPixels ( )

pure virtual

Lock the pixel buffer for reading/writing.

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

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

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.

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

Whether or not the operation succeeded.

---

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

• Ultralight/Bitmap.h