image.h File Reference

Image processing library utilities. More...

#include <stddef.h>
#include <stdint.h>
#include "tinyimg/tinyimg.h"
#include "tinyimg/util.h"

Go to the source code of this file.

Classes
struct	TinyImage
	Represents an image with its width, height, and pixel data. More...
struct	TinyImageInfo
	What a format's header says about an image, before any pixel is decoded. More...
struct	TinyDecodeOpts
	Options a decoder honors when only part of an image is wanted. More...
struct	TinyEncodeOpts
	Options an encoder honors. More...
struct	TinyShape
struct	TinyDisplayList
	A list of shapes that rasterizes once. More...

Macros
#define	TINYIMG_DISPLAY_MAX_SHAPES   64
#define	TINYIMG_DISPLAY_MAX_POINTS   256
#define	TINYIMG_DISPLAY_MAX_DEPTH   8

Typedefs
typedef enum TinyImageFormat	TinyImageFormat
	Image formats supported by TinyImage for conversion and saving.
typedef enum TinyImagePixelType	TinyImagePixelType
	What the channels of an image mean.
typedef struct TinyImageMeta	TinyImageMeta
	Metadata carried alongside the pixels.
typedef enum TinyEffort	TinyEffort
	How much computation an operation may spend to do its best work.
typedef enum TinyBlendMode	TinyBlendMode
	How a shape's color is combined with what is already there.
typedef enum TinyFillRule	TinyFillRule
	Which points a polygon fill considers inside.
typedef enum TinyDrawMode	TinyDrawMode
	How a source image larger or smaller than its target is placed.
typedef enum TinyShapeKind	TinyShapeKind
typedef enum TinyImageFit	TinyImageFit
	How an image is made to fit a target width and height.
typedef enum TinyImageGravity	TinyImageGravity
	Which part of an image a crop keeps, or where a pad puts it.
typedef enum TinyColorblindKind	TinyColorblindKind
	The forms of color blindness the simulation and the assist cover.
typedef enum TinyImagePreset	TinyImagePreset
	The named looks, each a fixed stack of the adjustments above.

Enumerations
enum	TinyImageFormat {   TINYIMG_FORMAT_UNKNOWN = 0 , TINYIMG_FORMAT_PNG = 1 , TINYIMG_FORMAT_JPEG = 2 , TINYIMG_FORMAT_BMP = 3 ,   TINYIMG_FORMAT_GIF = 4 , TINYIMG_FORMAT_TIFF = 5 , TINYIMG_FORMAT_WEBP = 6 , TINYIMG_FORMAT_AVIF = 7 ,   TINYIMG_FORMAT_HEIF = 8 }
	Image formats supported by TinyImage for conversion and saving. More...
enum	TinyImagePixelType { TINYIMG_PIXEL_GRAY = 0 , TINYIMG_PIXEL_GRAY_ALPHA = 1 , TINYIMG_PIXEL_RGB = 2 , TINYIMG_PIXEL_RGBA = 3 }
	What the channels of an image mean. More...
enum	TinyEffort { TINYIMG_EFFORT_FANCY = 0 , TINYIMG_EFFORT_FAST = 1 }
	How much computation an operation may spend to do its best work. More...
enum	TinyBlendMode {   TINYIMG_BLEND_NORMAL = 0 , TINYIMG_BLEND_REPLACE = 1 , TINYIMG_BLEND_MULTIPLY = 2 , TINYIMG_BLEND_SCREEN = 3 ,   TINYIMG_BLEND_OVERLAY = 4 , TINYIMG_BLEND_DARKEN = 5 , TINYIMG_BLEND_LIGHTEN = 6 , TINYIMG_BLEND_DIFFERENCE = 7 ,   TINYIMG_BLEND_EXCLUSION = 8 , TINYIMG_BLEND_HARD_LIGHT = 9 , TINYIMG_BLEND_SOFT_LIGHT = 10 , TINYIMG_BLEND_ADD = 11 ,   TINYIMG_BLEND_SUBTRACT = 12 }
	How a shape's color is combined with what is already there. More...
enum	TinyFillRule { TINYIMG_FILL_EVEN_ODD = 0 , TINYIMG_FILL_NONZERO = 1 }
	Which points a polygon fill considers inside. More...
enum	TinyDrawMode { TINYIMG_DRAW_ONCE = 0 , TINYIMG_DRAW_TILE = 1 , TINYIMG_DRAW_CENTER = 2 }
	How a source image larger or smaller than its target is placed. More...
enum	TinyShapeKind {   TINYIMG_SHAPE_NONE = 0 , TINYIMG_SHAPE_RECT = 1 , TINYIMG_SHAPE_ROUND_RECT = 2 , TINYIMG_SHAPE_ELLIPSE = 3 ,   TINYIMG_SHAPE_LINE = 4 , TINYIMG_SHAPE_POLYGON = 5 }
enum	TinyImageFit {   TINYIMG_FIT_SCALE_DOWN = 0 , TINYIMG_FIT_CONTAIN = 1 , TINYIMG_FIT_COVER = 2 , TINYIMG_FIT_CROP = 3 ,   TINYIMG_FIT_ASPECT_CROP = 4 , TINYIMG_FIT_ASPECT_CONTAIN = 5 , TINYIMG_FIT_ASPECT_COVER = 6 , TINYIMG_FIT_PAD = 7 ,   TINYIMG_FIT_STRETCH = 8 , TINYIMG_FIT_FILL = 9 , TINYIMG_FIT_SCALE_UP = 10 }
	How an image is made to fit a target width and height. More...
enum	TinyImageGravity {   TINYIMG_GRAVITY_CENTER = 0 , TINYIMG_GRAVITY_NORTH = 1 , TINYIMG_GRAVITY_SOUTH = 2 , TINYIMG_GRAVITY_WEST = 3 ,   TINYIMG_GRAVITY_EAST = 4 , TINYIMG_GRAVITY_NORTH_WEST = 5 , TINYIMG_GRAVITY_NORTH_EAST = 6 , TINYIMG_GRAVITY_SOUTH_WEST = 7 ,   TINYIMG_GRAVITY_SOUTH_EAST = 8 , TINYIMG_GRAVITY_AUTO = 9 , TINYIMG_GRAVITY_FACE = 10 }
	Which part of an image a crop keeps, or where a pad puts it. More...
enum	TinyColorblindKind { TINYIMG_COLORBLIND_PROTANOPIA = 0 , TINYIMG_COLORBLIND_DEUTERANOPIA = 1 , TINYIMG_COLORBLIND_TRITANOPIA = 2 , TINYIMG_COLORBLIND_ACHROMATOPSIA = 3 }
	The forms of color blindness the simulation and the assist cover. More...
enum	TinyImagePreset {   TINYIMG_PRESET_NOIR = 0 , TINYIMG_PRESET_CHROME = 1 , TINYIMG_PRESET_MONO = 2 , TINYIMG_PRESET_FADE = 3 ,   TINYIMG_PRESET_VIVID = 4 , TINYIMG_PRESET_WARM = 5 , TINYIMG_PRESET_COOL = 6 , TINYIMG_PRESET_INSTANT = 7 ,   TINYIMG_PRESET_TONAL = 8 }
	The named looks, each a fixed stack of the adjustments above. More...

Functions
int	tiny_image_create (TinyImage *image, uint32_t width, uint32_t height, uint8_t channels)
	Creates a new image with the specified width, height and channel count.
int	tiny_image_probe (const uint8_t *buffer, size_t buffer_size, TinyImageInfo *info)
	Reads an image's header without decoding any pixels.
int	tiny_image_load (TinyImage *image, const uint8_t *buffer, size_t buffer_size)
	Loads an image, decoding every pixel.
int	tiny_image_load_scaled (TinyImage *image, const uint8_t *buffer, size_t buffer_size, uint32_t max_width, uint32_t max_height)
	Loads an image at the cheapest scale that still covers the given box.
int	tiny_image_load_region (TinyImage *image, const uint8_t *buffer, size_t buffer_size, uint32_t x, uint32_t y, uint32_t width, uint32_t height)
	Loads one rectangle of an image.
int	tiny_image_decode (TinyImage *image, const uint8_t *buffer, size_t buffer_size, const TinyDecodeOpts *opts)
	Loads an image with full control over region, scale and channel count.
int	tiny_image_encode (const TinyImage *image, TinyImageFormat format, const TinyEncodeOpts *opts, TinyWriter *writer)
	Encodes an image into a growing byte sink.
int	tiny_image_destroy (TinyImage *image)
	Destroys an image, freeing its associated memory.
int	tiny_image_gettype (const TinyImage *image, TinyImagePixelType *type)
	Retrieves the type of the image (grayscale, grayscale with alpha, RGB or RGBA).
const char *	tiny_format_name (TinyImageFormat format)
	Retrieves the short name of a format, such as "png" or "jpeg".
const char *	tiny_format_extension (TinyImageFormat format)
	Retrieves the conventional file extension of a format, leading dot included.
TinyImageFormat	tiny_format_sniff (const uint8_t *buffer, size_t buffer_size)
	Identifies a format from a buffer's magic bytes.
int	tiny_image_getextension (const TinyImage *image, char *extension, size_t max_length)
	Retrieves the file extension associated with the image format.
int	tiny_image_getpixel (const TinyImage *image, uint32_t x, uint32_t y, uint8_t *pixel)
	Retrieves the pixel value at the specified (x, y) coordinates in the image.
int	tiny_image_setpixel (TinyImage *image, uint32_t x, uint32_t y, const uint8_t *pixel)
	Writes the pixel value at the specified (x, y) coordinates in the image.
uint32_t	tiny_image_info_sizeof (void)
	Size of a TinyImageInfo, for a host allocating one across the wasm boundary.
uint32_t	tiny_image_sizeof (void)
	Size of a TinyImage, for a host allocating one across the wasm boundary.
uint32_t	tiny_image_getwidth (const TinyImage *image)
	Width of an image in pixels.
uint32_t	tiny_image_getheight (const TinyImage *image)
	Height of an image in pixels.
uint32_t	tiny_image_getchannels (const TinyImage *image)
	Channels per pixel.
uint8_t *	tiny_image_getdata (const TinyImage *image)
	Pointer to an image's pixel data.
uint32_t	tiny_image_getsize (const TinyImage *image)
	Bytes an image's pixel data occupies.
int	tiny_image_hline (TinyImage *image, int32_t x1, int32_t y1, int32_t x2, int32_t y2, const uint8_t *pixel)
	Draws a horizontal run of pixels.
int	tiny_image_vline (TinyImage *image, int32_t x1, int32_t y1, int32_t x2, int32_t y2, const uint8_t *pixel)
	Draws a vertical run of pixels.
int	tiny_image_rectangle (TinyImage *image, int32_t x, int32_t y, uint32_t width, uint32_t height, const uint8_t *pixel)
	Draws the outline of a rectangle, one pixel wide.
int	tiny_image_fill_rectangle (TinyImage *image, int32_t x, int32_t y, uint32_t width, uint32_t height, const uint8_t *pixel)
	Fills a rectangle.
int	tiny_image_fill_rounded_rectangle (TinyImage *image, int32_t x, int32_t y, uint32_t width, uint32_t height, uint32_t radius, const uint8_t *pixel)
	Fills a rectangle whose corners are rounded.
int	tiny_image_draw_line (TinyImage *image, int32_t x1, int32_t y1, int32_t x2, int32_t y2, uint32_t thickness, const uint8_t *pixel)
	Draws a line of the given thickness.
int	tiny_image_draw_circle (TinyImage *image, int32_t center_x, int32_t center_y, uint32_t radius, const uint8_t *pixel)
	Draws the outline of a circle.
int	tiny_image_fill_circle (TinyImage *image, int32_t center_x, int32_t center_y, uint32_t radius, const uint8_t *pixel)
	Fills a circle.
int	tiny_image_draw_ellipse (TinyImage *image, int32_t center_x, int32_t center_y, uint32_t radius_x, uint32_t radius_y, const uint8_t *pixel)
	Draws the outline of an axis-aligned ellipse.
int	tiny_image_fill_ellipse (TinyImage *image, int32_t center_x, int32_t center_y, uint32_t radius_x, uint32_t radius_y, const uint8_t *pixel)
	Fills an axis-aligned ellipse.
int	tiny_image_polygon (TinyImage *image, const int32_t *x_points, const int32_t *y_points, size_t num_points, const uint8_t *pixel)
	Draws the edges of a polygon, closing it.
int	tiny_image_fill_polygon (TinyImage *image, const int32_t *x_points, const int32_t *y_points, size_t num_points, const uint8_t *pixel)
	Fills a polygon by the even-odd rule.
int	tiny_image_fill_polygon_with (TinyImage *image, const int32_t *x_points, const int32_t *y_points, size_t num_points, const uint8_t *pixel, TinyFillRule rule, TinyBlendMode blend)
	Fills a polygon by a named rule, blended.
int	tiny_image_replace_color (TinyImage *image, const uint8_t *old_color, const uint8_t *new_color, const uint8_t *tolerance)
	Replaces every pixel close to one color with another.
int	tiny_image_draw_image (TinyImage *dest_image, const TinyImage *src_image, int32_t x, int32_t y)
	Draws one image onto another.
int	tiny_image_draw_image_ex (TinyImage *dest_image, const TinyImage *src_image, int32_t x, int32_t y, float opacity, TinyDrawMode mode, TinyBlendMode blend)
	Draws one image onto another with an opacity, a placement and a blend mode.
int	tiny_image_composite (TinyImage *dest_image, const TinyImage *src_image, TinyBlendMode blend)
	Composites one image over another in place, Porter-Duff source-over.
int	tiny_image_premultiply (TinyImage *image)
	Multiplies each color channel by its alpha.
int	tiny_image_unpremultiply (TinyImage *image)
	Divides each color channel by its alpha.
int	tiny_image_gradient_linear (TinyImage *image, int32_t x0, int32_t y0, int32_t x1, int32_t y1, const uint8_t *from, const uint8_t *to)
	Fills the image with a linear gradient.
int	tiny_image_gradient_radial (TinyImage *image, int32_t center_x, int32_t center_y, uint32_t radius, const uint8_t *inner, const uint8_t *outer)
	Fills the image with a radial gradient.
int	tiny_image_gradient_fade (TinyImage *image, float angle, float start, float end)
	Fades the image toward transparency along a direction.
int	tiny_image_border (TinyImage *image, uint32_t border_width, const uint8_t *pixel)
	Draws a border inside the image's edges.
int	tiny_image_expand (TinyImage *image, uint32_t left, uint32_t top, uint32_t right, uint32_t bottom, const uint8_t *pixel)
	Grows the image by a border around it.
int	tiny_draw_coverage (TinyImage *image, int32_t x, int32_t y, const uint8_t *mask, uint32_t width, uint32_t height, const uint8_t *color, TinyBlendMode blend)
	Blends one color through an 8-bit coverage mask.
uint32_t	tiny_display_sizeof (void)
	Size of a TinyDisplayList, for a host allocating one.
int	tiny_display_init (TinyDisplayList *list)
	Empties a display list and resets its transform to the identity.
int	tiny_display_save (TinyDisplayList *list)
	Pushes the current transform.
int	tiny_display_restore (TinyDisplayList *list)
	Pops the transform saved last.
int	tiny_display_translate (TinyDisplayList *list, float x, float y)
	Moves the current transform.
int	tiny_display_scale (TinyDisplayList *list, float x, float y)
	Scales the current transform.
int	tiny_display_rotate (TinyDisplayList *list, float degrees)
	Turns the current transform.
int	tiny_display_set_transform (TinyDisplayList *list, const float *matrix)
	Sets the current transform outright.
int	tiny_display_rect (TinyDisplayList *list, float x, float y, float width, float height, const uint8_t *color)
	Adds a rectangle.
int	tiny_display_round_rect (TinyDisplayList *list, float x, float y, float width, float height, float radius, const uint8_t *color)
	Adds a rectangle with rounded corners.
int	tiny_display_ellipse (TinyDisplayList *list, float center_x, float center_y, float radius_x, float radius_y, const uint8_t *color)
	Adds an ellipse.
int	tiny_display_line (TinyDisplayList *list, float x1, float y1, float x2, float y2, float thickness, const uint8_t *color)
	Adds a line.
int	tiny_display_polygon (TinyDisplayList *list, const float *x_points, const float *y_points, size_t num_points, const uint8_t *color, TinyFillRule rule)
	Adds a polygon.
int	tiny_display_blend (TinyDisplayList *list, TinyBlendMode blend)
	Sets the blend mode the next shapes are added with.
