PostScript Surfaces: Cairo: A Vector Graphics Library

- - -

PostScript Surfaces

PostScript Surfaces — Rendering PostScript documents

Functions

---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

-cairo_surface_t * -	-cairo_ps_surface_create () -
-cairo_surface_t * -	-cairo_ps_surface_create_for_stream () -
-void -	-cairo_ps_surface_restrict_to_level () -
-void -	-cairo_ps_get_levels () -
const char * -	-cairo_ps_level_to_string () -
-void -	-cairo_ps_surface_set_eps () -
-cairo_bool_t -	-cairo_ps_surface_get_eps () -
-void -	-cairo_ps_surface_set_size () -
-void -	-cairo_ps_surface_dsc_begin_setup () -
-void -	-cairo_ps_surface_dsc_begin_page_setup () -
-void -	-cairo_ps_surface_dsc_comment () -

Types and Values

---- - - - - - - - - - - -

#define	CAIRO_HAS_PS_SURFACE
enum	cairo_ps_level_t

Description

The PostScript surface is used to render cairo graphics to Adobe -PostScript files and is a multi-page vector surface backend.

The following mime types are supported: CAIRO_MIME_TYPE_JPEG, -CAIRO_MIME_TYPE_UNIQUE_ID, -CAIRO_MIME_TYPE_CCITT_FAX, CAIRO_MIME_TYPE_CCITT_FAX_PARAMS, -CAIRO_MIME_TYPE_CCITT_FAX, CAIRO_MIME_TYPE_CCITT_FAX_PARAMS, -CAIRO_MIME_TYPE_EPS, CAIRO_MIME_TYPE_EPS_PARAMS.

Source surfaces used by the PostScript surface that have a -CAIRO_MIME_TYPE_UNIQUE_ID mime type will be stored in PostScript -printer memory for the duration of the print -job. CAIRO_MIME_TYPE_UNIQUE_ID should only be used for small -frequently used sources.

The CAIRO_MIME_TYPE_CCITT_FAX and CAIRO_MIME_TYPE_CCITT_FAX_PARAMS mime types -are documented in CCITT Fax Images.

Embedding EPS files

Encapsulated PostScript files can be embedded in the PS output by -setting the CAIRO_MIME_TYPE_EPS mime data on a surface to the EPS -data and painting the surface. The EPS will be scaled and -translated to the extents of the surface the EPS data is attached -to.

The CAIRO_MIME_TYPE_EPS mime type requires the -CAIRO_MIME_TYPE_EPS_PARAMS mime data to also be provided in order -to specify the embeddding parameters. CAIRO_MIME_TYPE_EPS_PARAMS -mime data must contain a string of the form "bbox=[llx lly urx -ury]" that specifies the bounding box (in PS coordinates) of the -EPS graphics. The parameters are: lower left x, lower left y, upper -right x, upper right y. Normally the bbox data is identical to the -%%BoundingBox data in the EPS file.

Functions

cairo_ps_surface_create ()

cairo_surface_t *
-cairo_ps_surface_create (const char *filename,
-                         double width_in_points,
-                         double height_in_points);

Creates a PostScript surface of the specified size in points to be -written to filename -. See cairo_ps_surface_create_for_stream() for -a more flexible mechanism for handling the PostScript output than -simply writing it to a named file.

Note that the size of individual pages of the PostScript output can -vary. See cairo_ps_surface_set_size().

Parameters

----- - - - - - - - - - - - - - - - - - -

filename	a filename for the PS output (must be writable), `NULL` may be -used to specify no output. This will generate a PS surface that -may be queried and used as a source, without generating a -temporary file.
width_in_points	width of the surface, in points (1 point == 1/72.0 inch)
height_in_points	height of the surface, in points (1 point == 1/72.0 inch)

Returns

a pointer to the newly created surface. The caller -owns the surface and should call cairo_surface_destroy() when done -with it.

This function always returns a valid pointer, but it will return a -pointer to a "nil" surface if an error such as out of memory -occurs. You can use cairo_surface_status() to check for this.

Since: 1.2

cairo_ps_surface_create_for_stream ()

cairo_surface_t *
-cairo_ps_surface_create_for_stream (cairo_write_func_t write_func,
-                                    void *closure,
-                                    double width_in_points,
-                                    double height_in_points);

Creates a PostScript surface of the specified size in points to be -written incrementally to the stream represented by write_func - and -closure -. See cairo_ps_surface_create() for a more convenient way -to simply direct the PostScript output to a named file.

Note that the size of individual pages of the PostScript -output can vary. See cairo_ps_surface_set_size().

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - -

write_func	a cairo_write_func_t to accept the output data, may be `NULL` -to indicate a no-op `write_func` -. With a no-op `write_func` -, -the surface may be queried or used as a source without -generating any temporary files.
closure	the closure argument for `write_func` -
width_in_points	width of the surface, in points (1 point == 1/72.0 inch)
height_in_points	height of the surface, in points (1 point == 1/72.0 inch)

Returns

a pointer to the newly created surface. The caller -owns the surface and should call cairo_surface_destroy() when done -with it.

This function always returns a valid pointer, but it will return a -pointer to a "nil" surface if an error such as out of memory -occurs. You can use cairo_surface_status() to check for this.

Since: 1.2

cairo_ps_surface_restrict_to_level ()

void
-cairo_ps_surface_restrict_to_level (cairo_surface_t *surface,
-                                    cairo_ps_level_t level);

Restricts the generated PostSript file to level -. See -cairo_ps_get_levels() for a list of available level values that -can be used here.

This function should only be called before any drawing operations -have been performed on the given surface. The simplest way to do -this is to call this function immediately after creating the -surface.

Parameters

----- - - - - - - - - - - - - -

surface	a PostScript cairo_surface_t
level	PostScript level

Since: 1.6

cairo_ps_get_levels ()

void
-cairo_ps_get_levels (cairo_ps_level_t const **levels,
-                     int *num_levels);

Used to retrieve the list of supported levels. See -cairo_ps_surface_restrict_to_level().

Parameters

----- - - - - - - - - - - - - -

levels	supported level list
num_levels	list length

Since: 1.6

cairo_ps_level_to_string ()

const char *
-cairo_ps_level_to_string (cairo_ps_level_t level);

Get the string representation of the given level - id. This function -will return NULL if level - id isn't valid. See cairo_ps_get_levels() -for a way to get the list of valid level ids.

Parameters

----- - - - - - -

level

a level id

Returns

the string associated to given level.

Since: 1.6

cairo_ps_surface_set_eps ()

void
-cairo_ps_surface_set_eps (cairo_surface_t *surface,
-                          cairo_bool_t eps);

If eps - is TRUE, the PostScript surface will output Encapsulated -PostScript.

This function should only be called before any drawing operations -have been performed on the current page. The simplest way to do -this is to call this function immediately after creating the -surface. An Encapsulated PostScript file should never contain more -than one page.

Parameters

----- - - - - - - - - - - - - -

surface	a PostScript cairo_surface_t
eps	`TRUE` to output EPS format PostScript

Since: 1.6

cairo_ps_surface_get_eps ()

cairo_bool_t
-cairo_ps_surface_get_eps (cairo_surface_t *surface);

Check whether the PostScript surface will output Encapsulated PostScript.

Parameters

----- - - - - - -

surface

a PostScript cairo_surface_t

Returns

TRUE if the surface will output Encapsulated PostScript.

Since: 1.6

cairo_ps_surface_set_size ()

void
-cairo_ps_surface_set_size (cairo_surface_t *surface,
-                           double width_in_points,
-                           double height_in_points);

Changes the size of a PostScript surface for the current (and -subsequent) pages.

This function should only be called before any drawing operations -have been performed on the current page. The simplest way to do -this is to call this function immediately after creating the -surface or immediately after completing a page with either -cairo_show_page() or cairo_copy_page().

Parameters

----- - - - - - - - - - - - - - - - - - -

surface	a PostScript cairo_surface_t
width_in_points	new surface width, in points (1 point == 1/72.0 inch)
height_in_points	new surface height, in points (1 point == 1/72.0 inch)

Since: 1.2

cairo_ps_surface_dsc_begin_setup ()

void
-cairo_ps_surface_dsc_begin_setup (cairo_surface_t *surface);

This function indicates that subsequent calls to -cairo_ps_surface_dsc_comment() should direct comments to the Setup -section of the PostScript output.

This function should be called at most once per surface, and must -be called before any call to cairo_ps_surface_dsc_begin_page_setup() -and before any drawing is performed to the surface.

See cairo_ps_surface_dsc_comment() for more details.

Parameters

----- - - - - - -

surface

a PostScript cairo_surface_t

Since: 1.2

cairo_ps_surface_dsc_begin_page_setup ()

void
-cairo_ps_surface_dsc_begin_page_setup (cairo_surface_t *surface);

This function indicates that subsequent calls to -cairo_ps_surface_dsc_comment() should direct comments to the -PageSetup section of the PostScript output.

This function call is only needed for the first page of a -surface. It should be called after any call to -cairo_ps_surface_dsc_begin_setup() and before any drawing is -performed to the surface.

See cairo_ps_surface_dsc_comment() for more details.

Parameters

