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: PostScript Surfacesjpayne@68:PostScript Surfaces — Rendering PostScript documents jpayne@68: |
jpayne@68: jpayne@68: |
jpayne@68: cairo_surface_t * jpayne@68: | jpayne@68:jpayne@68: cairo_ps_surface_create () jpayne@68: | jpayne@68:
jpayne@68: cairo_surface_t * jpayne@68: | jpayne@68:jpayne@68: cairo_ps_surface_create_for_stream () jpayne@68: | jpayne@68:
jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_ps_surface_restrict_to_level () jpayne@68: | jpayne@68:
jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_ps_get_levels () jpayne@68: | jpayne@68:
const char * jpayne@68: | jpayne@68:jpayne@68: cairo_ps_level_to_string () jpayne@68: | jpayne@68:
jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_ps_surface_set_eps () jpayne@68: | jpayne@68:
jpayne@68: cairo_bool_t jpayne@68: | jpayne@68:jpayne@68: cairo_ps_surface_get_eps () jpayne@68: | jpayne@68:
jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_ps_surface_set_size () jpayne@68: | jpayne@68:
jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_ps_surface_dsc_begin_setup () jpayne@68: | jpayne@68:
jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_ps_surface_dsc_begin_page_setup () jpayne@68: | jpayne@68:
jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_ps_surface_dsc_comment () jpayne@68: | jpayne@68:
#define | jpayne@68:CAIRO_HAS_PS_SURFACE | jpayne@68:
enum | jpayne@68:cairo_ps_level_t | jpayne@68:
The PostScript surface is used to render cairo graphics to Adobe jpayne@68: PostScript 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_UNIQUE_ID
,
jpayne@68: CAIRO_MIME_TYPE_CCITT_FAX
, CAIRO_MIME_TYPE_CCITT_FAX_PARAMS
,
jpayne@68: CAIRO_MIME_TYPE_CCITT_FAX
, CAIRO_MIME_TYPE_CCITT_FAX_PARAMS
,
jpayne@68: CAIRO_MIME_TYPE_EPS
, CAIRO_MIME_TYPE_EPS_PARAMS
.
Source surfaces used by the PostScript surface that have a
jpayne@68: CAIRO_MIME_TYPE_UNIQUE_ID
mime type will be stored in PostScript
jpayne@68: printer memory for the duration of the print
jpayne@68: job. CAIRO_MIME_TYPE_UNIQUE_ID
should only be used for small
jpayne@68: frequently used sources.
The CAIRO_MIME_TYPE_CCITT_FAX
and CAIRO_MIME_TYPE_CCITT_FAX_PARAMS
mime types
jpayne@68: are documented in CCITT Fax Images.
Encapsulated PostScript files can be embedded in the PS output by jpayne@68: setting the CAIRO_MIME_TYPE_EPS mime data on a surface to the EPS jpayne@68: data and painting the surface. The EPS will be scaled and jpayne@68: translated to the extents of the surface the EPS data is attached jpayne@68: to.
jpayne@68:The CAIRO_MIME_TYPE_EPS
mime type requires the
jpayne@68: CAIRO_MIME_TYPE_EPS_PARAMS
mime data to also be provided in order
jpayne@68: to specify the embeddding parameters. CAIRO_MIME_TYPE_EPS_PARAMS
jpayne@68: mime data must contain a string of the form "bbox=[llx lly urx
jpayne@68: ury]" that specifies the bounding box (in PS coordinates) of the
jpayne@68: EPS graphics. The parameters are: lower left x, lower left y, upper
jpayne@68: right x, upper right y. Normally the bbox data is identical to the
jpayne@68: %%BoundingBox
data in the EPS file.
cairo_surface_t * jpayne@68: cairo_ps_surface_create (jpayne@68:const char *filename
, jpayne@68:double width_in_points
, jpayne@68:double height_in_points
);
Creates a PostScript surface of the specified size in points to be
jpayne@68: written to filename
jpayne@68: . See cairo_ps_surface_create_for_stream()
for
jpayne@68: a more flexible mechanism for handling the PostScript output than
jpayne@68: simply writing it to a named file.
Note that the size of individual pages of the PostScript output can
jpayne@68: vary. See cairo_ps_surface_set_size()
.
filename |
jpayne@68: a filename for the PS 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_ps_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 PostScript surface of the specified size in points to be
jpayne@68: written incrementally to the stream represented by write_func
jpayne@68: and
jpayne@68: closure
jpayne@68: . See cairo_ps_surface_create()
for a more convenient way
jpayne@68: to simply direct the PostScript output to a named file.
Note that the size of individual pages of the PostScript
jpayne@68: output can vary. See cairo_ps_surface_set_size()
.
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_ps_surface_restrict_to_level (jpayne@68:cairo_surface_t *surface
, jpayne@68:cairo_ps_level_t level
);
Restricts the generated PostSript file to level
jpayne@68: . See
jpayne@68: cairo_ps_get_levels()
for a list of available level values that
jpayne@68: 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 PostScript cairo_surface_t |
jpayne@68: jpayne@68: |
level |
jpayne@68: PostScript level |
jpayne@68: jpayne@68: |
Since: 1.6
jpayne@68:void jpayne@68: cairo_ps_get_levels (jpayne@68:cairo_ps_level_t const **levels
, jpayne@68:int *num_levels
);
Used to retrieve the list of supported levels. See
jpayne@68: cairo_ps_surface_restrict_to_level()
.
levels |
jpayne@68: supported level list |
jpayne@68: jpayne@68: |
num_levels |
jpayne@68: list length |
jpayne@68: jpayne@68: |
Since: 1.6
jpayne@68:const char *
jpayne@68: cairo_ps_level_to_string (cairo_ps_level_t level
);
jpayne@68: Get the string representation of the given level
jpayne@68: id. This function
jpayne@68: will return NULL
if level
jpayne@68: id isn't valid. See cairo_ps_get_levels()
jpayne@68: for a way to get the list of valid level ids.
level |
jpayne@68: a level id |
jpayne@68: jpayne@68: |
Since: 1.6
jpayne@68:void jpayne@68: cairo_ps_surface_set_eps (jpayne@68:cairo_surface_t *surface
, jpayne@68:cairo_bool_t eps
);
If eps
jpayne@68: is TRUE
, the PostScript surface will output Encapsulated
jpayne@68: PostScript.
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. An Encapsulated PostScript file should never contain more jpayne@68: than one page.
jpayne@68:surface |
jpayne@68: a PostScript cairo_surface_t |
jpayne@68: jpayne@68: |
eps |
jpayne@68:
|
jpayne@68: jpayne@68: |
Since: 1.6
jpayne@68:cairo_bool_t
jpayne@68: cairo_ps_surface_get_eps (cairo_surface_t *surface
);
jpayne@68: Check whether the PostScript surface will output Encapsulated PostScript.
jpayne@68:surface |
jpayne@68: a PostScript cairo_surface_t |
jpayne@68: jpayne@68: |
Since: 1.6
jpayne@68:void jpayne@68: cairo_ps_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 PostScript 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 PostScript 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:void
jpayne@68: cairo_ps_surface_dsc_begin_setup (cairo_surface_t *surface
);
jpayne@68: This function indicates that subsequent calls to
jpayne@68: cairo_ps_surface_dsc_comment()
should direct comments to the Setup
jpayne@68: section of the PostScript output.
This function should be called at most once per surface, and must
jpayne@68: be called before any call to cairo_ps_surface_dsc_begin_page_setup()
jpayne@68: and before any drawing is performed to the surface.
See cairo_ps_surface_dsc_comment()
for more details.
surface |
jpayne@68: a PostScript cairo_surface_t |
jpayne@68: jpayne@68: |
Since: 1.2
jpayne@68:void
jpayne@68: cairo_ps_surface_dsc_begin_page_setup (cairo_surface_t *surface
);
jpayne@68: This function indicates that subsequent calls to
jpayne@68: cairo_ps_surface_dsc_comment()
should direct comments to the
jpayne@68: PageSetup section of the PostScript output.
This function call is only needed for the first page of a
jpayne@68: surface. It should be called after any call to
jpayne@68: cairo_ps_surface_dsc_begin_setup()
and before any drawing is
jpayne@68: performed to the surface.
See cairo_ps_surface_dsc_comment()
for more details.
surface |
jpayne@68: a PostScript cairo_surface_t |
jpayne@68: jpayne@68: |
Since: 1.2
jpayne@68:void jpayne@68: cairo_ps_surface_dsc_comment (jpayne@68:cairo_surface_t *surface
, jpayne@68:const char *comment
);
Emit a comment into the PostScript output for the given surface.
jpayne@68:The comment is expected to conform to the PostScript Language jpayne@68: Document Structuring Conventions (DSC). Please see that manual for jpayne@68: details on the available comments and their meanings. In jpayne@68: particular, the %%IncludeFeature comment allows a jpayne@68: device-independent means of controlling printer device features. So jpayne@68: the PostScript Printer Description Files Specification will also be jpayne@68: a useful reference.
jpayne@68:The comment string must begin with a percent character (%) and the
jpayne@68: total length of the string (including any initial percent
jpayne@68: characters) must not exceed 255 characters. Violating either of
jpayne@68: these conditions will place surface
jpayne@68: into an error state. But
jpayne@68: beyond these two conditions, this function will not enforce
jpayne@68: conformance of the comment with any particular specification.
The comment string should not have a trailing newline.
jpayne@68:The DSC specifies different sections in which particular comments jpayne@68: can appear. This function provides for comments to be emitted jpayne@68: within three sections: the header, the Setup section, and the jpayne@68: PageSetup section. Comments appearing in the first two sections jpayne@68: apply to the entire document while comments in the BeginPageSetup jpayne@68: section apply only to a single page.
jpayne@68:For comments to appear in the header section, this function should
jpayne@68: be called after the surface is created, but before a call to
jpayne@68: cairo_ps_surface_dsc_begin_setup()
.
For comments to appear in the Setup section, this function should
jpayne@68: be called after a call to cairo_ps_surface_dsc_begin_setup()
but
jpayne@68: before a call to cairo_ps_surface_dsc_begin_page_setup()
.
For comments to appear in the PageSetup section, this function
jpayne@68: should be called after a call to
jpayne@68: cairo_ps_surface_dsc_begin_page_setup()
.
Note that it is only necessary to call
jpayne@68: cairo_ps_surface_dsc_begin_page_setup()
for the first page of any
jpayne@68: surface. After a call to cairo_show_page()
or cairo_copy_page()
jpayne@68: comments are unambiguously directed to the PageSetup section of the
jpayne@68: current page. But it doesn't hurt to call this function at the
jpayne@68: beginning of every page as that consistency may make the calling
jpayne@68: code simpler.
As a final note, cairo automatically generates several comments on jpayne@68: its own. As such, applications must not manually generate any of jpayne@68: the following comments:
jpayne@68:Header section: %!PS-Adobe-3.0, %%Creator, %%CreationDate, %%Pages, jpayne@68: %%BoundingBox, %%DocumentData, %%LanguageLevel, %%EndComments.
jpayne@68:Setup section: %%BeginSetup, %%EndSetup
jpayne@68:PageSetup section: %%BeginPageSetup, %%PageBoundingBox, %%EndPageSetup.
jpayne@68:Other sections: %%BeginProlog, %%EndProlog, %%Page, %%Trailer, %%EOF
jpayne@68:Here is an example sequence showing how this function might be used:
jpayne@68:1 jpayne@68: 2 jpayne@68: 3 jpayne@68: 4 jpayne@68: 5 jpayne@68: 6 jpayne@68: 7 jpayne@68: 8 jpayne@68: 9 jpayne@68: 10 jpayne@68: 11 jpayne@68: 12 jpayne@68: 13 jpayne@68: 14 jpayne@68: 15 jpayne@68: 16 jpayne@68: 17 jpayne@68: 18 |
jpayne@68: cairo_surface_t *surface = cairo_ps_surface_create (filename, width, height); jpayne@68: ... jpayne@68: cairo_ps_surface_dsc_comment (surface, "%%Title: My excellent document"); jpayne@68: cairo_ps_surface_dsc_comment (surface, "%%Copyright: Copyright (C) 2006 Cairo Lover") jpayne@68: ... jpayne@68: cairo_ps_surface_dsc_begin_setup (surface); jpayne@68: cairo_ps_surface_dsc_comment (surface, "%%IncludeFeature: *MediaColor White"); jpayne@68: ... jpayne@68: cairo_ps_surface_dsc_begin_page_setup (surface); jpayne@68: cairo_ps_surface_dsc_comment (surface, "%%IncludeFeature: *PageSize A3"); jpayne@68: cairo_ps_surface_dsc_comment (surface, "%%IncludeFeature: *InputSlot LargeCapacity"); jpayne@68: cairo_ps_surface_dsc_comment (surface, "%%IncludeFeature: *MediaType Glossy"); jpayne@68: cairo_ps_surface_dsc_comment (surface, "%%IncludeFeature: *MediaColor Blue"); jpayne@68: ... draw to first page here .. jpayne@68: cairo_show_page (cr); jpayne@68: ... jpayne@68: cairo_ps_surface_dsc_comment (surface, "%%IncludeFeature: *PageSize A5"); jpayne@68: ... |
jpayne@68:
surface |
jpayne@68: a PostScript cairo_surface_t |
jpayne@68: jpayne@68: |
comment |
jpayne@68: a comment string to be emitted into the PostScript output |
jpayne@68: jpayne@68: |
Since: 1.2
jpayne@68:#define CAIRO_HAS_PS_SURFACE 1 jpayne@68:jpayne@68:
Defined if the PostScript surface backend is available. jpayne@68: This macro can be used to conditionally compile backend-specific code.
jpayne@68:Since: 1.2
jpayne@68:cairo_ps_level_t is used to describe the language level of the jpayne@68: PostScript Language Reference that a generated PostScript file will jpayne@68: conform to.
jpayne@68:jpayne@68: |
jpayne@68: The language level 2 of the PostScript specification. (Since 1.6) jpayne@68: |
jpayne@68: jpayne@68: |
jpayne@68: |
jpayne@68: The language level 3 of the PostScript specification. (Since 1.6) jpayne@68: |
jpayne@68: jpayne@68: |
Since: 1.6
jpayne@68: