]>
Commit | Line | Data |
---|---|---|
7407ac7f BB |
1 | /* |
2 | SDL_ttf: A companion library to SDL for working with TrueType (tm) fonts | |
3 | Copyright (C) 2001-2013 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 | #ifndef _SDL_TTF_H | |
28 | #define _SDL_TTF_H | |
29 | ||
30 | #include <SDL2/SDL.h> | |
31 | #include <SDL2/begin_code.h> | |
32 | ||
33 | /* Set up for C function definitions, even when using C++ */ | |
34 | #ifdef __cplusplus | |
35 | extern "C" { | |
36 | #endif | |
37 | ||
38 | /* Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL | |
39 | */ | |
40 | #define SDL_TTF_MAJOR_VERSION 2 | |
41 | #define SDL_TTF_MINOR_VERSION 0 | |
42 | #define SDL_TTF_PATCHLEVEL 12 | |
43 | ||
44 | /* This macro can be used to fill a version structure with the compile-time | |
45 | * version of the SDL_ttf library. | |
46 | */ | |
47 | #define SDL_TTF_VERSION(X) \ | |
48 | { \ | |
49 | (X)->major = SDL_TTF_MAJOR_VERSION; \ | |
50 | (X)->minor = SDL_TTF_MINOR_VERSION; \ | |
51 | (X)->patch = SDL_TTF_PATCHLEVEL; \ | |
52 | } | |
53 | ||
54 | /* Backwards compatibility */ | |
55 | #define TTF_MAJOR_VERSION SDL_TTF_MAJOR_VERSION | |
56 | #define TTF_MINOR_VERSION SDL_TTF_MINOR_VERSION | |
57 | #define TTF_PATCHLEVEL SDL_TTF_PATCHLEVEL | |
58 | #define TTF_VERSION(X) SDL_TTF_VERSION(X) | |
59 | ||
60 | /* This function gets the version of the dynamically linked SDL_ttf library. | |
61 | it should NOT be used to fill a version structure, instead you should | |
62 | use the SDL_TTF_VERSION() macro. | |
63 | */ | |
64 | extern DECLSPEC const SDL_version * SDLCALL TTF_Linked_Version(void); | |
65 | ||
66 | /* ZERO WIDTH NO-BREAKSPACE (Unicode byte order mark) */ | |
67 | #define UNICODE_BOM_NATIVE 0xFEFF | |
68 | #define UNICODE_BOM_SWAPPED 0xFFFE | |
69 | ||
70 | /* This function tells the library whether UNICODE text is generally | |
71 | byteswapped. A UNICODE BOM character in a string will override | |
72 | this setting for the remainder of that string. | |
73 | */ | |
74 | extern DECLSPEC void SDLCALL TTF_ByteSwappedUNICODE(int swapped); | |
75 | ||
76 | /* The internal structure containing font information */ | |
77 | typedef struct _TTF_Font TTF_Font; | |
78 | ||
79 | /* Initialize the TTF engine - returns 0 if successful, -1 on error */ | |
80 | extern DECLSPEC int SDLCALL TTF_Init(void); | |
81 | ||
82 | /* Open a font file and create a font of the specified point size. | |
83 | * Some .fon fonts will have several sizes embedded in the file, so the | |
84 | * point size becomes the index of choosing which size. If the value | |
85 | * is too high, the last indexed size will be the default. */ | |
86 | extern DECLSPEC TTF_Font * SDLCALL TTF_OpenFont(const char *file, int ptsize); | |
87 | extern DECLSPEC TTF_Font * SDLCALL TTF_OpenFontIndex(const char *file, int ptsize, long index); | |
88 | extern DECLSPEC TTF_Font * SDLCALL TTF_OpenFontRW(SDL_RWops *src, int freesrc, int ptsize); | |
89 | extern DECLSPEC TTF_Font * SDLCALL TTF_OpenFontIndexRW(SDL_RWops *src, int freesrc, int ptsize, long index); | |
90 | ||
91 | /* Set and retrieve the font style */ | |
92 | #define TTF_STYLE_NORMAL 0x00 | |
93 | #define TTF_STYLE_BOLD 0x01 | |
94 | #define TTF_STYLE_ITALIC 0x02 | |
95 | #define TTF_STYLE_UNDERLINE 0x04 | |
96 | #define TTF_STYLE_STRIKETHROUGH 0x08 | |
97 | extern DECLSPEC int SDLCALL TTF_GetFontStyle(const TTF_Font *font); | |
98 | extern DECLSPEC void SDLCALL TTF_SetFontStyle(TTF_Font *font, int style); | |
99 | extern DECLSPEC int SDLCALL TTF_GetFontOutline(const TTF_Font *font); | |
100 | extern DECLSPEC void SDLCALL TTF_SetFontOutline(TTF_Font *font, int outline); | |
101 | ||
102 | /* Set and retrieve FreeType hinter settings */ | |
103 | #define TTF_HINTING_NORMAL 0 | |
104 | #define TTF_HINTING_LIGHT 1 | |
105 | #define TTF_HINTING_MONO 2 | |
106 | #define TTF_HINTING_NONE 3 | |
107 | extern DECLSPEC int SDLCALL TTF_GetFontHinting(const TTF_Font *font); | |
108 | extern DECLSPEC void SDLCALL TTF_SetFontHinting(TTF_Font *font, int hinting); | |
109 | ||
110 | /* Get the total height of the font - usually equal to point size */ | |
111 | extern DECLSPEC int SDLCALL TTF_FontHeight(const TTF_Font *font); | |
112 | ||
113 | /* Get the offset from the baseline to the top of the font | |
114 | This is a positive value, relative to the baseline. | |
115 | */ | |
116 | extern DECLSPEC int SDLCALL TTF_FontAscent(const TTF_Font *font); | |
117 | ||
118 | /* Get the offset from the baseline to the bottom of the font | |
119 | This is a negative value, relative to the baseline. | |
120 | */ | |
121 | extern DECLSPEC int SDLCALL TTF_FontDescent(const TTF_Font *font); | |
122 | ||
123 | /* Get the recommended spacing between lines of text for this font */ | |
124 | extern DECLSPEC int SDLCALL TTF_FontLineSkip(const TTF_Font *font); | |
125 | ||
126 | /* Get/Set whether or not kerning is allowed for this font */ | |
127 | extern DECLSPEC int SDLCALL TTF_GetFontKerning(const TTF_Font *font); | |
128 | extern DECLSPEC void SDLCALL TTF_SetFontKerning(TTF_Font *font, int allowed); | |
129 | ||
130 | /* Get the number of faces of the font */ | |
131 | extern DECLSPEC long SDLCALL TTF_FontFaces(const TTF_Font *font); | |
132 | ||
133 | /* Get the font face attributes, if any */ | |
134 | extern DECLSPEC int SDLCALL TTF_FontFaceIsFixedWidth(const TTF_Font *font); | |
135 | extern DECLSPEC char * SDLCALL TTF_FontFaceFamilyName(const TTF_Font *font); | |
136 | extern DECLSPEC char * SDLCALL TTF_FontFaceStyleName(const TTF_Font *font); | |
137 | ||
138 | /* Check wether a glyph is provided by the font or not */ | |
139 | extern DECLSPEC int SDLCALL TTF_GlyphIsProvided(const TTF_Font *font, Uint16 ch); | |
140 | ||
141 | /* Get the metrics (dimensions) of a glyph | |
142 | To understand what these metrics mean, here is a useful link: | |
143 | http://freetype.sourceforge.net/freetype2/docs/tutorial/step2.html | |
144 | */ | |
145 | extern DECLSPEC int SDLCALL TTF_GlyphMetrics(TTF_Font *font, Uint16 ch, | |
146 | int *minx, int *maxx, | |
147 | int *miny, int *maxy, int *advance); | |
148 | ||
149 | /* Get the dimensions of a rendered string of text */ | |
150 | extern DECLSPEC int SDLCALL TTF_SizeText(TTF_Font *font, const char *text, int *w, int *h); | |
151 | extern DECLSPEC int SDLCALL TTF_SizeUTF8(TTF_Font *font, const char *text, int *w, int *h); | |
152 | extern DECLSPEC int SDLCALL TTF_SizeUNICODE(TTF_Font *font, const Uint16 *text, int *w, int *h); | |
153 | ||
154 | /* Create an 8-bit palettized surface and render the given text at | |
155 | fast quality with the given font and color. The 0 pixel is the | |
156 | colorkey, giving a transparent background, and the 1 pixel is set | |
157 | to the text color. | |
158 | This function returns the new surface, or NULL if there was an error. | |
159 | */ | |
160 | extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderText_Solid(TTF_Font *font, | |
161 | const char *text, SDL_Color fg); | |
162 | extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUTF8_Solid(TTF_Font *font, | |
163 | const char *text, SDL_Color fg); | |
164 | extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUNICODE_Solid(TTF_Font *font, | |
165 | const Uint16 *text, SDL_Color fg); | |
166 | ||
167 | /* Create an 8-bit palettized surface and render the given glyph at | |
168 | fast quality with the given font and color. The 0 pixel is the | |
169 | colorkey, giving a transparent background, and the 1 pixel is set | |
170 | to the text color. The glyph is rendered without any padding or | |
171 | centering in the X direction, and aligned normally in the Y direction. | |
172 | This function returns the new surface, or NULL if there was an error. | |
173 | */ | |
174 | extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderGlyph_Solid(TTF_Font *font, | |
175 | Uint16 ch, SDL_Color fg); | |
176 | ||
177 | /* Create an 8-bit palettized surface and render the given text at | |
178 | high quality with the given font and colors. The 0 pixel is background, | |
179 | while other pixels have varying degrees of the foreground color. | |
180 | This function returns the new surface, or NULL if there was an error. | |
181 | */ | |
182 | extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderText_Shaded(TTF_Font *font, | |
183 | const char *text, SDL_Color fg, SDL_Color bg); | |
184 | extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUTF8_Shaded(TTF_Font *font, | |
185 | const char *text, SDL_Color fg, SDL_Color bg); | |
186 | extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUNICODE_Shaded(TTF_Font *font, | |
187 | const Uint16 *text, SDL_Color fg, SDL_Color bg); | |
188 | ||
189 | /* Create an 8-bit palettized surface and render the given glyph at | |
190 | high quality with the given font and colors. The 0 pixel is background, | |
191 | while other pixels have varying degrees of the foreground color. | |
192 | The glyph is rendered without any padding or centering in the X | |
193 | direction, and aligned normally in the Y direction. | |
194 | This function returns the new surface, or NULL if there was an error. | |
195 | */ | |
196 | extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderGlyph_Shaded(TTF_Font *font, | |
197 | Uint16 ch, SDL_Color fg, SDL_Color bg); | |
198 | ||
199 | /* Create a 32-bit ARGB surface and render the given text at high quality, | |
200 | using alpha blending to dither the font with the given color. | |
201 | This function returns the new surface, or NULL if there was an error. | |
202 | */ | |
203 | extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderText_Blended(TTF_Font *font, | |
204 | const char *text, SDL_Color fg); | |
205 | extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUTF8_Blended(TTF_Font *font, | |
206 | const char *text, SDL_Color fg); | |
207 | extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUNICODE_Blended(TTF_Font *font, | |
208 | const Uint16 *text, SDL_Color fg); | |
209 | ||
210 | ||
211 | /* Create a 32-bit ARGB surface and render the given text at high quality, | |
212 | using alpha blending to dither the font with the given color. | |
213 | Text is wrapped to multiple lines on line endings and on word boundaries | |
214 | if it extends beyond wrapLength in pixels. | |
215 | This function returns the new surface, or NULL if there was an error. | |
216 | */ | |
217 | extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderText_Blended_Wrapped(TTF_Font *font, | |
218 | const char *text, SDL_Color fg, Uint32 wrapLength); | |
219 | extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUTF8_Blended_Wrapped(TTF_Font *font, | |
220 | const char *text, SDL_Color fg, Uint32 wrapLength); | |
221 | extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUNICODE_Blended_Wrapped(TTF_Font *font, | |
222 | const Uint16 *text, SDL_Color fg, Uint32 wrapLength); | |
223 | ||
224 | /* Create a 32-bit ARGB surface and render the given glyph at high quality, | |
225 | using alpha blending to dither the font with the given color. | |
226 | The glyph is rendered without any padding or centering in the X | |
227 | direction, and aligned normally in the Y direction. | |
228 | This function returns the new surface, or NULL if there was an error. | |
229 | */ | |
230 | extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderGlyph_Blended(TTF_Font *font, | |
231 | Uint16 ch, SDL_Color fg); | |
232 | ||
233 | /* For compatibility with previous versions, here are the old functions */ | |
234 | #define TTF_RenderText(font, text, fg, bg) \ | |
235 | TTF_RenderText_Shaded(font, text, fg, bg) | |
236 | #define TTF_RenderUTF8(font, text, fg, bg) \ | |
237 | TTF_RenderUTF8_Shaded(font, text, fg, bg) | |
238 | #define TTF_RenderUNICODE(font, text, fg, bg) \ | |
239 | TTF_RenderUNICODE_Shaded(font, text, fg, bg) | |
240 | ||
241 | /* Close an opened font file */ | |
242 | extern DECLSPEC void SDLCALL TTF_CloseFont(TTF_Font *font); | |
243 | ||
244 | /* De-initialize the TTF engine */ | |
245 | extern DECLSPEC void SDLCALL TTF_Quit(void); | |
246 | ||
247 | /* Check if the TTF engine is initialized */ | |
248 | extern DECLSPEC int SDLCALL TTF_WasInit(void); | |
249 | ||
250 | /* Get the kerning size of two glyphs */ | |
251 | extern DECLSPEC int TTF_GetFontKerningSize(TTF_Font *font, int prev_index, int index); | |
252 | ||
253 | /* We'll use SDL for reporting errors */ | |
254 | #define TTF_SetError SDL_SetError | |
255 | #define TTF_GetError SDL_GetError | |
256 | ||
257 | /* Ends C function definitions when using C++ */ | |
258 | #ifdef __cplusplus | |
259 | } | |
260 | #endif | |
261 | #include <SDL2/close_code.h> | |
262 | ||
263 | #endif /* _SDL_TTF_H */ |