int	tiny_display_render (TinyDisplayList *list, TinyImage *image)
	Draws every shape onto an image, in one pass over the list.
uint32_t	tiny_display_culled (const TinyDisplayList *list)
	How many shapes the last render dropped as outside the target.
uint32_t	tiny_display_covered (const TinyDisplayList *list)
	How many shapes the last render dropped as covered by a later opaque one.
int	tiny_display_bounds (const TinyDisplayList *list, int32_t *x, int32_t *y, uint32_t *width, uint32_t *height)
	The rectangle every shape in the list falls inside.
int	tiny_image_resize (TinyImage *image, uint32_t new_width, uint32_t new_height)
	Resamples an image to the specified new width and height.
int	tiny_image_crop (TinyImage *image, uint32_t x, uint32_t y, uint32_t crop_width, uint32_t crop_height)
	Crops an image to the specified rectangle defined by the top-left corner (x, y) and the desired width and height.
int	tiny_image_crop_circle (TinyImage *image, uint32_t center_x, uint32_t center_y, uint32_t radius)
	Crops an image to a circular region defined by the center (center_x, center_y) and the specified radius.
int	tiny_image_crop_ellipse (TinyImage *image, uint32_t center_x, uint32_t center_y, uint32_t radius_x, uint32_t radius_y)
	Crops an image to an elliptical region defined by the center (center_x, center_y) and the specified radii along the x and y axes.
int	tiny_image_crop_polygon (TinyImage *image, const uint32_t *x_points, const uint32_t *y_points, size_t num_points)
	Crops an image to a polygonal region defined by a series of points (x_points, y_points).
int	tiny_image_flip_horizontal (TinyImage *image)
	Flips an image horizontally, mirroring it along the vertical axis.
int	tiny_image_flip_vertical (TinyImage *image)
	Flips an image vertically, mirroring it along the horizontal axis.
int	tiny_image_rotate_90 (TinyImage *image)
	Rotates an image 90 degrees clockwise.
int	tiny_image_rotate_180 (TinyImage *image)
	Rotates an image 180 degrees.
int	tiny_image_rotate_270 (TinyImage *image)
	Rotates an image 270 degrees clockwise (or 90 degrees counterclockwise).
int	tiny_image_opacity (TinyImage *image, float opacity)
	Adjusts the opacity of an image by modifying its alpha channel.
int	tiny_image_trim (TinyImage *image, uint8_t tolerance)
	Removes a uniform border by cropping to what differs from it.
int	tiny_image_invert (TinyImage *image)
	Inverts the colors of an image, producing a negative effect.
int	tiny_image_quality (TinyImage *image, int quality)
	Sets the quality of the image for lossy formats (e.g., JPEG).
int	tiny_image_blur (TinyImage *image, float radius)
	Applies a blur effect to the image.
int	tiny_image_sharpen (TinyImage *image, float amount)
	Applies a sharpen effect to the image.
int	tiny_image_brightness (TinyImage *image, float factor)
	Adjusts the brightness of the image.
int	tiny_image_contrast (TinyImage *image, float factor)
	Adjusts the contrast of the image.
int	tiny_image_dpr (TinyImage *image, float dpr)
	Scales an image by a device pixel ratio.
int	tiny_image_saturation (TinyImage *image, float factor)
	Adjusts the saturation of the image.
int	tiny_image_hue (TinyImage *image, float angle)
	Adjusts the hue of the image.
int	tiny_image_fit (TinyImage *image, uint32_t target_width, uint32_t target_height, TinyImageFit fit_mode)
	Resizes an image to fit within the specified target width and height according to the specified fit mode.
int	tiny_image_fit_with_padding (TinyImage *image, uint32_t target_width, uint32_t target_height, TinyImageFit fit_mode, const uint8_t *padding_color)
	Resizes an image to fit within the specified target width and height according to the specified fit mode, with optional padding.
int	tiny_image_fit_with_padding_and_background (TinyImage *image, uint32_t target_width, uint32_t target_height, TinyImageFit fit_mode, const uint8_t *padding_color, const uint8_t *background_color)
	Resizes an image to fit within the specified target width and height according to the specified fit mode, with optional padding and background color.
int	tiny_image_fit_with_gravity (TinyImage *image, uint32_t target_width, uint32_t target_height, TinyImageFit fit_mode, TinyImageGravity gravity, const uint8_t *background)
	Fits the image to a target, keeping the part the gravity names.
int	tiny_image_gamma_correction (TinyImage *image, float gamma)
	Applies gamma correction to the image.
int	tiny_image_apply_sepia (TinyImage *image)
	Applies a sepia tone effect to the image.
int	tiny_image_remove_background (TinyImage *image, uint8_t tolerance)
	Clears the background, making it transparent.
int	tiny_image_zoom (TinyImage *image, float zoom_factor)
	Zooms in or out of the image by the specified zoom factor.
int	tiny_image_darken (TinyImage *image, uint32_t x, uint32_t y, uint32_t width, uint32_t height, float factor)
	Darkens a specified rectangular region of the image by the given factor.
int	tiny_image_lighten (TinyImage *image, uint32_t x, uint32_t y, uint32_t width, uint32_t height, float factor)
	Lightens a specified rectangular region of the image by the given factor.
int	tiny_image_gaussian_blur (TinyImage *image, float sigma)
	Applies a Gaussian blur effect to the image.
int	tiny_image_vignette (TinyImage *image, float radius, float strength, const uint8_t *color)
	Applies a vignette effect to the image.
int	tiny_image_color_overlay (TinyImage *image, const uint8_t *color, float opacity)
	Applies a color overlay to the image with the specified color and opacity.
int	tiny_image_color_overlay_rect (TinyImage *image, uint32_t x, uint32_t y, uint32_t width, uint32_t height, const uint8_t *color, float opacity)
	Applies a color overlay to a specified rectangular region of the image with the given color and opacity.
int	tiny_image_apply_matrix (TinyImage *image, const float *matrix)
	Applies a color matrix of the caller's own.
int	tiny_image_apply_lut (TinyImage *image, const uint8_t *lut)
	Applies a 256 entry table of the caller's own to every channel.
int	tiny_image_apply_luts (TinyImage *image, const uint8_t *red, const uint8_t *green, const uint8_t *blue)
	Applies one table per color channel.
int	tiny_image_curves (TinyImage *image, const uint8_t *x_points, const uint8_t *y_points, size_t num_points)
	Applies a tone curve through the caller's control points.
int	tiny_image_negate (TinyImage *image)
	Subtracts every color channel from full scale.
int	tiny_image_blackwhite (TinyImage *image)
	Replaces every color channel with the pixel's luminance, keeping the channel count.
int	tiny_image_colorize (TinyImage *image, const uint8_t *color, float strength)
	Mixes every pixel toward one color, keeping its luminance.
int	tiny_image_tint (TinyImage *image, const uint8_t *color, float strength)
	Adds a color cast without touching the luminance.
int	tiny_image_posterize (TinyImage *image, uint32_t levels)
	Rounds every channel to a number of evenly spaced levels.
int	tiny_image_threshold (TinyImage *image, uint8_t level)
	Drives every channel to nothing or to full scale.
int	tiny_image_solarize (TinyImage *image, uint8_t level)
	Inverts only the channels above a level.
int	tiny_image_duotone (TinyImage *image, const uint8_t *shadow, const uint8_t *highlight)
	Maps the tonal range between two colors.
int	tiny_image_split_tone (TinyImage *image, const uint8_t *shadow, const uint8_t *highlight, float balance)
	Tints the shadows and the highlights differently.
int	tiny_image_exposure (TinyImage *image, float stops)
	Scales every channel by a power of two.
int	tiny_image_fill_light (TinyImage *image, float amount)
	Lifts the shadows without moving the highlights.
int	tiny_image_temperature (TinyImage *image, float amount)
	Shifts the white point along the blue to amber axis.
int	tiny_image_white_balance (TinyImage *image, float temperature, float tint)
	Shifts the white point along both axes at once.
int	tiny_image_vibrance (TinyImage *image, float amount)
	Raises saturation, and least where it is already high.
int	tiny_image_levels (TinyImage *image, float in_black, float in_white, float gamma, float out_black, float out_white)
	Maps an input range onto an output range through a gamma.
int	tiny_image_levels_channel (TinyImage *image, uint8_t channel, float in_black, float in_white, float gamma, float out_black, float out_white)
	The same, on one channel.
int	tiny_image_color_balance (TinyImage *image, const float *shadows, const float *midtones, const float *highlights)
	Shifts the color of the shadows, midtones and highlights apart.
int	tiny_image_channel_mixer (TinyImage *image, const float *matrix)
	Rebuilds each output channel from a weighted sum of the inputs.
int	tiny_image_channel_gain (TinyImage *image, float red, float green, float blue)
	Scales each channel independently.
int	tiny_image_colorblind_simulate (TinyImage *image, TinyColorblindKind kind)
	Shows the image as a given color blindness would see it.
int	tiny_image_colorblind_assist (TinyImage *image, TinyColorblindKind kind)
	Moves the colors a given color blindness cannot separate apart.
int	tiny_image_preset (TinyImage *image, TinyImagePreset preset)
	Applies a named look.
int	tiny_image_unsharp_mask (TinyImage *image, float sigma, float amount, float threshold)
	Adds back a multiple of what a blur removed.
int	tiny_image_clarity (TinyImage *image, float amount)
	Raises local contrast, which is an unsharp mask at a large radius.
int	tiny_image_sobel (TinyImage *image)
	Replaces the image with its Sobel gradient magnitude.
int	tiny_image_emboss (TinyImage *image, float strength)
	Turns the image into a relief lit from the upper left.
int	tiny_image_pixelate (TinyImage *image, uint32_t size)
	Averages the image over square blocks.
int	tiny_image_pixelate_region (TinyImage *image, uint32_t x, uint32_t y, uint32_t width, uint32_t height, uint32_t size)
	The same, inside a rectangle.
int	tiny_image_despeckle (TinyImage *image)
	Replaces each pixel with the median of its 3x3 neighborhood.
int	tiny_image_dilate (TinyImage *image, uint32_t radius)
	Replaces each pixel with the brightest in a radius.
int	tiny_image_erode (TinyImage *image, uint32_t radius)
	Replaces each pixel with the darkest in a radius.
int	tiny_image_morphology_open (TinyImage *image, uint32_t radius)
	Erodes then dilates, which removes bright specks.
int	tiny_image_morphology_close (TinyImage *image, uint32_t radius)
	Dilates then erodes, which fills dark specks.
int	tiny_image_outline (TinyImage *image, uint32_t radius)
	The difference between a dilation and an erosion.
int	tiny_image_motion_blur (TinyImage *image, float length, float angle)
	Averages along a straight path.
int	tiny_image_radial_blur (TinyImage *image, float degrees)
	Averages along arcs about the center.
int	tiny_image_zoom_blur (TinyImage *image, float strength)
	Averages along rays from the center.
int	tiny_image_tilt_shift (TinyImage *image, float sigma, float band)
	Blurs away from a horizontal band left sharp.
int	tiny_image_blur_region (TinyImage *image, uint32_t x, uint32_t y, uint32_t width, uint32_t height, float sigma)
	Blurs inside a rectangle only.
int	tiny_image_drop_shadow (TinyImage *image, int32_t offset_x, int32_t offset_y, float sigma, const uint8_t *color)
	Grows the image and puts a blurred silhouette of it behind.
int	tiny_image_glow (TinyImage *image, float sigma, float strength)
	Adds a blurred copy of the image to itself, which is a bloom.
int	tiny_image_noise (TinyImage *image, float amount, int monochrome)
	Adds pseudorandom noise.
int	tiny_image_film_grain (TinyImage *image, float amount)
	Adds noise weighted toward the midtones, which is how film grains.
int	tiny_image_dither (TinyImage *image, uint32_t levels)
	Quantizes through an ordered threshold matrix.
int	tiny_image_halftone (TinyImage *image, uint32_t cell)
	Turns tone into dot area within a cell.
int	tiny_image_chromatic_aberration (TinyImage *image, float amount)
	Offsets the red and blue channels radially.
int	tiny_image_scanlines (TinyImage *image, uint32_t period, float strength)
	Darkens every nth row.
int	tiny_image_auto_brightness (TinyImage *image)
	Moves the mean luminance to the middle of the range.
int	tiny_image_auto_contrast (TinyImage *image)
	Stretches the luminance so that a small fraction clips at each end.
int	tiny_image_auto_color (TinyImage *image)
	Scales each channel so their means agree, which is a gray-world balance.
int	tiny_image_auto_levels (TinyImage *image)
	Stretches each channel to the full range independently.
int	tiny_image_auto_gamma (TinyImage *image)
	Applies the gamma that brings the mean luminance to mid gray.
int	tiny_image_improve (TinyImage *image)
	Applies the auto corrections a photograph usually wants together.
int	tiny_image_shadows_highlights (TinyImage *image, float shadows, float highlights)
	Recovers detail at both ends of the range.
int	tiny_image_dehaze (TinyImage *image, float strength)
	Removes a veiling haze by the dark-channel prior.
int	tiny_image_shear (TinyImage *image, float shear_x, float shear_y, const uint8_t *background)
	Slants the image along one or both axes.
int	tiny_image_rotate (TinyImage *image, float degrees, const uint8_t *background)
	Turns the image by any angle.
int	tiny_image_perspective (TinyImage *image, const float *quad, const uint8_t *background)
	Maps the image's four corners onto four arbitrary points.
int	tiny_image_arc (TinyImage *image, float degrees, const uint8_t *background)
	Bends the image along an arc.
int	tiny_image_barrel (TinyImage *image, float amount)
	Corrects or introduces lens distortion.
int	tiny_image_swirl (TinyImage *image, float degrees)
	Twists the image about its center, most at the center.
int	tiny_image_polar (TinyImage *image, int inverse)
	Maps between rectangular and polar coordinates.
int	tiny_image_corner_radius (TinyImage *image, uint32_t radius)
	Rounds the image's corners by clearing what falls outside them.
int	tiny_image_histogram (const TinyImage *image, uint8_t channel, uint32_t *bins)
	Counts how many pixels fall in each of 256 buckets.
int	tiny_image_dominant_color (const TinyImage *image, uint8_t *color)
	The color the most pixels are closest to.
int	tiny_image_palette (const TinyImage *image, uint32_t count, uint8_t *palette)
	The colors a palette of the given size would hold.
int	tiny_image_average_color (const TinyImage *image, uint8_t *color)
	The mean of every pixel, per channel.
int	tiny_image_phash (const TinyImage *image, uint64_t *hash)
	A 64 bit perceptual hash.
uint32_t	tiny_phash_distance (uint64_t first, uint64_t second)
	How many bits two perceptual hashes differ in.
int	tiny_image_focus (const TinyImage *image, TinyImageGravity gravity, float *x, float *y)
	Where the part of an image worth keeping is.
int	tiny_image_blur_faces (TinyImage *image, float sigma)
	Blurs whatever the detector finds and nothing else.
int	tiny_image_pixelate_faces (TinyImage *image, uint32_t size)
	Pixelates whatever the detector finds and nothing else.
int	tiny_image_set_exif (TinyImage *image, const char *exif_data, size_t exif_size)
	Sets the EXIF metadata for the image.
int	tiny_image_get_exif (const TinyImage *image, char **exif_data, size_t *exif_size)
	Retrieves the EXIF metadata from the image.
int	tiny_image_has_exif (const TinyImage *image)
	Checks if the image has EXIF metadata.
int	tiny_image_strip_exif (TinyImage *image)
	Strips the EXIF metadata from the image.
int	tiny_image_set_metadata (TinyImage *image, const char *key, const char *value)
	Sets a custom metadata key-value pair for the image.
int	tiny_image_get_metadata (const TinyImage *image, const char *key, char **value)
	Retrieves the value associated with a custom metadata key from the image.
int	tiny_image_has_metadata (const TinyImage *image, const char *key)
	Checks if the image has a specific custom metadata key.
int	tiny_image_remove_metadata (TinyImage *image, const char *key)
	Removes a specific custom metadata key-value pair from the image.
int	tiny_image_get_metadata_count (const TinyImage *image, size_t *count)
	Retrieves the count of custom metadata key-value pairs in the image.
int	tiny_image_to_rgb (TinyImage *image)
	Converts the image to RGB format.
int	tiny_image_to_rgba (TinyImage *image)
	Converts the image to RGBA format, adding an opaque alpha channel if there was none.
int	tiny_image_to_grayscale (TinyImage *image)
	Converts the image to grayscale.
int	tiny_image_convert_channels (TinyImage *image, uint8_t channels)
	Converts the image to a given channel count.
