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.

Typically a band writer is created using a call such as fz_new_png_band_writer:

$\begin{lstlisting} /* fz_new_png_band_writer: Obtain a fz_band_writer instance ... ...riter *fz_new_png_band_writer(fz_context *ctx, fz_output *out); \end{lstlisting}$

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:

$\begin{lstlisting} /* fz_write_header: Cause a band writer to write the header ... ...s, int pagenum, const fz_colorspace *cs, fz_separations *seps); \end{lstlisting}$

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:

$\begin{lstlisting} /* fz_write_band: Cause a band writer to write the next band... ...er, int stride, int band_height, const unsigned char *samples); \end{lstlisting}$

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:

$\begin{lstlisting} void fz_drop_band_writer(fz_context *ctx, fz_band_writer *writer); \end{lstlisting}$