[cairo-commit] cairo/src cairo-image-surface.c, 1.70,
1.71 cairo-pdf-surface.c, 1.73, 1.74 cairo-pdf.h, 1.13,
1.14 cairo-ps-surface.c, 1.69, 1.70 cairo-ps.h, 1.9, 1.10
Carl Worth
commit at pdx.freedesktop.org
Wed Jan 18 16:40:19 PST 2006
Committed by: cworth
Update of /cvs/cairo/cairo/src
In directory gabe:/tmp/cvs-serv14934/src
Modified Files:
cairo-image-surface.c cairo-pdf-surface.c cairo-pdf.h
cairo-ps-surface.c cairo-ps.h
Log Message:
2006-01-18 Carl Worth <cworth at cworth.org>
* src/cairo-image-surface.c: Change documentation to recommend
cairo_paint rather than cairo_rectangle;cairo_fill for clearing a
surface.
* src/cairo-pdf.h:
* src/cairo-pdf-surface.c: (cairo_pdf_surface_create_for_stream),
(cairo_pdf_surface_create): Add documentation. Add a
cairo_content_t argument to PDF surface constructors.
* src/cairo-ps.h:
* src/cairo-ps-surface.c: (cairo_ps_surface_create),
(cairo_ps_surface_create_for_stream): Add documentation. Add a
cairo_content_t argument to PS surface constructors.
* test/multi-page.c: (main):
* test/cairo-test.c: (create_ps_surface), (create_pdf_surface):
Track changes in PS/PDF surface constructor API.
Index: cairo-image-surface.c
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo-image-surface.c,v
retrieving revision 1.70
retrieving revision 1.71
diff -u -d -r1.70 -r1.71
--- cairo-image-surface.c 18 Jan 2006 01:01:37 -0000 1.70
+++ cairo-image-surface.c 19 Jan 2006 00:40:17 -0000 1.71
@@ -189,8 +189,8 @@
*
* Creates an image surface of the specified format and
* dimensions. The initial contents of the surface is undefined; you
- * must explicitely clear the buffer, using, for example,
- * cairo_rectangle() and cairo_fill() if you want it cleared.
+ * must explicitly initialize the surface contents, using, for
+ * example, cairo_paint().
*
* Return value: a pointer to the newly created surface. The caller
* owns the surface and should call cairo_surface_destroy when done
Index: cairo-pdf-surface.c
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo-pdf-surface.c,v
retrieving revision 1.73
retrieving revision 1.74
diff -u -d -r1.73 -r1.74
--- cairo-pdf-surface.c 18 Jan 2006 01:01:39 -0000 1.73
+++ cairo-pdf-surface.c 19 Jan 2006 00:40:17 -0000 1.74
@@ -308,11 +308,38 @@
return _cairo_paginated_surface_create (target, content, width, height);
}
+/**
+ * cairo_pdf_surface_create_for_stream:
+ * @write: a #cairo_write_func_t to accept the output data
+ * @closure: the closure argument for @write
+ * @content: CAIRO_CONTENT_COLOR_ALPHA or CAIRO_CONTENT_COLOR
+ * @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)
+ *
+ * Creates a PDF surface of the specified size in points to be written
+ * incrementally to the stream represented by @write and @closure.
+ *
+ * The @content argument is used to specify whether the rendering
+ * semantics should behave as if destination alpha is available. The
+ * expectation is that the value for @content will be selected to
+ * achieve consistent results with a display surface that either has
+ * or does not have destination alpha (for example,
+ * CAIRO_FORMAT_ARGB32 vs. CAIRO_FORMAT_RGB24).
+ *
+ * Return value: 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_surface_t *
cairo_pdf_surface_create_for_stream (cairo_write_func_t write,
void *closure,
- double width,
- double height)
+ cairo_content_t content,
+ double width_in_points,
+ double height_in_points)
{
cairo_output_stream_t *stream;
@@ -322,17 +349,40 @@
return (cairo_surface_t*) &_cairo_surface_nil;
}
- /* XXX: content here is hard-coded but should be passed in (API
- * change that needs to be discussed on the list). */
- return _cairo_pdf_surface_create_for_stream_internal (stream,
- CAIRO_CONTENT_COLOR_ALPHA,
+ return _cairo_pdf_surface_create_for_stream_internal (stream, content,
width, height);
}
+/**
+ * cairo_pdf_surface_create:
+ * @filename: a filename for the PDF output (must be writable)
+ * @content: CAIRO_CONTENT_COLOR_ALPHA or CAIRO_CONTENT_COLOR
+ * @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)
+ *
+ * Creates a PDF surface of the specified size in points to be written
+ * to @filename.
+ *
+ * The @content argument is used to specify whether the rendering
+ * semantics should behave as if destination alpha is available. The
+ * expectation is that the value for @content will be selected to
+ * achieve consistent results with a display surface that either has
+ * or does not have destination alpha (for example,
+ * CAIRO_FORMAT_ARGB32 vs. CAIRO_FORMAT_RGB24).
+ *
+ * Return value: 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_surface_t *
cairo_pdf_surface_create (const char *filename,
- double width,
- double height)
+ cairo_content_t content,
+ double width_in_points,
+ double height_in_points)
{
cairo_output_stream_t *stream;
@@ -342,10 +392,7 @@
return (cairo_surface_t*) &_cairo_surface_nil;
}
- /* XXX: content here is hard-coded but should be passed in (API
- * change that needs to be discussed on the list). */
- return _cairo_pdf_surface_create_for_stream_internal (stream,
- CAIRO_CONTENT_COLOR_ALPHA,
+ return _cairo_pdf_surface_create_for_stream_internal (stream, content,
width, height);
}
@@ -361,9 +408,11 @@
* @x_dpi: horizontal dpi
* @y_dpi: vertical dpi
*
- * Set horizontal and vertical resolution for image fallbacks. When
- * the pdf backend needs to fall back to image overlays, it will use
- * this resolution.
+ * Set the horizontal and vertical resolution for image fallbacks.
+ * When the pdf backend needs to fall back to image overlays, it will
+ * use this resolution. These DPI values are not used for any other
+ * purpose, (in particular, they do not have any bearing on the size
+ * passed to cairo_pdf_surface_create() nor on the CTM).
**/
void
cairo_pdf_surface_set_dpi (cairo_surface_t *surface,
Index: cairo-pdf.h
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo-pdf.h,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -d -r1.13 -r1.14
--- cairo-pdf.h 18 Jan 2006 01:01:39 -0000 1.13
+++ cairo-pdf.h 19 Jan 2006 00:40:17 -0000 1.14
@@ -45,12 +45,14 @@
cairo_public cairo_surface_t *
cairo_pdf_surface_create (const char *filename,
+ cairo_content_t content,
double width_in_points,
double height_in_points);
cairo_public cairo_surface_t *
cairo_pdf_surface_create_for_stream (cairo_write_func_t write_func,
void *closure,
+ cairo_content_t content,
double width_in_points,
double height_in_points);
Index: cairo-ps-surface.c
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo-ps-surface.c,v
retrieving revision 1.69
retrieving revision 1.70
diff -u -d -r1.69 -r1.70
--- cairo-ps-surface.c 18 Jan 2006 01:01:40 -0000 1.69
+++ cairo-ps-surface.c 19 Jan 2006 00:40:17 -0000 1.70
@@ -160,8 +160,34 @@
content, width, height);
}
+/**
+ * cairo_ps_surface_create:
+ * @filename: a filename for the PS output (must be writable)
+ * @content: CAIRO_CONTENT_COLOR_ALPHA or CAIRO_CONTENT_COLOR
+ * @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)
+ *
+ * Creates a PostScript surface of the specified size in points to be
+ * written to @filename.
+ *
+ * The @content argument is used to specify whether the rendering
+ * semantics should behave as if destination alpha is available. The
+ * expectation is that the value for @content will be selected to
+ * achieve consistent results with a display surface that either has
+ * or does not have destination alpha (for example,
+ * CAIRO_FORMAT_ARGB32 vs. CAIRO_FORMAT_RGB24).
+ *
+ * Return value: 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_surface_t *
cairo_ps_surface_create (const char *filename,
+ cairo_content_t content,
double width_in_points,
double height_in_points)
{
@@ -173,17 +199,43 @@
return (cairo_surface_t*) &_cairo_surface_nil;
}
- /* XXX: content here is hard-coded but should be passed in (API
- * change that needs to be discussed on the list). */
return _cairo_ps_surface_create_for_stream_internal (stream,
- CAIRO_CONTENT_COLOR_ALPHA,
+ content,
width_in_points,
height_in_points);
}
+/**
+ * cairo_ps_surface_create_for_stream:
+ * @write: a #cairo_write_func_t to accept the output data
+ * @closure: the closure argument for @write
+ * @content: CAIRO_CONTENT_COLOR_ALPHA or CAIRO_CONTENT_COLOR
+ * @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)
+ *
+ * Creates a PostScript surface of the specified size in points to be
+ * written incrementally to the stream represented by @write and
+ * @closure.
+ *
+ * The @content argument is used to specify whether the rendering
+ * semantics should behave as if destination alpha is available. The
+ * expectation is that the value for @content will be selected to
+ * achieve consistent results with a display surface that either has
+ * or does not have destination alpha (for example,
+ * CAIRO_FORMAT_ARGB32 vs. CAIRO_FORMAT_RGB24).
+ *
+ * Return value: 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_surface_t *
cairo_ps_surface_create_for_stream (cairo_write_func_t write_func,
void *closure,
+ cairo_content_t content,
double width_in_points,
double height_in_points)
{
@@ -195,10 +247,8 @@
return (cairo_surface_t*) &_cairo_surface_nil;
}
- /* XXX: content here is hard-coded but should be passed in (API
- * change that needs to be discussed on the list). */
return _cairo_ps_surface_create_for_stream_internal (stream,
- CAIRO_CONTENT_COLOR_ALPHA,
+ content,
width_in_points,
height_in_points);
}
@@ -215,9 +265,11 @@
* @x_dpi: horizontal dpi
* @y_dpi: vertical dpi
*
- * Set horizontal and vertical resolution for image fallbacks. When
- * the postscript backend needs to fall back to image overlays, it
- * will use this resolution.
+ * Set the horizontal and vertical resolution for image fallbacks.
+ * When the ps backend needs to fall back to image overlays, it will
+ * use this resolution. These DPI values are not used for any other
+ * purpose, (in particular, they do not have any bearing on the size
+ * passed to cairo_ps_surface_create() nor on the CTM).
**/
void
cairo_ps_surface_set_dpi (cairo_surface_t *surface,
Index: cairo-ps.h
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo-ps.h,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -d -r1.9 -r1.10
--- cairo-ps.h 18 Jan 2006 01:01:40 -0000 1.9
+++ cairo-ps.h 19 Jan 2006 00:40:17 -0000 1.10
@@ -49,12 +49,14 @@
cairo_public cairo_surface_t *
cairo_ps_surface_create (const char *filename,
+ cairo_content_t content,
double width_in_points,
double height_in_points);
cairo_public cairo_surface_t *
cairo_ps_surface_create_for_stream (cairo_write_func_t write_func,
void *closure,
+ cairo_content_t content,
double width_in_points,
double height_in_points);
More information about the cairo-commit
mailing list