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