int	tiny_image_convert (TinyImage *image, TinyImageFormat format)
	Records the format the image should be written as, dropping anything that format cannot carry.
int	tiny_image_istransparent (const TinyImage *image)
	Checks if the image has an alpha channel (transparency).
int	tiny_image_set_transparent (TinyImage *image, int enable_transparency)
	Sets the transparency of the image.
TinyImageFormat	tiny_image_getformat (const TinyImage *image)
	Retrieves the format of the image.

Detailed Description

Image processing library utilities.

Author

Gregory Mitchell (me@gm.nosp@m.itch.nosp@m.215.x.nosp@m.yz)

Version

1.0.0

Date

2026-08-31

Copyright

Copyright (c) 2026

Macro Definition Documentation

TINYIMG_DISPLAY_MAX_DEPTH

#define TINYIMG_DISPLAY_MAX_DEPTH   8

How deep the transform stack goes.

TINYIMG_DISPLAY_MAX_POINTS

#define TINYIMG_DISPLAY_MAX_POINTS   256

How many polygon vertices one display list holds between every shape.

TINYIMG_DISPLAY_MAX_SHAPES

#define TINYIMG_DISPLAY_MAX_SHAPES   64

How many shapes one display list holds.

Typedef Documentation

TinyBlendMode

typedef enum TinyBlendMode TinyBlendMode

How a shape's color is combined with what is already there.

The separable blend modes from the CSS compositing specification, so a mode named here and the same mode named in a stylesheet produce the same pixels. Each is a function of one destination channel and one source channel; the modes that are not separable, and so cannot be, are out of scope.

TinyColorblindKind

typedef enum TinyColorblindKind TinyColorblindKind

The forms of color blindness the simulation and the assist cover.

The three dichromacies plus total loss. Simulated through the Brettel, Vienot and Mollon projection onto the surviving plane, which is the model the accessibility tooling in browsers uses.

TinyEffort

typedef enum TinyEffort TinyEffort

How much computation an operation may spend to do its best work.

A separate axis from quality. Quality says what the output should look like; this says how hard to work to get there, and the two are not the same dial: a bounded search at quality 80 produces an image at roughly quality 80, in a few more bytes, for a fraction of the CPU.

The distinction matters because the Workers Free plan allows 10 milliseconds of CPU per request and does not let a caller pay for more. A request that cannot fit as TINYIMG_EFFORT_FANCY may fit as TINYIMG_EFFORT_FAST, and a caller who would rather serve a slightly larger file than fail can say so.

Not every operation has both. An operation with nothing to trade ignores this and does the exact thing, which is why it is a hint about effort rather than a promise about output. Each one that honors it documents what it gives up and carries a measured floor in the tests. Nothing here degrades silently.

TinyFillRule

typedef enum TinyFillRule TinyFillRule

Which points a polygon fill considers inside.

The two rules agree on every polygon that does not cross itself, so a test written against a convex shape cannot tell them apart.

TinyImageFit

typedef enum TinyImageFit TinyImageFit

How an image is made to fit a target width and height.

A target rectangle and a source rectangle rarely share an aspect ratio, so every mode is two independent choices: what happens to the mismatch, and how far the scale is allowed to move. Reading the two columns is quicker than reading eleven paragraphs.

Mode	Mismatch	Scale
TINYIMG_FIT_CONTAIN	left alone, so one axis falls short	free
TINYIMG_FIT_SCALE_DOWN	left alone	never above 1
TINYIMG_FIT_SCALE_UP	left alone	never below 1
TINYIMG_FIT_PAD	padded to the target	free
TINYIMG_FIT_ASPECT_CONTAIN	padded to the target's ratio	fixed at 1
TINYIMG_FIT_COVER	cropped to the target	free
TINYIMG_FIT_CROP	cropped to the target	never above 1
TINYIMG_FIT_FILL	cropped to the target	never below 1
TINYIMG_FIT_ASPECT_COVER	cropped to the target's ratio	fixed at 1
TINYIMG_FIT_ASPECT_CROP	cropped to the target's extent	fixed at 1
TINYIMG_FIT_STRETCH	absorbed by distorting	free, per axis

A fixed scale means no resampling happens at all, so those three modes cost stride arithmetic and reach the output without touching a pixel value. Where a mode crops or pads, the gravity decides which part survives or where the image sits.

The four Cloudflare Images modes are TINYIMG_FIT_SCALE_DOWN, TINYIMG_FIT_CONTAIN, TINYIMG_FIT_COVER, TINYIMG_FIT_CROP and TINYIMG_FIT_PAD, with the same meanings.

TinyImageFormat

typedef enum TinyImageFormat TinyImageFormat

Image formats supported by TinyImage for conversion and saving.

This enumeration defines the different image formats that are supported by TinyImage for conversion and saving operations.

TinyImageGravity

typedef enum TinyImageGravity TinyImageGravity

Which part of an image a crop keeps, or where a pad puts it.

The nine fixed positions are arithmetic. The two computed ones read the image, and until the phase that implements them lands they fall back to TINYIMG_GRAVITY_CENTER rather than failing, which is also what they do when the detector finds nothing.

TinyImageMeta

typedef struct TinyImageMeta TinyImageMeta

Metadata carried alongside the pixels.

Opaque here; EXIF and key value entries are reached through the metadata region below.

TinyImagePixelType

typedef enum TinyImagePixelType TinyImagePixelType

What the channels of an image mean.

Derived from the channel count rather than stored, so it cannot disagree with the pixel data.

TinyImagePreset

typedef enum TinyImagePreset TinyImagePreset

The named looks, each a fixed stack of the adjustments above.

A preset is worth having because the stack collapses: every one of these is a matrix and a curve by the time it runs, whatever it was written as, so a preset costs the same single pass a brightness change does.

TinyShapeKind

typedef enum TinyShapeKind TinyShapeKind

The shapes a display list can hold.

Enumeration Type Documentation

TinyBlendMode

enum TinyBlendMode

How a shape's color is combined with what is already there.

The separable blend modes from the CSS compositing specification, so a mode named here and the same mode named in a stylesheet produce the same pixels. Each is a function of one destination channel and one source channel; the modes that are not separable, and so cannot be, are out of scope.

Enumerator
TINYIMG_BLEND_NORMAL	Source over destination, weighted by alpha. The default.
TINYIMG_BLEND_REPLACE	Source replaces destination, alpha included.
TINYIMG_BLEND_MULTIPLY	Product of the two, which always darkens.
TINYIMG_BLEND_SCREEN	Inverse of the product of the inverses, which always lightens.
TINYIMG_BLEND_OVERLAY	Multiply where the destination is dark, screen where it is light.
TINYIMG_BLEND_DARKEN	The darker of the two.
TINYIMG_BLEND_LIGHTEN	The lighter of the two.
TINYIMG_BLEND_DIFFERENCE	Absolute difference.
TINYIMG_BLEND_EXCLUSION	Sum less the product, which is difference without the sign.
TINYIMG_BLEND_HARD_LIGHT	Multiply where the source is dark, screen where it is light.
TINYIMG_BLEND_SOFT_LIGHT	Overlay with a softer curve, which does not clip.
TINYIMG_BLEND_ADD	Sum, clamped.
TINYIMG_BLEND_SUBTRACT	Destination less source, clamped.

TinyColorblindKind

enum TinyColorblindKind

The forms of color blindness the simulation and the assist cover.

The three dichromacies plus total loss. Simulated through the Brettel, Vienot and Mollon projection onto the surviving plane, which is the model the accessibility tooling in browsers uses.

Enumerator
TINYIMG_COLORBLIND_PROTANOPIA	No long-wavelength cone; red appears dark.
TINYIMG_COLORBLIND_DEUTERANOPIA	No medium-wavelength cone, and the most common form.
TINYIMG_COLORBLIND_TRITANOPIA	No short-wavelength cone; blue and yellow confuse.
TINYIMG_COLORBLIND_ACHROMATOPSIA	No color at all.

TinyDrawMode

enum TinyDrawMode

How a source image larger or smaller than its target is placed.

Enumerator
TINYIMG_DRAW_ONCE	Once, at the offset, clipped to the destination.
TINYIMG_DRAW_TILE	Repeated to cover the destination, starting from the offset.
TINYIMG_DRAW_CENTER	Once, centered in the destination, ignoring the offset.

TinyEffort

enum TinyEffort

How much computation an operation may spend to do its best work.

A separate axis from quality. Quality says what the output should look like; this says how hard to work to get there, and the two are not the same dial: a bounded search at quality 80 produces an image at roughly quality 80, in a few more bytes, for a fraction of the CPU.

The distinction matters because the Workers Free plan allows 10 milliseconds of CPU per request and does not let a caller pay for more. A request that cannot fit as TINYIMG_EFFORT_FANCY may fit as TINYIMG_EFFORT_FAST, and a caller who would rather serve a slightly larger file than fail can say so.

Not every operation has both. An operation with nothing to trade ignores this and does the exact thing, which is why it is a hint about effort rather than a promise about output. Each one that honors it documents what it gives up and carries a measured floor in the tests. Nothing here degrades silently.

Enumerator
TINYIMG_EFFORT_FANCY	Spend what it takes to do the best work available. The default, and what every operation did before this existed.
TINYIMG_EFFORT_FAST	Bound the search, take the cheaper kernel, stay inside a floor. What each operation actually does is in its own documentation. It is never "skip a step and hope": every fast path here is measured against the fancy one and its cost in decibels and in bytes is recorded.

TinyFillRule

enum TinyFillRule

Which points a polygon fill considers inside.

The two rules agree on every polygon that does not cross itself, so a test written against a convex shape cannot tell them apart.

Enumerator
TINYIMG_FILL_EVEN_ODD	Inside when a ray to the point crosses an odd number of edges. A self-crossing shape has holes where its lobes overlap.
TINYIMG_FILL_NONZERO	Inside when the signed crossings do not cancel. A self-crossing shape is solid, and the direction the edges are wound in decides whether an inner loop is a hole.

TinyImageFit

enum TinyImageFit

How an image is made to fit a target width and height.

A target rectangle and a source rectangle rarely share an aspect ratio, so every mode is two independent choices: what happens to the mismatch, and how far the scale is allowed to move. Reading the two columns is quicker than reading eleven paragraphs.

Mode	Mismatch	Scale
TINYIMG_FIT_CONTAIN	left alone, so one axis falls short	free
TINYIMG_FIT_SCALE_DOWN	left alone	never above 1
TINYIMG_FIT_SCALE_UP	left alone	never below 1
TINYIMG_FIT_PAD	padded to the target	free
TINYIMG_FIT_ASPECT_CONTAIN	padded to the target's ratio	fixed at 1
TINYIMG_FIT_COVER	cropped to the target	free
TINYIMG_FIT_CROP	cropped to the target	never above 1
TINYIMG_FIT_FILL	cropped to the target	never below 1
TINYIMG_FIT_ASPECT_COVER	cropped to the target's ratio	fixed at 1
TINYIMG_FIT_ASPECT_CROP	cropped to the target's extent	fixed at 1
TINYIMG_FIT_STRETCH	absorbed by distorting	free, per axis

A fixed scale means no resampling happens at all, so those three modes cost stride arithmetic and reach the output without touching a pixel value. Where a mode crops or pads, the gravity decides which part survives or where the image sits.

The four Cloudflare Images modes are TINYIMG_FIT_SCALE_DOWN, TINYIMG_FIT_CONTAIN, TINYIMG_FIT_COVER, TINYIMG_FIT_CROP and TINYIMG_FIT_PAD, with the same meanings.

Enumerator
TINYIMG_FIT_SCALE_DOWN	Fits inside the target without cropping or padding, and never enlarges. One axis reaches the target and the other falls short, so the output is usually smaller than what was asked for. A source already inside the target comes through untouched.
TINYIMG_FIT_CONTAIN	Fits inside the target without cropping or padding. Enlarges a source smaller than the target, which TINYIMG_FIT_SCALE_DOWN does not.
TINYIMG_FIT_COVER	Fills the target exactly, cropping whichever axis overflows. The output is always the target extent, and part of the source is lost.
TINYIMG_FIT_CROP	Fills the target exactly, cropping the overflow, and never enlarges. A source too small to cover the target produces a smaller output rather than an enlarged one, which is the difference from TINYIMG_FIT_COVER.
TINYIMG_FIT_ASPECT_CROP	Crops to the target's extent without resampling. Pixels keep their original scale, so this is a crop and nothing else. A source smaller than the target crops to what there is.
TINYIMG_FIT_ASPECT_CONTAIN	Pads to the target's aspect ratio without resampling. Keeps every source pixel at its original scale and adds background on the axis that falls short, so the output has the target's ratio but not necessarily its extent.
TINYIMG_FIT_ASPECT_COVER	Crops to the target's aspect ratio without resampling. Keeps as much of the source as the ratio allows, at its original scale, which is the largest crop of that shape the source can give.
TINYIMG_FIT_PAD	Fits inside the target, then pads the shortfall with the background. The output is always the target extent and no part of the source is lost.
TINYIMG_FIT_STRETCH	Scales each axis independently to the target, distorting the image. The only mode that does not preserve the aspect ratio.
TINYIMG_FIT_FILL	Fills the target exactly, cropping the overflow, and never shrinks. The mirror of TINYIMG_FIT_CROP: a source larger than the target is cropped at its original scale rather than reduced.
TINYIMG_FIT_SCALE_UP	Fits inside the target without cropping or padding, and never shrinks. The mirror of TINYIMG_FIT_SCALE_DOWN.

TinyImageFormat

enum TinyImageFormat

Image formats supported by TinyImage for conversion and saving.

This enumeration defines the different image formats that are supported by TinyImage for conversion and saving operations.

TinyImageGravity

enum TinyImageGravity

Which part of an image a crop keeps, or where a pad puts it.

The nine fixed positions are arithmetic. The two computed ones read the image, and until the phase that implements them lands they fall back to TINYIMG_GRAVITY_CENTER rather than failing, which is also what they do when the detector finds nothing.

Enumerator
TINYIMG_GRAVITY_CENTER	The middle, and the default.
TINYIMG_GRAVITY_NORTH	The top edge.
TINYIMG_GRAVITY_SOUTH	The bottom edge.
TINYIMG_GRAVITY_WEST	The left edge.
TINYIMG_GRAVITY_EAST	The right edge.
TINYIMG_GRAVITY_NORTH_WEST	The top left corner.
TINYIMG_GRAVITY_NORTH_EAST	The top right corner.
TINYIMG_GRAVITY_SOUTH_WEST	The bottom left corner.
TINYIMG_GRAVITY_SOUTH_EAST	The bottom right corner.
TINYIMG_GRAVITY_AUTO	Wherever the detail is, measured from the image.
TINYIMG_GRAVITY_FACE	Wherever the faces are.

TinyImagePixelType

enum TinyImagePixelType

What the channels of an image mean.

Derived from the channel count rather than stored, so it cannot disagree with the pixel data.

Enumerator
TINYIMG_PIXEL_GRAY	One channel, luminance.
TINYIMG_PIXEL_GRAY_ALPHA	Two channels, luminance then alpha.
TINYIMG_PIXEL_RGB	Three channels, red then green then blue.
TINYIMG_PIXEL_RGBA	Four channels, red then green then blue then alpha.

TinyImagePreset

enum TinyImagePreset

The named looks, each a fixed stack of the adjustments above.

A preset is worth having because the stack collapses: every one of these is a matrix and a curve by the time it runs, whatever it was written as, so a preset costs the same single pass a brightness change does.

Enumerator
TINYIMG_PRESET_NOIR	High contrast monochrome.
TINYIMG_PRESET_CHROME	Monochrome with lifted blacks and a cool cast.
TINYIMG_PRESET_MONO	Plain monochrome at the original contrast.
TINYIMG_PRESET_FADE	Lifted blacks, pulled highlights, reduced saturation.
TINYIMG_PRESET_VIVID	Raised saturation and contrast.
TINYIMG_PRESET_WARM	Shifted toward amber.
TINYIMG_PRESET_COOL	Shifted toward blue.
TINYIMG_PRESET_INSTANT	Warm, low contrast and slightly faded, like instant film.
TINYIMG_PRESET_TONAL	Flattened contrast with the midtones held.

TinyShapeKind

enum TinyShapeKind

The shapes a display list can hold.

Enumerator
TINYIMG_SHAPE_NONE	An unused slot.
TINYIMG_SHAPE_RECT	A filled rectangle.
TINYIMG_SHAPE_ROUND_RECT	A filled rectangle with rounded corners.
TINYIMG_SHAPE_ELLIPSE	A filled ellipse.
TINYIMG_SHAPE_LINE	A line of some thickness.
TINYIMG_SHAPE_POLYGON	A filled polygon.

Function Documentation

tiny_display_blend()

int tiny_display_blend	(	TinyDisplayList *	list,
		TinyBlendMode	blend )

Sets the blend mode the next shapes are added with.

Parameters

list	The list.
blend	The mode.

Returns

int TINYIMG_OK or TINYIMG_ERR_NULL.

tiny_display_bounds()

int tiny_display_bounds	(	const TinyDisplayList *	list,
		int32_t *	x,
		int32_t *	y,
		uint32_t *	width,
		uint32_t *	height )

The rectangle every shape in the list falls inside.

Parameters

list	The list.
x	Receives the left edge.
y	Receives the top edge.
width	Receives the width, zero when the list is empty.
height	Receives the height.

Returns

int TINYIMG_OK or TINYIMG_ERR_NULL.

tiny_display_covered()

uint32_t tiny_display_covered

(

const TinyDisplayList *

list

)

How many shapes the last render dropped as covered by a later opaque one.

Parameters

list

The list.

Returns

uint32_t The count, or 0 when the list is NULL.

tiny_display_culled()

uint32_t tiny_display_culled

(

const TinyDisplayList *

list

)

How many shapes the last render dropped as outside the target.

Parameters

list

The list.

Returns

uint32_t The count, or 0 when the list is NULL.

tiny_display_ellipse()

int tiny_display_ellipse	(	TinyDisplayList *	list,
		float	center_x,
		float	center_y,
		float	radius_x,
		float	radius_y,
		const uint8_t *	color )

Adds an ellipse.

Parameters

list	The list.
center_x	Center, before the transform.
center_y	Center.
radius_x	Horizontal semi-axis.
radius_y	Vertical semi-axis.
color	As many channels as the target will have.

Returns

int TINYIMG_OK, TINYIMG_ERR_NULL, or TINYIMG_ERR_BOUNDS.

tiny_display_init()

int tiny_display_init

(

TinyDisplayList *

list

)

Empties a display list and resets its transform to the identity.

Parameters

list

The list.

Returns

int TINYIMG_OK or TINYIMG_ERR_NULL.

tiny_display_line()

int tiny_display_line	(	TinyDisplayList *	list,
		float	x1,
		float	y1,
		float	x2,
		float	y2,
		float	thickness,
		const uint8_t *	color )

Adds a line.

Parameters

list	The list.
x1	Start, before the transform.
y1	Start.
x2	End.
y2	End.
thickness	Width in pixels, before the transform.
color	As many channels as the target will have.

Returns

int TINYIMG_OK, TINYIMG_ERR_NULL, or TINYIMG_ERR_BOUNDS.

tiny_display_polygon()

int tiny_display_polygon	(	TinyDisplayList *	list,
		const float *	x_points,
		const float *	y_points,
		size_t	num_points,
		const uint8_t *	color,
		TinyFillRule	rule )

Adds a polygon.

Parameters

list	The list.
x_points	Vertex x coordinates, before the transform.
y_points	Vertex y coordinates.
num_points	How many vertices.
color	As many channels as the target will have.
rule	Which points count as inside.

Returns

int TINYIMG_OK, TINYIMG_ERR_NULL, TINYIMG_ERR_RANGE below three vertices, or TINYIMG_ERR_BOUNDS when the list is full.

tiny_display_rect()

int tiny_display_rect	(	TinyDisplayList *	list,
		float	x,
		float	y,
		float	width,
		float	height,
		const uint8_t *	color )

Adds a rectangle.

Parameters

list	The list.
x	Left edge, before the transform.
y	Top edge.
width	Width.
height	Height.
color	As many channels as the target will have.

Returns

int TINYIMG_OK, TINYIMG_ERR_NULL, or TINYIMG_ERR_BOUNDS when the list is full.

tiny_display_render()

int tiny_display_render	(	TinyDisplayList *	list,
		TinyImage *	image )

Draws every shape onto an image, in one pass over the list.

Parameters

list	The list, whose culled and covered counts are updated.
image	The image to draw on.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_display_restore()

int tiny_display_restore

(

TinyDisplayList *

list

)

Pops the transform saved last.

Parameters

list

The list.

Returns

int TINYIMG_OK, TINYIMG_ERR_NULL, or TINYIMG_ERR_BOUNDS when nothing is saved.

tiny_display_rotate()

int tiny_display_rotate	(	TinyDisplayList *	list,
		float	degrees )

Turns the current transform.

Parameters

list	The list.
degrees	Clockwise, any angle.

Returns

int TINYIMG_OK or TINYIMG_ERR_NULL.

tiny_display_round_rect()

int tiny_display_round_rect	(	TinyDisplayList *	list,
		float	x,
		float	y,
		float	width,
		float	height,
		float	radius,
		const uint8_t *	color )

Adds a rectangle with rounded corners.

Parameters

list	The list.
x	Left edge, before the transform.
y	Top edge.
width	Width.
height	Height.
radius	Corner radius.
color	As many channels as the target will have.

Returns

int TINYIMG_OK, TINYIMG_ERR_NULL, or TINYIMG_ERR_BOUNDS.

tiny_display_save()

int tiny_display_save

(

TinyDisplayList *

list

)

Pushes the current transform.

Parameters

list

The list.

Returns

int TINYIMG_OK, TINYIMG_ERR_NULL, or TINYIMG_ERR_BOUNDS when the stack is full.

tiny_display_scale()

int tiny_display_scale	(	TinyDisplayList *	list,
		float	x,
		float	y )

Scales the current transform.

Parameters

list	The list.
x	Factor along x.
y	Factor along y.

Returns

int TINYIMG_OK or TINYIMG_ERR_NULL.

tiny_display_set_transform()

int tiny_display_set_transform	(	TinyDisplayList *	list,
		const float *	matrix )

Sets the current transform outright.

Parameters

list	The list.
matrix	Six numbers: a, b, c, d, e, f, mapping (x, y) to (a x + c y + e, b x + d y + f).

Returns

int TINYIMG_OK or TINYIMG_ERR_NULL.

tiny_display_sizeof()

uint32_t tiny_display_sizeof

(

void

)

Size of a TinyDisplayList, for a host allocating one.

Returns

uint32_t sizeof(TinyDisplayList).

tiny_display_translate()

int tiny_display_translate	(	TinyDisplayList *	list,
		float	x,
		float	y )

Moves the current transform.

Parameters

list	The list.
x	How far along x.
y	How far along y.

Returns

int TINYIMG_OK or TINYIMG_ERR_NULL.

tiny_format_extension()

const char * tiny_format_extension

(

TinyImageFormat

format

)

Retrieves the conventional file extension of a format, leading dot included.

Parameters

format

The format.

Returns

const char* A NUL terminated extension, or "" for an unknown format.

tiny_format_name()

const char * tiny_format_name

(

TinyImageFormat

format

)

Retrieves the short name of a format, such as "png" or "jpeg".

Parameters

format

The format.

Returns

const char* A NUL terminated ASCII name, or "unknown".

tiny_format_sniff()

TinyImageFormat tiny_format_sniff	(	const uint8_t *	buffer,
		size_t	buffer_size )

Identifies a format from a buffer's magic bytes.

Recognizes more formats than the library can decode, so a caller can tell an unsupported format apart from an unrecognizable one.

Parameters

buffer	The bytes.
buffer_size	Number of bytes. Fewer than 12 limits what can be identified.

Returns

TinyImageFormat The format, or TINYIMG_FORMAT_UNKNOWN.

tiny_image_apply_lut()

int tiny_image_apply_lut	(	TinyImage *	image,
		const uint8_t *	lut )

Applies a 256 entry table of the caller's own to every channel.

Parameters

image	The image to change.
lut	The table.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_apply_luts()

int tiny_image_apply_luts	(	TinyImage *	image,
		const uint8_t *	red,
		const uint8_t *	green,
		const uint8_t *	blue )

Applies one table per color channel.

Parameters

image	The image to change.
red	The red channel's table, or NULL to leave it alone.
green	The green channel's table, or NULL.
blue	The blue channel's table, or NULL.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_apply_matrix()

int tiny_image_apply_matrix	(	TinyImage *	image,
		const float *	matrix )

Applies a color matrix of the caller's own.

The escape hatch under every named adjustment here. It composes with them, so a caller mixing its own matrix with a saturation change still pays for one pass.

Parameters

image	The image to change.
matrix	Row major 3x4 applied to RGB in the 0..255 range: three channel weights and a constant per row.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_apply_sepia()

int tiny_image_apply_sepia

(

TinyImage *

image

)

Applies a sepia tone effect to the image.

The sepia effect gives the image a warm, brownish tone, reminiscent of old photographs. This function modifies the pixel values of the image to achieve the sepia effect.

Parameters

image

Pointer to the TinyImage structure to be modified with the sepia effect.

Returns

int 0 on success, non-zero on failure (e.g., if the image is NULL).

tiny_image_arc()

int tiny_image_arc	(	TinyImage *	image,
		float	degrees,
		const uint8_t *	background )

Bends the image along an arc.

Parameters

image	The image, replaced by the result.
degrees	How far around; positive bows the top upward.
background	What the uncovered pixels are filled with, or NULL.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_auto_brightness()

int tiny_image_auto_brightness

(

TinyImage *

image

)

Moves the mean luminance to the middle of the range.

Parameters

image

The image to change.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_auto_color()

int tiny_image_auto_color

(

TinyImage *

image

)

Scales each channel so their means agree, which is a gray-world balance.

Parameters

image

The image to change.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_auto_contrast()

int tiny_image_auto_contrast

(

TinyImage *

image

)

Stretches the luminance so that a small fraction clips at each end.

Parameters

image

The image to change.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_auto_gamma()

int tiny_image_auto_gamma

(

TinyImage *

image

)

Applies the gamma that brings the mean luminance to mid gray.

Parameters

image

The image to change.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_auto_levels()

int tiny_image_auto_levels

(

TinyImage *

image

)

Stretches each channel to the full range independently.

Unlike tiny_image_auto_contrast this changes the color balance as well, because a channel with a narrow range is stretched further than one with a wide one.

Parameters

image

The image to change.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_average_color()

int tiny_image_average_color	(	const TinyImage *	image,
		uint8_t *	color )

The mean of every pixel, per channel.

Parameters

image	The image to read.
color	Receives as many channels as the image has.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_barrel()

int tiny_image_barrel	(	TinyImage *	image,
		float	amount )

Corrects or introduces lens distortion.

Parameters

image	The image to change.
amount	Positive corrects a barrel and so introduces a pincushion; negative does the reverse. 0 changes nothing.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_blackwhite()

int tiny_image_blackwhite

(

TinyImage *

image

)

Replaces every color channel with the pixel's luminance, keeping the channel count.

Unlike tiny_image_to_grayscale, which drops the channels, this leaves an RGB image RGB so that a later colorize or duotone has three channels to work with.

Parameters

image

The image to change.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_blur()

int tiny_image_blur	(	TinyImage *	image,
		float	radius )

Applies a blur effect to the image.

Parameters

image	Pointer to the TinyImage structure to be blurred.
radius	The radius of the blur effect. Must be a positive integer.

Returns

int 0 on success, non-zero on failure (e.g., if the image is NULL or if the radius is invalid).

tiny_image_blur_faces()

int tiny_image_blur_faces	(	TinyImage *	image,
		float	sigma )

Blurs whatever the detector finds and nothing else.

A no-op when no cascade is loaded or no face is found, rather than a blurred image: an anonymizer that blurs the whole photograph when it fails is worse than one that does nothing, because the failure is invisible in the output of the first and obvious in the second.

Parameters

image	The image to change.
sigma	Blur radius, in pixels of the image. Zero reads as a twelfth of the face's width, which stays proportionate across sizes.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_blur_region()

int tiny_image_blur_region	(	TinyImage *	image,
		uint32_t	x,
		uint32_t	y,
		uint32_t	width,
		uint32_t	height,
		float	sigma )

Blurs inside a rectangle only.

Parameters

image	The image to change.
x	Left edge.
y	Top edge.
width	Width; zero means to the right edge.
height	Height; zero means to the bottom edge.
sigma	The blur's standard deviation.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_border()

int tiny_image_border	(	TinyImage *	image,
		uint32_t	border_width,
		const uint8_t *	pixel )

Draws a border inside the image's edges.

Parameters

image	The image to draw on.
border_width	How thick, in pixels. Zero draws nothing.
pixel	As many channels as the image has.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_brightness()

int tiny_image_brightness	(	TinyImage *	image,
		float	factor )

Adjusts the brightness of the image.

Parameters

image	Pointer to the TinyImage structure whose brightness is to be adjusted.
factor	The factor by which to adjust the brightness. A value of 1.0 means no change, less than 1.0 darkens the image, and greater than 1.0 brightens the image.

Returns

int 0 on success, non-zero on failure (e.g., if the image is NULL or if the factor is invalid).

tiny_image_channel_gain()

int tiny_image_channel_gain	(	TinyImage *	image,
		float	red,
		float	green,
		float	blue )

Scales each channel independently.

Parameters

image	The image to change.
red	Factor for red.
green	Factor for green.
blue	Factor for blue.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_channel_mixer()

int tiny_image_channel_mixer	(	TinyImage *	image,
		const float *	matrix )

Rebuilds each output channel from a weighted sum of the inputs.

Parameters

image	The image to change.
matrix	Nine weights, row major; the identity changes nothing.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_chromatic_aberration()

int tiny_image_chromatic_aberration	(	TinyImage *	image,
		float	amount )

Offsets the red and blue channels radially.

Parameters

image	The image to change.
amount	Pixels of separation at the corner.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_clarity()

int tiny_image_clarity	(	TinyImage *	image,
		float	amount )

Raises local contrast, which is an unsharp mask at a large radius.

Parameters

image	The image to change.
amount	0 changes nothing.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_color_balance()

int tiny_image_color_balance	(	TinyImage *	image,
		const float *	shadows,
		const float *	midtones,
		const float *	highlights )

Shifts the color of the shadows, midtones and highlights apart.

Parameters

image	The image to change.
shadows	Three shifts, -1 through 1, for the dark end.
midtones	Three shifts for the middle.
highlights	Three shifts for the light end.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_color_overlay()

int tiny_image_color_overlay	(	TinyImage *	image,
		const uint8_t *	color,
		float	opacity )

Applies a color overlay to the image with the specified color and opacity.

This function overlays a solid color onto the entire image, blending it with the original pixel values based on the specified opacity. The color is provided as an array of uint8_t values, and the opacity is a float value between 0.0 (fully transparent) and 1.0 (fully opaque).

Parameters

image	Pointer to the TinyImage structure to be modified with the color overlay.
color	Pointer to a uint8_t array specifying the color to be used for the overlay. The size of the array should match the number of channels in the image type (e.g., 3 for RGB, 4 for RGBA).
opacity	The opacity of the overlay, where 0.0 means fully transparent and 1.0 means fully opaque. Must be a float value between 0.0 and 1.0.

Returns

int 0 on success, non-zero on failure (e.g., if the image is NULL or if parameters are invalid).

tiny_image_color_overlay_rect()

int tiny_image_color_overlay_rect	(	TinyImage *	image,
		uint32_t	x,
		uint32_t	y,
		uint32_t	width,
		uint32_t	height,
		const uint8_t *	color,
		float	opacity )

Applies a color overlay to a specified rectangular region of the image with the given color and opacity.

This function overlays a solid color onto a specified rectangular region of the image, blending it with the original pixel values based on the specified opacity. The rectangle is defined by its top-left corner (x, y) and its width and height. The color is provided as an array of uint8_t values, and the opacity is a float value between 0.0 (fully transparent) and 1.0 (fully opaque).

Parameters

image	Pointer to the TinyImage structure to be modified with the color overlay.
x	The x-coordinate of the top-left corner of the rectangle (0-based index).
y	The y-coordinate of the top-left corner of the rectangle (0-based index).
width	The width of the rectangle in pixels.
height	The height of the rectangle in pixels.
color	Pointer to a uint8_t array specifying the color to be used for the overlay. The size of the array should match the number of channels in the image type (e.g., 3 for RGB, 4 for RGBA).
opacity	The opacity of the overlay, where 0.0 means fully transparent and 1.0 means fully opaque. Must be a float value between 0.0 and 1.0.

Returns

int 0 on success, non-zero on failure (e.g., if coordinates are out of bounds or if parameters are invalid).

tiny_image_colorblind_assist()

int tiny_image_colorblind_assist	(	TinyImage *	image,
		TinyColorblindKind	kind )

Moves the colors a given color blindness cannot separate apart.

