The transform IR, the rewrites that run over it, and the executor. More...

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

Classes
struct	TinyPlanOp
	One operation and its operands. More...
struct	TinyPlan
	A sequence of operations over one source, and the source itself. More...
struct	TinyPlanResolution
	What the planner decided, before any pixel is touched. More...
struct	TinyColorStage
	One collapsed color operation. More...

Macros
#define	TINYIMG_PLAN_MAX_OPS 32
	How many operations one plan holds.

Typedefs
typedef enum TinyPlanOpKind	TinyPlanOpKind
	The operations a plan can hold.
typedef enum TinyCurveKind	TinyCurveKind
	The tone curves TINYIMG_OP_CURVE can carry.
typedef enum TinyEffectKind	TinyEffectKind
	The neighborhood effects TINYIMG_OP_EFFECT can carry.
typedef enum TinyPlanOpClass	TinyPlanOpClass
	What the planner needs to know about an operation to place it.
typedef enum TinyResampleFilter	TinyResampleFilter
	Which weights the resampler reads a source pixel through.
typedef enum TinyPlanKernel	TinyPlanKernel
	Special cases the planner took, reported as a bitmask.
typedef enum TinyPlanField	TinyPlanField
	A field of a TinyPlanResolution, named rather than offset.

Enumerations
enum	TinyPlanOpKind { TINYIMG_OP_NONE = 0 , TINYIMG_OP_CROP = 1 , TINYIMG_OP_RESIZE = 2 , TINYIMG_OP_FIT = 3 , TINYIMG_OP_FLIP_H = 4 , TINYIMG_OP_FLIP_V = 5 , TINYIMG_OP_ROTATE = 6 , TINYIMG_OP_BRIGHTNESS = 7 , TINYIMG_OP_CONTRAST = 8 , TINYIMG_OP_SATURATION = 9 , TINYIMG_OP_HUE = 10 , TINYIMG_OP_GRAYSCALE = 11 , TINYIMG_OP_INVERT = 12 , TINYIMG_OP_GAMMA = 13 , TINYIMG_OP_BLUR = 14 , TINYIMG_OP_MATRIX = 15 , TINYIMG_OP_CURVE = 16 , TINYIMG_OP_EFFECT = 17 }
	The operations a plan can hold. More...
enum	TinyCurveKind { TINYIMG_CURVE_GAMMA = 0 , TINYIMG_CURVE_POSTERIZE = 1 , TINYIMG_CURVE_THRESHOLD = 2 , TINYIMG_CURVE_SOLARIZE = 3 , TINYIMG_CURVE_EXPOSURE = 4 , TINYIMG_CURVE_LEVELS = 5 , TINYIMG_CURVE_FILL_LIGHT = 6 , TINYIMG_CURVE_GAIN = 7 , TINYIMG_CURVE_SIGMOID = 8 , TINYIMG_CURVE_NEGATE = 9 , TINYIMG_CURVE_SRGB = 10 , TINYIMG_CURVE_BALANCE = 11 }
	The tone curves TINYIMG_OP_CURVE can carry. More...
enum	TinyEffectKind { TINYIMG_FX_UNSHARP = 0 , TINYIMG_FX_CLARITY = 1 , TINYIMG_FX_SOBEL = 2 , TINYIMG_FX_EMBOSS = 3 , TINYIMG_FX_PIXELATE = 4 , TINYIMG_FX_MEDIAN = 5 , TINYIMG_FX_DILATE = 6 , TINYIMG_FX_ERODE = 7 , TINYIMG_FX_OUTLINE = 8 , TINYIMG_FX_MOTION_BLUR = 9 , TINYIMG_FX_RADIAL_BLUR = 10 , TINYIMG_FX_ZOOM_BLUR = 11 , TINYIMG_FX_TILT_SHIFT = 12 , TINYIMG_FX_BLUR_REGION = 13 , TINYIMG_FX_PIXELATE_REGION = 14 , TINYIMG_FX_CHROMATIC = 15 , TINYIMG_FX_DITHER = 16 , TINYIMG_FX_HALFTONE = 17 , TINYIMG_FX_SCANLINES = 18 }
	The neighborhood effects TINYIMG_OP_EFFECT can carry. More...
enum	TinyPlanOpClass { TINYIMG_OP_CLASS_GEOMETRY = 0 , TINYIMG_OP_CLASS_COLOR_MATRIX = 1 , TINYIMG_OP_CLASS_COLOR_LUT = 2 , TINYIMG_OP_CLASS_NEIGHBORHOOD = 3 }
	What the planner needs to know about an operation to place it. More...
enum	TinyResampleFilter { TINYIMG_FILTER_AUTO = 0 , TINYIMG_FILTER_NEAREST = 1 , TINYIMG_FILTER_BILINEAR = 2 , TINYIMG_FILTER_BOX = 3 , TINYIMG_FILTER_CATMULL_ROM = 4 }
	Which weights the resampler reads a source pixel through. More...
enum	TinyPlanKernel { TINYIMG_KERNEL_REGION = 1 << 0 , TINYIMG_KERNEL_SCALED = 1 << 1 , TINYIMG_KERNEL_COPY = 1 << 2 , TINYIMG_KERNEL_RESAMPLE = 1 << 3 , TINYIMG_KERNEL_ORIENT = 1 << 4 , TINYIMG_KERNEL_COLOR = 1 << 5 , TINYIMG_KERNEL_PAD = 1 << 6 , TINYIMG_KERNEL_GRAY_DECODE = 1 << 7 , TINYIMG_KERNEL_NEIGHBORHOOD = 1 << 8 }
	Special cases the planner took, reported as a bitmask. More...
