Band Writers

The purpose of the fz_band_writer mechanism is to allow banded rendering; rather than having to allocate a pixmap large enough to hold the entire page at once, we instead render bands across the page and feed those to the fz_band_writer which assembles them into a properly formed XXX format output stream.

/*
fz_new_png_band_writer: Obtain a fz_band_writer instance
for producing PNG output.
*/
fz_band_writer *fz_new_png_band_writer(fz_context *ctx, fz_output *out);

The page output starts by calling fz_write_header. This both configures the band writer for the type of data that is being sent, and triggers the output of the file header:

/*
   fz_write_header: Cause a band writer to write the header for
   a banded image with the given properties/dimensions etc. This
   also configures the bandwriter for the format of the data to be
   passed in future calls.

   w, h: Width and Height of the entire page.

   n: Number of components (including spots and alphas).

   alpha: Number of alpha components.

   xres, yres: X and Y resolutions in dpi.

   pagenum: Page number

   cs: Colorspace (NULL for bitmaps)

   seps: Separation details (or NULL).

   Throws exception if incompatible data format.
*/
void fz_write_header(fz_context *ctx, fz_band_writer *writer, int w, int h, int n, int alpha, int xres, int yres, int pagenum, const fz_colorspace *cs, fz_separations *seps);

This has the effect of setting the size and format of the data for the complete image. The caller then proceeds to render the page in horizontal strips from the top to the bottom, and pass them in to fz_write_band:

/*
   fz_write_band: Cause a band writer to write the next band
   of data for an image.

   stride: The byte offset from the first byte of the data
   for a pixel to the first byte of the data for the same pixel
   on the row below.

   band_height: The number of lines in this band.

   samples: Pointer to first byte of the data.
*/
void fz_write_band(fz_context *ctx, fz_band_writer *writer, int stride, int band_height, const unsigned char *samples);

The band writer keeps track of how much data has been written, and when an entire page has been sent, it writes out any image trailer required.

For formats that can accommodate multiple pages, a new call to fz_write_header will start the process again. Otherwise (or after the final image), the band writer can be neatly discarded by calling:

14.2 Band Writers