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 i