[cairo-commit] src/cairo-pdf-surface.c src/cairo-ps-surface.c src/cairo-svg-surface.c

[Chris Wilson]

 src/cairo-pdf-surface.c |   10 ++++++++--
 src/cairo-ps-surface.c  |   10 ++++++++--
 src/cairo-svg-surface.c |   10 ++++++++--
 3 files changed, 24 insertions(+), 6 deletions(-)

New commits:
commit 71e4f7e3a10e6c9794360473d0114b27b42bcead
Author: Chris Wilson <chris at chris-wilson.co.uk>
Date:   Mon Oct 20 23:54:57 2008 +0100

    Add API documentation for NULL filenames and write_funcs.
    
    Mention in the API docs that you can pass a NULL filename to
    cairo_(pdf|ps|svg)_surface_create in order to construct a queryable
    surface without generating any temporary files. Similarly when passing a
    NULL write_func to cairo_pdf_surface_create_for_stream et al.

diff --git a/src/cairo-pdf-surface.c b/src/cairo-pdf-surface.c
index 507f522..b07ee98 100644
--- a/src/cairo-pdf-surface.c
+++ b/src/cairo-pdf-surface.c
@@ -326,7 +326,10 @@ BAIL0:
 
 /**
  * cairo_pdf_surface_create_for_stream:
- * @write_func: a #cairo_write_func_t to accept the output data
+ * @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)
@@ -363,7 +366,10 @@ cairo_pdf_surface_create_for_stream (cairo_write_func_t		 write_func,
 
 /**
  * cairo_pdf_surface_create:
- * @filename: a filename for the PDF output (must be writable)
+ * @filename: a filename for the PDF output (must be writable), %NULL 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.
  * @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)
  *
diff --git a/src/cairo-ps-surface.c b/src/cairo-ps-surface.c
index 83c94a8..3a0e982 100644
--- a/src/cairo-ps-surface.c
+++ b/src/cairo-ps-surface.c
@@ -790,7 +790,10 @@ _cairo_ps_surface_create_for_stream_internal (cairo_output_stream_t *stream,
 
 /**
  * cairo_ps_surface_create:
- * @filename: a filename for the PS output (must be writable)
+ * @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)
  *
@@ -830,7 +833,10 @@ cairo_ps_surface_create (const char		*filename,
 
 /**
  * cairo_ps_surface_create_for_stream:
- * @write_func: a #cairo_write_func_t to accept the output data
+ * @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)
diff --git a/src/cairo-svg-surface.c b/src/cairo-svg-surface.c
index 428c8fb..1219d18 100644
--- a/src/cairo-svg-surface.c
+++ b/src/cairo-svg-surface.c
@@ -155,7 +155,10 @@ static const cairo_paginated_surface_backend_t cairo_svg_surface_paginated_backe
 
 /**
  * cairo_svg_surface_create_for_stream:
- * @write_func: a #cairo_write_func_t to accept the output data
+ * @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)
@@ -190,7 +193,10 @@ cairo_svg_surface_create_for_stream (cairo_write_func_t		 write_func,
 
 /**
  * cairo_svg_surface_create:
- * @filename: a filename for the SVG output (must be writable)
+ * @filename: a filename for the SVG output (must be writable), %NULL 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.
  * @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)
  *