The error the simulation discards, added back along the axes that form can still see. The result is not the original colors and is not meant to be; it is an image whose distinctions survive the viewer's own projection.

Parameters

image	The image to change.
kind	Which form.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_colorblind_simulate()

int tiny_image_colorblind_simulate	(	TinyImage *	image,
		TinyColorblindKind	kind )

Shows the image as a given color blindness would see it.

Parameters

image	The image to change.
kind	Which form.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_colorize()

int tiny_image_colorize	(	TinyImage *	image,
		const uint8_t *	color,
		float	strength )

Mixes every pixel toward one color, keeping its luminance.

Parameters

image	The image to change.
color	The target color, three channels.
strength	0 changes nothing, 1 replaces the hue entirely.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_composite()

int tiny_image_composite	(	TinyImage *	dest_image,
		const TinyImage *	src_image,
		TinyBlendMode	blend )

Composites one image over another in place, Porter-Duff source-over.

The two must have the same extent. Unlike tiny_image_draw_image this writes the composited alpha as well, so the result is what a stack of layers means rather than what an opaque backdrop would have shown.

Parameters

dest_image	The lower layer, replaced by the result.
src_image	The upper layer.
blend	How the colors meet.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE when the extents differ, or a negative TinyImageError.

tiny_image_contrast()

int tiny_image_contrast	(	TinyImage *	image,
		float	factor )

Adjusts the contrast of the image.

Parameters

image	Pointer to the TinyImage structure whose contrast is to be adjusted.
factor	The factor by which to adjust the contrast. A value of 1.0 means no change, less than 1.0 decreases contrast, and greater than 1.0 increases contrast.

Returns

int 0 on success, non-zero on failure (e.g., if the image is NULL or if the factor is invalid).

tiny_image_convert()

int tiny_image_convert	(	TinyImage *	image,
		TinyImageFormat	format )

Records the format the image should be written as, dropping anything that format cannot carry.

No pixels are re-encoded here; tiny_image_encode does that. Asking for JPEG flattens the alpha channel, because JPEG has nowhere to put it, and every other format keeps the pixels as they are.

Parameters

image	Pointer to the TinyImage structure to convert.
format	The format to convert the image to (e.g., TINYIMG_FORMAT_PNG, TINYIMG_FORMAT_JPEG).

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE for an unknown format, or a negative TinyImageError.

tiny_image_convert_channels()

int tiny_image_convert_channels	(	TinyImage *	image,
		uint8_t	channels )

Converts the image to a given channel count.

Widening allocates; narrowing rewrites in place, so dropping a channel never needs room for two copies of a large image. Dropping alpha discards it rather than compositing; tiny_image_set_transparent is the call that composites onto a background.

Parameters

image	Pointer to the TinyImage structure to convert.
channels	Target channels per pixel, 1 through 4.

Returns

int TINYIMG_OK, TINYIMG_ERR_NULL, TINYIMG_ERR_RANGE for a channel count outside 1 through 4, or TINYIMG_ERR_MEMORY.

tiny_image_corner_radius()

int tiny_image_corner_radius	(	TinyImage *	image,
		uint32_t	radius )

Rounds the image's corners by clearing what falls outside them.

Parameters

image	The image to change. Gains an alpha channel if it has none.
radius	Corner radius in pixels.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_create()

int tiny_image_create	(	TinyImage *	image,
		uint32_t	width,
		uint32_t	height,
		uint8_t	channels )

Creates a new image with the specified width, height and channel count.

The pixel data is zeroed, which for an image with alpha means fully transparent and for one without means black.

Parameters

image	Pointer to a TinyImage structure where the new image will be stored.
width	The width of the new image in pixels.
height	The height of the new image in pixels.
channels	Channels per pixel, 1 through 4.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE for a zero dimension or channel count, TINYIMG_ERR_TOO_LARGE past TINYIMG_MAX_PIXELS or TINYIMG_MAX_IMAGE_BYTES, or TINYIMG_ERR_MEMORY.

tiny_image_crop()

int tiny_image_crop	(	TinyImage *	image,
		uint32_t	x,
		uint32_t	y,
		uint32_t	crop_width,
		uint32_t	crop_height )

Crops an image to the specified rectangle defined by the top-left corner (x, y) and the desired width and height.

A rectangle reaching past the right or bottom edge is clipped to it, so asking for more than there is gives what there is. An origin outside the image is an error rather than an empty result.

Parameters

image	Pointer to the TinyImage structure to be cropped.
x	The x-coordinate of the top-left corner of the cropping rectangle.
y	The y-coordinate of the top-left corner of the cropping rectangle.
crop_width	The width in pixels. Zero runs to the right edge.
crop_height	The height in pixels. Zero runs to the bottom edge.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE when the origin is outside the image, or TINYIMG_ERR_MEMORY.

tiny_image_crop_circle()

int tiny_image_crop_circle	(	TinyImage *	image,
		uint32_t	center_x,
		uint32_t	center_y,
		uint32_t	radius )

Crops an image to a circular region defined by the center (center_x, center_y) and the specified radius.

The function creates a circular mask and retains only the pixels within the circle, discarding the rest. The cropped image will replace the original image in the TinyImage structure, and the original pixel data will be freed.

Parameters

image	Pointer to the TinyImage structure to be cropped.
center_x	The x-coordinate of the center of the circular cropping region.
center_y	The y-coordinate of the center of the circular cropping region.
radius	The radius of the circular cropping region in pixels.

Returns

int 0 on success, non-zero on failure (e.g., if memory allocation fails or if the circular region exceeds image bounds).

tiny_image_crop_ellipse()

int tiny_image_crop_ellipse	(	TinyImage *	image,
		uint32_t	center_x,
		uint32_t	center_y,
		uint32_t	radius_x,
		uint32_t	radius_y )

Crops an image to an elliptical region defined by the center (center_x, center_y) and the specified radii along the x and y axes.

The function creates an elliptical mask and retains only the pixels within the ellipse, discarding the rest. The cropped image will replace the original image in the TinyImage structure, and the original pixel data will be freed.

Parameters

image	Pointer to the TinyImage structure to be cropped.
center_x	The x-coordinate of the center of the elliptical cropping region.
center_y	The y-coordinate of the center of the elliptical cropping region.
radius_x	The radius of the ellipse along the x-axis in pixels.
radius_y	The radius of the ellipse along the y-axis in pixels.

Returns

int 0 on success, non-zero on failure (e.g., if memory allocation fails or if the elliptical region exceeds image bounds).

tiny_image_crop_polygon()

int tiny_image_crop_polygon	(	TinyImage *	image,
		const uint32_t *	x_points,
		const uint32_t *	y_points,
		size_t	num_points )

Crops an image to a polygonal region defined by a series of points (x_points, y_points).

The function creates a polygonal mask based on the provided vertices and retains only the pixels within the polygon, discarding the rest. The cropped image will replace the original image in the TinyImage structure, and the original pixel data will be freed.

Parameters

image	Pointer to the TinyImage structure to be cropped.
x_points	Pointer to an array of x-coordinates for the polygon's vertices (0-based indices).
y_points	Pointer to an array of y-coordinates for the polygon's vertices (0-based indices).
num_points	The number of points (vertices) in the polygon. This should match the lengths of the x_points and y_points arrays.

Returns

int 0 on success, non-zero on failure (e.g., if memory allocation fails, if num_points is less than 3, or if the polygon exceeds image bounds).

tiny_image_curves()

int tiny_image_curves	(	TinyImage *	image,
		const uint8_t *	x_points,
		const uint8_t *	y_points,
		size_t	num_points )

Applies a tone curve through the caller's control points.

The points are interpolated monotonically, so a curve through rising control points never dips between them; a cubic spline through the same points does, and the dip shows as a band in a gradient.

Parameters

image	The image to change.
x_points	Input levels, 0 through 255, strictly increasing.
y_points	Output levels, 0 through 255.
num_points	How many points; at least two.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE when the inputs do not increase, or a negative TinyImageError.

tiny_image_darken()

int tiny_image_darken	(	TinyImage *	image,
		uint32_t	x,
		uint32_t	y,
		uint32_t	width,
		uint32_t	height,
		float	factor )

Darkens a specified rectangular region of the image by the given factor.

This function reduces the brightness of the pixels within the specified rectangle, making them darker. The darkening effect is controlled by the factor parameter, where a value less than 1.0 will darken the pixels, and a value greater than 1.0 will have no effect (as it would brighten instead).

Parameters

image	Pointer to the TinyImage structure to be modified.
x	The x-coordinate of the top-left corner of the rectangle (0-based index).
y	The y-coordinate of the top-left corner of the rectangle (0-based index).
width	The width of the rectangle in pixels.
height	The height of the rectangle in pixels.
factor	The factor by which to darken the pixels. Must be a float value between 0.0 and 1.0, where lower values result in darker pixels.

Returns

int 0 on success, non-zero on failure (e.g., if coordinates are out of bounds or if the image is NULL).

tiny_image_decode()

int tiny_image_decode	(	TinyImage *	image,
		const uint8_t *	buffer,
		size_t	buffer_size,
		const TinyDecodeOpts *	opts )

Loads an image with full control over region, scale and channel count.

The primitive the other three loaders are written in terms of.

Parameters

image	Pointer to a TinyImage structure where the loaded image will be stored.
buffer	A pointer to the buffer containing the image data.
buffer_size	The size of the buffer in bytes.
opts	Region, scale and channel count. NULL decodes everything.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_dehaze()

int tiny_image_dehaze	(	TinyImage *	image,
		float	strength )

Removes a veiling haze by the dark-channel prior.

Parameters

image	The image to change.
strength	How much to remove, 0 through 1.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_despeckle()

int tiny_image_despeckle

(

TinyImage *

image

)

Replaces each pixel with the median of its 3x3 neighborhood.

Parameters

image

The image to change.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_destroy()

int tiny_image_destroy

(

TinyImage *

image

)

Destroys an image, freeing its associated memory.

Safe to call on a zeroed structure and safe to call twice.

Parameters

image

Pointer to the TinyImage structure to be destroyed.

Returns

int TINYIMG_OK, or TINYIMG_ERR_NULL if the image is NULL.

tiny_image_dilate()

int tiny_image_dilate	(	TinyImage *	image,
		uint32_t	radius )

Replaces each pixel with the brightest in a radius.

Parameters

image	The image to change.
radius	Pixels either side.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_dither()

int tiny_image_dither	(	TinyImage *	image,
		uint32_t	levels )

Quantizes through an ordered threshold matrix.

Parameters

image	The image to change.
levels	How many output levels per channel.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_dominant_color()

int tiny_image_dominant_color	(	const TinyImage *	image,
		uint8_t *	color )

The color the most pixels are closest to.

Found by clustering rather than by the most common exact value, which on a photograph is almost always a color that appears a handful of times.

Parameters

image	The image to read.
color	Receives as many channels as the image has.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_dpr()

int tiny_image_dpr	(	TinyImage *	image,
		float	dpr )

Scales an image by a device pixel ratio.

The same resample tiny_image_zoom performs, named for the request parameter it serves: a ratio of 2 asks for twice the pixels in each axis so a display with two device pixels per CSS pixel has one each.

Parameters

image	Pointer to the TinyImage structure to be scaled.
dpr	The ratio. Must be greater than zero.

Returns

int TINYIMG_OK, TINYIMG_ERR_NULL, TINYIMG_ERR_RANGE for a non-positive ratio, or a negative TinyImageError.

tiny_image_draw_circle()

int tiny_image_draw_circle	(	TinyImage *	image,
		int32_t	center_x,
		int32_t	center_y,
		uint32_t	radius,
		const uint8_t *	pixel )

Draws the outline of a circle.

Parameters

image	The image to draw on.
center_x	Center.
center_y	Center.
radius	Radius in pixels.
pixel	As many channels as the image has.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_draw_ellipse()

int tiny_image_draw_ellipse	(	TinyImage *	image,
		int32_t	center_x,
		int32_t	center_y,
		uint32_t	radius_x,
		uint32_t	radius_y,
		const uint8_t *	pixel )

Draws the outline of an axis-aligned ellipse.

Parameters

image	The image to draw on.
center_x	Center.
center_y	Center.
radius_x	Horizontal semi-axis.
radius_y	Vertical semi-axis.
pixel	As many channels as the image has.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_draw_image()

int tiny_image_draw_image	(	TinyImage *	dest_image,
		const TinyImage *	src_image,
		int32_t	x,
		int32_t	y )

Draws one image onto another.

The source's alpha is honored, so a transparent overlay composites rather than punching a hole. Channel counts need not match: a source with alpha over a destination without one blends against the destination, and a source without alpha is opaque.

Parameters

dest_image	The image to draw on.
src_image	The image to draw.
x	Where the source's left edge lands.
y	Where the source's top edge lands.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_draw_image_ex()

int tiny_image_draw_image_ex	(	TinyImage *	dest_image,
		const TinyImage *	src_image,
		int32_t	x,
		int32_t	y,
		float	opacity,
		TinyDrawMode	mode,
		TinyBlendMode	blend )

Draws one image onto another with an opacity, a placement and a blend mode.

Parameters

dest_image	The image to draw on.
src_image	The image to draw.
x	Where the source's left edge lands, or the tiling origin.
y	Where the source's top edge lands, or the tiling origin.
opacity	0 through 1, multiplied into the source's alpha.
mode	Once, tiled, or centered.
blend	How the colors meet.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_draw_line()

int tiny_image_draw_line	(	TinyImage *	image,
		int32_t	x1,
		int32_t	y1,
		int32_t	x2,
		int32_t	y2,
		uint32_t	thickness,
		const uint8_t *	pixel )

Draws a line of the given thickness.

Bresenham for a single-pixel line, and a distance test against the segment for a thicker one, which is what keeps a thick line's ends square and its joins free of the gaps a stamped brush leaves on a steep slope.

Parameters

image	The image to draw on.
x1	Start.
y1	Start.
x2	End.
y2	End.
thickness	Width in pixels; zero and one both mean a single pixel.
pixel	As many channels as the image has.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_drop_shadow()

int tiny_image_drop_shadow	(	TinyImage *	image,
		int32_t	offset_x,
		int32_t	offset_y,
		float	sigma,
		const uint8_t *	color )

Grows the image and puts a blurred silhouette of it behind.

The shadow is cast by the alpha channel, so an image with none casts a rectangle. The extent grows by whatever the offset and the blur need, so nothing is clipped.

Parameters

image	The image, replaced by the larger one.
offset_x	How far right the shadow falls.
offset_y	How far down.
sigma	How soft.
color	The shadow's color, as many channels as the result has.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_duotone()

int tiny_image_duotone	(	TinyImage *	image,
		const uint8_t *	shadow,
		const uint8_t *	highlight )

Maps the tonal range between two colors.

Parameters

image	The image to change.
shadow	The color black becomes, three channels.
highlight	The color white becomes.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_emboss()

int tiny_image_emboss	(	TinyImage *	image,
		float	strength )

Turns the image into a relief lit from the upper left.

Parameters

image	The image to change.
strength	Added to every output; 128 keeps a flat area mid gray.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_encode()

int tiny_image_encode	(	const TinyImage *	image,
		TinyImageFormat	format,
		const TinyEncodeOpts *	opts,
		TinyWriter *	writer )

Encodes an image into a growing byte sink.

The writer sizes itself, so no caller has to guess an output length. On success the bytes are writer->data for writer->size bytes, until the caller releases them with tiny_writer_free or takes them with tiny_writer_detach.

Parameters

image	Pointer to the TinyImage structure to be encoded.
format	The container to write.
opts	Quality and related settings. NULL uses the image's own quality and the format's defaults.
writer	An initialized TinyWriter to append to.

Returns

int TINYIMG_OK, TINYIMG_ERR_UNSUPPORTED_CODEC when the format has no encoder in this build, or a negative TinyImageError.

tiny_image_erode()

int tiny_image_erode	(	TinyImage *	image,
		uint32_t	radius )

Replaces each pixel with the darkest in a radius.

Parameters

image	The image to change.
radius	Pixels either side.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_expand()

int tiny_image_expand	(	TinyImage *	image,
		uint32_t	left,
		uint32_t	top,
		uint32_t	right,
		uint32_t	bottom,
		const uint8_t *	pixel )

Grows the image by a border around it.

Unlike tiny_image_border this changes the extent rather than covering the pixels at the edge, which is what a caller framing an image wants and what Cloudflare Images' border parameter does.

Parameters

image	The image, replaced by the larger one.
left	How many columns to add.
top	How many rows.
right	How many columns.
bottom	How many rows.
pixel	The border's color, as many channels as the image has.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_exposure()

