@c See COPYING.docs for copyright information.

@deffn Function cairo-create (@var{target} @code{<cairo-surface-t>}) @result{} (@var{ret} @code{<cairo-t>})
Creates a new @code{<cairo-t>} with all graphics state parameters set to default
values and with @var{target} as a target surface. The target surface should be
constructed with a backend-specific function such as
@code{cairo-image-surface-create} (or any other
@samp{cairo_<backend>_surface_create} variant).

@table @var
@item target
target surface for the context

@item ret
a newly allocated @code{<cairo-t>}.
@end table

@end deffn

@c order of arguments is [width height filename].
@c filename is optional.

@deffn Function cairo-svg-surface-create  (@var{width-in-points}@tie{}@code{<double>}) (@var{height-in-points}@tie{}@code{<double>}) [(@var{filename}@tie{}@code{<char>})] @result{}@tie{} (@var{ret}@tie{}@code{<cairo-surface-t >})
Creates a SVG surface of the specified size in points to be written to
@var{filename}. If @var{filename} is not given, the output is sent to
the current output port.

The SVG surface backend recognizes the following MIME types for the data
attached to a surface (see @code{cairo-surface-set-mime-data}) when it
is used as a source pattern for drawing on this surface:
@samp{CAIRO_MIME_TYPE_JPEG}, @samp{CAIRO_MIME_TYPE_PNG},
@samp{CAIRO_MIME_TYPE_URI}. If any of them is specified, the SVG backend
emits a href with the content of MIME data instead of a surface snapshot
(PNG, Base64-encoded) in the corresponding image tag.

The unofficial MIME type @samp{CAIRO_MIME_TYPE_URI} is examined first.
If present, the URI is emitted as is: assuring the correctness of URI is
left to the client code.

If @samp{CAIRO_MIME_TYPE_URI} is not present, but
@samp{CAIRO_MIME_TYPE_JPEG} or @samp{CAIRO_MIME_TYPE_PNG} is specified,
the corresponding data is Base64-encoded and emitted.

@table @var
@item filename
a filename for the SVG output (must be writable), @samp{@code{#f}} may
be used to specify no output. This will generate a SVG surface that may
be queried and used as a source, without generating a temporary file.

@item width-in-points
width of the surface, in points (1 point == 1/72.0 inch)

@item height-in-points
height of the surface, in points (1 point == 1/72.0 inch)

@item ret
a pointer to the newly created surface. The caller owns the surface and
should call @code{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
@code{cairo-surface-status} to check for this.

@end table

Since 1.2

@end deffn

@c order of arguments is [width height filename].
@c filename is optional.

@deffn Function cairo-pdf-surface-create  (@var{width-in-points}@tie{}@code{<double>}) (@var{height-in-points}@tie{}@code{<double>}) [(@var{filename}@tie{}@code{<char>})] @result{}@tie{} (@var{ret}@tie{}@code{<cairo-surface-t >})
Creates a PDF surface of the specified size in points to be written to
@var{filename}. If @var{filename} is not given, the output is sent to
the current output port.


@table @var
@item filename
a filename for the PDF output (must be writable), @samp{@code{#f}} may
be used to specify no output. This will generate a PDF surface that may
be queried and used as a source, without generating a temporary file.

@item width-in-points
width of the surface, in points (1 point == 1/72.0 inch)

@item height-in-points
height of the surface, in points (1 point == 1/72.0 inch)

@item ret
a pointer to the newly created surface. The caller owns the surface and
should call @code{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
@code{cairo-surface-status} to check for this.

@end table

Since 1.2

@end deffn

@c order of arguments is [width height filename].

@deffn Function cairo-ps-surface-create  (@var{width-in-points}@tie{}@code{<double>}) (@var{height-in-points}@tie{}@code{<double>}) (@var{filename}@tie{}@code{<char>}) @result{}@tie{} (@var{ret}@tie{}@code{<cairo-surface-t >})
Creates a PostScript surface of the specified size in points to be
written to @var{filename}. See @code{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 @code{cairo-ps-surface-set-size}.

@table @var
@item filename
a filename for the PS output (must be writable), @samp{@code{#f}} 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.

@item width-in-points
width of the surface, in points (1 point == 1/72.0 inch)

@item height-in-points
height of the surface, in points (1 point == 1/72.0 inch)

@item ret
a pointer to the newly created surface. The caller owns the surface and
should call @code{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
@code{cairo-surface-status} to check for this.

@end table

Since 1.2

@end deffn
