From 42098402e27ad323355e7091416f44b9c43f7345 Mon Sep 17 00:00:00 2001
From: Anon <git@anonweb.de>
Date: Sun, 13 Aug 2023 20:41:50 +0200
Subject: [PATCH] docs: document fonts
---
docs/api/ctx.rst | 2 +
docs/badge/fonts.rst | 92 ++++++++++++++++++++++++++++++++++++++++++++
docs/index.rst | 1 +
3 files changed, 95 insertions(+)
create mode 100644 docs/badge/fonts.rst
diff --git a/docs/api/ctx.rst b/docs/api/ctx.rst
index 0daaed0798..e53b3204b3 100644
--- a/docs/api/ctx.rst
+++ b/docs/api/ctx.rst
@@ -1,3 +1,5 @@
+.. _ctx API:
+
``ctx`` module
==============
diff --git a/docs/badge/fonts.rst b/docs/badge/fonts.rst
new file mode 100644
index 0000000000..71b9684557
--- /dev/null
+++ b/docs/badge/fonts.rst
@@ -0,0 +1,92 @@
+.. _Fonts:
+
+Fonts
+=====
+
+The current selection of fonts is baked into the firmware for use with :ref:`Context<ctx API>`.
+
+Available Fonts
+---------------
+
+Following fonts are currently available:
+
++-------------+----------------------+
+| Font Number | Font Name |
++=============+======================+
+| 0 | Arimo Regular |
++-------------+----------------------+
+| 1 | Arimo Bold |
++-------------+----------------------+
+| 2 | Arimo Italic |
++-------------+----------------------+
+| 3 | Arimo Bold Italic |
++-------------+----------------------+
+| 4 | Camp Font 1 |
++-------------+----------------------+
+| 5 | Camp Font 2 |
++-------------+----------------------+
+| 6 | Camp Font 3 |
++-------------+----------------------+
+| 7 | Material Icons |
++-------------+----------------------+
+| 8 | Comic Mono |
++-------------+----------------------+
+
+The Camp Fonts are based on Beon Regular, Saira Stencil One and Questrial Regular.
+
+Material Icons contains Glyphs in the range of U+E000 - U+F23B.
+
+See header files in ``components/ctx/fonts/`` for details.
+
+Basic Usage
+-----------
+To switch fonts, simply set ``ctx.font`` and refer to the font by full name:
+
+.. code-block:: python
+
+ ctx.rgb(255, 255, 255)
+ ctx.move_to(0, 0)
+ ctx.font = "Camp Font 1"
+ ctx.text("flow3r")
+
+To insert one or more icons, use Python ``\u`` escape sequences.
+You can look up the code points for icons on `https://fonts.google.com/icons <https://fonts.google.com/icons>`_.
+
+.. code-block:: python
+
+ ctx.save()
+ ctx.rgb(255, 255, 255)
+ ctx.move_to(0, 0)
+ ctx.font = "Material Icons"
+ ctx.text("\ue147 \ue1c2 \ue24e")
+ ctx.restore()
+
+Adding New Fonts
+----------------
+To add a new font to the firmware, it must first be converted into the ctx binary format.
+
+ctx provides the tools for this and you can set them up them with the folling commands:
+
+.. code-block:: bash
+
+ git clone https://ctx.graphics/.git/
+ cd ctx.graphics
+ ./configure.sh
+ make tools/ctx-fontgen
+
+Now you can use ``ctx-fontgen`` to convert a font:
+
+.. code-block:: bash
+
+ ./tools/ctx-fontgen /path/to/ComicMono.ttf Comic_Mono latin1 > Comic-Mono.h
+
+Note that the font name is read from the source file directly and not specified by any of the arguments.
+You can find it at the end of the header file. In this case: ``#define ctx_font_Comic_Mono_name "Comic Mono"``.
+
+The next step is to copy the header file over into ``components/ctx/fonts`` (and adding license headers, etc).
+
+Once the file is in the fonts directory, it can be added to ``components/ctx/ctx_config.h``.
+In there it needs an include and define with a new font number.
+
+The new font is now available in the next firmware build, but the simulator needs a rebuild of the Wasm bundle.
+See ``/sim/README.md`` for details.
diff --git a/docs/index.rst b/docs/index.rst
index 50a8b92022..3eb8d271ae 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -19,6 +19,7 @@ Welcome to flow3r's documentation!
badge/badge_link.rst
badge/badge_net.rst
badge/bl00mbox.rst
+ badge/fonts.rst
.. toctree::
:maxdepth: 1
--
GitLab