4 SDL_ttf: A companion library to SDL for working with TrueType (tm) fonts
5 Copyright (C) 2001-2013 Sam Lantinga <slouken@libsdl.org>
7 This software is provided 'as-is', without any express or implied
8 warranty. In no event will the authors be held liable for any damages
9 arising from the use of this software.
11 Permission is granted to anyone to use this software for any purpose,
12 including commercial applications, and to alter it and redistribute it
13 freely, subject to the following restrictions:
15 1. The origin of this software must not be misrepresented; you must not
16 claim that you wrote the original software. If you use this software
17 in a product, an acknowledgement in the product documentation would be
18 appreciated but is not required.
19 2. Altered source versions must be plainly marked as such, and must not be
20 misrepresented as being the original software.
21 3. This notice may not be removed or altered from any source distribution.
24 {* This library is a wrapper around the excellent FreeType 2.0 library,
26 http://www.freetype.org/
29 {* ChangeLog: (Header Translation)
32 v.1.72-stable; 29.09.2013: fixed bug with procedures without parameters
33 (they must have brackets)
34 v.1.70-stable; 11.09.2013: Initial Commit
47 TTF_LibName = 'SDL2_ttf.dll';
52 TTF_LibName = 'libSDL_tff-2.dylib';
55 TTF_LibName = 'libSDL_ttf-2.so';
57 TTF_LibName = 'libSDL_ttf-2.so.0';
63 TTF_LibName = 'SDL2_ttf';
65 {$linklib libSDL2_ttf}
69 {* Set up for C function definitions, even when using C++ *}
71 {* Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL *}
73 SDL_TTF_MAJOR_VERSION = 2;
74 SDL_TTF_MINOR_VERSION = 0;
75 SDL_TTF_PATCHLEVEL = 12;
77 {* Backwards compatibility *}
79 TTF_MAJOR_VERSION = SDL_TTF_MAJOR_VERSION;
80 TTF_MINOR_VERSION = SDL_TTF_MINOR_VERSION;
81 TTF_PATCHLEVEL = SDL_TTF_PATCHLEVEL;
82 //TTF_VERSION(X) = SDL_TTF_VERSION(X);
84 {* This function gets the version of the dynamically linked SDL_ttf library.
85 it should NOT be used to fill a version structure, instead you should
86 use the SDL_TTF_VERSION() macro.
88 function TTF_Linked_Version: TSDL_Version cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_Linked_Version' {$ENDIF} {$ENDIF};
90 {* ZERO WIDTH NO-BREAKSPACE (Unicode byte order mark) *}
92 UNICODE_BOM_NATIVE = $FEFF;
93 UNICODE_BOM_SWAPPED = $FFFE;
95 {* This function tells the library whether UNICODE text is generally
96 byteswapped. A UNICODE BOM character in a string will override
97 this setting for the remainder of that string.
99 procedure TTF_ByteSwappedUNICODE(swapped: Integer) cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_ByteSwappedUNICODE' {$ENDIF} {$ENDIF};
101 {* The internal structure containing font information *}
103 PTTF_Font = ^TTTF_Font;
104 TTTF_Font = record end; //todo?
106 {* Initialize the TTF engine - returns 0 if successful, -1 on error *}
107 function TTF_Init(): Integer cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_Init' {$ENDIF} {$ENDIF};
109 {* Open a font file and create a font of the specified point size.
110 * Some .fon fonts will have several sizes embedded in the file, so the
111 * point size becomes the index of choosing which size. If the value
112 * is too high, the last indexed size will be the default. *}
113 function TTF_OpenFont(_file: PAnsiChar; ptsize: Integer): PTTF_Font cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_OpenFont' {$ENDIF} {$ENDIF};
114 function TTF_OpenFontIndex(_file: PAnsiChar; ptsize: Integer; index: LongInt): PTTF_Font cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_OpenFontIndex' {$ENDIF} {$ENDIF};
115 function TTF_OpenFontRW(src: PSDL_RWops; freesrc: Integer; ptsize: LongInt): PTTF_Font cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_OpenFontRW' {$ENDIF} {$ENDIF};
116 function TTF_OpenFontIndexRW(src: PSDL_RWops; freesrc: Integer; ptsize: Integer; index: LongInt): PTTF_Font cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_OpenFontIndexRW' {$ENDIF} {$ENDIF};
118 {* Set and retrieve the font style *}
120 TTF_STYLE_NORMAL = $00;
121 TTF_STYLE_BOLD = $01;
122 TTF_STYLE_ITALIC = $02;
123 TTF_STYLE_UNDERLINE = $04;
124 TTF_STYLE_STRIKETHROUGH = $08;
126 function TTF_GetFontStyle(font: PTTF_Font): Integer cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_GetFontStyle' {$ENDIF} {$ENDIF};
127 procedure TTF_SetFontStyle(font: PTTF_Font; style: Integer) cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_SetFontStyle' {$ENDIF} {$ENDIF};
128 function TTF_GetFontOutline(font: PTTF_Font): Integer cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_GetFontOutline' {$ENDIF} {$ENDIF};
129 procedure TTF_SetFontOutline(font: PTTF_Font; outline: Integer) cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_SetFontOutline' {$ENDIF} {$ENDIF};
131 {* Set and retrieve FreeType hinter settings *}
133 TTF_HINTING_NORMAL = 0;
134 TTF_HINTING_LIGHT = 1;
135 TTF_HINTING_MONO = 2;
136 TTF_HINTING_NONE = 3;
138 function TTF_GetFontHinting(font: PTTF_Font): Integer cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_GetFontHinting' {$ENDIF} {$ENDIF};
139 procedure TTF_SetFontHinting(font: PTTF_Font; hinting: Integer) cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_SetFontHinting' {$ENDIF} {$ENDIF};
141 {* Get the total height of the font - usually equal to point size *}
142 function TTF_FontHeight(font: PTTF_Font): Integer cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_FontHeight' {$ENDIF} {$ENDIF};
144 {* Get the offset from the baseline to the top of the font
145 This is a positive value, relative to the baseline.
147 function TTF_FontAscent(font: PTTF_Font): Integer cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_FontAscent' {$ENDIF} {$ENDIF};
149 {* Get the offset from the baseline to the bottom of the font
150 This is a negative value, relative to the baseline.
152 function TTF_FontDescent(font: PTTF_Font): Integer cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_FontDescent' {$ENDIF} {$ENDIF};
154 {* Get the recommended spacing between lines of text for this font *}
155 function TTF_FontLineSkip(font: PTTF_Font): Integer cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_FontLineSkip' {$ENDIF} {$ENDIF};
157 {* Get/Set whether or not kerning is allowed for this font *}
158 function TTF_GetFontKerning(font: PTTF_Font): Integer cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_GetFontKerning' {$ENDIF} {$ENDIF};
159 procedure TTF_SetFontKerning(font: PTTF_Font; allowed: Integer) cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_SetFontKerning' {$ENDIF} {$ENDIF};
161 {* Get the number of faces of the font *}
162 function TTF_FontFaces(font: PTTF_Font): LongInt cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_FontFaces' {$ENDIF} {$ENDIF};
164 {* Get the font face attributes, if any *}
165 function TTF_FontFaceIsFixedWidth(font: PTTF_Font): Integer cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_FontFaceIsFixedWidth' {$ENDIF} {$ENDIF};
166 function TTF_FontFaceFamilyName(font: PTTF_Font): PAnsiChar cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_FontFaceFamilyName' {$ENDIF} {$ENDIF};
167 function TTF_FontFaceStyleName(font: PTTF_Font): PAnsiChar cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_FontFaceStyleName' {$ENDIF} {$ENDIF};
169 {* Check wether a glyph is provided by the font or not *}
170 function TTF_GlyphIsProvided(font: PTTF_Font; ch: UInt16): Integer cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_GlyphIsProvided' {$ENDIF} {$ENDIF};
172 {* Get the metrics (dimensions) of a glyph
173 To understand what these metrics mean, here is a useful link:
174 http://freetype.sourceforge.net/freetype2/docs/tutorial/step2.html
176 function TTF_GlyphMetrics(font: PTTF_Font; ch: UInt16;
178 miny, maxy: PInt; advance: PInt): Integer cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_GlyphMetrics' {$ENDIF} {$ENDIF};
180 {* Get the dimensions of a rendered string of text *}
181 function TTF_SizeText(font: PTTF_Font; text: PAnsiChar; w, h: PInt): Integer cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_SizeText' {$ENDIF} {$ENDIF};
182 function TTF_SizeUTF8(font: PTTF_Font; text: PAnsiChar; w, h: PInt): Integer cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_SizeUTF8' {$ENDIF} {$ENDIF};
183 function TTF_SizeUNICODE(font: PTTF_Font; text: PUInt16; w, h: PInt): Integer cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_SizeUNICODE' {$ENDIF} {$ENDIF};
185 {* Create an 8-bit palettized surface and render the given text at
186 fast quality with the given font and color. The 0 pixel is the
187 colorkey, giving a transparent background, and the 1 pixel is set
189 This function returns the new surface, or NULL if there was an error.
191 function TTF_RenderText_Solid(font: PTTF_Font; text: PAnsiChar; fg: TSDL_Color): PSDL_Surface cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderText_Solid' {$ENDIF} {$ENDIF};
192 function TTF_RenderUTF8_Solid(font: PTTF_Font; text: PAnsiChar; fg: TSDL_Color): PSDL_Surface cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderUTF8_Solid' {$ENDIF} {$ENDIF};
193 function TTF_RenderUNICODE_Solid(font: PTTF_Font; text: PUInt16; fg: TSDL_Color): PSDL_Surface cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderUNICODE_Solid' {$ENDIF} {$ENDIF};
195 {* Create an 8-bit palettized surface and render the given glyph at
196 fast quality with the given font and color. The 0 pixel is the
197 colorkey, giving a transparent background, and the 1 pixel is set
198 to the text color. The glyph is rendered without any padding or
199 centering in the X direction, and aligned normally in the Y direction.
200 This function returns the new surface, or NULL if there was an error.
202 function TTF_RenderGlyph_Solid(font: PTTF_Font; ch: UInt16; fg: TSDL_Color): PSDL_Surface cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderGlyph_Solid' {$ENDIF} {$ENDIF};
204 {* Create an 8-bit palettized surface and render the given text at
205 high quality with the given font and colors. The 0 pixel is background,
206 while other pixels have varying degrees of the foreground color.
207 This function returns the new surface, or NULL if there was an error.
209 function TTF_RenderText_Shaded(font: PTTF_Font; text: PAnsiChar; fg, bg: TSDL_Color): PSDL_Surface cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderText_Shaded' {$ENDIF} {$ENDIF};
210 function TTF_RenderUTF8_Shaded(font: PTTF_Font; text: PAnsiChar; fg, bg: TSDL_Color): PSDL_Surface cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderUTF8_Shaded' {$ENDIF} {$ENDIF};
211 function TTF_RenderUNICODE_Shaded(font: PTTF_Font; text: PUInt16; fg, bg: TSDL_Color): PSDL_Surface cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderUNICODE_Shaded' {$ENDIF} {$ENDIF};
213 {* Create an 8-bit palettized surface and render the given glyph at
214 high quality with the given font and colors. The 0 pixel is background,
215 while other pixels have varying degrees of the foreground color.
216 The glyph is rendered without any padding or centering in the X
217 direction, and aligned normally in the Y direction.
218 This function returns the new surface, or NULL if there was an error.
220 function TTF_RenderGlyph_Shaded(font: PTTF_Font; ch: UInt16; fg, bg: TSDL_Color): PSDL_Surface cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderGlyph_Shaded' {$ENDIF} {$ENDIF};
222 {* Create a 32-bit ARGB surface and render the given text at high quality,
223 using alpha blending to dither the font with the given color.
224 This function returns the new surface, or NULL if there was an error.
226 function TTF_RenderText_Blended(font: PTTF_Font; text: PAnsiChar; fg: TSDL_Color): PSDL_Surface cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderText_Blended' {$ENDIF} {$ENDIF};
227 function TTF_RenderUTF8_Blended(font: PTTF_Font; text: PAnsiChar; fg: TSDL_Color): PSDL_Surface cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderUTF8_Blended' {$ENDIF} {$ENDIF};
228 function TTF_RenderUNICODE_Blended(font: PTTF_Font; text: UInt16; fg: TSDL_Color): PSDL_Surface cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderUNICODE_Blended' {$ENDIF} {$ENDIF};
230 {* Create a 32-bit ARGB surface and render the given text at high quality,
231 using alpha blending to dither the font with the given color.
232 Text is wrapped to multiple lines on line endings and on word boundaries
233 if it extends beyond wrapLength in pixels.
234 This function returns the new surface, or NULL if there was an error.
236 function TTF_RenderText_Blended_Wrapped(font: PTTF_Font; text: PAnsiChar; fg: TSDL_Color; wrapLength: UInt32): PSDL_Surface cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderText_Blended_Wrapped' {$ENDIF} {$ENDIF};
237 function TTF_RenderUTF8_Blended_Wrapped(font: PTTF_Font; text: PAnsiChar; fg: TSDL_Color; wrapLength: UInt32): PSDL_Surface cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderUTF8_Blended_Wrapped' {$ENDIF} {$ENDIF};
238 function TTF_RenderUNICODE_Blended_Wrapped(font: PTTF_Font; text: PUInt16; fg: TSDL_Color; wrapLength: UInt32): PSDL_Surface cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderUNICODE_Blended_Wrapped' {$ENDIF} {$ENDIF};
240 {* Create a 32-bit ARGB surface and render the given glyph at high quality,
241 using alpha blending to dither the font with the given color.
242 The glyph is rendered without any padding or centering in the X
243 direction, and aligned normally in the Y direction.
244 This function returns the new surface, or NULL if there was an error.
246 function TTF_RenderGlyph_Blended(font: PTTF_Font; ch: UInt16; fg: TSDL_Color): PSDL_Surface cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_RenderGlyph_Blended' {$ENDIF} {$ENDIF};
248 {* For compatibility with previous versions, here are the old functions *}
249 function TTF_RenderText(font: PTTF_Font; text: PAnsiChar; fg, bg: TSDL_Color): PSDL_Surface;
250 function TTF_RenderUTF8(font: PTTF_Font; text: PAnsiChar; fg, bg: TSDL_Color): PSDL_Surface;
251 function TTF_RenderUNICODE(font: PTTF_Font; text: PUInt16; fg, bg: TSDL_Color): PSDL_Surface;
253 {* Close an opened font file *}
254 procedure TTF_CloseFont(font: PTTF_Font) cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_CloseFont' {$ENDIF} {$ENDIF};
256 {* De-initialize the TTF engine *}
257 procedure TTF_Quit() cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_Quit' {$ENDIF} {$ENDIF};
259 {* Check if the TTF engine is initialized *}
260 function TTF_WasInit: Boolean cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_WasInit' {$ENDIF} {$ENDIF};
262 {* Get the kerning size of two glyphs *}
263 function TTF_GetFontKerningSize(font: PTTF_Font; prev_index, index: Integer): Integer cdecl; external TTF_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_TTF_GetFontKerningSize' {$ENDIF} {$ENDIF};
265 {* We'll use SDL for reporting errors *}
266 function TTF_SetError(const fmt: PAnsiChar): SInt32;
267 function TTF_GetError: PAnsiChar;
271 function TTF_SetError(const fmt: PAnsiChar): SInt32;
273 Result := SDL_SetError(fmt);
276 function TTF_GetError: PAnsiChar;
278 Result := SDL_GetError;
281 function TTF_RenderText(font: PTTF_Font; text: PAnsiChar; fg, bg: TSDL_Color): PSDL_Surface;
283 Result := TTF_RenderText_Shaded(font, text, fg, bg);
286 function TTF_RenderUTF8(font: PTTF_Font; text: PAnsiChar; fg, bg: TSDL_Color): PSDL_Surface;
288 Result := TTF_RenderUTF8_Shaded(font, text, fg, bg);
291 function TTF_RenderUNICODE(font: PTTF_Font; text: PUInt16; fg, bg: TSDL_Color): PSDL_Surface;
293 Result := TTF_RenderUNICODE_Shaded(font, text, fg, bg);