1 /****************************************************************************************/
\r
4 /* Author: Thom Robertson */
\r
5 /* Description: Bitmapped font support interface */
\r
6 /* This implementation supports any TrueType fonts provided by Windows */
\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
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
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
22 /****************************************************************************************/
\r
27 #include "genesis.h"
\r
28 #include "basetype.h"
\r
30 // **************************
\r
33 // 2. geFont_CreateFont().
\r
35 // 3. (Optionally) geFont_AddCharacters().
\r
36 // 3A. Otherwise, IF you intend to use geFont_DrawText(), call geFont_AddBitmapBuffer().
\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
41 // 5. When finished, geFont_Destroy().
\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
59 // opaque structure headers.
\r
60 typedef struct geFont geFont; // an instance of a font
\r
63 //***************************************************************************************
\r
64 GENESISAPI geFont *GENESISCC geFont_Create(const geEngine *Engine, const char *fontNameString,
\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
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
75 // success: pointer to the newly created font.
\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
82 //***************************************************************************************
\r
83 GENESISAPI void GENESISCC geFont_CreateRef(geFont *font);
\r
86 //***************************************************************************************
\r
87 GENESISAPI void GENESISCC geFont_Destroy(geFont **font);
\r
91 // font - pointer to the font to be destroyed.
\r
96 //***************************************************************************************
\r
97 GENESISAPI geBoolean GENESISCC geFont_AddCharacters(geFont *font,
\r
98 unsigned char leastIndex,
\r
99 unsigned char mostIndex
\r
101 // Adds a set of characters to the font defined by the ascii range passed in
\r
102 // (leastIndex and mostIndex, inclusive).
\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
112 // success: GE_TRUE.
\r
113 // failure: GE_FALSE.
\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
121 //*******************************************************************************
\r
122 GENESISAPI void GENESISCC geFont_DestroyBitmapBuffer( geFont *font );
\r
123 // destroys any valid "scratch-pad" buffer attached to the geFont.
\r
125 // font - pointer to the geFont.
\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
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
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
145 // success: GE_TRUE.
\r
146 // failure: GE_FALSE.
\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
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
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
173 // success: GE_TRUE.
\r
174 // failure: GE_FALSE.
\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
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
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
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
209 // success: GE_TRUE.
\r
210 // failure: GE_FALSE.
\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
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
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
232 // font - pointer to the font to draw with.
\r
233 // textString - pointer to the text string to output to the screen.
\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
241 // these two functions assume no text wrapping!
\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
248 // font - pointer to the font.
\r
251 // a valid pointer to a geBitmap, OR NULL, signifying that the buffer wasn't initialized.
\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
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