# FixImage Documentation

- Version: 0.2
- Homepage
- ChangeLog

This library allows you to use and draw 2D images.

Features:

- images up to 16384x16384 size can be used
- the only supported format is ARGB with premultiplied alpha
- direct access to pixels (as shared array)
- built-in PNG loader/writer
- downscaling of images
- fractional blur with radius independent performance (both faster and more accurate Gaussian approximations)
- ability to apply color ramps
- painting with 2D transforms
- fast clearing & painting of pixel aligned rectangles
- high performance 2D shape rasterizer with maximum quality (255x antialiasing)
- subpixel rendering
- gamma adjusted rendering
- simple shaders support
- nearest, bilinear & bicubic image filtering
- shape outlining
- TrueType font support
- uses SSE2 and multiple CPU cores
- optional batched rendering for better performance and full utilization of CPU cores
- licensed under ZLIB license (no attribution required in binary builds)

## Format

All images are stored in ARGB format. Each pixel is 32-bit integer divided into four 8bit quantities. The order of channels is A,R,G,B (from highest order to lowest). For example, a fully opaque yellow color is 0xFF FF FF 00.

The alpha channel determines how translucent the pixel is. The format uses premultiplied alpha which means that color channels are multiplied with alpha (as if represented in the normalized 0-1 range). For example a half-transparent yellow color is 0x80 80 80 00. This allows for correct filtering and better performance. You can think of it as the more transparent the pixel is the less important the color is up into a fully transparent pixel where the color is completely meaningless.

As a side-effect this format also supports additive blending (with smooth transition between normal and additive blending when filtering), simply use zero alpha and non-zero color channels, it will be just added into the image instead of blending. However this is not supported for all operations (for example gamma adjusted rendering requires to convert back to normal representation).

## Shaders

Some drawing functions accept shaders. These are small special purpose code fragments optimized for computing the resulting color. The syntax looks like this:

    use "image/shaders"; // at the beginning of the file
    use "classes";
    ...
    var factor = 128;
    p.fill_rect(0, 0, 100, 100, Shader {
        var color = sample_bilinear(img, tr, CLAMP_X|CLAMP_Y);
        blend(mix(color, 0x00000000, factor) * 0x80808080);
    });

The shader is created using the `Shader {}` construct. The body can contain these statements:

    var name = <expression>;
    blend(<expression>);
    replace(<expression>);

That means you can declare variables and issue either blending with the output, or replacing the output with the color derived from the expression.

In expressions you can use hexadecimal literals to directly provide constant color (in premultiplied format), or use the `rgb` and `argb` functions to convert from the normal format. You can directly reference outside variables by an identifier, or if it's a more complex expression you can wrap it in `$(...)` fragment (the body is normal FixScript code). You can use parenthesis in the expressions to group operations as needed, you can add/subtract/multiply pixel values (each component is processed separately using saturation arithmetic).

You can use these functions:

`sample_nearest(img: Image, tr: Transform[, flags])
sample_bilinear(img: Image, tr: Transform[, flags])
sample_bicubic(img: Image, tr: Transform[, flags])
`
  Samples pixel values from given image and transform. Optionally you can use these flags (delimited by `|`):
  CLAMP - clamp both X & Y coordinates at the edges of the image
  CLAMP_X - clamp the X coordinate at the edges of the image
  CLAMP_Y - clamp the Y coordinate at the edges of the image
`mix(var1, var2, factor)`
  Returns mixed color between variables var1 and var2 using the outside variable `factor` (with values between 0 and 256 inclusively).

## Classes

- Image - contains the image data
- Painter - is used to draw 2D shapes into an Image
- Shape - represents a 2D shape defined by multiple paths (either closed or open)
- Transform - represents linear 2D transformation
- Rect - rectangle with integer coordinates
- Font - TrueType font

Global functions
C API