git.mutantstargoat.com Git - raydungeon/blob - libs/drawtext/drawtext.h

   1 /*
   2 libdrawtext - a simple library for fast text rendering in OpenGL
   3 Copyright (C) 2011-2019  John Tsiombikas <nuclear@member.fsf.org>
   4
   5 This program is free software: you can redistribute it and/or modify
   6 it under the terms of the GNU Lesser General Public License as published by
   7 the Free Software Foundation, either version 3 of the License, or
   8 (at your option) any later version.
   9
  10 This program is distributed in the hope that it will be useful,
  11 but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 GNU Lesser General Public License for more details.
  14
  15 You should have received a copy of the GNU Lesser General Public License
  16 along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17 */
  18 #ifndef LIBDRAWTEXT_H_
  19 #define LIBDRAWTEXT_H_
  20
  21 #include <stdio.h>
  22 #include <stdlib.h>
  23
  24 struct dtx_font;
  25 struct dtx_glyphmap;
  26
  27 /* draw buffering modes */
  28 enum {
  29         DTX_NBF = 0,/* unbuffered */
  30         DTX_LBF,        /* line buffered */
  31         DTX_FBF         /* fully buffered */
  32 };
  33
  34 /* glyphmap resize filtering */
  35 enum {
  36         DTX_NEAREST,
  37         DTX_LINEAR
  38 };
  39
  40 struct dtx_box {
  41         float x, y;
  42         float width, height;
  43 };
  44
  45 #ifdef __cplusplus
  46 extern "C" {
  47 #endif
  48
  49 /* Open a truetype/opentype/whatever font.
  50  *
  51  * If sz is non-zero, the default ASCII glyphmap at the requested point size is
  52  * automatically created as well, and ready to use.
  53  *
  54  * To use other unicode ranges and different font sizes you must first call
  55  * dtx_prepare or dtx_prepare_range before issuing any drawing calls, otherwise
  56  * nothing will be rendered.
  57  */
  58 struct dtx_font *dtx_open_font(const char *fname, int sz);
  59 /* same as dtx_open_font, but open from a memory buffer instead of a file */
  60 struct dtx_font *dtx_open_font_mem(void *ptr, int memsz, int fontsz);
  61 /* open a font by loading a precompiled glyphmap (see: dtx_save_glyphmap)
  62  * this works even when compiled without freetype support
  63  */
  64 struct dtx_font *dtx_open_font_glyphmap(const char *fname);
  65 /* same as dtx_open_font_glyphmap, but open from a memory buffer instead of a file */
  66 struct dtx_font *dtx_open_font_glyphmap_mem(void *ptr, int memsz);
  67 /* close a font opened by either of the above */
  68 void dtx_close_font(struct dtx_font *fnt);
  69
  70 /* prepare an ASCII glyphmap for the specified font size */
  71 void dtx_prepare(struct dtx_font *fnt, int sz);
  72 /* prepare an arbitrary unicode range glyphmap for the specified font size */
  73 void dtx_prepare_range(struct dtx_font *fnt, int sz, int cstart, int cend);
  74
  75 /* convert all glyphmaps to distance fields for use with the distance field
  76  * font rendering algorithm. This is a convenience function which calls
  77  * dtx_calc_glyphmap_distfield and
  78  * dtx_resize_glyphmap(..., scale_numer, scale_denom, DTX_LINEAR) for each
  79  * glyphmap in this font.
  80  */
  81 int dtx_calc_font_distfield(struct dtx_font *fnt, int scale_numer, int scale_denom);
  82
  83 /* Finds the glyphmap that contains the specified character code and matches the requested size
  84  * Returns null if it hasn't been created (you should call dtx_prepare/dtx_prepare_range).
  85  */
  86 struct dtx_glyphmap *dtx_get_font_glyphmap(struct dtx_font *fnt, int sz, int code);
  87
  88 /* Finds the glyphmap that contains the specified unicode range and matches the requested font size
  89  * Will automatically generate one if it can't find it.
  90  */
  91 struct dtx_glyphmap *dtx_get_font_glyphmap_range(struct dtx_font *fnt, int sz, int cstart, int cend);
  92
  93 /* returns the number of glyphmaps in this font */
  94 int dtx_get_num_glyphmaps(struct dtx_font *fnt);
  95 /* returns the Nth glyphmap of this font */
  96 struct dtx_glyphmap *dtx_get_glyphmap(struct dtx_font *fnt, int idx);
  97
  98 /* Creates and returns a glyphmap for a particular unicode range and font size.
  99  * The generated glyphmap is added to the font's list of glyphmaps.
 100  */
 101 struct dtx_glyphmap *dtx_create_glyphmap_range(struct dtx_font *fnt, int sz, int cstart, int cend);
 102 /* free a glyphmap */
 103 void dtx_free_glyphmap(struct dtx_glyphmap *gmap);
 104
 105 /* converts a glyphmap to a distance field glyphmap, for use with the distance
 106  * field font rendering algorithm.
 107  *
 108  * It is recommended to use a fairly large font size glyphmap for this, and
 109  * then shrink the resulting distance field glyphmap as needed, with
 110  * dtx_resize_glyphmap
 111  */
 112 int dtx_calc_glyphmap_distfield(struct dtx_glyphmap *gmap);
 113
 114 /* resize a glyphmap by the provided scale factor fraction snum/sdenom
 115  * in order to maintain the power of 2 invariant, scaling fractions are only
 116  * allowed to be of the form 1/x or x/1, where x is a power of 2
 117  */
 118 int dtx_resize_glyphmap(struct dtx_glyphmap *gmap, int snum, int sdenom, int filter);
 119
 120 /* returns a pointer to the raster image of a glyphmap (1 byte per pixel grayscale) */
 121 unsigned char *dtx_get_glyphmap_image(struct dtx_glyphmap *gmap);
 122 /* returns the width of the glyphmap image in pixels */
 123 int dtx_get_glyphmap_width(struct dtx_glyphmap *gmap);
 124 /* returns the height of the glyphmap image in pixels */
 125 int dtx_get_glyphmap_height(struct dtx_glyphmap *gmap);
 126 /* returns the point size represented by this glyphmap */
 127 int dtx_get_glyphmap_ptsize(struct dtx_glyphmap *gmap);
 128
 129 /* The following functions can be used even when the library is compiled without
 130  * freetype support.
 131  */
 132 struct dtx_glyphmap *dtx_load_glyphmap(const char *fname);
 133 struct dtx_glyphmap *dtx_load_glyphmap_stream(FILE *fp);
 134 struct dtx_glyphmap *dtx_load_glyphmap_mem(void *ptr, int memsz);
 135 int dtx_save_glyphmap(const char *fname, const struct dtx_glyphmap *gmap);
 136 int dtx_save_glyphmap_stream(FILE *fp, const struct dtx_glyphmap *gmap);
 137
 138 /* adds a glyphmap to a font */
 139 void dtx_add_glyphmap(struct dtx_font *fnt, struct dtx_glyphmap *gmap);
 140
 141 void dtxhack_replace_texture(struct dtx_glyphmap *gmap, unsigned int tex);
 142
 143 /* ---- options and flags ---- */
 144 enum dtx_option {
 145         /* options for the OpenGL renderer */
 146         DTX_GL_ATTR_VERTEX,   /* vertex attribute location     (default: -1 for standard gl_Vertex) */
 147         DTX_GL_ATTR_TEXCOORD, /* texture uv attribute location (default: -1 for gl_MultiTexCoord0) */
 148         DTX_GL_ATTR_COLOR,        /* color attribute location      (default: -1 for gl_Color) */
 149         /* options for the raster renderer */
 150         DTX_RASTER_THRESHOLD, /* opaque/transparent threshold  (default: -1. fully opaque glyphs) */
 151         DTX_RASTER_BLEND,     /* glyph alpha blending (0 or 1) (default: 0 (off)) */
 152
 153         DTX_GL_BLEND,             /* GL alpha blending (0 or 1) (default: 1 (on)) */
 154         DTX_GL_ALPHATEST,         /* GL alpha test threshold (0 - 255) (default: 0 (disabled)) */
 155
 156         /* generic options */
 157         DTX_PADDING = 128,    /* padding between glyphs in pixels (default: 8) */
 158         DTX_SAVE_PPM,         /* let dtx_save_glyphmap* save PPM instead of PGM (0 or 1) (default: 0 (PGM)) */
 159
 160         DTX_FORCE_32BIT_ENUM = 0x7fffffff       /* this is not a valid option */
 161 };
 162
 163 void dtx_set(enum dtx_option opt, int val);
 164 int dtx_get(enum dtx_option opt);
 165
 166
 167 /* ---- rendering ---- */
 168
 169 /* the dtx_target_ functions select which rendering mode to use.
 170  * default: opengl
 171  */
 172 void dtx_target_opengl(void);
 173 /* pixels are expected to be RGBA ordered bytes, 4 per pixel
 174  * text is rendered with pre-multiplied alpha
 175  */
 176 void dtx_target_raster(unsigned char *pixels, int width, int height);
 177
 178
 179 /* data structures passed to user-supplied draw callback */
 180 struct dtx_vertex { float x, y, s, t; };
 181 struct dtx_pixmap {
 182         unsigned char *pixels;  /* pixel buffer pointer (8 bits per pixel) */
 183         int width, height;              /* dimensions of the pixel buffer */
 184         void *udata;    /* user-supplied pointer to data associated with this
 185                                          * pixmap. On the first callback invocation this pointer
 186                                          * will be null. The user may set it to associate any extra
 187                                          * data to this pixmap (such as texture structures or
 188                                          * identifiers). Libdrawtext will never modify this pointer.
 189                                          */
 190 };
 191
 192 /* user-defined glyph drawing callback type (set with dtx_target_user)
 193  * It's called when the output buffer is flushed, with a pointer to the vertex
 194  * buffer that needs to be drawn (every 3 vertices forming a triangle), the
 195  * number of vertices in the buffer, and a pointer to the current glyphmap
 196  * atlas pixmap (see struct dtx_pixmap above).
 197  */
 198 typedef void (*dtx_user_draw_func)(struct dtx_vertex *v, int vcount,
 199                 struct dtx_pixmap *pixmap, void *cls);
 200
 201 /* set user-supplied draw callback and optional closure pointer, which will
 202  * be passed unchanged as the last argument on every invocation of the draw
 203  * callback.
 204  */
 205 void dtx_target_user(dtx_user_draw_func drawfunc, void *cls);
 206
 207
 208 /* position of the origin of the first character to be printed */
 209 void dtx_position(float x, float y);
 210 /* TODO currently only used by the raster renderer, implement in gl too */
 211 void dtx_color(float r, float g, float b, float a);
 212
 213 /* before drawing anything this function must set the font to use */
 214 void dtx_use_font(struct dtx_font *fnt, int sz);
 215
 216 /* sets the buffering mode
 217  * - DTX_NBUF: every call to dtx_string gets rendered immediately.
 218  * - DTX_LBUF: renders when the buffer is full or the string contains a newline.
 219  * - DTX_FBUF: renders only when the buffer is full (you must call dtx_flush explicitly).
 220  */
 221 void dtx_draw_buffering(int mode);
 222
 223 /* Sets the vertex attribute indices to use for passing vertex and texture coordinate
 224  * data. By default both are -1 which means you don't have to use a shader, and if you
 225  * do they are accessible through gl_Vertex and gl_MultiTexCoord0, as usual.
 226  *
 227  * NOTE: If you are using OpenGL ES 2.x or OpenGL >= 3.1 core (non-compatibility)
 228  * context you must specify valid attribute indices.
 229  *
 230  * NOTE2: equivalent to:
 231  *    dtx_set(DTX_GL_ATTR_VERTEX, vert_attr);
 232  *    dtx_set(DTX_GL_ATTR_TEXCOORD, tex_attr);
 233  */
 234 void dtx_vertex_attribs(int vert_attr, int tex_attr);
 235
 236 /* draws a single glyph at the origin */
 237 void dtx_glyph(int code);
 238 /* draws a utf-8 string starting at the origin. \n \r and \t are handled appropriately. */
 239 void dtx_string(const char *str);
 240 void dtx_substring(const char *str, int start, int end);
 241
 242 void dtx_printf(const char *fmt, ...);
 243
 244 /* render any pending glyphs (see dtx_draw_buffering) */
 245 void dtx_flush(void);
 246
 247
 248 /* ---- encodings ---- */
 249
 250 /* returns a pointer to the next character in a utf-8 stream */
 251 char *dtx_utf8_next_char(char *str);
 252
 253 /* returns a pointer to the previous character in a utf-8 stream */
 254 char *dtx_utf8_prev_char(char *ptr, char *first);
 255
 256 /* returns the unicode character codepoint of the utf-8 character starting at str */
 257 int dtx_utf8_char_code(const char *str);
 258
 259 /* returns the number of bytes of the utf-8 character starting at str */
 260 int dtx_utf8_nbytes(const char *str);
 261
 262 /* returns the number of utf-8 characters in a zero-terminated utf-8 string */
 263 int dtx_utf8_char_count(const char *str);
 264
 265 /* returns the number of utf-8 characters in the next N bytes starting from str */
 266 int dtx_utf8_char_count_range(const char *str, int nbytes);
 267
 268 /* Converts a unicode code-point to a utf-8 character by filling in the buffer
 269  * passed at the second argument, and returns the number of bytes taken by that
 270  * utf-8 character.
 271  * It's valid to pass a null buffer pointer, in which case only the byte count is
 272  * returned (useful to figure out how much memory to allocate for a buffer).
 273  */
 274 size_t dtx_utf8_from_char_code(int code, char *buf);
 275
 276 /* Converts a unicode utf-16 wchar_t string to utf-8, filling in the buffer passed
 277  * at the second argument. Returns the size of the resulting string in bytes.
 278  *
 279  * It's valid to pass a null buffer pointer, in which case only the size gets
 280  * calculated and returned, which is useful for figuring out how much memory to
 281  * allocate for the utf-8 buffer.
 282  */
 283 size_t dtx_utf8_from_string(const wchar_t *str, char *buf);
 284
 285
 286 /* ---- metrics ---- */
 287 float dtx_line_height(void);
 288 float dtx_baseline(void);
 289
 290 /* rendered dimensions of a single glyph */
 291 void dtx_glyph_box(int code, struct dtx_box *box);
 292 float dtx_glyph_width(int code);
 293 float dtx_glyph_height(int code);
 294
 295 /* rendered dimensions of a string */
 296 void dtx_string_box(const char *str, struct dtx_box *box);
 297 void dtx_substring_box(const char *str, int start, int end, struct dtx_box *box);
 298 float dtx_string_width(const char *str);
 299 float dtx_string_height(const char *str);
 300
 301 /* returns the horizontal position of the n-th character of the rendered string
 302  * (useful for placing cursors)
 303  */
 304 float dtx_char_pos(const char *str, int n);
 305
 306 int dtx_char_at_pt(const char *str, float pt);
 307
 308 #ifdef __cplusplus
 309 }
 310 #endif
 311
 312 #endif  /* LIBDRAWTEXT_H_ */