Fixed width fonts specific management

font_api/API.md

@@ -7,35 +7,84 @@ 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
+## 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" (hardcoded) node meta.
+
+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").
+
+## 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_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_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
-**pos**: Node position
+  * `objref`: Object reference of entity
-
-**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) .
+* `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.
+* `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.
+* `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.
+* `marginbottom` (optional): Margin (in texture pixels) added at bottom of each char texture.
-* **linespacing** (optional): Spacing (in texture pixels) between each lines.
+* `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.
+`margintop`, `marginbottom` and `linespacing` can be negative numbers (default 0) and are to be used to adjust various font styles to each other.
 
 Font must have a char 0 which will be used to display any unknown char.
 
@@ -57,7 +106,7 @@ 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. 
+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__
 
@@ -95,51 +144,34 @@ __Syntax__
 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. 
+Create a new font object.
+  * `def` is a table containing font definition. See **Font definition table** above.
 
-**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.
-### font:get_char_width(char)
+  * `codepoint`: Unicode codepoint of 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.
-**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.
-**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.
-**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.
-**texturew**: Width of the texture (extra text is not rendered).
+	* `y`: Vertical position of the line in texture.
-
-**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.
-**text**: Text to be rendered.
+  * `texturew`: Width of the texture (extra text will be truncated).
-
+  * `textureh`: Height of the texture.
-**texturew**: Width of the texture (extra text will be truncated).
+  * `maxlines`: Maximum number of lines.
-
+  * `halign`: Horizontal text align ("left"/"center"/"right") (optional).
-**textureh**: Height of the texture.
+  * `valign`: Vertical text align ("top"/"center"/"bottom") (optional).
-
+  * `color`: Color of the text (optional).
-**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).
-

font_api/font.lua

@@ -103,6 +103,16 @@ function Font:new(def)
 	local font = table.copy(def)
 	setmetatable(font, self)
 	self.__index = self
+
+	-- Check if fixedwidth
+	for codepoint, width in pairs(font.widths) do
+		font.fixedwidth = font.fixedwidth or width
+		if width ~= font.fixedwidth then
+			font.fixedwidth = nil
+			break
+		end
+	end
+
 	return font
 end
 
@@ -138,11 +148,11 @@ end
 --- Returns the width of a given char
 -- @param char : codepoint of the char
 -- @return Char width
-
+function Font:get_char_width(codepoint)
-function Font:get_char_width(char)
+	if self.fixedwidth then
-	-- Replace chars with no texture by the NULL(0) char
+		return self.fixedwidth
-	if self.widths[char] ~= nil then
+	elseif self.widths[codepoint] then
-		return self.widths[char]
+		return self.widths[codepoint]
 	else
 		return self.widths[0]
 	end
@@ -201,12 +211,12 @@ function Font:make_line_texture(line, texturew, x, y)
 		codepoint, line = self:get_next_char(line)
 
 		-- Add image only if it is visible (at least partly)
-		if x + self.widths[codepoint] >= 0 and x <= texturew then
+		if x + self:get_char_width(codepoint) >= 0 and x <= texturew then
 			texture = texture..
 				string.format(":%d,%d=font_%s_%04x.png",
 				              x, y, self.name, codepoint)
 		end
-		x = x + self.widths[codepoint]
+		x = x + self:get_char_width(codepoint)
 	end
 
 	return texture
@@ -223,7 +233,7 @@ end
 -- @return Texture string
 
 function Font:make_text_texture(text, texturew, textureh, maxlines,
-                                         halign, valign, color)
+		halign, valign, color)
 	local texture = ""
 	local lines = {}
 	local textheight = 0

font_api/init.lua

@@ -48,13 +48,30 @@ function font_api.on_display_update(pos, objref)
 		local font = font_api.get_font(meta:get_string("font") ~= ""
 			and meta:get_string("font") or def.font_name)
 
-		local maxlines = def.maxlines or 1 -- TODO:How to do w/o maxlines ?
+		-- Compute entity resolution accroding to given attributes
+		local texturew, textureh
+		textureh = font:get_height(def.lines or def.maxlines or 1)
+
+		if def.columns then
+			if font.fixedwidth then
+				texturew = def.columns * font.fixedwidth
+				if def.aspect_ratio then
+					minetest.log('warning', "[font_api] 'aspect_ratio' ignored because 'columns' is specified")
+				end
+			else
+				minetest.log('warning', "[font_api] 'columns' ignored because '"..font.name.."' is not a fixed width font.")
+			end
+		end
+
+		if not texturew then
+			if not def.aspect_ratio then
+				minetest.log('warning', "[font_api] No 'aspect_ratio' specified, using default 1.")
+			end
+			texturew = textureh * def.size.x / def.size.y	/ (def.aspect_ratio or 1)
+		end
 
 		objref:set_properties({
-			textures={font:make_text_texture(text,
+			textures={font:make_text_texture(text, texturew, textureh,
-				font:get_height(maxlines) * def.size.x / def.size.y
-					/ (def.aspect_ratio or 1),
-				font:get_height(maxlines),
 				def.maxlines, def.halign, def.valign, def.color)},
 			visual_size = def.size
 		})