raster

0.0.0

A library for software rasterisation

About Raster

This is a portable software rasterisation library. It implements many primitives to perform drawing operations in software onto a portable and ubiquitous format: 8-bit RGBA pixel buffers.

Basic Operation

We'll assume the package org.shirakumo.raster is nicknamed to raster. You can perform simple raster operations with the with-drawing macro and the draw commands:

(raster:with-drawing (800 600)
  (raster:draw-line 10 10 100 100)
  (raster:draw-line 10 20 100 100 :sampler (raster:encode-color 255 0 0))
  (raster:draw-rectangle 400 300 100 100 :sampler (raster:encode-color 0 255 0 128))
  (raster:draw-ellipse 800 600 200 100 :feather 10)
  (raster:with-rect-clip (0 0 100 100)
    (raster:draw-ellipse 100 100 50 50)))

This will return the completed image into which the shapes were drawn. Please see the respective functions for all available options.

Compositing and Sampling

Most draw-* calls are relatively simple wrappers over composite-sdf. Sometimes though it can be too expensive to perform raster operations via SDFs. In this case you may want to either draw pixels directly yourself via color-ref and color-ref*, or at least handle the compositing of different buffers and samplers.

blit-buffer simply copies pixels from one buffer's sub-region to another. It does not perform interpolation, so it can't stretch or squash the image.

composite-buffer composites the pixels from one buffer onto another with basic "source-over" alpha blending applied. This is typically how two images are combined.

composite-mask does the same but using an arbitrary sampler and an alpha mask to determine which pixels to draw to.

composite-sdf finally is the same as composite-mask but instead of using an explicit mask, it relies on an sdf function to provide the mask.

A sampler is a function that simply returns a color value for a given pixel index pair. The underlying source can be a constant colour (via solid-color), another image (via sampler), a gradient (via radial-gradient, linear-gradient, bilinear-gradient, diamond-gradient, or conical-gradient), or some other function that computes the colour value to use.

The primary sampler constructed from an image also allows you to rotate and transform the image arbitrarily. To do this it uses the sample-color function to access pixels, which performs bilinear interpolation of colours as needed.

Signed Distance Fields

Most drawing operations happen via Signed Distance Fields. These are functions that represent the distance to an outline as a signed number, positive being outside, negative inside. They are a very convenient representation of shapes, since they can easily be combined together and evaluated to produce blurred and anti-aliased shapes.

This library provides a variety of functions to create sdfs for particular shapes:

And to combine or manipulate them:

While SDFs are extremely convenient in this way, be aware that the more complex the shape, the more expensive it gets to evaluate and thus raster the SDF, so they aren't suitable for everything, especially when performance is crucial.

System Information

0.0.0
Yukari Hafner
zlib
https://shirakumo.github.io/raster/
https://github.com/shirakumo/raster/issues
https://github.com/shirakumo/raster.git

Definition Index