[prev in list] [next in list] [prev in thread] [next in thread]
List: cairo-commit
Subject: [cairo-commit] [cairo-www] src/documentation
From: cworth () freedesktop ! org (Carl Worth)
Date: 2009-09-27 6:51:53
Message-ID: 20090927065153.6540413005A () annarchy ! freedesktop ! org
[Download RAW message or body]
src/documentation/using_the_postscript_surface.mdwn | 156 ++++++++++++++++++++
1 file changed, 156 insertions(+)
New commits:
commit a8a49c1cc7d9955ad885cfc8a41fb1006019de32
Author: ajohnson <ajohnson@web>
Date: Sat Sep 26 23:51:53 2009 -0700
diff --git a/src/documentation/using_the_postscript_surface.mdwn \
b/src/documentation/using_the_postscript_surface.mdwn new file mode 100644
index 0000000..f4e511c
--- /dev/null
+++ b/src/documentation/using_the_postscript_surface.mdwn
@@ -0,0 +1,156 @@
+[[!meta title="Using the PostScript surface"]]
+
+# Coordinate system
+
+The PostScript surface coordinate space is in points. One point is 1/72 inch. The \
user space ctm can be scaled to work in other units: +
+millimeters:
+
+cairo_scale (cr, 72/25.4, 72/25.4);
+
+inches
+
+cairo_scale (cr, 72, 72);
+
+# Page Size
+
+The page size is in points. For example A4 paper is 595 points wide by 842 points \
high. Letter paper is 612 by 792 points. +
+The [gv documentation](http://www.gnu.org/software/gv/manual/html_node/Paper-Keywords-and-paper-size-in-points.html) \
lists some Common paper sizes and the size in points. +
+Page size can be changed for each page using cairo\_ps\_surface\_set\_size ().
+
+# PostScript Level
+
+By default cairo will emit Language Level 3 PostScript. The \
cairo\_ps\_surface\_restrict\_to\_level () function may be used to limit the Language \
Level used. +
+The benefit of using language level 3 is support for additional features such as \
gradient patterns. However Language Level 2 printers can not print PostScript \
containing Language Level 3 features. +
+Note that when when Language Level 3 is permitted the, "LanguageLevel" DSC comment \
in the output may still indicate 2 if no level 3 features are used. +
+
+# Encapsulated PostScript (EPS)
+
+When generating PostScript output that will be imported as diagrams into \
applications the EPS format is used. EPS files must contain only one page. Language \
level 2 or 3 can be used with EPS mode. +
+Note that cairo does not include the device independent preview.
+
+The [Encapsulated PostScript \
Specification](http://www.adobe.com/devnet/postscript/pdfs/5002.EPSF_Spec.pdf) \
contains describes how to embed EPS files into PostScript. +
+# Printing in Landscape
+
+The method for printing in landscape depends on whether PostScript or Encapsulated \
PostScript is being generated. +
+##PostScript
+
+When generating landscape PostScript output the surface should not be created with a \
width greater than the height. Instead create the surface with a height greater than \
the width and rotate the cairo drawing context. The "%PageOrientation" DSC comment is \
used by PostScript viewers to indicate the orientation of the page. +
+The steps to create a landscape page are:
+
+1. Set the page size to a portrait size eg (595, 842) for A4.
+
+2. Rotate user space 90 degrees counterclockwise and move the origin to the correct \
location +
+3. Insert the "%PageOrientation: Landscape" DSC comment.
+
+Evince, gv, or okular can be used to check that the output.
+
+The following code prints one portrait page followed by one landscape page.
+
+ #include <cairo.h>
+ #include <cairo-ps.h>
+
+ #define PAGE_WIDTH 595
+ #define PAGE_HEIGHT 842
+
+ #define BORDER 50
+
+ void draw (cairo_t *cr, const char *text, int width, int height)
+ {
+ char buf[100];
+
+ cairo_rectangle (cr, BORDER, BORDER, width - 2*BORDER, height - 2*BORDER);
+ cairo_set_line_width (cr, 2);
+ cairo_stroke (cr);
+
+ cairo_select_font_face (cr, "Sans", CAIRO_FONT_SLANT_NORMAL, \
CAIRO_FONT_WEIGHT_NORMAL); + cairo_set_font_size (cr, 60);
+ cairo_move_to (cr, 200, height/3);
+ cairo_show_text (cr, text);
+
+ sprintf (buf, "Width: %d points Height: %d points", width, height);
+ cairo_set_font_size (cr, 18);
+ cairo_move_to (cr, 120, height*2/3);
+ cairo_show_text (cr, buf);
+ }
+
+ int main()
+ {
+ cairo_surface_t *surface;
+ cairo_t *cr;
+ cairo_matrix_t matrix;
+
+ surface = cairo_ps_surface_create ("output.ps", PAGE_WIDTH, PAGE_HEIGHT);
+ cr = cairo_create (surface);
+
+ /* Print portrait page */
+ cairo_ps_surface_dsc_begin_page_setup (surface);
+ cairo_ps_surface_dsc_comment (surface, "%%PageOrientation: Portrait");
+ draw (cr, "Portrait", PAGE_WIDTH, PAGE_HEIGHT);
+ cairo_surface_show_page (surface);
+
+ /* Print landscape page */
+ cairo_ps_surface_dsc_begin_page_setup (surface);
+ cairo_ps_surface_dsc_comment (surface, "%%PageOrientation: Landscape");
+
+ /* Move the origin to landscape origin and rotate counterclockwise
+ * 90 degrees.
+ *
+ * This is equivilent to:
+ * cairo_translate (cr, 0, PAGE_HEIGHT);
+ * cairo_rotate (cr, -M_PI/2);
+ */
+ cairo_translate (cr, 0, PAGE_HEIGHT);
+ cairo_matrix_init (&matrix, 0, -1, 1, 0, 0, 0);
+ cairo_transform (cr, &matrix);
+
+ draw (cr, "Landscape", PAGE_HEIGHT, PAGE_WIDTH);
+ cairo_surface_show_page (surface);
+
+ cairo_destroy (cr);
+ cairo_surface_finish (surface);
+ cairo_surface_destroy (surface);
+
+ return 0;
+ }
+
+##Encapsulated PostScript
+
+When generating landscape EPS output the surface width can be greater than the \
height. +
+For example:
+
+ surface = cairo_ps_surface_create (filename, 400, 200)
+ cairo_ps_surface_set_eps (surface, TRUE);
+
+
+# Fonts
+
+PS surface natively supports Type 1 and TrueType fonts. All other fonts types \
(including OpenType/PS) are converted to Type 1. +
+Fonts are always subsetted and embedded.
+
+
+#Fallback images
+
+Cairo will ensure that the PostScript output looks the same as the image surface for \
the same set of cairo commands. When cairo drawing operations are performed that can \
be be natively represented in PostScript, the drawing is rasterized and embedded in \
the output. +
+Since cairo 1.6 the rasterization of unsupported operations is limited to the \
smallest rectangle or set of rectangles required to draw the unsupported operations. \
+ +Fallback images are the main cause of large file sizes and slow printing times. \
Fallback images have a comment containing the size and location of the fallback. +
+ > grep 'Fallback' output.ps
+ output.ps:% Fallback Image: x=100, y=100, w=299, h=50 res=300dpi size=783750
+ output.ps:% Fallback Image: x=100, y=150, w=350, h=250 res=300dpi size=4560834
+ output.ps:% Fallback Image: x=150, y=400, w=299, h=50 res=300dpi size=783750
+
_______________________________________________
cairo-commit mailing list
cairo-commit@lists.cairographics.org
http://lists.cairographics.org/mailman/listinfo/cairo-commit
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic