paul_bitmap.h

Includes:

<stdint.h>
<stddef.h>
<stdbool.h>
<io.h>
<dirent.h>
<unistd.h>
<assert.h>
<math.h>
<stdlib.h>
<string.h>
<ctype.h>
"paul_color.h"

Introduction

Bitmap manipulation library for C/C++.

Discussion

Implementation is included when PAUL_BITMAP_IMPLEMENTATION or PAUL_IMPLEMENTATION is defined.

Updated:: Monday, September 29, 2025

Functions

bitmap_clip: Clips a rectangular region from an image in-place.
bitmap_clipped(bitmap_t, int, int, int, int): Creates a new image from a rectangular region of another image.
bitmap_clipped(bitmap_t, int, int, int, int): Creates a new image from a rectangular region of another image.
bitmap_clipped_paste: Pastes a rectangular region from one image to another.
bitmap_destroy: Frees the memory associated with an image.
bitmap_dominant_color: Finds the most frequently occurring color in the image.
bitmap_draw_circle: Draws a circle or filled circle.
bitmap_draw_line: Draws a line between two points.
bitmap_draw_rectangle: Draws a rectangle or filled rectangle.
bitmap_draw_triangle: Draws a triangle or filled triangle.
bitmap_dupe: Creates a duplicate copy of an image.
bitmap_empty: Creates a new empty image filled with a specified color.
bitmap_fill: Fills the entire image with a solid color.
bitmap_flipped: Creates a flipped copy of an image.
bitmap_flood: Performs a flood fill starting from the specified coordinates.
bitmap_height: Gets the height of an image in pixels.
bitmap_histogram: Generates a histogram of color frequencies in the image.
bitmap_load: Creates an image from raw pixel data in the specified format.
bitmap_palette: Extracts a color palette from the image.
bitmap_paste: Pastes one image onto another at the specified position.
bitmap_pget: Gets the color of a pixel at the specified coordinates.
bitmap_pset: Sets the color of a pixel at the specified coordinates.
bitmap_resize: Resizes an image in-place to new dimensions.
bitmap_resized: Creates a resized copy of an image.
bitmap_rotate: Rotates an image in-place by the specified angle.
bitmap_rotated: Creates a rotated copy of an image.
bitmap_size: Gets both width and height of an image.
bitmap_width: Gets the width of an image in pixels.

bitmap_clip

Clips a rectangular region from an image in-place.

bool bitmap_clip(
    bitmap_t *src,
    int rx,
    int ry,
    int rw,
    int rh);

Parameters

src: Pointer to the image to clip (will be modified).
rx: The x-coordinate of the region to keep.
ry: The y-coordinate of the region to keep.
rw: The width of the region to keep.
rh: The height of the region to keep.

Return Value

true if successful, false if region is invalid or image is invalid.

Discussion

Extracts a rectangular region from the image, making it the new image content. The original image is replaced with just the clipped region.

bitmap_clipped(bitmap_t, int, int, int, int)

Creates a new image from a rectangular region of another image.

bitmap_t bitmap_clipped(
    bitmap_t src,
    int rx,
    int ry,
    int rw,
    int rh);

Parameters

src: The source image to clip from.
rx: The x-coordinate of the region in the source image.
ry: The y-coordinate of the region in the source image.
rw: The width of the region.
rh: The height of the region.

Return Value

A new image containing the clipped region, or NULL on allocation failure.

Discussion

Allocates a new image containing only the specified rectangular region from the source image. The original image remains unchanged.

bitmap_clipped(bitmap_t, int, int, int, int)

Creates a new image from a rectangular region of another image.

bitmap_t bitmap_clipped(
    bitmap_t src,
    int rx,
    int ry,
    int rw,
    int rh);

Parameters

src: The source image to clip from.
rx: The x-coordinate of the region in the source image.
ry: The y-coordinate of the region in the source image.
rw: The width of the region.
rh: The height of the region.

Return Value

A new image containing the clipped region, or NULL on allocation failure.

Discussion

Allocates a new image containing only the specified rectangular region from the source image. The original image remains unchanged.

bitmap_clipped_paste

Pastes a rectangular region from one image to another.

bool bitmap_clipped_paste(
    bitmap_t dst,
    const bitmap_t src,
    int x,
    int y,
    int rx,
    int ry,
    int rw,
    int rh);

Parameters

dst: The destination image to paste onto.
src: The source image to paste from.
x: The x-coordinate in the destination where to paste.
y: The y-coordinate in the destination where to paste.
rx: The x-coordinate of the region in the source image.
ry: The y-coordinate of the region in the source image.
rw: The width of the region in the source image.
rh: The height of the region in the source image.

Return Value

true if successful, false if images are invalid or operation would exceed bounds.

Discussion

Copies a rectangular region (rx, ry, rw, rh) from the source image onto the destination image at position (x, y). Only the specified region of the source is copied.

bitmap_destroy

Frees the memory associated with an image.

void bitmap_destroy(
    bitmap_t img);

Parameters

img: The image to destroy.

Discussion

Releases all memory allocated for the image. The image pointer becomes invalid after this call and should not be used.

bitmap_dominant_color

Finds the most frequently occurring color in the image.

color_t bitmap_dominant_color(
    const bitmap_t img);

Parameters

img: The image to analyze.

Return Value

The dominant color in the image.

Discussion

Analyzes all pixels in the image and returns the color that appears most often. Useful for generating color palettes or determining the primary color of an image.

bitmap_draw_circle

Draws a circle or filled circle.

bool bitmap_draw_circle(
    bitmap_t img,
    int xc,
    int yc,
    int r,
    color_t color,
    int fill);

Parameters

img: The image to draw on.
xc: The x-coordinate of the circle center.
yc: The y-coordinate of the circle center.
r: The radius of the circle.
color: The color to draw the circle with.
fill: Non-zero to fill the circle, zero for outline only.

Return Value

true if successful, false if the image is invalid.

Discussion

Draws a circle centered at (xc, yc) with radius r. If fill is non-zero, the circle is filled; otherwise only the outline is drawn.

bitmap_draw_line

Draws a line between two points.

bool bitmap_draw_line(
    bitmap_t img,
    int x0,
    int y0,
    int x1,
    int y1,
    color_t color);

Parameters

img: The image to draw on.
x0: The x-coordinate of the starting point.
y0: The y-coordinate of the starting point.
x1: The x-coordinate of the ending point.
y1: The y-coordinate of the ending point.
color: The color to draw the line with.

Return Value

true if successful, false if the image is invalid.

Discussion

Draws a straight line from (x0, y0) to (x1, y1) using the specified color. Uses Bresenham's line algorithm for efficient rasterization.

bitmap_draw_rectangle

Draws a rectangle or filled rectangle.

bool bitmap_draw_rectangle(
    bitmap_t img,
    int x,
    int y,
    int w,
    int h,
    color_t color,
    int fill);

Parameters

img: The image to draw on.
x: The x-coordinate of the top-left corner.
y: The y-coordinate of the top-left corner.
w: The width of the rectangle.
h: The height of the rectangle.
color: The color to draw the rectangle with.
fill: Non-zero to fill the rectangle, zero for outline only.

Return Value

true if successful, false if the image is invalid.

Discussion

Draws a rectangle with top-left corner at (x, y) and dimensions w by h. If fill is non-zero, the rectangle is filled; otherwise only the outline is drawn.

bitmap_draw_triangle

Draws a triangle or filled triangle.

bool bitmap_draw_triangle(
    bitmap_t img,
    int x0,
    int y0,
    int x1,
    int y1,
    int x2,
    int y2,
    color_t color,
    int fill);

Parameters

