15.1 Usage
As well as opening existing documents, MuPDF contains functions to allow the easy
creation of new documents. The most general form of this functionality takes the
form of the fz_document_writer interface.
A document writer is obtained by calling a generation function. The most general
purpose one is:
/* fz_new_document_writer: Create a new fz_document_writer, for a file of the given type. path: The document name to write (or NULL for default) format: Which format to write (currently cbz, pdf, pam, pbm, pgm, pkm, png, ppm, pnm, svg, tga) options: NULL, or pointer to comma separated string to control file generation. */ fz_document_writer *fz_new_document_writer(fz_context *ctx, const char *path, const char *format, const char *options);
Alternatively, direct calls to generate specific document writers can be used, such
as:
fz_document_writer *fz_new_cbz_writer(fz_context *ctx, const char *path, const char *options); fz_document_writer *fz_new_pdf_writer(fz_context *ctx, const char *path, const char *options); fz_document_writer *fz_new_svg_writer(fz_context *ctx, const char *path, const char *options); fz_document_writer *fz_new_png_pixmap_writer(fz_context *ctx, const char *path, const char *options); fz_document_writer *fz_new_tga_pixmap_writer(fz_context *ctx, const char *path, const char *options); fz_document_writer *fz_new_pam_pixmap_writer(fz_context *ctx, const char *path, const char *options); fz_document_writer *fz_new_pnm_pixmap_writer(fz_context *ctx, const char *path, const char *options); fz_document_writer *fz_new_pgm_pixmap_writer(fz_context *ctx, const char *path, const char *options); fz_document_writer *fz_new_ppm_pixmap_writer(fz_context *ctx, const char *path, const char *options); fz_document_writer *fz_new_pbm_pixmap_writer(fz_context *ctx, const char *path, const char *options); fz_document_writer *fz_new_pkm_pixmap_writer(fz_context *ctx, const char *path, const char *options);
Once a fz_document_writer has been created, pages can be written to the
document one at a time. The process is started by calling fz_begin_page:
/* fz_begin_page: Called to start the process of writing a page to a document. mediabox: page size rectangle in points. Returns a fz_device to write page contents to. */ fz_device *fz_begin_page(fz_context *ctx, fz_document_writer *wri, const fz_rect *mediabox);
This function returns a fz_device pointer that should be used to write the page
contents to. This can be done by making a sequence of normal device calls (see
chapter 9 The Device interface) to paint the page with its content. One of the most
common ways of doing this is by calling fz_run_page_contents on another open
document. This therefore offers a quick mechanism for converting documents from
one format to another.
Once the page contents have all been written, the page is finalized by calling
fz_end_page:
/* fz_end_page: Called to end the process of writing a page to a document. */ void fz_end_page(fz_context *ctx, fz_document_writer *wri);
At this point, many formats will allow more pages to be written, simply by repeating
the fz_begin_page, output, fz_end_page loop.
When all the pages have been written, the produced document can be finalized by
calling fz_close_document_writer:
/* fz_close_document_writer: Called to end the process of writing pages to a document. This writes any file level trailers required. After this completes successfully the file is up to date and complete. */ void fz_close_document_writer(fz_context *ctx, fz_document_writer *wri);
Finally, the document writer itself can be freed in the usual fashion by calling
fz_drop_document_writer:
/* fz_drop_document_writer: Called to discard a fz_document_writer. This may be called at any time during the process to release all the resources owned by the writer. Calling drop without having previously called drop may leave the file in an inconsistent state. */ void fz_drop_document_writer(fz_context *ctx, fz_document_writer *wri);