# G l y p h Keeper Latest version: 0.30 (January 15, 2007) Home | Introduction | License | Screenshots | Files | Compiling | Manual | Reference | Examples | Future | Thanks | Links ## API Reference Structures Basic routines GLYPH_FACE routines GLYPH_KEEP routines GLYPH_REND routines Layout and rendering Allegro-specific routines ## Structures typedef struct GLYPH_FACE GLYPH_FACE structure represents a font face. Font face is a typographic term, it is used because single font may have several faces, like normal, bold, italic are different faces of the same font. A font file may contain several font faces, so here we will deal with an individual font face, rather than with the whole font. A new GLYPH_FACE object is created when you load a font face from file with gk_load_face_from_file() (or from memory buffer with gk_load_face_from_memory()). After loading a font face from file you can create a renderer (GLYPH_REND object) that will use it. Also you may introduce new font face to existing renderer with gk_rend_set_face(). When you don't need a font face anymore, you can dispose it with gk_unload_face(). A call to gk_library_cleanup() will dispose (among other things) all font faces currently loaded. typedef struct GLYPH_KEEP This structure represents a glyph cache object. It takes some time to render a character glyph, so it makes good sense to remember once rendered glyphs to print them faster later. GLYPH_KEEP object is created with gk_create_keeper(). Then you should connect it to one or more renderers (GLYPH_REND objects), otherwise it will be not used. One way to do it is to create a new renderer with gk_create_renderer(), providing GLYPH_KEEP* as a second parameter. Another way is to connect it to existing renderer with gk_rend_set_keeper(). A single GLYPH_KEEP object may work with several renderers at the same time. Even large program using many fonts may still have only one or two glyph caches. This makes easier to control and monitor cache size. GLYPH_KEEP object can be disposed with gk_done_keeper(). When you do this, all renderers that were using this cache will automatically switch to uncached mode. gk_library_cleanup() will also dispose all caches. typedef struct GLYPH_REND This structure keeps together all text rendering settings, like font face, size, color, angle and so on. Every text output with Glyph Keeper requires a GLYPH_REND object. A renderer (GLYPH_REND object) can be created with gk_create_renderer(). New renderer is immediately ready to use, as long as you provided valid font face when creating it. (If not, you can assign a font face later with gk_rend_set_face().) Default font size it 16 pixels, default rendering mode is antialiased hinted rendering, default color is 0x0000FF (blue), default transparency is 255 (opaque). Renderer can be disposed with gk_done_renderer(). gk_library_cleanup() will dispose all currently existing renderers. #define GLYPH_TARGET_SURFACE ... You will need to provide a pointer to GLYPH_TARGET_SURFACE to all Glyph Keeper routines that actually produce some text. GLYPH_TARGET_SURFACE is simply an alias for target-specific surface: BITMAP for Allegro, SDL_Surface for SDL and FILE for text only mode. ## Basic routines void gk_set_messenger ( void (*func)(const char* const msg) ); This function sets user-provided messenger function, which will handle Glyph Keeper's messages. Glyph Keeper routines will produce diagnostic or error messages for various matters. If no messenger function is provided, no text feedback or error messages will come out of Glyph Keeper. Set to 0 to 'unset' the messenger function. Although it is better to set messenger function once in the begining and keep it same through the program session, there is no any problem in changing messenger to another one, as many times as you like. void gk_set_font_path ( char* path ); Sets font search path - a list of directories where a font file will be searched when you load a font from file. 'path' can include several directories, separated by semicolon. All directories should include the final slash character. 'path' should be an ASCII string. After calling this function only reference to the 'path' will be kept by Glyph Keeper, the string itself is not copied. So, don't dispose the path string after setting. Also, every change you make to the path string will have immediate effect. void gk_library_init(); Glyph Keeper initialization. There is no need to call this function in your program - it will be called automatically when you load first font face, or create first keeper or renderer object. This function does several simple things: 1. It initializes FreeType. 2. Creates Glyph Keeper log file 'glyph.log' if GLYPH_LOG macro is defined. 3. Registers cleanup code gk_library_cleanup() with atexit(), if it was not registered yet. You can call this function, if you want to separate FreeType initialization from loading first font for some reason. void gk_library_cleanup(); Glyph Keeper shutdown function. Basically it does nothing more than complete cleanup. All data allocated by Glyph Keeper will be disposed: all objects of type GLYPH_FACE, GLYPH_KEEP and GLYPH_REND will be gone, all pointers to them will become invalid. FreeType library will be also dismissed. It is OK to call this function and later load some new font and start using Glyph Keeper again in the same program session. Just be careful not to use any old pointers after this call. Actually you are not required to call this function in your program. Glyph Keeper initialization will register this function with the atexit(), and it will be called in the end of your program anyway. There is no problem to call this function twice or any number of times. So, you can still call it at the end, if you like. Or if you want to control the order of things happening. int gk_bytes_allocated(); Returns amount of memory, allocated in heap by Glyph Keeper, in bytes. FreeType memory is not counted. (I don't know how to get this information from FreeType) (FIXME). If you call this function immediately after gk_library_cleanup() you should obtain 0. ## GLYPH_FACE routines GLYPH_FACE* gk_load_face_from_file ( char* fname, int face_index ); Loads font face from a file 'fname'. If there is no such file in the current directory, the font search path will be searched for this file. One file may contain several font faces, use 'face_index' to specify wich one to load. Use 'face_index' = 0 to load first font face, or if there is only one font face in the file. This function returns 0 on failure. Glyph Keeper currently only supports scalable fonts (TrueType, OpenType etc), that have Unicode character map. GLYPH_FACE* gk_load_face_from_memory ( unsigned char* data, int size, int face_index ); Loads font face from a memory buffer, pointed by 'data'. Returns a pointer to new GLYPH_FACE object if successful, returns 0 on failure. GLYPH_FACE object returned by this function does not contain copy of the 'data' contents, that data is used directly. So, you must not dispose the memory occupied by 'data' until you destroy the font face with gk_unload_face(), or better until you call gk_library_cleanup(). void gk_unload_face ( GLYPH_FACE* f ); You can manually dispose GLYPH_FACE object with this function. All renderers using is will automatically become unuseful until you set them to use another font face. All currently loaded font faces can be also disposed with gk_library_cleanup(). const char* gk_face_family ( GLYPH_FACE* f ); const char* gk_face_style ( GLYPH_FACE* f ); const char* gk_face_postscript_name ( GLYPH_FACE* f ); const char* gk_face_driver_name ( GLYPH_FACE* f ); These functions extract various information from font face. Don't free() the char* after using. int gk_face_is_horizontal ( GLYPH_FACE* f ); int gk_face_is_vertical ( GLYPH_FACE* f ); These functions check the directions supported by the font face. They can both return true for the same font face, if the font face contains both horisontal and vertical metrics. int gk_face_ascender ( GLYPH_FACE* f ); Vertical distance from the baseline to the topmost point of any glyph in the face. Positive, expressed in font units. int gk_face_descender ( GLYPH_FACE* f ); Vertical distance from the baseline to the bottommost point of any glyph in the face. Negative, expressed in font units. int gk_face_line_spacing ( GLYPH_FACE* f ); Vertical distance from one baseline to the next one when writing several lines of text. Always positive, expressed in font units. int gk_face_number_of_glyphs ( GLYPH_FACE* f ); Returns total number of glyphs in a font face. This is not necessarily the same with the number of characters this font face can render. int gk_face_has_character ( GLYPH_FACE* f, unsigned code ); Returns non-zero, if font face 'f' has character 'code', including remapped characters. Returns zero otherwise. int gk_face_has_own_character ( GLYPH_FACE* f, unsigned code ); Returns non-zero, if font face 'f' has its own definition of character 'code', without remapping. Returns zero otherwise. int gk_face_number_of_characters ( GLYPH_FACE* f ); Returns number of characters, that can be rendered with this font face. Remapped characters are also counted. On the other hand, if a character is disabled due to the remapping, it is not counted. int gk_face_number_of_own_characters ( GLYPH_FACE* f ); Returns number characters defined in this font face, without remapping. void gk_remap_character ( GLYPH_FACE* face1, unsigned code1, GLYPH_FACE* face2, unsigned code2 ); Remaps character 'code1' of 'face1' so that character 'code2' of 'face2' is used instead. This function has immediate effect, all renderers using 'face1' will start printing character code2 of face2 whenever they are asked to render character code1. Note, that character code1 does not have to be defined in face1 for remapping to work. If face1 has character code1, but face2 does not have character code2, remapping will be set anyway, disabling possibility of rendering character code1 of face1. "undefined character" will be used instead. If 'face2' is 0, remapping is removed for this character (code1 of face1). Original character of face1 will be used, or "undefined character" if it is not defined. Character remapping is discussed in detail in the manual. void gk_unmap_character ( GLYPH_FACE* face, unsigned code ); Removes any remapping assosiated with character 'code' of font face 'face'. Equivalent to gk_remap_character(face,code,0,0); void gk_remap_range ( GLYPH_FACE* face1, unsigned code1, GLYPH_FACE* face2, unsigned code2, unsigned range_size ); Remaps a whole range of characters. It is identical to for (i=0; i<range_size; i++) gk_remap_character(face1,code1+i,face2,code2+i); (Actually this is how it really works). void gk_unmap_range ( GLYPH_FACE* face, unsigned code, unsigned range_size ); Unmaps a range of characters, like this: for (i=0; i<range_size; i++) gk_unmap_character(face,code+i); ## GLYPH_KEEP routines GLYPH_KEEP* gk_create_keeper ( unsigned max_glyphs, unsigned max_memory ); Creates new GLYPH_KEEP object, limited to keep not more than 'max_glyphs' glyphs and to use not more than 'max_memory' bytes in memory. You can set 'max_glyphs' and/or 'max_memory' to 0 to have no limit. This function returns 0 on failure. void gk_done_keeper ( GLYPH_KEEP* keeper ); This function is useful to destroy GLYPH_KEEP object. Normally there is no particular need to call it - all GLYPH_KEEP objects will be automatically destroyed by gk_library_cleanup(). Note that you can safely destroy GLYPH_KEEP object, even if some renderer (GLYPH_REND object) is using it. Renderer will just switch to work without cache. But don't use in any way pointer to the destroyed keeper. int gk_keeper_glyph_count ( GLYPH_KEEP* keeper ); Returns number of glyphs currently cached by the keeper. int gk_keeper_glyph_limit ( GLYPH_KEEP* keeper ); Returns maximum number of glyphs a keeper can keep. int gk_keeper_byte_count ( GLYPH_KEEP* keeper ); Returns number of bytes used by a keeper. This includes GLYPH_KEEP structure, its indexes and all cached glyphs. int gk_keeper_byte_limit ( GLYPH_KEEP* keeper ); Returns maximum number of bytes this keeper may use in memory. void gk_keeper_debug ( GLYPH_KEEP* keeper ); Prints some information about keeper's current state. Printing goes through the messenger function. ## GLYPH_REND routines GLYPH_REND* gk_create_renderer ( GLYPH_FACE* face, GLYPH_KEEP* keeper ); Creates new renderer - GLYPH_REND object. Renderer is set to use font face 'face' and glyph cache 'keeper'. If 'keeper' is 0, renderer will still work fine, just without cache. Caching can be turned on later by introducing a keeper with gk_rend_set_keeper(). If 'face' is 0, renderer will be still created, but can't be used until some font face is specified with gk_rend_set_face(). FT_RENDER_MODE_NORMAL is the default rendering mode. '?' (U+003F) is the default undefined character. void gk_done_renderer ( GLYPH_REND* rend ); Deletes GLYPH_REND object from memory. Don't use in any way pointer to the destroyed renderer, it will crash your program. void gk_rend_set_keeper ( GLYPH_REND* rend, GLYPH_KEEP* new_keeper ); Assigns a glyph cache - GLYPH_KEEP object to this renderer. In fact one GLYPH_KEEP object can cache glyphs for several renderers at the same time. If 'new_keeper' is 0, glyph caching will be turned off for this renderer. void gk_rend_set_face ( GLYPH_REND* rend, GLYPH_FACE* new_face ); Assigns a new font face for this renderer. All rendered glyphs will be of that face. If 'new_face' is 0, the renderer will become unuseful - it can't render anything. int gk_rend_set_size_subpixel ( GLYPH_REND* rend, unsigned new_hsize, unsigned new_vsize ); Sets new character size for the renderer. New size is set in the way, that font's EM square dimensions become 'new_hsize' x 'new_vsize', in 1/64th of a pixel. Returns 1 on success, 0 on failure. I don't know why it may fail, but please check for return code anyway. int gk_rend_set_size_pixels ( GLYPH_REND* rend, unsigned new_pixel_hsize, unsigned new_pixel_vsize ); Similar to gk_rend_set_size_subpixel(), just takes new size arguments expressed in integer pixels. Returns 1 on success, 0 on failure. void gk_rend_set_angle ( GLYPH_REND* rend, double new_angle ); Sets new angle in radians. Renderer with angle set to M_PI/2, for example, will produce text going vertically upside. void gk_rend_set_italic ( GLYPH_REND* rend, int new_italic_angle ); Sets text obliquing angle, in degrees. Positive angles mean obliquing to the right, negative - to the left. Allowed angles are from -45 to 45. Use angle of 12 degrees to obtain a common italic text. void gk_rend_set_bold ( GLYPH_REND* rend, int new_bold_strength ); Sets text boldness to 'new_bold_strength', which must be non-negative. 0 means no additional boldness. 100 is about normal bold. int gk_rend_ascender ( GLYPH_REND* rend ); int gk_rend_ascender_pixels ( GLYPH_REND* rend ); int gk_rend_descender ( GLYPH_REND* rend ); int gk_rend_descender_pixels ( GLYPH_REND* rend ); These finctions return renderer's ascender and descender in 1/64th of a pixel. ..._pixels - version returns same thing in integer pixels. Ascender is (should be) the vertical distance from the baseline to the highest point of a character, rendered with this renderer. Descender is the vertical distance from the baseline to the lowest point of any character. Note, that ascender is positive, while descender is usually negative. int gk_rend_spacing ( GLYPH_REND* rend ); int gk_rend_spacing_pixels ( GLYPH_REND* rend ); Returns vertical distance between lines, in 1/64th of a pixel. Spacing returned by this function is not affected by renderer's angle setting. gk_rend_spacing_pixels() returns line spacing in integer pixels. Line spacing is usually larger than (ascender - descender). int gk_rend_height ( GLYPH_REND* rend ); int gk_rend_height_pixels ( GLYPH_REND* rend ); Returns 'text height' = ascender - descender. void gk_rend_set_hinting_off ( GLYPH_REND* rend ); void gk_rend_set_hinting_default ( GLYPH_REND* rend ); void gk_rend_set_hinting_force_autohint ( GLYPH_REND* rend ); void gk_rend_set_hinting_no_autohint ( GLYPH_REND* rend ); These functions control how this renderer will perform hinting. (to do: explain what hinting is) void gk_rend_set_antialiasing_on ( GLYPH_REND* rend ); void gk_rend_set_antialiasing_off ( GLYPH_REND* rend ); Turn antialiasing on/off for a renderer. By default it is on for all created renderers, you should switch it off if you don't need it. void gk_rend_set_undefined_char ( GLYPH_REND* rend, unsigned new_undefined_char ); You can specify which character will show up instead of the character, not present in font. Default character is '?', but with this function you can set it to anything. Setting it to 0 will prevent anything shown instead of undefined characters. void gk_rend_set_error_char ( GLYPH_REND* rend, unsigned new_error_char ); Sometimes the character glyph is defined in font face, but some error happens when trying to render it. In such case the 'error_char' will appear instead of the failed character. Default 'error_char' is 0, which means nothing is shown instead of failed characters. int gk_rend_has_character ( GLYPH_REND* rend, unsigned code ); Returns 1, if renderer can render a glyph for character 'code', otherwise returns 0. int gk_rend_has_glyph ( GLYPH_REND* rend, unsigned code ); Returns 1, if renderer can render a non-empty glyph for character 'code', otherwise returns 0. Empty glyphs usually represent space characters, but are also abundant in some broken fonts. void gk_rend_set_text_color ( GLYPH_REND* rend, unsigned char r, unsigned char g, unsigned char b ); This routine will set text color. With Glyph Keeper you don't have to provide text color for each text output operation, instead you set it once in renderer and all newly rendered text will have this color automatically. Color is specified in platform/gfx.mode independent way - 'r', 'g' and 'b' are in 0..255 range. When a new renderer is created, it has blue text color by default. You can always revert to the default color by calling rend_set_text_color(rend,0,0,255); void gk_rend_set_text_alpha ( GLYPH_REND* rend, unsigned char alpha ); unsigned gk_rend_get_text_alpha ( GLYPH_REND* rend ); Setting and querying renderer's alpha transparency, always from 0 to 255. This setting affect only text transparency, background rectangle is not transparent. With alpha = 0 no text will appear at all, with alpha = 255 opaque text will be rendered. If you are rendering text with background rectangle, the background rectangle will be drawn even if the text alpha is 0. void gk_rend_set_text_alpha_color ( GLYPH_REND* rend, unsigned alpha_color ); unsigned gk_rend_get_text_alpha_color ( GLYPH_REND* rend ); Setting and querying text alpha transparency and color together. 'alpha_color' is in AARRGGBB format: (A<<24)+(R<<16)+(G<<8)+B. A, R, G and B are in 0..255 range. void gk_rend_set_back_color ( GLYPH_REND* rend, int new_back_color ); int gk_rend_get_back_color ( GLYPH_REND* rend ); Setting and querying the background color, in 24-bit RRGGBB format ( (R<<16)|(G<<8)|B, 0 <= R G B <= 255 ). void gk_rend_debug ( GLYPH_REND* rend ); Prints out renderer's settings via the messenger function. ## Layout and rendering int gk_char_width ( GLYPH_REND* rend, unsigned unicode ); int gk_text_width_utf8 ( GLYPH_REND* rend, char* text ); int gk_text_width_utf16 ( GLYPH_REND* rend, unsigned short* text ); int gk_text_width_utf32 ( GLYPH_REND* rend, unsigned* text ); These functions return width of text produced by renderer 'rend', in pixels. For angled text the width is not just length of a rendered string, but its horizontal width - it is smaller for angled string than for the same string printed horizontally. (Text angle is specified in the renderer object 'rend') int gk_char_height ( GLYPH_REND* rend, unsigned unicode ); int gk_text_height_utf8 ( GLYPH_REND* rend, char* text ); int gk_text_height_utf16 ( GLYPH_REND* rend, unsigned short* text ); int gk_text_height_utf32 ( GLYPH_REND* rend, unsigned* text ); These functions return text height in pixels. For horizontal text height taken from the renderer structure and returned immediately, but for angled text all the height is calculated by rendering all glyphs one by one and accumulating their vertical advance. void gk_char_size ( GLYPH_REND* rend, unsigned unicode, int* width, int* height ); void gk_text_size_utf8 ( GLYPH_REND* rend, char* text, int* width, int* height ); void gk_text_size_utf16 ( GLYPH_REND* rend, unsigned short* text, int* width, int* height ); void gk_text_size_utf32 ( GLYPH_REND* rend, unsigned* text, int* width, int* height ); These functions obtain both width and height of text, in pixels, and write them to '*width' and '*height'. It is faster to call one of these functions than obtaining text width and height separately. void gk_char_advance ( GLYPH_REND* rend, unsigned unicode, int* adv_x, int* adv_y ); void gk_text_advance_utf8 ( GLYPH_REND* rend, char* text, int* x_adv, int* y_adv ); void gk_text_advance_utf16 ( GLYPH_REND* rend, unsigned short* text, int* x_adv, int* y_adv ); void gk_text_advance_utf32 ( GLYPH_REND* rend, unsigned* text, int* x_adv, int* y_adv ); These functions calculate text advance (in pixels) and writes it to '*x_adv' and '*y_adv'. Advance is horizontal and vertical shift applied to the pen position, when the text is rendered along the baseline. See the picture: void gk_char_advance_subpixel ( GLYPH_REND* rend, unsigned unicode, int* adv_x, int* adv_y ); void gk_text_advance_subpixel_utf8 ( GLYPH_REND* rend, char* text, int* x_adv, int* y_adv ); void gk_text_advance_subpixel_utf16 ( GLYPH_REND* rend, unsigned short* text, int* x_adv, int* y_adv ); void gk_text_advance_subpixel_utf32 ( GLYPH_REND* rend, unsigned* text, int* x_adv, int* y_adv ); Text advance is returned in 1/64th of a pixel. void gk_glyph_size ( GLYPH_REND* rend, unsigned unicode, int* width, int* height ); int gk_glyph_width ( GLYPH_REND* rend, unsigned unicode ); int gk_glyph_height ( GLYPH_REND* rend, unsigned unicode ); These functions measure a single glyph. void gk_precache_char ( GLYPH_REND* rend, unsigned unicode ); void gk_precache_range ( GLYPH_REND* rend, unsigned range_start, unsigned range_end ); void gk_precache_set_utf8 ( GLYPH_REND* rend, char* char_set ); void gk_precache_set_utf16 ( GLYPH_REND* rend, unsigned short* char_set ); void gk_precache_set_utf32 ( GLYPH_REND* rend, unsigned* char_set ); These functions perform precaching - rendering character glyph and putting it into the cache for later usage. Precaching should be used to prepare glyphs that you expect to be used soon. Glyphs that are already in the cache are not rendered again, just moved to the head of cache's MRU-ordered glyph list. If the renderer does not have cache this functions have no effect. gk_precache_char() precaches one character glyph. gk_precache_range() precaches continuous range of characters. gk_precache_set_utf8() precaches a set of characters, passed in a 0-terminated UTF-8 string. gk_precache_set_utf16() and gk_precache_set_utf32() do same thing taking character set in UTF-16 and UTF-32. Also see the manual. void gk_put_char ( GLYPH_TARGET_SURFACE* bmp, GLYPH_REND* rend, unsigned unicode, int x, int y ); Prints a unicode character to the surface 'bmp', using renderer 'rend'. Character glyph is positioned so that its left top corner will appear at (x,y). This is rather low-level function, it is not useful for rendering a line of text, because characters have varying height and also because this function doesn't respect character glyph's bearing and advance values. Also, this function never draws background rectangle. void gk_put_char_center ( GLYPH_TARGET_SURFACE* bmp, GLYPH_REND* rend, unsigned unicode, int x, int y ); Similar to gk_put_char(), the only difference is that the character glyph is printed out centered at (x,y). void gk_render_char ( GLYPH_TARGET_SURFACE* bmp, GLYPH_REND* rend, unsigned unicode, int* pen_x, int* pen_y ); Renders one character, starting with positioning pen at text origin point (*pen_x,*pen_y). *pen_x and *pen_y coordinates are expressed in 1/64th of a pixel. *pen_x and *pen_y will be incremented to become starting pen position for the next character. Also see the manual. void gk_render_line_utf8 ( GLYPH_TARGET_SURFACE* bmp, GLYPH_REND* rend, char* text, int pen_x, int pen_y ); void gk_render_line_utf16 ( GLYPH_TARGET_SURFACE* bmp, GLYPH_REND* rend, unsigned short* text, int pen_x, int pen_y ); void gk_render_line_utf32 ( GLYPH_TARGET_SURFACE* bmp, GLYPH_REND* rend, unsigned* text, int pen_x, int pen_y ); Render one line of text. Text must be null-terminated string in one of the UTF encodings. The byte order mark (BOM) is supported for UTF-16 and UTF-32 text, so you can render text you recieve from network without caring about endianness. ## Allegro-specific routines FONT* gk_create_allegro_font ( GLYPH_REND* r ); This function creates a FONT object, corresponding the the renderer 'r'. (FONT is structure defined by Allegro for its built-in text rendering.) Returns pointer to created FONT structure or 0 on failure. Created FONT object can be used with any of Allegro functions and is supposed to produce text, with the font face, size, hinting, antialiasing and all other settings of the renderer 'r'. Please see the manual section for more details. Please note that the FONT structure does not contain copy of renderer's data, it simply refers to the renderer. Don't dispose the renderer, if you are still going to use the FONT object made from it.