----- - - - - - -

surface

a PostScript cairo_surface_t

Since: 1.2

cairo_ps_surface_dsc_comment ()

void
-cairo_ps_surface_dsc_comment (cairo_surface_t *surface,
-                              const char *comment);

Emit a comment into the PostScript output for the given surface.

The comment is expected to conform to the PostScript Language -Document Structuring Conventions (DSC). Please see that manual for -details on the available comments and their meanings. In -particular, the %%IncludeFeature comment allows a -device-independent means of controlling printer device features. So -the PostScript Printer Description Files Specification will also be -a useful reference.

The comment string must begin with a percent character (%) and the -total length of the string (including any initial percent -characters) must not exceed 255 characters. Violating either of -these conditions will place surface - into an error state. But -beyond these two conditions, this function will not enforce -conformance of the comment with any particular specification.

The comment string should not have a trailing newline.

The DSC specifies different sections in which particular comments -can appear. This function provides for comments to be emitted -within three sections: the header, the Setup section, and the -PageSetup section. Comments appearing in the first two sections -apply to the entire document while comments in the BeginPageSetup -section apply only to a single page.

For comments to appear in the header section, this function should -be called after the surface is created, but before a call to -cairo_ps_surface_dsc_begin_setup().

For comments to appear in the Setup section, this function should -be called after a call to cairo_ps_surface_dsc_begin_setup() but -before a call to cairo_ps_surface_dsc_begin_page_setup().

For comments to appear in the PageSetup section, this function -should be called after a call to -cairo_ps_surface_dsc_begin_page_setup().

Note that it is only necessary to call -cairo_ps_surface_dsc_begin_page_setup() for the first page of any -surface. After a call to cairo_show_page() or cairo_copy_page() -comments are unambiguously directed to the PageSetup section of the -current page. But it doesn't hurt to call this function at the -beginning of every page as that consistency may make the calling -code simpler.

As a final note, cairo automatically generates several comments on -its own. As such, applications must not manually generate any of -the following comments:

Header section: %!PS-Adobe-3.0, %%Creator, %%CreationDate, %%Pages, -%%BoundingBox, %%DocumentData, %%LanguageLevel, %%EndComments.

Setup section: %%BeginSetup, %%EndSetup

PageSetup section: %%BeginPageSetup, %%PageBoundingBox, %%EndPageSetup.

Other sections: %%BeginProlog, %%EndProlog, %%Page, %%Trailer, %%EOF

Here is an example sequence showing how this function might be used:

- - - - - - - -

1
-2
-3
-4
-5
-6
-7
-8
-9
-10
-11
-12
-13
-14
-15
-16
-17
-18

cairo_surface_t *surface = cairo_ps_surface_create (filename, width, height);
-...
-cairo_ps_surface_dsc_comment (surface, "%%Title: My excellent document");
-cairo_ps_surface_dsc_comment (surface, "%%Copyright: Copyright (C) 2006 Cairo Lover")
-...
-cairo_ps_surface_dsc_begin_setup (surface);
-cairo_ps_surface_dsc_comment (surface, "%%IncludeFeature: *MediaColor White");
-...
-cairo_ps_surface_dsc_begin_page_setup (surface);
-cairo_ps_surface_dsc_comment (surface, "%%IncludeFeature: *PageSize A3");
-cairo_ps_surface_dsc_comment (surface, "%%IncludeFeature: *InputSlot LargeCapacity");
-cairo_ps_surface_dsc_comment (surface, "%%IncludeFeature: *MediaType Glossy");
-cairo_ps_surface_dsc_comment (surface, "%%IncludeFeature: *MediaColor Blue");
-... draw to first page here ..
-cairo_show_page (cr);
-...
-cairo_ps_surface_dsc_comment (surface, "%%IncludeFeature: *PageSize A5");
-...

- -

Parameters

----- - - - - - - - - - - - - -

surface	a PostScript cairo_surface_t
comment	a comment string to be emitted into the PostScript output

Since: 1.2

Types and Values

CAIRO_HAS_PS_SURFACE

#define CAIRO_HAS_PS_SURFACE 1
-

Defined if the PostScript surface backend is available. -This macro can be used to conditionally compile backend-specific code.

Since: 1.2

enum cairo_ps_level_t

cairo_ps_level_t is used to describe the language level of the -PostScript Language Reference that a generated PostScript file will -conform to.

Members

----- - - - - - - - - - - - - -

CAIRO_PS_LEVEL_2	- The language level 2 of the PostScript specification. (Since 1.6) -
CAIRO_PS_LEVEL_3	- The language level 3 of the PostScript specification. (Since 1.6) -

Since: 1.6