1/*
2libdrawtext - a simple library for fast text rendering in OpenGL
3Copyright (C) 2011-2014 John Tsiombikas <nuclear@member.fsf.org>
4
5This program is free software: you can redistribute it and/or modify
6it under the terms of the GNU Lesser General Public License as published by
7the Free Software Foundation, either version 3 of the License, or
8(at your option) any later version.
9
10This program is distributed in the hope that it will be useful,
11but WITHOUT ANY WARRANTY; without even the implied warranty of
12MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13GNU Lesser General Public License for more details.
14
15You should have received a copy of the GNU Lesser General Public License
16along with this program. If not, see <http://www.gnu.org/licenses/>.
17*/
18#pragma once
19
20#include <stdio.h>
21#include <stdlib.h>
22
23struct dtx_font;
24struct dtx_glyphmap;
25
26/* draw buffering modes */
27enum {
28 DTX_NBF, /* unbuffered */
29 DTX_LBF, /* line buffered */
30 DTX_FBF /* fully buffered */
31};
32
33struct dtx_box {
34 float x, y;
35 float width, height;
36};
37
38#ifdef __cplusplus
39extern "C" {
40#endif
41
42/* Open a truetype/opentype/whatever font.
43 *
44 * If sz is non-zero, the default ASCII glyphmap at the requested point size is
45 * automatically created as well, and ready to use.
46 *
47 * To use other unicode ranges and different font sizes you must first call
48 * dtx_prepare or dtx_prepare_range before issuing any drawing calls, otherwise
49 * nothing will be rendered.
50 */
51struct dtx_font *dtx_open_font(const char *fname, int sz);
52/* open a font by loading a precompiled glyphmap (see: dtx_save_glyphmap)
53 * this works even when compiled without freetype support
54 */
55struct dtx_font *dtx_open_font_glyphmap(const char *fname);
56/* close a font opened by either of the above */
57void dtx_close_font(struct dtx_font *fnt);
58
59/* prepare an ASCII glyphmap for the specified font size */
60void dtx_prepare(struct dtx_font *fnt, int sz);
61/* prepare an arbitrary unicode range glyphmap for the specified font size */
62void dtx_prepare_range(struct dtx_font *fnt, int sz, int cstart, int cend);
63
64/* Finds the glyphmap that contains the specified character code and matches the requested size
65 * Returns null if it hasn't been created (you should call dtx_prepare/dtx_prepare_range).
66 */
67struct dtx_glyphmap *dtx_get_font_glyphmap(struct dtx_font *fnt, int sz, int code);
68
69/* Finds the glyphmap that contains the specified unicode range and matches the requested font size
70 * Will automatically generate one if it can't find it.
71 */
72struct dtx_glyphmap *dtx_get_font_glyphmap_range(struct dtx_font *fnt, int sz, int cstart, int cend);
73
74/* Creates and returns a glyphmap for a particular unicode range and font size.
75 * The generated glyphmap is added to the font's list of glyphmaps.
76 */
77struct dtx_glyphmap *dtx_create_glyphmap_range(struct dtx_font *fnt, int sz, int cstart, int cend);
78/* free a glyphmap */
79void dtx_free_glyphmap(struct dtx_glyphmap *gmap);
80
81/* returns a pointer to the raster image of a glyphmap (1 byte per pixel grayscale) */
82unsigned char *dtx_get_glyphmap_image(struct dtx_glyphmap *gmap);
83/* returns the width of the glyphmap image in pixels */
84int dtx_get_glyphmap_width(struct dtx_glyphmap *gmap);
85/* returns the height of the glyphmap image in pixels */
86int dtx_get_glyphmap_height(struct dtx_glyphmap *gmap);
87
88/* The following functions can be used even when the library is compiled without
89 * freetype support.
90 */
91struct dtx_glyphmap *dtx_load_glyphmap(const char *fname);
92struct dtx_glyphmap *dtx_load_glyphmap_stream(FILE *fp);
93int dtx_save_glyphmap(const char *fname, const struct dtx_glyphmap *gmap);
94int dtx_save_glyphmap_stream(FILE *fp, const struct dtx_glyphmap *gmap);
95
96/* adds a glyphmap to a font */
97void dtx_add_glyphmap(struct dtx_font *fnt, struct dtx_glyphmap *gmap);
98
99/* ---- rendering ---- */
100
101/* sets whether or not to use linear interpolation for the glyph textures */
102void dtx_use_interpolation(int interpolation);
103
104/* before drawing anything this function must set the font to use */
105void dtx_use_font(struct dtx_font *fnt, int sz);
106
107/* sets the buffering mode
108 * - DTX_NBUF: every call to dtx_string gets rendered immediately.
109 * - DTX_LBUF: renders when the buffer is full or the string contains a newline.
110 * - DTX_FBUF: renders only when the buffer is full (you must call dtx_flush explicitly).
111 */
112void dtx_draw_buffering(int mode);
113
114/* Sets the vertex attribute indices to use for passing vertex and texture coordinate
115 * data. By default both are -1 which means you don't have to use a shader, and if you
116 * do they are accessible through gl_Vertex and gl_MultiTexCoord0, as usual.
117 *
118 * NOTE: If you are using OpenGL ES 2.x or OpenGL >= 3.1 pure (non-compatibility) context
119 * you must specify valid attribute indices.
120 */
121void dtx_vertex_attribs(int vert_attr, int tex_attr);
122
123/* draws a single glyph at the origin */
124void dtx_glyph(int code);
125/* draws a utf-8 string starting at the origin. \n \r and \t are handled appropriately. */
126void dtx_string(const char *str);
127
128void dtx_printf(const char *fmt, ...);
129
130void dtx_prepare_string(const char *str);
131float dtx_get_prepared_width();
132float dtx_get_prepared_height();
133void dtx_render_prepared();
134
135/* render any pending glyphs (see dtx_draw_buffering) */
136void dtx_flush(void);
137void dtx_render();
138
139
140/* ---- encodings ---- */
141
142/* returns a pointer to the next character in a utf-8 stream */
143char *dtx_utf8_next_char(char *str);
144
145/* returns the unicode character codepoint of the utf-8 character starting at str */
146int dtx_utf8_char_code(const char *str);
147
148/* returns the number of bytes of the utf-8 character starting at str */
149int dtx_utf8_nbytes(const char *str);
150
151/* returns the number of utf-8 character in a zero-terminated utf-8 string */
152int dtx_utf8_char_count(const char *str);
153
154/* Converts a unicode code-point to a utf-8 character by filling in the buffer
155 * passed at the second argument, and returns the number of bytes taken by that
156 * utf-8 character.
157 * It's valid to pass a null buffer pointer, in which case only the byte count is
158 * returned (useful to figure out how much memory to allocate for a buffer).
159 */
160size_t dtx_utf8_from_char_code(int code, char *buf);
161
162/* Converts a unicode utf-16 wchar_t string to utf-8, filling in the buffer passed
163 * at the second argument. Returns the size of the resulting string in bytes.
164 *
165 * It's valid to pass a null buffer pointer, in which case only the size gets
166 * calculated and returned, which is useful for figuring out how much memory to
167 * allocate for the utf-8 buffer.
168 */
169size_t dtx_utf8_from_string(const wchar_t *str, char *buf);
170
171
172/* ---- metrics ---- */
173float dtx_line_height(void);
174
175/* rendered dimensions of a single glyph */
176void dtx_glyph_box(int code, struct dtx_box *box);
177float dtx_glyph_width(int code);
178float dtx_glyph_height(int code);
179
180/* rendered dimensions of a string */
181void dtx_string_box(const char *str, struct dtx_box *box);
182float dtx_string_width(const char *str);
183float dtx_string_height(const char *str);
184
185/* returns the horizontal position of the n-th character of the rendered string
186 * (useful for placing cursors)
187 */
188float dtx_char_pos(const char *str, int n);
189
190int dtx_char_at_pt(const char *str, float pt);
191
192/* initialization and cleanup functions */
193int dtx_gl_init(void);
194void dtx_gl_kill(void);
195
196#ifdef __cplusplus
197}
198#endif
199