enum	TinyPlanField { TINYIMG_FIELD_REGION_X = 0 , TINYIMG_FIELD_REGION_Y = 1 , TINYIMG_FIELD_REGION_WIDTH = 2 , TINYIMG_FIELD_REGION_HEIGHT = 3 , TINYIMG_FIELD_SCALE = 4 , TINYIMG_FIELD_DECODE_WIDTH = 5 , TINYIMG_FIELD_DECODE_HEIGHT = 6 , TINYIMG_FIELD_WIDTH = 7 , TINYIMG_FIELD_HEIGHT = 8 , TINYIMG_FIELD_CHANNELS = 9 , TINYIMG_FIELD_OPS = 10 , TINYIMG_FIELD_ELIMINATED = 11 , TINYIMG_FIELD_COLLAPSED = 12 , TINYIMG_FIELD_COLOR_STAGES = 13 , TINYIMG_FIELD_PASSES = 14 , TINYIMG_FIELD_KERNELS = 15 }
	A field of a TinyPlanResolution, named rather than offset. More...

Functions
uint32_t	tiny_plan_sizeof (void)
	Size of a TinyPlan, for a host allocating one across the wasm boundary.
uint32_t	tiny_plan_resolution_sizeof (void)
	Size of a TinyPlanResolution, for the same reason.
int	tiny_plan_init (TinyPlan plan, const uint8_t buffer, size_t size)
	Starts a plan over encoded bytes.
int	tiny_plan_init_image (TinyPlan plan, const TinyImage image)
	Starts a plan over pixels that are already decoded.
int	tiny_plan_set_fusion (TinyPlan *plan, int enabled)
	Chooses whether the plan fuses.
int	tiny_plan_set_effort (TinyPlan *plan, uint8_t effort)
	Chooses how much work the plan's decode may spend.
int	tiny_plan_background (TinyPlan plan, const uint8_t color)
	Sets what padding is filled with.
int	tiny_plan_crop (TinyPlan *plan, uint32_t x, uint32_t y, uint32_t width, uint32_t height)
	Appends a crop.
int	tiny_plan_resize (TinyPlan *plan, uint32_t width, uint32_t height)
	Appends a resize with the filter the planner would choose.
int	tiny_plan_resize_with (TinyPlan *plan, uint32_t width, uint32_t height, TinyResampleFilter filter)
	Appends a resize through a named filter.
int	tiny_plan_fit (TinyPlan *plan, uint32_t width, uint32_t height, TinyImageFit mode, TinyImageGravity gravity)
	Appends a fit, which resolves to a scale and a crop or a pad.
int	tiny_plan_fit_with (TinyPlan *plan, uint32_t width, uint32_t height, TinyImageFit mode, TinyImageGravity gravity, TinyResampleFilter filter)
	Appends a fit that samples through a named filter.
int	tiny_plan_flip_horizontal (TinyPlan *plan)
	Appends a horizontal flip.
int	tiny_plan_flip_vertical (TinyPlan *plan)
	Appends a vertical flip.
int	tiny_plan_rotate (TinyPlan *plan, int32_t degrees)
	Appends a turn.
int	tiny_plan_brightness (TinyPlan *plan, float factor)
	Appends a brightness change.
int	tiny_plan_contrast (TinyPlan *plan, float factor)
	Appends a contrast change.
int	tiny_plan_saturation (TinyPlan *plan, float factor)
	Appends a saturation change.
int	tiny_plan_hue (TinyPlan *plan, float degrees)
	Appends a hue rotation.
int	tiny_plan_grayscale (TinyPlan *plan)
	Appends a conversion to luminance.
int	tiny_plan_invert (TinyPlan *plan)
	Appends an inversion.
int	tiny_plan_gamma (TinyPlan *plan, float gamma)
	Appends a gamma correction.
int	tiny_plan_blur (TinyPlan *plan, float radius)
	Appends a box blur.
int	tiny_plan_gaussian_blur (TinyPlan *plan, float sigma)
	Appends a gaussian blur.
int	tiny_plan_matrix (TinyPlan plan, const float matrix)
	Appends a color matrix.
int	tiny_plan_curve (TinyPlan plan, TinyCurveKind kind, const float params, uint8_t channels)
	Appends a tone curve.
int	tiny_plan_effect (TinyPlan plan, TinyEffectKind kind, const float params)
	Appends a neighborhood effect.
int	tiny_plan_effect_rect (TinyPlan plan, TinyEffectKind kind, const float params, uint32_t x, uint32_t y, uint32_t width, uint32_t height)
	Appends a neighborhood effect confined to a rectangle.
uint32_t	tiny_plan_count (const TinyPlan *plan)
	How many operations a plan holds, before any rewrite.
int	tiny_plan_op_at (const TinyPlan plan, uint32_t index, TinyPlanOp op)
	Reads one appended operation out.
TinyPlanOpClass	tiny_plan_op_class (TinyPlanOpKind kind)
	What class the planner puts an operation in.
uint32_t	tiny_plan_cost (const TinyPlan *plan)
	What running this plan is expected to cost, in microseconds.
uint32_t	tiny_encode_cost (TinyImageFormat format, uint32_t width, uint32_t height)
	What encoding an image of this extent is expected to cost.
uint32_t	tiny_plan_field (const TinyPlanResolution *resolution, TinyPlanField field)
	Reads one named field of a resolution.
int	tiny_plan_resolve (const TinyPlan plan, TinyPlanResolution resolution)
	Runs the rewrites and the propagation, touching no pixels.
int	tiny_plan_color_stages (const TinyPlanResolution resolution, TinyColorStage stages, uint32_t capacity, uint32_t *count)
	Collapses a resolved plan's color operations into stages.
int	tiny_plan_replace (TinyImage image, TinyPlan plan)
	Runs a plan over an image and puts the result in its place.
int	tiny_effect_apply (TinyImage image, const TinyPlanOp op)
	Runs one TINYIMG_OP_EFFECT operation over a materialized image.
int	tiny_plan_blur_box (TinyImage *image, uint32_t radius)
	Blurs an image with one box pass of the given radius.
int	tiny_plan_run (const TinyPlan plan, TinyImage out)
	Runs the plan and produces the output image.
int	tiny_plan_encode (const TinyPlan plan, TinyImageFormat format, const TinyEncodeOpts opts, TinyWriter *writer)
	Runs the plan and encodes the result in one call.

Detailed Description

The transform IR, the rewrites that run over it, and the executor.

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

Version: 1.0.0

Date: 2026-09-03

Copyright: Copyright (c) 2026

Macro Definition Documentation

◆ TINYIMG_PLAN_MAX_OPS

#define TINYIMG_PLAN_MAX_OPS 32

How many operations one plan holds.

A fixed capacity, so a TinyPlan is an ordinary structure a caller keeps on the stack and the planner never touches the allocator to build one. A chain longer than this is a caller that means to run two transforms.

Typedef Documentation

◆ TinyCurveKind

typedef enum TinyCurveKind TinyCurveKind

The tone curves TINYIMG_OP_CURVE can carry.

A curve is named and parameterized rather than carried as a table, because a 768 byte table inline would make one operation larger than the whole rest of a plan and a plan is a structure a caller keeps on the stack. A caller's own table is still reachable: tiny_image_apply_lut takes one and runs it as a single pass, which is the escape hatch rather than the default.

◆ TinyEffectKind

typedef enum TinyEffectKind TinyEffectKind

The neighborhood effects TINYIMG_OP_EFFECT can carry.

Every one of these reads more than one pixel, so they share the class that ends a fused pass. What separates them is the kernel and the parameters, not anything the planner needs to know, which is why one operation kind carries them all.

◆ TinyPlanField

typedef enum TinyPlanField TinyPlanField

A field of a TinyPlanResolution, named rather than offset.

TinyPlanResolution's layout is not part of the ABI, so a host that read it by computing offsets would be reading whatever the C compiler chose that day. The awkward part is not the prefix, which is fixed; it is that TinyPlanOp op[TINYIMG_PLAN_MAX_OPS] sits in the middle, so every counter after it moves whenever an operand grows. Naming the fields is what makes the decision readable from the outside without pinning the structure.

◆ TinyPlanKernel

typedef enum TinyPlanKernel TinyPlanKernel

Special cases the planner took, reported as a bitmask.

Every bit is an assertion a test can make about a plan rather than about its pixels, which is the only way to tell a plan that was optimized from one that happened to produce the same image.

◆ TinyPlanOpClass

typedef enum TinyPlanOpClass TinyPlanOpClass

What the planner needs to know about an operation to place it.

The class is the whole contract for adding an operation: pick the one that describes how the operation reads its input, and every rewrite, the ROI walk and the executor already know what to do with it. Nothing else in the planner is written per operation.

◆ TinyPlanOpKind

typedef enum TinyPlanOpKind TinyPlanOpKind

The operations a plan can hold.

Appending to this enum is additive; the values are part of the ABI and are read by the host wrapper, so an operation is never renumbered.

Enumeration Type Documentation

◆ TinyCurveKind

enum TinyCurveKind

The tone curves TINYIMG_OP_CURVE can carry.

A curve is named and parameterized rather than carried as a table, because a 768 byte table inline would make one operation larger than the whole rest of a plan and a plan is a structure a caller keeps on the stack. A caller's own table is still reachable: tiny_image_apply_lut takes one and runs it as a single pass, which is the escape hatch rather than the default.

Enumerator
TINYIMG_CURVE_GAMMA	Raise to a power; p[0] is the exponent.
TINYIMG_CURVE_POSTERIZE	Round to p[0] evenly spaced levels.
TINYIMG_CURVE_THRESHOLD	Zero below p[0], full above it.
TINYIMG_CURVE_SOLARIZE	Invert above p[0], leaving the rest alone.
TINYIMG_CURVE_EXPOSURE	Scale by two to the power p[0], in stops.
TINYIMG_CURVE_LEVELS	Map p[0]..p[1] onto p[3]..p[4] through gamma p[2]. The five-number levels control, so one curve covers the whole of it and a per-channel levels request is three of these with different masks.
TINYIMG_CURVE_FILL_LIGHT	Lift the shadows by p[0] without moving the highlights.
TINYIMG_CURVE_GAIN	Multiply by p[0].
TINYIMG_CURVE_SIGMOID	An S-curve of strength p[0] about mid gray.
TINYIMG_CURVE_NEGATE	Subtract from full scale.
TINYIMG_CURVE_SRGB	Encode linear light as sRGB, or decode it when p[0] is negative.
TINYIMG_CURVE_BALANCE	Shift the shadows by p[0], the midtones by p[1] and the highlights by p[2], each weighted by how much of the pixel is in that band. One channel of a color balance. The three bands overlap, so a shift applied to one of them does not leave a step where it meets the next.

◆ TinyEffectKind

enum TinyEffectKind

The neighborhood effects TINYIMG_OP_EFFECT can carry.

Every one of these reads more than one pixel, so they share the class that ends a fused pass. What separates them is the kernel and the parameters, not anything the planner needs to know, which is why one operation kind carries them all.

Enumerator
TINYIMG_FX_UNSHARP	Unsharp mask; p[0] sigma, p[1] amount, p[2] threshold.
TINYIMG_FX_CLARITY	Local contrast, an unsharp mask at a large radius.
TINYIMG_FX_SOBEL	Sobel gradient magnitude.
TINYIMG_FX_EMBOSS	Directional 3x3 emboss.
TINYIMG_FX_PIXELATE	Average over p[0] by p[0] blocks.
TINYIMG_FX_MEDIAN	Replace each pixel with the median of its 3x3 neighborhood.
TINYIMG_FX_DILATE	Maximum over a p[0] radius.
TINYIMG_FX_ERODE	Minimum over a p[0] radius.
TINYIMG_FX_OUTLINE	Difference between a dilation and an erosion.
TINYIMG_FX_MOTION_BLUR	Average along p[0] pixels at p[1] degrees.
TINYIMG_FX_RADIAL_BLUR	Average along arcs about the center; p[0] is the strength.
TINYIMG_FX_ZOOM_BLUR	Average along rays from the center; p[0] is the strength.
TINYIMG_FX_TILT_SHIFT	A blur that grows away from a band; p[0] sigma, p[1] band.
TINYIMG_FX_BLUR_REGION	Gaussian blur inside the rectangle only.
TINYIMG_FX_PIXELATE_REGION	Pixelate inside the rectangle only.
TINYIMG_FX_CHROMATIC	Offset the red and blue channels by p[0] pixels.
TINYIMG_FX_DITHER	Ordered dither to p[0] levels through a Bayer matrix.
TINYIMG_FX_HALFTONE	Cluster-dot halftone at cell size p[0].
TINYIMG_FX_SCANLINES	Darken every p[0]th row by p[1].

◆ TinyPlanField

enum TinyPlanField

A field of a TinyPlanResolution, named rather than offset.

TinyPlanResolution's layout is not part of the ABI, so a host that read it by computing offsets would be reading whatever the C compiler chose that day. The awkward part is not the prefix, which is fixed; it is that TinyPlanOp op[TINYIMG_PLAN_MAX_OPS] sits in the middle, so every counter after it moves whenever an operand grows. Naming the fields is what makes the decision readable from the outside without pinning the structure.

Enumerator
TINYIMG_FIELD_REGION_X	Left edge of the region the decoder is asked for, in source pixels.
TINYIMG_FIELD_REGION_Y	Top edge of that region.
TINYIMG_FIELD_REGION_WIDTH	Width of that region.
TINYIMG_FIELD_REGION_HEIGHT	Height of that region.
TINYIMG_FIELD_SCALE	Subsampling denominator the decoder is asked for: 1, 2, 4 or 8.
TINYIMG_FIELD_DECODE_WIDTH	Width the decode produces.
TINYIMG_FIELD_DECODE_HEIGHT	Height the decode produces.
TINYIMG_FIELD_WIDTH	Width of the final image.
TINYIMG_FIELD_HEIGHT	Height of the final image.
TINYIMG_FIELD_CHANNELS	Channels of the final image.
TINYIMG_FIELD_OPS	Operations left after the rewrites.
TINYIMG_FIELD_ELIMINATED	Operations an identity or annihilation rule removed.
TINYIMG_FIELD_COLLAPSED	Operations a pair rule merged into another.
TINYIMG_FIELD_COLOR_STAGES	Color stages the operations collapsed into.
TINYIMG_FIELD_PASSES	Fused passes tiny_plan_run will make.
TINYIMG_FIELD_KERNELS	A bitmask of TinyPlanKernel.

◆ TinyPlanKernel

enum TinyPlanKernel

Special cases the planner took, reported as a bitmask.

Every bit is an assertion a test can make about a plan rather than about its pixels, which is the only way to tell a plan that was optimized from one that happened to produce the same image.

Enumerator
TINYIMG_KERNEL_REGION	The pass reads a rectangle of its source rather than all of it.
TINYIMG_KERNEL_SCALED	The decode ran at a scale denominator above 1.
TINYIMG_KERNEL_COPY	The output is the decoded pixels with nothing done to them.
TINYIMG_KERNEL_RESAMPLE	A resample runs.
TINYIMG_KERNEL_ORIENT	A flip or a quarter turn runs, folded into the output addressing.
TINYIMG_KERNEL_COLOR	At least one color stage runs.
TINYIMG_KERNEL_PAD	The output is larger than the resampled image and the rest is filled.
TINYIMG_KERNEL_GRAY_DECODE	The decoder produced the luminance, so no color stage was needed.
TINYIMG_KERNEL_NEIGHBORHOOD	A neighborhood operation runs on a materialized image.

◆ TinyPlanOpClass

enum TinyPlanOpClass

What the planner needs to know about an operation to place it.

The class is the whole contract for adding an operation: pick the one that describes how the operation reads its input, and every rewrite, the ROI walk and the executor already know what to do with it. Nothing else in the planner is written per operation.

Enumerator
TINYIMG_OP_CLASS_GEOMETRY	Moves pixels without changing their values. Folds into the accumulated source window, the sample map and the orientation, so any number of these cost one pass between them.
TINYIMG_OP_CLASS_COLOR_MATRIX	Reads one pixel and is affine in its channels. Composes with its neighbors by matrix multiplication, so any number of these cost one matrix between them.
TINYIMG_OP_CLASS_COLOR_LUT	Reads one pixel and is not affine in its channels. Composes with its neighbors through the lookup table, so any number of these cost one table between them.
TINYIMG_OP_CLASS_NEIGHBORHOOD	Reads a neighborhood around each pixel. Cannot fold into a sample map, so it ends a fused pass and its input is materialized. It is also what stops resolution propagation, unless a rewrite has already moved it after the downscale.

◆ TinyPlanOpKind

enum TinyPlanOpKind

The operations a plan can hold.

Appending to this enum is additive; the values are part of the ABI and are read by the host wrapper, so an operation is never renumbered.

Enumerator
TINYIMG_OP_NONE	An empty slot, which a rewrite leaves behind and the resolved op list never contains.
TINYIMG_OP_CROP	Take a rectangle, in the coordinates the previous operation produced.
TINYIMG_OP_RESIZE	Resample to an extent.
TINYIMG_OP_FIT	Resample and crop or pad according to a TinyImageFit mode.
TINYIMG_OP_FLIP_H	Mirror along the vertical axis.
TINYIMG_OP_FLIP_V	Mirror along the horizontal axis.
TINYIMG_OP_ROTATE	Turn by a multiple of 90 degrees clockwise.
TINYIMG_OP_BRIGHTNESS	Scale every channel by a factor.
TINYIMG_OP_CONTRAST	Scale every channel about mid gray.
TINYIMG_OP_SATURATION	Move every channel toward or away from its luminance.
TINYIMG_OP_HUE	Rotate the hue by an angle in degrees.
TINYIMG_OP_GRAYSCALE	Replace every channel with the pixel's luminance.
TINYIMG_OP_INVERT	Subtract every channel from 255, leaving alpha alone.
TINYIMG_OP_GAMMA	Raise every channel to a power.
TINYIMG_OP_BLUR	Average each pixel with its neighbors.
TINYIMG_OP_MATRIX	Apply a caller-supplied 3x4 color matrix.
TINYIMG_OP_CURVE	Apply a named tone curve, per channel.
TINYIMG_OP_EFFECT	Apply a named neighborhood effect.

◆ TinyResampleFilter

enum TinyResampleFilter

Which weights the resampler reads a source pixel through.

Enumerator
TINYIMG_FILTER_AUTO	Box when the axis is being reduced, Catmull-Rom when it is being enlarged, chosen per axis. The right answer for almost every request: an area average is what a reduction means, and it is what every codec in this library does for its own scaled decode, so a plan that reduces through the decoder and then through the resampler is doing one kind of thing twice rather than two different kinds once.
TINYIMG_FILTER_NEAREST	One source pixel per output pixel.
TINYIMG_FILTER_BILINEAR	Two samples per axis, weighted by the fractional position.
TINYIMG_FILTER_BOX	Every source pixel the output pixel covers, averaged.
TINYIMG_FILTER_CATMULL_ROM	Four samples per axis through the Catmull-Rom cubic.

Function Documentation

◆ tiny_encode_cost()

uint32_t tiny_encode_cost	(	TinyImageFormat	format,
		uint32_t	width,
		uint32_t	height )

What encoding an image of this extent is expected to cost.

Separate from tiny_plan_cost so a caller choosing between formats can price each one without building a plan per candidate. The spread is the reason the function exists: at the rates measured, PNG costs 29 times JPEG per sample and WebP costs 4, so a request that does not fit as WebP may fit as JPEG.

Parameters

format	The format to write.
width	Output width.
height	Output height.

Returns: uint32_t Microseconds, or 0 for a format this build cannot write.

◆ tiny_plan_background()

int tiny_plan_background	(	TinyPlan *	plan,
		const uint8_t *	color )

Sets what padding is filled with.

Parameters

plan	The plan.
color	As many channels as the output will have. NULL restores the default, which is transparent, or black when the output has no alpha.

Returns: int TINYIMG_OK or TINYIMG_ERR_NULL.

◆ tiny_plan_blur()

int tiny_plan_blur	(	TinyPlan *	plan,
		float	radius )

Appends a box blur.

Parameters

plan	The plan.
radius	Pixels either side. Zero changes nothing and is eliminated.

Returns: int TINYIMG_OK, TINYIMG_ERR_NULL, TINYIMG_ERR_RANGE for a negative radius, or TINYIMG_ERR_PLAN.

◆ tiny_plan_brightness()

int tiny_plan_brightness	(	TinyPlan *	plan,
		float	factor )

Appends a brightness change.

Parameters

plan	The plan.
factor	1.0 changes nothing and is eliminated.

Returns: int TINYIMG_OK, TINYIMG_ERR_NULL, TINYIMG_ERR_RANGE for a negative factor, or TINYIMG_ERR_PLAN.

◆ tiny_plan_contrast()

int tiny_plan_contrast	(	TinyPlan *	plan,
		float	factor )

Appends a contrast change.

Parameters

plan	The plan.
factor	1.0 changes nothing and is eliminated.

Returns: int TINYIMG_OK, TINYIMG_ERR_NULL, TINYIMG_ERR_RANGE for a negative factor, or TINYIMG_ERR_PLAN.

◆ tiny_plan_cost()

uint32_t tiny_plan_cost ( const TinyPlan * plan )

What running this plan is expected to cost, in microseconds.

For deciding whether a request fits a CPU budget before spending any of it. The plan is resolved, which reads the source header and no pixels, so this costs about as much as tiny_plan_resolve and nothing like the plan itself.

This is an estimate and says so. The rates come from scripts/measure/calibrate.ts on one machine, and a machine of a different speed wants all of them scaled. Measured against real transforms it lands within about 20%, which is the accuracy a budget question needs when the question is whether 7 milliseconds of work will fit inside 10. It is not a substitute for measuring: a caller that needs to know what a request cost should read the work counters afterwards.

The encoder is not included, because a plan does not carry one. Add tiny_encode_cost for the format being written.

Parameters

plan	The plan to price.

Returns: uint32_t Microseconds, or 0 when the plan cannot be resolved or its source header cannot be read.

◆ tiny_plan_count()

uint32_t tiny_plan_count ( const TinyPlan * plan )

How many operations a plan holds, before any rewrite.

Parameters

plan The plan.

Returns: uint32_t The count, or 0 when the plan is NULL.

◆ tiny_plan_crop()

int tiny_plan_crop	(	TinyPlan *	plan,
		uint32_t	x,
		uint32_t	y,
		uint32_t	width,
		uint32_t	height )

Appends a crop.

The rectangle is in the coordinates the previous operation produces, not in source pixels, so a crop after a resize means what it reads like.

Parameters

plan	The plan.
x	Left edge.
y	Top edge.
width	Width; zero means to the right edge.
height	Height; zero means to the bottom edge.

Returns: int TINYIMG_OK, TINYIMG_ERR_NULL, or TINYIMG_ERR_PLAN when the plan is full.

◆ tiny_plan_curve()

int tiny_plan_curve	(	TinyPlan *	plan,
		TinyCurveKind	kind,
		const float *	params,
		uint8_t	channels )

Appends a tone curve.

The generic form of every color operation that is not affine. Adjacent curves compose through the table, so any number of them cost one table.

Parameters

plan	The plan.
kind	Which curve.
params	Its parameters, up to five, read according to kind. NULL is the same as all zero.
channels	Which channels to apply it to, bit 0 red through bit 2 blue; zero means all three.

Returns: int TINYIMG_OK, TINYIMG_ERR_NULL, TINYIMG_ERR_RANGE for a parameter the curve cannot take, or TINYIMG_ERR_PLAN.

◆ tiny_plan_effect()

int tiny_plan_effect	(	TinyPlan *	plan,
		TinyEffectKind	kind,
		const float *	params )

Appends a neighborhood effect.

Parameters

plan	The plan.
kind	Which effect.
params	Its parameters, up to four. NULL is the same as all zero.

Returns: int TINYIMG_OK, TINYIMG_ERR_NULL, TINYIMG_ERR_RANGE, or TINYIMG_ERR_PLAN.

◆ tiny_plan_effect_rect()

int tiny_plan_effect_rect	(	TinyPlan *	plan,
		TinyEffectKind	kind,
		const float *	params,
		uint32_t	x,
		uint32_t	y,
		uint32_t	width,
		uint32_t	height )

Appends a neighborhood effect confined to a rectangle.

Parameters

plan	The plan.
kind	Which effect.
params	Its parameters, up to four. NULL is the same as all zero.
x	Left edge.
y	Top edge.
width	Width; zero means to the right edge.
height	Height; zero means to the bottom edge.

Returns: int TINYIMG_OK, TINYIMG_ERR_NULL, TINYIMG_ERR_RANGE, or TINYIMG_ERR_PLAN.

◆ tiny_plan_encode()

int tiny_plan_encode	(	const TinyPlan *	plan,
		TinyImageFormat	format,
		const TinyEncodeOpts *	opts,
		TinyWriter *	writer )

Runs the plan and encodes the result in one call.

Parameters

plan	The plan.
format	The container to write.
opts	Quality and related settings, or NULL for the defaults.
writer	An initialized TinyWriter to append to.

Returns: int TINYIMG_OK or a negative TinyImageError.

◆ tiny_plan_field()

uint32_t tiny_plan_field	(	const TinyPlanResolution *	resolution,
		TinyPlanField	field )

Reads one named field of a resolution.

One accessor rather than sixteen, because every field a host wants is an unsigned integer and sixteen exports would cost more module bytes than the switch does.

Parameters

resolution	A resolution from tiny_plan_resolve.
field	Which field.

Returns: uint32_t Its value, or 0 for a NULL resolution or an unknown field.

◆ tiny_plan_fit()

int tiny_plan_fit	(	TinyPlan *	plan,
		uint32_t	width,
		uint32_t	height,
		TinyImageFit	mode,
		TinyImageGravity	gravity )

Appends a fit, which resolves to a scale and a crop or a pad.

Parameters

plan	The plan.
width	Target width.
height	Target height.
mode	How the aspect mismatch is absorbed and how the scale is clamped; see TinyImageFit.
gravity	Which part of the image a crop keeps, or where a pad puts it.

Returns: int TINYIMG_OK, TINYIMG_ERR_NULL, TINYIMG_ERR_RANGE, or TINYIMG_ERR_PLAN.

◆ tiny_plan_fit_with()

int tiny_plan_fit_with	(	TinyPlan *	plan,
		uint32_t	width,
		uint32_t	height,
		TinyImageFit	mode,
		TinyImageGravity	gravity,
		TinyResampleFilter	filter )

Appends a fit that samples through a named filter.

tiny_plan_fit leaves the filter to the planner, which is the right default and what almost every caller wants. This exists because a caller who names a filter for a resize has no way to name one for a fit, and an option that is accepted and then ignored is worse than one that does not exist.

Parameters

plan	The plan.
width	Target width.
height	Target height.
mode	How the aspect mismatch is absorbed and how the scale is clamped; see TinyImageFit.
gravity	Which part of the image a crop keeps, or where a pad puts it.
filter	The weights to sample through. TINYIMG_FILTER_AUTO is what tiny_plan_fit passes.

Returns: int TINYIMG_OK, TINYIMG_ERR_NULL, TINYIMG_ERR_RANGE, or TINYIMG_ERR_PLAN.

◆ tiny_plan_flip_horizontal()

int tiny_plan_flip_horizontal ( TinyPlan * plan )

Appends a horizontal flip.

Parameters

plan The plan.

Returns: int TINYIMG_OK, TINYIMG_ERR_NULL, or TINYIMG_ERR_PLAN.

◆ tiny_plan_flip_vertical()

int tiny_plan_flip_vertical ( TinyPlan * plan )

Appends a vertical flip.

Parameters

plan The plan.

Returns: int TINYIMG_OK, TINYIMG_ERR_NULL, or TINYIMG_ERR_PLAN.

◆ tiny_plan_gamma()

int tiny_plan_gamma	(	TinyPlan *	plan,
		float	gamma )

