- removed Visual Studio junk
[genesis3d.git] / include / font.H
1 /****************************************************************************************/\r
2 /*  FONT.H                                                                              */\r
3 /*                                                                                      */\r
4 /*  Author: Thom Robertson                                                              */\r
5 /*  Description: Bitmapped font support interface                                       */\r
6 /*               This implementation supports any TrueType fonts provided by Windows    */\r
7 /*                                                                                      */\r
8 /*  The contents of this file are subject to the Genesis3D Public License               */\r
9 /*  Version 1.01 (the "License"); you may not use this file except in                   */\r
10 /*  compliance with the License. You may obtain a copy of the License at                */\r
11 /*  http://www.genesis3d.com                                                            */\r
12 /*                                                                                      */\r
13 /*  Software distributed under the License is distributed on an "AS IS"                 */\r
14 /*  basis, WITHOUT WARRANTY OF ANY KIND, either express or implied.  See                */\r
15 /*  the License for the specific language governing rights and limitations              */\r
16 /*  under the License.                                                                  */\r
17 /*                                                                                      */\r
18 /*  The Original Code is Genesis3D, released March 25, 1999.                            */\r
19 /*  Genesis3D Version 1.1 released November 15, 1999                                 */\r
20 /*  Copyright (C) 1999 WildTangent, Inc. All Rights Reserved           */\r
21 /*                                                                                      */\r
22 /****************************************************************************************/\r
23 #ifndef GE_FONT_H\r
24 #define GE_FONT_H\r
25 \r
26 // includes\r
27 #include "genesis.h"\r
28 #include "basetype.h"\r
29 #include "bitmap.h"\r
30 // **************************\r
31 // to use this API:\r
32 \r
33 // 2.  geFont_CreateFont().\r
34 \r
35 // 3.  (Optionally) geFont_AddCharacters().\r
36 // 3A. Otherwise, IF you intend to use geFont_DrawText(), call geFont_AddBitmapBuffer().\r
37 \r
38 // 4.  Between geEngine_BeginFrame() and geEngine_EndFrame(), and after geEngine_RenderWorld(),\r
39 //       geFont_DrawText(). You may call geFont_DrawTextToBitmap() anytime, though.\r
40 \r
41 // 5.  When finished, geFont_Destroy().\r
42 \r
43 \r
44 \r
45 //*************************************************************************************** \r
46 // these are bit flags for _DrawText(). Currently only _WORDWRAP is implemented, and without\r
47 // it, the function will still wrap, just not on word boundaries.\r
48 // Note that these will fail for non ascii fonts.\r
49 #define GE_FONT_WRAP                0x00000001  // wrap to fit inside the drawing rect\r
50 #define GE_FONT_WORDWRAP            0x00000002  // wrap on word boundaries\r
51 #define GE_FONT_JUST_RETURN_FIT     0x00000004  // returns number of characters that fit in drawing rectangle, WITHOUT drawing anything.\r
52 #define GE_FONT_JUSTIFY_RIGHT       0x00000008\r
53 #define GE_FONT_JUSTIFY_CENTER      0x00000010\r
54 \r
55 #ifdef __cplusplus\r
56 extern "C" {\r
57 #endif\r
58 \r
59 // opaque structure headers.\r
60 typedef struct geFont geFont;                   // an instance of a font\r
61 \r
62 \r
63 //*************************************************************************************** \r
64 GENESISAPI geFont *GENESISCC geFont_Create(const geEngine *Engine, const char *fontNameString, \r
65                                                const int fontSize,\r
66                                                                                            const int fontWeight , const geBoolean antialiased) ;\r
67    // Creates a font, and returns a pointer to it.\r
68    // Pass in the string name of the TrueType font (case sensitive), and the height in pixels.\r
69    \r
70    // ARGUMENTS:\r
71    // fontNameString - char pointer to a string containing the case sensitive name of the font.\r
72    // fontSize - the pixel height of the requested font.\r
73 \r
74    // RETURNS:\r
75    // success: pointer to the newly created font.\r
76    // failure: NULL.\r
77 \r
78    // NOTE: the new font set has NO actual characters in it at first.  You must add characters\r
79    // to it with the _AddCharacters() function before you can use the font.\r
80    // NOTE: all fonts start out with a grayscale palette, with the range 0 to 128.\r
81 \r
82 //*************************************************************************************** \r
83 GENESISAPI void GENESISCC geFont_CreateRef(geFont *font);\r
84 \r
85 \r
86 //*************************************************************************************** \r
87 GENESISAPI void GENESISCC geFont_Destroy(geFont **font);\r
88    // destroys a font.\r
89 \r
90    // ARGUMENTS:\r
91    // font - pointer to the font to be destroyed.\r
92 \r
93    // RETURNS:\r
94    // nothing.\r
95 \r
96 //*************************************************************************************** \r
97 GENESISAPI geBoolean GENESISCC geFont_AddCharacters(geFont *font, \r
98                                                   unsigned char leastIndex, \r
99                                                   unsigned char mostIndex\r
100                                                   );\r
101    // Adds a set of characters to the font defined by the ascii range passed in \r
102    // (leastIndex and mostIndex, inclusive).\r
103 \r
104    // ARGUMENTS:\r
105    // font - pointer to the font to add characters to.\r
106    // e - pointer to a valid geEngine.\r
107    // leastIndex and mostIndex - the ASCII range of characters to add.\r
108    // cellBuffer - an allocated hunk of ram to temproarily store the character image\r
109    // bufferSize - length of the above buffer\r
110 \r
111    // RETURNS:\r
112    // success: GE_TRUE.\r
113    // failure: GE_FALSE.\r
114 \r
115    // NOTES:\r
116    // This is the function that actually uses the\r
117    // Win32 GetGlyphOutline() function to draw the character onto a geBitmap, which can be\r
118    // blitted to the screen.\r
119 \r
120 \r
121 //*******************************************************************************\r
122 GENESISAPI void GENESISCC geFont_DestroyBitmapBuffer( geFont *font );\r
123    // destroys any valid "scratch-pad" buffer attached to the geFont.\r
124    // ARGUMENTS:\r
125    // font - pointer to the geFont.\r
126    //\r
127    // NOTES:\r
128    // you'll rarely need to call this function; it's called by geFont_Destroy() anyway.\r
129    // Calling this function with a geFont that has no initialized buffer doesn't\r
130    // hurt anything.\r
131 \r
132 //*******************************************************************************\r
133 GENESISAPI geBoolean GENESISCC geFont_AddBitmapBuffer(\r
134                                   geFont *font, const uint32 width, const uint32 height);\r
135    // Adds a geBitmap to the geFont, to be used as a temporary "scratch-pad".  This is\r
136    // required for using geFont_DrawText() when no characters have been added.\r
137 \r
138    // ARGUMENTS:\r
139    // font - pointer to the geFont to add a buffer to.\r
140    // width and height - the size of the buffer to create.  Make sure this size is >=\r
141    // the biggest rectagle of text you'll want to write to the screen using this geFont\r
142    // and DrawText().\r
143 \r
144    // RETURNS:\r
145    // success: GE_TRUE.\r
146    // failure: GE_FALSE.\r
147 \r
148    // NOTES:\r
149    // You don't need to call this function IF you _AddCharacters() to this geFont.\r
150    // You call this function for each geFont you need to use.  geFont's don't share buffers.\r
151    // if you call this function on a geFont that already has a valid buffer, the buffer is\r
152    // destroyed, and replaced by the new one.\r
153 \r
154 //*************************************************************************************** \r
155 GENESISAPI geBoolean GENESISCC geFont_DrawText(geFont *font, const char *textString, \r
156                                            const GE_Rect *Rect, const GE_RGBA *Color, \r
157                                            uint32 flags, const GE_Rect *clipRect);\r
158    // This is the function you put between geEngine_BeginFrame() and _EndFrame(), the function\r
159    // that draws text to the screen.\r
160 \r
161    // ARGUMENTS:\r
162    // font - pointer to the font to draw with.  IF the font has NO characters in it\r
163    //  (added by geFont_AddCharacters() ) then a different, more windows-intensive way is\r
164    //  used to draw out the characters.\r
165    // textString - pointer to the text string to output to the screen.\r
166    // Rect - screen rectangle to place the text within.\r
167    // Color - RGB color the text should be.\r
168    // flags - a bitfield of GE_FONT_ values.\r
169    // clipRect - pointer to a screen rectangle to clip the text to.  MAY BE NULL, in which\r
170    // case the text is only clipped by the boundaries of the screen.\r
171 \r
172    // RETURNS:\r
173    // success: GE_TRUE.\r
174    // failure: GE_FALSE.\r
175 \r
176    // NOTES:\r
177    // Assuming you've added characters to the font, characters which have NOT been added\r
178    // WILL cause an assert if you try to draw them.  \r
179    // Only GE_FONTSET_WORDWRAP is meaningfull right now.  Using any other flags will cause\r
180    // an assert.\r
181    // As stated above, you can use an entirely different way of creating a string, by\r
182    // making a font with no characters in it.  This\r
183    // jumps through Windows DIB hoops, and draws the text in a non-anti-aliased, but\r
184    // (hopefully) more unicode-tolerant way (DrawText() ).\r
185 \r
186 \r
187 //*************************************************************************************** \r
188 GENESISAPI geBoolean GENESISCC geFont_DrawTextToBitmap(geFont *font, const char *textString, \r
189                                            const GE_Rect *Rect, const GE_RGBA *Color, \r
190                                            uint32 flags, const GE_Rect *clipRect,\r
191                                            geBitmap *targetBitmap);\r
192    // This is the function you put between geEngine_BeginFrame() and _EndFrame(), the function\r
193    // that draws text to the screen.\r
194 \r
195    // ARGUMENTS:\r
196    // font - pointer to the font to draw with.  IF the font has NO characters in it\r
197    //  (added by geFont_AddCharacters() ) then a different, more windows-intensive way is\r
198    //  used to draw out the characters.\r
199    // textString - pointer to the text string to output to the screen.\r
200    // Rect - screen rectangle to place the text within.\r
201    // Color - RGB color the text should be.\r
202    // flags - a bitfield of GE_FONT_ values.\r
203    // clipRect - pointer to a screen rectangle to clip the text to.  MAY BE NULL, in which\r
204    // case the text is only clipped by the boundaries of the screen.\r
205    // targetBitmap - pointer to a target bitmap to draw the text into.  MAY NOT BE NULL,\r
206    // and MUST BE GE_PIXELFORMAT_8BIT.\r
207 \r
208    // RETURNS:\r
209    // success: GE_TRUE.\r
210    // failure: GE_FALSE.\r
211 \r
212    // NOTES:\r
213    // Assuming you've added characters to the font, characters which have NOT been added\r
214    // WILL cause an assert if you try to draw them.  \r
215    // Only GE_FONTSET_WORDWRAP is meaningfull right now.  Using any other flags will cause\r
216    // an assert.\r
217    // As stated above, you can use an entirely different way of creating a string, by\r
218    // making a font with no characters in it.  This\r
219    // jumps through Windows DIB hoops, and draws the text in a non-anti-aliased, but\r
220    // (hopefully) more unicode-tolerant way (DrawText() ).\r
221    // The Color argument is will be used to modify the existing palette of the targetBitmap\r
222    // passed in.  Therefore, you won't be able to _DrawTextToBitmap() a red piece of text,\r
223    // then a green piece, then a blue piece.  You'll end up with three lines of blue text.\r
224 \r
225 \r
226 //*************************************************************************************** \r
227 GENESISAPI int32 GENESISCC geFont_GetStringPixelWidth (geFont *font, const char *textString);\r
228 GENESISAPI int32 GENESISCC geFont_GetStringPixelHeight(geFont *font, const char *textString);\r
229    // These two functions return the pixel width and height of the string passed in.\r
230 \r
231    // ARGUMENTS:\r
232    // font - pointer to the font to draw with.\r
233    // textString - pointer to the text string to output to the screen.\r
234 \r
235    // RETURNS:\r
236    // success: a positive value in pixels.  IF the text passed in contains characters\r
237    //          which haven't been added to the font yet, BUT other characters HAVE\r
238    //          been added, the function asserts.\r
239    // failure: -1.\r
240    // NOTES:\r
241    // these two functions assume no text wrapping!\r
242 \r
243 //*************************************************************************************** \r
244 GENESISAPI geBitmap* GENESISCC geFont_GetBuffer(geFont *font);\r
245    // This function returns a pointer to the drawing buffer contained by the font.\r
246 \r
247    // ARGUMENTS:\r
248    // font - pointer to the font.\r
249 \r
250    // RETURNS:\r
251    // a valid pointer to a geBitmap, OR NULL, signifying that the buffer wasn't initialized.\r
252 \r
253 \r
254 //*************************************************************************************** \r
255 GENESISAPI geBoolean GENESISCC geFont_GetCharMap(geFont *font, uint8 character, GE_Rect *Rect, \r
256                                                                                                  geBitmap **targetBitmap, int32 *fullWidth, int32 *fullHeight, \r
257                                                                                                  int32 *offsetX, int32 *offsetY);\r
258 \r
259 //*************************************************************************************** \r
260 GENESISAPI void GENESISCC geFont_EnableAntialiasing(geFont *font, const geBoolean anti);\r
261 //*************************************************************************************** \r
262 GENESISAPI geBoolean GENESISCC geFont_IsAntialiased(geFont *font);\r
263 \r
264 #ifdef __cplusplus\r
265 }\r
266 #endif\r
267 \r
268 #endif\r
269 \r