14.9 PWG/CUPS
The PWG format is intended to encapsulate output for printers. As such
there are many values that can be set in the headers. To allow for this, we
expose these fields as an options structure that can be fed into the output
functions.
typedef struct fz_pwg_options_s fz_pwg_options; struct fz_pwg_options_s { /* These are not interpreted as CStrings by the writing code, but * are rather copied directly out. */ char media_class[64]; char media_color[64]; char media_type[64]; char output_type[64]; unsigned int advance_distance; int advance_media; int collate; int cut_media; int duplex; int insert_sheet; int jog; int leading_edge; int manual_feed; unsigned int media_position; unsigned int media_weight; int mirror_print; int negative_print; unsigned int num_copies; int orientation; int output_face_up; unsigned int PageSize[2]; int separations; int tray_switch; int tumble; int media_type_num; int compression; unsigned int row_count; unsigned int row_feed; unsigned int row_step; /* These are not interpreted as CStrings by the writing code, but * are rather copied directly out. */ char rendering_intent[64]; char page_size_name[64]; };
No documentation for these fields is given here - for more information see the PWG
specification.
There are 2 sets of output functions available for PWG, those that take
fz_pixmaps (for contone output) and those that take fz_bitmaps (for halftoned
output).
PWG files are structured as a header (to identify the format), followed by a stream of
pages (images). Those functions that save (or write) a complete file include the file
header as part of their output. If the option is used to append to a file, then the
header is not added, as we presume we are appending new page information to the
end of an existing file.
In circumstances when the header is not output automatically (such as when
using the band writer) the header output must be triggered manually, by
calling:
/* Output the file header to a pwg stream, ready for pages to follow it. */ void fz_write_pwg_file_header(fz_context *ctx, fz_output *out);
14.9.1 Contone
The PWG writer can accept pixmaps in greyscale, RGB and CMYK format, with no
alpha planes.
PWG files can be saved to a file using:
/* fz_save_pixmap_as_pwg: Save a pixmap as a pwg filename: The filename to save as (including extension). append: If non-zero, then append a new page to existing file. pwg: NULL, or a pointer to an options structure (initialised to zero before being filled in, for future expansion). */ void fz_save_pixmap_as_pwg(fz_context *ctx, fz_pixmap *pixmap, char *filename, int append, const fz_pwg_options *pwg);
The file header will only be sent in the case where we are not appending to an
existing file.
Alternatively, pages may be sent to an output stream. Two functions exist to do this.
The first always sends a complete PWG file (including header):
/* Output a pixmap to an output stream as a pwg raster. */ void fz_write_pixmap_as_pwg(fz_context *ctx, fz_output *out, const fz_pixmap *pixmap, const fz_pwg_options *pwg);
The second sends just the page data, and is therefore suitable for sending
the second or subsequent pages in a file. Alternatively, the header can be
sent manually, and then this function can be used for all the pages in a
file.
/* Output a page to a pwg stream to follow a header, or other pages. */ void fz_write_pixmap_as_pwg_page(fz_context *ctx, fz_output *out, const fz_pixmap *pixmap, const fz_pwg_options *pwg);
Finally, a standard band writer can be used:
/* fz_new_pwg_band_writer: Generate a new band writer for contone PWG format images. */ fz_band_writer *fz_new_pwg_band_writer(fz_context *ctx, fz_output *out, const fz_pwg_options *pwg);
In all cases, a NULL value can be sent for the fz_pwg_options field, in which case
default values will be used.
14.9.2 Mono
The monochrome version of the PWG writer parallels the contone one. It can accept
monochrome bitmaps only.
PWG files can be saved to a file using:
/* fz_save_bitmap_as_pwg: Save a bitmap as a pwg filename: The filename to save as (including extension). append: If non-zero, then append a new page to existing file. pwg: NULL, or a pointer to an options structure (initialised to zero before being filled in, for future expansion). */ void fz_save_bitmap_as_pwg(fz_context *ctx, fz_bitmap *bitmap, char *filename, int append, const fz_pwg_options *pwg);
The file header will only be sent in the case where we are not appending to an
existing file.
Alternatively, pages may be sent to an output stream. Two functions exist to do this.
The first always sends a complete PWG file (including header):
/* Output a bitmap to an output stream as a pwg raster. */ void fz_write_bitmap_as_pwg(fz_context *ctx, fz_output *out, const fz_bitmap *bitmap, const fz_pwg_options *pwg);
The second sends just the page data, and is therefore suitable for sending
the second or subsequent pages in a file. Alternatively, the header can be
sent manually, and then this function can be used for all the pages in a
file.
/* Output a bitmap page to a pwg stream to follow a header, or other pages. */ void fz_write_bitmap_as_pwg_page(fz_context *ctx, fz_output *out, const fz_bitmap *bitmap, const fz_pwg_options *pwg);
Finally, a standard band writer can be used:
/* fz_new_mono_pwg_band_writer: Generate a new band writer for PWG format images. */ fz_band_writer *fz_new_mono_pwg_band_writer(fz_context *ctx, fz_output *out, const fz_pwg_options *pwg);
In all cases, a NULL value can be sent for the fz_pwg_options field, in which case
default values will be used.