cairo_ps_surface_create ()

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.

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 ()

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.

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.

cairo_ps_surface_set_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.

cairo_ps_surface_set_size ()

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().

cairo_ps_surface_dsc_comment ()

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_begin_setup().

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

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

Note that it is only necessary to call cairo_ps_surface_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: