PlutoFilter

PlutoFilter is a single-header, zero-allocation image filter library written in C. It applies fast, chainable image effects without any dynamic memory allocation. Compatible with SVG and CSS filter semantics, it makes it easy to reproduce visual effects consistently across platforms.

Installation

PlutoFilter is a self-contained, single-header library written in standard C99. It can be used in two modes: header-only or implementation. In header-only mode, simply include the header in any source or header file. This exposes all API declarations but does not include the implementation.

To include the actual implementation, define PLUTOFILTER_IMPLEMENTATION in one .c or .cpp file before including the header:

#define PLUTOFILTER_IMPLEMENTATION
#include "plutofilter.h"

In all other source files, include the header as usual:

#include "plutofilter.h"

The macro PLUTOFILTER_API controls the linkage of public functions. By default, it expands to extern, but if you define PLUTOFILTER_BUILD_STATIC before including the header, all functions will be declared static instead. This is useful when embedding the library in a single translation unit to avoid symbol collisions.

Example

#define PLUTOFILTER_IMPLEMENTATION
#include "plutofilter.h"

// Replace with real image I/O implementations
extern plutofilter_surface_t load_image(const char* filename);
extern void write_image(plutofilter_surface_t surface, const char* filename);

int main(void)
{
    plutofilter_surface_t surface = load_image("input.jpg");

    // filter: contrast(97%) hue-rotate(330deg) saturate(111%)
    plutofilter_color_transform_contrast(surface, surface, 0.97f);
    plutofilter_color_transform_hue_rotate(surface, surface, 330.0f);
    plutofilter_color_transform_saturate(surface, surface, 1.11f);

    write_image(surface, "output.jpg");
    return 0;
}

input.jpg	output.jpg

Features

• Gaussian Blur

• Color Transform

  • Grayscale
  • Sepia
  • Saturate
  • Brightness
  • Contrast
  • Opacity
  • Invert
  • Hue Rotate
  • Luminance to Alpha
  • LinearRGB to sRGB
  • sRGB to LinearRGB

• Blend

  • Normal
  • Multiply
  • Screen
  • Overlay
  • Darken
  • Lighten
  • Color Dodge
  • Color Burn
  • Hard Light
  • Soft Light
  • Difference
  • Exclusion
  • Hue
  • Saturation
  • Color
  • Luminosity

• Composite

  • Over
  • In
  • Out
  • Atop
  • Xor
  • Arithmetic

Roadmap

• Morphology
• Diffuse Lighting
• Specular Lighting
• Convolve Matrix
• Displacement Map
• Turbulence

Gaussian Blur

void plutofilter_gaussian_blur(plutofilter_surface_t in, plutofilter_surface_t out, float std_deviation_x, float std_deviation_y);

Applies a Gaussian blur to the input surface using separable convolution. The amount of blur is controlled by the standard deviation along the horizontal and vertical axes. A value of 0 applies no blur.

0x0	5x5	10x10

Color Transform

void plutofilter_color_transform(plutofilter_surface_t in, plutofilter_surface_t out, const float matrix[20]);

Applies a 5×4 color transformation matrix to each pixel in the input surface. The matrix operates on color and alpha channels, allowing both isolated and cross-channel transformations. The input and output surfaces may be the same for in-place filtering.

Example

const float original[20] = {
    1.0f, 0.0f, 0.0f, 0.0f, 0.0f,
    0.0f, 1.0f, 0.0f, 0.0f, 0.0f,
    0.0f, 0.0f, 1.0f, 0.0f, 0.0f,
    0.0f, 0.0f, 0.0f, 1.0f, 0.0f
};

const float grayscale[20] = {
    0.2126f, 0.7152f, 0.0722f, 0.0f, 0.0f,
    0.2126f, 0.7152f, 0.0722f, 0.0f, 0.0f,
    0.2126f, 0.7152f, 0.0722f, 0.0f, 0.0f,
    0.0f,    0.0f,    0.0f,    1.0f, 0.0f
};

const float sepia[20] = {
    0.393f, 0.769f, 0.189f, 0.0f, 0.0f,
    0.349f, 0.686f, 0.168f, 0.0f, 0.0f,
    0.272f, 0.534f, 0.131f, 0.0f, 0.0f,
    0.0f,   0.0f,   0.0f,   1.0f, 0.0f
};

const float contrast[20] = {
    1.75f, 0.0f,  0.0f,  0.0f, -0.375f,
    0.0f,  1.75f, 0.0f,  0.0f, -0.375f,
    0.0f,  0.0f,  1.75f, 0.0f, -0.375f,
    0.0f,  0.0f,  0.0f,  1.0f,   0.0f
};

original	grayscale	sepia	contrast

Grayscale

void plutofilter_color_transform_grayscale(plutofilter_surface_t in, plutofilter_surface_t out, float amount);

Applies a grayscale effect to the input surface, controlled by a blending amount between the original color and fully desaturated grayscale. A value of 0 preserves the original image, while 1 results in complete grayscale.