Appends a gamma correction.

Parameters

plan	The plan.
gamma	Above 1.0 darkens; 1.0 changes nothing and is eliminated.

Returns: int TINYIMG_OK, TINYIMG_ERR_NULL, TINYIMG_ERR_RANGE for a non-positive gamma, or TINYIMG_ERR_PLAN.

◆ tiny_plan_gaussian_blur()

int tiny_plan_gaussian_blur	(	TinyPlan *	plan,
		float	sigma )

Appends a gaussian blur.

Three box passes, which converge on a gaussian and cost the same as one regardless of sigma.

Parameters

plan	The plan.
sigma	Standard deviation in pixels. Zero changes nothing and is eliminated.

Returns: int TINYIMG_OK, TINYIMG_ERR_NULL, TINYIMG_ERR_RANGE for a negative sigma, or TINYIMG_ERR_PLAN.

◆ tiny_plan_grayscale()

int tiny_plan_grayscale ( TinyPlan * plan )

Appends a conversion to luminance.

The output keeps its alpha channel and loses the other two, so an RGBA source becomes two channels and an RGB source becomes one.

Parameters

plan The plan.

Returns: int TINYIMG_OK, TINYIMG_ERR_NULL, or TINYIMG_ERR_PLAN.

◆ tiny_plan_hue()

int tiny_plan_hue	(	TinyPlan *	plan,
		float	degrees )

Appends a hue rotation.

Parameters

plan	The plan.
degrees	Any angle; a multiple of 360 changes nothing and is eliminated.

Returns: int TINYIMG_OK, TINYIMG_ERR_NULL, or TINYIMG_ERR_PLAN.

◆ tiny_plan_init()

int tiny_plan_init	(	TinyPlan *	plan,
		const uint8_t *	buffer,
		size_t	size )

Starts a plan over encoded bytes.

Reads the header to learn the source's dimensions and nothing else; no pixel is decoded until tiny_plan_run, which is what lets the planner choose the decode. The buffer is borrowed and must outlive the plan.

Parameters

plan	The plan to initialize.
buffer	The encoded image.
size	Number of bytes.

Returns: int TINYIMG_OK, TINYIMG_ERR_UNKNOWN_FORMAT, or a negative TinyImageError from the probe.

◆ tiny_plan_init_image()

int tiny_plan_init_image	(	TinyPlan *	plan,
		const TinyImage *	image )

Starts a plan over pixels that are already decoded.

The escape hatch, and the form the eager operations in image.h are written in. There is no decode to choose, so the region and resolution propagation have nothing to do; every other rewrite still runs. The image is borrowed and is never written to.

Parameters

plan	The plan to initialize.
image	The source pixels.

Returns: int TINYIMG_OK or TINYIMG_ERR_NULL.

◆ tiny_plan_invert()

int tiny_plan_invert ( TinyPlan * plan )

Appends an inversion.

Parameters

plan The plan.

Returns: int TINYIMG_OK, TINYIMG_ERR_NULL, or TINYIMG_ERR_PLAN.

◆ tiny_plan_matrix()

int tiny_plan_matrix	(	TinyPlan *	plan,
		const float *	matrix )

Appends a color matrix.

The generic form of every affine color operation in the library. Sepia, a channel mixer, a white balance and a colorblind simulation are all one of these, so they compose with each other and with brightness, contrast, saturation and hue into the single matrix the executor applies.

Parameters

plan	The plan.
matrix	Row major 3x4 applied to RGB, in the 0..255 range. The identity is eliminated.

Returns: int TINYIMG_OK, TINYIMG_ERR_NULL, or TINYIMG_ERR_PLAN.

◆ tiny_plan_op_at()

int tiny_plan_op_at	(	const TinyPlan *	plan,
		uint32_t	index,
		TinyPlanOp *	op )

Reads one appended operation out.

Parameters

plan	The plan.
index	Zero based, below tiny_plan_count.
op	Receives the operation.

Returns: int TINYIMG_OK, TINYIMG_ERR_NULL, or TINYIMG_ERR_BOUNDS.

◆ tiny_plan_op_class()

TinyPlanOpClass tiny_plan_op_class ( TinyPlanOpKind kind )

What class the planner puts an operation in.

Parameters

kind	The operation.

Returns: TinyPlanOpClass Its class; an unknown kind reads as geometry, which is the class that assumes the least about the pixels.

◆ tiny_plan_resize()

int tiny_plan_resize	(	TinyPlan *	plan,
		uint32_t	width,
		uint32_t	height )

Appends a resize with the filter the planner would choose.

Parameters

plan	The plan.
width	Target width. Zero keeps the aspect ratio against height.
height	Target height. Zero keeps the aspect ratio against width.

Returns: int TINYIMG_OK, TINYIMG_ERR_NULL, TINYIMG_ERR_RANGE when both are zero, or TINYIMG_ERR_PLAN.

◆ tiny_plan_resize_with()

int tiny_plan_resize_with	(	TinyPlan *	plan,
		uint32_t	width,
		uint32_t	height,
		TinyResampleFilter	filter )

Appends a resize through a named filter.

Parameters

plan	The plan.
width	Target width. Zero keeps the aspect ratio.
height	Target height. Zero keeps the aspect ratio.
filter	The weights to sample through.

Returns: int TINYIMG_OK, TINYIMG_ERR_NULL, TINYIMG_ERR_RANGE, or TINYIMG_ERR_PLAN.

◆ tiny_plan_resolution_sizeof()

uint32_t tiny_plan_resolution_sizeof ( void )

Size of a TinyPlanResolution, for the same reason.

Returns: uint32_t sizeof(TinyPlanResolution).

◆ tiny_plan_resolve()

