php-io-extensions / paint
Shapes painted straight into pixels in C: PaintSurface fills paths, ellipses, rounded boxes, shadows and thin lines, in a colour or a gradient
Package info
github.com/php-io-extensions/paint
Language:C
Type:php-ext
Ext name:ext-paint
pkg:composer/php-io-extensions/paint
Requires
- php: >=8.4
Requires (Dev)
- pestphp/pest: ^4.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-19 13:36:07 UTC
README
ext-paint
Shapes painted straight into pixels in C, for PHP 8.4+
Drawing a filled shape means deciding, for every pixel near it, how much of that pixel the shape covers, and then mixing the shape's colour into the pixel by that amount. In PHP that is a loop over rows and a walk along each edge through the pixels it crosses, with float arithmetic in the middle and four byte writes at the end. ext-paint works the covered area out exactly, from the shape's edges and curves, instead of sampling it.
ext-paint runs those loops in C. You hand it a list of shapes and their paints; it works out the coverage and blends them into 32-bit pixels, its own or memory you already hold. It has no dependency, no window, no fonts and no drawing state: shapes go in, pixels change, and the same input gives the same bytes on every platform.
Basic usage
$surface = new PaintSurface(320, 200); $surface->clear(0x101820FF, 0, 0, 320, 200); $surface->fill( [ [PAINT_PATH, [[40, 160, 160, 30, 280, 160]], PAINT_NON_ZERO], // a triangle [PAINT_ELLIPSE, 160, 110, 40, 40], [PAINT_ROUND_RECT, 20, 170, 300, 190, [8, 8, 8, 8]], ], [0xF2AA4CFF, 0xFFFFFF80, 0x2E86DEFF], // one paint an op, 0xRRGGBBAA 0, 0, 320, 200, // paint nothing outside this rect ); $rgba = $surface->bytes(); // 320 * 200 * 4 bytes, rows top first
Examples
A gradient is a paint: a ramp of 256 colours and six numbers that take a pixel to a position along it.
$ramp = ''; for ($i = 0; $i < 256; $i++) { $ramp .= chr($i).chr(0).chr(255 - $i)."\xFF"; // blue to red } // u = px / 320: left edge is the ramp's start, right edge its end $surface->fill([[PAINT_ROUND_RECT, 0, 0, 320, 200, [0, 0, 0, 0]]], [[PAINT_LINEAR, PAINT_PAD, $ramp, 1 / 320, 0, 0, 0, 0, 0]], 0, 0, 320, 200);
Paint into pixels another extension holds, with nothing copied:
$surface = PaintSurface::over($address, $width, $height, $stride, PAINT_ORDER_BGRA, $owner); $boxes = $surface->fill($ops, $paints, 0, 0, $width, $height); // the rect each op covered, or null
over() trusts the address. It is for a caller that already holds native memory; $owner is kept alive for as long as the surface is.
Hard edges, where a pixel is in when its centre is:
$surface->fill($ops, $paints, 0, 0, 320, 200, antialias: false);
Requirements
- PHP 8.4 or later, NTS or ZTS
- Linux or macOS
- A C compiler and the PHP development headers. No system library.
Installation
With PHP PIE (recommended)
pie install php-io-extensions/paint
Manually (install script)
./install-macos.sh # Homebrew php@8.4 and php@8.4-zts ./install-debian-trixie.sh # Debian trixie, Raspberry Pi OS
Manually (phpize)
phpize ./configure --enable-paint make sudo make install
Then add extension=paint to your php.ini.
Verify
php -r 'var_dump(extension_loaded("paint"));'
API
The full reference, with how coverage and blending are worked step by step, is in .okf/api/surface.md.
PaintSurface
| Method | What it does |
|---|---|
new PaintSurface(width, height, order = PAINT_ORDER_RGBA) |
A surface with its own pixels, every byte 0 |
PaintSurface::over(address, width, height, stride, order, owner) |
A surface over memory something else holds |
width(), height() |
The sides |
bytes() |
The pixels, rows tight |
clear(rgba, x, y, width, height) |
Set a rect to a colour, not blended |
fill(ops, paints, x, y, width, height, antialias = true) |
Paint each op with its paint inside a rect |
Ops
| Kind | Op |
|---|---|
PAINT_PATH |
[kind, contours, rule], a contour a flat list x0, y0, x1, y1, ... |
PAINT_ELLIPSE |
[kind, cx, cy, rx, ry] |
PAINT_RING |
[kind, cx, cy, rx, ry, stroke] |
PAINT_ROUND_RECT |
[kind, x0, y0, x1, y1, [tl, tr, br, bl]] |
PAINT_ROUND_RING |
[kind, x0, y0, x1, y1, [tl, tr, br, bl], inset] |
PAINT_SHADOW |
[kind, x0, y0, x1, y1, radius, blur] |
PAINT_POLYLINE |
[kind, [x0, y0, x1, y1, ...], closed], one-pixel lines |
A wide stroke is a path: work out its outline and fill it.
Paints
A colour 0xRRGGBBAA, or a gradient [kind, spread, ramp, a, b, c, d, e, f] with kind PAINT_LINEAR or PAINT_RADIAL and spread PAINT_PAD, PAINT_REPEAT or PAINT_REFLECT.
What is refused
An op, a paint or a number that is not one is a ValueError naming the op. fill() paints one op at a time, so the ops before a refused one have been painted.
Testing
composer install vendor/bin/pest
License
MIT. See LICENSE.