1 /** @file api_fontrender.h Font renderer.
2 *
3 * @ingroup gl
4 *
5 * @authors Copyright © 1999-2017 Jaakko Keränen <jaakko.keranen@iki.fi>
6 * @authors Copyright © 2006-2013 Daniel Swanson <danij@dengine.net>
7 *
8 * @par License
9 * GPL: http://www.gnu.org/licenses/gpl.html
10 *
11 * <small>This program is free software; you can redistribute it and/or modify
12 * it under the terms of the GNU General Public License as published by the
13 * Free Software Foundation; either version 2 of the License, or (at your
14 * option) any later version. This program is distributed in the hope that it
15 * will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
16 * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
17 * Public License for more details. You should have received a copy of the GNU
18 * General Public License along with this program; if not, write to the Free
19 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
20 * 02110-1301 USA</small>
21 */
22
23 #ifndef LIBDENG_API_FONT_RENDERER_H
24 #define LIBDENG_API_FONT_RENDERER_H
25
26 #include "api_base.h"
27
28 #ifdef __cplusplus
29 extern "C" {
30 #endif
31
32 /**
33 * Font attributes are managed as a finite stack of attribute sets.
34 * This value defines the maximum allowed depth of the attribute stack.
35 */
36 #define FR_MAX_ATTRIB_STACK_DEPTH (8)
37
38 /**
39 * Font attribute defaults. Used with FR_LoadDefaultAttrib.
40 */
41 #define FR_DEF_ATTRIB_LEADING (.5)
42 #define FR_DEF_ATTRIB_TRACKING (0)
43 #define FR_DEF_ATTRIB_COLOR_RED (1)
44 #define FR_DEF_ATTRIB_COLOR_GREEN (1)
45 #define FR_DEF_ATTRIB_COLOR_BLUE (1)
46 #define FR_DEF_ATTRIB_ALPHA (1)
47 #define FR_DEF_ATTRIB_GLITTER_STRENGTH (.5)
48 #define FR_DEF_ATTRIB_SHADOW_STRENGTH (.5)
49 #define FR_DEF_ATTRIB_SHADOW_XOFFSET (2)
50 #define FR_DEF_ATTRIB_SHADOW_YOFFSET (2)
51 #define FR_DEF_ATTRIB_CASE_SCALE (false)
52
53 /**
54 * @defgroup drawTextFlags Draw Text Flags
55 * @ingroup apiFlags
56 */
57 /*@{*/
58 #define DTF_NO_TYPEIN (0x0001)
59 #define DTF_NO_SHADOW (0x0002)
60 #define DTF_NO_GLITTER (0x0004)
61
62 #define DTF_NO_EFFECTS (DTF_NO_TYPEIN|DTF_NO_SHADOW|DTF_NO_GLITTER)
63 #define DTF_ONLY_SHADOW (DTF_NO_TYPEIN|DTF_NO_GLITTER)
64 /*@}*/
65
DENG_API_TYPEDEF(FR)66 DENG_API_TYPEDEF(FR)
67 {
68 de_api_t api;
69
70 fontid_t (*ResolveUri)(struct uri_s const *uri);
71
72 /// @return Unique identifier associated with the current font.
73 fontid_t (*Font)(void);
74
75 /// Change the current font.
76 void (*SetFont)(fontid_t font);
77
78 /// Push the attribute stack.
79 void (*PushAttrib)(void);
80
81 /// Pop the attribute stack.
82 void (*PopAttrib)(void);
83
84 /// Load the default attributes at the current stack depth.
85 void (*LoadDefaultAttrib)(void);
86
87 /// @return Current leading (attribute).
88 float (*Leading)(void);
89
90 void (*SetLeading)(float value);
91
92 /// @return Current tracking (attribute).
93 int (*Tracking)(void);
94
95 void (*SetTracking)(int value);
96
97 /// Retrieve the current color and alpha factors.
98 void (*ColorAndAlpha)(float rgba[4]);
99
100 void (*SetColor)(float red, float green, float blue);
101
102 void (*SetColorv)(const float rgb[3]);
103
104 void (*SetColorAndAlpha)(float red, float green, float blue, float alpha);
105
106 void (*SetColorAndAlphav)(const float rgba[4]);
107
108 /// @return Current red color factor.
109 float (*ColorRed)(void);
110
111 void (*SetColorRed)(float value);
112
113 /// @return Current green color factor.
114 float (*ColorGreen)(void);
115
116 void (*SetColorGreen)(float value);
117
118 /// @return Current blue color factor.
119 float (*ColorBlue)(void);
120
121 void (*SetColorBlue)(float value);
122
123 /// @return Current alpha factor.
124 float (*Alpha)(void);
125
126 void (*SetAlpha)(float value);
127
128 /// Retrieve the current shadow offset (attribute).
129 void (*ShadowOffset)(int* offsetX, int* offsetY);
130
131 void (*SetShadowOffset)(int offsetX, int offsetY);
132
133 /// @return Current shadow strength (attribute).
134 float (*ShadowStrength)(void);
135
136 void (*SetShadowStrength)(float value);
137
138 /// @return Current glitter strength (attribute).
139 float (*GlitterStrength)(void);
140
141 void (*SetGlitterStrength)(float value);
142
143 /// @return Current case scale (attribute).
144 dd_bool (*CaseScale)(void);
145
146 void (*SetCaseScale)(dd_bool value);
147
148 /**
149 * Text blocks (possibly formatted and/or multi-line text):
150 *
151 * Formatting of text blocks is initially determined by the current font
152 * renderer state at draw time (i.e., the attribute stack and draw paramaters).
153 *
154 ** Paramater blocks:
155 *
156 * A single text block may also embed attribute and draw paramater changes
157 * within the text string itself. Paramater blocks are defined within the curly
158 * bracketed escape sequence { } A single paramater block may
159 * contain any number of attribute and draw paramaters delimited by semicolons.
160 *
161 * A text block may contain any number of paramater blocks. The scope for which
162 * extends until the last character has been drawn or another block overrides
163 * the same attribute.
164 *
165 * Examples:
166 * <pre>
167 * "{r = 1.0; g = 0.0; b = 0.0; case}This is red text with a case-scaled first character"
168 * "This is text with an {y = -14}offset{y = 0} internal fragment."
169 * "{fontb; r=0.5; g=1; b=0; x=2; y=-2}This is good!"
170 * </pre>
171 */
172
173 /**
174 * Draw a text block.
175 *
176 * @param text Block of text to be drawn.
177 * @param origin Orient drawing about this offset (topleft:[0,0]).
178 */
179 void (*DrawText)(const char* text, const Point2Raw* origin);
180
181 /**
182 * @copydoc de_api_FR_s::DrawText
183 * @param alignFlags @ref alignmentFlags
184 */
185 void (*DrawText2)(const char* text, const Point2Raw* origin, int alignFlags);
186
187 /**
188 * Draw a text block.
189 *
190 * @param text Block of text to be drawn.
191 * @param _origin Orient drawing about this offset (topleft:[0,0]).
192 * @param alignFlags @ref alignmentFlags
193 * @param _textFlags @ref drawTextFlags
194 */
195 void (*DrawText3)(const char* text, const Point2Raw* _origin, int alignFlags, uint16_t _textFlags);
196
197 void (*DrawTextXY3)(const char* text, int x, int y, int alignFlags, short flags);
198
199 void (*DrawTextXY2)(const char* text, int x, int y, int alignFlags);
200
201 void (*DrawTextXY)(const char* text, int x, int y);
202
203 // Utility routines:
204 void (*TextSize)(Size2Raw* size, const char* text);
205
206 /// @return Visible width of the text.
207 int (*TextWidth)(const char* text);
208
209 /// @return Visible height of the text.
210 int (*TextHeight)(const char* text);
211
212 /*
213 * Single characters:
214 */
215
216 /**
217 * Draw a character.
218 *
219 * @param ch Character to be drawn.
220 * @param origin Origin/offset at which to begin drawing.
221 * @param alignFlags @ref alignmentFlags
222 * @param textFlags @ref drawTextFlags
223 */
224 void (*DrawChar3)(unsigned char ch, const Point2Raw* origin, int alignFlags, short textFlags);
225
226 void (*DrawChar2)(unsigned char ch, const Point2Raw* origin, int alignFlags);
227
228 void (*DrawChar)(unsigned char ch, const Point2Raw* origin);
229
230 void (*DrawCharXY3)(unsigned char ch, int x, int y, int alignFlags, short textFlags);
231
232 void (*DrawCharXY2)(unsigned char ch, int x, int y, int alignFlags);
233
234 void (*DrawCharXY)(unsigned char ch, int x, int y);
235
236 // Utility routines:
237 void (*CharSize)(Size2Raw* size, unsigned char ch);
238
239 /// @return Visible width of the character.
240 int (*CharWidth)(unsigned char ch);
241
242 /// @return Visible height of the character.
243 int (*CharHeight)(unsigned char ch);
244
245 /// @deprecated Will be replaced with per-text-object animations.
246 void (*ResetTypeinTimer)(void);
247
248 }
249 DENG_API_T(FR);
250
251 #ifndef DENG_NO_API_MACROS_FONT_RENDER
252 #define Fonts_ResolveUri _api_FR.ResolveUri
253 #define FR_Font _api_FR.Font
254 #define FR_SetFont _api_FR.SetFont
255 #define FR_PushAttrib _api_FR.PushAttrib
256 #define FR_PopAttrib _api_FR.PopAttrib
257 #define FR_LoadDefaultAttrib _api_FR.LoadDefaultAttrib
258 #define FR_Leading _api_FR.Leading
259 #define FR_SetLeading _api_FR.SetLeading
260 #define FR_Tracking _api_FR.Tracking
261 #define FR_SetTracking _api_FR.SetTracking
262 #define FR_ColorAndAlpha _api_FR.ColorAndAlpha
263 #define FR_SetColor _api_FR.SetColor
264 #define FR_SetColorv _api_FR.SetColorv
265 #define FR_SetColorAndAlpha _api_FR.SetColorAndAlpha
266 #define FR_SetColorAndAlphav _api_FR.SetColorAndAlphav
267 #define FR_ColorRed _api_FR.ColorRed
268 #define FR_SetColorRed _api_FR.SetColorRed
269 #define FR_ColorGreen _api_FR.ColorGreen
270 #define FR_SetColorGreen _api_FR.SetColorGreen
271 #define FR_ColorBlue _api_FR.ColorBlue
272 #define FR_SetColorBlue _api_FR.SetColorBlue
273 #define FR_Alpha _api_FR.Alpha
274 #define FR_SetAlpha _api_FR.SetAlpha
275 #define FR_ShadowOffset _api_FR.ShadowOffset
276 #define FR_SetShadowOffset _api_FR.SetShadowOffset
277 #define FR_ShadowStrength _api_FR.ShadowStrength
278 #define FR_SetShadowStrength _api_FR.SetShadowStrength
279 #define FR_GlitterStrength _api_FR.GlitterStrength
280 #define FR_SetGlitterStrength _api_FR.SetGlitterStrength
281 #define FR_CaseScale _api_FR.CaseScale
282 #define FR_SetCaseScale _api_FR.SetCaseScale
283 #define FR_DrawText _api_FR.DrawText
284 #define FR_DrawText2 _api_FR.DrawText2
285 #define FR_DrawText3 _api_FR.DrawText3
286 #define FR_DrawTextXY3 _api_FR.DrawTextXY3
287 #define FR_DrawTextXY2 _api_FR.DrawTextXY2
288 #define FR_DrawTextXY _api_FR.DrawTextXY
289 #define FR_TextSize _api_FR.TextSize
290 #define FR_TextWidth _api_FR.TextWidth
291 #define FR_TextHeight _api_FR.TextHeight
292 #define FR_DrawChar3 _api_FR.DrawChar3
293 #define FR_DrawChar2 _api_FR.DrawChar2
294 #define FR_DrawChar _api_FR.DrawChar
295 #define FR_DrawCharXY3 _api_FR.DrawCharXY3
296 #define FR_DrawCharXY2 _api_FR.DrawCharXY2
297 #define FR_DrawCharXY _api_FR.DrawCharXY
298 #define FR_CharSize _api_FR.CharSize
299 #define FR_CharWidth _api_FR.CharWidth
300 #define FR_CharHeight _api_FR.CharHeight
301 #define FR_ResetTypeinTimer _api_FR.ResetTypeinTimer
302 #endif
303
304 #if defined __DOOMSDAY__ && defined __CLIENT__
305 DENG_USING_API(FR);
306 #endif
307
308 #ifdef __cplusplus
309 } // extern "C"
310 #endif
311
312 #endif /* LIBDENG_API_FONT_RENDERER_H */
313