1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<head> 4<title>The Ghostscript library</title> 5<!-- $Id: Lib.htm,v 1.43 2005/10/20 19:46:23 ray Exp $ --> 6<!-- Originally: lib.txt --> 7<link rel="stylesheet" type="text/css" href="gs.css" title="Ghostscript Style"> 8</head> 9 10<body> 11<!-- [1.0 begin visible header] ============================================ --> 12 13<!-- [1.1 begin headline] ================================================== --> 14 15<h1>The Ghostscript Library</h1> 16 17<!-- [1.1 end headline] ==================================================== --> 18 19<!-- [1.2 begin table of contents] ========================================= --> 20 21<h2>Table of contents</h2> 22 23<blockquote><ul> 24<li><a href="#GS_library">The Ghostscript library</a> 25<li><a href="#PS_operator_API">PostScript operator API</a> 26<ul> 27<li><a href="#Patterns">Patterns</a> 28<li><a href="#Lower_level_API">Lower-level API</a> 29</ul> 30<li><a href="#Visual_trace">Visual Trace instructions</a> 31<li><a href="#Full_example">A full example</a> 32</ul></blockquote> 33 34<!-- [1.2 end table of contents] =========================================== --> 35 36<!-- [1.3 begin hint] ====================================================== --> 37 38<p>For other information, see the <a href="Readme.htm">Ghostscript 39overview</a>. 40 41<!-- [1.3 end hint] ======================================================== --> 42 43<hr> 44 45<!-- [1.0 end visible header] ============================================== --> 46 47<!-- [2.0 begin contents] ================================================== --> 48 49<h2><a name="GS_library"></a>The Ghostscript library</h2> 50 51<p> 52This document describes the Ghostscript library, a set of procedures 53to implement the graphics and filtering capabilities that are primitive 54operations in the PostScript language and in Adobe Portable Document Format 55(PDF). 56 57<p> 58Ghostscript is actually two programs: a language interpreter, and a 59graphics library. The library provides, in the form of C procedures, all 60the graphics functions of the language, that is, approximately those 61facilities listed in section 8.1 of the <cite>PostScript 62Language Reference Manual</cite>, starting with the 63graphics state operators. In addition, the library provides some 64lower-level graphics facilities that offer higher performance in exchange 65for less generality. 66 67<hr> 68 69<h2><a name="PS_operator_API"></a>PostScript operator API</h2> 70 71<p> 72The highest level of the library, which is the one that most clients will 73use, directly implements the PostScript graphics operators with procedures 74named <b><tt>gs_XXX</tt></b>, for instance <b><tt>gs_moveto</tt></b> and 75<b><tt>gs_fill</tt></b>. Nearly all of these procedures take graphics 76state objects as their first arguments, such as 77 78<blockquote><b><tt> 79int gs_moveto(gs_state *, double, double); 80</tt></b></blockquote> 81 82<p> 83Nearly every procedure returns an integer code which is >= 0 for a 84successful return or <0 for a failure. The failure codes correspond 85directly to PostScript errors, and are defined in 86<b><tt>gserrors.h</tt></b>. 87 88<p> 89The library implements all the operators in the following sections of the 90<cite>PostScript Language Reference Manual</cite>, with the indicated 91omissions and with the APIs defined in the indicated <b><tt>.h</tt></b> 92files. A header of the form <b><em>A.h(B.h)</em></b> indicates that 93<b><em>A.h</em></b> is included in <b><em>B.h</em></b>, so 94<b><em>A.h</em></b> need not be included explicitly if <b><em>B.h</em></b> 95is included. Operators marked with * in the "omissions" column are not 96implemented directly; the library provides lower-level procedures that can 97be used to implement the operator. 98 99<p> 100There are slight differences in the operators that return multiple values, 101since C's provisions for this are awkward. Also, the control structure for 102the operators involving callback procedures (<b><tt>pathforall</tt></b>, 103<b><tt>image</tt></b>, <b><tt>colorimage</tt></b>, 104<b><tt>imagemask</tt></b>) is partly inverted: the client calls a procedure 105to set up an enumerator object, and then calls another procedure for each 106iteration. The <b><tt>...show</tt></b> operators, 107<b><tt>charpath</tt></b>, and <b><tt>stringwidth</tt></b> also use an 108inverted control structure. 109 110<blockquote><table cellpadding=0 cellspacing=0> 111<tr valign=bottom> 112 <th align=left>Section<br>(operators) 113 <td> 114 <th align=left>Headers 115 <td> 116 <th align=left>Omissions 117<tr> <td colspan=5><hr> 118<tr valign=top> <td>Graphics state -- device-independent 119 <td> 120 <td><b><tt>gscolor.h</tt></b>(<b><tt>gsstate.h</tt></b>)<br><b><tt>gscolor1.h</tt></b><br><b><tt>gscolor2.h</tt></b><br><b><tt>gscspace.h</tt></b><br><b><tt>gshsb.h</tt></b><br><b><tt>gsline.h</tt></b>(<b><tt>gsstate.h</tt></b>)<br><b><tt>gsstate.h</tt></b> 121 <td> 122 <td> 123<tr> <td> 124<tr valign=top> <td>Graphics state -- device-dependent 125 <td> 126 <td><b><tt>gscolor.h</tt></b>(<b><tt>gsstate.h</tt></b>)<br><b><tt>gscolor1.h</tt></b><br><b><tt>gscolor2.h</tt></b><br><b><tt>gsht.h</tt></b>(<b><tt>gsht1.h</tt></b>,<b><tt>gsstate.h</tt></b>)<br><b><tt>gsht1.h</tt></b><br><b><tt>gsline.h</tt></b>(<b><tt>gsstate.h</tt></b>) 127 <td> 128 <td> 129<tr> <td> 130<tr valign=top> <td>Coordinate system and matrix 131 <td> 132 <td><b><tt>gscoord.h</tt></b><br><b><tt>gsmatrix.h</tt></b> 133 <td> 134 <td><b><tt>*matrix</tt></b>, <b><tt>*identmatrix</tt></b>, <b><tt>*concatmatrix</tt></b>, <b><tt>*invertmatrix</tt></b> 135<tr> <td> 136<tr valign=top> <td>Path construction 137 <td> 138 <td><b><tt>gspath.h</tt></b><br><b><tt>gspath2.h</tt></b> 139 <td> 140 <td><b><tt>*arct</tt></b>, <b><tt>*pathforall</tt></b>, <b><tt>ustrokepath</tt></b>, <b><tt>uappend</tt></b>, <b><tt>upath</tt></b>, <b><tt>ucache</tt></b> 141<tr> <td> 142<tr valign=top> <td>Painting 143 <td> 144 <td><b><tt>gsimage.h</tt></b><br><b><tt>gspaint.h</tt></b><br><b><tt>gspath2.h</tt></b> 145 <td> 146 <td><b><tt>*image</tt></b>, <b><tt>*colorimage</tt></b>, <b><tt>*imagemask</tt></b>, <b><tt>ufill</tt></b>, <b><tt>ueofill</tt></b>, <b><tt>ustroke</tt></b> 147<tr> <td> 148<tr valign=top> <td>Form and pattern 149 <td> 150 <td><b><tt>gscolor2.h</tt></b> 151 <td> 152 <td><b><tt>execform</tt></b> 153<tr> <td> 154<tr valign=top> <td>Device setup and output 155 <td> 156 <td><b><tt>gsdevice.h</tt></b> 157 <td> 158 <td><b><tt>*showpage</tt></b>, <b><tt>*set</tt></b>/<b><tt>currentpagedevice</tt></b> 159<tr> <td> 160<tr valign=top> <td>Character and font 161 <td> 162 <td><b><tt>gschar.h</tt></b><br><b><tt>gsfont.h</tt></b> 163 <td> 164 <td>*(all the <b><tt>show</tt></b> operators), <b><tt>definefont</tt></b>, <b><tt>undefinefont</tt></b>, <b><tt>findfont</tt></b>, <b><tt>*scalefont</tt></b>, <b><tt>*makefont</tt></b>, <b><tt>selectfont</tt></b>, <b><tt>[Global]FontDirectory</tt></b>, <b><tt>Standard</tt></b>/<b><tt>ISOLatin1Encoding</tt></b>, <b><tt>findencoding</tt></b> 165</table></blockquote> 166 167<p> 168The following procedures from the list above operate differently from their 169PostScript operator counterparts, as explained here: 170 171<dl> 172<dt><b><tt>gs_makepattern(gscolor2.h)</tt></b> 173<dd>Takes an explicit current color, rather than using the current color in 174the graphics state. Takes an explicit allocator for allocating the pattern 175implementation. See below for more details on 176<b><tt>gs_makepattern</tt></b>. 177</dl> 178 179<dl> 180<dt><b><tt>gs_setpattern(gscolor2.h)</tt></b> 181<dt><b><tt>gs_setcolor(gscolor2.h)</tt></b> 182<dt><b><tt>gs_currentcolor(gscolor2.h)</tt></b> 183<dd>Use <b><tt>gs_client_color</tt></b> rather than a set of color 184parameter values. See below for more details on 185<b><tt>gs_setpattern</tt></b>. 186</dl> 187 188<dl> 189<dt><b><tt>gs_currentdash_length/pattern/offset(gsline.h)</tt></b> 190<dd>Splits up <b><tt>currentdash</tt></b> into three separate procedures. 191</dl> 192 193<dl> 194<dt><b><tt>gs_screen_init/currentpoint/next/install(gsht.h)</tt></b> 195<dd>Provide an "enumeration style" interface to <b><tt>setscreen</tt></b>. 196(<b><tt>gs_setscreen</tt></b> is also implemented.) 197</dl> 198 199<dl> 200<dt><b><tt>gs_rotate/scale/translate(gscoord.h)</tt></b> 201<dt><b><tt>gs_[i][d]transform(gscoord.h)</tt></b> 202<dd>These always operate on the graphics state CTM. The corresponding 203operations on free-standing matrices are in <b><tt>gsmatrix.h</tt></b> and 204have different names. 205</dl> 206 207<dl> 208<dt><b><tt>gs_path_enum_alloc/init/next/cleanup(gspath.h)</tt></b> 209<dd>Provide an "enumeration style" implementation of 210<b><tt>pathforall</tt></b>. 211</dl> 212 213<dl> 214<dt><b><tt>gs_image_enum_alloc(gsimage.h)</tt></b> 215<dt><b><tt>gs_image_init/next/cleanup(gsimage.h)</tt></b> 216<dd>Provide an "enumeration style" interface to the equivalent of 217<b><tt>image</tt></b>, <b><tt>imagemask</tt></b>, and 218<b><tt>colorimage</tt></b>. In the <b><tt>gs_image_t</tt></b>, 219<b><tt>ColorSpace</tt></b> provides an explicit color space, rather than 220using the current color space in the graphics state; 221<b><tt>ImageMask</tt></b> distinguishes <b><tt>imagemask</tt></b> from 222<b><tt>[color]image</tt></b>. 223</dl> 224 225<dl> 226<dt><b><tt>gs_get/putdeviceparams(gsdevice.h)</tt></b> 227<dd>Take a <b><tt>gs_param_list</tt></b> for specifying or receiving the 228parameter values. See <b><tt>gsparam.h</tt></b> for more details. 229</dl> 230 231<dl> 232<dt><b><tt>gs_show_enum_alloc/release(gschar.h)</tt></b> 233<dt><b><tt>gs_xxxshow_[n_]init(gschar.h)</tt></b> 234<dt><b><tt>gs_show_next(gschar.h)</tt></b> 235<dd>Provide an "enumeration style" interface to writing text. Note that 236control returns to the caller if the character must be rasterized. 237</dl> 238 239<p> 240This level of the library also implements the following operators from other 241sections of the Manual: 242 243<blockquote><table cellpadding=0 cellspacing=0> 244<tr valign=bottom> 245 <th align=left>Section<br>(operators) 246 <td> 247 <th align=left>Headers 248 <td> 249 <th align=left>Operators 250<tr> <td colspan=5><hr> 251<tr valign=top> <td>Interpreter parameter 252 <td> 253 <td><b><tt>gsfont.h</tt></b> 254 <td> 255 <td><b><tt>cachestatus</tt></b>, <b><tt>setcachelimit</tt></b>, <b><tt>*set/currentcacheparams</tt></b> 256<tr valign=top> <td>Display PostScript 257 <td> 258 <td><b><tt>gsstate.h</tt></b> 259 <td> 260 <td><b><tt>set/currenthalftonephase</tt></b> 261</table></blockquote> 262 263<p> 264In order to obtain the full PostScript Level 2 functionality listed above, 265<b><tt>FEATURE_DEVS</tt></b> must be set in the makefile to include at least the following: 266 267<blockquote><b><tt> 268FEATURE_DEVS=patcore.dev cmykcore.dev psl2core.dev dps2core.dev ciecore.dev path1core.dev hsbcore.dev 269</tt></b></blockquote> 270 271<p> 272The <b><tt>*lib.mak</tt></b> makefiles mentioned below do not always 273include all of these features. 274 275<p> 276Files named <b><tt>gs*.c</tt></b> implement the higher level of the 277graphics library. As might be expected, all procedures, variables, and 278structures available at this level begin with "<b><tt>gs_</tt></b>". 279Structures that appear in these interfaces, but whose definitions may be 280hidden from clients, also have names beginning with "<b><tt>gs_</tt></b>", 281that is, the prefix, not the implementation, reflects at what level the 282abstraction is made available. 283 284<h3><a name="Patterns"></a>Patterns</h3> 285 286<p> 287Patterns are the most complicated PostScript language objects that the 288library API deals with. As in PostScript, defining a pattern color and 289using the color are two separate operations. 290 291<p> 292<b><tt>gs_makepattern</tt></b> defines a pattern color. Its arguments are as follows: 293 294<blockquote><table cellpadding=0 cellspacing=0> 295<tr valign=top> <td><b><tt>gs_client_color *</tt></b> 296 <td> 297 <td>The resulting <b><tt>Pattern</tt></b> color is stored here. This is different from PostScript, which has no color objects <em>per se</em>, and hence returns a modified copy of the dictionary. 298<tr valign=top> <td><b><tt>const gs_client_pattern *</tt></b> 299 <td> 300 <td>The analogue of the original <b><tt>Pattern</tt></b> dictionary, described in detail just below. 301<tr valign=top> <td><b><tt>const gs_matrix *</tt></b> 302 <td> 303 <td>Corresponds to the matrix argument of the <b><tt>makepattern</tt></b> operator. 304<tr valign=top> <td><b><tt>gs_state *</tt></b> 305 <td> 306 <td>The current graphics state. 307<tr valign=top> <td><b><tt>gs_memory_t *</tt></b> 308 <td> 309 <td>The allocator to use for allocating the saved data for the 310 <b><tt>Pattern</tt></b> color. If this is 311 <b><tt>NULL</tt></b>, <b><tt>gs_makepattern</tt></b> uses the 312 same allocator that allocated the graphics state. Library 313 clients should probably always use <b><tt>NULL</tt></b>. 314 315</table></blockquote> 316 317<p> 318The <b><tt>gs_client_pattern</tt></b> structure defined in 319<b><tt>gscolor2.h</tt></b> corresponds to the <b><tt>Pattern</tt></b> 320dictionary that is the argument to the PostScript language 321<b><tt>makepattern</tt></b> operator. This structure has one extra member, 322<b><tt>void *client_data</tt></b>, which is a place for clients to 323store a pointer to additional data for the <b><tt>PaintProc</tt></b>; this 324provides the same functionality as putting additional keys in the 325<b><tt>Pattern</tt></b> dictionary at the PostScript language level. The 326<b><tt>PaintProc</tt></b> is an ordinary C procedure that takes as 327parameters a <b><tt>gs_client_color *</tt></b>, which is the 328<b><tt>Pattern</tt></b> color that is being used for painting, and a 329<b><tt>gs_state *</tt></b>, which is the same graphics state that 330would be presented to the <b><tt>PaintProc</tt></b> in PostScript. 331Currently the <b><tt>gs_client_color *</tt></b> is always the current 332color in the graphics state, but the <b><tt>PaintProc</tt></b> should not 333rely on this. The <b><tt>PaintProc</tt></b> can retrieve the 334<b><tt>gs_client_pattern *</tt></b> from the 335<b><tt>gs_client_color *</tt></b> with the 336<b><tt>gs_getpattern</tt></b> procedure, also defined in 337<b><tt>gscolor2.h</tt></b>, and from there, it can retrieve the 338<b><tt>client_data</tt></b> pointer. 339 340<p> 341The normal way to set a <b><tt>Pattern</tt></b> color is to call 342<b><tt>gs_setpattern</tt></b> with the graphics state and with the 343<b><tt>gs_client_color</tt></b> returned by <b><tt>gs_makepattern</tt></b>. 344After that, one can use <b><tt>gs_setcolor</tt></b> to set further 345<b><tt>Pattern</tt></b> colors (colored, or uncolored with the same 346underlying color space); the rules are the same as those in PostScript. 347Note that for <b><tt>gs_setpattern</tt></b>, the 348<b><tt>paint.values</tt></b> in the <b><tt>gs_client_color</tt></b> must be 349filled in for uncolored patterns; this corresponds to the additional 350arguments for the PostScript <b><tt>setpattern</tt></b> operator in the 351uncolored case. 352 353<p> 354There is a special procedure <b><tt>gs_makebitmappattern</tt></b> for creating bitmap-based 355patterns. Its API is documented in <b><tt>gscolor2.h</tt></b>; its implementation, in 356<b><tt>gspcolor.c</tt></b>, may be useful as an example of a pattern using a particularly 357simple <b><tt>PaintProc.</tt></b> 358 359<h3><a name="Lower_level_API"></a>Lower-level API</h3> 360 361<p> 362Files named <b><tt>gx*.c</tt></b> implement the lower level of the graphics 363library. The interfaces at the <b><tt>gx</tt></b> level are less stable, 364and expose more of the implementation detail, than those at the 365<b><tt>gs</tt></b> level: in particular, the <b><tt>gx</tt></b> interfaces 366generally use device coordinates in an internal fixed-point representation, 367as opposed to the <b><tt>gs</tt></b> interfaces that use floating point 368user coordinates. Named entities at this level begin with 369<b><tt>gx_</tt></b>. 370 371<p> 372Files named <b><tt>gz*.c</tt></b> and <b><tt>gz*.h</tt></b> are internal to 373the Ghostscript implementation, and are not designed to be called by 374clients. 375 376<hr> 377 378<h2><a name="Visual_trace"></a>Visual Trace instructions</h2> 379 380<p> 381Visual Trace instructions may be inserted in code to provide debug output in 382a graphical form. Graphics Library doesn't provide a rasterisation of the 383output, because it is platform dependent. Instead this, client application 384shpuld set <b><tt>vd_trace0</tt></b> external variable to Graphics Library, 385passing a set of callbacks which provide the rasterization. 386 387<p> 388Visual Trace instructions are defined in <b><tt>vdtrace.h</tt></b>. 389Debug output must be opened with <b><tt>vd_get_dc</tt></b> instruction, 390which obtains a drawing context for the debug output, and must be closed 391with <b><tt>vd_release_dc</tt></b> instruction. After opening the output, 392scale, origin and shift to be set for mapping the debugee coordinate space 393to window coordinate space. Than painting instructions to be used. 394Painting may be either immediate or indirect. 395 396<p> 397Indirect painting uses <b><tt>vd_beg_path</b></tt> before 398line output and <b><tt>vd_end_path</b></tt> after line output, 399to store a path into a temporary storage. After this 400<b><tt>vd_stroke</b></tt> may be used for stroking the path, 401or <b><tt>vd_fill</b></tt> may be used for filling the region inside the path. 402 403<p> 404Immediate painting happens when path construction instructions are 405involved without <b><tt>vd_beg_path</b></tt> and <b><tt>vd_end_path</b></tt>. 406In this case lines and curves are being drawed immediately, when a path construction 407instruction is executed. 408 409<p> 410The following table explains the semantics of Visual Trace instructions. 411<p> 412 413<table cellpadding=0 cellspacing=0> 414<tr><th colspan=5 bgcolor="#CCCC00"><hr><font size="+1">Visual Trace instructions</font><hr> 415<tr> <th align=left>Instruction 416 <td> 417 <th align=left>Function 418 <td> 419 <th align=left>Parameters 420<tr> <td colspan=5><hr> 421<tr> <td><b><tt>vd_get_dc</tt></b> 422 <td> 423 <td>Obtain drawing context 424 <td> 425 <td><b><tt>-T</tt></b> option flag value, for which the subsequent output is enabled. 426<tr> <td><b><tt>vd_release_dc</tt></b> 427 <td> 428 <td>Release drawing context 429 <td> 430 <td> 431<tr> <td><b><tt>vd_enabled</tt></b> 432 <td> 433 <td>Is trace currently enabled ? 434 <td> 435 <td> 436<tr> <td><b><tt>vd_get_size_unscaled_x</tt></b> 437 <td> 438 <td>Get the horizontal size of the output window in pixels. 439 <td> 440 <td> 441<tr> <td><b><tt>vd_get_size_unscaled_y</tt></b> 442 <td> 443 <td>Get the vertical size of the output window in pixels. 444 <td> 445 <td> 446<tr> <td><b><tt>vd_get_size_caled_x</tt></b> 447 <td> 448 <td>Get the horizontal size of the output window in debuggee coordinate units. 449 <td> 450 <td> 451<tr> <td><b><tt>vd_get_size_caled_y</tt></b> 452 <td> 453 <td>Get the vertical size of the output window in debuggee coordinate units. 454 <td> 455 <td> 456<tr> <td><b><tt>vd_get_scale_x</tt></b> 457 <td> 458 <td>Get the horizontal scale. 459 <td> 460 <td> 461<tr> <td><b><tt>vd_get_scale_y</tt></b> 462 <td> 463 <td>Get the vertical scale. 464 <td> 465 <td> 466<tr> <td><b><tt>vd_get_origin_x</tt></b> 467 <td> 468 <td>Get the horizontal position of the draft origin in debuggee coordinate space. 469 <td> 470 <td> 471<tr> <td><b><tt>vd_get_origin_y</tt></b> 472 <td> 473 <td>Get the vertical position of the draft origin in debuggee coordinate space. 474 <td> 475 <td> 476<tr> <td><b><tt>vd_set_scale(s)</tt></b> 477 <td> 478 <td>Set isotripic scale. 479 <td> 480 <td>Debugee space to window space mapping scale, same for both dimentions. 481<tr> <td><b><tt>vd_set_scaleXY(sx,sy)</tt></b> 482 <td> 483 <td>Set anisotripic scale. 484 <td> 485 <td>Debugee space to window space mapping scale, one for each dimention. 486<tr> <td><b><tt>vd_set_origin(x,y)</tt></b> 487 <td> 488 <td>Set the draft origin. 489 <td> 490 <td>Origin of the draft in debugee space. 491<tr> <td><b><tt>vd_set_shift(x,y)</tt></b> 492 <td> 493 <td>Set the draft position. 494 <td> 495 <td>Position of the draft origin in window space (in pixels). 496<tr> <td><b><tt>vd_set_central_shift</tt></b> 497 <td> 498 <td>Set the draft position to window center. 499 <td> 500 <td> 501<tr> <td><b><tt>vd_erase(c)</tt></b> 502 <td> 503 <td>Fill entire window. 504 <td> 505 <td>Color to fill. 506<tr> <td><b><tt>vd_beg_path</tt></b> 507 <td> 508 <td>Begin path construction. 509 <td> 510 <td> 511<tr> <td><b><tt>vd_end_path</tt></b> 512 <td> 513 <td>End path construction. 514 <td> 515 <td> 516<tr> <td><b><tt>vd_moveto(x,y)</tt></b> 517 <td> 518 <td>Path construction : Set the draft current point. 519 <td> 520 <td>Debugee coordinates. 521<tr> <td><b><tt>vd_lineto(x,y)</tt></b> 522 <td> 523 <td>Path construction : Line from current point to specified point. 524 <td> 525 <td>Debugee coordinates. 526<tr> <td><b><tt>vd_lineto_mupti(p,n)</tt></b> 527 <td> 528 <td>Path construction : Poliline from current point to specified points. 529 <td> 530 <td>Array of points and its size, debugee coordinates. 531<tr> <td><b><tt>vd_curveto(x0,y0,x1,y1,x2,y2)</tt></b> 532 <td> 533 <td>Path construction : Curve (3d order Bezier) from current point to specified point, with specified poles. 534 <td> 535 <td>2 poles and the curve ending point, debuggee coordinates. 536<tr> <td><b><tt>vd_closepath</tt></b> 537 <td> 538 <td>Path construction : Close the path (is necessary for filling an area). 539 <td> 540 <td> 541<tr> <td><b><tt>vd_bar(x0,y0,x1,y1,w,c)</tt></b> 542 <td> 543 <td>Bar from point to point. 544 <td> 545 <td>2 points (debugee coordinates), width (in pixels) and color. 546<tr> <td><b><tt>vd_square(x0,y0,w,c)</tt></b> 547 <td> 548 <td>Square with specified center and size. 549 <td> 550 <td>The center (debugee coordinates), size (in pixels) and color. 551<tr> <td><b><tt>vd_rect(x0,y0,x1,y1,w,c)</tt></b> 552 <td> 553 <td>Canonic rectangle with specified coordinites. 554 <td> 555 <td>Coordinates of boundaries (debugee coordinates), line width (in pixels) and color. 556<tr> <td><b><tt>vd_quad(x0,y0,x1,y1,x2,y2,x3,y3,w,c)</tt></b> 557 <td> 558 <td>Quadrangle with specified coordinites. 559 <td> 560 <td>Coordinates of vertices (debugee coordinates), line width (in pixels) and color. 561<tr> <td><b><tt>vd_curve(x0,y0,x1,y1,x2,y2,x3,y3,c,w)</tt></b> 562 <td> 563 <td>Curve with width. 564 <td> 565 <td>4 curve poles (debugee coordinates), color, and width (in pixels). 566<tr> <td><b><tt>vd_circle(x,y,r,c)</tt></b> 567 <td> 568 <td>Circle. 569 <td> 570 <td>Center (debugee coordinates), radius (in pixels) and color. 571<tr> <td><b><tt>vd_round(x,y,r,c)</tt></b> 572 <td> 573 <td>Filled circle. 574 <td> 575 <td>Center (debugee coordinates), radius (in pixels) and color. 576<tr> <td><b><tt>vd_stroke</tt></b> 577 <td> 578 <td>Stroke a path constructed with vd_beg_path, vd_moveto, vd_lineto, 579 vd_curveto, vd_closepath, vd_end_path. 580 <td> 581 <td> 582<tr> <td><b><tt>vd_fill</tt></b> 583 <td> 584 <td>Fill a path constructed with vd_beg_path, vd_moveto, vd_lineto, 585 vd_curveto, vd_closepath, vd_end_path. 586 <td> 587 <td> 588<tr> <td><b><tt>vd_setcolor(c)</tt></b> 589 <td> 590 <td>Set a color. 591 <td> 592 <td>Color (an integer consisting of red, green, blue bytes). 593<tr> <td><b><tt>vd_setlinewidth(w)</tt></b> 594 <td> 595 <td>Set line width. 596 <td> 597 <td>Width (in pixels). 598<tr> <td><b><tt>vd_text(x,y,s,c)</tt></b> 599 <td> 600 <td>Paint a text. 601 <td> 602 <td>Origin point (debugee coordinates), a string, and a color. 603<tr> <td><b><tt>vd_wait</tt></b> 604 <td> 605 <td>Delay execution until a resuming command is entered through user interface. 606 <td> 607 <td> 608</table> 609 610 611<p> 612Graphics Library doesn't provide a rasterization of the debug output. 613Instead it calls callbacks, which are specified by a client, and which may 614have a platform dependent implementation. The implementation must not 615use Graphics Library to exclude recursive calls to it from Visual Trace 616instructions. The callbacks and auxiliary data are collected in 617the structure <b><tt>vd_trace_interface</b></tt>, explained in the table below. 618<p> 619 620<table cellpadding=0 cellspacing=0> 621<tr><th colspan=5 bgcolor="#CCCC00"><hr><font size="+1">vd_trace_interface structure</font><hr> 622<tr> <th align=left>Field 623 <td> 624 <th align=left>Purpose 625 <td> 626 <th align=left>Parameters 627<tr> <td colspan=5><hr> 628<tr> <td><b><tt>host</tt></b> 629 <td> 630 <td>A pointer to the rasterizer control block - to be provided by client application. 631 The type of the fild is client dependent. 632 <td> 633 <td> 634<tr> <td><b><tt>scale_x, scale_y</tt></b> 635 <td> 636 <td>Scale of debugee coordinate to window coordinate mapping - internal work data, don't change. 637 <td> 638 <td> 639<tr> <td><b><tt>orig_x, orig_y</tt></b> 640 <td> 641 <td>Draft origin in debugee coordinates - internal work data, don't change. 642 <td> 643 <td> 644<tr> <td><b><tt>shift_x, shift_y</tt></b> 645 <td> 646 <td>Draft shift in window coordinates - internal work data, don't change. 647 <td> 648 <td> 649<tr> <td><b><tt>get_size_x(I)</tt></b> 650 <td> 651 <td>Get window width in pixels. 652 <td> 653 <td> 654<tr> <td><b><tt>get_size_y(I)</tt></b> 655 <td> 656 <td>Get window height in pixels. 657 <td> 658 <td> 659<tr> <td><b><tt>get_dc(I,I1)</tt></b> 660 <td> 661 <td>Obtain drawing context. 662 <td> 663 <td>Pointer to interface block, and pointer to copy of the pointer. 664 Implementation must set *I1 if it succeeds to get a drawing context. 665<tr> <td><b><tt>release_dc(I,I1)</tt></b> 666 <td> 667 <td>Release drawing context. 668 <td> 669 <td>Pointer to interface block, and pointer to copy of the pointer. 670 Implementation must reset *I1 if it succeeds to release the drawing context. 671<tr> <td><b><tt>erase(I,c)</tt></b> 672 <td> 673 <td>Erase entire window. 674 <td> 675 <td>Background color. 676<tr> <td><b><tt>beg_path(I)</tt></b> 677 <td> 678 <td>Begin path construction. 679 <td> 680 <td> 681<tr> <td><b><tt>end_path(I)</tt></b> 682 <td> 683 <td>End path construction. 684 <td> 685 <td> 686<tr> <td><b><tt>moveto(I,x,y)</tt></b> 687 <td> 688 <td>Set current point. 689 <td> 690 <td>A point in window coordinates. 691<tr> <td><b><tt>lineto(I,x,y)</tt></b> 692 <td> 693 <td>Line from current point to specified point. 694 <td> 695 <td>A point in window coordinates. 696<tr> <td><b><tt>curveto(I,x0,y0,x1,y1,x2,y2)</tt></b> 697 <td> 698 <td>Curve from current point with specified poles to specified point. 699 <td> 700 <td>3 points in window coordinates. 701<tr> <td><b><tt>closepath(I)</tt></b> 702 <td> 703 <td>Close the path. 704 <td> 705 <td> 706<tr> <td><b><tt>circle(I,x,y,r)</tt></b> 707 <td> 708 <td>Circle. 709 <td> 710 <td>Center and radius, window coordinates. 711<tr> <td><b><tt>round(I,x,y,r)</tt></b> 712 <td> 713 <td>Filled circle. 714 <td> 715 <td>Center and radius, window coordinates. 716<tr> <td><b><tt>fill(I)</tt></b> 717 <td> 718 <td>Fill the path. 719 <td> 720 <td> 721<tr> <td><b><tt>stroke(I)</tt></b> 722 <td> 723 <td>Stroke the path. 724 <td> 725 <td> 726<tr> <td><b><tt>setcolor(I,c)</tt></b> 727 <td> 728 <td>Set color. 729 <td> 730 <td>An integer, consisting of red, green, blue bytes. 731<tr> <td><b><tt>setlinewidth(I,w)</tt></b> 732 <td> 733 <td>Set line width. 734 <td> 735 <td>Line width in pixels. 736<tr> <td><b><tt>text(I,x,y,s)</tt></b> 737 <td> 738 <td>Draw a text. 739 <td> 740 <td>Coodrinates in pixels, and a string. 741<tr> <td><b><tt>wait(I)</tt></b> 742 <td> 743 <td>Delay execution untill resume command is inputted from user. 744 <td> 745 <td> 746</table> 747 748 749 750<p> 751<hr> 752 753<h2><a name="Full_example"></a>A full example</h2> 754 755<p> 756The file <b><tt>gslib.c</tt></b> in the Ghostscript fileset is a complete 757example program that initializes the library and produces output using it; 758files named <b><tt>*lib.mak</tt></b> (such as <b><tt>ugcclib.mak</tt></b> 759and <b><tt>bclib.mak</tt></b>) are makefiles using <b><tt>gslib.c</tt></b> 760as the main program. The following annotated excerpts from this file are 761intended to provide a roadmap for applications that call the library. 762 763<blockquote><pre>/* Capture stdin/out/err before gs.h redefines them. */ 764#include <stdio.h> 765static FILE *real_stdin, *real_stdout, *real_stderr; 766static void 767get_real(void) 768{ real_stdin = stdin, real_stdout = stdout, real_stderr = stderr; 769}</pre></blockquote> 770 771<p> 772Any application using Ghostscript should include the fragment above at the 773very beginning of the main program. 774 775<blockquote><pre>#include "gx.h"</pre></blockquote> 776 777<p> 778The <b><tt>gx.h</tt></b> header includes a wealth of declarations related 779to the Ghostscript memory manager, portability machinery, debugging 780framework, and other substrate facilities. Any application file that calls 781any Ghostscript API functions should probably include <b><tt>gx.h</tt></b>. 782 783<blockquote><pre>/* Configuration information imported from gconfig.c. */ 784extern gx_device *gx_device_list[]; 785 786/* Other imported procedures */ 787 /* from gsinit.c */ 788extern void gs_lib_init(P1(FILE *)); 789extern void gs_lib_finit(P2(int, int)); 790 /* from gsalloc.c */ 791extern gs_ref_memory_t *ialloc_alloc_state(P2(gs_memory_t *, uint));</pre></blockquote> 792 793<p> 794The externs above are needed for initializing the library. 795 796<blockquote><pre> gs_ref_memory_t *imem; 797#define mem ((gs_memory_t *)imem) 798 gs_state *pgs; 799 gx_device *dev = gx_device_list[0]; 800 801 gp_init(); 802 get_real(); 803 gs_stdin = real_stdin; 804 gs_stdout = real_stdout; 805 gs_stderr = real_stderr; 806 gs_lib_init(stdout); 807 .... 808 imem = ialloc_alloc_state(&gs_memory_default, 20000); 809 imem->space = 0; 810 .... 811 pgs = gs_state_alloc(mem);</pre></blockquote> 812 813<p> 814The code above initializes the library and its memory manager. <b><tt>pgs</tt></b> now 815points to the graphics state that will be passed to the drawing routines in 816the library. 817 818<blockquote><pre> gs_setdevice_no_erase(pgs, dev); /* can't erase yet */ 819 { gs_point dpi; 820 gs_screen_halftone ht; 821 gs_dtransform(pgs, 72.0, 72.0, &dpi); 822 ht.frequency = min(fabs(dpi.x), fabs(dpi.y)) / 16.001; 823 ht.angle = 0; 824 ht.spot_function = odsf; 825 gs_setscreen(pgs, &ht); 826 }</pre></blockquote> 827 828<p> 829The code above initializes the default device and sets a default halftone 830screen. (For brevity, we have omitted the definition of odsf, the spot 831function.) 832 833<blockquote><pre> /* gsave and grestore (among other places) assume that */ 834 /* there are at least 2 gstates on the graphics stack. */ 835 /* Ensure that now. */ 836 gs_gsave(pgs);</pre></blockquote> 837 838<p> 839The call above completes initializing the graphics state. When the program 840is finished, it should execute: 841 842<blockquote><pre> gs_lib_finit(0, 0);</pre></blockquote> 843 844<!-- [2.0 end contents] ==================================================== --> 845 846<!-- [3.0 begin visible trailer] =========================================== --> 847<hr> 848 849<p> 850<small>Copyright © 1996, 1997, 1998 Aladdin Enterprises. 851All rights reserved.</small> 852 853<p> 854This software is provided AS-IS with no warranty, either express or 855implied. 856 857This software is distributed under license and may not be copied, 858modified or distributed except as expressly authorized under the terms 859of the license contained in the file LICENSE in this distribution. 860 861For more information about licensing, please refer to 862http://www.ghostscript.com/licensing/. For information on 863commercial licensing, go to http://www.artifex.com/licensing/ or 864contact Artifex Software, Inc., 101 Lucas Valley Road #110, 865San Rafael, CA 94903, U.S.A., +1(415)492-9861. 866 867<p> 868<small>Ghostscript version 8.53, 20 October 2005 869 870<!-- [3.0 end visible trailer] ============================================= --> 871 872</body> 873</html> 874