int tiny_plan_resolve	(	const TinyPlan *	plan,
		TinyPlanResolution *	resolution )

Runs the rewrites and the propagation, touching no pixels.

Everything the planner decides is here: which operations survived, what rectangle of the source at what scale the decoder is asked for, the window and extent the resample works over, the composed orientation, and which special cases were taken. Calling it is free relative to a decode, so a caller that wants to log the saving can.

Parameters

plan	The plan.
resolution	Receives the decision.

Returns: int TINYIMG_OK, TINYIMG_ERR_NULL, TINYIMG_ERR_RANGE for an operation that leaves nothing to produce, or TINYIMG_ERR_TOO_LARGE past TINYIMG_MAX_PIXELS or TINYIMG_MAX_IMAGE_BYTES. Both caps are checked here rather than left to the executor, so a plan that resolves is a plan that can allocate its output.

◆ tiny_plan_rotate()

int tiny_plan_rotate	(	TinyPlan *	plan,
		int32_t	degrees )

Appends a turn.

Parameters

plan	The plan.
degrees	Clockwise, and a multiple of 90. Negative and past 360 are both reduced.

Returns: int TINYIMG_OK, TINYIMG_ERR_NULL, TINYIMG_ERR_RANGE when the angle is not a multiple of 90, or TINYIMG_ERR_PLAN.

◆ tiny_plan_run()

int tiny_plan_run	(	const TinyPlan *	plan,
		TinyImage *	out )

Runs the plan and produces the output image.

Parameters

plan	The plan.
out	Receives the output. Its previous contents are not freed.

Returns: int TINYIMG_OK or a negative TinyImageError.

◆ tiny_plan_saturation()

int tiny_plan_saturation	(	TinyPlan *	plan,
		float	factor )

Appends a saturation change.

Parameters

plan	The plan.
factor	1.0 changes nothing and is eliminated; 0.0 is a grayscale that keeps three channels.

Returns: int TINYIMG_OK, TINYIMG_ERR_NULL, TINYIMG_ERR_RANGE for a negative factor, or TINYIMG_ERR_PLAN.

◆ tiny_plan_set_effort()

int tiny_plan_set_effort	(	TinyPlan *	plan,
		uint8_t	effort )

Chooses how much work the plan's decode may spend.

TINYIMG_EFFORT_FANCY, the default, decodes to the bitstream's definition. TINYIMG_EFFORT_FAST lets a lossy decoder drop its smoothing pass: VP8 skips deblocking and JPEG replicates chroma rather than interpolating it. A lossless format has nothing to drop and is unaffected.

Separate from the encoder's effort, which is set on TinyEncodeOpts, because a request can want one and not the other: a thumbnail small enough to hide a decode approximation may still want a carefully searched encode.

Parameters

plan	The plan.
effort	A TinyEffort.

Returns: int TINYIMG_OK, TINYIMG_ERR_NULL, or TINYIMG_ERR_RANGE for a value that is not a TinyEffort.

◆ tiny_plan_set_fusion()

int tiny_plan_set_fusion	(	TinyPlan *	plan,
		int	enabled )

Chooses whether the plan fuses.

On, which is the default, the plan collapses into as few passes as the operations allow.

Off, nothing is rewritten, the source is decoded whole, and every operation as appended runs as its own pass over a materialized image. That is what the fused path is measured against, and it is the benchmark's planner-off arm. Both paths share one resampler, so a difference between them is a fault in the rewrites, the collapse or the region arithmetic, and cannot be a fault in the sampling.

Parameters

plan	The plan.
enabled	Non-zero to fuse.

Returns: int TINYIMG_OK or TINYIMG_ERR_NULL.

◆ tiny_plan_sizeof()

uint32_t tiny_plan_sizeof ( void )

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

Returns: uint32_t sizeof(TinyPlan).

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ TINYIMG_PLAN_MAX_OPS

Typedef Documentation

◆ TinyCurveKind

◆ TinyEffectKind

◆ TinyPlanField

◆ TinyPlanKernel

◆ TinyPlanOpClass

◆ TinyPlanOpKind

Enumeration Type Documentation

◆ TinyCurveKind

◆ TinyEffectKind

◆ TinyPlanField

◆ TinyPlanKernel

◆ TinyPlanOpClass

◆ TinyPlanOpKind

◆ TinyResampleFilter

Function Documentation

◆ tiny_encode_cost()

◆ tiny_plan_background()

◆ tiny_plan_blur()

◆ tiny_plan_brightness()

◆ tiny_plan_contrast()

◆ tiny_plan_cost()

◆ tiny_plan_count()

◆ tiny_plan_crop()

◆ tiny_plan_curve()

◆ tiny_plan_effect()

◆ tiny_plan_effect_rect()

◆ tiny_plan_encode()

◆ tiny_plan_field()

◆ tiny_plan_fit()

◆ tiny_plan_fit_with()

◆ tiny_plan_flip_horizontal()

◆ tiny_plan_flip_vertical()

◆ tiny_plan_gamma()

◆ tiny_plan_gaussian_blur()

◆ tiny_plan_grayscale()

◆ tiny_plan_hue()

◆ tiny_plan_init()

◆ tiny_plan_init_image()

◆ tiny_plan_invert()

◆ tiny_plan_matrix()

◆ tiny_plan_op_at()

◆ tiny_plan_op_class()

◆ tiny_plan_resize()

◆ tiny_plan_resize_with()

◆ tiny_plan_resolution_sizeof()

◆ tiny_plan_resolve()

◆ tiny_plan_rotate()

◆ tiny_plan_run()

◆ tiny_plan_saturation()

◆ tiny_plan_set_effort()

◆ tiny_plan_set_fusion()

◆ tiny_plan_sizeof()