0	0.25	0.5	0.75	1

Sepia

void plutofilter_color_transform_sepia(plutofilter_surface_t in, plutofilter_surface_t out, float amount);

Applies a sepia tone to the input surface, blending between the original image and a warm, brownish tone. The amount controls the intensity, where 0 leaves the image unchanged and 1 applies full sepia coloration.

0	0.25	0.5	0.75	1

Saturate

void plutofilter_color_transform_saturate(plutofilter_surface_t in, plutofilter_surface_t out, float amount);

Adjusts the color saturation of the input surface. The amount controls how vivid or muted the colors become: 1 leaves the image unchanged, values less than 1 reduce saturation toward grayscale, and values greater than 1 enhance the intensity of colors.

1	4	0.5	0

Contrast

void plutofilter_color_transform_contrast(plutofilter_surface_t in, plutofilter_surface_t out, float amount);

Adjusts the contrast of the input surface. An amount of 1 leaves the image unchanged, values below 1 reduce contrast, and values above 1 increase it. The image is scaled around the midpoint of the color range.

1	1.75	0.5	0

Brightness

void plutofilter_color_transform_brightness(plutofilter_surface_t in, plutofilter_surface_t out, float amount);

Adjusts the brightness of the input surface. An amount of 1 preserves the original brightness, values below 1 darken the image, and values above 1 brighten it uniformly across all color channels.

1	1.75	0.5	0

Opacity

void plutofilter_color_transform_opacity(plutofilter_surface_t in, plutofilter_surface_t out, float amount);

Adjusts the opacity (alpha) of the input surface. An amount of 1 leaves opacity unchanged, while values between 0 and 1 scale the alpha channel linearly. A value of 0 makes the image fully transparent.

1	0.75	0.5	0.25	0

Invert

void plutofilter_color_transform_invert(plutofilter_surface_t in, plutofilter_surface_t out, float amount);

Applies a color inversion effect to the input surface. The amount controls the strength of the inversion: 0 leaves the image unchanged, 1 fully inverts the RGB channels, and intermediate values blend between the original and inverted colors.

0	0.25	0.5	0.75	1

Hue Rotate

void plutofilter_color_transform_hue_rotate(plutofilter_surface_t in, plutofilter_surface_t out, float degrees);

Rotates the hue of each pixel in the input surface by the given angle in degrees. The rotation is applied in the RGB color space, preserving luminance and alpha. A value of 0 leaves colors unchanged, while 360 completes a full rotation back to the original.

0°	30°	90°	180°	270°	360°

Blend

void plutofilter_blend(plutofilter_surface_t in1, plutofilter_surface_t in2, plutofilter_surface_t out, plutofilter_blend_mode_t mode);

Blends two surfaces using the specified blend mode. The source surface (in1) is blended over the backdrop (in2), and the result is written to out.

Mode	Input 1	Input 2	Output	Explanation
Normal				Displays in1 over in2 using standard alpha compositing.
Multiply				Multiplies the colors of in1 and in2, resulting in a darker image.
Screen				Brightens the result by inverting, multiplying, and inverting again.
Overlay				Applies Multiply on dark areas and Screen on light areas to add contrast.
Darken				Keeps the darker color of each pixel from in1 or in2.
Lighten				Keeps the lighter color of each pixel from in1 or in2.
Color Dodge				Brightens in2 based on the content of in1 by dividing by the inverse.
Color Burn				Darkens in2 based on in1 by dividing the inverse of in2 by in1.
Hard Light				A strong effect that applies Overlay with in1 as the source.
Soft Light				Gently adjusts contrast based on in1, giving a softer result.
Difference				Subtracts the darker color from the lighter one at each pixel.
Exclusion				Similar to Difference, but with reduced contrast and softer transitions.

Composite

void plutofilter_composite(plutofilter_surface_t in1, plutofilter_surface_t in2, plutofilter_surface_t out, plutofilter_composite_operator_t op);

Composites two surfaces using a Porter-Duff compositing operator. The source surface (in1) is composited over the backdrop (in2) using the specified operator. The result is written to out.

Operator	Input 1	Input 2	Output	Explanation
Over				Draws in1 over in2, preserving transparency. This is the default mode.
In				Shows the part of in1 that overlaps with in2. Everything else is hidden.
Out				Shows the part of in1 that lies outside in2. Removes overlapping areas.
Atop				Keeps the overlapping part of in1, but only where in2 is present.
Xor				Combines the non-overlapping parts of in1 and in2. Removes the overlap.

Arithmetic

void plutofilter_composite_arithmetic(plutofilter_surface_t in1, plutofilter_surface_t in2, plutofilter_surface_t out, float k1, float k2, float k3, float k4);

Blends two input surfaces using a flexible arithmetic combination of their color values. The output is based on the colors from both inputs, combined according to the four constants: k1, k2, k3, and k4.

Input 1	Input 2	k1	k2	k3	k4	Output
		0	1	1	0
		0.5	0.5	0.5	0
		1	0	0	0
		1	0	0	0.5