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