img: The image to draw on.
x0: The x-coordinate of the first vertex.
y0: The y-coordinate of the first vertex.
x1: The x-coordinate of the second vertex.
y1: The y-coordinate of the second vertex.
x2: The x-coordinate of the third vertex.
y2: The y-coordinate of the third vertex.
color: The color to draw the triangle with.
fill: Non-zero to fill the triangle, zero for outline only.

Return Value

true if successful, false if the image is invalid.

Discussion

Draws a triangle defined by three vertices (x0,y0), (x1,y1), (x2,y2). If fill is non-zero, the triangle is filled; otherwise only the outline is drawn.

bitmap_dupe

Creates a duplicate copy of an image.

bitmap_t bitmap_dupe(
    bitmap_t src);

Parameters

src: The source image to duplicate.

Return Value

A new image that is a copy of the source, or NULL on allocation failure.

Discussion

Allocates a new image with the same dimensions and pixel data as the source image. The returned image is independent and must be freed with bitmap_destroy() when no longer needed.

bitmap_empty

Creates a new empty image filled with a specified color.

bitmap_t bitmap_empty(
    unsigned int w,
    unsigned int h,
    color_t color);

Parameters

w: The width of the image in pixels.
h: The height of the image in pixels.
color: The color to fill the image with.

Return Value

A pointer to the new image, or NULL on allocation failure.

Discussion

Allocates memory for a new image of the specified width and height, initializing all pixels to the given color. The returned image must be freed with bitmap_destroy() when no longer needed.

bitmap_fill

Fills the entire image with a solid color.

bool bitmap_fill(
    bitmap_t img,
    color_t color);

Parameters

img: The image to fill.
color: The color to fill the image with.

Return Value

true if successful, false if the image is invalid.

Discussion

Sets all pixels in the image to the specified color, effectively clearing the image to a uniform color.

bitmap_flipped

Creates a flipped copy of an image.

bitmap_t bitmap_flipped(
    bitmap_t src,
    int horizontal,
    int vertical);

Parameters

src: The source image to flip.
horizontal: Non-zero to flip horizontally, zero to keep original orientation.
vertical: Non-zero to flip vertically, zero to keep original orientation.

Return Value

A new flipped image, or NULL on allocation failure.

Discussion

Allocates a new image that is a horizontally and/or vertically flipped version of the source image. The original image remains unchanged.

bitmap_flood

Performs a flood fill starting from the specified coordinates.

bool bitmap_flood(
    bitmap_t img,
    int x,
    int y,
    color_t color);

Parameters

img: The image to modify.
x: The x-coordinate of the starting pixel.
y: The y-coordinate of the starting pixel.
color: The new color to fill the region with.

Return Value

true if successful, false if coordinates are out of bounds or image is invalid.

Discussion

Fills a contiguous region of pixels with the same color as the starting pixel with a new color. Uses 4-way connectivity (up, down, left, right).

bitmap_height

Gets the height of an image in pixels.

int bitmap_height(
    const bitmap_t img);

Parameters

img: The image to query.

Return Value

The height of the image in pixels.

Discussion

Returns the height dimension of the image.

bitmap_histogram

Generates a histogram of color frequencies in the image.

int* bitmap_histogram(
    const bitmap_t img);

Parameters

img: The image to analyze.

Return Value

An array of integers representing color frequencies, or NULL on failure.

Discussion

Creates an array representing the frequency distribution of colors in the image. The returned array must be freed by the caller when no longer needed.

bitmap_load

Creates an image from raw pixel data in the specified format.

bitmap_t bitmap_load(
    const void *data,
    int width,
    int height,
    bitmap_format_t format);

Parameters

data: Pointer to the raw pixel data.
width: The width of the image in pixels.
height: The height of the image in pixels.
format: The format of the pixel data (see bitmap_format_t).

Return Value

A new image created from the pixel data, or NULL on failure.

Discussion

Loads pixel data from a raw byte array and creates a new image. The data must be in the specified format and contain width * height * bytes_per_pixel bytes. The returned image must be freed with bitmap_destroy() when no longer needed.

bitmap_palette

Extracts a color palette from the image.

