<script src="flif.js"></script>

<canvas data-polyflif-src="xyz.flif"></canvas>

Documentation

Basics

The `flif.js` script performs the following steps:

1. Registers a handler for `DOMContentLoaded` event.
2. When the event is triggered, it queries all canvas elements that have `data-polyflif-src` attribute.
3. Each such <canvas> element will be queued for processing.
4. The URL specified in the attribute will be loaded via XHR request, decoded and rendered onto the canvas.

The canvas element will be resized to fit the image dimensions. Similarly, if any element has the `data-polyflif-bg-src` attribute, then the CSS `background-image` is set to the decoded FLIF image.

Partial load and decode

A FLIF image can be partially decoded to yield a lower resolution image. We can utilise this to reduce bandwidth and CPU usage.

Use the optional `data-polyflif-bytes` attribute to specify the amount of bytes to be loaded and decoded. When this is specified, a range header is added to the XHR request. If the server supports range requests, only the specified bytes will be loaded. Further, the data from XHR, if not truncated by the server, will be truncated in JS to ensure that decoding is partial.

Tip: To determine the optimal number of bytes to decode, use the CLI tool with the -b option.

Controlling the image dimensions

First, style the canvas element using CSS so that it has the desired dimensions. You can use media-queries to set responsive dimensions.

Then, add the `data-polyflif-scale` attribute to the canvas element. When this attribute is present, the CSS computed size of the canvas element is sent to the decoder (equivalent to the -f option of the FLIF CLI tool). The image is decoded so that it fits the requested dimensions.

(We need to add more options here, for example, to center the image in the canvas, to upscale the image, resize the canvas to fit actual dimensions, etc).

Low Level API

For version 0.8.1 Example usage:

var canvasElement = document.getElementById("...");    // get canvas element somehow
var buffer = ...                                       // get data in Uint8Array; via XHR, for example.

var options = {
  canvas: canvasElement,
  buf:    buffer
};
var pf = new PolyFlif(options);

var showPreviews = true;                              // enable or disable previews during progressive decode
var truncationPercent = 0;                            // in percent (0 to 100). 0 means no truncation.
var truncationCount = -1;                             // in bytes (-1 means no truncation)
var rw = 0;                                           // requested width (if 0, original image width is used)
var rh = 0;                                           // requested height (if 0, original image height is used)

// Either this version
pf.beginPercent(showPreviews, truncationPercent, rw, rh);

// Or this version
pf.beginCount(showPreviews, truncationCount, rw, rh);