ui::Bitmap¶

Header: winui/render/Bitmap.hpp.

A CPU bitmap, 4 bytes per pixel: RGBA with straight alpha unless made in another PixelFormat.

The picture type everything image-shaped uses: ImageSource and the Image element, Icon, PersonPicture, IconSource::bitmap(), the clipboard, and pixel tests, which capture into one and check it with compare(). PNG encodes and decodes byte for byte the same on every platform. decode() and read() handle photos (JPEG, GIF and the other formats the system's image codecs read) with optional downscaling and EXIF orientation. A value type: copying copies the pixels.

A renderer that writes premultiplied BGRA can draw straight into a bitmap made in that format, through bytes(), and the picture then reaches the screen with no pass over its pixels. get(), set() and the encoders work in either format.

Example:

// Load a photo for display, bounded to 1024px and upright.
ui::Bitmap photo = ui::Bitmap::read("holiday.jpg", {.max_width = 1024, .max_height = 1024});
window.set_content(ui::Image{.source = std::move(photo), .stretch = ui::Stretch::Uniform});

// Build one by hand, e.g. a color swatch for a palette export, and save it as PNG.
ui::Bitmap swatch{16, 16, ui::colors::White};
swatch.set(0, 0, ui::Color::from_rgba(255, 0, 0));
swatch.write_png("swatch.png"); // lossless: read_png() gives back the same pixels

// A page a PDF renderer draws right into the bitmap's bytes, shown as they are. Here the
// page is filled opaque white, the same in premultiplied BGRA.
ui::Bitmap page{612, 792, ui::PixelFormat::Bgra8Premultiplied};
std::ranges::fill(page.bytes(), std::uint8_t{0xFF});

Bitmap¶

Bitmap() = default

An empty (0x0) image.

Bitmap¶

Bitmap(int width, int height, const Color& fill = colors::Transparent)

A width x height image, every pixel fill (transparent by default).

Bitmap¶

Bitmap(int width, int height, PixelFormat format)

A width x height image in format, every pixel transparent: zero bytes, ready for a renderer to draw into through bytes().

width¶

int width() const

Width in pixels; 0 when empty.

height¶

int height() const

Height in pixels; 0 when empty.

empty¶

bool empty() const

True when either dimension is zero (nothing to draw).

format¶

PixelFormat format() const

How the bytes are laid out; Rgba8 unless the bitmap was made in another format.

converted¶

Bitmap converted(PixelFormat format) const

The same picture with its bytes in format; a copy when it is already in it.

bytes¶

std::span<const std::uint8_t> bytes() const

The pixel bytes in format()'s layout, row-major, 4 per pixel, width * 4 per row.

bytes¶

std::span<std::uint8_t> bytes()

The pixel bytes, writable; width * height * 4 of them. Asking for them counts as a change to the pixels (content_id()).

content_id¶

std::uint64_t content_id() const

A number that stays the same while the pixels do and is never reused for other pixels: a copy shares it until either side is written to (fill(), set(), blend(), the writable bytes()). A renderer keeps the copy it uploaded to the GPU under it.

fill¶

void fill(const Color& c)

Sets every pixel to c (a replace, not a blend).

set¶

void set(int x, int y, const Color& c)

Replaces the pixel, ignoring what was there.

get¶

Color get(int x, int y) const

Reads a pixel back as a Color, with straight alpha in either format.

blend¶

void blend(int x, int y, const Color& c, std::uint8_t coverage)

Source-over composite of c at coverage (0..255) onto the existing pixel.

encode_png¶

std::vector<std::uint8_t> encode_png() const

The image as PNG bytes, identical on every platform.

write_png¶

void write_png(const std::filesystem::path& path) const

encode_png() written to path. Throws std::runtime_error if the file can't be written.

encode_jpeg¶

std::vector<std::uint8_t> encode_jpeg(int quality = 90) const

Baseline JPEG at quality (1..100). Alpha is dropped; JPEG has none.

oriented¶

Bitmap oriented(ImageOrientation orientation) const

This image turned upright, given the orientation it was stored with.

scaled_to_fit¶

Bitmap scaled_to_fit(int max_width, int max_height) const

This image shrunk to fit inside max_width × max_height (zero: unconstrained), aspect ratio kept, by area averaging with alpha weighting, so a transparent pixel's color doesn't bleed into its neighbors. Never enlarges: an image that already fits comes back as is. The result keeps the format.

decode_png¶

static Bitmap decode_png(const std::vector<std::uint8_t>& data)

Decodes PNG bytes, identically on every platform. Throws std::runtime_error if data is not a readable PNG.

read_png¶

static Bitmap read_png(const std::filesystem::path& path)

decode_png() of the file at path. Throws std::runtime_error if it can't be read.

decode¶

static Bitmap decode(std::span<const std::uint8_t> data, const ImageDecodeOptions& options = {})

Decodes an encoded image held in memory. Throws std::runtime_error if it can't.

read¶

static Bitmap read(const std::filesystem::path& path, const ImageDecodeOptions& options = {})

Decodes the file at path. Any file name opens, whatever characters it holds. Throws std::runtime_error if the file can't be read or decoded. Thread-safe and meant to be called from worker threads, which need no setup for it.

read_thumbnail¶

static Bitmap read_thumbnail(const std::filesystem::path& path, int max_edge)

read() into a max_edge × max_edge box, upright.

read_orientation¶

static ImageOrientation read_orientation(std::span<const std::uint8_t> data)

The EXIF orientation recorded in an encoded JPEG or TIFF, Normal when there is none. Reads only the header; decode()/read() already apply it unless told not to.