Cleanup: use override/final for derived classes.
[blender.git] / source / blender / blenfont / BLF_api.h
1 /*
2  * This program is free software; you can redistribute it and/or
3  * modify it under the terms of the GNU General Public License
4  * as published by the Free Software Foundation; either version 2
5  * of the License, or (at your option) any later version.
6  *
7  * This program is distributed in the hope that it will be useful,
8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
10  * GNU General Public License for more details.
11  *
12  * You should have received a copy of the GNU General Public License
13  * along with this program; if not, write to the Free Software Foundation,
14  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
15  *
16  * The Original Code is Copyright (C) 2009 Blender Foundation.
17  * All rights reserved.
18  */
19
20 /** \file
21  * \ingroup blf
22  */
23
24 #pragma once
25
26 #include "BLI_compiler_attrs.h"
27 #include "BLI_sys_types.h"
28
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32
33 /* enable this only if needed (unused circa 2016) */
34 #define BLF_BLUR_ENABLE 0
35
36 struct ColorManagedDisplay;
37 struct ResultBLF;
38 struct rctf;
39 struct rcti;
40
41 int BLF_init(void);
42 void BLF_exit(void);
43
44 void BLF_cache_clear(void);
45
46 /* Loads a font, or returns an already loaded font and increments its reference count. */
47 int BLF_load(const char *name) ATTR_NONNULL();
48 int BLF_load_mem(const char *name, const unsigned char *mem, int mem_size) ATTR_NONNULL();
49
50 int BLF_load_unique(const char *name) ATTR_NONNULL();
51 int BLF_load_mem_unique(const char *name, const unsigned char *mem, int mem_size) ATTR_NONNULL();
52
53 void BLF_unload(const char *name) ATTR_NONNULL();
54 void BLF_unload_id(int fontid);
55
56 char *BLF_display_name_from_file(const char *filename);
57
58 /* Check if font supports a particular glyph. */
59 bool BLF_has_glyph(int fontid, unsigned int unicode);
60
61 /* Attach a file with metrics information from memory. */
62 void BLF_metrics_attach(int fontid, unsigned char *mem, int mem_size);
63
64 void BLF_aspect(int fontid, float x, float y, float z);
65 void BLF_position(int fontid, float x, float y, float z);
66 void BLF_size(int fontid, int size, int dpi);
67
68 /* goal: small but useful color API */
69 void BLF_color4ubv(int fontid, const unsigned char rgba[4]);
70 void BLF_color3ubv(int fontid, const unsigned char rgb[3]);
71 void BLF_color3ubv_alpha(int fontid, const unsigned char rgb[3], unsigned char alpha);
72 void BLF_color4ub(
73     int fontid, unsigned char r, unsigned char g, unsigned char b, unsigned char alpha);
74 void BLF_color3ub(int fontid, unsigned char r, unsigned char g, unsigned char b);
75 void BLF_color4f(int fontid, float r, float g, float b, float a);
76 void BLF_color4fv(int fontid, const float rgba[4]);
77 void BLF_color3f(int fontid, float r, float g, float b);
78 void BLF_color3fv_alpha(int fontid, const float rgb[3], float alpha);
79 /* Also available: `UI_FontThemeColor(fontid, colorid)`. */
80
81 /* Set a 4x4 matrix to be multiplied before draw the text.
82  * Remember that you need call BLF_enable(BLF_MATRIX)
83  * to enable this.
84  *
85  * The order of the matrix is like GL:
86  *
87  *  | m[0]  m[4]  m[8]  m[12] |
88  *  | m[1]  m[5]  m[9]  m[13] |
89  *  | m[2]  m[6]  m[10] m[14] |
90  *  | m[3]  m[7]  m[11] m[15] |
91  */
92 void BLF_matrix(int fontid, const float m[16]);
93
94 /* Batch draw-calls together as long as
95  * the model-view matrix and the font remain unchanged. */
96 void BLF_batch_draw_begin(void);
97 void BLF_batch_draw_flush(void);
98 void BLF_batch_draw_end(void);
99
100 /* Draw the string using the current font. */
101 void BLF_draw_ex(int fontid, const char *str, size_t str_len, struct ResultBLF *r_info)
102     ATTR_NONNULL(2);
103 void BLF_draw(int fontid, const char *str, size_t str_len) ATTR_NONNULL(2);
104 int BLF_draw_mono(int fontid, const char *str, size_t str_len, int cwidth) ATTR_NONNULL(2);
105
106 typedef bool (*BLF_GlyphBoundsFn)(const char *str,
107                                   const size_t str_step_ofs,
108                                   const struct rcti *glyph_step_bounds,
109                                   const int glyph_advance_x,
110                                   const struct rctf *glyph_bounds,
111                                   const int glyph_bearing[2],
112                                   void *user_data);
113
114 void BLF_boundbox_foreach_glyph_ex(int fontid,
115                                    const char *str,
116                                    size_t str_len,
117                                    BLF_GlyphBoundsFn user_fn,
118                                    void *user_data,
119                                    struct ResultBLF *r_info) ATTR_NONNULL(2);
120 void BLF_boundbox_foreach_glyph(int fontid,
121                                 const char *str,
122                                 size_t str_len,
123                                 BLF_GlyphBoundsFn user_fn,
124                                 void *user_data) ATTR_NONNULL(2);
125
126 /* Get the string byte offset that fits within a given width */
127 size_t BLF_width_to_strlen(
128     int fontid, const char *str, size_t str_len, float width, float *r_width) ATTR_NONNULL(2);
129 /* Same as BLF_width_to_strlen but search from the string end */
130 size_t BLF_width_to_rstrlen(
131     int fontid, const char *str, size_t str_len, float width, float *r_width) ATTR_NONNULL(2);
132
133 /* This function return the bounding box of the string
134  * and are not multiplied by the aspect.
135  */
136 void BLF_boundbox_ex(int fontid,
137                      const char *str,
138                      size_t str_len,
139                      struct rctf *box,
140                      struct ResultBLF *r_info) ATTR_NONNULL(2);
141 void BLF_boundbox(int fontid, const char *str, size_t str_len, struct rctf *box) ATTR_NONNULL();
142
143 /* The next both function return the width and height
144  * of the string, using the current font and both value
145  * are multiplied by the aspect of the font.
146  */
147 float BLF_width_ex(int fontid, const char *str, size_t str_len, struct ResultBLF *r_info)
148     ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(2);
149 float BLF_width(int fontid, const char *str, size_t str_len) ATTR_WARN_UNUSED_RESULT
150     ATTR_NONNULL();
151 float BLF_height_ex(int fontid, const char *str, size_t str_len, struct ResultBLF *r_info)
152     ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(2);
153 float BLF_height(int fontid, const char *str, size_t str_len) ATTR_WARN_UNUSED_RESULT
154     ATTR_NONNULL();
155
156 /* Return dimensions of the font without any sample text. */
157 int BLF_height_max(int fontid) ATTR_WARN_UNUSED_RESULT;
158 float BLF_width_max(int fontid) ATTR_WARN_UNUSED_RESULT;
159 float BLF_descender(int fontid) ATTR_WARN_UNUSED_RESULT;
160 float BLF_ascender(int fontid) ATTR_WARN_UNUSED_RESULT;
161
162 /* The following function return the width and height of the string, but
163  * just in one call, so avoid extra freetype2 stuff.
164  */
165 void BLF_width_and_height(
166     int fontid, const char *str, size_t str_len, float *r_width, float *r_height) ATTR_NONNULL();
167
168 /* For fixed width fonts only, returns the width of a
169  * character.
170  */
171 float BLF_fixed_width(int fontid) ATTR_WARN_UNUSED_RESULT;
172
173 /* By default, rotation and clipping are disable and
174  * have to be enable/disable using BLF_enable/disable.
175  */
176 void BLF_rotation(int fontid, float angle);
177 void BLF_clipping(int fontid, float xmin, float ymin, float xmax, float ymax);
178 void BLF_wordwrap(int fontid, int wrap_width);
179
180 #if BLF_BLUR_ENABLE
181 void BLF_blur(int fontid, int size);
182 #endif
183
184 void BLF_enable(int fontid, int option);
185 void BLF_disable(int fontid, int option);
186
187 /* Shadow options, level is the blur level, can be 3, 5 or 0 and
188  * the other argument are the rgba color.
189  * Take care that shadow need to be enable using BLF_enable!!!
190  */
191 void BLF_shadow(int fontid, int level, const float rgba[4]) ATTR_NONNULL(3);
192
193 /* Set the offset for shadow text, this is the current cursor
194  * position plus this offset, don't need call BLF_position before
195  * this function, the current position is calculate only on
196  * BLF_draw, so it's safe call this whenever you like.
197  */
198 void BLF_shadow_offset(int fontid, int x, int y);
199
200 /* Set the buffer, size and number of channels to draw, one thing to take care is call
201  * this function with NULL pointer when we finish, for example:
202  *
203  *     BLF_buffer(my_fbuf, my_cbuf, 100, 100, 4, true, NULL);
204  *
205  *     ... set color, position and draw ...
206  *
207  *     BLF_buffer(NULL, NULL, NULL, 0, 0, false, NULL);
208  */
209 void BLF_buffer(int fontid,
210                 float *fbuf,
211                 unsigned char *cbuf,
212                 int w,
213                 int h,
214                 int nch,
215                 struct ColorManagedDisplay *display);
216
217 /* Set the color to be used for text. */
218 void BLF_buffer_col(int fontid, const float rgba[4]) ATTR_NONNULL(2);
219
220 /* Draw the string into the buffer, this function draw in both buffer,
221  * float and unsigned char _BUT_ it's not necessary set both buffer, NULL is valid here.
222  */
223 void BLF_draw_buffer_ex(int fontid, const char *str, size_t str_len, struct ResultBLF *r_info)
224     ATTR_NONNULL(2);
225 void BLF_draw_buffer(int fontid, const char *str, size_t str_len) ATTR_NONNULL(2);
226
227 /* Add a path to the font dir paths. */
228 void BLF_dir_add(const char *path) ATTR_NONNULL();
229
230 /* Remove a path from the font dir paths. */
231 void BLF_dir_rem(const char *path) ATTR_NONNULL();
232
233 /* Return an array with all the font dir (this can be used for filesel) */
234 char **BLF_dir_get(int *ndir) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
235
236 /* Free the data return by BLF_dir_get. */
237 void BLF_dir_free(char **dirs, int count) ATTR_NONNULL();
238
239 /* blf_thumbs.c */
240 void BLF_thumb_preview(const char *filename,
241                        const char **draw_str,
242                        const char **i18n_draw_str,
243                        const unsigned char draw_str_lines,
244                        const float font_color[4],
245                        const int font_size,
246                        unsigned char *buf,
247                        int w,
248                        int h,
249                        int channels) ATTR_NONNULL();
250
251 /* blf_default.c */
252 void BLF_default_dpi(int dpi);
253 void BLF_default_set(int fontid);
254 int BLF_default(void); /* get default font ID so we can pass it to other functions */
255 /* Draw the string using the default font, size and dpi. */
256 void BLF_draw_default(float x, float y, float z, const char *str, size_t str_len) ATTR_NONNULL();
257 /* Set size and DPI, and return default font ID. */
258 int BLF_set_default(void);
259
260 /* blf_font_default.c */
261 int BLF_load_default(const bool unique);
262 int BLF_load_mono_default(const bool unique);
263
264 #ifdef DEBUG
265 void BLF_state_print(int fontid);
266 #endif
267
268 /* font->flags. */
269 #define BLF_ROTATION (1 << 0)
270 #define BLF_CLIPPING (1 << 1)
271 #define BLF_SHADOW (1 << 2)
272 // #define BLF_FLAG_UNUSED_3 (1 << 3) /* dirty */
273 #define BLF_MATRIX (1 << 4)
274 #define BLF_ASPECT (1 << 5)
275 #define BLF_WORD_WRAP (1 << 6)
276 #define BLF_MONOCHROME (1 << 7) /* no-AA */
277 #define BLF_HINTING_NONE (1 << 8)
278 #define BLF_HINTING_SLIGHT (1 << 9)
279 #define BLF_HINTING_FULL (1 << 10)
280 #define BLF_BOLD (1 << 11)
281 #define BLF_ITALIC (1 << 12)
282
283 #define BLF_DRAW_STR_DUMMY_MAX 1024
284
285 /* XXX, bad design */
286 extern int blf_mono_font;
287 extern int blf_mono_font_render; /* don't mess drawing with render threads. */
288
289 /**
290  * Result of drawing/evaluating the string
291  */
292 struct ResultBLF {
293   /**
294    * Number of lines drawn when #BLF_WORD_WRAP is enabled (both wrapped and `\n` newline).
295    */
296   int lines;
297   /**
298    * The 'cursor' position on completion (ignoring character boundbox).
299    */
300   int width;
301 };
302
303 #ifdef __cplusplus
304 }
305 #endif