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.
An immutable Bitmap (see is_immutable()) does no locking either, since its pixels never change.
Accessing Pixel Data
You can access the underlying pixel data by using the LockPixelsSafe() method. An example follows:
auto pixels = bitmap->LockPixelsSafe();
if (pixels && pixels.data()) {
memset(pixels.data(), 0, pixels.size());
}
static RefPtr< Bitmap > Create()
Create an empty Bitmap.
@ BGRA8_UNORM_SRGB
Blue Green Red Alpha channels, 32-bits per pixel.
Definition Bitmap.h:33
|
| 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.
|
|
| 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.
|
| virtual bool | is_immutable () const =0 |
| | Whether or not this Bitmap is immutable.
|
| virtual WeakControlBlock * | weak_control_block () const override=0 |
| | Get the control block used to track weak references to this object (never nullptr).
|
| 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.
|
| virtual bool is_immutable |
( |
| ) |
const |
|
pure virtual |
Whether or not this Bitmap is immutable.
The library makes a Bitmap immutable once its pixels are final (eg, a fully decoded image). Once this returns true it stays true: the pixels never change again and the pixel buffer lives as long as the Bitmap, so you can keep a reference to it instead of copying the pixels.
Erase(), Set(), DrawBitmap(), SwapRedBlueChannels(), ConvertToStraightAlpha(), ConvertToPremultipliedAlpha(), and using this Bitmap as the destination of Resample() all fail or do nothing on an immutable Bitmap.
You can still read it: LockPixels(), LockPixelsSafe(), EncodePNG(), WritePNG(), and using it as the source of Resample() or DrawBitmap() work as usual.
- Note
- This is safe to call from any thread. An immutable Bitmap's pixels can be read from any thread at the same time.
| 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.