jpayne@68: jpayne@68: jpayne@68:
jpayne@68: jpayne@68:jpayne@68: Top jpayne@68: | jpayne@68:![]() |
jpayne@68: ![]() |
jpayne@68: ![]() |
jpayne@68: ![]() |
jpayne@68:
jpayne@68: PDF Surfacesjpayne@68:PDF Surfaces — Rendering PDF documents jpayne@68: |
jpayne@68: jpayne@68: |
jpayne@68: cairo_surface_t * jpayne@68: | jpayne@68:jpayne@68: cairo_pdf_surface_create () jpayne@68: | jpayne@68:
jpayne@68: cairo_surface_t * jpayne@68: | jpayne@68:jpayne@68: cairo_pdf_surface_create_for_stream () jpayne@68: | jpayne@68:
jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_pdf_surface_restrict_to_version () jpayne@68: | jpayne@68:
jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_pdf_get_versions () jpayne@68: | jpayne@68:
const char * jpayne@68: | jpayne@68:jpayne@68: cairo_pdf_version_to_string () jpayne@68: | jpayne@68:
jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_pdf_surface_set_size () jpayne@68: | jpayne@68:
jpayne@68: int jpayne@68: | jpayne@68:jpayne@68: cairo_pdf_surface_add_outline () jpayne@68: | jpayne@68:
jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_pdf_surface_set_metadata () jpayne@68: | jpayne@68:
jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_pdf_surface_set_page_label () jpayne@68: | jpayne@68:
jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_pdf_surface_set_thumbnail_size () jpayne@68: | jpayne@68:
#define | jpayne@68:CAIRO_HAS_PDF_SURFACE | jpayne@68:
#define | jpayne@68:CAIRO_PDF_OUTLINE_ROOT | jpayne@68:
enum | jpayne@68:cairo_pdf_outline_flags_t | jpayne@68:
enum | jpayne@68:cairo_pdf_metadata_t | jpayne@68:
enum | jpayne@68:cairo_pdf_version_t | jpayne@68:
The PDF surface is used to render cairo graphics to Adobe jpayne@68: PDF files and is a multi-page vector surface backend.
jpayne@68:The following mime types are supported: CAIRO_MIME_TYPE_JPEG
,
jpayne@68: CAIRO_MIME_TYPE_JP2
, CAIRO_MIME_TYPE_UNIQUE_ID
,
jpayne@68: CAIRO_MIME_TYPE_JBIG2
, CAIRO_MIME_TYPE_JBIG2_GLOBAL
,
jpayne@68: CAIRO_MIME_TYPE_JBIG2_GLOBAL_ID
,
jpayne@68: CAIRO_MIME_TYPE_CCITT_FAX
, CAIRO_MIME_TYPE_CCITT_FAX_PARAMS
.
JBIG2 data in PDF must be in the embedded format as described in
jpayne@68: ISO/IEC 11544. Image specific JBIG2 data must be in
jpayne@68: CAIRO_MIME_TYPE_JBIG2
. Any global segments in the JBIG2 data
jpayne@68: (segments with page association field set to 0) must be in
jpayne@68: CAIRO_MIME_TYPE_JBIG2_GLOBAL
. The global data may be shared by
jpayne@68: multiple images. All images sharing the same global data must set
jpayne@68: CAIRO_MIME_TYPE_JBIG2_GLOBAL_ID
to a unique identifier. At least
jpayne@68: one of the images must provide the global data using
jpayne@68: CAIRO_MIME_TYPE_JBIG2_GLOBAL
. The global data will only be
jpayne@68: embedded once and shared by all JBIG2 images with the same
jpayne@68: CAIRO_MIME_TYPE_JBIG2_GLOBAL_ID
.
The CAIRO_MIME_TYPE_CCITT_FAX
mime data requires a number of decoding
jpayne@68: parameters These parameters are specified using CAIRO_MIME_TYPE_CCITT_FAX_PARAMS
.
CAIRO_MIME_TYPE_CCITT_FAX_PARAMS
mime data must contain a string of the form
jpayne@68: "param1=value1 param2=value2 ...".
Columns
jpayne@68: : [required] An integer specifying the width of the image in pixels.
Rows
jpayne@68: : [required] An integer specifying the height of the image in scan lines.
K
jpayne@68: : [optional] An integer identifying the encoding scheme used. < 0
jpayne@68: is 2 dimensional Group 4, = 0 is Group3 1 dimensional, > 0 is mixed 1
jpayne@68: and 2 dimensional encoding. Default is 0.
EndOfLine
jpayne@68: : [optional] If true end-of-line bit patterns are present. Default is false.
EncodedByteAlign
jpayne@68: : [optional] If true the end of line is padded
jpayne@68: with 0 bits so the next line begins on a byte boundary. Default is false.
EndOfBlock
jpayne@68: : [optional] If true the data contains an end-of-block pattern. Default is true.
BlackIs1
jpayne@68: : [optional] If true 1 bits are black pixels. Default is false.
DamagedRowsBeforeError
jpayne@68: : [optional] An integer specifying the
jpayne@68: number of damages rows tolerated before an error occurs. Default is 0.
Boolean values may be "true" or "false", or 1 or 0.
jpayne@68:These parameters are the same as the CCITTFaxDecode parameters in the jpayne@68: PostScript Language Reference jpayne@68: and Portable Document Format (PDF). jpayne@68: Refer to these documents for further details.
jpayne@68:An example CAIRO_MIME_TYPE_CCITT_FAX_PARAMS
string is:
jpayne@68: "Columns=10230 Rows=40000 K=1 EndOfLine=true EncodedByteAlign=1 BlackIs1=false" jpayne@68:jpayne@68:
cairo_surface_t * jpayne@68: cairo_pdf_surface_create (jpayne@68:const char *filename
, jpayne@68:double width_in_points
, jpayne@68:double height_in_points
);
Creates a PDF surface of the specified size in points to be written
jpayne@68: to filename
jpayne@68: .
filename |
jpayne@68: a filename for the PDF output (must be writable), |
jpayne@68: jpayne@68: |
width_in_points |
jpayne@68: width of the surface, in points (1 point == 1/72.0 inch) |
jpayne@68: jpayne@68: |
height_in_points |
jpayne@68: height of the surface, in points (1 point == 1/72.0 inch) |
jpayne@68: jpayne@68: |
a pointer to the newly created surface. The caller
jpayne@68: owns the surface and should call cairo_surface_destroy()
when done
jpayne@68: with it.
This function always returns a valid pointer, but it will return a
jpayne@68: pointer to a "nil" surface if an error such as out of memory
jpayne@68: occurs. You can use cairo_surface_status()
to check for this.
Since: 1.2
jpayne@68:cairo_surface_t * jpayne@68: cairo_pdf_surface_create_for_stream (jpayne@68:cairo_write_func_t write_func
, jpayne@68:void *closure
, jpayne@68:double width_in_points
, jpayne@68:double height_in_points
);
Creates a PDF surface of the specified size in points to be written
jpayne@68: incrementally to the stream represented by write_func
jpayne@68: and closure
jpayne@68: .
write_func |
jpayne@68: a cairo_write_func_t to accept the output data, may be |
jpayne@68: jpayne@68: |
closure |
jpayne@68: the closure argument for |
jpayne@68: jpayne@68: |
width_in_points |
jpayne@68: width of the surface, in points (1 point == 1/72.0 inch) |
jpayne@68: jpayne@68: |
height_in_points |
jpayne@68: height of the surface, in points (1 point == 1/72.0 inch) |
jpayne@68: jpayne@68: |
a pointer to the newly created surface. The caller
jpayne@68: owns the surface and should call cairo_surface_destroy()
when done
jpayne@68: with it.
This function always returns a valid pointer, but it will return a
jpayne@68: pointer to a "nil" surface if an error such as out of memory
jpayne@68: occurs. You can use cairo_surface_status()
to check for this.
Since: 1.2
jpayne@68:void jpayne@68: cairo_pdf_surface_restrict_to_version (jpayne@68:cairo_surface_t *surface
, jpayne@68:cairo_pdf_version_t version
);
Restricts the generated PDF file to version
jpayne@68: . See cairo_pdf_get_versions()
jpayne@68: for a list of available version values that can be used here.
This function should only be called before any drawing operations jpayne@68: have been performed on the given surface. The simplest way to do jpayne@68: this is to call this function immediately after creating the jpayne@68: surface.
jpayne@68:surface |
jpayne@68: a PDF cairo_surface_t |
jpayne@68: jpayne@68: |
version |
jpayne@68: PDF version |
jpayne@68: jpayne@68: |
Since: 1.10
jpayne@68:void jpayne@68: cairo_pdf_get_versions (jpayne@68:cairo_pdf_version_t const **versions
, jpayne@68:int *num_versions
);
Used to retrieve the list of supported versions. See
jpayne@68: cairo_pdf_surface_restrict_to_version()
.
versions |
jpayne@68: supported version list |
jpayne@68: jpayne@68: |
num_versions |
jpayne@68: list length |
jpayne@68: jpayne@68: |
Since: 1.10
jpayne@68:const char *
jpayne@68: cairo_pdf_version_to_string (cairo_pdf_version_t version
);
jpayne@68: Get the string representation of the given version
jpayne@68: id. This function
jpayne@68: will return NULL
if version
jpayne@68: isn't valid. See cairo_pdf_get_versions()
jpayne@68: for a way to get the list of valid version ids.
version |
jpayne@68: a version id |
jpayne@68: jpayne@68: |
Since: 1.10
jpayne@68:void jpayne@68: cairo_pdf_surface_set_size (jpayne@68:cairo_surface_t *surface
, jpayne@68:double width_in_points
, jpayne@68:double height_in_points
);
Changes the size of a PDF surface for the current (and jpayne@68: subsequent) pages.
jpayne@68:This function should only be called before any drawing operations
jpayne@68: have been performed on the current page. The simplest way to do
jpayne@68: this is to call this function immediately after creating the
jpayne@68: surface or immediately after completing a page with either
jpayne@68: cairo_show_page()
or cairo_copy_page()
.
surface |
jpayne@68: a PDF cairo_surface_t |
jpayne@68: jpayne@68: |
width_in_points |
jpayne@68: new surface width, in points (1 point == 1/72.0 inch) |
jpayne@68: jpayne@68: |
height_in_points |
jpayne@68: new surface height, in points (1 point == 1/72.0 inch) |
jpayne@68: jpayne@68: |
Since: 1.2
jpayne@68:int jpayne@68: cairo_pdf_surface_add_outline (jpayne@68:cairo_surface_t *surface
, jpayne@68:int parent_id
, jpayne@68:const char *utf8
, jpayne@68:const char *link_attribs
, jpayne@68:cairo_pdf_outline_flags_t flags
);
Add an item to the document outline hierarchy with the name utf8
jpayne@68:
jpayne@68: that links to the location specified by link_attribs
jpayne@68: . Link
jpayne@68: attributes have the same keys and values as the Link Tag,
jpayne@68: excluding the "rect" attribute. The item will be a child of the
jpayne@68: item with id parent_id
jpayne@68: . Use CAIRO_PDF_OUTLINE_ROOT
as the parent
jpayne@68: id of top level items.
surface |
jpayne@68: a PDF cairo_surface_t |
jpayne@68: jpayne@68: |
parent_id |
jpayne@68: the id of the parent item or |
jpayne@68: jpayne@68: |
utf8 |
jpayne@68: the name of the outline |
jpayne@68: jpayne@68: |
link_attribs |
jpayne@68: the link attributes specifying where this outline links to |
jpayne@68: jpayne@68: |
flags |
jpayne@68: outline item flags |
jpayne@68: jpayne@68: |
Since: 1.16
jpayne@68:void jpayne@68: cairo_pdf_surface_set_metadata (jpayne@68:cairo_surface_t *surface
, jpayne@68:cairo_pdf_metadata_t metadata
, jpayne@68:const char *utf8
);
Set document metadata. The CAIRO_PDF_METADATA_CREATE_DATE
and
jpayne@68: CAIRO_PDF_METADATA_MOD_DATE
values must be in ISO-8601 format:
jpayne@68: YYYY-MM-DDThh:mm:ss. An optional timezone of the form "[+/-]hh:mm"
jpayne@68: or "Z" for UTC time can be appended. All other metadata values can be any UTF-8
jpayne@68: string.
For example:
jpayne@68:1 jpayne@68: 2 |
jpayne@68: cairo_pdf_surface_set_metadata (surface, CAIRO_PDF_METADATA_TITLE, "My Document"); jpayne@68: cairo_pdf_surface_set_metadata (surface, CAIRO_PDF_METADATA_CREATE_DATE, "2015-12-31T23:59+02:00"); |
jpayne@68:
surface |
jpayne@68: a PDF cairo_surface_t |
jpayne@68: jpayne@68: |
metadata |
jpayne@68: The metadata item to set. |
jpayne@68: jpayne@68: |
utf8 |
jpayne@68: metadata value |
jpayne@68: jpayne@68: |
Since: 1.16
jpayne@68:void jpayne@68: cairo_pdf_surface_set_page_label (jpayne@68:cairo_surface_t *surface
, jpayne@68:const char *utf8
);
Set page label for the current page.
jpayne@68:surface |
jpayne@68: a PDF cairo_surface_t |
jpayne@68: jpayne@68: |
utf8 |
jpayne@68: The page label. |
jpayne@68: jpayne@68: |
Since: 1.16
jpayne@68:void jpayne@68: cairo_pdf_surface_set_thumbnail_size (jpayne@68:cairo_surface_t *surface
, jpayne@68:int width
, jpayne@68:int height
);
Set the thumbnail image size for the current and all subsequent jpayne@68: pages. Setting a width or height of 0 disables thumbnails for the jpayne@68: current and subsequent pages.
jpayne@68:surface |
jpayne@68: a PDF cairo_surface_t |
jpayne@68: jpayne@68: |
width |
jpayne@68: Thumbnail width. |
jpayne@68: jpayne@68: |
height |
jpayne@68: Thumbnail height |
jpayne@68: jpayne@68: |
Since: 1.16
jpayne@68:#define CAIRO_HAS_PDF_SURFACE 1 jpayne@68:jpayne@68:
Defined if the PDF surface backend is available. jpayne@68: This macro can be used to conditionally compile backend-specific code.
jpayne@68:Since: 1.2
jpayne@68:#define CAIRO_PDF_OUTLINE_ROOT 0 jpayne@68:jpayne@68:
The root outline item in cairo_pdf_surface_add_outline()
.
Since: 1.16
jpayne@68:cairo_pdf_outline_flags_t is used by the
jpayne@68: cairo_pdf_surface_add_outline()
function specify the attributes of
jpayne@68: an outline item. These flags may be bitwise-or'd to produce any
jpayne@68: combination of flags.
jpayne@68: |
jpayne@68: The outline item defaults to open in the PDF viewer (Since 1.16) jpayne@68: |
jpayne@68: jpayne@68: |
jpayne@68: |
jpayne@68: The outline item is displayed by the viewer in bold text (Since 1.16) jpayne@68: |
jpayne@68: jpayne@68: |
jpayne@68: |
jpayne@68: The outline item is displayed by the viewer in italic text (Since 1.16) jpayne@68: |
jpayne@68: jpayne@68: |
Since: 1.16
jpayne@68:cairo_pdf_metadata_t is used by the
jpayne@68: cairo_pdf_surface_set_metadata()
function specify the metadata to set.
jpayne@68: |
jpayne@68: The document title (Since 1.16) jpayne@68: |
jpayne@68: jpayne@68: |
jpayne@68: |
jpayne@68: The document author (Since 1.16) jpayne@68: |
jpayne@68: jpayne@68: |
jpayne@68: |
jpayne@68: The document subject (Since 1.16) jpayne@68: |
jpayne@68: jpayne@68: |
jpayne@68: |
jpayne@68: The document keywords (Since 1.16) jpayne@68: |
jpayne@68: jpayne@68: |
jpayne@68: |
jpayne@68: The document creator (Since 1.16) jpayne@68: |
jpayne@68: jpayne@68: |
jpayne@68: |
jpayne@68: The document creation date (Since 1.16) jpayne@68: |
jpayne@68: jpayne@68: |
jpayne@68: |
jpayne@68: The document modification date (Since 1.16) jpayne@68: |
jpayne@68: jpayne@68: |
Since: 1.16
jpayne@68:cairo_pdf_version_t is used to describe the version number of the PDF jpayne@68: specification that a generated PDF file will conform to.
jpayne@68:jpayne@68: |
jpayne@68: The version 1.4 of the PDF specification. (Since 1.10) jpayne@68: |
jpayne@68: jpayne@68: |
jpayne@68: |
jpayne@68: The version 1.5 of the PDF specification. (Since 1.10) jpayne@68: |
jpayne@68: jpayne@68: |
Since: 1.10
jpayne@68: