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>Ghostscript's external font and text interface</title> 5<!-- $Id: Xfonts.htm,v 1.39 2005/10/20 19:46:23 ray Exp $ --> 6<!-- Originally: xfonts.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>Ghostscript's external font and text interface</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="#Introduction">Introduction</a> 25<li><a href="#Types">Types</a> 26<li><a href="#Implementation_procedures">Implementation procedures</a> 27<li><a href="#Font_level_procedures">Font-level procedures</a> 28<ul> 29<li><a href="#lookup_font"><b><tt>lookup_font</tt></b></a> 30<li><a href="#char_xglyph"><b><tt>char_xglyph</tt></b></a> 31<li><a href="#char_metrics"><b><tt>char_metrics</tt></b></a> 32<li><a href="#render_char"><b><tt>render_char</tt></b></a> 33<li><a href="#release"><b><tt>release</tt></b></a> 34</ul> 35</ul></blockquote> 36 37<!-- [1.2 end table of contents] =========================================== --> 38 39<!-- [1.3 begin hint] ====================================================== --> 40 41<p>For other information, see the <a href="Readme.htm">Ghostscript 42overview</a>. 43 44<!-- [1.3 end hint] ======================================================== --> 45 46<hr> 47 48<!-- [1.0 end visible header] ============================================== --> 49 50<!-- [2.0 begin contents] ================================================== --> 51 52<h2><a name="Introduction"></a>Introduction</h2> 53 54<p> 55Ghostscript can use the character rasterizer provided by the underlying 56operating system and window system; specifically, Adobe Type Manager (ATM) 57or a TrueType rasterizer under MS Windows, or the facilities provided by X 58Windows. This ability augments, but does not replace, Ghostscript's own 59Type 1 rasterizer: Ghostscript may still use its own rasterizer for very 60large characters, characters that are clipped or transformed in unusual 61ways, and for output to devices other than the screen. 62 63<p> 64Ghostscript connects to these platform facilities through a driver-like 65interface called the xfont (external font) interface. Current xfont 66implementations are associated directly with device drivers; in a future 67release, Ghostscript may separate them, so that (for example) it will be 68possible to use the platform rasterizer when writing to a file. 69 70<p> 71Please note that from this point, this file is likely to be useful only 72to a small number of Ghostscript porters and implementors. 73 74<hr> 75 76<h2><a name="Types"></a>Types</h2> 77 78<table cellpadding=0 cellspacing=0> 79<tr> <th valign=bottom align=left>Type 80 <td> 81 <th valign=bottom align=left>Declared /<br>defined in 82 <td> 83 <th valign=bottom align=left>Represents 84<tr> <td colspan=5><hr> 85<tr> <td valign=top><b><tt>gs_char</tt></b> 86 <td> 87 <td valign=top><b><tt>gsccode.h</tt></b> 88 <td> 89 <td valign=top>A character code that appears in a string. Currently 90 it is always a single byte, but composite fonts or Unicode may 91 require it to be wider in the future. 92<tr> <td valign=top><b><tt>gs_glyph</tt></b> 93 <td> 94 <td valign=top><b><tt>gsccode.h</tt></b> 95 <td> 96 <td valign=top>A character name like "period" or "epsilon". From 97 the xfont implementation's point of view, it is just a handle; 98 when necessary, Ghostscript provides a 99 <b><tt>gs_proc_glyph_name_t</tt></b> procedure to 100 convert it to a string name. 101<tr> <td valign=top><b><tt>gs_proc_glyph_name_t</tt></b> 102 <td> 103 <td valign=top><b><tt>gsccode.h</tt></b> 104 <td> 105 <td valign=top>A procedure that maps a <b><tt>gs_glyph</tt></b> to 106 its string name; see the <b><tt>char_xglyph</tt></b> procedure. 107<tr> <td valign=top><b><tt>gx_xglyph</tt></b> 108 <td> 109 <td valign=top><b><tt>gsxfont.h</tt></b> 110 <td> 111 <td valign=top>A character or glyph code that can be used with a 112 specific platform font. Normally it will be a character code 113 that the implementation of <b><tt>render_char</tt></b> will 114 turn into a 1-character string and give to the platform's 115 "display string" operation. 116<tr> <td valign=top><b><tt>gx_xfont_procs</tt></b> 117 <td> 118 <td valign=top><b><tt>gsxfont.h</tt></b>, <b><tt>gxxfont.h</tt></b> 119 <td> 120 <td valign=top>The xfont analogue of 121 <b><tt>gx_device_procs</tt></b>, the type of the 122 procedure record that defines an xfont implementation. 123<tr> <td valign=top><b><tt>gx_xfont</tt></b> 124 <td> 125 <td valign=top><b><tt>gsxfont.h</tt></b>, <b><tt>gxxfont.h</tt></b> 126 <td> 127 <td valign=top>The gxfont analogue of <b><tt>gx_device</tt></b>, 128 the type of the basic structure for an xfont. 129<tr> <td valign=top>(<b><tt>encoding_index</tt></b>) 130 <td> 131 <td> 132 <td> 133 <td valign=top>Not really a type, although it probably should be: 134 an <b><tt>int</tt></b> used to indicate the 135 <b><tt>Encoding</tt></b> used by a font. Defined values are 136 <dl compact> 137 <dt>0<dd><b><tt>StandardEncoding</tt></b> 138 <dt>1<dd><b><tt>ISOLatin1Encoding</tt></b> 139 <dt>2<dd><b><tt>SymbolEncoding</tt></b> 140 <dt>3<dd><b><tt>DingbatsEncoding</tt></b> 141 <dt>-1<dd>Other encoding 142 </dl> 143</table> 144 145<hr> 146 147<h2><a name="Implementation_procedures"></a>Implementation 148procedures</h2> 149 150<p> 151All the procedures that return <b><tt>int</tt></b> results return 0 on 152success, or an appropriate negative error code for error conditions; these 153error codes are defined in <b><tt>gserrors.h</tt></b>. The relevant ones 154are the same as for <a href="Drivers.htm">drivers</a>, and as with drivers, 155if an implementation procedure returns an error, it should use the 156<b><tt>return_error</tt></b> macro -- defined in <b><tt>gx.h</tt></b>, 157which is automatically included by <b><tt>gdevprn.h</tt></b> but not by 158<b><tt>gserrors.h</tt></b> -- rather than a simple <b><tt>return</tt></b> 159statement, for instance 160 161<blockquote> 162<b><tt>return_error(gs_error_VMerror);</tt></b> 163</blockquote> 164 165<h2><a name="Font_level_procedures"></a>Font-level procedures</h2> 166 167<h3><a name="lookup_font"></a><b><tt>lookup_font</tt></b></h3> 168 169<dl> 170<dt><b><tt>gx_xfont *(*lookup_font)(P7(gx_device *dev, 171const byte *fname, uint len, int encoding_index, 172const gs_uid *puid, const gs_matrix *pmat, 173const gs_memory_procs *mprocs))</tt></b> 174<dd>Look up a font name, <b><tt>UniqueID</tt></b>, and matrix, and return 175an xfont, or <b><tt>NULL</tt></b> if no suitable xfont exists. Use 176<b><tt>mprocs</tt></b> to allocate the xfont and any subsidiary data 177structures. The matrix is the <b><tt>FontMatrix</tt></b> concatenated with 178the CTM, so (roughly speaking) the font size in pixels is 179<b><tt>pmat -> yy</tt></b> × 1000 for a normal 180Type 1 font. 181 182<p> 183Note that this is the only implementation procedure that does not take an 184xfont * as its first argument. In fact, callers of 185<b><tt>lookup_font</tt></b> must use the <b><tt>get_xfont_device</tt></b> 186driver procedure to get the correct device to pass as the first argument to 187<b><tt>lookup_font</tt></b>. 188</dl> 189 190<h3><a name="char_xglyph"></a><b><tt>char_xglyph</tt></b></h3> 191 192<dl> 193<dt><b><tt>gx_xglyph (*char_xglyph)(P5(gx_xfont *xf, gs_char chr, 194int encoding_index, gs_glyph glyph, 195gs_proc_glyph_name_t glyph_name))</tt></b> 196<dd>Convert a character name to an xglyph code. In the case of 197<b><tt>glyphshow</tt></b>, <b><tt>chr</tt></b> may be 198<b><tt>gs_no_char</tt></b>; for an ordinary <b><tt>show</tt></b> operation, 199if the character code is invalid, <b><tt>glyph</tt></b> may be 200<b><tt>gs_no_glyph</tt></b>. 201</dl> 202 203<h3><a name="char_metrics"></a><b><tt>char_metrics</tt></b></h3> 204 205<dl> 206<dt><b><tt>int (*char_metrics)(P5(gx_xfont *xf, gx_xglyph xg, 207int wmode, gs_int_point *pwidth, 208gs_int_rect *pbbox))</tt></b> 209<dd>Get the metrics for a character. If the metrics are unavailable, 210return 1. 211</dl> 212 213<h3><a name="render_char"></a><b><tt>render_char</tt></b></h3> 214 215<dl> 216<dt><b><tt>int (*render_char)(P7(gx_xfont *xf, gx_xglyph xg, 217gx_device *target, int x, int y, gx_color_index color, 218int required))</tt></b> 219<dd>Render a character. <em>(x,y)</em> corresponds to the character 220origin. The target may be any Ghostscript device. A good implementation 221will check whether the target can handle this type of xfont directly (for 222instance by checking the target name), and if so, will render the character 223directly; otherwise, it will do what has to be done in the general case, 224namely, get a bitmap for the character and use the target's 225<b><tt>copy_mono</tt></b> operation. If <b><tt>required</tt></b> is false, 226the procedure should return an error if the rendering operation would be 227expensive, since in this case Ghostscript has already cached the bitmap and 228metrics from a previous call with <b><tt>required</tt></b>=true. If the 229operation cannot be done, return 1. 230</dl> 231 232<h3><a name="release"></a><b><tt>release</tt></b></h3> 233 234<dl> 235<dt><b><tt>int (*release)(P2(gx_xfont *xf, 236const gs_memory_procs *mprocs))</tt></b> 237<dd>Release any external resources associated with an xfont. If 238<b><tt>mprocs</tt></b> is not <b><tt>NULL</tt></b>, also free any storage 239allocated by <b><tt>lookup_font</tt></b> (including the xfont itself). 240</dl> 241 242<!-- [2.0 end contents] ==================================================== --> 243 244<!-- [3.0 begin visible trailer] =========================================== --> 245<hr> 246 247<p> 248<small>Copyright © 1996, 1997, 1998 Aladdin Enterprises. All 249rights reserved.</small> 250 251<p> 252This software is provided AS-IS with no warranty, either express or 253implied. 254 255This software is distributed under license and may not be copied, 256modified or distributed except as expressly authorized under the terms 257of the license contained in the file LICENSE in this distribution. 258 259For more information about licensing, please refer to 260http://www.ghostscript.com/licensing/. For information on 261commercial licensing, go to http://www.artifex.com/licensing/ or 262contact Artifex Software, Inc., 101 Lucas Valley Road #110, 263San Rafael, CA 94903, U.S.A., +1(415)492-9861. 264 265<p> 266<small>Ghostscript version 8.53, 20 October 2005 267 268<!-- [3.0 end visible trailer] ============================================= --> 269 270</body> 271</html> 272