UI: disable new text hinting from D3201 by default for now.
[blender.git] / source / blender / blenfont / BLF_api.h
1 /*
2  * ***** BEGIN GPL LICENSE BLOCK *****
3  *
4  * This program is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU General Public License
6  * as published by the Free Software Foundation; either version 2
7  * of the License, or (at your option) any later version.
8  *
9  * This program is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12  * GNU General Public License for more details.
13  *
14  * You should have received a copy of the GNU General Public License
15  * along with this program; if not, write to the Free Software Foundation,
16  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
17  *
18  * The Original Code is Copyright (C) 2009 Blender Foundation.
19  * All rights reserved.
20  *
21  *
22  * Contributor(s): Blender Foundation
23  *
24  * ***** END GPL LICENSE BLOCK *****
25  */
26
27 /** \file blender/blenfont/BLF_api.h
28  *  \ingroup blf
29  */
30
31
32 #ifndef __BLF_API_H__
33 #define __BLF_API_H__
34
35 #include "BLI_compiler_attrs.h"
36 #include "BLI_sys_types.h"
37
38 struct rctf;
39 struct ColorManagedDisplay;
40 struct ResultBLF;
41
42 int BLF_init(void);
43 void BLF_exit(void);
44 void BLF_default_dpi(int dpi);
45 void BLF_default_set(int fontid);
46
47 void BLF_cache_clear(void);
48
49 int BLF_load(const char *name) ATTR_NONNULL();
50 int BLF_load_mem(const char *name, const unsigned char *mem, int mem_size) ATTR_NONNULL();
51
52 int BLF_load_unique(const char *name) ATTR_NONNULL();
53 int BLF_load_mem_unique(const char *name, const unsigned char *mem, int mem_size) ATTR_NONNULL();
54
55 void BLF_unload(const char *name) ATTR_NONNULL();
56 void BLF_unload_id(int fontid);
57
58 /* Attach a file with metrics information from memory. */
59 void BLF_metrics_attach(int fontid, unsigned char *mem, int mem_size);
60
61 void BLF_aspect(int fontid, float x, float y, float z);
62 void BLF_position(int fontid, float x, float y, float z);
63 void BLF_size(int fontid, int size, int dpi);
64
65 /* Set a 4x4 matrix to be multiplied before draw the text.
66  * Remember that you need call BLF_enable(BLF_MATRIX)
67  * to enable this.
68  *
69  * The order of the matrix is like GL:
70  *
71  *  | m[0]  m[4]  m[8]  m[12] |
72  *  | m[1]  m[5]  m[9]  m[13] |
73  *  | m[2]  m[6]  m[10] m[14] |
74  *  | m[3]  m[7]  m[11] m[15] |
75  *
76  */
77 void BLF_matrix(int fontid, const float m[16]);
78
79 /* Draw the string using the default font, size and dpi. */
80 void BLF_draw_default(float x, float y, float z, const char *str, size_t len) ATTR_NONNULL();
81 void BLF_draw_default_ascii(float x, float y, float z, const char *str, size_t len) ATTR_NONNULL();
82
83 /* Draw the string using the current font. */
84 void BLF_draw_ex(int fontid, const char *str, size_t len, struct ResultBLF *r_info) ATTR_NONNULL(2);
85 void BLF_draw(int fontid, const char *str, size_t len) ATTR_NONNULL(2);
86 void BLF_draw_ascii_ex(int fontid, const char *str, size_t len, struct ResultBLF *r_info) ATTR_NONNULL(2);
87 void BLF_draw_ascii(int fontid, const char *str, size_t len) ATTR_NONNULL(2);
88 int BLF_draw_mono(int fontid, const char *str, size_t len, int cwidth) ATTR_NONNULL(2);
89
90 /* Get the string byte offset that fits within a given width */
91 size_t BLF_width_to_strlen(int fontid, const char *str, size_t len, float width, float *r_width) ATTR_NONNULL(2);
92 /* Same as BLF_width_to_strlen but search from the string end */
93 size_t BLF_width_to_rstrlen(int fontid, const char *str, size_t len, float width, float *r_width) ATTR_NONNULL(2);
94
95 /* This function return the bounding box of the string
96  * and are not multiplied by the aspect.
97  */
98 void BLF_boundbox_ex(int fontid, const char *str, size_t len, struct rctf *box, struct ResultBLF *r_info) ATTR_NONNULL(2);
99 void BLF_boundbox(int fontid, const char *str, size_t len, struct rctf *box) ATTR_NONNULL();
100
101 /* The next both function return the width and height
102  * of the string, using the current font and both value
103  * are multiplied by the aspect of the font.
104  */
105 float BLF_width_ex(int fontid, const char *str, size_t len, struct ResultBLF *r_info) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(2);
106 float BLF_width(int fontid, const char *str, size_t len) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
107 float BLF_height_ex(int fontid, const char *str, size_t len, struct ResultBLF *r_info) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(2);
108 float BLF_height(int fontid, const char *str, size_t len) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
109
110 /* Return dimensions of the font without any sample text. */
111 int BLF_height_max(int fontid) ATTR_WARN_UNUSED_RESULT;
112 float BLF_width_max(int fontid) ATTR_WARN_UNUSED_RESULT;
113 float BLF_descender(int fontid) ATTR_WARN_UNUSED_RESULT;
114 float BLF_ascender(int fontid) ATTR_WARN_UNUSED_RESULT;
115
116 /* The following function return the width and height of the string, but
117  * just in one call, so avoid extra freetype2 stuff.
118  */
119 void BLF_width_and_height(int fontid, const char *str, size_t len, float *r_width, float *r_height) ATTR_NONNULL();
120
121 /* For fixed width fonts only, returns the width of a
122  * character.
123  */
124 float BLF_fixed_width(int fontid) ATTR_WARN_UNUSED_RESULT;
125
126 /* and this two function return the width and height
127  * of the string, using the default font and both value
128  * are multiplied by the aspect of the font.
129  */
130 void  BLF_width_and_height_default(const char *str, size_t len, float *r_width, float *r_height) ATTR_NONNULL();
131 float BLF_width_default(const char *str, size_t len) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
132 float BLF_height_default(const char *str, size_t len) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
133
134 /* Set rotation for default font. */
135 void BLF_rotation_default(float angle);
136
137 /* Enable/disable options to the default font. */
138 void BLF_enable_default(int option);
139 void BLF_disable_default(int option);
140
141 /* By default, rotation and clipping are disable and
142  * have to be enable/disable using BLF_enable/disable.
143  */
144 void BLF_rotation(int fontid, float angle);
145 void BLF_clipping(int fontid, float xmin, float ymin, float xmax, float ymax);
146 void BLF_clipping_default(float xmin, float ymin, float xmax, float ymax);
147 void BLF_wordwrap(int fontid, int wrap_width);
148 void BLF_blur(int fontid, int size);
149
150 void BLF_enable(int fontid, int option);
151 void BLF_disable(int fontid, int option);
152
153 /* Shadow options, level is the blur level, can be 3, 5 or 0 and
154  * the other argument are the rgba color.
155  * Take care that shadow need to be enable using BLF_enable!!!
156  */
157 void BLF_shadow(int fontid, int level, const float rgba[4]) ATTR_NONNULL(3);
158
159 /* Set the offset for shadow text, this is the current cursor
160  * position plus this offset, don't need call BLF_position before
161  * this function, the current position is calculate only on
162  * BLF_draw, so it's safe call this whenever you like.
163  */
164 void BLF_shadow_offset(int fontid, int x, int y);
165
166 /* Set the buffer, size and number of channels to draw, one thing to take care is call
167  * this function with NULL pointer when we finish, for example:
168  *
169  *     BLF_buffer(my_fbuf, my_cbuf, 100, 100, 4, true, NULL);
170  *
171  *     ... set color, position and draw ...
172  *
173  *     BLF_buffer(NULL, NULL, NULL, 0, 0, false, NULL);
174  */
175 void BLF_buffer(int fontid, float *fbuf, unsigned char *cbuf, int w, int h, int nch, struct ColorManagedDisplay *display);
176
177 /* Set the color to be used for text. */
178 void BLF_buffer_col(int fontid, const float rgba[4]) ATTR_NONNULL(2);
179
180 /* Draw the string into the buffer, this function draw in both buffer, float and unsigned char _BUT_
181  * it's not necessary set both buffer, NULL is valid here.
182  */
183 void BLF_draw_buffer_ex(int fontid, const char *str, size_t len, struct ResultBLF *r_info) ATTR_NONNULL(2);
184 void BLF_draw_buffer(int fontid, const char *str, size_t len) ATTR_NONNULL(2);
185
186 /* Add a path to the font dir paths. */
187 void BLF_dir_add(const char *path) ATTR_NONNULL();
188
189 /* Remove a path from the font dir paths. */
190 void BLF_dir_rem(const char *path) ATTR_NONNULL();
191
192 /* Return an array with all the font dir (this can be used for filesel) */
193 char **BLF_dir_get(int *ndir) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
194
195 /* Free the data return by BLF_dir_get. */
196 void BLF_dir_free(char **dirs, int count) ATTR_NONNULL();
197
198 /* blf_thumbs.c */
199 void BLF_thumb_preview(
200         const char *filename, const char **draw_str, const unsigned char draw_str_lines,
201         const float font_color[4], const int font_size,
202         unsigned char *buf, int w, int h, int channels) ATTR_NONNULL();
203
204 /* blf_font_i18.c */
205 unsigned char *BLF_get_unifont(int *unifont_size);
206 void           BLF_free_unifont(void);
207 unsigned char *BLF_get_unifont_mono(int *unifont_size);
208 void           BLF_free_unifont_mono(void);
209
210 #ifdef DEBUG
211 void BLF_state_print(int fontid);
212 #endif
213
214 /* font->flags. */
215 #define BLF_ROTATION         (1 << 0)
216 #define BLF_CLIPPING         (1 << 1)
217 #define BLF_SHADOW           (1 << 2)
218 #define BLF_KERNING_DEFAULT  (1 << 3)
219 #define BLF_MATRIX           (1 << 4)
220 #define BLF_ASPECT           (1 << 5)
221 #define BLF_WORD_WRAP        (1 << 6)
222 #define BLF_MONOCHROME       (1 << 7)  /* no-AA */
223 #define BLF_HINTING_NONE     (1 << 8)
224 #define BLF_HINTING_SLIGHT   (1 << 9)
225 #define BLF_HINTING_FULL     (1 << 10)
226
227 #define BLF_DRAW_STR_DUMMY_MAX 1024
228
229 /* XXX, bad design */
230 extern int blf_mono_font;
231 extern int blf_mono_font_render; /* don't mess drawing with render threads. */
232
233 /**
234  * Result of drawing/evaluating the string
235  */
236 struct ResultBLF {
237         /**
238          * Number of lines drawn when #BLF_WORD_WRAP is enabled (both wrapped and `\n` newline).
239          */
240         int lines;
241         /**
242          * The 'cursor' position on completion (ignoring character boundbox).
243          */
244         int width;
245 };
246
247 #endif /* __BLF_API_H__ */