| blob | 3ba0ad46794ff21b5763a70fbf1a91af9e409602 |
5 </head><body>
6 <!-- Generated by Doxygen 1.3.9.1 -->
7 <div class="qindex"><a class="qindexHL" href="index.html">Main Page</a> | <a class="qindex" href="annotated.html">Class List</a> | <a class="qindex" href="files.html">File List</a> | <a class="qindex" href="globals.html">File Members</a></div>
9 <p>
11 Introduction</a></h2>
12 Pango is the text rendering engine of GNOME 2.x. SDL_Pango connects the engine to SDL. In Windows, pre-built binary package (MSI and merge module) is provided.<h3><a class="anchor" name="dist">
13 Distribution</a></h3>
14 If you are a game software developer, you should know the difficulties of distribution. So I will start to introduce SDL_Pango from the viewpoint of distribution.<p>
15 In Un*x, SDL_Pango is hard to use as system-independent module, because it depends on fontconfig and Pango which are designed as system-singleton modules. If you use SDL_Pango, your software will require those modules installed to target system. If your software is shipped as shrink-wrap package, it may cause much problem on your support desk. You should carefully design your installation process.<p>
16 In Windows, SDL_Pango is distributed as "merge module" which contains fontconfig and Pango. Those binaries are modified as side-by-side components. You should use Windows Installer and merge the module on your MSI package. The merge module not only contains files, but also includes custom action which must be run at installation.<h3><a class="anchor" name="api">
17 High-level API</a></h3>
18 From the viewpoint of text rendering, the heart of SDL_Pango is high-level API. Other text rendering APIs, like DrawText() of Windows, font and text must be specified separately. In SDL_Pango, font specification is embedded in text like HTML:<p>
19 <div class="fragment"><pre class="fragment"> <span font_family=<span class="stringliteral">"Courier New"</span>><i>This is Courier New and italic.</i></span>
20 </pre></div><p>
21 Color, size, subscript/superscript, obliquing, weight, and other many features are also available in same way.<h3><a class="anchor" name="i18n">
22 Internationalized Text</a></h3>
23 Internationalized text is another key feature. Text is specified by UTF-8. RTL script (Arabic and Hebrew) and complicated rendering (Arabic, Indic and Thai) are supported. You can see it with GNOME 2.x.<h2><a class="anchor" name="get">
24 Getting Started</a></h2>
26 Get latest files</a></h3>
27 Get latest files from <a href="http://sourceforge.net/projects/sdlpango/">http://sourceforge.net/projects/sdlpango/</a> .<h3><a class="anchor" name="install">
28 Install Header and Library</a></h3>
29 In Windows and VS2003, I strongly recommend you to install MSI package. It contains Pango and fontconfig binaries which are modified as side-by-side components. It is nearly impossible to build them. (I spent much time to build them...)<p>
30 In MinGW, I recommend you to use VS2003. Otherwise you may run into the maze of distribution. If you insist MinGW, you should use MinGW binary archive.<p>
31 In Un*x, installation consists of:<p>
33 make
34 make install
36 Includes</a></h3>
37 To use SDL_Pango functions in a C/C++ source code file, you must use the <a class="el" href="_s_d_l___pango_8h.html">SDL_Pango.h</a> include file:<p>
38 <div class="fragment"><pre class="fragment"><span class="preprocessor"> #include "<a class="code" href="_s_d_l___pango_8h.html">SDL_Pango.h</a>"</span>
39 </pre></div><p>
40 In Windows, <a class="el" href="_s_d_l___pango_8h.html">SDL_Pango.h</a> is installed on <code>%ProgramFiles%\SDL_Pango</code> <code>Development\include</code> (usually <code>C:\Program</code> <code>Files\SDL_Pango</code> <code>Development\include</code>). You should add this directory to include path.<h3><a class="anchor" name="comp">
41 Compiling</a></h3>
42 In Un*x, to link with SDL_Pango you should use sdl-config to get the required SDL compilation options. After that, compiling with SDL_Pango is quite easy.<p>
43 Note: Some systems may not have the SDL_Pango library and include file in the same place as the SDL library and includes are located, in that case you will need to add more -I and -L paths to these command lines.<p>
44 Simple Example for compiling an object file:<p>
46 </pre></div><p>
47 Simple Example for linking an object file:<p>
48 <div class="fragment"><pre class="fragment"> cc -o myprogram mysource.o `sdl-config --libs` -lSDL_Pango
49 </pre></div><p>
50 Now myprogram is ready to run.<p>
51 You can see a sample of autoconfiscation in 'test' directory.<p>
52 In Windows, MSI package installs many dlls to <code>%ProgramFiles%\SDL_Pango</code> <code>Development\import_lib</code>. To link with SDL_Pango you should use SDL_Pango.lib.<p>
53 SDL_Pango.dll depends on many dlls and other many files. Those dlls are installed on <code>%ProgramFiles%\SDL_Pango</code> <code>Development\bin</code>. MSI package adds the directory to PATH environment variable.<h2><a class="anchor" name="devel">
54 Development</a></h2>
56 Font Handling</a></h3>
57 In Un*x, font handling depends on fontconfig of your system.<p>
58 In Windows, local.conf of fontconfig is placed on <code>%ProgramFiles%\SDL_Pango</code> <code>Development\etc\fonts</code>. You should know about fontconfig's font cache mechanism.<h3><a class="anchor" name="example">
59 Step-by-step Example</a></h3>
60 The operation of SDL_Pango is done via context.<p>
61 <div class="fragment"><pre class="fragment"> SDLPango_Context *context = <a class="code" href="_s_d_l___pango_8c.html#a23">SDLPango_CreateContext</a>();
62 </pre></div><p>
63 Specify default colors and minimum surface size.<p>
64 <div class="fragment"><pre class="fragment"> <a class="code" href="_s_d_l___pango_8c.html#a29">SDLPango_SetDefaultColor</a>(context, MATRIX_TRANSPARENT_BACK_WHITE_LETTER);
66 </pre></div><p>
67 Set markup text.<p>
68 <div class="fragment"><pre class="fragment"> <a class="code" href="_s_d_l___pango_8c.html#a32">SDLPango_SetMarkup</a>(context, <span class="stringliteral">"This is <i>markup</i> text."</span>, -1);
69 </pre></div><p>
70 Now you can get the size of surface.<p>
71 <div class="fragment"><pre class="fragment"> <span class="keywordtype">int</span> w = <a class="code" href="_s_d_l___pango_8c.html#a30">SDLPango_GetLayoutWidth</a>(context);
72 <span class="keywordtype">int</span> h = <a class="code" href="_s_d_l___pango_8c.html#a31">SDLPango_GetLayoutHeight</a>(context);
73 </pre></div><p>
74 Create surface to draw.<p>
77 SDL_Surface *surface = SDL_CreateRGBSurface(SDL_SWSURFACE,
81 </pre></div><p>
82 And draw on it.<p>
83 <div class="fragment"><pre class="fragment"> <a class="code" href="_s_d_l___pango_8c.html#a27">SDLPango_Draw</a>(context, surface, margin_x, margin_y);
84 </pre></div><p>
85 You must free the surface by yourself.<p>
87 </pre></div><p>
88 Free context.<p>
89 <div class="fragment"><pre class="fragment"> <a class="code" href="_s_d_l___pango_8c.html#a24">SDLPango_FreeContext</a>(context);
90 </pre></div><p>
92 Packaging</a></h3>
93 In Un*x, do it yourself.<p>
94 In Windows, font files must be installed on apprication folder (usually <code>C:\Program</code> <code>Files\</code>[Manufacturer]\[ProductName]). The property of apprication folder must be <code>TARGETDIR</code> (this is default setting of VS2003). SDL.dll also must be installed on apprication folder. Add SDL_Pango.msm to your MSI package.<h2><a class="anchor" name="ack">
95 Acknowledgment</a></h2>
96 SDL_Pango is developed with financial assistance of Information-technology Promotion Agency, Japan.<p>
97 <ul>
98 <li>NAKAMURA Ken'ichi <<a href="mailto:nakamura@sbp.fp.a.u-tokyo.ac.jp">nakamura@sbp.fp.a.u-tokyo.ac.jp</a>> </li></ul>
99 <hr size="1"><address style="align: right;"><small>Generated on Thu Dec 9 08:33:15 2004 for SDL_Pango by
102 </body>
103 </html>