1 | /* |
2 | SDL_ttf: A companion library to SDL for working with TrueType (tm) fonts |
3 | Copyright (C) 2001-2019 Sam Lantinga <slouken@libsdl.org> |
4 | |
5 | This software is provided 'as-is', without any express or implied |
6 | warranty. In no event will the authors be held liable for any damages |
7 | arising from the use of this software. |
8 | |
9 | Permission is granted to anyone to use this software for any purpose, |
10 | including commercial applications, and to alter it and redistribute it |
11 | freely, subject to the following restrictions: |
12 | |
13 | 1. The origin of this software must not be misrepresented; you must not |
14 | claim that you wrote the original software. If you use this software |
15 | in a product, an acknowledgment in the product documentation would be |
16 | appreciated but is not required. |
17 | 2. Altered source versions must be plainly marked as such, and must not be |
18 | misrepresented as being the original software. |
19 | 3. This notice may not be removed or altered from any source distribution. |
20 | */ |
21 | |
22 | /* This library is a wrapper around the excellent FreeType 2.0 library, |
23 | available at: |
24 | http://www.freetype.org/ |
25 | */ |
26 | |
27 | /* Note: In many places, SDL_ttf will say "glyph" when it means "code point." |
28 | Unicode is hard, we learn as we go, and we apologize for adding to the |
29 | confusion. */ |
30 | |
31 | #ifndef SDL_TTF_H_ |
32 | #define SDL_TTF_H_ |
33 | |
34 | #include "SDL.h" |
35 | #include "begin_code.h" |
36 | |
37 | /* Set up for C function definitions, even when using C++ */ |
38 | #ifdef __cplusplus |
39 | extern "C" { |
40 | #endif |
41 | |
42 | /* Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL |
43 | */ |
44 | #define SDL_TTF_MAJOR_VERSION 2 |
45 | #define SDL_TTF_MINOR_VERSION 0 |
46 | #define SDL_TTF_PATCHLEVEL 15 |
47 | |
48 | /* This macro can be used to fill a version structure with the compile-time |
49 | * version of the SDL_ttf library. |
50 | */ |
51 | #define SDL_TTF_VERSION(X) \ |
52 | { \ |
53 | (X)->major = SDL_TTF_MAJOR_VERSION; \ |
54 | (X)->minor = SDL_TTF_MINOR_VERSION; \ |
55 | (X)->patch = SDL_TTF_PATCHLEVEL; \ |
56 | } |
57 | |
58 | /* Backwards compatibility */ |
59 | #define TTF_MAJOR_VERSION SDL_TTF_MAJOR_VERSION |
60 | #define TTF_MINOR_VERSION SDL_TTF_MINOR_VERSION |
61 | #define TTF_PATCHLEVEL SDL_TTF_PATCHLEVEL |
62 | #define TTF_VERSION(X) SDL_TTF_VERSION(X) |
63 | |
64 | /** |
65 | * This is the version number macro for the current SDL_ttf version. |
66 | */ |
67 | #define SDL_TTF_COMPILEDVERSION \ |
68 | SDL_VERSIONNUM(SDL_TTF_MAJOR_VERSION, SDL_TTF_MINOR_VERSION, SDL_TTF_PATCHLEVEL) |
69 | |
70 | /** |
71 | * This macro will evaluate to true if compiled with SDL_ttf at least X.Y.Z. |
72 | */ |
73 | #define SDL_TTF_VERSION_ATLEAST(X, Y, Z) \ |
74 | (SDL_TTF_COMPILEDVERSION >= SDL_VERSIONNUM(X, Y, Z)) |
75 | |
76 | /* Make sure this is defined (only available in newer SDL versions) */ |
77 | #ifndef SDL_DEPRECATED |
78 | #define SDL_DEPRECATED |
79 | #endif |
80 | |
81 | /* This function gets the version of the dynamically linked SDL_ttf library. |
82 | it should NOT be used to fill a version structure, instead you should |
83 | use the SDL_TTF_VERSION() macro. |
84 | */ |
85 | extern DECLSPEC const SDL_version * SDLCALL TTF_Linked_Version(void); |
86 | |
87 | /* ZERO WIDTH NO-BREAKSPACE (Unicode byte order mark) */ |
88 | #define UNICODE_BOM_NATIVE 0xFEFF |
89 | #define UNICODE_BOM_SWAPPED 0xFFFE |
90 | |
91 | /* This function tells the library whether UNICODE text is generally |
92 | byteswapped. A UNICODE BOM character in a string will override |
93 | this setting for the remainder of that string. |
94 | */ |
95 | extern DECLSPEC void SDLCALL TTF_ByteSwappedUNICODE(int swapped); |
96 | |
97 | /* The internal structure containing font information */ |
98 | typedef struct _TTF_Font TTF_Font; |
99 | |
100 | /* Initialize the TTF engine - returns 0 if successful, -1 on error */ |
101 | extern DECLSPEC int SDLCALL TTF_Init(void); |
102 | |
103 | /* Open a font file and create a font of the specified point size. |
104 | * Some .fon fonts will have several sizes embedded in the file, so the |
105 | * point size becomes the index of choosing which size. If the value |
106 | * is too high, the last indexed size will be the default. */ |
107 | extern DECLSPEC TTF_Font * SDLCALL TTF_OpenFont(const char *file, int ptsize); |
108 | extern DECLSPEC TTF_Font * SDLCALL TTF_OpenFontIndex(const char *file, int ptsize, long index); |
109 | extern DECLSPEC TTF_Font * SDLCALL TTF_OpenFontRW(SDL_RWops *src, int freesrc, int ptsize); |
110 | extern DECLSPEC TTF_Font * SDLCALL TTF_OpenFontIndexRW(SDL_RWops *src, int freesrc, int ptsize, long index); |
111 | |
112 | /* Set and retrieve the font style */ |
113 | #define TTF_STYLE_NORMAL 0x00 |
114 | #define TTF_STYLE_BOLD 0x01 |
115 | #define TTF_STYLE_ITALIC 0x02 |
116 | #define TTF_STYLE_UNDERLINE 0x04 |
117 | #define TTF_STYLE_STRIKETHROUGH 0x08 |
118 | extern DECLSPEC int SDLCALL TTF_GetFontStyle(const TTF_Font *font); |
119 | extern DECLSPEC void SDLCALL TTF_SetFontStyle(TTF_Font *font, int style); |
120 | extern DECLSPEC int SDLCALL TTF_GetFontOutline(const TTF_Font *font); |
121 | extern DECLSPEC void SDLCALL TTF_SetFontOutline(TTF_Font *font, int outline); |
122 | |
123 | /* Set and retrieve FreeType hinter settings */ |
124 | #define TTF_HINTING_NORMAL 0 |
125 | #define TTF_HINTING_LIGHT 1 |
126 | #define TTF_HINTING_MONO 2 |
127 | #define TTF_HINTING_NONE 3 |
128 | extern DECLSPEC int SDLCALL TTF_GetFontHinting(const TTF_Font *font); |
129 | extern DECLSPEC void SDLCALL TTF_SetFontHinting(TTF_Font *font, int hinting); |
130 | |
131 | /* Get the total height of the font - usually equal to point size */ |
132 | extern DECLSPEC int SDLCALL TTF_FontHeight(const TTF_Font *font); |
133 | |
134 | /* Get the offset from the baseline to the top of the font |
135 | This is a positive value, relative to the baseline. |
136 | */ |
137 | extern DECLSPEC int SDLCALL TTF_FontAscent(const TTF_Font *font); |
138 | |
139 | /* Get the offset from the baseline to the bottom of the font |
140 | This is a negative value, relative to the baseline. |
141 | */ |
142 | extern DECLSPEC int SDLCALL TTF_FontDescent(const TTF_Font *font); |
143 | |
144 | /* Get the recommended spacing between lines of text for this font */ |
145 | extern DECLSPEC int SDLCALL TTF_FontLineSkip(const TTF_Font *font); |
146 | |
147 | /* Get/Set whether or not kerning is allowed for this font */ |
148 | extern DECLSPEC int SDLCALL TTF_GetFontKerning(const TTF_Font *font); |
149 | extern DECLSPEC void SDLCALL TTF_SetFontKerning(TTF_Font *font, int allowed); |
150 | |
151 | /* Get the number of faces of the font */ |
152 | extern DECLSPEC long SDLCALL TTF_FontFaces(const TTF_Font *font); |
153 | |
154 | /* Get the font face attributes, if any */ |
155 | extern DECLSPEC int SDLCALL TTF_FontFaceIsFixedWidth(const TTF_Font *font); |
156 | extern DECLSPEC char * SDLCALL TTF_FontFaceFamilyName(const TTF_Font *font); |
157 | extern DECLSPEC char * SDLCALL TTF_FontFaceStyleName(const TTF_Font *font); |
158 | |
159 | /* Check wether a glyph is provided by the font or not */ |
160 | extern DECLSPEC int SDLCALL TTF_GlyphIsProvided(const TTF_Font *font, Uint16 ch); |
161 | |
162 | /* Get the metrics (dimensions) of a glyph |
163 | To understand what these metrics mean, here is a useful link: |
164 | http://freetype.sourceforge.net/freetype2/docs/tutorial/step2.html |
165 | */ |
166 | extern DECLSPEC int SDLCALL TTF_GlyphMetrics(TTF_Font *font, Uint16 ch, |
167 | int *minx, int *maxx, |
168 | int *miny, int *maxy, int *advance); |
169 | |
170 | /* Get the dimensions of a rendered string of text */ |
171 | extern DECLSPEC int SDLCALL TTF_SizeText(TTF_Font *font, const char *text, int *w, int *h); |
172 | extern DECLSPEC int SDLCALL TTF_SizeUTF8(TTF_Font *font, const char *text, int *w, int *h); |
173 | extern DECLSPEC int SDLCALL TTF_SizeUNICODE(TTF_Font *font, const Uint16 *text, int *w, int *h); |
174 | |
175 | /* Create an 8-bit palettized surface and render the given text at |
176 | fast quality with the given font and color. The 0 pixel is the |
177 | colorkey, giving a transparent background, and the 1 pixel is set |
178 | to the text color. |
179 | This function returns the new surface, or NULL if there was an error. |
180 | */ |
181 | extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderText_Solid(TTF_Font *font, |
182 | const char *text, SDL_Color fg); |
183 | extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUTF8_Solid(TTF_Font *font, |
184 | const char *text, SDL_Color fg); |
185 | extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUNICODE_Solid(TTF_Font *font, |
186 | const Uint16 *text, SDL_Color fg); |
187 | |
188 | /* Create an 8-bit palettized surface and render the given glyph at |
189 | fast quality with the given font and color. The 0 pixel is the |
190 | colorkey, giving a transparent background, and the 1 pixel is set |
191 | to the text color. The glyph is rendered without any padding or |
192 | centering in the X direction, and aligned normally in the Y direction. |
193 | This function returns the new surface, or NULL if there was an error. |
194 | */ |
195 | extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderGlyph_Solid(TTF_Font *font, |
196 | Uint16 ch, SDL_Color fg); |
197 | |
198 | /* Create an 8-bit palettized surface and render the given text at |
199 | high quality with the given font and colors. The 0 pixel is background, |
200 | while other pixels have varying degrees of the foreground color. |
201 | This function returns the new surface, or NULL if there was an error. |
202 | */ |
203 | extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderText_Shaded(TTF_Font *font, |
204 | const char *text, SDL_Color fg, SDL_Color bg); |
205 | extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUTF8_Shaded(TTF_Font *font, |
206 | const char *text, SDL_Color fg, SDL_Color bg); |
207 | extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUNICODE_Shaded(TTF_Font *font, |
208 | const Uint16 *text, SDL_Color fg, SDL_Color bg); |
209 | |
210 | /* Create an 8-bit palettized surface and render the given glyph at |
211 | high quality with the given font and colors. The 0 pixel is background, |
212 | while other pixels have varying degrees of the foreground color. |
213 | The glyph is rendered without any padding or centering in the X |
214 | direction, and aligned normally in the Y direction. |
215 | This function returns the new surface, or NULL if there was an error. |
216 | */ |
217 | extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderGlyph_Shaded(TTF_Font *font, |
218 | Uint16 ch, SDL_Color fg, SDL_Color bg); |
219 | |
220 | /* Create a 32-bit ARGB surface and render the given text at high quality, |
221 | using alpha blending to dither the font with the given color. |
222 | This function returns the new surface, or NULL if there was an error. |
223 | */ |
224 | extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderText_Blended(TTF_Font *font, |
225 | const char *text, SDL_Color fg); |
226 | extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUTF8_Blended(TTF_Font *font, |
227 | const char *text, SDL_Color fg); |
228 | extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUNICODE_Blended(TTF_Font *font, |
229 | const Uint16 *text, SDL_Color fg); |
230 | |
231 | |
232 | /* Create a 32-bit ARGB surface and render the given text at high quality, |
233 | using alpha blending to dither the font with the given color. |
234 | Text is wrapped to multiple lines on line endings and on word boundaries |
235 | if it extends beyond wrapLength in pixels. |
236 | This function returns the new surface, or NULL if there was an error. |
237 | */ |
238 | extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderText_Blended_Wrapped(TTF_Font *font, |
239 | const char *text, SDL_Color fg, Uint32 wrapLength); |
240 | extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUTF8_Blended_Wrapped(TTF_Font *font, |
241 | const char *text, SDL_Color fg, Uint32 wrapLength); |
242 | extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUNICODE_Blended_Wrapped(TTF_Font *font, |
243 | const Uint16 *text, SDL_Color fg, Uint32 wrapLength); |
244 | |
245 | /* Create a 32-bit ARGB surface and render the given glyph at high quality, |
246 | using alpha blending to dither the font with the given color. |
247 | The glyph is rendered without any padding or centering in the X |
248 | direction, and aligned normally in the Y direction. |
249 | This function returns the new surface, or NULL if there was an error. |
250 | */ |
251 | extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderGlyph_Blended(TTF_Font *font, |
252 | Uint16 ch, SDL_Color fg); |
253 | |
254 | /* For compatibility with previous versions, here are the old functions */ |
255 | #define TTF_RenderText(font, text, fg, bg) \ |
256 | TTF_RenderText_Shaded(font, text, fg, bg) |
257 | #define TTF_RenderUTF8(font, text, fg, bg) \ |
258 | TTF_RenderUTF8_Shaded(font, text, fg, bg) |
259 | #define TTF_RenderUNICODE(font, text, fg, bg) \ |
260 | TTF_RenderUNICODE_Shaded(font, text, fg, bg) |
261 | |
262 | /* Close an opened font file */ |
263 | extern DECLSPEC void SDLCALL TTF_CloseFont(TTF_Font *font); |
264 | |
265 | /* De-initialize the TTF engine */ |
266 | extern DECLSPEC void SDLCALL TTF_Quit(void); |
267 | |
268 | /* Check if the TTF engine is initialized */ |
269 | extern DECLSPEC int SDLCALL TTF_WasInit(void); |
270 | |
271 | /* Get the kerning size of two glyphs indices */ |
272 | /* DEPRECATED: this function requires FreeType font indexes, not glyphs, |
273 | by accident, which we don't expose through this API, so it could give |
274 | wildly incorrect results, especially with non-ASCII values. |
275 | Going forward, please use TTF_GetFontKerningSizeGlyphs() instead, which |
276 | does what you probably expected this function to do. */ |
277 | extern DECLSPEC int TTF_GetFontKerningSize(TTF_Font *font, int prev_index, int index) SDL_DEPRECATED; |
278 | |
279 | /* Get the kerning size of two glyphs */ |
280 | extern DECLSPEC int TTF_GetFontKerningSizeGlyphs(TTF_Font *font, Uint16 previous_ch, Uint16 ch); |
281 | |
282 | /* We'll use SDL for reporting errors */ |
283 | #define TTF_SetError SDL_SetError |
284 | #define TTF_GetError SDL_GetError |
285 | |
286 | /* Ends C function definitions when using C++ */ |
287 | #ifdef __cplusplus |
288 | } |
289 | #endif |
290 | #include "close_code.h" |
291 | |
292 | #endif /* SDL_TTF_H_ */ |
293 | |
294 | /* vi: set ts=4 sw=4 expandtab: */ |
295 | |