color_t* bitmap_palette(
    const bitmap_t img,
    int count);

Parameters

img: The image to analyze.
count: The number of colors to extract for the palette.

Return Value

An array of colors representing the extracted palette, or NULL on failure.

Discussion

Analyzes the image and extracts the specified number of most representative colors. The returned array contains the palette colors and must be freed by the caller.

bitmap_paste

Pastes one image onto another at the specified position.

bool bitmap_paste(
    bitmap_t dst,
    const bitmap_t src,
    int x,
    int y);

Parameters

dst: The destination image to paste onto.
src: The source image to paste from.
x: The x-coordinate in the destination where to paste.
y: The y-coordinate in the destination where to paste.

Return Value

true if successful, false if images are invalid or operation would exceed bounds.

Discussion

Copies all pixels from the source image onto the destination image starting at position (x, y). The source image is pasted over the destination without any alpha blending.

bitmap_pget

Gets the color of a pixel at the specified coordinates.

color_t bitmap_pget(
    const bitmap_t img,
    int x,
    int y);

Parameters

img: The image to query.
x: The x-coordinate of the pixel.
y: The y-coordinate of the pixel.

Return Value

The color of the pixel, or a default color if coordinates are out of bounds.

Discussion

Retrieves the color of the pixel at position (x, y). Coordinates are zero-based, with (0,0) being the top-left corner. If coordinates are out of bounds, returns a default color.

bitmap_pset

Sets the color of a pixel at the specified coordinates.

bool bitmap_pset(
    bitmap_t img,
    int x,
    int y,
    color_t color);

Parameters

img: The image to modify.
x: The x-coordinate of the pixel.
y: The y-coordinate of the pixel.
color: The new color for the pixel.

Return Value

true if successful, false if coordinates are out of bounds or image is invalid.

Discussion

Changes the color of the pixel at position (x, y). Coordinates are zero-based, with (0,0) being the top-left corner. If coordinates are out of bounds, the operation fails.

bitmap_resize

Resizes an image in-place to new dimensions.

bool bitmap_resize(
    bitmap_t *src,
    int nw,
    int nh);

Parameters

src: Pointer to the image to resize (will be modified).
nw: The new width for the image.
nh: The new height for the image.

Return Value

true if successful, false if allocation fails or image is invalid.

Discussion

Changes the size of the image to the specified width and height. The original image data is lost and replaced with resized content. Uses nearest-neighbor interpolation.

bitmap_resized

Creates a resized copy of an image.

bitmap_t bitmap_resized(
    bitmap_t src,
    int nw,
    int nh);

Parameters

src: The source image to resize.
nw: The width of the new image.
nh: The height of the new image.

Return Value

A new resized image, or NULL on allocation failure.

Discussion

Allocates a new image with the specified dimensions and copies the source image content resized to fit. Uses nearest-neighbor interpolation. The original image remains unchanged.

bitmap_rotate

Rotates an image in-place by the specified angle.

bool bitmap_rotate(
    bitmap_t *src,
    float angle);

Parameters

src: Pointer to the image to rotate (will be modified).
angle: The rotation angle in degrees.

Return Value

true if successful, false if allocation fails or image is invalid.

Discussion

Rotates the image around its center by the given angle in degrees. Positive angles rotate clockwise. The image dimensions may change to accommodate the rotated content.

bitmap_rotated

Creates a rotated copy of an image.

bitmap_t bitmap_rotated(
    bitmap_t src,
    float angle);

Parameters

src: The source image to rotate.
angle: The rotation angle in degrees.

Return Value

A new rotated image, or NULL on allocation failure.

Discussion

Allocates a new image and copies the source image content rotated by the specified angle. The original image remains unchanged.

bitmap_size

Gets both width and height of an image.

bool bitmap_size(
    const bitmap_t img,
    int *w,
    int *h);

Parameters

img: The image to query.
w: Pointer to store the width (can be NULL if not needed).
h: Pointer to store the height (can be NULL if not needed).

