From d1d2fe5e991ca7dd15e7ffc436f7f94cab64fafe Mon Sep 17 00:00:00 2001
From: Niels Martin Hansen <nielsm@aegisub.org>
Date: Fri, 11 Jul 2008 02:00:04 +0000
Subject: [PATCH] Documentation on how I imagine the fonts interface for
 OverLua can work. No code yet.

Originally committed to SVN as r2245.
---
 OverLua/docs/lua-fonts.txt | 62 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)
 create mode 100644 OverLua/docs/lua-fonts.txt

diff --git a/OverLua/docs/lua-fonts.txt b/OverLua/docs/lua-fonts.txt
new file mode 100644
index 000000000..55b86d2ca
--- /dev/null
+++ b/OverLua/docs/lua-fonts.txt
@@ -0,0 +1,62 @@
+Documentation for the fonts interface provided in OverLua
+=========================================================
+
+OverLua provides a simplified interface to create and manage Fontconfig
+in-memory configurations, create FreeType font face objects from those
+and basic manipulation of these font face objects.
+
+It is possible to create cairo font face objects from the FreeType font
+face objects, so the fonts can be used in cairo rendering. This is the
+preferred way to produce text in OverLua.
+
+This interface does not provide means to have Fontconfig load and use
+configuration files, neither system-wide, per-user nor private ones.
+The only way to load and use fonts is to explicitly name the font files
+and load these. The purpose of this is to let OverLua scripts produce
+predictable results, as the same font will always be selected regardless
+of the system the script is running on.
+
+
+See also:
+
+Fontconfig documentation: <http://fontconfig.org/fontconfig-devel/>
+
+FreeType 2 documentation: <http://www.freetype.org/freetype2/docs/reference/ft2-toc.html>
+
+
+Font configuration object
+-------------------------
+
+OverLua keeps one global Fontconfig configuration object, which is
+implicitly used for all operations. It is accessed through the global
+'fonts' object.
+
+The following operations are supported:
+
+
+success = fonts.add_file(filename)
+
+Attempts to load the specified font file and add all fonts in it to the
+Fontconfig configuration. This uses the FcConfigAppFontAddFile C function
+to perform the work.
+
+On return, 'success' is a boolean which is 'true' on success and 'false'
+otherwise.
+
+
+cairofont = fonts.select(pattern, cairofo)
+
+Select the font best matching the pattern given, and return an object
+representing that font.
+
+The pattern is a Lua table of key=value pairs, with the keys being the
+properties Fontconfig understands, and the values the value you want
+for that property.
+
+'cairofo' is a cairo font options object. This parameter is optional.
+
+You can see a list of known properties on: <http://fontconfig.org/fontconfig-user.html>
+
+This function returns a cairo FreeType font object that can be selected
+into a cairo context for rendering with.
+