int tiny_image_exposure	(	TinyImage *	image,
		float	stops )

Scales every channel by a power of two.

Parameters

image	The image to change.
stops	Positive brightens; 0 changes nothing.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_fill_circle()

int tiny_image_fill_circle	(	TinyImage *	image,
		int32_t	center_x,
		int32_t	center_y,
		uint32_t	radius,
		const uint8_t *	pixel )

Fills a circle.

Parameters

image	The image to draw on.
center_x	Center.
center_y	Center.
radius	Radius in pixels.
pixel	As many channels as the image has.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_fill_ellipse()

int tiny_image_fill_ellipse	(	TinyImage *	image,
		int32_t	center_x,
		int32_t	center_y,
		uint32_t	radius_x,
		uint32_t	radius_y,
		const uint8_t *	pixel )

Fills an axis-aligned ellipse.

Parameters

image	The image to draw on.
center_x	Center.
center_y	Center.
radius_x	Horizontal semi-axis.
radius_y	Vertical semi-axis.
pixel	As many channels as the image has.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_fill_light()

int tiny_image_fill_light	(	TinyImage *	image,
		float	amount )

Lifts the shadows without moving the highlights.

Parameters

image	The image to change.
amount	0 through 1.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_fill_polygon()

int tiny_image_fill_polygon	(	TinyImage *	image,
		const int32_t *	x_points,
		const int32_t *	y_points,
		size_t	num_points,
		const uint8_t *	pixel )

Fills a polygon by the even-odd rule.

Parameters

image	The image to draw on.
x_points	Vertex x coordinates.
y_points	Vertex y coordinates.
num_points	How many vertices; below three fills nothing.
pixel	As many channels as the image has.

Returns

int TINYIMG_OK, TINYIMG_ERR_NULL, or a negative TinyImageError.

tiny_image_fill_polygon_with()

int tiny_image_fill_polygon_with	(	TinyImage *	image,
		const int32_t *	x_points,
		const int32_t *	y_points,
		size_t	num_points,
		const uint8_t *	pixel,
		TinyFillRule	rule,
		TinyBlendMode	blend )

Fills a polygon by a named rule, blended.

Parameters

image	The image to draw on.
x_points	Vertex x coordinates.
y_points	Vertex y coordinates.
num_points	How many vertices.
pixel	As many channels as the image has.
rule	Which points count as inside.
blend	How the color meets what is there.

Returns

int TINYIMG_OK, TINYIMG_ERR_NULL, or a negative TinyImageError.

tiny_image_fill_rectangle()

int tiny_image_fill_rectangle	(	TinyImage *	image,
		int32_t	x,
		int32_t	y,
		uint32_t	width,
		uint32_t	height,
		const uint8_t *	pixel )

Fills a rectangle.

Parameters

image	The image to draw on.
x	Left edge.
y	Top edge.
width	Width in pixels.
height	Height in pixels.
pixel	As many channels as the image has.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_fill_rounded_rectangle()

int tiny_image_fill_rounded_rectangle	(	TinyImage *	image,
		int32_t	x,
		int32_t	y,
		uint32_t	width,
		uint32_t	height,
		uint32_t	radius,
		const uint8_t *	pixel )

Fills a rectangle whose corners are rounded.

Parameters

image	The image to draw on.
x	Left edge.
y	Top edge.
width	Width in pixels.
height	Height in pixels.
radius	Corner radius; clamped to half the shorter side, so a radius past that gives a stadium rather than an error.
pixel	As many channels as the image has.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_film_grain()

int tiny_image_film_grain	(	TinyImage *	image,
		float	amount )

Adds noise weighted toward the midtones, which is how film grains.

Parameters

image	The image to change.
amount	Standard deviation in levels at mid gray.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_fit()

int tiny_image_fit	(	TinyImage *	image,
		uint32_t	target_width,
		uint32_t	target_height,
		TinyImageFit	fit_mode )

Resizes an image to fit within the specified target width and height according to the specified fit mode.

The function adjusts the image dimensions based on the selected fit mode, which determines how the image will be scaled, cropped, or padded to fit within the target dimensions while maintaining its aspect ratio.

Parameters

image	Pointer to the TinyImage structure to be resized.
target_width	The desired width of the resized image in pixels.
target_height	The desired height of the resized image in pixels.
fit_mode	The fit mode that specifies how the image should be resized (e.g., scale down, contain, cover, crop, etc.).

Returns

int 0 on success, non-zero on failure (e.g., if memory allocation fails or if the new dimensions exceed limits).

tiny_image_fit_with_gravity()

int tiny_image_fit_with_gravity	(	TinyImage *	image,
		uint32_t	target_width,
		uint32_t	target_height,
		TinyImageFit	fit_mode,
		TinyImageGravity	gravity,
		const uint8_t *	background )

Fits the image to a target, keeping the part the gravity names.

Parameters

image	The image, replaced by the result.
target_width	Target width.
target_height	Target height.
fit_mode	How the aspect mismatch is absorbed; see TinyImageFit.
gravity	Which part a crop keeps, or where a pad puts the image.
background	What a pad is filled with, or NULL for the default.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_fit_with_padding()

int tiny_image_fit_with_padding	(	TinyImage *	image,
		uint32_t	target_width,
		uint32_t	target_height,
		TinyImageFit	fit_mode,
		const uint8_t *	padding_color )

Resizes an image to fit within the specified target width and height according to the specified fit mode, with optional padding.

The function adjusts the image dimensions based on the selected fit mode, which determines how the image will be scaled, cropped, or padded to fit within the target dimensions while maintaining its aspect ratio. If padding is required, the specified padding color will be used to fill the empty space around the image.

Parameters

image	Pointer to the TinyImage structure to be resized.
target_width	The desired width of the resized image in pixels.
target_height	The desired height of the resized image in pixels.
fit_mode	The fit mode that specifies how the image should be resized (e.g., scale down, contain, cover, crop, etc.).
padding_color	Pointer to a uint8_t array specifying the color to be used for padding. The size of the array should match the number of channels in the image type. If NULL, no padding will be applied.

Returns

int 0 on success, non-zero on failure (e.g., if memory allocation fails or if the new dimensions exceed limits).

tiny_image_fit_with_padding_and_background()

int tiny_image_fit_with_padding_and_background	(	TinyImage *	image,
		uint32_t	target_width,
		uint32_t	target_height,
		TinyImageFit	fit_mode,
		const uint8_t *	padding_color,
		const uint8_t *	background_color )

Resizes an image to fit within the specified target width and height according to the specified fit mode, with optional padding and background color.

The function adjusts the image dimensions based on the selected fit mode, which determines how the image will be scaled, cropped, or padded to fit within the target dimensions while maintaining its aspect ratio. If padding is required, the specified padding color will be used to fill the empty space around the image. Additionally, a background color can be specified to fill any remaining areas of the image that are not covered by the original image or padding.

Parameters

image	Pointer to the TinyImage structure to be resized.
target_width	The desired width of the resized image in pixels.
target_height	The desired height of the resized image in pixels.
fit_mode	The fit mode that specifies how the image should be resized (e.g., scale down, contain, cover, crop, etc.).
padding_color	Pointer to a uint8_t array specifying the color to be used for padding. The size of the array should match the number of channels in the image type. If NULL, no padding will be applied.
background_color	Pointer to a uint8_t array specifying the color to be used for filling any remaining areas of the image. The size of the array should match the number of channels in the image type. If NULL, no background color will be applied.

Returns

int 0 on success, non-zero on failure (e.g., if memory allocation fails or if the new dimensions exceed limits).

tiny_image_flip_horizontal()

int tiny_image_flip_horizontal

(

TinyImage *

image

)

Flips an image horizontally, mirroring it along the vertical axis.

Parameters

image

Pointer to the TinyImage structure to be flipped.

Returns

int 0 on success, non-zero on failure (e.g., if the image is NULL).

tiny_image_flip_vertical()

int tiny_image_flip_vertical

(

TinyImage *

image

)

Flips an image vertically, mirroring it along the horizontal axis.

Parameters

image

Pointer to the TinyImage structure to be flipped.

Returns

int 0 on success, non-zero on failure (e.g., if the image is NULL).

tiny_image_focus()

int tiny_image_focus	(	const TinyImage *	image,
		TinyImageGravity	gravity,
		float *	x,
		float *	y )

Where the part of an image worth keeping is.

What the two computed gravities resolve to, and useful on its own: a caller cropping by hand wants the same answer the planner would have used.

TINYIMG_GRAVITY_AUTO weights every tile of the image by how much local detail it holds and returns the centroid, so a photograph with one sharp subject on a soft background focuses on the subject. TINYIMG_GRAVITY_FACE runs tiny_image_detect_faces and returns the center of the detections, weighted by how confident each one is, and falls back to TINYIMG_GRAVITY_AUTO when no cascade is loaded or nothing was found. Every fixed gravity is arithmetic and reads no pixels.

Parameters

image	The image to read.
gravity	Which question to ask.
x	Receives the horizontal position, 0 through 1 across the width.
y	Receives the vertical position.

Returns

int TINYIMG_OK, or a negative TinyImageError. A detector that finds nothing is not a failure; it reports TINYIMG_OK with the fallback.

tiny_image_gamma_correction()

int tiny_image_gamma_correction	(	TinyImage *	image,
		float	gamma )

Applies gamma correction to the image.

Gamma correction adjusts the brightness of the image based on a specified gamma value. A gamma value greater than 1.0 will darken the image, while a value less than 1.0 will brighten it. The function modifies the pixel values of the image accordingly.

Parameters

image	Pointer to the TinyImage structure to be gamma corrected.
gamma	The gamma value to be applied for correction. Must be a positive float greater than 0.

Returns

int 0 on success, non-zero on failure (e.g., if the image is NULL or if the gamma value is invalid).

tiny_image_gaussian_blur()

int tiny_image_gaussian_blur	(	TinyImage *	image,
		float	sigma )

Applies a Gaussian blur effect to the image.

This function applies a Gaussian blur to the entire image, softening edges and reducing noise. The amount of blurring is controlled by the sigma parameter, which determines the standard deviation of the Gaussian kernel.

Parameters

image	Pointer to the TinyImage structure to be blurred.
sigma	The standard deviation of the Gaussian kernel. A higher value results in a stronger blur effect. Must be a positive float greater than 0.

Returns

int 0 on success, non-zero on failure (e.g., if the image is NULL or if the sigma value is invalid).

tiny_image_get_exif()

int tiny_image_get_exif	(	const TinyImage *	image,
		char **	exif_data,
		size_t *	exif_size )

Retrieves the EXIF metadata from the image.

This function allows you to retrieve the EXIF metadata from the image, which can include information such as camera settings, date and time, GPS location, and more. The EXIF data is returned as a byte array, and the size of the data is also provided.

Parameters

image	Pointer to the TinyImage structure from which to retrieve the EXIF metadata.
exif_data	Pointer to a pointer that will be set to point to the retrieved EXIF metadata. The caller is responsible for freeing this memory.
exif_size	Pointer to a size_t variable that will be set to the size of the retrieved EXIF data in bytes.

Returns

int 0 on success, non-zero on failure (e.g., if the image is NULL or if there is no EXIF data).

tiny_image_get_metadata()

int tiny_image_get_metadata	(	const TinyImage *	image,
		const char *	key,
		char **	value )

Retrieves the value associated with a custom metadata key from the image.

This function allows you to retrieve the value associated with a custom metadata key from the image. The key is provided as a string, and the corresponding value is returned as a string. The caller is responsible for freeing the memory allocated for the value.

Parameters

image	Pointer to the TinyImage structure from which to retrieve the custom metadata.
key	The key for the custom metadata whose value is to be retrieved.
value	Pointer to a pointer that will be set to point to the retrieved value. The caller is responsible for freeing this memory.

Returns

int 0 on success, non-zero on failure (e.g., if the image is NULL or if the key does not exist).

tiny_image_get_metadata_count()

int tiny_image_get_metadata_count	(	const TinyImage *	image,
		size_t *	count )

Retrieves the count of custom metadata key-value pairs in the image.

Parameters

image	Pointer to the TinyImage structure from which to retrieve the metadata count.
count	Pointer to a size_t variable that will be set to the number of custom metadata key-value pairs in the image.

Returns

int 0 on success, non-zero on failure (e.g., if the image is NULL or if the count pointer is NULL).

tiny_image_getchannels()

uint32_t tiny_image_getchannels

(

const TinyImage *

image

)

Channels per pixel.

Parameters

image

The image.

Returns

uint32_t The channel count, or 0 if the image is NULL.

tiny_image_getdata()

uint8_t * tiny_image_getdata

(

const TinyImage *

image

)

Pointer to an image's pixel data.

Parameters

image

The image.

Returns

uint8_t* The pixels, or NULL if the image is NULL or empty.

tiny_image_getextension()

int tiny_image_getextension	(	const TinyImage *	image,
		char *	extension,
		size_t	max_length )

Retrieves the file extension associated with the image format.

Parameters

image	Pointer to the TinyImage structure whose file extension is to be determined.
extension	Pointer to a character array where the file extension will be stored. The array should be large enough to hold the extension string.
max_length	The maximum length of the extension string, including the null terminator.

Returns

int TINYIMG_OK, TINYIMG_ERR_NULL, TINYIMG_ERR_UNKNOWN_FORMAT, or TINYIMG_ERR_BUFFER_TOO_SMALL when max_length is insufficient.

tiny_image_getformat()

TinyImageFormat tiny_image_getformat

(

const TinyImage *

image

)

Retrieves the format of the image.

Parameters

image

Pointer to the TinyImage structure from which to retrieve the format.

Returns

TinyImageFormat The format of the image.

tiny_image_getheight()

uint32_t tiny_image_getheight

(

const TinyImage *

image

)

Height of an image in pixels.

Parameters

image

The image.

Returns

uint32_t The height, or 0 if the image is NULL.

tiny_image_getpixel()

int tiny_image_getpixel	(	const TinyImage *	image,
		uint32_t	x,
		uint32_t	y,
		uint8_t *	pixel )

Retrieves the pixel value at the specified (x, y) coordinates in the image.

The function calculates the appropriate index in the pixel data array based on the image's width and height, and retrieves the pixel value. The pixel value is returned as a single byte for grayscale images or as multiple bytes for color images (e.g., RGB, RGBA).

Parameters

image	Pointer to the TinyImage structure from which to retrieve the pixel value.
x	The x-coordinate of the pixel (0-based index).
y	The y-coordinate of the pixel (0-based index).
pixel	Pointer to a uint8_t array where the pixel value will be stored. The size of the array should match the number of channels in the image type.

Returns

int TINYIMG_OK, TINYIMG_ERR_NULL, or TINYIMG_ERR_BOUNDS when the coordinates fall outside the image.

tiny_image_getsize()

uint32_t tiny_image_getsize

(

const TinyImage *

image

)

Bytes an image's pixel data occupies.

Parameters

image

The image.

Returns

uint32_t width * height * channels, or 0 if the image is NULL.

tiny_image_gettype()

int tiny_image_gettype	(	const TinyImage *	image,
		TinyImagePixelType *	type )

Retrieves the type of the image (grayscale, grayscale with alpha, RGB or RGBA).

Parameters

image	Pointer to the TinyImage structure whose type is to be determined.
type	Receives the pixel type.

Returns

int TINYIMG_OK, TINYIMG_ERR_NULL, or TINYIMG_ERR_RANGE when the channel count is not 1 through 4.

tiny_image_getwidth()

uint32_t tiny_image_getwidth

(

const TinyImage *

image

)

Width of an image in pixels.

Parameters

image

The image.

Returns

uint32_t The width, or 0 if the image is NULL.

tiny_image_glow()

int tiny_image_glow	(	TinyImage *	image,
		float	sigma,
		float	strength )

Adds a blurred copy of the image to itself, which is a bloom.

Parameters

image	The image to change.
sigma	How wide the glow spreads.
strength	How much of the blurred copy to add.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_gradient_fade()

int tiny_image_gradient_fade	(	TinyImage *	image,
		float	angle,
		float	start,
		float	end )

Fades the image toward transparency along a direction.

Parameters

image	The image to change. Gains an alpha channel if it has none.
angle	Degrees clockwise from the positive x axis; the fade runs along it, opaque at the start.
start	Where the fade begins, 0 through 1 across the image.
end	Where it reaches full transparency.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_gradient_linear()

int tiny_image_gradient_linear	(	TinyImage *	image,
		int32_t	x0,
		int32_t	y0,
		int32_t	x1,
		int32_t	y1,
		const uint8_t *	from,
		const uint8_t *	to )

Fills the image with a linear gradient.

