|
|
@@ -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 .
|
Léo Gaspard