diff options
Diffstat (limited to 'font_api/API.md')
| -rw-r--r-- | font_api/API.md | 201 |
1 files changed, 0 insertions, 201 deletions
diff --git a/font_api/API.md b/font_api/API.md deleted file mode 100644 index 80b1121..0000000 --- a/font_api/API.md +++ /dev/null @@ -1,201 +0,0 @@ -# Font API -This document describes Font API. Font API creates textures for font display on entities. - -## Settings -### default_font -Name of the font to be used when no font is given. The font should be registered. - -If no default\_font given or if default\_font given but not registered, the first registered font will be used as default. - -## Use font_api with display_api (to display text on nodes) -### Base setup -Font_api offers a direct integration with display_api to display text on nodes. - -First of all, create a display node with an entity. -To do this, refer to API.md in display_api mod, in particular "Howto register a display node". - -The only requirement then is to connect the `on_display_update` callback of the display entity to `font_api.on_display_update`: - -``` -minetest.register_node("mymod:test_text_node", { - ... - paramtype2 = "facedir", - ... - groups = { display_api = 1, ... }, - ... - display_entities = { - ["mymod:text"] = { - depth = -0.5 - display_api.entity_spacing, - on_display_update = font_api.on_display_update }, - } - ... - on_place = display_api.on_place, - on_construct = display_api.on_construct, - on_destruct = display_api.on_destruct, - on_rotate = display_api.on_rotate, - ... -}) -``` - -At this step, your node already displays text form "display_text" (by default) node meta. If you want to store your text into another meta data field, add a `meta_text` field to display entity definition. - -But it uses defaults (default font, default size, default color). Likely you need something more. - -### Style your text -Font style and size can be chosen by adding some more entries to the display_entities definition table. - -#### Font size -Font size can be defined in various ways (maybe more in the future). -Start with a number of lines, and font_api will make it fit to the entity size. - * `maxlines` or `lines`: Number of maximum lines of text to be displayed. The font height will be adjusted accordingly. - -Then specify the char width. Two methods available: - * `aspect_ratio`: Defines the aspect ratio of chars. Works with all fonts. Should not be used if `columns` is specified. - * `columns`: Only if using a fixed width font, specifies the number of columns to display. - -#### Font style - * `font_name`: name of the font to use. Should correspond to a registered font (from a font mod). If not specified or font not found, default font is used. - * `color`: color to be used (default black). - * `halign`: Horizontal alignment: "left", "center" or "right" (default "center"). - * `valign`: Vertical alignement: "top", "middle" or "bottom" (default "middle"). - -### Example -Using blue //botic// font, three lines height, aligned top left. Text stored in "text" node meta. -``` -minetest.register_node("mymod:test_text_node", { - ... - ... - display_entities = { - ["mymod:text"] = { - depth = -0.5 - display_api.entity_spacing, - on_display_update = font_api.on_display_update - meta_text = "text", - font_name = "botic", - color = "#0000FF", - maxlines = 3, - aspect_ratio = 0.5, - halign = "left", - valign = "top", - }, - } - ... -}) -``` -## Provided methods -### font_api.get_default_font_name() -Returns de default font name. - -### font_api.register_font(font_name, font_def) -Register a new font. - * `font_name`: Name of the font to register. If registering different sizes of the same font, add size in the font name (e.g. times_10, times_12...). - * `font_def`: Font definition table (see **Font definition table** below). - -### font_api.on_display_update(pos, objref) -Standard on_display_update entity callback. - * `pos`: Node position - * `objref`: Object reference of entity - -Node should have a corresponding display_entity with size, resolution and maxlines fields and optionally halign, valign and color fields. - -## Font definition table -Font definition table used by **font_api.register_font** and **font\_api.Font:new** may/can contain following elements: - -* `height` (required): Font height in pixels (all font textures should have the same height) . -* `widths` (required): Array of character widths in pixels, indexed by UTF codepoints. -* `margintop` (optional): Margin (in texture pixels) added on top of each char texture. -* `marginbottom` (optional): Margin (in texture pixels) added at bottom of each char texture. -* `linespacing` (optional): Spacing (in texture pixels) between each lines. - -`margintop`, `marginbottom` and `linespacing` can be negative numbers (default 0) and are to be used to adjust various font styles to each other. - -Font attributes around a single char:\ - - -Font attributes effects on several lines:\ - - -#### Additional requirements - -Font must have a char 0 which will be used to display any unknown char. - -All textures corresponding to the indexes in widths array should be present in textures directory with a name matching the pattern : - -> font\_**{font_name}**_**{utf_code}**.png - -**{font\_name}**: Name of the font as given in the first argument - -**{utf\_code}**: UTF code of the char in 4 hexadecimal digits - -Example : font_courrier_0041.png is for the "A" char in the "courrier" font. - -To ease that declaration (specially to build the **widths** array), a shell is provided to build a {font\_name}.lua file from the texture files (see provided tools). - -## Provided tools - -Still in early stage of development, these tools are helpers to create font mods. - -### make_font_texture.sh - -This scripts takes a .ttf file as input and create one .png file per char, that can be used as font texture. Launch it from your future font mod directory. - -__Advice__ - -This script works much better with pixels font, providing the correct height. There is no antialiasing at all, vector fonts and bad heights gives very ugly results. - -__Syntax__ - -**make\_font\_texture.sh {fontfile} {fontname} {fontsize}** - -**{fontfile}**: A TTF font file to use to create textures. -**{fontname}**: The font name to be used in font_api (should be simple, with no spaces). -**{fontsize}**: Font height to be rendered. - -### make_font_lua.sh - -This script analyses textures in textures directory and creates a font\_{font\_name}.lua files with a call to register_font with images information. Launch it from your future font mod directory. - -Once the font\_{font\_name}.lua created, it can be included by a init.lua file or directly renamed to init.lua if you are creating a simple font mod. - -__Syntax__ - -**make\_font_lua.sh {fontname}** - -**{fontname}**: The font name to be used in font_api (same as given to make\_font\_texture.sh) - -### An exemple generating a font mod - - mkdir font_myfont - cd font_myfont - /<path_to_font_api>/tools/make_font_texture.sh myfont.ttf myfont 12 - /<path_to_font_api>/tools/make_font_lua.sh myfont - mv font_myfont.lua init.lua - -## Font class -A font usable with font API. This class is supposed to be for internal use but who knows. - -### font\_api.Font:new(def) -Create a new font object. - * `def` is a table containing font definition. See **Font definition table** above. - -### font:get_char_width(codepoint) -Returns the width of char `codepoint` in texture pixels. - * `codepoint`: Unicode codepoint of char. - -### font:get_height(nb_of_lines) -Returns line(s) height. Takes care of top and bottom margins and line spacing. - * `nb_of_lines`: Number of lines in the text. - -### font:get_width(line) -Returns the width of a text line. Beware, if line contains any new line char, they are ignored. - * `line`: Line of text which the width will be computed. - -### font:renter(text, texturew, textureh, style) -Builds texture for a multiline colored text. - * `text`: Text to be rendered. - * `texturew`: Width of the texture (extra text will be truncated). - * `textureh`: Height of the texture (extra text will be truncated). - * `style`: A table with style indications: - - `lines` or `maxlines`: Maximum number of lines (default none). - - `halign`: Horizontal text align: "left"/"center"/"right" (default "center") - - `valign`: Vertical text align: "top"/"middle"/"bottom" (default "middle") - - `color`: Color of the text (default black) |