Parameters

image	The image to fill.
x0	Where the gradient starts.
y0	Where the gradient starts.
x1	Where it ends.
y1	Where it ends.
from	The color at the start, as many channels as the image has.
to	The color at the end.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE when the two points coincide, or a negative TinyImageError.

tiny_image_gradient_radial()

int tiny_image_gradient_radial	(	TinyImage *	image,
		int32_t	center_x,
		int32_t	center_y,
		uint32_t	radius,
		const uint8_t *	inner,
		const uint8_t *	outer )

Fills the image with a radial gradient.

Parameters

image	The image to fill.
center_x	Center.
center_y	Center.
radius	Where the outer color is reached.
inner	The color at the center.
outer	The color at the radius and beyond.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE for a zero radius, or a negative TinyImageError.

tiny_image_halftone()

int tiny_image_halftone	(	TinyImage *	image,
		uint32_t	cell )

Turns tone into dot area within a cell.

Parameters

image	The image to change.
cell	Cell size in pixels.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_has_exif()

int tiny_image_has_exif

(

const TinyImage *

image

)

Checks if the image has EXIF metadata.

This function checks whether the image contains any EXIF metadata. It returns a non-zero value if EXIF data is present, and zero if no EXIF data is found.

Parameters

image

Pointer to the TinyImage structure to be checked for EXIF metadata.

Returns

int Non-zero if EXIF data is present, zero if no EXIF data is found, or a negative value on error (e.g., if the image is NULL).

tiny_image_has_metadata()

int tiny_image_has_metadata	(	const TinyImage *	image,
		const char *	key )

Checks if the image has a specific custom metadata key.

This function checks whether the image contains a specific custom metadata key. It returns a non-zero value if the key is present, and zero if the key is not found.

Parameters

image	Pointer to the TinyImage structure to be checked for the custom metadata key.
key	The key for the custom metadata to check for.

Returns

int Non-zero if the key is present, zero if the key is not found, or a negative value on error (e.g., if the image is NULL).

tiny_image_histogram()

int tiny_image_histogram	(	const TinyImage *	image,
		uint8_t	channel,
		uint32_t *	bins )

Counts how many pixels fall in each of 256 buckets.

Parameters

image	The image to read.
channel	Which channel, or 255 for the luminance.
bins	Receives 256 counts.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE for a channel the image has not got, or a negative TinyImageError.

tiny_image_hline()

int tiny_image_hline	(	TinyImage *	image,
		int32_t	x1,
		int32_t	y1,
		int32_t	x2,
		int32_t	y2,
		const uint8_t *	pixel )

Draws a horizontal run of pixels.

Coordinates are signed and the run is clipped, so a line that starts or ends outside the image draws the part of it that is inside rather than failing. A run whose endpoints are both outside on the same side draws nothing.

Parameters

image	The image to draw on.
x1	One end.
y1	The row. y2 is ignored, so the two forms of a line share a signature.
x2	The other end. May be to the left of x1.
y2	Ignored.
pixel	As many channels as the image has.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_hue()

int tiny_image_hue	(	TinyImage *	image,
		float	angle )

Adjusts the hue of the image.

This function modifies the image's color hue by rotating its hue value by the specified angle. The angle is measured in degrees, and a positive angle rotates the hue clockwise, while a negative angle rotates it counterclockwise. The function will resample the image data accordingly to maintain the visual quality of the image.

Parameters

image	Pointer to the TinyImage structure whose hue is to be adjusted.
angle	The angle by which to rotate the hue, in degrees. Must be a float value between -360.0 and 360.0.

Returns

int 0 on success, non-zero on failure (e.g., if the image is NULL or if the angle is invalid).

tiny_image_improve()

int tiny_image_improve

(

TinyImage *

image

)

Applies the auto corrections a photograph usually wants together.

Levels, then color, then a small saturation lift. All three collapse, so it costs one pass.

Parameters

image

The image to change.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_info_sizeof()

uint32_t tiny_image_info_sizeof

(

void

)

Size of a TinyImageInfo, for a host allocating one across the wasm boundary.

Returns

uint32_t sizeof(TinyImageInfo).

tiny_image_invert()

int tiny_image_invert

(

TinyImage *

image

)

Inverts the colors of an image, producing a negative effect.

Each pixel's color value is transformed to its complementary color by subtracting the original value from the maximum value (255 for 8-bit images).

Parameters

image

Pointer to the TinyImage structure to be inverted.

Returns

int 0 on success, non-zero on failure (e.g., if the image is NULL).

tiny_image_istransparent()

int tiny_image_istransparent

(

const TinyImage *

image

)

Checks if the image has an alpha channel (transparency).

This function checks whether the image contains an alpha channel, which indicates that the image supports transparency. It returns a non-zero value if the image has an alpha channel, and zero if it does not.

Parameters

image

Pointer to the TinyImage structure to be checked for an alpha channel.

Returns

int Non-zero if the image has an alpha channel, zero if it does not, or a negative value on error (e.g., if the image is NULL).

tiny_image_levels()

int tiny_image_levels	(	TinyImage *	image,
		float	in_black,
		float	in_white,
		float	gamma,
		float	out_black,
		float	out_white )

Maps an input range onto an output range through a gamma.

Parameters

image	The image to change.
in_black	Input level that becomes out_black.
in_white	Input level that becomes out_white; above in_black.
gamma	Applied between the two; 1 is linear.
out_black	The output floor.
out_white	The output ceiling.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_levels_channel()

int tiny_image_levels_channel	(	TinyImage *	image,
		uint8_t	channel,
		float	in_black,
		float	in_white,
		float	gamma,
		float	out_black,
		float	out_white )

The same, on one channel.

Parameters

image	The image to change.
channel	0 red, 1 green, 2 blue.
in_black	Input level that becomes out_black.
in_white	Input level that becomes out_white.
gamma	Applied between the two.
out_black	The output floor.
out_white	The output ceiling.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_lighten()

int tiny_image_lighten	(	TinyImage *	image,
		uint32_t	x,
		uint32_t	y,
		uint32_t	width,
		uint32_t	height,
		float	factor )

Lightens a specified rectangular region of the image by the given factor.

This function increases the brightness of the pixels within the specified rectangle, making them lighter. The lightening effect is controlled by the factor parameter, where a value greater than 1.0 will lighten the pixels, and a value less than 1.0 will have no effect (as it would darken instead).

Parameters

image	Pointer to the TinyImage structure to be modified.
x	The x-coordinate of the top-left corner of the rectangle (0-based index).
y	The y-coordinate of the top-left corner of the rectangle (0-based index).
width	The width of the rectangle in pixels.
height	The height of the rectangle in pixels.
factor	The factor by which to lighten the pixels. Must be a float value greater than 1.0, where higher values result in lighter pixels.

Returns

int 0 on success, non-zero on failure (e.g., if coordinates are out of bounds or if the image is NULL).

tiny_image_load()

int tiny_image_load	(	TinyImage *	image,
		const uint8_t *	buffer,
		size_t	buffer_size )

Loads an image, decoding every pixel.

The format is identified from the buffer's magic bytes; there is no format argument to get wrong.

Parameters

image	Pointer to a TinyImage structure where the loaded image will be stored.
buffer	A pointer to the buffer containing the image data.
buffer_size	The size of the buffer in bytes.

Returns

int TINYIMG_OK, or a negative TinyImageError. An image past TINYIMG_MAX_PIXELS or TINYIMG_MAX_IMAGE_BYTES reports TINYIMG_ERR_TOO_LARGE rather than TINYIMG_ERR_MEMORY, because the remedy is tiny_image_load_scaled.

tiny_image_load_region()

int tiny_image_load_region	(	TinyImage *	image,
		const uint8_t *	buffer,
		size_t	buffer_size,
		uint32_t	x,
		uint32_t	y,
		uint32_t	width,
		uint32_t	height )

Loads one rectangle of an image.

Memory is bounded by the rectangle rather than by the source, except for progressive JPEG: successive approximation needs the whole coefficient plane before any pixel is final, so a progressive file is decoded and then cropped.

Parameters

image	Pointer to a TinyImage structure where the loaded image will be stored.
buffer	A pointer to the buffer containing the image data.
buffer_size	The size of the buffer in bytes.
x	Left edge of the rectangle in source pixels.
y	Top edge of the rectangle in source pixels.
width	Width of the rectangle. Zero means to the right edge.
height	Height of the rectangle. Zero means to the bottom edge.

Returns

int TINYIMG_OK, TINYIMG_ERR_BOUNDS when the rectangle starts outside the image, or a negative TinyImageError.

tiny_image_load_scaled()

int tiny_image_load_scaled	(	TinyImage *	image,
		const uint8_t *	buffer,
		size_t	buffer_size,
		uint32_t	max_width,
		uint32_t	max_height )

Loads an image at the cheapest scale that still covers the given box.

Codecs offer halves, quarters and eighths, so the result is the smallest of those that is still at least as large as the box in both axes. It is therefore usually larger than the box, never smaller unless the source itself is, which leaves any resampling that follows as a downscale.

This is the entry point that makes an oversized source usable: statistics, face detection and any output smaller than the source all read a reduced decode instead of the full pixel count.

Parameters

image	Pointer to a TinyImage structure where the loaded image will be stored.
buffer	A pointer to the buffer containing the image data.
buffer_size	The size of the buffer in bytes.
max_width	Width the decode must still cover. Zero means unconstrained.
max_height	Height the decode must still cover. Zero means unconstrained.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_morphology_close()

int tiny_image_morphology_close	(	TinyImage *	image,
		uint32_t	radius )

Dilates then erodes, which fills dark specks.

Parameters

image	The image to change.
radius	Pixels either side.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_morphology_open()

int tiny_image_morphology_open	(	TinyImage *	image,
		uint32_t	radius )

Erodes then dilates, which removes bright specks.

Parameters

image	The image to change.
radius	Pixels either side.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_motion_blur()

int tiny_image_motion_blur	(	TinyImage *	image,
		float	length,
		float	angle )

Averages along a straight path.

Parameters

image	The image to change.
length	How far, in pixels.
angle	Degrees clockwise from the positive x axis.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_negate()

int tiny_image_negate

(

TinyImage *

image

)

Subtracts every color channel from full scale.

Parameters

image

The image to change.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_noise()

int tiny_image_noise	(	TinyImage *	image,
		float	amount,
		int	monochrome )

Adds pseudorandom noise.

The generator is a counter hashed per pixel, so the same request over the same image gives the same noise. A generator carrying state between calls would not, and a caller comparing two runs would see a difference that is not in the request.

Parameters

image	The image to change.
amount	Standard deviation in levels.
monochrome	Non-zero to add the same value to every channel.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_opacity()

int tiny_image_opacity	(	TinyImage *	image,
		float	opacity )

Adjusts the opacity of an image by modifying its alpha channel.

The function multiplies the alpha value of each pixel by the specified opacity factor, which should be in the range [0.0, 1.0]. A value of 0.0 makes the image fully transparent, while a value of 1.0 retains the original opacity.

Parameters

image	Pointer to the TinyImage structure whose opacity is to be adjusted.
opacity	The opacity factor to apply to the image (0.0-1.0).

Returns

int 0 on success, non-zero on failure (e.g., if the image is NULL or if the opacity value is out of range).

tiny_image_outline()

int tiny_image_outline	(	TinyImage *	image,
		uint32_t	radius )

The difference between a dilation and an erosion.

Parameters

image	The image to change.
radius	Pixels either side.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_palette()

int tiny_image_palette	(	const TinyImage *	image,
		uint32_t	count,
		uint8_t *	palette )

The colors a palette of the given size would hold.

Parameters

image	The image to read.
count	How many colors to find, 1 through 256.
palette	Receives count entries of as many channels as the image has.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_perspective()

int tiny_image_perspective	(	TinyImage *	image,
		const float *	quad,
		const uint8_t *	background )

Maps the image's four corners onto four arbitrary points.

Parameters

image	The image, replaced by the result.
quad	Eight numbers: the x and y of the destination for the top left, top right, bottom right and bottom left corners, in that order.
background	What the uncovered pixels are filled with, or NULL for transparent.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE when the quad is degenerate, or a negative TinyImageError.

tiny_image_phash()

int tiny_image_phash	(	const TinyImage *	image,
		uint64_t *	hash )

A 64 bit perceptual hash.

The discrete cosine transform of a 32x32 luminance reduction, thresholded at the median of its low frequency block. Two images a viewer would call the same differ in few bits; two unrelated ones differ in about half.

Parameters

image	The image to read.
hash	Receives the hash, most significant bit first.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_pixelate()

int tiny_image_pixelate	(	TinyImage *	image,
		uint32_t	size )

Averages the image over square blocks.

Parameters

image	The image to change.
size	Block size in pixels; below two changes nothing.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_pixelate_faces()

int tiny_image_pixelate_faces	(	TinyImage *	image,
		uint32_t	size )

Pixelates whatever the detector finds and nothing else.

A no-op when nothing is found, for the reason given on tiny_image_blur_faces.

Parameters

image	The image to change.
size	Block size in pixels. Zero reads as a twelfth of the face's width.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_pixelate_region()

int tiny_image_pixelate_region	(	TinyImage *	image,
		uint32_t	x,
		uint32_t	y,
		uint32_t	width,
		uint32_t	height,
		uint32_t	size )

The same, inside a rectangle.

Parameters

image	The image to change.
x	Left edge.
y	Top edge.
width	Width; zero means to the right edge.
height	Height; zero means to the bottom edge.
size	Block size in pixels.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_polar()

int tiny_image_polar	(	TinyImage *	image,
		int	inverse )

Maps between rectangular and polar coordinates.

Parameters

image	The image to change.
inverse	Zero maps the image onto a disc; non-zero unrolls a disc into a rectangle.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_polygon()

int tiny_image_polygon	(	TinyImage *	image,
		const int32_t *	x_points,
		const int32_t *	y_points,
		size_t	num_points,
		const uint8_t *	pixel )

Draws the edges of a polygon, closing it.

Parameters

image	The image to draw on.
x_points	Vertex x coordinates.
y_points	Vertex y coordinates.
num_points	How many vertices; below two draws nothing.
pixel	As many channels as the image has.

Returns

int TINYIMG_OK, TINYIMG_ERR_NULL, or a negative TinyImageError.

tiny_image_posterize()

int tiny_image_posterize	(	TinyImage *	image,
		uint32_t	levels )

Rounds every channel to a number of evenly spaced levels.

Parameters

image	The image to change.
levels	How many, 2 through 256.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_premultiply()

int tiny_image_premultiply

(

TinyImage *

image

)

Multiplies each color channel by its alpha.

The form compositing and resampling are correct in. A no-op on an image with no alpha channel.

Parameters

image

The image to change.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_preset()

int tiny_image_preset	(	TinyImage *	image,
		TinyImagePreset	preset )

Applies a named look.

Parameters

image	The image to change.
preset	Which look.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_probe()

int tiny_image_probe	(	const uint8_t *	buffer,
		size_t	buffer_size,
		TinyImageInfo *	info )

Reads an image's header without decoding any pixels.

The cheapest of the four ways in. Answers for every format the library recognizes, including AVIF and HEIF, which it can describe but not decode.

Parameters

buffer	A pointer to the buffer containing the image data.
buffer_size	The size of the buffer in bytes.
info	Receives what the header says.

Returns

int TINYIMG_OK, TINYIMG_ERR_UNKNOWN_FORMAT when no format matched, or TINYIMG_ERR_CORRUPT when the header is malformed.

tiny_image_quality()

int tiny_image_quality	(	TinyImage *	image,
		int	quality )

Sets the quality of the image for lossy formats (e.g., JPEG).

The quality parameter typically ranges from 0 to 100, where higher values indicate better quality and larger file sizes, while lower values indicate lower quality and smaller file sizes.

Parameters

image	Pointer to the TinyImage structure whose quality is to be set.
quality	The desired quality level (0-100) for the image.

Returns

int 0 on success, non-zero on failure (e.g., if the image is NULL or if the quality value is out of range).

tiny_image_radial_blur()

int tiny_image_radial_blur	(	TinyImage *	image,
		float	degrees )

Averages along arcs about the center.

Parameters

image	The image to change.
degrees	How far around.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_rectangle()

int tiny_image_rectangle	(	TinyImage *	image,
		int32_t	x,
		int32_t	y,
		uint32_t	width,
		uint32_t	height,
		const uint8_t *	pixel )

Draws the outline of a rectangle, one pixel wide.

Parameters

image	The image to draw on.
x	Left edge.
y	Top edge.
width	Width in pixels.
height	Height in pixels.
pixel	As many channels as the image has.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_remove_background()