Return Value

true if successful, false if the image is invalid.

Discussion

Retrieves the dimensions of the image, storing them in the provided pointers. This is more efficient than calling bitmap_width() and bitmap_height() separately.

bitmap_width

Gets the width of an image in pixels.

int bitmap_width(
    const bitmap_t img);

Parameters

img: The image to query.

Return Value

The width of the image in pixels.

Discussion

Returns the width dimension of the image.

Typedefs

bitmap_format_t: Enumeration of supported pixel data formats for image loading.
bitmap_t: Represents an RGBA color with 8 bits per channel.
color_t: Represents a color with red, green, blue, and alpha components.

bitmap_format_t

Enumeration of supported pixel data formats for image loading.

typedef enum { 
    BITMAP_FORMAT_RGBA, // 4 bytes per pixel: R, G, B, A 
    BITMAP_FORMAT_RGB, // 3 bytes per pixel: R, G, B (alpha = 255) 
    BITMAP_FORMAT_BGRA, // 4 bytes per pixel: B, G, R, A 
    BITMAP_FORMAT_BGR, // 3 bytes per pixel: B, G, R (alpha = 255) 
    BITMAP_FORMAT_ARGB, // 4 bytes per pixel: A, R, G, B 
    BITMAP_FORMAT_ABGR, // 4 bytes per pixel: A, B, G, R 
    BITMAP_FORMAT_GRAY, // 1 byte per pixel: grayscale (alpha = 255) 
    BITMAP_FORMAT_GRAY_ALPHA, // 2 bytes per pixel: grayscale, alpha 
    BITMAP_FORMAT_RGB565, // 2 bytes per pixel: 5-bit R, 6-bit G, 5-bit B (alpha = 255) 
    BITMAP_FORMAT_RGB555, // 2 bytes per pixel: 5-bit R, 5-bit G, 5-bit B (alpha = 255) 
    BITMAP_FORMAT_ARGB1555 // 2 bytes per pixel: 1-bit A, 5-bit R, 5-bit G, 5-bit B 
} bitmap_format_t;

Fields

BITMAP_FORMAT_RGBA: 4 bytes per pixel: R, G, B, A
BITMAP_FORMAT_RGB: 3 bytes per pixel: R, G, B (alpha = 255)
BITMAP_FORMAT_BGRA: 4 bytes per pixel: B, G, R, A
BITMAP_FORMAT_BGR: 3 bytes per pixel: B, G, R (alpha = 255)
BITMAP_FORMAT_ARGB: 4 bytes per pixel: A, R, G, B
BITMAP_FORMAT_ABGR: 4 bytes per pixel: A, B, G, R
BITMAP_FORMAT_GRAY: 1 byte per pixel: grayscale (alpha = 255)
BITMAP_FORMAT_GRAY_ALPHA: 2 bytes per pixel: grayscale, alpha
BITMAP_FORMAT_RGB565: 2 bytes per pixel: 5-bit R, 6-bit G, 5-bit B (alpha = 255)
BITMAP_FORMAT_RGB555: 2 bytes per pixel: 5-bit R, 5-bit G, 5-bit B (alpha = 255)
BITMAP_FORMAT_ARGB1555: 2 bytes per pixel: 1-bit A, 5-bit R, 5-bit G, 5-bit B

Discussion

Defines the various pixel formats that can be used when loading image data from raw pixel arrays. Each format specifies the byte layout and channel count of the pixel data.

bitmap_t

Represents an RGBA color with 8 bits per channel.

typedef color_t* bitmap_t;

color_t

Represents a color with red, green, blue, and alpha components.

typedef union color_t { 
    struct { 
        uint8_t r, g, b, a; 
        }; 
    uint32_t rgba; 
} color_t;

Fields

r: Red component (0-255)
g: Green component (0-255)
b: Blue component (0-255)
a: Alpha component (0-255)
rgba: Packed RGBA value as 32-bit integer

Last Updated: Monday, September 29, 2025