Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/gtk-doc/html/cairo/cairo-PostScript-Surfaces.html @ 68:5028fdace37b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 16:23:26 -0400
parents
children
rev   line source
jpayne@68 1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
jpayne@68 2 <html>
jpayne@68 3 <head>
jpayne@68 4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
jpayne@68 5 <title>PostScript Surfaces: Cairo: A Vector Graphics Library</title>
jpayne@68 6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
jpayne@68 7 <link rel="home" href="index.html" title="Cairo: A Vector Graphics Library">
jpayne@68 8 <link rel="up" href="cairo-surfaces.html" title="Surfaces">
jpayne@68 9 <link rel="prev" href="cairo-PNG-Support.html" title="PNG Support">
jpayne@68 10 <link rel="next" href="cairo-Recording-Surfaces.html" title="Recording Surfaces">
jpayne@68 11 <meta name="generator" content="GTK-Doc V1.27 (XML mode)">
jpayne@68 12 <link rel="stylesheet" href="style.css" type="text/css">
jpayne@68 13 </head>
jpayne@68 14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
jpayne@68 15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
jpayne@68 16 <td width="100%" align="left" class="shortcuts">
jpayne@68 17 <a href="#" class="shortcut">Top</a><span id="nav_description">  <span class="dim">|</span> 
jpayne@68 18 <a href="#cairo-PostScript-Surfaces.description" class="shortcut">Description</a></span>
jpayne@68 19 </td>
jpayne@68 20 <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
jpayne@68 21 <td><a accesskey="u" href="cairo-surfaces.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
jpayne@68 22 <td><a accesskey="p" href="cairo-PNG-Support.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
jpayne@68 23 <td><a accesskey="n" href="cairo-Recording-Surfaces.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
jpayne@68 24 </tr></table>
jpayne@68 25 <div class="refentry">
jpayne@68 26 <a name="cairo-PostScript-Surfaces"></a><div class="titlepage"></div>
jpayne@68 27 <div class="refnamediv"><table width="100%"><tr>
jpayne@68 28 <td valign="top">
jpayne@68 29 <h2><span class="refentrytitle"><a name="cairo-PostScript-Surfaces.top_of_page"></a>PostScript Surfaces</span></h2>
jpayne@68 30 <p>PostScript Surfaces — Rendering PostScript documents</p>
jpayne@68 31 </td>
jpayne@68 32 <td class="gallery_image" valign="top" align="right"></td>
jpayne@68 33 </tr></table></div>
jpayne@68 34 <div class="refsect1">
jpayne@68 35 <a name="cairo-PostScript-Surfaces.functions"></a><h2>Functions</h2>
jpayne@68 36 <div class="informaltable"><table class="informaltable" width="100%" border="0">
jpayne@68 37 <colgroup>
jpayne@68 38 <col width="150px" class="functions_return">
jpayne@68 39 <col class="functions_name">
jpayne@68 40 </colgroup>
jpayne@68 41 <tbody>
jpayne@68 42 <tr>
jpayne@68 43 <td class="function_type">
jpayne@68 44 <a class="link" href="cairo-cairo-surface-t.html#cairo-surface-t" title="cairo_surface_t"><span class="returnvalue">cairo_surface_t</span></a> *
jpayne@68 45 </td>
jpayne@68 46 <td class="function_name">
jpayne@68 47 <a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-surface-create" title="cairo_ps_surface_create ()">cairo_ps_surface_create</a> <span class="c_punctuation">()</span>
jpayne@68 48 </td>
jpayne@68 49 </tr>
jpayne@68 50 <tr>
jpayne@68 51 <td class="function_type">
jpayne@68 52 <a class="link" href="cairo-cairo-surface-t.html#cairo-surface-t" title="cairo_surface_t"><span class="returnvalue">cairo_surface_t</span></a> *
jpayne@68 53 </td>
jpayne@68 54 <td class="function_name">
jpayne@68 55 <a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-surface-create-for-stream" title="cairo_ps_surface_create_for_stream ()">cairo_ps_surface_create_for_stream</a> <span class="c_punctuation">()</span>
jpayne@68 56 </td>
jpayne@68 57 </tr>
jpayne@68 58 <tr>
jpayne@68 59 <td class="function_type">
jpayne@68 60 <span class="returnvalue">void</span>
jpayne@68 61 </td>
jpayne@68 62 <td class="function_name">
jpayne@68 63 <a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-surface-restrict-to-level" title="cairo_ps_surface_restrict_to_level ()">cairo_ps_surface_restrict_to_level</a> <span class="c_punctuation">()</span>
jpayne@68 64 </td>
jpayne@68 65 </tr>
jpayne@68 66 <tr>
jpayne@68 67 <td class="function_type">
jpayne@68 68 <span class="returnvalue">void</span>
jpayne@68 69 </td>
jpayne@68 70 <td class="function_name">
jpayne@68 71 <a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-get-levels" title="cairo_ps_get_levels ()">cairo_ps_get_levels</a> <span class="c_punctuation">()</span>
jpayne@68 72 </td>
jpayne@68 73 </tr>
jpayne@68 74 <tr>
jpayne@68 75 <td class="function_type">const <span class="returnvalue">char</span> *
jpayne@68 76 </td>
jpayne@68 77 <td class="function_name">
jpayne@68 78 <a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-level-to-string" title="cairo_ps_level_to_string ()">cairo_ps_level_to_string</a> <span class="c_punctuation">()</span>
jpayne@68 79 </td>
jpayne@68 80 </tr>
jpayne@68 81 <tr>
jpayne@68 82 <td class="function_type">
jpayne@68 83 <span class="returnvalue">void</span>
jpayne@68 84 </td>
jpayne@68 85 <td class="function_name">
jpayne@68 86 <a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-surface-set-eps" title="cairo_ps_surface_set_eps ()">cairo_ps_surface_set_eps</a> <span class="c_punctuation">()</span>
jpayne@68 87 </td>
jpayne@68 88 </tr>
jpayne@68 89 <tr>
jpayne@68 90 <td class="function_type">
jpayne@68 91 <a class="link" href="cairo-Types.html#cairo-bool-t" title="cairo_bool_t"><span class="returnvalue">cairo_bool_t</span></a>
jpayne@68 92 </td>
jpayne@68 93 <td class="function_name">
jpayne@68 94 <a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-surface-get-eps" title="cairo_ps_surface_get_eps ()">cairo_ps_surface_get_eps</a> <span class="c_punctuation">()</span>
jpayne@68 95 </td>
jpayne@68 96 </tr>
jpayne@68 97 <tr>
jpayne@68 98 <td class="function_type">
jpayne@68 99 <span class="returnvalue">void</span>
jpayne@68 100 </td>
jpayne@68 101 <td class="function_name">
jpayne@68 102 <a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-surface-set-size" title="cairo_ps_surface_set_size ()">cairo_ps_surface_set_size</a> <span class="c_punctuation">()</span>
jpayne@68 103 </td>
jpayne@68 104 </tr>
jpayne@68 105 <tr>
jpayne@68 106 <td class="function_type">
jpayne@68 107 <span class="returnvalue">void</span>
jpayne@68 108 </td>
jpayne@68 109 <td class="function_name">
jpayne@68 110 <a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-surface-dsc-begin-setup" title="cairo_ps_surface_dsc_begin_setup ()">cairo_ps_surface_dsc_begin_setup</a> <span class="c_punctuation">()</span>
jpayne@68 111 </td>
jpayne@68 112 </tr>
jpayne@68 113 <tr>
jpayne@68 114 <td class="function_type">
jpayne@68 115 <span class="returnvalue">void</span>
jpayne@68 116 </td>
jpayne@68 117 <td class="function_name">
jpayne@68 118 <a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-surface-dsc-begin-page-setup" title="cairo_ps_surface_dsc_begin_page_setup ()">cairo_ps_surface_dsc_begin_page_setup</a> <span class="c_punctuation">()</span>
jpayne@68 119 </td>
jpayne@68 120 </tr>
jpayne@68 121 <tr>
jpayne@68 122 <td class="function_type">
jpayne@68 123 <span class="returnvalue">void</span>
jpayne@68 124 </td>
jpayne@68 125 <td class="function_name">
jpayne@68 126 <a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-surface-dsc-comment" title="cairo_ps_surface_dsc_comment ()">cairo_ps_surface_dsc_comment</a> <span class="c_punctuation">()</span>
jpayne@68 127 </td>
jpayne@68 128 </tr>
jpayne@68 129 </tbody>
jpayne@68 130 </table></div>
jpayne@68 131 </div>
jpayne@68 132 <div class="refsect1">
jpayne@68 133 <a name="cairo-PostScript-Surfaces.other"></a><h2>Types and Values</h2>
jpayne@68 134 <div class="informaltable"><table class="informaltable" width="100%" border="0">
jpayne@68 135 <colgroup>
jpayne@68 136 <col width="150px" class="name">
jpayne@68 137 <col class="description">
jpayne@68 138 </colgroup>
jpayne@68 139 <tbody>
jpayne@68 140 <tr>
jpayne@68 141 <td class="define_keyword">#define</td>
jpayne@68 142 <td class="function_name"><a class="link" href="cairo-PostScript-Surfaces.html#CAIRO-HAS-PS-SURFACE:CAPS" title="CAIRO_HAS_PS_SURFACE">CAIRO_HAS_PS_SURFACE</a></td>
jpayne@68 143 </tr>
jpayne@68 144 <tr>
jpayne@68 145 <td class="datatype_keyword">enum</td>
jpayne@68 146 <td class="function_name"><a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-level-t" title="enum cairo_ps_level_t">cairo_ps_level_t</a></td>
jpayne@68 147 </tr>
jpayne@68 148 </tbody>
jpayne@68 149 </table></div>
jpayne@68 150 </div>
jpayne@68 151 <div class="refsect1">
jpayne@68 152 <a name="cairo-PostScript-Surfaces.description"></a><h2>Description</h2>
jpayne@68 153 <p>The PostScript surface is used to render cairo graphics to Adobe
jpayne@68 154 PostScript files and is a multi-page vector surface backend.</p>
jpayne@68 155 <p>The following mime types are supported: <a class="link" href="cairo-cairo-surface-t.html#CAIRO-MIME-TYPE-JPEG:CAPS" title="CAIRO_MIME_TYPE_JPEG"><code class="literal">CAIRO_MIME_TYPE_JPEG</code></a>,
jpayne@68 156 <a class="link" href="cairo-cairo-surface-t.html#CAIRO-MIME-TYPE-UNIQUE-ID:CAPS" title="CAIRO_MIME_TYPE_UNIQUE_ID"><code class="literal">CAIRO_MIME_TYPE_UNIQUE_ID</code></a>,
jpayne@68 157 <a class="link" href="cairo-cairo-surface-t.html#CAIRO-MIME-TYPE-CCITT-FAX:CAPS" title="CAIRO_MIME_TYPE_CCITT_FAX"><code class="literal">CAIRO_MIME_TYPE_CCITT_FAX</code></a>, <a class="link" href="cairo-cairo-surface-t.html#CAIRO-MIME-TYPE-CCITT-FAX-PARAMS:CAPS" title="CAIRO_MIME_TYPE_CCITT_FAX_PARAMS"><code class="literal">CAIRO_MIME_TYPE_CCITT_FAX_PARAMS</code></a>,
jpayne@68 158 <a class="link" href="cairo-cairo-surface-t.html#CAIRO-MIME-TYPE-CCITT-FAX:CAPS" title="CAIRO_MIME_TYPE_CCITT_FAX"><code class="literal">CAIRO_MIME_TYPE_CCITT_FAX</code></a>, <a class="link" href="cairo-cairo-surface-t.html#CAIRO-MIME-TYPE-CCITT-FAX-PARAMS:CAPS" title="CAIRO_MIME_TYPE_CCITT_FAX_PARAMS"><code class="literal">CAIRO_MIME_TYPE_CCITT_FAX_PARAMS</code></a>,
jpayne@68 159 <a class="link" href="cairo-cairo-surface-t.html#CAIRO-MIME-TYPE-EPS:CAPS" title="CAIRO_MIME_TYPE_EPS"><code class="literal">CAIRO_MIME_TYPE_EPS</code></a>, <a class="link" href="cairo-cairo-surface-t.html#CAIRO-MIME-TYPE-EPS-PARAMS:CAPS" title="CAIRO_MIME_TYPE_EPS_PARAMS"><code class="literal">CAIRO_MIME_TYPE_EPS_PARAMS</code></a>.</p>
jpayne@68 160 <p>Source surfaces used by the PostScript surface that have a
jpayne@68 161 <a class="link" href="cairo-cairo-surface-t.html#CAIRO-MIME-TYPE-UNIQUE-ID:CAPS" title="CAIRO_MIME_TYPE_UNIQUE_ID"><code class="literal">CAIRO_MIME_TYPE_UNIQUE_ID</code></a> mime type will be stored in PostScript
jpayne@68 162 printer memory for the duration of the print
jpayne@68 163 job. <a class="link" href="cairo-cairo-surface-t.html#CAIRO-MIME-TYPE-UNIQUE-ID:CAPS" title="CAIRO_MIME_TYPE_UNIQUE_ID"><code class="literal">CAIRO_MIME_TYPE_UNIQUE_ID</code></a> should only be used for small
jpayne@68 164 frequently used sources.</p>
jpayne@68 165 <p>The <a class="link" href="cairo-cairo-surface-t.html#CAIRO-MIME-TYPE-CCITT-FAX:CAPS" title="CAIRO_MIME_TYPE_CCITT_FAX"><code class="literal">CAIRO_MIME_TYPE_CCITT_FAX</code></a> and <a class="link" href="cairo-cairo-surface-t.html#CAIRO-MIME-TYPE-CCITT-FAX-PARAMS:CAPS" title="CAIRO_MIME_TYPE_CCITT_FAX_PARAMS"><code class="literal">CAIRO_MIME_TYPE_CCITT_FAX_PARAMS</code></a> mime types
jpayne@68 166 are documented in <a class="link" href="cairo-PDF-Surfaces.html#ccitt" title="CCITT Fax Images">CCITT Fax Images</a>.</p>
jpayne@68 167 <div class="refsect2">
jpayne@68 168 <a name="eps"></a><h3>Embedding EPS files</h3>
jpayne@68 169 <p>Encapsulated PostScript files can be embedded in the PS output by
jpayne@68 170 setting the CAIRO_MIME_TYPE_EPS mime data on a surface to the EPS
jpayne@68 171 data and painting the surface. The EPS will be scaled and
jpayne@68 172 translated to the extents of the surface the EPS data is attached
jpayne@68 173 to.</p>
jpayne@68 174 <p>The <a class="link" href="cairo-cairo-surface-t.html#CAIRO-MIME-TYPE-EPS:CAPS" title="CAIRO_MIME_TYPE_EPS"><code class="literal">CAIRO_MIME_TYPE_EPS</code></a> mime type requires the
jpayne@68 175 <a class="link" href="cairo-cairo-surface-t.html#CAIRO-MIME-TYPE-EPS-PARAMS:CAPS" title="CAIRO_MIME_TYPE_EPS_PARAMS"><code class="literal">CAIRO_MIME_TYPE_EPS_PARAMS</code></a> mime data to also be provided in order
jpayne@68 176 to specify the embeddding parameters. <a class="link" href="cairo-cairo-surface-t.html#CAIRO-MIME-TYPE-EPS-PARAMS:CAPS" title="CAIRO_MIME_TYPE_EPS_PARAMS"><code class="literal">CAIRO_MIME_TYPE_EPS_PARAMS</code></a>
jpayne@68 177 mime data must contain a string of the form "bbox=[llx lly urx
jpayne@68 178 ury]" that specifies the bounding box (in PS coordinates) of the
jpayne@68 179 EPS graphics. The parameters are: lower left x, lower left y, upper
jpayne@68 180 right x, upper right y. Normally the bbox data is identical to the
jpayne@68 181 %%<code class="literal">BoundingBox</code> data in the EPS file.</p>
jpayne@68 182 </div>
jpayne@68 183 </div>
jpayne@68 184 <div class="refsect1">
jpayne@68 185 <a name="cairo-PostScript-Surfaces.functions_details"></a><h2>Functions</h2>
jpayne@68 186 <div class="refsect2">
jpayne@68 187 <a name="cairo-ps-surface-create"></a><h3>cairo_ps_surface_create ()</h3>
jpayne@68 188 <pre class="programlisting"><a class="link" href="cairo-cairo-surface-t.html#cairo-surface-t" title="cairo_surface_t"><span class="returnvalue">cairo_surface_t</span></a> *
jpayne@68 189 cairo_ps_surface_create (<em class="parameter"><code>const <span class="type">char</span> *filename</code></em>,
jpayne@68 190 <em class="parameter"><code><span class="type">double</span> width_in_points</code></em>,
jpayne@68 191 <em class="parameter"><code><span class="type">double</span> height_in_points</code></em>);</pre>
jpayne@68 192 <p>Creates a PostScript surface of the specified size in points to be
jpayne@68 193 written to <em class="parameter"><code>filename</code></em>
jpayne@68 194 . See <a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-surface-create-for-stream" title="cairo_ps_surface_create_for_stream ()"><code class="function">cairo_ps_surface_create_for_stream()</code></a> for
jpayne@68 195 a more flexible mechanism for handling the PostScript output than
jpayne@68 196 simply writing it to a named file.</p>
jpayne@68 197 <p>Note that the size of individual pages of the PostScript output can
jpayne@68 198 vary. See <a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-surface-set-size" title="cairo_ps_surface_set_size ()"><code class="function">cairo_ps_surface_set_size()</code></a>.</p>
jpayne@68 199 <div class="refsect3">
jpayne@68 200 <a name="cairo-ps-surface-create.parameters"></a><h4>Parameters</h4>
jpayne@68 201 <div class="informaltable"><table class="informaltable" width="100%" border="0">
jpayne@68 202 <colgroup>
jpayne@68 203 <col width="150px" class="parameters_name">
jpayne@68 204 <col class="parameters_description">
jpayne@68 205 <col width="200px" class="parameters_annotations">
jpayne@68 206 </colgroup>
jpayne@68 207 <tbody>
jpayne@68 208 <tr>
jpayne@68 209 <td class="parameter_name"><p>filename</p></td>
jpayne@68 210 <td class="parameter_description"><p>a filename for the PS output (must be writable), <a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> may be
jpayne@68 211 used to specify no output. This will generate a PS surface that
jpayne@68 212 may be queried and used as a source, without generating a
jpayne@68 213 temporary file.</p></td>
jpayne@68 214 <td class="parameter_annotations"> </td>
jpayne@68 215 </tr>
jpayne@68 216 <tr>
jpayne@68 217 <td class="parameter_name"><p>width_in_points</p></td>
jpayne@68 218 <td class="parameter_description"><p>width of the surface, in points (1 point == 1/72.0 inch)</p></td>
jpayne@68 219 <td class="parameter_annotations"> </td>
jpayne@68 220 </tr>
jpayne@68 221 <tr>
jpayne@68 222 <td class="parameter_name"><p>height_in_points</p></td>
jpayne@68 223 <td class="parameter_description"><p>height of the surface, in points (1 point == 1/72.0 inch)</p></td>
jpayne@68 224 <td class="parameter_annotations"> </td>
jpayne@68 225 </tr>
jpayne@68 226 </tbody>
jpayne@68 227 </table></div>
jpayne@68 228 </div>
jpayne@68 229 <div class="refsect3">
jpayne@68 230 <a name="cairo-ps-surface-create.returns"></a><h4>Returns</h4>
jpayne@68 231 <p> a pointer to the newly created surface. The caller
jpayne@68 232 owns the surface and should call <a class="link" href="cairo-cairo-surface-t.html#cairo-surface-destroy" title="cairo_surface_destroy ()"><code class="function">cairo_surface_destroy()</code></a> when done
jpayne@68 233 with it.</p>
jpayne@68 234 <p>This function always returns a valid pointer, but it will return a
jpayne@68 235 pointer to a "nil" surface if an error such as out of memory
jpayne@68 236 occurs. You can use <a class="link" href="cairo-cairo-surface-t.html#cairo-surface-status" title="cairo_surface_status ()"><code class="function">cairo_surface_status()</code></a> to check for this.</p>
jpayne@68 237 </div>
jpayne@68 238 <p class="since">Since: 1.2</p>
jpayne@68 239 </div>
jpayne@68 240 <hr>
jpayne@68 241 <div class="refsect2">
jpayne@68 242 <a name="cairo-ps-surface-create-for-stream"></a><h3>cairo_ps_surface_create_for_stream ()</h3>
jpayne@68 243 <pre class="programlisting"><a class="link" href="cairo-cairo-surface-t.html#cairo-surface-t" title="cairo_surface_t"><span class="returnvalue">cairo_surface_t</span></a> *
jpayne@68 244 cairo_ps_surface_create_for_stream (<em class="parameter"><code><a class="link" href="cairo-PNG-Support.html#cairo-write-func-t" title="cairo_write_func_t ()"><span class="type">cairo_write_func_t</span></a> write_func</code></em>,
jpayne@68 245 <em class="parameter"><code><span class="type">void</span> *closure</code></em>,
jpayne@68 246 <em class="parameter"><code><span class="type">double</span> width_in_points</code></em>,
jpayne@68 247 <em class="parameter"><code><span class="type">double</span> height_in_points</code></em>);</pre>
jpayne@68 248 <p>Creates a PostScript surface of the specified size in points to be
jpayne@68 249 written incrementally to the stream represented by <em class="parameter"><code>write_func</code></em>
jpayne@68 250 and
jpayne@68 251 <em class="parameter"><code>closure</code></em>
jpayne@68 252 . See <a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-surface-create" title="cairo_ps_surface_create ()"><code class="function">cairo_ps_surface_create()</code></a> for a more convenient way
jpayne@68 253 to simply direct the PostScript output to a named file.</p>
jpayne@68 254 <p>Note that the size of individual pages of the PostScript
jpayne@68 255 output can vary. See <a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-surface-set-size" title="cairo_ps_surface_set_size ()"><code class="function">cairo_ps_surface_set_size()</code></a>.</p>
jpayne@68 256 <div class="refsect3">
jpayne@68 257 <a name="cairo-ps-surface-create-for-stream.parameters"></a><h4>Parameters</h4>
jpayne@68 258 <div class="informaltable"><table class="informaltable" width="100%" border="0">
jpayne@68 259 <colgroup>
jpayne@68 260 <col width="150px" class="parameters_name">
jpayne@68 261 <col class="parameters_description">
jpayne@68 262 <col width="200px" class="parameters_annotations">
jpayne@68 263 </colgroup>
jpayne@68 264 <tbody>
jpayne@68 265 <tr>
jpayne@68 266 <td class="parameter_name"><p>write_func</p></td>
jpayne@68 267 <td class="parameter_description"><p>a <a class="link" href="cairo-PNG-Support.html#cairo-write-func-t" title="cairo_write_func_t ()"><span class="type">cairo_write_func_t</span></a> to accept the output data, may be <a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>
jpayne@68 268 to indicate a no-op <em class="parameter"><code>write_func</code></em>
jpayne@68 269 . With a no-op <em class="parameter"><code>write_func</code></em>
jpayne@68 270 ,
jpayne@68 271 the surface may be queried or used as a source without
jpayne@68 272 generating any temporary files.</p></td>
jpayne@68 273 <td class="parameter_annotations"> </td>
jpayne@68 274 </tr>
jpayne@68 275 <tr>
jpayne@68 276 <td class="parameter_name"><p>closure</p></td>
jpayne@68 277 <td class="parameter_description"><p>the closure argument for <em class="parameter"><code>write_func</code></em>
jpayne@68 278 </p></td>
jpayne@68 279 <td class="parameter_annotations"> </td>
jpayne@68 280 </tr>
jpayne@68 281 <tr>
jpayne@68 282 <td class="parameter_name"><p>width_in_points</p></td>
jpayne@68 283 <td class="parameter_description"><p>width of the surface, in points (1 point == 1/72.0 inch)</p></td>
jpayne@68 284 <td class="parameter_annotations"> </td>
jpayne@68 285 </tr>
jpayne@68 286 <tr>
jpayne@68 287 <td class="parameter_name"><p>height_in_points</p></td>
jpayne@68 288 <td class="parameter_description"><p>height of the surface, in points (1 point == 1/72.0 inch)</p></td>
jpayne@68 289 <td class="parameter_annotations"> </td>
jpayne@68 290 </tr>
jpayne@68 291 </tbody>
jpayne@68 292 </table></div>
jpayne@68 293 </div>
jpayne@68 294 <div class="refsect3">
jpayne@68 295 <a name="cairo-ps-surface-create-for-stream.returns"></a><h4>Returns</h4>
jpayne@68 296 <p> a pointer to the newly created surface. The caller
jpayne@68 297 owns the surface and should call <a class="link" href="cairo-cairo-surface-t.html#cairo-surface-destroy" title="cairo_surface_destroy ()"><code class="function">cairo_surface_destroy()</code></a> when done
jpayne@68 298 with it.</p>
jpayne@68 299 <p>This function always returns a valid pointer, but it will return a
jpayne@68 300 pointer to a "nil" surface if an error such as out of memory
jpayne@68 301 occurs. You can use <a class="link" href="cairo-cairo-surface-t.html#cairo-surface-status" title="cairo_surface_status ()"><code class="function">cairo_surface_status()</code></a> to check for this.</p>
jpayne@68 302 </div>
jpayne@68 303 <p class="since">Since: 1.2</p>
jpayne@68 304 </div>
jpayne@68 305 <hr>
jpayne@68 306 <div class="refsect2">
jpayne@68 307 <a name="cairo-ps-surface-restrict-to-level"></a><h3>cairo_ps_surface_restrict_to_level ()</h3>
jpayne@68 308 <pre class="programlisting"><span class="returnvalue">void</span>
jpayne@68 309 cairo_ps_surface_restrict_to_level (<em class="parameter"><code><a class="link" href="cairo-cairo-surface-t.html#cairo-surface-t" title="cairo_surface_t"><span class="type">cairo_surface_t</span></a> *surface</code></em>,
jpayne@68 310 <em class="parameter"><code><a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-level-t" title="enum cairo_ps_level_t"><span class="type">cairo_ps_level_t</span></a> level</code></em>);</pre>
jpayne@68 311 <p>Restricts the generated PostSript file to <em class="parameter"><code>level</code></em>
jpayne@68 312 . See
jpayne@68 313 <a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-get-levels" title="cairo_ps_get_levels ()"><code class="function">cairo_ps_get_levels()</code></a> for a list of available level values that
jpayne@68 314 can be used here.</p>
jpayne@68 315 <p>This function should only be called before any drawing operations
jpayne@68 316 have been performed on the given surface. The simplest way to do
jpayne@68 317 this is to call this function immediately after creating the
jpayne@68 318 surface.</p>
jpayne@68 319 <div class="refsect3">
jpayne@68 320 <a name="cairo-ps-surface-restrict-to-level.parameters"></a><h4>Parameters</h4>
jpayne@68 321 <div class="informaltable"><table class="informaltable" width="100%" border="0">
jpayne@68 322 <colgroup>
jpayne@68 323 <col width="150px" class="parameters_name">
jpayne@68 324 <col class="parameters_description">
jpayne@68 325 <col width="200px" class="parameters_annotations">
jpayne@68 326 </colgroup>
jpayne@68 327 <tbody>
jpayne@68 328 <tr>
jpayne@68 329 <td class="parameter_name"><p>surface</p></td>
jpayne@68 330 <td class="parameter_description"><p>a PostScript <a class="link" href="cairo-cairo-surface-t.html#cairo-surface-t" title="cairo_surface_t"><span class="type">cairo_surface_t</span></a></p></td>
jpayne@68 331 <td class="parameter_annotations"> </td>
jpayne@68 332 </tr>
jpayne@68 333 <tr>
jpayne@68 334 <td class="parameter_name"><p>level</p></td>
jpayne@68 335 <td class="parameter_description"><p>PostScript level</p></td>
jpayne@68 336 <td class="parameter_annotations"> </td>
jpayne@68 337 </tr>
jpayne@68 338 </tbody>
jpayne@68 339 </table></div>
jpayne@68 340 </div>
jpayne@68 341 <p class="since">Since: 1.6</p>
jpayne@68 342 </div>
jpayne@68 343 <hr>
jpayne@68 344 <div class="refsect2">
jpayne@68 345 <a name="cairo-ps-get-levels"></a><h3>cairo_ps_get_levels ()</h3>
jpayne@68 346 <pre class="programlisting"><span class="returnvalue">void</span>
jpayne@68 347 cairo_ps_get_levels (<em class="parameter"><code><a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-level-t" title="enum cairo_ps_level_t"><span class="type">cairo_ps_level_t</span></a> const **levels</code></em>,
jpayne@68 348 <em class="parameter"><code><span class="type">int</span> *num_levels</code></em>);</pre>
jpayne@68 349 <p>Used to retrieve the list of supported levels. See
jpayne@68 350 <a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-surface-restrict-to-level" title="cairo_ps_surface_restrict_to_level ()"><code class="function">cairo_ps_surface_restrict_to_level()</code></a>.</p>
jpayne@68 351 <div class="refsect3">
jpayne@68 352 <a name="cairo-ps-get-levels.parameters"></a><h4>Parameters</h4>
jpayne@68 353 <div class="informaltable"><table class="informaltable" width="100%" border="0">
jpayne@68 354 <colgroup>
jpayne@68 355 <col width="150px" class="parameters_name">
jpayne@68 356 <col class="parameters_description">
jpayne@68 357 <col width="200px" class="parameters_annotations">
jpayne@68 358 </colgroup>
jpayne@68 359 <tbody>
jpayne@68 360 <tr>
jpayne@68 361 <td class="parameter_name"><p>levels</p></td>
jpayne@68 362 <td class="parameter_description"><p>supported level list</p></td>
jpayne@68 363 <td class="parameter_annotations"> </td>
jpayne@68 364 </tr>
jpayne@68 365 <tr>
jpayne@68 366 <td class="parameter_name"><p>num_levels</p></td>
jpayne@68 367 <td class="parameter_description"><p>list length</p></td>
jpayne@68 368 <td class="parameter_annotations"> </td>
jpayne@68 369 </tr>
jpayne@68 370 </tbody>
jpayne@68 371 </table></div>
jpayne@68 372 </div>
jpayne@68 373 <p class="since">Since: 1.6</p>
jpayne@68 374 </div>
jpayne@68 375 <hr>
jpayne@68 376 <div class="refsect2">
jpayne@68 377 <a name="cairo-ps-level-to-string"></a><h3>cairo_ps_level_to_string ()</h3>
jpayne@68 378 <pre class="programlisting">const <span class="returnvalue">char</span> *
jpayne@68 379 cairo_ps_level_to_string (<em class="parameter"><code><a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-level-t" title="enum cairo_ps_level_t"><span class="type">cairo_ps_level_t</span></a> level</code></em>);</pre>
jpayne@68 380 <p>Get the string representation of the given <em class="parameter"><code>level</code></em>
jpayne@68 381 id. This function
jpayne@68 382 will return <a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if <em class="parameter"><code>level</code></em>
jpayne@68 383 id isn't valid. See <a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-get-levels" title="cairo_ps_get_levels ()"><code class="function">cairo_ps_get_levels()</code></a>
jpayne@68 384 for a way to get the list of valid level ids.</p>
jpayne@68 385 <div class="refsect3">
jpayne@68 386 <a name="cairo-ps-level-to-string.parameters"></a><h4>Parameters</h4>
jpayne@68 387 <div class="informaltable"><table class="informaltable" width="100%" border="0">
jpayne@68 388 <colgroup>
jpayne@68 389 <col width="150px" class="parameters_name">
jpayne@68 390 <col class="parameters_description">
jpayne@68 391 <col width="200px" class="parameters_annotations">
jpayne@68 392 </colgroup>
jpayne@68 393 <tbody><tr>
jpayne@68 394 <td class="parameter_name"><p>level</p></td>
jpayne@68 395 <td class="parameter_description"><p>a level id</p></td>
jpayne@68 396 <td class="parameter_annotations"> </td>
jpayne@68 397 </tr></tbody>
jpayne@68 398 </table></div>
jpayne@68 399 </div>
jpayne@68 400 <div class="refsect3">
jpayne@68 401 <a name="cairo-ps-level-to-string.returns"></a><h4>Returns</h4>
jpayne@68 402 <p> the string associated to given level.</p>
jpayne@68 403 </div>
jpayne@68 404 <p class="since">Since: 1.6</p>
jpayne@68 405 </div>
jpayne@68 406 <hr>
jpayne@68 407 <div class="refsect2">
jpayne@68 408 <a name="cairo-ps-surface-set-eps"></a><h3>cairo_ps_surface_set_eps ()</h3>
jpayne@68 409 <pre class="programlisting"><span class="returnvalue">void</span>
jpayne@68 410 cairo_ps_surface_set_eps (<em class="parameter"><code><a class="link" href="cairo-cairo-surface-t.html#cairo-surface-t" title="cairo_surface_t"><span class="type">cairo_surface_t</span></a> *surface</code></em>,
jpayne@68 411 <em class="parameter"><code><a class="link" href="cairo-Types.html#cairo-bool-t" title="cairo_bool_t"><span class="type">cairo_bool_t</span></a> eps</code></em>);</pre>
jpayne@68 412 <p>If <em class="parameter"><code>eps</code></em>
jpayne@68 413 is <a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a>, the PostScript surface will output Encapsulated
jpayne@68 414 PostScript.</p>
jpayne@68 415 <p>This function should only be called before any drawing operations
jpayne@68 416 have been performed on the current page. The simplest way to do
jpayne@68 417 this is to call this function immediately after creating the
jpayne@68 418 surface. An Encapsulated PostScript file should never contain more
jpayne@68 419 than one page.</p>
jpayne@68 420 <div class="refsect3">
jpayne@68 421 <a name="cairo-ps-surface-set-eps.parameters"></a><h4>Parameters</h4>
jpayne@68 422 <div class="informaltable"><table class="informaltable" width="100%" border="0">
jpayne@68 423 <colgroup>
jpayne@68 424 <col width="150px" class="parameters_name">
jpayne@68 425 <col class="parameters_description">
jpayne@68 426 <col width="200px" class="parameters_annotations">
jpayne@68 427 </colgroup>
jpayne@68 428 <tbody>
jpayne@68 429 <tr>
jpayne@68 430 <td class="parameter_name"><p>surface</p></td>
jpayne@68 431 <td class="parameter_description"><p>a PostScript <a class="link" href="cairo-cairo-surface-t.html#cairo-surface-t" title="cairo_surface_t"><span class="type">cairo_surface_t</span></a></p></td>
jpayne@68 432 <td class="parameter_annotations"> </td>
jpayne@68 433 </tr>
jpayne@68 434 <tr>
jpayne@68 435 <td class="parameter_name"><p>eps</p></td>
jpayne@68 436 <td class="parameter_description"><p><a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> to output EPS format PostScript</p></td>
jpayne@68 437 <td class="parameter_annotations"> </td>
jpayne@68 438 </tr>
jpayne@68 439 </tbody>
jpayne@68 440 </table></div>
jpayne@68 441 </div>
jpayne@68 442 <p class="since">Since: 1.6</p>
jpayne@68 443 </div>
jpayne@68 444 <hr>
jpayne@68 445 <div class="refsect2">
jpayne@68 446 <a name="cairo-ps-surface-get-eps"></a><h3>cairo_ps_surface_get_eps ()</h3>
jpayne@68 447 <pre class="programlisting"><a class="link" href="cairo-Types.html#cairo-bool-t" title="cairo_bool_t"><span class="returnvalue">cairo_bool_t</span></a>
jpayne@68 448 cairo_ps_surface_get_eps (<em class="parameter"><code><a class="link" href="cairo-cairo-surface-t.html#cairo-surface-t" title="cairo_surface_t"><span class="type">cairo_surface_t</span></a> *surface</code></em>);</pre>
jpayne@68 449 <p>Check whether the PostScript surface will output Encapsulated PostScript.</p>
jpayne@68 450 <div class="refsect3">
jpayne@68 451 <a name="cairo-ps-surface-get-eps.parameters"></a><h4>Parameters</h4>
jpayne@68 452 <div class="informaltable"><table class="informaltable" width="100%" border="0">
jpayne@68 453 <colgroup>
jpayne@68 454 <col width="150px" class="parameters_name">
jpayne@68 455 <col class="parameters_description">
jpayne@68 456 <col width="200px" class="parameters_annotations">
jpayne@68 457 </colgroup>
jpayne@68 458 <tbody><tr>
jpayne@68 459 <td class="parameter_name"><p>surface</p></td>
jpayne@68 460 <td class="parameter_description"><p>a PostScript <a class="link" href="cairo-cairo-surface-t.html#cairo-surface-t" title="cairo_surface_t"><span class="type">cairo_surface_t</span></a></p></td>
jpayne@68 461 <td class="parameter_annotations"> </td>
jpayne@68 462 </tr></tbody>
jpayne@68 463 </table></div>
jpayne@68 464 </div>
jpayne@68 465 <div class="refsect3">
jpayne@68 466 <a name="cairo-ps-surface-get-eps.returns"></a><h4>Returns</h4>
jpayne@68 467 <p> <a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if the surface will output Encapsulated PostScript.</p>
jpayne@68 468 </div>
jpayne@68 469 <p class="since">Since: 1.6</p>
jpayne@68 470 </div>
jpayne@68 471 <hr>
jpayne@68 472 <div class="refsect2">
jpayne@68 473 <a name="cairo-ps-surface-set-size"></a><h3>cairo_ps_surface_set_size ()</h3>
jpayne@68 474 <pre class="programlisting"><span class="returnvalue">void</span>
jpayne@68 475 cairo_ps_surface_set_size (<em class="parameter"><code><a class="link" href="cairo-cairo-surface-t.html#cairo-surface-t" title="cairo_surface_t"><span class="type">cairo_surface_t</span></a> *surface</code></em>,
jpayne@68 476 <em class="parameter"><code><span class="type">double</span> width_in_points</code></em>,
jpayne@68 477 <em class="parameter"><code><span class="type">double</span> height_in_points</code></em>);</pre>
jpayne@68 478 <p>Changes the size of a PostScript surface for the current (and
jpayne@68 479 subsequent) pages.</p>
jpayne@68 480 <p>This function should only be called before any drawing operations
jpayne@68 481 have been performed on the current page. The simplest way to do
jpayne@68 482 this is to call this function immediately after creating the
jpayne@68 483 surface or immediately after completing a page with either
jpayne@68 484 <a class="link" href="cairo-cairo-t.html#cairo-show-page" title="cairo_show_page ()"><code class="function">cairo_show_page()</code></a> or <a class="link" href="cairo-cairo-t.html#cairo-copy-page" title="cairo_copy_page ()"><code class="function">cairo_copy_page()</code></a>.</p>
jpayne@68 485 <div class="refsect3">
jpayne@68 486 <a name="cairo-ps-surface-set-size.parameters"></a><h4>Parameters</h4>
jpayne@68 487 <div class="informaltable"><table class="informaltable" width="100%" border="0">
jpayne@68 488 <colgroup>
jpayne@68 489 <col width="150px" class="parameters_name">
jpayne@68 490 <col class="parameters_description">
jpayne@68 491 <col width="200px" class="parameters_annotations">
jpayne@68 492 </colgroup>
jpayne@68 493 <tbody>
jpayne@68 494 <tr>
jpayne@68 495 <td class="parameter_name"><p>surface</p></td>
jpayne@68 496 <td class="parameter_description"><p>a PostScript <a class="link" href="cairo-cairo-surface-t.html#cairo-surface-t" title="cairo_surface_t"><span class="type">cairo_surface_t</span></a></p></td>
jpayne@68 497 <td class="parameter_annotations"> </td>
jpayne@68 498 </tr>
jpayne@68 499 <tr>
jpayne@68 500 <td class="parameter_name"><p>width_in_points</p></td>
jpayne@68 501 <td class="parameter_description"><p>new surface width, in points (1 point == 1/72.0 inch)</p></td>
jpayne@68 502 <td class="parameter_annotations"> </td>
jpayne@68 503 </tr>
jpayne@68 504 <tr>
jpayne@68 505 <td class="parameter_name"><p>height_in_points</p></td>
jpayne@68 506 <td class="parameter_description"><p>new surface height, in points (1 point == 1/72.0 inch)</p></td>
jpayne@68 507 <td class="parameter_annotations"> </td>
jpayne@68 508 </tr>
jpayne@68 509 </tbody>
jpayne@68 510 </table></div>
jpayne@68 511 </div>
jpayne@68 512 <p class="since">Since: 1.2</p>
jpayne@68 513 </div>
jpayne@68 514 <hr>
jpayne@68 515 <div class="refsect2">
jpayne@68 516 <a name="cairo-ps-surface-dsc-begin-setup"></a><h3>cairo_ps_surface_dsc_begin_setup ()</h3>
jpayne@68 517 <pre class="programlisting"><span class="returnvalue">void</span>
jpayne@68 518 cairo_ps_surface_dsc_begin_setup (<em class="parameter"><code><a class="link" href="cairo-cairo-surface-t.html#cairo-surface-t" title="cairo_surface_t"><span class="type">cairo_surface_t</span></a> *surface</code></em>);</pre>
jpayne@68 519 <p>This function indicates that subsequent calls to
jpayne@68 520 <a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-surface-dsc-comment" title="cairo_ps_surface_dsc_comment ()"><code class="function">cairo_ps_surface_dsc_comment()</code></a> should direct comments to the Setup
jpayne@68 521 section of the PostScript output.</p>
jpayne@68 522 <p>This function should be called at most once per surface, and must
jpayne@68 523 be called before any call to <a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-surface-dsc-begin-page-setup" title="cairo_ps_surface_dsc_begin_page_setup ()"><code class="function">cairo_ps_surface_dsc_begin_page_setup()</code></a>
jpayne@68 524 and before any drawing is performed to the surface.</p>
jpayne@68 525 <p>See <a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-surface-dsc-comment" title="cairo_ps_surface_dsc_comment ()"><code class="function">cairo_ps_surface_dsc_comment()</code></a> for more details.</p>
jpayne@68 526 <div class="refsect3">
jpayne@68 527 <a name="cairo-ps-surface-dsc-begin-setup.parameters"></a><h4>Parameters</h4>
jpayne@68 528 <div class="informaltable"><table class="informaltable" width="100%" border="0">
jpayne@68 529 <colgroup>
jpayne@68 530 <col width="150px" class="parameters_name">
jpayne@68 531 <col class="parameters_description">
jpayne@68 532 <col width="200px" class="parameters_annotations">
jpayne@68 533 </colgroup>
jpayne@68 534 <tbody><tr>
jpayne@68 535 <td class="parameter_name"><p>surface</p></td>
jpayne@68 536 <td class="parameter_description"><p>a PostScript <a class="link" href="cairo-cairo-surface-t.html#cairo-surface-t" title="cairo_surface_t"><span class="type">cairo_surface_t</span></a></p></td>
jpayne@68 537 <td class="parameter_annotations"> </td>
jpayne@68 538 </tr></tbody>
jpayne@68 539 </table></div>
jpayne@68 540 </div>
jpayne@68 541 <p class="since">Since: 1.2</p>
jpayne@68 542 </div>
jpayne@68 543 <hr>
jpayne@68 544 <div class="refsect2">
jpayne@68 545 <a name="cairo-ps-surface-dsc-begin-page-setup"></a><h3>cairo_ps_surface_dsc_begin_page_setup ()</h3>
jpayne@68 546 <pre class="programlisting"><span class="returnvalue">void</span>
jpayne@68 547 cairo_ps_surface_dsc_begin_page_setup (<em class="parameter"><code><a class="link" href="cairo-cairo-surface-t.html#cairo-surface-t" title="cairo_surface_t"><span class="type">cairo_surface_t</span></a> *surface</code></em>);</pre>
jpayne@68 548 <p>This function indicates that subsequent calls to
jpayne@68 549 <a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-surface-dsc-comment" title="cairo_ps_surface_dsc_comment ()"><code class="function">cairo_ps_surface_dsc_comment()</code></a> should direct comments to the
jpayne@68 550 PageSetup section of the PostScript output.</p>
jpayne@68 551 <p>This function call is only needed for the first page of a
jpayne@68 552 surface. It should be called after any call to
jpayne@68 553 <a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-surface-dsc-begin-setup" title="cairo_ps_surface_dsc_begin_setup ()"><code class="function">cairo_ps_surface_dsc_begin_setup()</code></a> and before any drawing is
jpayne@68 554 performed to the surface.</p>
jpayne@68 555 <p>See <a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-surface-dsc-comment" title="cairo_ps_surface_dsc_comment ()"><code class="function">cairo_ps_surface_dsc_comment()</code></a> for more details.</p>
jpayne@68 556 <div class="refsect3">
jpayne@68 557 <a name="cairo-ps-surface-dsc-begin-page-setup.parameters"></a><h4>Parameters</h4>
jpayne@68 558 <div class="informaltable"><table class="informaltable" width="100%" border="0">
jpayne@68 559 <colgroup>
jpayne@68 560 <col width="150px" class="parameters_name">
jpayne@68 561 <col class="parameters_description">
jpayne@68 562 <col width="200px" class="parameters_annotations">
jpayne@68 563 </colgroup>
jpayne@68 564 <tbody><tr>
jpayne@68 565 <td class="parameter_name"><p>surface</p></td>
jpayne@68 566 <td class="parameter_description"><p>a PostScript <a class="link" href="cairo-cairo-surface-t.html#cairo-surface-t" title="cairo_surface_t"><span class="type">cairo_surface_t</span></a></p></td>
jpayne@68 567 <td class="parameter_annotations"> </td>
jpayne@68 568 </tr></tbody>
jpayne@68 569 </table></div>
jpayne@68 570 </div>
jpayne@68 571 <p class="since">Since: 1.2</p>
jpayne@68 572 </div>
jpayne@68 573 <hr>
jpayne@68 574 <div class="refsect2">
jpayne@68 575 <a name="cairo-ps-surface-dsc-comment"></a><h3>cairo_ps_surface_dsc_comment ()</h3>
jpayne@68 576 <pre class="programlisting"><span class="returnvalue">void</span>
jpayne@68 577 cairo_ps_surface_dsc_comment (<em class="parameter"><code><a class="link" href="cairo-cairo-surface-t.html#cairo-surface-t" title="cairo_surface_t"><span class="type">cairo_surface_t</span></a> *surface</code></em>,
jpayne@68 578 <em class="parameter"><code>const <span class="type">char</span> *comment</code></em>);</pre>
jpayne@68 579 <p>Emit a comment into the PostScript output for the given surface.</p>
jpayne@68 580 <p>The comment is expected to conform to the PostScript Language
jpayne@68 581 Document Structuring Conventions (DSC). Please see that manual for
jpayne@68 582 details on the available comments and their meanings. In
jpayne@68 583 particular, the %%IncludeFeature comment allows a
jpayne@68 584 device-independent means of controlling printer device features. So
jpayne@68 585 the PostScript Printer Description Files Specification will also be
jpayne@68 586 a useful reference.</p>
jpayne@68 587 <p>The comment string must begin with a percent character (%) and the
jpayne@68 588 total length of the string (including any initial percent
jpayne@68 589 characters) must not exceed 255 characters. Violating either of
jpayne@68 590 these conditions will place <em class="parameter"><code>surface</code></em>
jpayne@68 591 into an error state. But
jpayne@68 592 beyond these two conditions, this function will not enforce
jpayne@68 593 conformance of the comment with any particular specification.</p>
jpayne@68 594 <p>The comment string should not have a trailing newline.</p>
jpayne@68 595 <p>The DSC specifies different sections in which particular comments
jpayne@68 596 can appear. This function provides for comments to be emitted
jpayne@68 597 within three sections: the header, the Setup section, and the
jpayne@68 598 PageSetup section. Comments appearing in the first two sections
jpayne@68 599 apply to the entire document while comments in the BeginPageSetup
jpayne@68 600 section apply only to a single page.</p>
jpayne@68 601 <p>For comments to appear in the header section, this function should
jpayne@68 602 be called after the surface is created, but before a call to
jpayne@68 603 <a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-surface-dsc-begin-setup" title="cairo_ps_surface_dsc_begin_setup ()"><code class="function">cairo_ps_surface_dsc_begin_setup()</code></a>.</p>
jpayne@68 604 <p>For comments to appear in the Setup section, this function should
jpayne@68 605 be called after a call to <a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-surface-dsc-begin-setup" title="cairo_ps_surface_dsc_begin_setup ()"><code class="function">cairo_ps_surface_dsc_begin_setup()</code></a> but
jpayne@68 606 before a call to <a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-surface-dsc-begin-page-setup" title="cairo_ps_surface_dsc_begin_page_setup ()"><code class="function">cairo_ps_surface_dsc_begin_page_setup()</code></a>.</p>
jpayne@68 607 <p>For comments to appear in the PageSetup section, this function
jpayne@68 608 should be called after a call to
jpayne@68 609 <a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-surface-dsc-begin-page-setup" title="cairo_ps_surface_dsc_begin_page_setup ()"><code class="function">cairo_ps_surface_dsc_begin_page_setup()</code></a>.</p>
jpayne@68 610 <p>Note that it is only necessary to call
jpayne@68 611 <a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-surface-dsc-begin-page-setup" title="cairo_ps_surface_dsc_begin_page_setup ()"><code class="function">cairo_ps_surface_dsc_begin_page_setup()</code></a> for the first page of any
jpayne@68 612 surface. After a call to <a class="link" href="cairo-cairo-t.html#cairo-show-page" title="cairo_show_page ()"><code class="function">cairo_show_page()</code></a> or <a class="link" href="cairo-cairo-t.html#cairo-copy-page" title="cairo_copy_page ()"><code class="function">cairo_copy_page()</code></a>
jpayne@68 613 comments are unambiguously directed to the PageSetup section of the
jpayne@68 614 current page. But it doesn't hurt to call this function at the
jpayne@68 615 beginning of every page as that consistency may make the calling
jpayne@68 616 code simpler.</p>
jpayne@68 617 <p>As a final note, cairo automatically generates several comments on
jpayne@68 618 its own. As such, applications must not manually generate any of
jpayne@68 619 the following comments:</p>
jpayne@68 620 <p>Header section: %!PS-Adobe-3.0, %%Creator, %%CreationDate, %%Pages,
jpayne@68 621 %%BoundingBox, %%DocumentData, %%LanguageLevel, %%EndComments.</p>
jpayne@68 622 <p>Setup section: %%BeginSetup, %%EndSetup</p>
jpayne@68 623 <p>PageSetup section: %%BeginPageSetup, %%PageBoundingBox, %%EndPageSetup.</p>
jpayne@68 624 <p>Other sections: %%BeginProlog, %%EndProlog, %%Page, %%Trailer, %%EOF</p>
jpayne@68 625 <p>Here is an example sequence showing how this function might be used:</p>
jpayne@68 626 <div class="informalexample">
jpayne@68 627 <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
jpayne@68 628 <tbody>
jpayne@68 629 <tr>
jpayne@68 630 <td class="listing_lines" align="right"><pre>1
jpayne@68 631 2
jpayne@68 632 3
jpayne@68 633 4
jpayne@68 634 5
jpayne@68 635 6
jpayne@68 636 7
jpayne@68 637 8
jpayne@68 638 9
jpayne@68 639 10
jpayne@68 640 11
jpayne@68 641 12
jpayne@68 642 13
jpayne@68 643 14
jpayne@68 644 15
jpayne@68 645 16
jpayne@68 646 17
jpayne@68 647 18</pre></td>
jpayne@68 648 <td class="listing_code"><pre class="programlisting">cairo_surface_t <span class="gtkdoc opt">*</span>surface <span class="gtkdoc opt">=</span> <span class="function"><a href="cairo-PostScript-Surfaces.html#cairo-ps-surface-create">cairo_ps_surface_create</a></span> <span class="gtkdoc opt">(</span>filename<span class="gtkdoc opt">,</span> width<span class="gtkdoc opt">,</span> height<span class="gtkdoc opt">);</span>
jpayne@68 649 <span class="gtkdoc opt">...</span>
jpayne@68 650 <span class="function"><a href="cairo-PostScript-Surfaces.html#cairo-ps-surface-dsc-comment">cairo_ps_surface_dsc_comment</a></span> <span class="gtkdoc opt">(</span>surface<span class="gtkdoc opt">,</span> <span class="string">&quot;%%Title: My excellent document&quot;</span><span class="gtkdoc opt">);</span>
jpayne@68 651 <span class="function"><a href="cairo-PostScript-Surfaces.html#cairo-ps-surface-dsc-comment">cairo_ps_surface_dsc_comment</a></span> <span class="gtkdoc opt">(</span>surface<span class="gtkdoc opt">,</span> <span class="string">&quot;%%Copyright: Copyright (C) 2006 Cairo Lover&quot;</span><span class="gtkdoc opt">)</span>
jpayne@68 652 <span class="gtkdoc opt">...</span>
jpayne@68 653 <span class="function"><a href="cairo-PostScript-Surfaces.html#cairo-ps-surface-dsc-begin-setup">cairo_ps_surface_dsc_begin_setup</a></span> <span class="gtkdoc opt">(</span>surface<span class="gtkdoc opt">);</span>
jpayne@68 654 <span class="function"><a href="cairo-PostScript-Surfaces.html#cairo-ps-surface-dsc-comment">cairo_ps_surface_dsc_comment</a></span> <span class="gtkdoc opt">(</span>surface<span class="gtkdoc opt">,</span> <span class="string">&quot;%%IncludeFeature: *MediaColor White&quot;</span><span class="gtkdoc opt">);</span>
jpayne@68 655 <span class="gtkdoc opt">...</span>
jpayne@68 656 <span class="function"><a href="cairo-PostScript-Surfaces.html#cairo-ps-surface-dsc-begin-page-setup">cairo_ps_surface_dsc_begin_page_setup</a></span> <span class="gtkdoc opt">(</span>surface<span class="gtkdoc opt">);</span>
jpayne@68 657 <span class="function"><a href="cairo-PostScript-Surfaces.html#cairo-ps-surface-dsc-comment">cairo_ps_surface_dsc_comment</a></span> <span class="gtkdoc opt">(</span>surface<span class="gtkdoc opt">,</span> <span class="string">&quot;%%IncludeFeature: *PageSize A3&quot;</span><span class="gtkdoc opt">);</span>
jpayne@68 658 <span class="function"><a href="cairo-PostScript-Surfaces.html#cairo-ps-surface-dsc-comment">cairo_ps_surface_dsc_comment</a></span> <span class="gtkdoc opt">(</span>surface<span class="gtkdoc opt">,</span> <span class="string">&quot;%%IncludeFeature: *InputSlot LargeCapacity&quot;</span><span class="gtkdoc opt">);</span>
jpayne@68 659 <span class="function"><a href="cairo-PostScript-Surfaces.html#cairo-ps-surface-dsc-comment">cairo_ps_surface_dsc_comment</a></span> <span class="gtkdoc opt">(</span>surface<span class="gtkdoc opt">,</span> <span class="string">&quot;%%IncludeFeature: *MediaType Glossy&quot;</span><span class="gtkdoc opt">);</span>
jpayne@68 660 <span class="function"><a href="cairo-PostScript-Surfaces.html#cairo-ps-surface-dsc-comment">cairo_ps_surface_dsc_comment</a></span> <span class="gtkdoc opt">(</span>surface<span class="gtkdoc opt">,</span> <span class="string">&quot;%%IncludeFeature: *MediaColor Blue&quot;</span><span class="gtkdoc opt">);</span>
jpayne@68 661 <span class="gtkdoc opt">...</span> draw to first page here <span class="gtkdoc opt">..</span>
jpayne@68 662 <span class="function"><a href="cairo-cairo-t.html#cairo-show-page">cairo_show_page</a></span> <span class="gtkdoc opt">(</span>cr<span class="gtkdoc opt">);</span>
jpayne@68 663 <span class="gtkdoc opt">...</span>
jpayne@68 664 <span class="function"><a href="cairo-PostScript-Surfaces.html#cairo-ps-surface-dsc-comment">cairo_ps_surface_dsc_comment</a></span> <span class="gtkdoc opt">(</span>surface<span class="gtkdoc opt">,</span> <span class="string">&quot;%%IncludeFeature: *PageSize A5&quot;</span><span class="gtkdoc opt">);</span>
jpayne@68 665 <span class="gtkdoc opt">...</span></pre></td>
jpayne@68 666 </tr>
jpayne@68 667 </tbody>
jpayne@68 668 </table>
jpayne@68 669 </div>
jpayne@68 670
jpayne@68 671 <div class="refsect3">
jpayne@68 672 <a name="cairo-ps-surface-dsc-comment.parameters"></a><h4>Parameters</h4>
jpayne@68 673 <div class="informaltable"><table class="informaltable" width="100%" border="0">
jpayne@68 674 <colgroup>
jpayne@68 675 <col width="150px" class="parameters_name">
jpayne@68 676 <col class="parameters_description">
jpayne@68 677 <col width="200px" class="parameters_annotations">
jpayne@68 678 </colgroup>
jpayne@68 679 <tbody>
jpayne@68 680 <tr>
jpayne@68 681 <td class="parameter_name"><p>surface</p></td>
jpayne@68 682 <td class="parameter_description"><p>a PostScript <a class="link" href="cairo-cairo-surface-t.html#cairo-surface-t" title="cairo_surface_t"><span class="type">cairo_surface_t</span></a></p></td>
jpayne@68 683 <td class="parameter_annotations"> </td>
jpayne@68 684 </tr>
jpayne@68 685 <tr>
jpayne@68 686 <td class="parameter_name"><p>comment</p></td>
jpayne@68 687 <td class="parameter_description"><p>a comment string to be emitted into the PostScript output</p></td>
jpayne@68 688 <td class="parameter_annotations"> </td>
jpayne@68 689 </tr>
jpayne@68 690 </tbody>
jpayne@68 691 </table></div>
jpayne@68 692 </div>
jpayne@68 693 <p class="since">Since: 1.2</p>
jpayne@68 694 </div>
jpayne@68 695 </div>
jpayne@68 696 <div class="refsect1">
jpayne@68 697 <a name="cairo-PostScript-Surfaces.other_details"></a><h2>Types and Values</h2>
jpayne@68 698 <div class="refsect2">
jpayne@68 699 <a name="CAIRO-HAS-PS-SURFACE:CAPS"></a><h3>CAIRO_HAS_PS_SURFACE</h3>
jpayne@68 700 <pre class="programlisting">#define CAIRO_HAS_PS_SURFACE 1
jpayne@68 701 </pre>
jpayne@68 702 <p>Defined if the PostScript surface backend is available.
jpayne@68 703 This macro can be used to conditionally compile backend-specific code.</p>
jpayne@68 704 <p class="since">Since: 1.2</p>
jpayne@68 705 </div>
jpayne@68 706 <hr>
jpayne@68 707 <div class="refsect2">
jpayne@68 708 <a name="cairo-ps-level-t"></a><h3>enum cairo_ps_level_t</h3>
jpayne@68 709 <p><a class="link" href="cairo-PostScript-Surfaces.html#cairo-ps-level-t" title="enum cairo_ps_level_t"><span class="type">cairo_ps_level_t</span></a> is used to describe the language level of the
jpayne@68 710 PostScript Language Reference that a generated PostScript file will
jpayne@68 711 conform to.</p>
jpayne@68 712 <div class="refsect3">
jpayne@68 713 <a name="cairo-ps-level-t.members"></a><h4>Members</h4>
jpayne@68 714 <div class="informaltable"><table class="informaltable" width="100%" border="0">
jpayne@68 715 <colgroup>
jpayne@68 716 <col width="300px" class="enum_members_name">
jpayne@68 717 <col class="enum_members_description">
jpayne@68 718 <col width="200px" class="enum_members_annotations">
jpayne@68 719 </colgroup>
jpayne@68 720 <tbody>
jpayne@68 721 <tr>
jpayne@68 722 <td class="enum_member_name"><p><a name="CAIRO-PS-LEVEL-2:CAPS"></a>CAIRO_PS_LEVEL_2</p></td>
jpayne@68 723 <td class="enum_member_description">
jpayne@68 724 <p>The language level 2 of the PostScript specification. (Since 1.6)</p>
jpayne@68 725 </td>
jpayne@68 726 <td class="enum_member_annotations"> </td>
jpayne@68 727 </tr>
jpayne@68 728 <tr>
jpayne@68 729 <td class="enum_member_name"><p><a name="CAIRO-PS-LEVEL-3:CAPS"></a>CAIRO_PS_LEVEL_3</p></td>
jpayne@68 730 <td class="enum_member_description">
jpayne@68 731 <p>The language level 3 of the PostScript specification. (Since 1.6)</p>
jpayne@68 732 </td>
jpayne@68 733 <td class="enum_member_annotations"> </td>
jpayne@68 734 </tr>
jpayne@68 735 </tbody>
jpayne@68 736 </table></div>
jpayne@68 737 </div>
jpayne@68 738 <p class="since">Since: 1.6</p>
jpayne@68 739 </div>
jpayne@68 740 </div>
jpayne@68 741 <div class="refsect1">
jpayne@68 742 <a name="cairo-PostScript-Surfaces.see-also"></a><h2>See Also</h2>
jpayne@68 743 <p><a class="link" href="cairo-cairo-surface-t.html#cairo-surface-t" title="cairo_surface_t"><span class="type">cairo_surface_t</span></a></p>
jpayne@68 744 </div>
jpayne@68 745 </div>
jpayne@68 746 <div class="footer">
jpayne@68 747 <hr>Generated by GTK-Doc V1.27</div>
jpayne@68 748 </body>
jpayne@68 749 </html>