Add README

README

@@ -0,0 +1,102 @@
+dtext
+=====
+
+`dtext` is a font-rendering library that aims at simplicity, both of the
+internals and of use.
+
+Installation
+------------
+
+In order to use `dtext` in one of your projects, the recommended way is to just
+drop `dtext.h` and `dtext.c` in its directory and add them to the `Makefile`.
+For legal matters, despite this not being legal advice, you most likely should
+in this case add anyone noted as owning a copyright for this code in the LICENSE
+file to the place you keep your own list.
+
+You can also build `dtext` as a shared library, and then link against it. This
+should relieve you of the obligation of adding names to your copyright list, so
+long as you do not distribute both files bundled. Again, this is not legal
+advice.
+
+Usage
+-----
+
+Most functions return a `dt_error` value. In this case, zero means success and
+any non-zero value indicates failure.
+
+    dt_error dt_init(dt_context **ctx, Display *dpy, Window win);
+    void dt_quit(dt_context *ctx);
+
+First, you need to initialize the library using `dt_init`. At the end of the
+program, you should close it with `dt_quit`.
+
+    dt_error dt_load(dt_context *ctx, dt_font **fnt, char const *name)
+    void dt_free(dt_context **ctx, dt_font *fnt);
+
+Then, you can load fonts using `dt_load`, and free them with `dt_free`. The
+format of the `name` argument is described in the "Font names" section below.
+
+    dt_error dt_box(dt_context *ctx, dt_font *fnt, dt_bbox *bbox,
+                    wchar_t const *txt, size_t len);
+    dt_error dt_draw(dt_context *ctx, dt_font *fnt, dt_color const *color,
+                     uint32_t x, uint32_t y, wchar_t const *txt, size_t len);
+
+These are the two main functions of the library.
+
+`dt_box` returns a bounding box to the string composed of the first `len`
+characters of `txt`, drawn with font `fnt`. The return is done through the
+pointer `bbox`, which will contain the bounding box. `bbox->x` and `bbox->y`
+will contain the coordinates of the top-left corner of the box relative to the
+origin of the baseline, and `bbox.w` and `bbox.h` are its width and height.
+
+`dt_draw` draws the string composed of the first `len` characters of `txt`,
+drawn with font `fnt`, in color `color`, with the baseline starting at position
+`x`, `y`.
+
+`dt_color` represents a color. It is of the form
+`{ .red, .green, .blue, .alpha }`, with `alpha = 0xFF` for full-visibility. For
+example, if it is memset with `0xFF`, it will be the color "white".
+
+The baseline is the line on which text would be drawn, if it was drawn by hand.
+`dt_font.ascent` is the height of the highest character of the font, relative to
+the baseline. `dt_font.height` is the total height of the highest character in
+the font.
+
+Font names
+----------
+
+A font name is composed of several font descriptions, separated by `;`. Each
+font description is a file name and a pixel size, separated by `:`.
+
+For example, the following is a valid font string:
+
+    /fonts/main.ttf:16;/fonts/special_chars.ttf:18;/fonts/fallback.ttf:16
+
+You have to specify one font size per font file, given every font file is not
+built the same way.
+
+Examples
+--------
+
+You can find examples in the `examples` directory. They have been built using
+certain fonts you may not have ; so you may have to edit the font strings
+located near the top of those files.
+
+In order to test them, just run `make` and run the executables in `build/`.
+
+Distribution
+------------
+
+This code is distributed at http://git.ekleog.org/dtext ; and every commit
+should be signed with OpenPGP key
+
+    AA29 BF0D F468 A8DC 1AB0  EA84 6598 F235 F23F B2AE
+
+If this is not the case, it means either I forgot to sign a commit, or you are
+getting MitM-ed. In any case, please do not use code from an unsigned version
+without properly checking it.
+
+Contributing
+------------
+
+Please send any comments, insults or preferably patches to leo@gaspard.io .

TODO

@@ -1,4 +1,3 @@
 Still to do:
- * Document
  * Support for faces other than the first
  * Add FontConfig optional support for last-resort fallback font (?)