blender
/
blender
136
405
Fork 586
Code Issues 6.2k Pull Requests 755 Projects 19 Wiki Activity

Cleanup: move public doc-strings into headers for 'blenfont' 

Ref T92709
This commit is contained in:
Campbell Barton 2021-12-08 17:12:35 +11:00
parent 00f3957b8e
commit d6c3ea9e7a
Notes: blender-bot 2024-01-31 11:35:08 +01:00 
Referenced by issue #93854, Relocate doc-strings into public headers
Referenced by issue #92709, Code Style: documentation at declaration or definition
7 changed files with 119 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

135
source/blender/blenfont/BLF_api.h
View File

@ -43,9 +43,14 @@ void BLF_exit(void);
void BLF_cache_clear(void);
/**
* Optional cache flushing function, called before #blf_batch_draw.
*/
void BLF_cache_flush_set_fn(void (*cache_flush_fn)(void));
/* Loads a font, or returns an already loaded font and increments its reference count. */
/**
* Loads a font, or returns an already loaded font and increments its reference count.
*/
int BLF_load(const char *name) ATTR_NONNULL();
int BLF_load_mem(const char *name, const unsigned char *mem, int mem_size) ATTR_NONNULL();
@ -57,17 +62,22 @@ void BLF_unload_id(int fontid);
char *BLF_display_name_from_file(const char *filename);
/* Check if font supports a particular glyph. */
/**
* Check if font supports a particular glyph.
*/
bool BLF_has_glyph(int fontid, unsigned int unicode);
/* Attach a file with metrics information from memory. */
/**
* Attach a file with metrics information from memory.
*/
void BLF_metrics_attach(int fontid, unsigned char *mem, int mem_size);
void BLF_aspect(int fontid, float x, float y, float z);
void BLF_position(int fontid, float x, float y, float z);
void BLF_size(int fontid, float size, int dpi);
/* goal: small but useful color API */
/* Goal: small but useful color API. */
void BLF_color4ubv(int fontid, const unsigned char rgba[4]);
void BLF_color3ubv(int fontid, const unsigned char rgb[3]);
void BLF_color3ubv_alpha(int fontid, const unsigned char rgb[3], unsigned char alpha);
@ -80,26 +90,32 @@ void BLF_color3f(int fontid, float r, float g, float b);
void BLF_color3fv_alpha(int fontid, const float rgb[3], float alpha);
/* Also available: `UI_FontThemeColor(fontid, colorid)`. */
/* Set a 4x4 matrix to be multiplied before draw the text.
/**
* Set a 4x4 matrix to be multiplied before draw the text.
* Remember that you need call BLF_enable(BLF_MATRIX)
* to enable this.
*
* The order of the matrix is like GL:
*
* \code{.unparsed}
* | m[0] m[4] m[8] m[12] |
* | m[1] m[5] m[9] m[13] |
* | m[2] m[6] m[10] m[14] |
* | m[3] m[7] m[11] m[15] |
* \endcode
*/
void BLF_matrix(int fontid, const float m[16]);
/* Batch draw-calls together as long as
* the model-view matrix and the font remain unchanged. */
/**
* Batch draw-calls together as long as
* the model-view matrix and the font remain unchanged.
*/
void BLF_batch_draw_begin(void);
void BLF_batch_draw_flush(void);
void BLF_batch_draw_end(void);
/* Draw the string using the current font. */
/**
* Draw the string using the current font.
*/
void BLF_draw_ex(int fontid, const char *str, size_t str_len, struct ResultBLF *r_info)
ATTR_NONNULL(2);
void BLF_draw(int fontid, const char *str, size_t str_len) ATTR_NONNULL(2);
@ -113,6 +129,14 @@ typedef bool (*BLF_GlyphBoundsFn)(const char *str,
const int glyph_bearing[2],
void *user_data);
/**
* Run \a user_fn for each character, with the bound-box that would be used for drawing.
*
* \param user_fn: Callback that runs on each glyph, returning false early exits.
* \param user_data: User argument passed to \a user_fn.
*
* \note The font position, clipping, matrix and rotation are not applied.
*/
void BLF_boundbox_foreach_glyph_ex(int fontid,
const char *str,
size_t str_len,
@ -125,14 +149,19 @@ void BLF_boundbox_foreach_glyph(int fontid,
BLF_GlyphBoundsFn user_fn,
void *user_data) ATTR_NONNULL(2);
/* Get the string byte offset that fits within a given width */
/**
* Get the string byte offset that fits within a given width.
*/
size_t BLF_width_to_strlen(
int fontid, const char *str, size_t str_len, float width, float *r_width) ATTR_NONNULL(2);
/* Same as BLF_width_to_strlen but search from the string end */
/**
* Same as BLF_width_to_strlen but search from the string end.
*/
size_t BLF_width_to_rstrlen(
int fontid, const char *str, size_t str_len, float width, float *r_width) ATTR_NONNULL(2);
/* This function return the bounding box of the string
/**
* This function return the bounding box of the string
* and are not multiplied by the aspect.
*/
void BLF_boundbox_ex(int fontid,
@ -142,7 +171,8 @@ void BLF_boundbox_ex(int fontid,
struct ResultBLF *r_info) ATTR_NONNULL(2);
void BLF_boundbox(int fontid, const char *str, size_t str_len, struct rctf *box) ATTR_NONNULL();
/* The next both function return the width and height
/**
* The next both function return the width and height
* of the string, using the current font and both value
* are multiplied by the aspect of the font.
*/
@ -155,24 +185,29 @@ float BLF_height_ex(int fontid, const char *str, size_t str_len, struct ResultBL
float BLF_height(int fontid, const char *str, size_t str_len) ATTR_WARN_UNUSED_RESULT
ATTR_NONNULL();
/* Return dimensions of the font without any sample text. */
/**
* Return dimensions of the font without any sample text.
*/
int BLF_height_max(int fontid) ATTR_WARN_UNUSED_RESULT;
float BLF_width_max(int fontid) ATTR_WARN_UNUSED_RESULT;
float BLF_descender(int fontid) ATTR_WARN_UNUSED_RESULT;
float BLF_ascender(int fontid) ATTR_WARN_UNUSED_RESULT;
/* The following function return the width and height of the string, but
/**
* The following function return the width and height of the string, but
* just in one call, so avoid extra freetype2 stuff.
*/
void BLF_width_and_height(
int fontid, const char *str, size_t str_len, float *r_width, float *r_height) ATTR_NONNULL();
/* For fixed width fonts only, returns the width of a
/**
* For fixed width fonts only, returns the width of a
* character.
*/
float BLF_fixed_width(int fontid) ATTR_WARN_UNUSED_RESULT;
/* By default, rotation and clipping are disable and
/**
* By default, rotation and clipping are disable and
* have to be enable/disable using BLF_enable/disable.
*/
void BLF_rotation(int fontid, float angle);
@ -186,27 +221,31 @@ void BLF_blur(int fontid, int size);
void BLF_enable(int fontid, int option);
void BLF_disable(int fontid, int option);
/* Shadow options, level is the blur level, can be 3, 5 or 0 and
* the other argument are the rgba color.
* Take care that shadow need to be enable using BLF_enable!!!
/**
* Shadow options, level is the blur level, can be 3, 5 or 0 and
* the other argument are the RGBA color.
* Take care that shadow need to be enable using #BLF_enable!
*/
void BLF_shadow(int fontid, int level, const float rgba[4]) ATTR_NONNULL(3);
/* Set the offset for shadow text, this is the current cursor
/**
* Set the offset for shadow text, this is the current cursor
* position plus this offset, don't need call BLF_position before
* this function, the current position is calculate only on
* BLF_draw, so it's safe call this whenever you like.
*/
void BLF_shadow_offset(int fontid, int x, int y);
/* Set the buffer, size and number of channels to draw, one thing to take care is call
/**
* Set the buffer, size and number of channels to draw, one thing to take care is call
* this function with NULL pointer when we finish, for example:
* \code{.c}
* BLF_buffer(my_fbuf, my_cbuf, 100, 100, 4, true, NULL);
*
* BLF_buffer(my_fbuf, my_cbuf, 100, 100, 4, true, NULL);
* ... set color, position and draw ...
*
* ... set color, position and draw ...
*
* BLF_buffer(NULL, NULL, NULL, 0, 0, false, NULL);
* BLF_buffer(NULL, NULL, NULL, 0, 0, false, NULL);
* \endcode
*/
void BLF_buffer(int fontid,
float *fbuf,
@ -216,29 +255,46 @@ void BLF_buffer(int fontid,
int nch,
struct ColorManagedDisplay *display);
/* Set the color to be used for text. */
/**
* Set the color to be used for text.
*/
void BLF_buffer_col(int fontid, const float rgba[4]) ATTR_NONNULL(2);
/* Draw the string into the buffer, this function draw in both buffer,
/**
* Draw the string into the buffer, this function draw in both buffer,
* float and unsigned char _BUT_ it's not necessary set both buffer, NULL is valid here.
*/
void BLF_draw_buffer_ex(int fontid, const char *str, size_t str_len, struct ResultBLF *r_info)
ATTR_NONNULL(2);
void BLF_draw_buffer(int fontid, const char *str, size_t str_len) ATTR_NONNULL(2);
/* Add a path to the font dir paths. */
/**
* Add a path to the font dir paths.
*/
void BLF_dir_add(const char *path) ATTR_NONNULL();
/* Remove a path from the font dir paths. */
/**
* Remove a path from the font dir paths.
*/
void BLF_dir_rem(const char *path) ATTR_NONNULL();
/* Return an array with all the font dir (this can be used for filesel) */
/**
* Return an array with all the font dir (this can be used for file-selector).
*/
char **BLF_dir_get(int *ndir) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
/* Free the data return by BLF_dir_get. */
/**
* Free the data return by #BLF_dir_get.
*/
void BLF_dir_free(char **dirs, int count) ATTR_NONNULL();
/* blf_thumbs.c */
/**
* This function is used for generating thumbnail previews.
*
* \note called from a thread, so it bypasses the normal BLF_* api (which isn't thread-safe).
*/
void BLF_thumb_preview(const char *filename,
const char **draw_str,
const char **i18n_draw_str,
@ -251,16 +307,25 @@ void BLF_thumb_preview(const char *filename,
int channels) ATTR_NONNULL();
/* blf_default.c */
void BLF_default_dpi(int dpi);
void BLF_default_size(int size);
void BLF_default_set(int fontid);
int BLF_default(void); /* get default font ID so we can pass it to other functions */
/* Draw the string using the default font, size and dpi. */
/**
* Get default font ID so we can pass it to other functions.
*/
int BLF_default(void);
/**
* Draw the string using the default font, size and DPI.
*/
void BLF_draw_default(float x, float y, float z, const char *str, size_t str_len) ATTR_NONNULL();
/* Set size and DPI, and return default font ID. */
/**
* Set size and DPI, and return default font ID.
*/
int BLF_set_default(void);
/* blf_font_default.c */
int BLF_load_default(const bool unique);
int BLF_load_mono_default(const bool unique);

11
source/blender/blenfont/intern/blf.c
View File

@ -66,7 +66,8 @@
/* Font array. */
static FontBLF *global_font[BLF_MAX_FONT] = {NULL};
/* XXX, should these be made into global_font_'s too? */
/* XXX: should these be made into global_font_'s too? */
int blf_mono_font = -1;
int blf_mono_font_render = -1;
@ -568,14 +569,6 @@ int BLF_draw_mono(int fontid, const char *str, const size_t str_len, int cwidth)
return columns;
}
/**
* Run \a user_fn for each character, with the bound-box that would be used for drawing.
*
* \param user_fn: Callback that runs on each glyph, returning false early exits.
* \param user_data: User argument passed to \a user_fn.
*
* \note The font position, clipping, matrix and rotation are not applied.
*/
void BLF_boundbox_foreach_glyph_ex(int fontid,
const char *str,
size_t str_len,

4
source/blender/blenfont/intern/blf_dir.c
View File

@ -148,10 +148,6 @@ char *blf_dir_search(const char *file)
return s;
}
/**
* Some font have additional file with metrics information,
* in general, the extension of the file is: `.afm` or `.pfm`
*/
char *blf_dir_metrics_search(const char *filename)
{
char *mfile;

5
source/blender/blenfont/intern/blf_font.c
View File

@ -63,6 +63,7 @@
#endif
/* Batching buffer for drawing. */
BatchBLF g_batch;
/* freetype2 handle ONLY for this file! */
@ -394,7 +395,6 @@ void blf_font_draw(FontBLF *font, const char *str, const size_t str_len, struct
blf_glyph_cache_release(font);
}
/* use fixed column width, but an utf8 character may occupy multiple columns */
int blf_font_draw_mono(FontBLF *font, const char *str, const size_t str_len, int cwidth)
{
GlyphBLF *g;
@ -1168,9 +1168,6 @@ void blf_font_exit(void)
blf_batch_draw_exit();
}
/**
* Optional cache flushing function, called before #blf_batch_draw.
*/
void BLF_cache_flush_set_fn(void (*cache_flush_fn)(void))
{
blf_draw_cache_flush = cache_flush_fn;

9
source/blender/blenfont/intern/blf_glyph.c
View File

@ -73,9 +73,6 @@ static FT_Fixed to_16dot16(double val)
/** \name Glyph Cache
* \{ */
/**
* Find a glyph cache that matches a size, DPI & styles.
*/
GlyphCacheBLF *blf_glyph_cache_find(FontBLF *font, float size, unsigned int dpi)
{
GlyphCacheBLF *gc = (GlyphCacheBLF *)font->cache.first;
@ -89,9 +86,6 @@ GlyphCacheBLF *blf_glyph_cache_find(FontBLF *font, float size, unsigned int dpi)
return NULL;
}
/**
* Create a new glyph cache for the current size, DPI & styles.
*/
GlyphCacheBLF *blf_glyph_cache_new(FontBLF *font)
{
GlyphCacheBLF *gc = (GlyphCacheBLF *)MEM_callocN(sizeof(GlyphCacheBLF), "blf_glyph_cache_new");
@ -451,9 +445,6 @@ static FT_GlyphSlot blf_glyph_render(FontBLF *settings_font,
return NULL;
}
/**
* Create (or load from cache) a fully-rendered bitmap glyph.
*/
GlyphBLF *blf_glyph_ensure(FontBLF *font, GlyphCacheBLF *gc, uint charcode)
{
GlyphBLF *g = blf_glyph_cache_find_glyph(gc, charcode);

16
source/blender/blenfont/intern/blf_internal.h
View File

@ -37,6 +37,10 @@ unsigned int blf_next_p2(unsigned int x);
unsigned int blf_hash(unsigned int val);
char *blf_dir_search(const char *file);
/**
* Some font have additional file with metrics information,
* in general, the extension of the file is: `.afm` or `.pfm`
*/
char *blf_dir_metrics_search(const char *filename);
/* int blf_dir_split(const char *str, char *file, int *size); */ /* UNUSED */
@ -65,6 +69,9 @@ void blf_font_draw_ascii(struct FontBLF *font,
const char *str,
size_t str_len,
struct ResultBLF *r_info);
/**
* Use fixed column width, but an utf8 character may occupy multiple columns.
*/
int blf_font_draw_mono(struct FontBLF *font, const char *str, size_t str_len, int cwidth);
void blf_font_draw_buffer(struct FontBLF *font,
const char *str,
@ -130,13 +137,22 @@ int blf_font_count_missing_chars(struct FontBLF *font,
void blf_font_free(struct FontBLF *font);
/**
* Find a glyph cache that matches a size, DPI & styles.
*/
struct GlyphCacheBLF *blf_glyph_cache_find(struct FontBLF *font, float size, unsigned int dpi);
/**
* Create a new glyph cache for the current size, DPI & styles.
*/
struct GlyphCacheBLF *blf_glyph_cache_new(struct FontBLF *font);
struct GlyphCacheBLF *blf_glyph_cache_acquire(struct FontBLF *font);
void blf_glyph_cache_release(struct FontBLF *font);
void blf_glyph_cache_clear(struct FontBLF *font);
void blf_glyph_cache_free(struct GlyphCacheBLF *gc);
/**
* Create (or load from cache) a fully-rendered bitmap glyph.
*/
struct GlyphBLF *blf_glyph_ensure(struct FontBLF *font, struct GlyphCacheBLF *gc, uint charcode);
void blf_glyph_free(struct GlyphBLF *g);

5
source/blender/blenfont/intern/blf_thumbs.c
View File

@ -43,11 +43,6 @@
#include "BLI_strict_flags.h"
/**
* This function is used for generating thumbnail previews.
*
* \note called from a thread, so it bypasses the normal BLF_* api (which isn't thread-safe).
*/
void BLF_thumb_preview(const char *filename,
const char **draw_str,
const char **i18n_draw_str,