From f3970f641eb60bf92492b6715084273cc1bceb74 Mon Sep 17 00:00:00 2001 From: Thomas--S Date: Thu, 1 Feb 2018 16:54:55 +0100 Subject: Seperate signs API from signs definitions Change modnames from *_lib to *_api --- font_api/API.md | 110 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 font_api/API.md (limited to 'font_api/API.md') diff --git a/font_api/API.md b/font_api/API.md new file mode 100644 index 0000000..a4aee6d --- /dev/null +++ b/font_api/API.md @@ -0,0 +1,110 @@ +# Font Lib API +This document describes Font Lib API. Font Lib 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. + +## Provided methods +### get\_text\_size +**font\_lib.get\_text\_size(font\_name, text)** + +Computes size for a given font and text + +**font\_name**: Font name of registered font to use +**text**: Text to be rendered +**Returns**: rendered text width, height + +### make\_line\_texture +**font\_lib.make\_line\_texture(font\_name, text, width, x, y)** + +Builds texture part for a text line + +**font\_name**: Font name of registered font to use +**text**: Text to be rendered +**texturew**: Width of the texture (extra text is not rendered) +**x**: Starting x position in texture +**y**: Vertical position of the line in texture +**Returns**: Texture string + +### make\_multiline\_texture +**font\_lib.make\_multiline\_texture(font\_name, text, width, height, maxlines, halign, valign, color)** + +Builds texture for a multiline colored text + +**font\_name**: Font name of registered font to use +**text**: Text to be rendered +**texturew**: Width of the texture (extra text will be truncated) +**textureh**: Height of the texture +**maxlines**: Maximum number of lines +**halign**: Horizontal text align ("left", "right" or "center") (optional) +**valign**: Vertical text align ("top", "bottom" or "center") (optional) +**color**: Color of the text (optional) +**Returns**: Texture string + +### register\_font +**font\_lib.register_font(font\_name, height, widths)** + +Registers a new font in font_api. + +**font\_name**: Name of the font to register (this name will be used to address the font later) +If registering different sizes of the same font, add size in the font name (e.g. times\_10, times\_12...). +**height**: Font height in pixels (all font textures should have the same height) +**widths** : Array of character widths in pixels, indexed by UTF codepoints + +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\__.png** + +****: Name of the font as given in the first argument +****: UTF code of the char in 4 hexadecimal digits + +To ease that declaration, a shell is provided to build a .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 ** + +****: A TTF font file to use to create textures. +****: The font name to be used in font_api (should be simple, with no spaces). +****: Font height to be rendered. + +### make_font_lua.sh + +This script analyses textures in textures directory and creates a font\_.lua files with a call to register_font with images information. Launch it from your future font mod directory. + +Once the font\_.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 ** + +****: 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 + //tools/make_font_texture.sh myfont.ttf myfont 12 + //tools/make_font_lua.sh myfont + mv font_myfont.lua init.lua + + + + + -- cgit v1.2.3 From c6cad702bcea7f7836153b9b7f6ad847e3bd605e Mon Sep 17 00:00:00 2001 From: Pierre-Yves Rollo Date: Sun, 8 Jul 2018 20:36:34 +0200 Subject: Creation of Font class and code update accordingly --- font_api/API.md | 131 +++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 83 insertions(+), 48 deletions(-) (limited to 'font_api/API.md') diff --git a/font_api/API.md b/font_api/API.md index a4aee6d..4c711be 100644 --- a/font_api/API.md +++ b/font_api/API.md @@ -4,65 +4,52 @@ This document describes Font Lib API. Font Lib creates textures for font display ## 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. ## Provided methods -### get\_text\_size -**font\_lib.get\_text\_size(font\_name, text)** -Computes size for a given font and text +### font_api.get_default_font_name() +Returns de default font name. -**font\_name**: Font name of registered font to use -**text**: Text to be rendered -**Returns**: rendered text width, height +###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). -### make\_line\_texture -**font\_lib.make\_line\_texture(font\_name, text, width, x, y)** +###font_api.on_display_update(pos, objref) +Standard on_display_update entity callback. -Builds texture part for a text line +**pos**: Node position -**font\_name**: Font name of registered font to use -**text**: Text to be rendered -**texturew**: Width of the texture (extra text is not rendered) -**x**: Starting x position in texture -**y**: Vertical position of the line in texture -**Returns**: Texture string +**objref**: Object reference of entity -### make\_multiline\_texture -**font\_lib.make\_multiline\_texture(font\_name, text, width, height, maxlines, halign, valign, color)** +Node should have a corresponding display_entity with size, resolution and maxlines fields and optionally halign, valign and color fields. -Builds texture for a multiline colored text +###Font definition table +Font definition table used by **font_api.register_font** and **font\_api.Font:new** may/can contain following elements: -**font\_name**: Font name of registered font to use -**text**: Text to be rendered -**texturew**: Width of the texture (extra text will be truncated) -**textureh**: Height of the texture -**maxlines**: Maximum number of lines -**halign**: Horizontal text align ("left", "right" or "center") (optional) -**valign**: Vertical text align ("top", "bottom" or "center") (optional) -**color**: Color of the text (optional) -**Returns**: Texture string +* **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. -### register\_font -**font\_lib.register_font(font\_name, height, widths)** +**margintop**, **marginbottom** and **linespacing** can be negative numbers (default 0) and are to be used to adjust various font styles to each other. -Registers a new font in font_api. +Font must have a char 0 which will be used to display any unknown char. -**font\_name**: Name of the font to register (this name will be used to address the font later) -If registering different sizes of the same font, add size in the font name (e.g. times\_10, times\_12...). -**height**: Font height in pixels (all font textures should have the same height) -**widths** : Array of character widths in pixels, indexed by UTF codepoints +All textures corresponding to the indexes in widths array should be present in textures directory with a name matching the pattern : -Font must have a char 0 which will be used to display any unknown char. +> font\_**{font_name}**_**{utf_code}**.png -All textures corresponding to the indexes in **widths** array should be present in textures directory with a name matching the pattern : +**{font\_name}**: Name of the font as given in the first argument -**font\__.png** +**{utf\_code}**: UTF code of the char in 4 hexadecimal digits -****: Name of the font as given in the first argument -****: 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, a shell is provided to build a .lua file from the texture files (see provided tools). +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 @@ -78,23 +65,23 @@ This script works much better with pixels font, providing the correct height. Th __Syntax__ -**make\_font\_texture.sh ** +**make\_font\_texture.sh {fontfile} {fontname} {fontsize}** -****: A TTF font file to use to create textures. -****: The font name to be used in font_api (should be simple, with no spaces). -****: Font height to be rendered. +**{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\_.lua files with a call to register_font with images information. Launch it from your future font mod directory. +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\_.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. +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 ** +**make\_font_lua.sh {fontname}** -****: The font name to be used in font_api (same as given to make\_font\_texture.sh) +**{fontname}**: The font name to be used in font_api (same as given to make\_font\_texture.sh) ### An exemple generating a font mod @@ -104,7 +91,55 @@ __Syntax__ //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(char) +Returns the width of char **char** in texture pixels. + +**char**: 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:make_line_texture(line, texturew, x, y) +Create a texture for a text line. + +**line**: Line of text to be rendered in texture. + +**texturew**: Width of the texture (extra text is not rendered). + +**x**: Starting x position in texture. + +**y**: Vertical position of the line in texture. + +### font:make_text_texture(text, texturew, textureh, maxlines, halign, valign, color) +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. + +**maxlines**: Maximum number of lines. +**halign**: Horizontal text align ("left"/"center"/"right") (optional). +**valign**: Vertical text align ("top"/"center"/"bottom") (optional). +**color**: Color of the text (optional). -- cgit v1.2.3 From a83d494d45bdb15cd65749bc8ce505a9e7dc1f8a Mon Sep 17 00:00:00 2001 From: Pierre-Yves Rollo Date: Mon, 9 Jul 2018 07:19:27 +0000 Subject: Fix typos in API.md --- font_api/API.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'font_api/API.md') diff --git a/font_api/API.md b/font_api/API.md index 4c711be..9900a80 100644 --- a/font_api/API.md +++ b/font_api/API.md @@ -12,12 +12,12 @@ If no default\_font given or if default\_font given but not registered, the firs ### font_api.get_default_font_name() Returns de default font name. -###font_api.register_font(font_name, font_def) +### 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) +### font_api.on_display_update(pos, objref) Standard on_display_update entity callback. **pos**: Node position @@ -26,7 +26,7 @@ Standard on_display_update entity callback. 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 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) . -- cgit v1.2.3