int tiny_image_remove_background	(	TinyImage *	image,
		uint8_t	tolerance )

Clears the background, making it transparent.

A flood fill seeded from the four corners, so what counts as background is whatever is connected to the edge and close in color to it. That is the difference from clearing every pixel near the background color: a white shirt in the middle of a photograph on a white backdrop stays.

The edge of what it clears is feathered by the alpha the match was within, so the cutout has a soft boundary rather than a stair-stepped one.

Parameters

image	The image to change. Gains an alpha channel if it has none.
tolerance	How far a channel may differ from the seed color and still count as background, 0 through 255.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_remove_metadata()

int tiny_image_remove_metadata	(	TinyImage *	image,
		const char *	key )

Removes a specific custom metadata key-value pair from the image.

This function allows you to remove a specific custom metadata key-value pair from the image. The key is provided as a string, and if the key exists, it will be removed along with its associated value.

Parameters

image	Pointer to the TinyImage structure from which to remove the custom metadata.
key	The key for the custom metadata to be removed.

Returns

int 0 on success, non-zero on failure (e.g., if the image is NULL or if the key does not exist).

tiny_image_replace_color()

int tiny_image_replace_color	(	TinyImage *	image,
		const uint8_t *	old_color,
		const uint8_t *	new_color,
		const uint8_t *	tolerance )

Replaces every pixel close to one color with another.

Parameters

image	The image to change.
old_color	The color to look for, as many channels as the image has.
new_color	What to write instead.
tolerance	How far each channel may differ and still match, as many channels as the image has. NULL means an exact match.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_resize()

int tiny_image_resize	(	TinyImage *	image,
		uint32_t	new_width,
		uint32_t	new_height )

Resamples an image to the specified new width and height.

Every pixel of the result is read from the pixels it covers: an area average when an axis is reduced and a Catmull-Rom cubic when it is enlarged, chosen per axis. The aspect ratio is not preserved; tiny_image_fit is the call that preserves it.

One operation on its own is one pass. A chain of them is a pass each, and TinyPlan is what collapses a chain into one.

Parameters

image	Pointer to the TinyImage structure to be resized.
new_width	The desired width in pixels. Zero keeps the aspect ratio against new_height.
new_height	The desired height in pixels. Zero keeps the aspect ratio against new_width.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE when both are zero, TINYIMG_ERR_TOO_LARGE past TINYIMG_MAX_PIXELS, or TINYIMG_ERR_MEMORY.

tiny_image_rotate()

int tiny_image_rotate	(	TinyImage *	image,
		float	degrees,
		const uint8_t *	background )

Turns the image by any angle.

The extent grows to hold the turned image, so a 45 degree turn of a square is a larger square with the original standing on a corner.

Parameters

image	The image, replaced by the result.
degrees	Clockwise. A multiple of 90 goes through the exact kernel and loses nothing.
background	What the corners are filled with, or NULL for transparent.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_rotate_180()

int tiny_image_rotate_180

(

TinyImage *

image

)

Rotates an image 180 degrees.

Parameters

image

Pointer to the TinyImage structure to be rotated.

Returns

int 0 on success, non-zero on failure (e.g., if the image is NULL).

tiny_image_rotate_270()

int tiny_image_rotate_270

(

TinyImage *

image

)

Rotates an image 270 degrees clockwise (or 90 degrees counterclockwise).

Parameters

image

Pointer to the TinyImage structure to be rotated.

Returns

int 0 on success, non-zero on failure (e.g., if the image is NULL).

tiny_image_rotate_90()

int tiny_image_rotate_90

(

TinyImage *

image

)

Rotates an image 90 degrees clockwise.

Parameters

image

Pointer to the TinyImage structure to be rotated.

Returns

int 0 on success, non-zero on failure (e.g., if the image is NULL).

tiny_image_saturation()

int tiny_image_saturation	(	TinyImage *	image,
		float	factor )

Adjusts the saturation of the image.

This function modifies the image's color saturation by adjusting its saturation value. A higher saturation value results in more vivid colors, while a lower saturation value results in more muted colors. The function will resample the image data accordingly to maintain the visual quality of the image.

Parameters

image	Pointer to the TinyImage structure whose saturation is to be adjusted.
factor	The factor by which to adjust the saturation. A value of 1.0 means no change, less than 1.0 decreases saturation, and greater than 1.0 increases saturation.

Returns

int 0 on success, non-zero on failure (e.g., if the image is NULL or if the factor is invalid).

tiny_image_scanlines()

int tiny_image_scanlines	(	TinyImage *	image,
		uint32_t	period,
		float	strength )

Darkens every nth row.

Parameters

image	The image to change.
period	How many rows between darkened ones.
strength	How much darker, 0 through 1.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_set_exif()

int tiny_image_set_exif	(	TinyImage *	image,
		const char *	exif_data,
		size_t	exif_size )

Sets the EXIF metadata for the image.

This function allows you to set the EXIF metadata for the image, which can include information such as camera settings, date and time, GPS location, and more. The EXIF data is provided as a byte array, and the size of the data must be specified.

Parameters

image	Pointer to the TinyImage structure for which to set the EXIF metadata.
exif_data	Pointer to a byte array containing the EXIF metadata to be set for the image.
exif_size	The size of the EXIF data in bytes.

Returns

int 0 on success, non-zero on failure (e.g., if the image is NULL or if the EXIF data is invalid).

tiny_image_set_metadata()

int tiny_image_set_metadata	(	TinyImage *	image,
		const char *	key,
		const char *	value )

Sets a custom metadata key-value pair for the image.

This function allows you to set a custom metadata key-value pair for the image. The key and value are provided as strings, and they can be used to store additional information about the image that is not covered by standard EXIF metadata.

Parameters

image	Pointer to the TinyImage structure for which to set the custom metadata.
key	The key for the custom metadata (e.g., "Author", "Description").
value	The value associated with the specified key.

Returns

int 0 on success, non-zero on failure (e.g., if the image is NULL or if the key or value is invalid).

tiny_image_set_transparent()

int tiny_image_set_transparent	(	TinyImage *	image,
		int	enable_transparency )

Sets the transparency of the image.

This function enables or disables transparency for the image. If enable_transparency is non-zero, the image will be set to support transparency (if applicable). If enable_transparency is zero, the image will be set to not support transparency.

Setting a non-transparent image to support transparency may result in the addition of an alpha channel, which can increase the image's memory usage and file size. Setting a transparent image to not support transparency may result in the removal of the alpha channel and the background being filled with white or black, depending on the image format and implementation.

Parameters

image	Pointer to the TinyImage structure for which to set transparency.
enable_transparency	Non-zero to enable transparency, zero to disable it.

tiny_image_setpixel()

int tiny_image_setpixel	(	TinyImage *	image,
		uint32_t	x,
		uint32_t	y,
		const uint8_t *	pixel )

Writes the pixel value at the specified (x, y) coordinates in the image.

A plain bounds checked write with no blending. The drawing region composites.

Parameters

image	Pointer to the TinyImage structure to write into.
x	The x-coordinate of the pixel (0-based index).
y	The y-coordinate of the pixel (0-based index).
pixel	Pointer to a uint8_t array containing the pixel value. The size of the array should match the number of channels in the image type.

Returns

int TINYIMG_OK, TINYIMG_ERR_NULL, or TINYIMG_ERR_BOUNDS when the coordinates fall outside the image.

tiny_image_shadows_highlights()

int tiny_image_shadows_highlights	(	TinyImage *	image,
		float	shadows,
		float	highlights )

Recovers detail at both ends of the range.

Parameters

image	The image to change.
shadows	How much to lift the dark end, 0 through 1.
highlights	How much to pull the light end down, 0 through 1.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_sharpen()

int tiny_image_sharpen	(	TinyImage *	image,
		float	amount )

Applies a sharpen effect to the image.

Parameters

image	Pointer to the TinyImage structure to be sharpened.
amount	The amount of sharpening to apply. Must be a positive float.

Returns

int 0 on success, non-zero on failure (e.g., if the image is NULL or if the amount is invalid).

tiny_image_shear()

int tiny_image_shear	(	TinyImage *	image,
		float	shear_x,
		float	shear_y,
		const uint8_t *	background )

Slants the image along one or both axes.

The extent grows to hold the result, so nothing is cut off.

Parameters

image	The image, replaced by the result.
shear_x	How far each row moves per row down.
shear_y	How far each column moves per column right.
background	What the corners are filled with, or NULL for transparent.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_sizeof()

uint32_t tiny_image_sizeof

(

void

)

Size of a TinyImage, for a host allocating one across the wasm boundary.

The struct layout is not part of the ABI; the accessors below are. This exists so a host can reserve the right number of bytes without knowing the layout.

Returns

uint32_t sizeof(TinyImage).

tiny_image_sobel()

int tiny_image_sobel

(

TinyImage *

image

)

Replaces the image with its Sobel gradient magnitude.

Parameters

image

The image to change.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_solarize()

int tiny_image_solarize	(	TinyImage *	image,
		uint8_t	level )

Inverts only the channels above a level.

Parameters

image	The image to change.
level	Where the inversion begins.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_split_tone()

int tiny_image_split_tone	(	TinyImage *	image,
		const uint8_t *	shadow,
		const uint8_t *	highlight,
		float	balance )

Tints the shadows and the highlights differently.

Parameters

image	The image to change.
shadow	The shadows' cast, three channels.
highlight	The highlights' cast.
balance	Where the two meet, 0 through 1; 0.5 is mid gray.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_strip_exif()

int tiny_image_strip_exif

(

TinyImage *

image

)

Strips the EXIF metadata from the image.

This function removes any existing EXIF metadata from the image, effectively clearing any camera settings, date and time, GPS location, and other information that may have been stored in the EXIF data.

Parameters

image

Pointer to the TinyImage structure from which to strip the EXIF metadata.

Returns

int 0 on success, non-zero on failure (e.g., if the image is NULL).

tiny_image_swirl()

int tiny_image_swirl	(	TinyImage *	image,
		float	degrees )

Twists the image about its center, most at the center.

Parameters

image	The image to change.
degrees	How far the center turns.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_temperature()

int tiny_image_temperature	(	TinyImage *	image,
		float	amount )

Shifts the white point along the blue to amber axis.

Parameters

image	The image to change.
amount	-1 is fully cool, 1 fully warm, 0 changes nothing.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_threshold()

int tiny_image_threshold	(	TinyImage *	image,
		uint8_t	level )

Drives every channel to nothing or to full scale.

Parameters

image	The image to change.
level	Where the split falls, 0 through 255.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_tilt_shift()

int tiny_image_tilt_shift	(	TinyImage *	image,
		float	sigma,
		float	band )

Blurs away from a horizontal band left sharp.

Parameters

image	The image to change.
sigma	The blur at the furthest row.
band	How much of the height stays sharp, 0 through 1.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_tint()

int tiny_image_tint	(	TinyImage *	image,
		const uint8_t *	color,
		float	strength )

Adds a color cast without touching the luminance.

Parameters

image	The image to change.
color	The cast, three channels.
strength	0 changes nothing.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_to_grayscale()

int tiny_image_to_grayscale

(

TinyImage *

image

)

Converts the image to grayscale.

Luminance is weighted by Rec. 709, matching what a browser's grayscale filter produces.

Parameters

image

Pointer to the TinyImage structure to be converted to grayscale.

Returns

int TINYIMG_OK, TINYIMG_ERR_NULL, or TINYIMG_ERR_MEMORY.

tiny_image_to_rgb()

int tiny_image_to_rgb

(

TinyImage *

image

)

Converts the image to RGB format.

Parameters

image

Pointer to the TinyImage structure to be converted to RGB.

Returns

int 0 on success, non-zero on failure (e.g., if the image is NULL).

tiny_image_to_rgba()

int tiny_image_to_rgba

(

TinyImage *

image

)

Converts the image to RGBA format, adding an opaque alpha channel if there was none.

Parameters

image

Pointer to the TinyImage structure to be converted to RGBA.

Returns

int TINYIMG_OK, TINYIMG_ERR_NULL, or TINYIMG_ERR_MEMORY.

tiny_image_trim()

int tiny_image_trim	(	TinyImage *	image,
		uint8_t	tolerance )

Removes a uniform border by cropping to what differs from it.

The border color is taken from the corners, which is what a caller trimming whitespace or letterboxing means. An image whose corners already differ from each other is left alone.

The scan works inward from each edge and stops at the first row or column that differs, so it costs the border it removes rather than the image.

This is not a plan operation, and cannot be: tiny_plan_resolve decides the whole pipeline before any pixel is read, and how much a trim removes is a function of the pixels. A caller that wants a trim inside a chain runs it between two plans.

Parameters

image	The image, replaced by the cropped one.
tolerance	How far a channel may differ from the border color and still count as border, 0 through 255.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE when nothing would be left, or a negative TinyImageError.

tiny_image_unpremultiply()

int tiny_image_unpremultiply

(

TinyImage *

image

)

Divides each color channel by its alpha.

The inverse of tiny_image_premultiply, and lossy in the same way every inverse of a quantized product is: a channel that was rounded to a multiple of its alpha cannot be recovered exactly. A fully transparent pixel has no color to recover and is left at zero.

Parameters

image

The image to change.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_unsharp_mask()

int tiny_image_unsharp_mask	(	TinyImage *	image,
		float	sigma,
		float	amount,
		float	threshold )

Adds back a multiple of what a blur removed.

Parameters

image	The image to change.
sigma	The blur's standard deviation.
amount	How much of the difference to add back.
threshold	Differences at or below this are left alone, which keeps flat areas from gaining noise.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_vibrance()

int tiny_image_vibrance	(	TinyImage *	image,
		float	amount )

Raises saturation, and least where it is already high.

Parameters

image	The image to change.
amount	0 changes nothing.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_vignette()

int tiny_image_vignette	(	TinyImage *	image,
		float	radius,
		float	strength,
		const uint8_t *	color )

Applies a vignette effect to the image.

This function darkens the edges of the image, creating a vignette effect. The radius parameter controls how far the darkening extends from the center of the image, and the strength parameter controls how dark the edges become. The color parameter specifies the color to be used for the vignette effect.

Parameters

image	Pointer to the TinyImage structure to be modified with the vignette effect.
radius	The radius of the vignette effect, in pixels. Must be a positive float greater than 0.
strength	The strength of the vignette effect, where 0.0 means no effect and 1.0 means full effect. Must be a float value between 0.0 and 1.0.
color	Pointer to a uint8_t array specifying the color to be used for the vignette effect. The size of the array should match the number of channels in the image type (e.g., 3 for RGB, 4 for RGBA).

Returns

int 0 on success, non-zero on failure (e.g., if the image is NULL or if parameters are invalid).

tiny_image_vline()

int tiny_image_vline	(	TinyImage *	image,
		int32_t	x1,
		int32_t	y1,
		int32_t	x2,
		int32_t	y2,
		const uint8_t *	pixel )

Draws a vertical run of pixels.

Parameters

image	The image to draw on.
x1	The column. x2 is ignored.
y1	One end.
x2	Ignored.
y2	The other end. May be above y1.
pixel	As many channels as the image has.

Returns

int TINYIMG_OK or a negative TinyImageError.

tiny_image_white_balance()

int tiny_image_white_balance	(	TinyImage *	image,
		float	temperature,
		float	tint )

Shifts the white point along both axes at once.

Parameters

image	The image to change.
temperature	-1 cool through 1 warm.
tint	-1 green through 1 magenta.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_image_zoom()

int tiny_image_zoom	(	TinyImage *	image,
		float	zoom_factor )

Zooms in or out of the image by the specified zoom factor.

A zoom factor greater than 1.0 will zoom in (enlarge) the image, while a zoom factor less than 1.0 will zoom out (shrink) the image. The function modifies the pixel values of the image accordingly.

Parameters

image	Pointer to the TinyImage structure to be zoomed.
zoom_factor	The factor by which to zoom the image. Must be a positive float greater than 0.

Returns

int 0 on success, non-zero on failure (e.g., if the image is NULL or if the zoom factor is invalid).

tiny_image_zoom_blur()

int tiny_image_zoom_blur	(	TinyImage *	image,
		float	strength )

Averages along rays from the center.

Parameters

image	The image to change.
strength	How far, as a percentage of the distance from the center.

Returns

int TINYIMG_OK, TINYIMG_ERR_RANGE, or a negative TinyImageError.

tiny_phash_distance()

uint32_t tiny_phash_distance	(	uint64_t	first,
		uint64_t	second )

How many bits two perceptual hashes differ in.

Parameters

first	One hash.
second	The other.

Returns

uint32_t The count, 0 through 64.