zztaeha

C constants and macros

246 constants and macros in daegun 2.0.0, as its headers define them, filed by header. A code that names one of several, such as a DAEGUN_ALIGN_ value, is an int32_twherever a call or a field takes it, and one that is none of its constants answersDAEGUN_INVALID_ARGUMENT.

The last group, Header machinery, holds the macros the headers wrap their own declarations in for compilers. A program rarely writes one of those itself.

Base

daegun/base.h: what every other header builds on. Statuses, the views and owned results calls hand back, the ABI version, the last error, tags, boxes, and the font and location handles.

DAEGUN_OK
#define DAEGUN_OK 0

The call did what it says, and its out parameters hold the result.

The ten status constants are the values of a daegun_status. This one is 0, and it is the only status after which a call's results are there to read, so the usual check is != DAEGUN_OK.

It is not a failure and writes no reason. daegun_last_error still holds whatever an earlier failure on the thread left there, so learn whether a call worked from its status, never from the reason.

uint16_t upem = 0;
if (daegun_font_units_per_em(font, &upem) != DAEGUN_OK) return 1;
/* upem is 2048 for Inter. */
DAEGUN_NULL
#define DAEGUN_NULL -1

A pointer the call requires was NULL.

Not a failure of the font: it is always a bug in the calling code. The call checks before it reads, so the NULL is never dereferenced. A number or struct out is left as it was, and a handle out is NULL.

A pointer is required unless the header marks it DAEGUN_NULLABLE, and the reference lists the marked ones on each call. A pointer that comes with a count may be NULL where the count is 0. A location is never required: NULL there means the default instance.

It writes no reason, and daegun_last_error is left as it was.

const daegun_font *missing = NULL; /* a font that was never opened */
uint16_t upem = 1000;
daegun_status status = daegun_font_units_per_em(missing, &upem);
/* status is DAEGUN_NULL, and upem is still 1000. */
DAEGUN_MALFORMED
#define DAEGUN_MALFORMED -2

Font data the call needs is malformed: truncated, out of range or inconsistent.

A failure: the bytes are not what their format says they should be. daegun_font_open answers it for bytes that are not a font. The reason in daegun_last_error names the table or step and what was wrong there.

uint8_t junk[64];
memset(junk, 0xAB, sizeof junk);
daegun_font *opened = NULL;
daegun_status status = daegun_font_open(junk, sizeof junk, &opened);
/* status is DAEGUN_MALFORMED, opened is NULL, and the reason says the bytes are not a font file. */
daegun_font_free(opened);
DAEGUN_INVALID_ARGUMENT
#define DAEGUN_INVALID_ARGUMENT -3

An argument is out of range, not a number, or not UTF-8.

A failure, and one about what you passed, not about the font. It covers text that is not UTF-8, a code point that is not a Unicode scalar value, a NaN where the call needs a number, an index past the end of a list, a code that names none of its constants, a buffer too small for the result or one that shares bytes with another the call reads or fills, and an options struct whose size is below what daegun 2.0 defined.

The reason in daegun_last_error says which. For text it names the byte where the text stops being UTF-8.

daegun_shaped_run *run = NULL;
daegun_status status = daegun_font_shape(font, "a\xff", 2, NULL, NULL, &run);
/* 0xFF is not UTF-8: status is DAEGUN_INVALID_ARGUMENT, and the reason names byte 1. */
daegun_shaped_run_free(run);
DAEGUN_ABSENT
#define DAEGUN_ABSENT -4

The font has no such glyph, table or value: an answer, not a failure.

C has no optional type, and a zero can't stand for none, since 0 is a real glyph id (.notdef). So a call that asks for something a font may not have answers this where there is none. Handle it as an ordinary branch of your code.

The out is as on any status but DAEGUN_OK: a number or struct is left as it was, and a handle is NULL. It writes no reason, and daegun_last_error is left as it was.

uint32_t gid = 0;
daegun_status status = daegun_font_glyph_id(font, 0x8A9E, &gid);
if (status == DAEGUN_ABSENT) {
    /* Inter has no glyph for U+8A9E, a CJK character: draw it with another font. */
} else if (status != DAEGUN_OK) {
    return 1;
}
DAEGUN_UNSUPPORTED
#define DAEGUN_UNSUPPORTED -6

A format, version or options struct daegun doesn't read.

A failure. The data is in a format or a version that daegun has no reader for. The reason is in daegun_last_error.

For an options struct it means the struct is larger than this library knows, which happens when your header is newer than the library you link.

Its value is -6. The -5 before it is retired and names no status.

/* An AAT lookup table whose first two bytes claim format 0xFFFF. */
uint8_t table[16];
memset(table, 0xFF, sizeof table);
daegun_aat_lookup *lookup = NULL;
daegun_status status = daegun_aat_lookup_parse(table, sizeof table, 10, &lookup);
/* status is DAEGUN_UNSUPPORTED: lookups come in formats 0, 2, 4, 6, 8 and 10. */
daegun_aat_lookup_free(lookup);
DAEGUN_MISSING
#define DAEGUN_MISSING -7

A table or record the call needs isn't in the font.

A failure. It differs from DAEGUN_ABSENT, which answers a question about what the font has. This one means the call could not do its work at all, because the font lacks something that work rests on. daegun_font_open answers it for a font with no head table to give the units per em, or no maxp table to give the glyph count. The reason in daegun_last_error names what is missing.

/* A font file that holds a name table and nothing else. */
daegun_table_map *tables = daegun_table_map_new();
const uint8_t name[8] = { 0 };
if (daegun_table_map_set(tables, DAEGUN_TAG('n', 'a', 'm', 'e'), name, sizeof name) != DAEGUN_OK) return 1;
daegun_blob *file = NULL;
if (daegun_table_map_build(tables, &file) != DAEGUN_OK) return 1;
size_t size = 0;
const uint8_t *bytes = daegun_blob_data(file, &size);

daegun_font *opened = NULL;
daegun_status status = daegun_font_open(bytes, size, &opened);
/* status is DAEGUN_MISSING, and the reason is "head: missing, or no unitsPerEm". */

daegun_font_free(opened);
daegun_blob_free(file);
daegun_table_map_free(tables);
DAEGUN_LIMIT_EXCEEDED
#define DAEGUN_LIMIT_EXCEEDED -8

The font, or the call, asks for more work or memory than daegun allows.

A failure. daegun puts a ceiling on the work and the memory that one font or one call may take, and this is what a call answers past it. Where a ceiling is a number you can know in advance, the call that keeps it names it: daegun_path_flatten answers this when a path flattens to more than DAEGUN_MAX_FLATTEN_POINTS points, or holds more than twice that many. The reason is in daegun_last_error.

/* A path of one point more than daegun_path_flatten keeps. */
daegun_path *path = daegun_path_new();
if (daegun_path_move_to(path, 0.0f, 0.0f) != DAEGUN_OK) return 1;
for (int i = 1; i <= DAEGUN_MAX_FLATTEN_POINTS; i++) {
    if (daegun_path_line_to(path, (float)(i % 1000), (float)(i / 1000)) != DAEGUN_OK) return 1;
}

daegun_contours *contours = NULL;
daegun_status status = daegun_path_flatten(path, 1.0f, &contours);
/* status is DAEGUN_LIMIT_EXCEEDED, and contours is NULL. */

daegun_contours_free(contours);
daegun_path_free(path);
DAEGUN_NO_OUTLINE
#define DAEGUN_NO_OUTLINE -9

The glyph has no outline to draw.

A failure, with its reason in daegun_last_error. daegun_font_quads answers it for a glyph that draws nothing, such as a space. Where an empty glyph is ordinary, as it is for the spaces in a line of text, check for this status and skip the glyph.

uint32_t space = 0;
if (daegun_font_glyph_id(font, ' ', &space) != DAEGUN_OK) return 1;
daegun_quads *quads = NULL;
daegun_status status = daegun_font_quads(font, space, NULL, &quads);
/* A space draws nothing: status is DAEGUN_NO_OUTLINE, and quads is NULL. */
daegun_quads_free(quads);
DAEGUN_OVERFLOW
#define DAEGUN_OVERFLOW -10

A value outgrows what its type can hold once scaled.

A failure. An outline's points are 32-bit floats, and a value that would pass a float's range on its way to a pen is refused, not drawn at infinity. daegun_font_prepared_outline answers this for a transform that scales a glyph past that range, and draws nothing. The reason is in daegun_last_error.

/* A transform that scales the glyph by 3e38, close to the largest number a float holds. */
daegun_outline_options opts;
if (daegun_outline_options_default(&opts, sizeof opts) != DAEGUN_OK) return 1;
opts.transform[0] = 3.0e38f;
opts.transform[3] = 3.0e38f;
opts.has_transform = true;

uint32_t gid = 0;
if (daegun_font_glyph_id(font, 'A', &gid) != DAEGUN_OK) return 1;
daegun_pen pen = { 0 };
daegun_status status = daegun_font_prepared_outline(font, gid, NULL, 32.0f, &opts, &pen, NULL);
/* status is DAEGUN_OVERFLOW. */
DAEGUN_ABI_VERSION
#define DAEGUN_ABI_VERSION 0x020000u

The ABI version of the header your program is compiled against.

It is packed as daegun_abi_version packs the library's: (major << 16) | (minor << 8) | patch, here 2.0.0. The two differ when a program built against one release runs with the library of another, and DAEGUN_ABI_COMPATIBLE says whether that pairing works.

DAEGUN_ABI_MAJOR
#define DAEGUN_ABI_MAJOR(v) ((v) >> 16)

The major part of an ABI version.

The DAEGUN_ABI_ macros take a version as daegun_abi_version returns it and DAEGUN_ABI_VERSION holds it. Each is a constant expression when its argument is, so each works in #if too.

A different major means an existing call, constant or struct changed, so a program built for one major must not use a library of another.

#if DAEGUN_ABI_MAJOR(DAEGUN_ABI_VERSION) != 2
#error "this code is written for major 2 of daegun's ABI"
#endif
uint32_t abi = daegun_abi_version();
if (DAEGUN_ABI_MAJOR(abi) != DAEGUN_ABI_MAJOR(DAEGUN_ABI_VERSION)) return 1;
DAEGUN_ABI_MINOR
#define DAEGUN_ABI_MINOR(v) (((v) >> 8) & 0xFFu)

The minor part of an ABI version.

It goes up when calls or constants are added, or an options struct grows at its end. A library whose minor is higher than that of your header still serves your program. One whose minor is lower may lack a call you use.

uint32_t abi = daegun_abi_version();
if (DAEGUN_ABI_MINOR(abi) < DAEGUN_ABI_MINOR(DAEGUN_ABI_VERSION)) {
    /* The library is older than the header: it may lack calls this program uses. */
    return 1;
}
DAEGUN_ABI_PATCH
#define DAEGUN_ABI_PATCH(v) ((v) & 0xFFu)

The patch part of an ABI version.

DAEGUN_ABI_COMPATIBLE does not look at it. It is there to print, for a log or a bug report.

uint32_t abi = daegun_abi_version();
printf("daegun ABI %u.%u.%u\n", DAEGUN_ABI_MAJOR(abi), DAEGUN_ABI_MINOR(abi), DAEGUN_ABI_PATCH(abi));
/* Prints "daegun ABI 2.0.0". */
DAEGUN_ABI_COMPATIBLE
#define DAEGUN_ABI_COMPATIBLE(v) \
    (DAEGUN_ABI_MAJOR(v) == DAEGUN_ABI_MAJOR(DAEGUN_ABI_VERSION) && ((v) >> 8) >= (DAEGUN_ABI_VERSION >> 8))

Whether a library that reports ABI version v can serve a program built against this header.

True when v has the same major as DAEGUN_ABI_VERSION and a minor no lower. The patch is not compared. Pass it what daegun_abi_version returns, once at startup, and stop if it is false.

It is a constant expression when v is, so it works in #if too.

if (!DAEGUN_ABI_COMPATIBLE(daegun_abi_version())) {
    fprintf(stderr, "this daegun library is not one this program can use\n");
    return 1;
}
/* A later minor of the same major passes. Another major does not, higher or lower. */
DAEGUN_TAG
#ifdef __cplusplus
#define DAEGUN_TAG(a, b, c, d) \
    (static_cast<daegun_tag>(static_cast<uint8_t>(a)) << 24 | static_cast<daegun_tag>(static_cast<uint8_t>(b)) << 16 \
     | static_cast<daegun_tag>(static_cast<uint8_t>(c)) << 8 | static_cast<daegun_tag>(static_cast<uint8_t>(d)))
#else
#define DAEGUN_TAG(a, b, c, d) \
    ((daegun_tag)(((uint32_t)(uint8_t)(a) << 24) | ((uint32_t)(uint8_t)(b) << 16) | \
                  ((uint32_t)(uint8_t)(c) << 8) | (uint32_t)(uint8_t)(d)))
#endif

Builds a daegun_tag from four characters.

The first argument becomes the high byte, so DAEGUN_TAG('w', 'g', 'h', 't') is 0x77676874. It is a constant expression, so it works in an initializer and as a case label. Pad a shorter tag with spaces yourself: DAEGUN_TAG('l', 'a', 'o', ' ').

Each argument is cut to one byte before it is shifted into place. In C++ the macro is written with static_cast and gives the same number.

daegun_tag gpos = DAEGUN_TAG('G', 'P', 'O', 'S');
bool has = false;
if (daegun_font_has_table(font, gpos, &has) != DAEGUN_OK) return 1;
/* has is true: Inter has a GPOS table. gpos is 0x47504F53. */
DAEGUN_UNTAG
#ifdef __cplusplus
#define DAEGUN_UNTAG(t) \
    static_cast<char>(((t) >> 24) & 0xFFu), static_cast<char>(((t) >> 16) & 0xFFu), \
    static_cast<char>(((t) >> 8) & 0xFFu), static_cast<char>((t) & 0xFFu)
#else
#define DAEGUN_UNTAG(t) \
    (char)(((t) >> 24) & 0xFFu), (char)(((t) >> 16) & 0xFFu), (char)(((t) >> 8) & 0xFFu), (char)((t) & 0xFFu)
#endif

A tag's four characters, first to last, as four char arguments.

It expands to four expressions with commas between them, so it goes where four arguments go: printf("%c%c%c%c", DAEGUN_UNTAG(tag)). It is not one value, so it cannot be assigned to a variable, and its argument is evaluated four times.

A tag read from a font may hold any byte, not only printable ones.

daegun_tag tags[64];
size_t count = 0;
if (daegun_font_table_tags(font, tags, 64, &count) != DAEGUN_OK) return 1;

char name[5];
snprintf(name, sizeof name, "%c%c%c%c", DAEGUN_UNTAG(tags[0]));
/* Inter has 19 tables, and the first in sorted order is "GDEF". */
DAEGUN_HORIZONTAL
#define DAEGUN_HORIZONTAL 0

Across the line: the orientation of horizontal text.

DAEGUN_HORIZONTAL and DAEGUN_VERTICAL are the two orientation codes. A call with an orientation parameter takes one to say which way a metric, an advance or a run of text goes: daegun_font_advance, daegun_font_line_metrics and daegun_font_caret_positions are three such calls. A value that is neither answers DAEGUN_INVALID_ARGUMENT.

uint32_t gid = 0;
if (daegun_font_glyph_id(font, 'A', &gid) != DAEGUN_OK) return 1;
double across = 0.0;
if (daegun_font_advance(font, gid, NULL, DAEGUN_HORIZONTAL, &across) != DAEGUN_OK) return 1;
/* Inter's A moves the pen 1413 units along a horizontal line. */
DAEGUN_VERTICAL
#define DAEGUN_VERTICAL 1

Down the line: the orientation of vertical text, as CJK text is often set.

A font without vertical metrics still answers. daegun_font_advance then moves each glyph down by the height between the font's ascender and descender.

uint32_t gid = 0;
if (daegun_font_glyph_id(font, 'A', &gid) != DAEGUN_OK) return 1;
double across = 0.0, down = 0.0;
if (daegun_font_advance(font, gid, NULL, DAEGUN_HORIZONTAL, &across) != DAEGUN_OK) return 1;
if (daegun_font_advance(font, gid, NULL, DAEGUN_VERTICAL, &down) != DAEGUN_OK) return 1;
/* Source Han Sans sets a Latin A 574 units across a line, and 1000 down one. */

Fonts

daegun/font.h: opening a font and asking what it is. Its names, its tables, its variation axes and the locations they make, and the caches that keep its work.

DAEGUN_STYLE_NORMAL
#define DAEGUN_STYLE_NORMAL 0

The font stands upright: it is neither italic nor oblique.

The DAEGUN_STYLE_ codes say whether a font's glyphs stand upright or lean. daegun_font_style writes one of them: at the default instance from flags in the font's OS/2 and head tables, and at any other location from the flags daegun works out for the instance there. Weight is no part of it: a bold upright font is still this code.

DAEGUN_STYLE_ITALIC
#define DAEGUN_STYLE_ITALIC 1

The font is italic: its OS/2 table or its head table flags it so.

DAEGUN_STYLE_OBLIQUE
#define DAEGUN_STYLE_OBLIQUE 2

The font is oblique: a slanted form of an upright design, flagged in its OS/2 table.

A font may set this flag beside the italic one. daegun_font_style looks for it first, so such a font answers oblique.

DAEGUN_CACHE_SHAPE
#define DAEGUN_CACHE_SHAPE 0

The shape cache: shaped runs, kept so that shaping the same text again is a lookup.

The DAEGUN_CACHE_ codes name a font's four caches. Pass one to daegun_font_set_cache_budget, daegun_font_cache_stats, daegun_font_clear_cache or daegun_font_set_cache_pool to say which cache you mean. Each cache has a budget in bytes of its own, which is a ceiling it grows into as the font is used and never memory set aside. No cache changes a result: it only saves doing the work again. Each is dead weight for some caller, which is why each can be turned down or off.

This one holds runs keyed by their text and how it was to be shaped. daegun_font_shape and daegun_font_shape_bidi keep a run in it only where their daegun_shape_options set no more than a direction, the text around the run, a language and a seed script: a request that sets features, a script or any other option, or shapes bottom to top, is shaped afresh each time. daegun_font_layout keeps the runs of the lines it sets. daegun_font_shape_into neither reads it nor adds to it.

Its budget starts at 8 MiB. Each run is charged for its entry as well as its text and glyphs, so a budget of 0 keeps none. Text that never repeats gains nothing from it.

A run is kept only where it costs no more than an eighth of the list it goes into, or 64 KiB where that is more, so that one long run cannot push out the rest. A budget below 4 MiB is one list, and one of 4 MiB or more is split over 16 (see daegun_font_set_cache_budget), so at the default budget the limit is 64 KiB: a paragraph of a few thousand characters is shaped again at every call.

Outside the cache's count, a thread may hold on to as many as 32 of the runs it read last, across all fonts. daegun_thread_release lets them go.

DAEGUN_CACHE_INSTANCE
#define DAEGUN_CACHE_INSTANCE 1

The instance cache: what each location of a variable font has built.

One entry for each location the font has been used at, other than the default instance: the tables that location changes, what drawing, measuring and shaping build there, and the font file daegun_font_instance made of it. That call adds an entry for the default instance too, and for a static font, as the file it builds is kept here. So does subsetting, with daegun_font_subset, daegun_font_subset_text or daegun_font_glyph_closure, which keeps what it reads at its location here, the default included.

Its budget starts at 64 MiB. Past it the location used longest ago goes first, but the location used last always stays, whatever the budget, so a font used at one fixed weight runs well on a budget of 0.

Outside the cache, each thread holds on to the locations it last read at, up to 2, until it reads at others, ends or calls daegun_thread_release.

DAEGUN_CACHE_OUTLINE
#define DAEGUN_CACHE_OUTLINE 2

The outline cache: glyph outlines that daegun_font_prewarm drew ahead of use.

It holds only what daegun_font_prewarm puts in it: drawing a glyph that was not prewarmed keeps nothing. daegun_font_outline, daegun_font_glyph_bounds and the other calls that draw the unhinted outline of a glyph replay a kept outline in place of decoding the glyph again. Its budget starts at 4 MiB.

DAEGUN_CACHE_RASTER
#define DAEGUN_CACHE_RASTER 3

The raster cache: images of glyphs that a rasterizer drew, lent again in place of being drawn.

Its budget is 0 until you set one with daegun_font_set_cache_budget, so it starts off, and a rasterizer draws a glyph's image again at every call. Give it a budget, and an image that daegun_rasterizer_glyph, daegun_rasterizer_color_glyph or daegun_rasterizer_distance_field drew is kept: the same glyph asked for again at the same size, location and options comes from the cache.

It is not the rasterizer's own cache of what it learned of each outline, which daegun_rasterizer_set_cache_budget sets.

Metrics

daegun/metrics.h: a font's metrics in font units, y up. Line spacing, the OS/2 and post tables, STAT, tracking and the flags a PDF writer needs.

DAEGUN_PDF_FIXED_PITCH
#define DAEGUN_PDF_FIXED_PITCH 0x01u

Every glyph of the font has the same width.

The DAEGUN_PDF_ bits are the flags of a PDF font descriptor, which daegun_font_pdf_flags answers together as one number. Each has the value PDF gives it, so the number goes into a PDF file as it is. Test one with &.

This one is set when the post table's isFixedPitch field is not 0.

DAEGUN_PDF_SERIF
#define DAEGUN_PDF_SERIF 0x02u

The glyphs have serifs.

Set when the class in the OS/2 table's family class, the high byte of family_class in a daegun_os2, is one of the serif classes: 1 to 5, or 7.

DAEGUN_PDF_SYMBOLIC
#define DAEGUN_PDF_SYMBOLIC 0x04u

The font is a symbol font, or maps a character outside the Adobe standard Latin set.

Set for a Windows symbol font, one whose cmap table has a symbol subtable and none keyed by Unicode, and for any font that maps a character outside that set. Control codes are not counted. So a font that covers Greek, as Inter does, counts as symbolic.

Where it is not set, DAEGUN_PDF_NONSYMBOLIC is.

DAEGUN_PDF_SCRIPT
#define DAEGUN_PDF_SCRIPT 0x08u

The glyphs look like handwriting.

Set when the class in the OS/2 table's family class is 10, the script class.

DAEGUN_PDF_NONSYMBOLIC
#define DAEGUN_PDF_NONSYMBOLIC 0x20u

The font is not a symbol font and maps no character outside the Adobe standard Latin set, control codes aside.

Set whenever DAEGUN_PDF_SYMBOLIC is not, so every answer holds exactly one of the two. A font with no cmap table gets this one.

DAEGUN_PDF_ITALIC
#define DAEGUN_PDF_ITALIC 0x40u

The glyphs slant.

Set when the italic angle, the one daegun_font_italic_angle answers, is not 0.

DAEGUN_DEFAULT_POINT_SIZE
#define DAEGUN_DEFAULT_POINT_SIZE 12

The point size tracking is read at when no usable size is given: 12.

daegun_font_tracking reads at this size when its point_size is not a finite number above zero. Shaping tracks a run at it when its options are NULL, set has_point_size false, or give a point_size that is not a finite number above zero.

DAEGUN_STAT_SINGLE
#define DAEGUN_STAT_SINGLE 0

One value on one axis.

The DAEGUN_STAT_ codes are the kind of a daegun_stat_value. STAT has four kinds of value, and the code says which fields of the struct mean anything. For this kind they are axis_index and value: Inter names 700 on its weight axis Bold.

DAEGUN_STAT_RANGE
#define DAEGUN_STAT_RANGE 1

A range of values on one axis, with the value the name is for.

The fields that count are axis_index, min, max and value, which holds the nominal value. Source Serif 4 calls weights 650 to 750 Bold, named for 700.

DAEGUN_STAT_LINKED
#define DAEGUN_STAT_LINKED 2

One value on one axis, with a second value it is linked to.

The fields that count are axis_index, value and linked_value. The link pairs two styles: Inter links its Regular, at weight 400, to 700, which is where a bold button takes you.

DAEGUN_STAT_COMBO
#define DAEGUN_STAT_COMBO 3

Values on several axes, named together.

The fields that count are combo_start and combo_count, which pick the pairs of axis and value out of the array daegun_stat_combo_values lends. axis_index and value are 0 for this kind.

Glyphs

daegun/glyphs.h: from characters to glyphs, and what each glyph measures. Its id for a character, its advance, its box, its vertical origin, its ligature carets, its class and its name.

DAEGUN_GLYPH_CLASS_BASE
#define DAEGUN_GLYPH_CLASS_BASE 0

A base glyph: a letter or symbol that stands by itself, and that marks attach to.

The DAEGUN_GLYPH_CLASS_ codes are what daegun_font_glyph_class writes: the kind of glyph a font's GDEF table says one is. They are daegun's own codes and count from 0, where the table itself numbers the same four classes from 1.

int32_t kind = -1;
if (daegun_font_glyph_class(font, 2, &kind) == DAEGUN_OK) {
    switch (kind) {
    case DAEGUN_GLYPH_CLASS_BASE: /* a letter or symbol */ break;
    case DAEGUN_GLYPH_CLASS_LIGATURE: /* several characters in one glyph */ break;
    case DAEGUN_GLYPH_CLASS_MARK: /* drawn onto the glyph before it */ break;
    case DAEGUN_GLYPH_CLASS_COMPONENT: /* a part of another glyph */ break;
    }
}
/* Glyph 2 of Inter, its A, is a base. */
DAEGUN_GLYPH_CLASS_LIGATURE
#define DAEGUN_GLYPH_CLASS_LIGATURE 1

A ligature: one glyph that stands for several characters, such as fi.

DAEGUN_GLYPH_CLASS_MARK
#define DAEGUN_GLYPH_CLASS_MARK 2

A mark: an accent or vowel sign that attaches to another glyph.

DAEGUN_GLYPH_CLASS_COMPONENT
#define DAEGUN_GLYPH_CLASS_COMPONENT 3

A component: one part of a glyph that is built from several.

DAEGUN_MAX_GLYPH_NAME
#define DAEGUN_MAX_GLYPH_NAME 63

The longest glyph name, in bytes.

It is the limit the post table sets on a name, and daegun holds the names of a CFF font to it as well. A buffer of DAEGUN_MAX_GLYPH_NAME + 1 bytes fits any name daegun_font_glyph_name writes, with the NUL after it.

char name[DAEGUN_MAX_GLYPH_NAME + 1]; /* room for any name and its NUL */
size_t count = 0;
if (daegun_font_glyph_name(font, 0, name, sizeof name, &count) != DAEGUN_OK) return 1;
/* Glyph 0 of Inter is named ".notdef". */

Shaping

daegun/shape.h: text to glyphs placed in font units, one run or the runs of mixed-direction text, and the carets that hit testing reads off them.

DAEGUN_SHAPER_DEFAULT
#define DAEGUN_SHAPER_DEFAULT 0

The general shaping model, for a script that needs none of its own, such as Latin, Greek or Cyrillic.

The DAEGUN_SHAPER_ codes name the model a run went through. daegun_shaped_run_shaper reports it, and daegun_shaper_name gives a code's name. A newer library may report a code this header has no name for.

daegun picks the model in this order. First, script of the options set to qaag, in either case, picks DAEGUN_SHAPER_MYANMAR_ZAWGYI, whatever the text. Otherwise the script of the run decides, which is seed_script of the options or, without one, the first script found in the text, and a run with none takes this general model. Hebrew, Thai, Lao, Hangul and Khmer always take their own model. Arabic and Syriac take the joining model in horizontal text and this general one in vertical text, and Syriac this one too where the font files its lookups under DFLT. The Indic scripts, Myanmar and the scripts of the Universal Shaping Engine go by the script tag the font's lookups come from. Where that is DFLT or latn, as it is when the font has no lookups under the script's own tag or the script the options name but has them under one of those, they take the general model, with no syllables and no reordering. A font with neither, or with no GSUB table, leaves them their own. An Indic script under a version 3 tag, such as dev3, takes the Universal model, and Myanmar under its older tag mymr the general one. Last, where the font's morx table shapes the run, any model but the general one gives way to DAEGUN_SHAPER_DUMBER.

DAEGUN_SHAPER_DUMBER
#define DAEGUN_SHAPER_DUMBER 1

The model that stands in for a script's own where the font's morx table shapes the text, as in Apple's fonts.

daegun applies no features, masks or reordering of its own and leaves the work to the font. Text whose script takes the general model, such as Latin, reports DAEGUN_SHAPER_DEFAULT even where morx shapes it, so this code does not tell you whether morx ran.

DAEGUN_SHAPER_ARABIC
#define DAEGUN_SHAPER_ARABIC 2

Joining, for Arabic and Syriac.

DAEGUN_SHAPER_HANGUL
#define DAEGUN_SHAPER_HANGUL 3

Hangul's syllables.

DAEGUN_SHAPER_HEBREW
#define DAEGUN_SHAPER_HEBREW 4

Hebrew's marks.

DAEGUN_SHAPER_INDIC
#define DAEGUN_SHAPER_INDIC 5

The syllables of the Indic scripts, Devanagari and its kin.

DAEGUN_SHAPER_KHMER
#define DAEGUN_SHAPER_KHMER 6

Khmer's syllables.

DAEGUN_SHAPER_MYANMAR
#define DAEGUN_SHAPER_MYANMAR 7

Myanmar's syllables.

DAEGUN_SHAPER_MYANMAR_ZAWGYI
#define DAEGUN_SHAPER_MYANMAR_ZAWGYI 8

Myanmar text in the older Zawgyi encoding.

You ask for it by setting script of a daegun_shape_options to DAEGUN_TAG('Q', 'a', 'a', 'g'), in upper or lower case. The language of the options plays no part. Its syllables stay in the order given: nothing is reordered but a run of combining marks, which goes in Unicode's canonical order as in any text.

DAEGUN_SHAPER_THAI
#define DAEGUN_SHAPER_THAI 9

The marks of Thai and Lao.

DAEGUN_SHAPER_UNIVERSAL
#define DAEGUN_SHAPER_UNIVERSAL 10

The Universal Shaping Engine, for the many complex scripts it covers, such as Tibetan, Sinhala and Javanese, and for an Indic script whose lookups the font files under a version 3 tag such as dev3.

DAEGUN_DIRECTION_DEFAULT
#define DAEGUN_DIRECTION_DEFAULT 0

The direction the text itself reads in: left to right or right to left, taken from its script.

The DAEGUN_DIRECTION_ codes go in direction of a daegun_shape_options. This one is 0, so options from daegun_shape_options_default already hold it.

DAEGUN_DIRECTION_LTR
#define DAEGUN_DIRECTION_LTR 1

Left to right, as Latin text runs.

DAEGUN_DIRECTION_RTL
#define DAEGUN_DIRECTION_RTL 2

Right to left, as Arabic and Hebrew text run.

DAEGUN_DIRECTION_TTB
#define DAEGUN_DIRECTION_TTB 3

Top to bottom, for vertical text.

Each advance then runs down the line, and each glyph's offset puts it under the pen.

DAEGUN_DIRECTION_BTT
#define DAEGUN_DIRECTION_BTT 4

Bottom to top.

DAEGUN_CLUSTER_MONOTONE_GRAPHEMES
#define DAEGUN_CLUSTER_MONOTONE_GRAPHEMES 0

A grapheme is one cluster, and clusters stay in text order. The default.

The DAEGUN_CLUSTER_ codes go in cluster_level of a daegun_shape_options and decide how daegun_shaped_run_clusters groups the text. At this level every glyph of one user-perceived character shares a cluster, and glyphs that shaping reorders end up sharing one too, so the order holds. It is what hit testing and selection want.

DAEGUN_CLUSTER_MONOTONE_CHARACTERS
#define DAEGUN_CLUSTER_MONOTONE_CHARACTERS 1

A character is one cluster, and clusters stay in text order.

Characters that shaping reorders still end up sharing a cluster, so the order holds.

DAEGUN_CLUSTER_CHARACTERS
#define DAEGUN_CLUSTER_CHARACTERS 2

A character is one cluster, in whatever order shaping leaves the glyphs.

Clusters may go backward along the run.

DAEGUN_CLUSTER_GRAPHEMES
#define DAEGUN_CLUSTER_GRAPHEMES 3

A grapheme is one cluster, in whatever order shaping leaves the glyphs.

DAEGUN_IGNORABLES_HIDE
#define DAEGUN_IGNORABLES_HIDE 0

Default ignorables stay in the run as an invisible glyph with an advance of 0. The default.

The DAEGUN_IGNORABLES_ codes go in ignorables of a daegun_shape_options. They say what becomes of the invisible characters, such as the zero width joiner and variation selectors. Hidden, each keeps its place in the clusters. The glyph is the font's space unless the options name an invisible_glyph. In a font with no space glyph, and none named, there is nothing to hide them with, and they are left out of the run, as with DAEGUN_IGNORABLES_REMOVE.

DAEGUN_IGNORABLES_REMOVE
#define DAEGUN_IGNORABLES_REMOVE 1

Default ignorables are left out of the run altogether.

DAEGUN_IGNORABLES_PRESERVE
#define DAEGUN_IGNORABLES_PRESERVE 2

Default ignorables are shaped like any other character, with whatever glyph the font maps them to.

For one the font has no glyph for, that is not_found_glyph of the options, .notdef by default.

DAEGUN_BASE_AUTO
#define DAEGUN_BASE_AUTO -1

The paragraph's direction is decided by its first strongly directional character, and is left to right if it has none.

The DAEGUN_BASE_ codes are the base direction of a paragraph, wherever a call takes one, such as daegun_font_shape_bidi. The base direction is the way the paragraph as a whole reads, which decides the order its runs are set in.

DAEGUN_BASE_LTR
#define DAEGUN_BASE_LTR 0

The paragraph reads left to right, whatever its first character.

DAEGUN_BASE_RTL
#define DAEGUN_BASE_RTL 1

The paragraph reads right to left, whatever its first character.

Unicode

daegun/unicode.h: text analysis that needs no font. Bidi, grapheme and word boundaries, line breaking, scripts and character properties. Every position is a byte offset where a character starts.

DAEGUN_SCRIPT_DIRECTION_LEFT_TO_RIGHT
#define DAEGUN_SCRIPT_DIRECTION_LEFT_TO_RIGHT 0

The script is written left to right across a line, as Latin, Greek and Devanagari are.

The two DAEGUN_SCRIPT_DIRECTION_ codes are what daegun_script_direction writes. It goes by the direction most of a script's letters have. So a script that was once written either way, as Old Italic was, answers this one, and so do Common and Inherited.

DAEGUN_SCRIPT_DIRECTION_RIGHT_TO_LEFT
#define DAEGUN_SCRIPT_DIRECTION_RIGHT_TO_LEFT 1

The script is written right to left across a line, as Arabic, Hebrew and Syriac are.

DAEGUN_GC_UNASSIGNED
#define DAEGUN_GC_UNASSIGNED 0

Cn: a code point that no character is assigned to.

The 30 DAEGUN_GC_ codes are the values of the Unicode General_Category property, which sorts every code point into one kind, and daegun_general_category writes one. Unicode abbreviates each to two letters, the first for its major class: L for a letter, M for a mark, N for a number, P for punctuation, S for a symbol, Z for a separator and C for the rest. Each summary here opens with that abbreviation.

The codes are numbered in the alphabetical order of the abbreviations, apart from this one, which comes first. So each major class is one unbroken range: a letter is any code from DAEGUN_GC_LOWERCASE_LETTER to DAEGUN_GC_UPPERCASE_LETTER, a mark any from DAEGUN_GC_SPACING_MARK to DAEGUN_GC_NONSPACING_MARK, and the same holds for numbers, punctuation, symbols and separators.

int32_t category = 0;
if (daegun_general_category(0x0378, &category) != DAEGUN_OK) return 1;
/* U+0378 has no character assigned: category is DAEGUN_GC_UNASSIGNED. */

if (daegun_general_category(0x00E9, &category) != DAEGUN_OK) return 1;
/* The codes of a major class are consecutive, so one range test asks whether it is a letter. */
bool letter = category >= DAEGUN_GC_LOWERCASE_LETTER && category <= DAEGUN_GC_UPPERCASE_LETTER;
/* U+00E9, an e with an acute accent, is DAEGUN_GC_LOWERCASE_LETTER, so letter is true. */
DAEGUN_GC_CONTROL
#define DAEGUN_GC_CONTROL 1

Cc: a control code, such as a tab or a line feed.

DAEGUN_GC_FORMAT
#define DAEGUN_GC_FORMAT 2

Cf: a format character, which draws nothing itself, such as the zero width joiner, the soft hyphen or a bidi control.

DAEGUN_GC_PRIVATE_USE
#define DAEGUN_GC_PRIVATE_USE 3

Co: a private use character, such as U+E000, whose meaning is left to whoever uses it.

DAEGUN_GC_SURROGATE
#define DAEGUN_GC_SURROGATE 4

Cs: a surrogate code point, U+D800 to U+DFFF.

daegun_general_category never writes it. A surrogate is not a character that text can hold, and passing one answers DAEGUN_INVALID_ARGUMENT.

DAEGUN_GC_LOWERCASE_LETTER
#define DAEGUN_GC_LOWERCASE_LETTER 5

Ll: a lowercase letter, such as a.

DAEGUN_GC_MODIFIER_LETTER
#define DAEGUN_GC_MODIFIER_LETTER 6

Lm: a modifier letter, such as the small raised h U+02B0 or the Japanese long vowel mark U+30FC.

DAEGUN_GC_OTHER_LETTER
#define DAEGUN_GC_OTHER_LETTER 7

Lo: a letter of a script without case, such as an Arabic or Hebrew letter, a kana or a CJK ideograph.

DAEGUN_GC_TITLECASE_LETTER
#define DAEGUN_GC_TITLECASE_LETTER 8

Lt: a titlecase letter, a digraph whose first part alone is capital, such as U+01C5.

DAEGUN_GC_UPPERCASE_LETTER
#define DAEGUN_GC_UPPERCASE_LETTER 9

Lu: an uppercase letter, such as A.

DAEGUN_GC_SPACING_MARK
#define DAEGUN_GC_SPACING_MARK 10

Mc: a combining mark that takes room of its own on the line, such as the Devanagari sign U+0903.

DAEGUN_GC_ENCLOSING_MARK
#define DAEGUN_GC_ENCLOSING_MARK 11

Me: a combining mark that surrounds the character it follows, such as the enclosing circle U+20DD.

DAEGUN_GC_NONSPACING_MARK
#define DAEGUN_GC_NONSPACING_MARK 12

Mn: a combining mark that takes no room of its own, such as the acute accent U+0301.

DAEGUN_GC_DECIMAL_NUMBER
#define DAEGUN_GC_DECIMAL_NUMBER 13

Nd: a decimal digit, 0 to 9 and the digits of other scripts, such as the Arabic-Indic zero U+0660.

DAEGUN_GC_LETTER_NUMBER
#define DAEGUN_GC_LETTER_NUMBER 14

Nl: a number written as a letter, such as the Roman numeral U+2160.

DAEGUN_GC_OTHER_NUMBER
#define DAEGUN_GC_OTHER_NUMBER 15

No: any other number, such as the superscript two U+00B2 or the fraction U+00BD.

DAEGUN_GC_CONNECT_PUNCTUATION
#define DAEGUN_GC_CONNECT_PUNCTUATION 16

Pc: punctuation that joins words, such as the underscore.

DAEGUN_GC_DASH_PUNCTUATION
#define DAEGUN_GC_DASH_PUNCTUATION 17

Pd: a dash or a hyphen.

DAEGUN_GC_CLOSE_PUNCTUATION
#define DAEGUN_GC_CLOSE_PUNCTUATION 18

Pe: a closing bracket, such as ).

DAEGUN_GC_FINAL_PUNCTUATION
#define DAEGUN_GC_FINAL_PUNCTUATION 19

Pf: a closing quotation mark, such as U+00BB or U+2019.

DAEGUN_GC_INITIAL_PUNCTUATION
#define DAEGUN_GC_INITIAL_PUNCTUATION 20

Pi: an opening quotation mark, such as U+00AB or U+201C.

DAEGUN_GC_OTHER_PUNCTUATION
#define DAEGUN_GC_OTHER_PUNCTUATION 21

Po: any other punctuation, such as !, a comma or a period.

DAEGUN_GC_OPEN_PUNCTUATION
#define DAEGUN_GC_OPEN_PUNCTUATION 22

Ps: an opening bracket, such as (.

DAEGUN_GC_CURRENCY_SYMBOL
#define DAEGUN_GC_CURRENCY_SYMBOL 23

Sc: a currency sign, such as $.

DAEGUN_GC_MODIFIER_SYMBOL
#define DAEGUN_GC_MODIFIER_SYMBOL 24

Sk: a modifier symbol, an accent that stands by itself, such as ^.

DAEGUN_GC_MATH_SYMBOL
#define DAEGUN_GC_MATH_SYMBOL 25

Sm: a math symbol, such as + or =.

DAEGUN_GC_OTHER_SYMBOL
#define DAEGUN_GC_OTHER_SYMBOL 26

So: any other symbol, such as the copyright sign U+00A9 or an emoji.

DAEGUN_GC_LINE_SEPARATOR
#define DAEGUN_GC_LINE_SEPARATOR 27

Zl: the line separator, U+2028.

DAEGUN_GC_PARAGRAPH_SEPARATOR
#define DAEGUN_GC_PARAGRAPH_SEPARATOR 28

Zp: the paragraph separator, U+2029.

DAEGUN_GC_SPACE_SEPARATOR
#define DAEGUN_GC_SPACE_SEPARATOR 29

Zs: a space, such as U+0020, the no-break space U+00A0 or the ideographic space U+3000.

DAEGUN_VO_ROTATED
#define DAEGUN_VO_ROTATED 0

R: the character lies on its side in vertical text, turned a quarter clockwise, as Latin letters are set.

The four DAEGUN_VO_ codes say how a character is set in vertical text. They are the values of the Vertical_Orientation property of UAX #50, and daegun_vertical_orientation writes one.

In vertical text daegun_font_layout, with its default DAEGUN_TEXT_ORIENTATION_MIXED, sets a character upright where its code is DAEGUN_VO_UPRIGHT or DAEGUN_VO_TRANSFORMED_UPRIGHT, and where it is DAEGUN_VO_TRANSFORMED_ROTATED and daegun_vertical_form finds a vertical form of it. Otherwise it is turned on its side.

int32_t orientation = 0;
if (daegun_vertical_orientation('a', &orientation) != DAEGUN_OK) return 1;
bool upright = orientation == DAEGUN_VO_UPRIGHT || orientation == DAEGUN_VO_TRANSFORMED_UPRIGHT;
/* orientation is DAEGUN_VO_ROTATED: a Latin letter lies on its side in vertical text. */
DAEGUN_VO_TRANSFORMED_ROTATED
#define DAEGUN_VO_TRANSFORMED_ROTATED 1

Tr: upright where Unicode encodes a vertical form of the character, as it does for the fullwidth parentheses, and on its side otherwise, as the long vowel mark U+30FC is.

DAEGUN_VO_TRANSFORMED_UPRIGHT
#define DAEGUN_VO_TRANSFORMED_UPRIGHT 2

Tu: upright, in a vertical form where the font draws one, as the ideographic comma U+3001 and full stop U+3002.

DAEGUN_VO_UPRIGHT
#define DAEGUN_VO_UPRIGHT 3

U: the character stands upright in vertical text, as CJK ideographs, kana and emoji are set.

Layout

daegun/layout.h: paragraphs laid out in lines, aligned, in either writing mode, and one line justified by a font's JSTF table. All in font units.

DAEGUN_ALIGN_START
#define DAEGUN_ALIGN_START 0

Lines sit at the start edge of the measure: the left in a left-to-right paragraph, the right in a right-to-left one. The default.

The DAEGUN_ALIGN_ codes go in align of a daegun_layout_options and say where each line sits in the measure, which is max_inline_size. You see the result in the offset of each daegun_layout_run. Where the measure is infinite there is no edge to align to, so the lines align against the widest one. In vertical text, read top for left and bottom for right.

DAEGUN_ALIGN_END
#define DAEGUN_ALIGN_END 1

Lines sit at the end edge of the measure: the right in a left-to-right paragraph, the left in a right-to-left one.

DAEGUN_ALIGN_CENTER
#define DAEGUN_ALIGN_CENTER 2

Lines are centered in the measure.

DAEGUN_ALIGN_JUSTIFY
#define DAEGUN_ALIGN_JUSTIFY 3

Lines are spread to fill the measure by widening their spaces, except a line that ends at a hard break, such as the last line of a paragraph, which sits at the start edge.

The extra width goes into the advances of the line's spaces, each in proportion to its width, so the runs come back already justified. The lines left alone are those whose daegun_layout_line has hard_break true. A line with no space to widen sits at the start edge too.

With DAEGUN_BREAK_OPTIMAL a line may also be set a little too full and its spaces narrowed, by a third of their width at most. On a line with tabs only the spaces after the last tab change, so the tab stops hold.

DAEGUN_WRITING_HORIZONTAL
#define DAEGUN_WRITING_HORIZONTAL 0

Lines run across and stack downward. The default.

The DAEGUN_WRITING_ codes go in writing_mode of a daegun_layout_options. In the two vertical modes lines run top to bottom, max_inline_size is the height of a column, the baseline of each daegun_layout_line is measured from the left edge of the block, and the font's vertical line metrics space the columns. daegun_writing_mode_is_vertical tells the vertical modes from this one.

DAEGUN_WRITING_VERTICAL_RL
#define DAEGUN_WRITING_VERTICAL_RL 1

Lines run top to bottom and stack leftward, so the first line is the rightmost, as Japanese is set.

DAEGUN_WRITING_VERTICAL_LR
#define DAEGUN_WRITING_VERTICAL_LR 2

Lines run top to bottom and stack rightward, so the first line is the leftmost, as Mongolian is set.

DAEGUN_TEXT_ORIENTATION_MIXED
#define DAEGUN_TEXT_ORIENTATION_MIXED 0

In vertical text each character stands the way Unicode says it does: upright for CJK and the like, on its side for scripts such as Latin. The default.

The DAEGUN_TEXT_ORIENTATION_ codes go in text_orientation of a daegun_layout_options and say how characters stand in vertical lines. They change nothing in horizontal text. The rule Unicode gives is the vertical orientation of UAX #50. upright of each daegun_layout_run says which way a run came out.

A character UAX #50 sets upright only in a vertical form, such as a CJK bracket, stands upright where Unicode has a vertical presentation form for it and lies on its side where it has none. The long vowel mark ー (U+30FC) has none, so inside a katakana word it comes out as a sideways run of its own. The font's vertical glyphs are not consulted.

DAEGUN_TEXT_ORIENTATION_UPRIGHT
#define DAEGUN_TEXT_ORIENTATION_UPRIGHT 1

In vertical text every character stands upright.

The bidirectional algorithm is not run in this mode: every character is treated as left to right, so each run has a level of 0 and the text goes down the line in the order it is written.

DAEGUN_TEXT_ORIENTATION_SIDEWAYS
#define DAEGUN_TEXT_ORIENTATION_SIDEWAYS 2

In vertical text every character lies on its side.

DAEGUN_BREAK_GREEDY
#define DAEGUN_BREAK_GREEDY 0

Each line takes as much text as fits before the next one starts. The default.

The DAEGUN_BREAK_ codes go in strategy of a daegun_layout_options and say how the places to break lines are chosen. Greedy breaking decides one line at a time: it breaks at the last opportunity that still fits and never goes back.

DAEGUN_BREAK_OPTIMAL
#define DAEGUN_BREAK_OPTIMAL 1

The breaks of a whole paragraph are chosen together so that its lines come out evenly full, as the Knuth-Plass total-fit algorithm chooses them.

It may end a line early where that keeps the lines after it from being too loose or too tight. Breaking at a soft hyphen counts against a choice, and two hyphenated lines in a row count more, so a paragraph hyphenates only where its spacing gains from it.

DAEGUN_JSTF_SHRINKAGE_ENABLE_GSUB
#define DAEGUN_JSTF_SHRINKAGE_ENABLE_GSUB 0

The GSUB lookups a level turns on to shrink a line.

The DAEGUN_JSTF_ codes name the eight lookup lists a JSTF priority level may hold, for which of daegun_jstf_priorities_lookups. A list belongs to shrinking a line or to extending it, turns lookups on or off, and names lookups of GSUB, the font's substitution table, or of GPOS, its positioning table.

DAEGUN_JSTF_SHRINKAGE_DISABLE_GSUB
#define DAEGUN_JSTF_SHRINKAGE_DISABLE_GSUB 1

The GSUB lookups a level turns off to shrink a line.

DAEGUN_JSTF_SHRINKAGE_ENABLE_GPOS
#define DAEGUN_JSTF_SHRINKAGE_ENABLE_GPOS 2

The GPOS lookups a level turns on to shrink a line.

DAEGUN_JSTF_SHRINKAGE_DISABLE_GPOS
#define DAEGUN_JSTF_SHRINKAGE_DISABLE_GPOS 3

The GPOS lookups a level turns off to shrink a line.

DAEGUN_JSTF_EXTENSION_ENABLE_GSUB
#define DAEGUN_JSTF_EXTENSION_ENABLE_GSUB 4

The GSUB lookups a level turns on to extend a line.

DAEGUN_JSTF_EXTENSION_DISABLE_GSUB
#define DAEGUN_JSTF_EXTENSION_DISABLE_GSUB 5

The GSUB lookups a level turns off to extend a line.

DAEGUN_JSTF_EXTENSION_ENABLE_GPOS
#define DAEGUN_JSTF_EXTENSION_ENABLE_GPOS 6

The GPOS lookups a level turns on to extend a line.

DAEGUN_JSTF_EXTENSION_DISABLE_GPOS
#define DAEGUN_JSTF_EXTENSION_DISABLE_GPOS 7

The GPOS lookups a level turns off to extend a line.

DAEGUN_ADJUST_SHRINK
#define DAEGUN_ADJUST_SHRINK 0

Make the line narrower, with a level's shrinkage lookups.

The DAEGUN_ADJUST_ codes say which way a JSTF level adjusts a line. You pass one as adjustment to daegun_font_shape_justified, and daegun_font_justify reports the way it went in adjustment of a daegun_justification.

DAEGUN_ADJUST_EXTEND
#define DAEGUN_ADJUST_EXTEND 1

Make the line wider, with a level's extension lookups.

Outlines

daegun/outline.h: a glyph's shape, as the font stores it in font units, hinted in pixels, or prepared for a rasterizer of your own, with the paths, pens, strokes, curves and polygons around it.

DAEGUN_VERB_MOVE
#define DAEGUN_VERB_MOVE 0

The verb that starts a contour, taking one point: where the contour begins.

The DAEGUN_VERB_ values are the bytes that daegun_path_verbs lends, and the verbs of a daegun_path_view. A path keeps its points apart from its verbs, in one list, and each verb takes the next few off the front of it: one for a move or a line, two for a quadratic curve, three for a cubic and none for a close. To read a path, walk the verbs and step through the points as you go.

daegun_path *path = daegun_path_new();
daegun_path_move_to(path, 0.0f, 0.0f);
daegun_path_line_to(path, 100.0f, 0.0f);
daegun_path_quad_to(path, 150.0f, 50.0f, 100.0f, 100.0f);
daegun_path_curve_to(path, 60.0f, 130.0f, 20.0f, 130.0f, 0.0f, 100.0f);
daegun_path_close(path);

size_t verb_count = 0, point_count = 0;
const uint8_t *verbs = daegun_path_verbs(path, &verb_count);
const daegun_point *p = daegun_path_points(path, &point_count);
for (size_t i = 0; i < verb_count; i++) {
    switch (verbs[i]) {
    case DAEGUN_VERB_MOVE: /* a contour starts at p[0] */
        p += 1;
        break;
    case DAEGUN_VERB_LINE: /* a line to p[0] */
        p += 1;
        break;
    case DAEGUN_VERB_QUAD: /* a curve bent toward p[0], ending at p[1] */
        p += 2;
        break;
    case DAEGUN_VERB_CUBIC: /* a curve with the controls p[0] and p[1], ending at p[2] */
        p += 3;
        break;
    case DAEGUN_VERB_CLOSE: /* the contour closes: no point */
        break;
    }
}
/* The five verbs took 1 + 1 + 2 + 3 + 0 points, which is all 7 the path has. */

daegun_path_free(path);
DAEGUN_VERB_LINE
#define DAEGUN_VERB_LINE 1

The verb for a straight line, taking one point: where the line ends.

DAEGUN_VERB_QUAD
#define DAEGUN_VERB_QUAD 2

The verb for a quadratic curve, taking two points: its control, then its end.

DAEGUN_VERB_CUBIC
#define DAEGUN_VERB_CUBIC 3

The verb for a cubic curve, taking three points: its two controls, then its end.

DAEGUN_VERB_CLOSE
#define DAEGUN_VERB_CLOSE 4

The verb that closes a contour, taking no point.

DAEGUN_JOIN_MITER
#define DAEGUN_JOIN_MITER 0

A sharp corner: the stroke's two edges run on until they meet in a point.

The DAEGUN_JOIN_ codes go in join of a daegun_stroke_style and say how a stroke turns a corner of the path. A code that is none of them answers DAEGUN_INVALID_ARGUMENT.

A miter is the only join that reads miter_limit. The sharper the turn, the further the point reaches, and where it would reach past that many half widths from the corner, the corner is cut straight across as DAEGUN_JOIN_BEVEL cuts it. That is what keeps a hairpin turn from growing a spike.

DAEGUN_JOIN_ROUND
#define DAEGUN_JOIN_ROUND 1

A rounded corner: an arc around the corner, half the width of the stroke in radius.

The arc reaches the pen as short lines, as close to the true arc as the call's tolerance asks.

DAEGUN_JOIN_BEVEL
#define DAEGUN_JOIN_BEVEL 2

A corner cut straight across, from the end of one edge of the stroke to the start of the next.

DAEGUN_CAP_BUTT
#define DAEGUN_CAP_BUTT 0

The stroke ends flat, exactly where the path ends.

The DAEGUN_CAP_ codes go in cap of a daegun_stroke_style and say how a stroke ends an open contour. A closed contour has no ends, and so no caps. A code that is none of them answers DAEGUN_INVALID_ARGUMENT.

A contour that is a single point, a daegun_path_move_to with nothing after it, has no length to stroke, and its caps are all that can show. With this cap it draws nothing.

daegun_path *line = daegun_path_new();
daegun_path_move_to(line, 0.0f, 0.0f);
daegun_path_line_to(line, 100.0f, 0.0f);

daegun_path *stroked = daegun_path_new();
daegun_pen pen;
if (daegun_path_as_pen(stroked, &pen) != DAEGUN_OK) return 1;
daegun_stroke_style style = { 10.0f, DAEGUN_CAP_BUTT, DAEGUN_JOIN_MITER, 4.0f };
if (daegun_path_stroke(line, &style, 0.1f, &pen) != DAEGUN_OK) return 1;
daegun_bounds box;
if (daegun_path_bounds(stroked, &box) != DAEGUN_OK) return 1;
/* Butt caps stop at the ends of the line: the stroke runs from x 0 to 100. */

style.cap = DAEGUN_CAP_SQUARE;
daegun_path_clear(stroked);
if (daegun_path_stroke(line, &style, 0.1f, &pen) != DAEGUN_OK) return 1;
if (daegun_path_bounds(stroked, &box) != DAEGUN_OK) return 1;
/* Square caps add half the width at each end: from x -5 to 105. */

daegun_path_free(stroked);
daegun_path_free(line);
DAEGUN_CAP_ROUND
#define DAEGUN_CAP_ROUND 1

The stroke ends in a half circle that reaches half its width past the end of the path.

A contour that is a single point left open, a daegun_path_move_to with nothing after it, draws a full circle as wide as the stroke. Closed, it draws nothing.

DAEGUN_CAP_SQUARE
#define DAEGUN_CAP_SQUARE 2

The stroke ends flat, half its width past the end of the path.

A contour that is a single point left open draws a square as wide as the stroke, its sides along the axes. Closed, it draws nothing.

DAEGUN_MAX_FLATTEN_POINTS
#define DAEGUN_MAX_FLATTEN_POINTS 1048576

The most points daegun_path_flatten keeps, and the most daegun_path_stroke_simplified holds to resolve.

Either call answers DAEGUN_LIMIT_EXCEEDED for a result past it. One curve can flatten into as many as 4,096 lines, so without a bound a path of many curves, flattened as finely as it goes, could ask for hundreds of millions of points. Text comes nowhere near it: Inter's W, flattened for 32 px, is 34 points.

DAEGUN_HINT_NONE
#define DAEGUN_HINT_NONE 0

No hinting: the outline stays where scaling puts it.

The DAEGUN_HINT_ codes say which hinter fits a glyph to the pixel grid. Hinting moves the points of an outline, at one pixel size, so that its heights and stems land on whole pixels, which keeps small text sharp. A code goes in hinting of a daegun_outline_options, and daegun_font_hinted_outline takes one as its mode.

The four values are 0, 1, 3 and 4. There is no 2, and a code that is none of the four answers DAEGUN_INVALID_ARGUMENT. This one is 0, so options from daegun_outline_options_default already hold it. daegun_font_hinted_outline answers DAEGUN_ABSENT for it.

DAEGUN_HINT_FONT
#define DAEGUN_HINT_FONT 1

The font's own hints: its TrueType bytecode, or its CFF or CFF2 hints.

TrueType bytecode fits y to the grid. It moves x only in a font that declares native ClearType, which a font does with the INSTCTRL instruction. In every other font x stays as drawn, so advances and subpixel positions match the unhinted outline.

A glyph these hints would leave where scaling puts it is not hinted: a simple TrueType glyph that carries no instructions, for one, or any glyph that draws nothing. A composite glyph may be taken with no instructions at all: where the font asks for it, with the ROUND_XY_TO_GRID flag of a component, placing a part rounds its offset to the grid in y, and in x too in a font that declares native ClearType. Inter has no bytecode, so under this mode its H stays unhinted, while its À, built from an A and an accent set above it, is taken.

DAEGUN_HINT_AUTO
#define DAEGUN_HINT_AUTO 3

One hinter chosen once for the whole font: the autohinter for a TrueType font with no hinting programs to speak of, else the font's own hints.

The autohinter reads the shapes of the outlines and needs nothing from the font. It fits y to the grid and leaves x as scaled. Under this mode it takes every glyph of a font that has TrueType outlines, no font program (the fpgm table) and a CVT program (the prep table) of at most 7 bytes, which is room for a dropout setting and nothing else.

Any other font, CFF and CFF2 fonts included, is hinted as DAEGUN_HINT_FONT hints it, and a glyph its hints leave alone stays unhinted: it is not passed on to the autohinter. The choice depends on the font alone, never on the glyph or the size, so all the text of one font is hinted one way.

DAEGUN_HINT_AUTO_FORCE
#define DAEGUN_HINT_AUTO_FORCE 4

The autohinter for every glyph, whatever hints the font has.

It takes the glyphs of CFF and CFF2 fonts too. A glyph that draws nothing, such as a space, has nothing to hint and stays unhinted.

DAEGUN_POINT_ON_CURVE
#define DAEGUN_POINT_ON_CURVE 0

The point lies on the outline.

The DAEGUN_POINT_ codes are what daegun_hinted_outline_kinds gives for each point of a hinted outline: on the curve, or a control point of a curve of one kind. Two on-curve points in a row are joined by a straight line.

DAEGUN_POINT_QUADRATIC
#define DAEGUN_POINT_QUADRATIC 1

The control point of a quadratic curve, as TrueType outlines have.

The curve runs between the on-curve points on either side of it. Two of these in a row have an on-curve point implied halfway between them, as TrueType stores its outlines. daegun_hinted_outline_draw works that out for you.

DAEGUN_POINT_CUBIC
#define DAEGUN_POINT_CUBIC 2

One of the two control points of a cubic curve, as CFF outlines have.

They come in pairs between two on-curve points.

Color

daegun/color.h: color glyphs. Bitmap strikes, COLR layers and palettes, paint graphs and the scenes made from them, and the color math to sample a gradient and composite a layer.

DAEGUN_BITMAP_PNG
#define DAEGUN_BITMAP_PNG 0

The bitmap is a PNG file, as the font stores it.

The DAEGUN_BITMAP_ codes are the format of a daegun_bitmap_info and say what its data holds. With this one it is a whole PNG file. daegun does not decode pictures, so hand the bytes to a PNG decoder of your own. width and height are 0, as the PNG's header holds its size.

Every picture from sbix comes this way, and so do the PNG pictures of the other tables, such as those CBDT holds in Noto Color Emoji. daegun never hands out decoded color pixels.

DAEGUN_BITMAP_COVERAGE
#define DAEGUN_BITMAP_COVERAGE 1

The bitmap is decoded coverage: one byte a pixel, from 0 for empty to 255 for fully covered.

A monochrome or grayscale strike comes this way, whatever depth the font stores it at: 1, 2, 4 or 8 bits a pixel all become a byte from 0 to 255. data holds width times height bytes, row after row from the top with no padding between them. It carries no color: draw it as a mask in the text's color.

DAEGUN_FILL_NONZERO
#define DAEGUN_FILL_NONZERO 0

A point is inside the path where its contours wind around it a nonzero number of times, as glyph outlines are filled.

The DAEGUN_FILL_ codes say which points a path covers where its contours overlap or sit inside one another. They are the rule of a daegun_scene_op that fills and of a daegun_clip_shape, and the rule that daegun_rasterizer_path and daegun_rasterizer_path_into take.

Under this rule a contour that runs one way around a point counts +1 and one that runs the other way counts -1, and the point is inside where the sum is not 0. So two contours that overlap in the same direction fill as one shape, and a contour cuts a hole only if it runs against the one around it. A scene made by daegun_font_color_scene uses this rule for every fill and every clip shape.

DAEGUN_FILL_EVENODD
#define DAEGUN_FILL_EVENODD 1

A point is inside the path where its contours wind around it an odd number of times.

A contour inside another then cuts a hole whichever way it runs, and where two contours overlap the overlap is left empty.

DAEGUN_COMPOSITE_CLEAR
#define DAEGUN_COMPOSITE_CLEAR 0

Nothing is left: the layer and what lies under it are both cleared.

The DAEGUN_COMPOSITE_ codes say how a layer combines with what lies under it. One is the blend of a daegun_scene_op whose kind is DAEGUN_OP_PUSH_LAYER, the mode of a daegun_paint_node whose kind is DAEGUN_PAINT_COMPOSITE, and the mode that daegun_blend and daegun_composite take. The values are COLR's own composite-mode numbers, 0 to 27.

In these entries the layer is the source, the thing being composited, and the backdrop is what lies under it. The first 13 codes, this one to DAEGUN_COMPOSITE_PLUS, are the Porter-Duff operators. They have no formula for mixing the two colors: each says how much of the layer and how much of the backdrop is kept, going by where each has ink. The other 15, DAEGUN_COMPOSITE_SCREEN to DAEGUN_COMPOSITE_HSL_LUMINOSITY, are the blend modes of W3C Compositing and Blending: where the two overlap they mix the two colors by a formula, and the result is then laid over the backdrop as DAEGUN_COMPOSITE_SRC_OVER lays it.

A font's composite mode that COLR does not define is read as this one, as the OpenType spec asks. daegun_composite does the arithmetic of any of the 28 for one pixel.

DAEGUN_COMPOSITE_SRC
#define DAEGUN_COMPOSITE_SRC 1

The layer alone: the backdrop is dropped, where the layer has ink and where it has none.

DAEGUN_COMPOSITE_DEST
#define DAEGUN_COMPOSITE_DEST 2

The backdrop alone: the layer is dropped.

DAEGUN_COMPOSITE_SRC_OVER
#define DAEGUN_COMPOSITE_SRC_OVER 3

The layer over the backdrop, the ordinary way to stack one thing on another.

The backdrop shows through wherever the layer is transparent. It is the mode a fill is drawn with, and the one the outer layer of a COLR composite is pushed with.

DAEGUN_COMPOSITE_DEST_OVER
#define DAEGUN_COMPOSITE_DEST_OVER 4

The backdrop over the layer, so the layer shows only where the backdrop is transparent.

DAEGUN_COMPOSITE_SRC_IN
#define DAEGUN_COMPOSITE_SRC_IN 5

The layer, only where the backdrop has ink. The backdrop itself is dropped.

DAEGUN_COMPOSITE_DEST_IN
#define DAEGUN_COMPOSITE_DEST_IN 6

The backdrop, only where the layer has ink. The layer itself is dropped.

DAEGUN_COMPOSITE_SRC_OUT
#define DAEGUN_COMPOSITE_SRC_OUT 7

The layer, only where the backdrop has no ink. The backdrop itself is dropped.

DAEGUN_COMPOSITE_DEST_OUT
#define DAEGUN_COMPOSITE_DEST_OUT 8

The backdrop, only where the layer has no ink: the layer cuts its shape out of it.

DAEGUN_COMPOSITE_SRC_ATOP
#define DAEGUN_COMPOSITE_SRC_ATOP 9

The layer over the backdrop, but only where the backdrop has ink.

DAEGUN_COMPOSITE_DEST_ATOP
#define DAEGUN_COMPOSITE_DEST_ATOP 10

The backdrop over the layer, but only where the layer has ink.

DAEGUN_COMPOSITE_XOR
#define DAEGUN_COMPOSITE_XOR 11

Each where the other has no ink: where both have ink, neither shows.

DAEGUN_COMPOSITE_PLUS
#define DAEGUN_COMPOSITE_PLUS 12

The two added together, channel by channel, which lightens where they overlap.

DAEGUN_COMPOSITE_SCREEN
#define DAEGUN_COMPOSITE_SCREEN 13

Lightens: the complements of the two colors are multiplied, and the result complemented.

The result is never darker than either color. Black changes nothing and white gives white.

DAEGUN_COMPOSITE_OVERLAY
#define DAEGUN_COMPOSITE_OVERLAY 14

Multiplies where the backdrop's color is dark and screens where it is light.

It is DAEGUN_COMPOSITE_HARD_LIGHT with the two colors' roles swapped.

DAEGUN_COMPOSITE_DARKEN
#define DAEGUN_COMPOSITE_DARKEN 15

The darker of the two colors, channel by channel.

DAEGUN_COMPOSITE_LIGHTEN
#define DAEGUN_COMPOSITE_LIGHTEN 16

The lighter of the two colors, channel by channel.

DAEGUN_COMPOSITE_COLOR_DODGE
#define DAEGUN_COMPOSITE_COLOR_DODGE 17

Brightens the backdrop by the layer's color: the lighter the layer, the brighter the result.

DAEGUN_COMPOSITE_COLOR_BURN
#define DAEGUN_COMPOSITE_COLOR_BURN 18

Darkens the backdrop by the layer's color: the darker the layer, the darker the result.

DAEGUN_COMPOSITE_HARD_LIGHT
#define DAEGUN_COMPOSITE_HARD_LIGHT 19

Multiplies where the layer's color is dark and screens where it is light.

DAEGUN_COMPOSITE_SOFT_LIGHT
#define DAEGUN_COMPOSITE_SOFT_LIGHT 20

A gentler hard light: darkens the backdrop where the layer's color is dark and lightens it where the layer's is light.

DAEGUN_COMPOSITE_DIFFERENCE
#define DAEGUN_COMPOSITE_DIFFERENCE 21

The difference of the two colors, channel by channel: the darker taken from the lighter.

DAEGUN_COMPOSITE_EXCLUSION
#define DAEGUN_COMPOSITE_EXCLUSION 22

Like DAEGUN_COMPOSITE_DIFFERENCE, with less contrast.

DAEGUN_COMPOSITE_MULTIPLY
#define DAEGUN_COMPOSITE_MULTIPLY 23

Darkens: the two colors multiplied, channel by channel.

The result is never lighter than either color. White changes nothing and black gives black.

DAEGUN_COMPOSITE_HSL_HUE
#define DAEGUN_COMPOSITE_HSL_HUE 24

The layer's hue with the backdrop's saturation and luminosity.

DAEGUN_COMPOSITE_HSL_SATURATION
#define DAEGUN_COMPOSITE_HSL_SATURATION 25

The layer's saturation with the backdrop's hue and luminosity.

DAEGUN_COMPOSITE_HSL_COLOR
#define DAEGUN_COMPOSITE_HSL_COLOR 26

The layer's hue and saturation with the backdrop's luminosity.

DAEGUN_COMPOSITE_HSL_LUMINOSITY
#define DAEGUN_COMPOSITE_HSL_LUMINOSITY 27

The layer's luminosity with the backdrop's hue and saturation.

DAEGUN_EXTEND_PAD
#define DAEGUN_EXTEND_PAD 0

A gradient's end colors carry on: the first stop's color before its start and the last stop's after its end.

The DAEGUN_EXTEND_ codes say how a gradient goes on past its first and last stops. One is the extend of a daegun_gradient and of a daegun_paint_node that is a gradient. The values are COLR's own.

DAEGUN_EXTEND_REPEAT
#define DAEGUN_EXTEND_REPEAT 1

A gradient's stops repeat past its ends, first to last each time.

DAEGUN_EXTEND_REFLECT
#define DAEGUN_EXTEND_REFLECT 2

A gradient's stops repeat past its ends, every other time reversed, so the colors run back and forth.

DAEGUN_OP_FILL
#define DAEGUN_OP_FILL 0

A path filled with a color or a gradient.

The DAEGUN_OP_ codes are the kind of a daegun_scene_op, and say which of its fields to read. A fill is the only op that draws. The other four come in pairs that bracket the ops between them: a clip pushed and popped, and a layer pushed and popped.

DAEGUN_OP_PUSH_CLIP
#define DAEGUN_OP_PUSH_CLIP 1

Starts a clip: until the DAEGUN_OP_POP_CLIP that pairs with it, drawing shows only inside its shapes.

Its shapes are entries shapes_start up to shapes_end of what daegun_scene_shapes lends, taken together: a point that any one of them covers is inside. A clip pushed inside another shows only where both do.

DAEGUN_OP_POP_CLIP
#define DAEGUN_OP_POP_CLIP 2

Ends the clip that the last DAEGUN_OP_PUSH_CLIP still open started.

DAEGUN_OP_PUSH_LAYER
#define DAEGUN_OP_PUSH_LAYER 3

Starts a layer: until the DAEGUN_OP_POP_LAYER that pairs with it, drawing goes into a transparent layer of its own.

It carries the blend and opacity its layer is composited with when it is popped.

DAEGUN_OP_POP_LAYER
#define DAEGUN_OP_POP_LAYER 4

Ends the last layer still open and composites it onto what lies below.

The layer goes on by the blend and opacity of the DAEGUN_OP_PUSH_LAYER that started it. This op has no fields of its own.

DAEGUN_GRADIENT_LINEAR
#define DAEGUN_GRADIENT_LINEAR 0

A gradient along a line: values hold x0, y0, x1, y1.

The DAEGUN_GRADIENT_ codes are the kind of a daegun_gradient, and say what its values hold. Positions are in the gradient's own space, which its transform takes to the scene's.

Offset 0 is at (x0, y0) and offset 1 at (x1, y1). The color changes along that line and stays the same across it. The last two values are 0. COLR gives a linear gradient a third point that turns it, and that point is already worked into these two.

DAEGUN_GRADIENT_RADIAL
#define DAEGUN_GRADIENT_RADIAL 1

A gradient between two circles: values hold x0, y0, r0, x1, y1, r1.

Offset 0 is on the circle of radius r0 around (x0, y0), and offset 1 on the circle of radius r1 around (x1, y1). Between and beyond them the circle's center and radius change at a steady rate. Where no such circle of a radius of 0 or more passes through a point, the gradient paints nothing there, as a radial gradient does outside its cone.

DAEGUN_GRADIENT_SWEEP
#define DAEGUN_GRADIENT_SWEEP 2

A gradient around a center: values hold cx, cy, start_angle, end_angle.

The color goes by the angle of a point about (cx, cy), in degrees counterclockwise from the positive x axis, y being up. Offset 0 is at start_angle and offset 1 at end_angle. The last two values are 0.

daegun takes a point's angle from 0 up to 360 and doesn't wrap it into the gradient's range, so an angle below 0 or past 360 is reached only through extend. Glyph 19 of the COLR test font sweeps from -22.5 to 22.5 under DAEGUN_EXTEND_PAD, and a point at -10 degrees counts as 350, past the end, so it takes the last stop's color.

DAEGUN_INTERPOLATE_LINEAR_LIGHT
#define DAEGUN_INTERPOLATE_LINEAR_LIGHT 0

A gradient blends between its stops in linear light, with alpha premultiplied, as the OpenType spec asks.

The DAEGUN_INTERPOLATE_ codes go in interpolation of daegun_scene_ramp and say how a ramp mixes the colors of two neighboring stops. This one turns the stops from sRGB into linear light, mixes them there with each color weighed by its alpha, and turns the result back. Either way the color daegun_ramp_at answers is sRGB with straight alpha, and a pixel that falls exactly on a stop gets that stop's color.

/* Glyph 8 is filled with a gradient that runs from red at x = 100 to blue at x = 900, in font units. */
daegun_scene *scene = NULL;
if (daegun_font_color_scene(font, 8, NULL, NULL, &scene) != DAEGUN_OK) return 1;

const double identity[6] = { 1.0, 0.0, 0.0, 1.0, 0.0, 0.0 };
daegun_ramp *linear = NULL, *srgb = NULL;
if (daegun_scene_ramp(scene, 0, identity, DAEGUN_INTERPOLATE_LINEAR_LIGHT, &linear) != DAEGUN_OK) return 1;
if (daegun_scene_ramp(scene, 0, identity, DAEGUN_INTERPOLATE_SRGB, &srgb) != DAEGUN_OK) return 1;

/* Halfway along, at x = 500, which is the center of the pixel at 499.5. */
daegun_rgba a, b;
if (daegun_ramp_at(linear, 499.5, 249.5, &a) != DAEGUN_OK) return 1;
if (daegun_ramp_at(srgb, 499.5, 249.5, &b) != DAEGUN_OK) return 1;
/* In linear light the middle is 188, 0, 188. In sRGB it is 128, 0, 128. */

daegun_ramp_free(linear);
daegun_ramp_free(srgb);
daegun_scene_free(scene);
DAEGUN_INTERPOLATE_SRGB
#define DAEGUN_INTERPOLATE_SRGB 1

A gradient blends between its stops in the stored sRGB values, with alpha straight.

It mixes the numbers the palette holds, each of the four bytes on its own. Halfway from red to blue is 128, 0, 128 this way, where DAEGUN_INTERPOLATE_LINEAR_LIGHT gives 188, 0, 188.

DAEGUN_PAINT_LAYERS
#define DAEGUN_PAINT_LAYERS 0

A stack of paints: its children are painted in turn, the first at the bottom.

The DAEGUN_PAINT_ codes are the kind of a daegun_paint_node, one for each kind of paint that COLR version 1 defines. A glyph's paints form a tree. Some fill: a solid color or a gradient, over whatever region the paints above them have clipped to. DAEGUN_PAINT_GLYPH clips its child to an outline, the transforming paints place their child, and a composite combines two children. Each code says which fields of the node it reads. Of the rest, values, center, glyph, extend, mode, color, foreground, has_center and stops_count are 0, while end is set for every paint and stops_start holds where the graph's stops stood when the paint came, so go by stops_count.

Positions are in font units with y up, and angles are in degrees counterclockwise. A paint that scales, rotates or skews keeps one point fixed: the node's center where its has_center is true, and the origin otherwise.

A layers paint has any number of children, and may have none. A paint daegun can't read from the font or that the font leaves out, one with more than 64 paints above it, one past what a glyph's walk may read (100,000 paints and 1,000,000 stops, each plus one for every 4 bytes of the COLR table), and one that would lead back into a paint it lies inside each come as a layers paint with no children, which draws nothing.

DAEGUN_PAINT_GLYPH
#define DAEGUN_PAINT_GLYPH 1

Its one child painted inside the outline of the node's glyph.

The outline is the clip: nothing of the child shows outside it. It is the outline of an ordinary glyph, which daegun_font_outline draws.

DAEGUN_PAINT_COLR_GLYPH
#define DAEGUN_PAINT_COLR_GLYPH 2

Another color glyph painted in place: the paint graph of the node's glyph, which follows as this paint's one child.

DAEGUN_PAINT_SOLID
#define DAEGUN_PAINT_SOLID 3

One color over the whole region clipped to: the node's color, or the text's color where foreground is true.

It has no children.

DAEGUN_PAINT_LINEAR_GRADIENT
#define DAEGUN_PAINT_LINEAR_GRADIENT 4

A gradient along a line, over the whole region clipped to.

The node's values hold x0, y0, x1, y1, x2, y2. The colors run from the point (x0, y0) to the point (x1, y1), and (x2, y2) sets the rotation: lines of one color run parallel to the line from (x0, y0) to (x2, y2). The gradient's stops are stops_count of the graph's stops from stops_start, and extend says how the colors go on past the first and last stop. It has no children.

DAEGUN_PAINT_RADIAL_GRADIENT
#define DAEGUN_PAINT_RADIAL_GRADIENT 5

A gradient between two circles, over the whole region clipped to.

The node's values hold x0, y0, r0, x1, y1, r1. The colors start on the circle centered at (x0, y0) with radius r0 and end on the one centered at (x1, y1) with radius r1. Stops and extend are read as for DAEGUN_PAINT_LINEAR_GRADIENT. It has no children.

DAEGUN_PAINT_SWEEP_GRADIENT
#define DAEGUN_PAINT_SWEEP_GRADIENT 6

A gradient that sweeps around a point, over the whole region clipped to.

The node's values hold cx, cy, start_angle, end_angle. The colors run around the point (cx, cy) from the one angle to the other. Angles are in degrees, counted counterclockwise from the direction of the positive x axis. Stops and extend are read as for DAEGUN_PAINT_LINEAR_GRADIENT. It has no children.

DAEGUN_PAINT_TRANSFORM
#define DAEGUN_PAINT_TRANSFORM 7

Its one child drawn through a matrix.

The node's values hold xx, yx, xy, yy, dx, dy. A point (x, y) of the child lands at (xx*x + xy*y + dx, yx*x + yy*y + dy). That is the order of every transform in daegun, so the six values can go straight into one.

DAEGUN_PAINT_TRANSLATE
#define DAEGUN_PAINT_TRANSLATE 8

Its one child moved by dx, dy, the first two of the node's values, in font units.

DAEGUN_PAINT_SCALE
#define DAEGUN_PAINT_SCALE 9

Its one child scaled by sx across and sy up, the first two of the node's values.

The scale is about the node's center where has_center is true, and about the origin otherwise.

DAEGUN_PAINT_SCALE_UNIFORM
#define DAEGUN_PAINT_SCALE_UNIFORM 10

Its one child scaled the same both ways by s, the first of the node's values.

The scale is about the node's center where has_center is true, and about the origin otherwise.

DAEGUN_PAINT_ROTATE
#define DAEGUN_PAINT_ROTATE 11

Its one child turned by angle, the first of the node's values, in degrees counterclockwise.

It turns about the node's center where has_center is true, and about the origin otherwise.

DAEGUN_PAINT_SKEW
#define DAEGUN_PAINT_SKEW 12

Its one child slanted by x_angle and y_angle, the first two of the node's values, in degrees.

About the origin, a point (x, y) of the child lands at (x - tan(x_angle)*y, y + tan(y_angle)*x). So a positive x_angle leans the top of the child to the left, the way a counterclockwise turn would. Where has_center is true the skew is about the node's center in place of the origin. At a right angle the tangent is infinite, and daegun's own scene leans by nothing there.

DAEGUN_PAINT_COMPOSITE
#define DAEGUN_PAINT_COMPOSITE 13

Two children combined: the first, the source, composited onto the second, the backdrop, by the node's mode.

mode is a DAEGUN_COMPOSITE_ code. A composite always has its two children, the source first. daegun_composite works one pixel of such a combination.

Math

daegun/mathtable.h: the MATH table, for setting formulas. Its constants, each glyph's italic correction and kerning, and the larger variants and assemblies a stretched glyph is built from, in font units at a location.

DAEGUN_MATH_KERN_TOP_RIGHT
#define DAEGUN_MATH_KERN_TOP_RIGHT 0

The top right corner of a glyph, where a superscript after the glyph meets it.

The DAEGUN_MATH_KERN_ codes name the four corners of a glyph where a subscript or superscript can meet it. One goes in corner of daegun_font_math_kern, as a font can give each corner its own kerns.

The right-hand corners serve a glyph as a base: a superscript meets it at the top right, a subscript at the bottom right. The left-hand corners serve a glyph as a script: a superscript turns its bottom left corner to its base, and a subscript its top left. They also serve a base whose scripts are set before it. To kern a base and a script, add the base's kern at its corner to the script's kern at the corner facing it.

DAEGUN_MATH_KERN_TOP_LEFT
#define DAEGUN_MATH_KERN_TOP_LEFT 1

The top left corner of a glyph, where a superscript set before the glyph meets it.

It is also the corner the glyph turns to its base when it is itself a subscript.

DAEGUN_MATH_KERN_BOTTOM_RIGHT
#define DAEGUN_MATH_KERN_BOTTOM_RIGHT 2

The bottom right corner of a glyph, where a subscript after the glyph meets it.

DAEGUN_MATH_KERN_BOTTOM_LEFT
#define DAEGUN_MATH_KERN_BOTTOM_LEFT 3

The bottom left corner of a glyph, where a subscript set before the glyph meets it.

It is also the corner the glyph turns to its base when it is itself a superscript.

Raw tables

daegun/raw.h: font data at the byte level, for tools that read or write a table daegun has no call for. Bounds-checked reads and writes, the structures several tables share, loca and glyf, and building a font file from its tables.

DAEGUN_AAT_CLASS_END_OF_TEXT
#define DAEGUN_AAT_CLASS_END_OF_TEXT 0

The class a state machine is handed once, after the last glyph: class 0.

Every AAT state table holds a few classes and states at numbers fixed in advance, and these constants name three of them. Read the entry for this class with daegun_aat_state_table_entry, in the state the machine reached, to see what it does when the text ends.

Class 1, out of bounds, has no constant here: it is what daegun_aat_state_table_class answers for a glyph the class table doesn't list.

DAEGUN_AAT_CLASS_DELETED_GLYPH
#define DAEGUN_AAT_CLASS_DELETED_GLYPH 2

The class of glyph 0xFFFF, class 2: the mark a machine leaves where it deleted a glyph.

daegun_aat_state_table_class answers it for glyph 0xFFFF, whatever the class table says.

DAEGUN_AAT_STATE_START_OF_TEXT
#define DAEGUN_AAT_STATE_START_OF_TEXT 0

The state every machine starts in, state 0.

Pass it as state to daegun_aat_state_table_entry to read what a machine does with the first glyph.

Rasterizing

daegun/raster.h: daegun's own rasterizer, which turns glyphs and paths into pixels, and what any rasterizer needs beyond outlines. Subpixel layouts with their filters, and an atlas packer.

DAEGUN_MAX_OVERSAMPLE
#define DAEGUN_MAX_OVERSAMPLE 4

The most samples a layout takes for each pixel, in either direction.

Three limits on what daegun_subpixel_layout_from_weights takes, each answering DAEGUN_INVALID_ARGUMENT past it. DAEGUN_MAX_OVERSAMPLE bounds oversample_x and oversample_y. DAEGUN_MAX_TAPS, which is it plus 4, bounds taps_x and taps_y: room for every sample of a pixel at the highest oversampling and two more on each side. DAEGUN_MAX_WEIGHTS, the taps squared, is the most weights one channel has, so a buffer of that many floats holds any channel that daegun_subpixel_layout_weights lends.

The layouts daegun builds stay well inside them: 3 samples one way and 1 the other, and at most 7 taps.

DAEGUN_MAX_TAPS
#define DAEGUN_MAX_TAPS 8

The most taps a layout's filter has, in either direction.

DAEGUN_MAX_WEIGHTS
#define DAEGUN_MAX_WEIGHTS 64

The most weights one channel of a filter has: DAEGUN_MAX_TAPS squared.

DAEGUN_STRIPES_RGB
#define DAEGUN_STRIPES_RGB 0

Red, green, blue: from left to right for stripes side by side, from top to bottom for stacked ones.

The DAEGUN_STRIPES_ codes are the order that daegun_subpixel_layout_horizontal, daegun_subpixel_layout_vertical and daegun_subpixel_layout_unfiltered take. Most panels run their stripes red, green, blue from the left, which is this one. Some run them the other way, and so does an RGB panel turned upside down. With the wrong order the edges of every stem show as color.

The order changes which samples each channel reads, not the order of the bytes: a pixel of the image is red, green, blue either way. A code that is neither answers DAEGUN_INVALID_ARGUMENT.

DAEGUN_STRIPES_BGR
#define DAEGUN_STRIPES_BGR 1

Blue, green, red: from left to right, or from top to bottom for stacked stripes.

DAEGUN_MAX_SIDE
#define DAEGUN_MAX_SIDE 16384

The most pixels an image a rasterizer lends is across or down.

daegun_rasterizer_glyph, daegun_rasterizer_color_glyph, daegun_rasterizer_path and daegun_rasterizer_distance_field answer DAEGUN_LIMIT_EXCEEDED for an image wider or taller than this. A draw into a daegun_target takes any size, so draw a glyph that large in tiles with daegun_rasterizer_glyph_into.

DAEGUN_MAX_DRAW_BYTES
#define DAEGUN_MAX_DRAW_BYTES 268435456

The most bytes a draw whose image a rasterizer lends may hold in its buffers, the image among them: 256 MiB.

An outline can reach DAEGUN_MAX_SIDE even at a few pixels to the em, through a large transform or points far out, and the working buffers of such a draw would take gigabytes, so it is refused with DAEGUN_LIMIT_EXCEEDED before its image and working buffers are allocated. Plain coverage takes about 10 bytes a pixel, the image's own byte included, so the limit comes well before DAEGUN_MAX_SIDE on a square image, and sooner still for a subpixel layout, a color glyph with layers or a DAEGUN_FIELD_MSDF field. A draw into a daegun_target holds the pixels you gave it and works in bands of rows of a bounded size, so this limit does not apply there.

DAEGUN_GAMMA_LINEAR
#define DAEGUN_GAMMA_LINEAR 0

Coverage as it is, exact: each byte is the share of the pixel the glyph covers. The default.

The DAEGUN_GAMMA_ codes go in gamma of a daegun_raster_options and say how coverage becomes the alpha you blend with. Pick by how your compositor blends. Coverage is a share of area, and it is right to blend with as it stands only if the blend happens in linear light: a compositor that converts colors to linear light, blends there and converts back wants this one.

Most simple compositors blend the sRGB bytes directly, out = text * a + back * (1 - a) on the encoded values, which makes dark text on a light ground heavier than it should be and light text on a dark ground thinner. DAEGUN_GAMMA_SRGB hands such a compositor the alpha that makes its blend of the text color over its opposite come out where the linear one would. The difference is large in the middle of the range: a pixel half covered reads 128 as coverage, 68 for black text and 188 for white text. A pixel not covered stays 0 and one fully covered stays 255.

uint32_t gid = 0;
if (daegun_font_glyph_id(font, 'o', &gid) != DAEGUN_OK) return 1;
daegun_rasterizer *rasterizer = daegun_rasterizer_new();
daegun_raster_options opts;
if (daegun_raster_options_default(&opts, sizeof opts) != DAEGUN_OK) return 1;
opts.gamma = DAEGUN_GAMMA_LINEAR;
daegun_image image;
if (daegun_rasterizer_glyph(rasterizer, font, gid, NULL, 12.0f, &opts, &image) != DAEGUN_OK) return 1;
/* Find a pixel of the o that is half covered: 128. */
size_t half = 0;
while (half < image.pixels_len && image.pixels[half] != 128) half++;

/* For black text blended in sRGB, its alpha is 68, and for white text 188. */
opts.gamma = DAEGUN_GAMMA_SRGB;
opts.text = (daegun_rgba){ 0, 0, 0, 255 };
if (daegun_rasterizer_glyph(rasterizer, font, gid, NULL, 12.0f, &opts, &image) != DAEGUN_OK) return 1;
opts.text = (daegun_rgba){ 255, 255, 255, 255 };
if (daegun_rasterizer_glyph(rasterizer, font, gid, NULL, 12.0f, &opts, &image) != DAEGUN_OK) return 1;
daegun_rasterizer_free(rasterizer);
DAEGUN_GAMMA_SRGB
#define DAEGUN_GAMMA_SRGB 1

Alpha for a compositor that blends sRGB values as they are, worked out for text of the options' text color.

Each coverage level becomes the alpha whose plain sRGB blend of the text color over its opposite, the color with every channel inverted, lands where blending by coverage in linear light would. So black text is corrected for a white ground and white text for a black one. contrast of the options can thicken the coverage first.

DAEGUN_FIELD_SDF
#define DAEGUN_FIELD_SDF 0

A signed distance field: one byte a pixel, the distance to the outline.

The DAEGUN_FIELD_ codes are the field that daegun_rasterizer_distance_field takes. Both kinds store, for each pixel, the distance from its center to the outline, positive inside, as the byte 127.5 + 127.5 * d / spread, rounded and kept within 0 to 255.

This one is the plain field and the smaller. Scaled up, its corners round off, as a distance alone cannot say which of two edges a pixel is near.

DAEGUN_FIELD_MSDF
#define DAEGUN_FIELD_MSDF 1

A multi-channel signed distance field: three bytes a pixel whose median is the distance, which keeps corners sharp when the image is scaled up.

Each channel measures to its own share of the outline's edges. A shader takes the median of the three, which away from corners is the same as the single-channel field. Where overlapping contours meet too closely to be merged, the corner they make rounds off as in a DAEGUN_FIELD_SDF field.

Header machinery

The macros daegun/base.h defines for compilers: how each call is declared, which pointers may be NULL, which array an argument counts, and the layout checks. They are why the declarations in the headers look busier than the ones shown here. A program writes very few of them itself, and each header also guards itself with a DAEGUN_<NAME>_H macro of its own.

DAEGUN_API
#if defined(__GNUC__) && defined(_WIN32) && defined(DAEGUN_DLL)
#define DAEGUN_API __attribute__((dllimport, nothrow))
#elif defined(__GNUC__)
#define DAEGUN_API __attribute__((nothrow))
#elif defined(_MSC_VER) && defined(__cplusplus) && defined(DAEGUN_DLL)
#define DAEGUN_API __declspec(dllimport) __declspec(nothrow)
#elif defined(_MSC_VER) && defined(__cplusplus)
#define DAEGUN_API __declspec(nothrow)
#elif defined(_WIN32) && defined(DAEGUN_DLL)
#define DAEGUN_API __declspec(dllimport)
#else
#define DAEGUN_API
#endif

How every call is declared: imported from the DLL where DAEGUN_DLL asks for it, and marked as throwing nothing.

It is part of the declaration of every function in the headers, and you never write it yourself. It does two jobs, and which of them depends on the compiler.

On Windows with DAEGUN_DLL defined, it declares each call as imported from daegun-2.dll (dllimport), which saves every call a jump through a stub. Without DAEGUN_DLL, and anywhere off Windows, it imports nothing.

To GCC, clang and MSVC's C++ compiler it also says that the call throws nothing (nothrow), so C++ code around a call needs no cleanup path for an exception out of it. C compiled for MSVC, by MSVC or by clang-cl, takes no such mark, so there it is __declspec(dllimport) or nothing. Under any other compiler it is __declspec(dllimport) on Windows with DAEGUN_DLL defined, and empty otherwise.

DAEGUN_CALL
#if defined(_MSC_VER)
#define DAEGUN_CALL __cdecl
#elif defined(__i386__) && (defined(__GNUC__) || defined(__clang__))
#define DAEGUN_CALL __attribute__((cdecl))
#else
#define DAEGUN_CALL
#endif

C's calling convention, pinned on every call.

It sits between each call's return type and its name, and you never write it yourself. Some compiler switches change the convention of every function that doesn't name one: /Gv and /Gz under MSVC, and -mrtd under GCC and clang on 32-bit x86. With the convention spelled out in each declaration, a program built with one of those switches still calls daegun the right way, and links.

It is __cdecl under MSVC, __attribute__((cdecl)) under GCC and clang on 32-bit x86, and empty everywhere else.

DAEGUN_CALLBACK
#define DAEGUN_CALLBACK DAEGUN_CALL

C's calling convention for a function you hand to daegun.

It is DAEGUN_CALL under a second name, and every callback type in the headers carries it: the functions of a daegun_pen and of a daegun_paint_visitor, a daegun_word_segmenter, and the key_at that daegun_search_records takes.

This is one of the two macros here that you may write yourself. Build with /Gv or /Gz under MSVC, or with -mrtd on 32-bit x86, and a function you leave unmarked takes that other convention. The compiler then refuses it where you hand it to daegun, which is better than a callback called the wrong way. Mark your callbacks with this and they match. Where it expands to nothing it costs nothing, so marking them is safe in any build.

/* A pen callback, marked so that it keeps C's calling convention whatever the build's default. */
static void DAEGUN_CALLBACK on_move(void *user, float x, float y)
{
    (void)x;
    (void)y;
    ++*(int *)user;
}

int contours = 0;
daegun_pen pen = { 0 };
pen.move_to = on_move;
pen.user = &contours;

uint32_t gid = 0;
if (daegun_font_glyph_id(font, 'o', &gid) != DAEGUN_OK) return 1;
if (daegun_font_outline(font, gid, NULL, &pen) != DAEGUN_OK) return 1;
/* An "o" is two contours, so on_move ran twice. */
DAEGUN_NODISCARD
#if (defined(__cplusplus) && __cplusplus >= 201703L) || (defined(_MSVC_LANG) && _MSVC_LANG >= 201703L)
#define DAEGUN_NODISCARD [[nodiscard]]
#elif defined(__STDC_VERSION__) && __STDC_VERSION__ > 201710L && defined(__has_c_attribute)
/* A C2x draft's version says nothing of whether the attribute is in: GCC 10's has none. */
#if __has_c_attribute(nodiscard)
#define DAEGUN_NODISCARD [[nodiscard]]
#endif
#endif
#ifndef DAEGUN_NODISCARD
#if defined(__clang__)
#define DAEGUN_NODISCARD __attribute__((warn_unused_result))
#elif defined(_MSC_VER)
#include <sal.h>
#define DAEGUN_NODISCARD _Check_return_
#else
#define DAEGUN_NODISCARD
#endif
#endif

Makes a compiler warn when the result of a call is ignored.

It marks the calls whose return value you are expected to read: a status that comes with results in out parameters, or a value such as daegun_abi_version returns. Ignore one and a compiler that knows the mark warns. A call made for its effect alone, such as daegun_table_map_set, is left unmarked. You never write the macro yourself.

It is [[nodiscard]] in C++17 and later, and in C23 where the compiler has that attribute. Otherwise it is __attribute__((warn_unused_result)) under clang, _Check_return_ under MSVC, which warns under /analyze, and empty under GCC and any other compiler. So GCC warns from C23 and C++17 on.

To ignore a result on purpose, cast the call to void.

DAEGUN_MALLOC
#if defined(__GNUC__) && !defined(__clang__) && __GNUC__ >= 11
#define DAEGUN_MALLOC(...) __attribute__((__VA_ARGS__))
#elif defined(__clang__)
#define DAEGUN_MALLOC(...) __attribute__((malloc))
#elif defined(_MSC_VER)
#define DAEGUN_MALLOC(...) __declspec(restrict)
#else
#define DAEGUN_MALLOC(...)
#endif

Tells a compiler that a call returns newly allocated memory, and which call frees it.

It marks the calls that return a new handle or buffer as their return value, such as daegun_font_buffer_new and daegun_path_new. You never write it yourself.

Under GCC 11 and later it passes its arguments on as attributes. They name each call that takes the pointer back, daegun_font_buffer_free and daegun_font_open_owned for a buffer, so GCC's analyzer and -Wmismatched-dealloc can follow the pointer to it, and on a call that never returns NULL, such as daegun_path_new, they add returns_nonnull. Under clang it is __attribute__((malloc)) and under MSVC __declspec(restrict), each of which says only that the pointer aliases nothing else. Under an older GCC and any other compiler it is empty.

DAEGUN_ALLOC_SIZE
#if defined(__GNUC__) || defined(__clang__)
#define DAEGUN_ALLOC_SIZE(n, len) __attribute__((alloc_size(n)))
#elif defined(_MSC_VER)
#include <sal.h>
#define DAEGUN_ALLOC_SIZE(n, len) _Ret_maybenull_ _Post_writable_byte_size_(len)
#else
#define DAEGUN_ALLOC_SIZE(n, len)
#endif

Tells a compiler how many bytes an allocating call returns.

It is on daegun_font_buffer_new alone, and says the buffer is as large as the len you ask for, which GCC and clang use in their bounds checks. You never write it yourself.

Its two arguments name the same parameter twice. GCC and clang take its position, counted from 1 (alloc_size). MSVC takes its name, in annotations for /analyze that also say the call may return NULL. Under any other compiler it is empty.

DAEGUN_CONST
#if defined(__GNUC__) || defined(__clang__)
#define DAEGUN_CONST __attribute__((const))
#else
#define DAEGUN_CONST
#endif

Tells a compiler that a call answers from its arguments alone.

It marks calls that read no memory and change nothing, such as daegun_abi_version and daegun_status_name, so a compiler may reuse the answer of one call for another with the same arguments. It is __attribute__((const)) under GCC and clang and empty elsewhere. You never write it yourself.

DAEGUN_COLD
#if defined(__GNUC__) || defined(__clang__)
#define DAEGUN_COLD __attribute__((cold))
#else
#define DAEGUN_COLD
#endif

Tells a compiler that a call is rarely made.

It is on daegun_last_error, daegun_status_name and daegun_thread_release. The first two are made once a call has failed, so a compiler lays the code that leads to them out of the way of the path that succeeds. It is __attribute__((cold)) under GCC and clang and empty elsewhere. You never write it yourself.

DAEGUN_READS
#if defined(__GNUC__) && !defined(__clang__) && __GNUC__ >= 10
#define DAEGUN_READS(p, n) __attribute__((access(read_only, p, n)))
#define DAEGUN_WRITES(p, n) __attribute__((access(write_only, p, n)))
#else
#define DAEGUN_READS(p, n)
#define DAEGUN_WRITES(p, n)
#endif

Tells GCC that a call reads an array, and which argument gives its length.

DAEGUN_READS(p, n) goes on a call and says that the argument at position p, counted from 1, is an array the call reads, holding as many items as the argument at position n says. DAEGUN_WRITES is the same for an array the call fills. You never write either yourself.

GCC 10 and later checks your calls against it, as __attribute__((access(read_only, p, n))): an array of yours shorter than the length you pass warns, and so does NULL with a length. A buffer that may be NULL whatever its length carries neither macro. Under every other compiler both are empty, and DAEGUN_IN and DAEGUN_OUT carry the same facts to clang and MSVC.

DAEGUN_WRITES
#if defined(__GNUC__) && !defined(__clang__) && __GNUC__ >= 10
#define DAEGUN_READS(p, n) __attribute__((access(read_only, p, n)))
#define DAEGUN_WRITES(p, n) __attribute__((access(write_only, p, n)))
#else
#define DAEGUN_READS(p, n)
#define DAEGUN_WRITES(p, n)
#endif

Tells GCC that a call fills an array, and which argument gives its room.

The counterpart of DAEGUN_READS for a buffer the call writes: DAEGUN_WRITES(p, n) says the argument at position p has room for as many items as the argument at position n says. GCC 10 and later warns where your buffer is smaller than the length you pass, as __attribute__((access(write_only, p, n))). It is empty under every other compiler, and you never write it yourself.

DAEGUN_IN
#if defined(__has_feature)
#if __has_feature(bounds_attributes) || __has_feature(bounds_safety_attributes)
#define DAEGUN_IN(n) __attribute__((__counted_by__(n)))
#define DAEGUN_OUT(n) __attribute__((__counted_by__(n)))
#define DAEGUN_OUT_OR_NULL(n) __attribute__((__counted_by_or_null__(n)))
#endif
#endif
#if !defined(DAEGUN_IN) && defined(_MSC_VER)
#include <sal.h>
#define DAEGUN_IN(n) _In_reads_opt_(n)
#define DAEGUN_OUT(n) _Out_writes_opt_(n)
#define DAEGUN_OUT_OR_NULL(n) _Out_writes_opt_(n)
#endif
#ifndef DAEGUN_IN
#define DAEGUN_IN(n)
#define DAEGUN_OUT(n)
#define DAEGUN_OUT_OR_NULL(n)
#endif

Marks an array parameter a call reads with the parameter that counts it.

It says what DAEGUN_READS says, written on the parameter itself and naming the count by name, as in DAEGUN_IN(len) const char *text. It serves the two checkers that read a mark in that place.

To clang with bounds safety on it is __counted_by__(n). That is -fbounds-safety, or its attributes alone, which Swift's C interop reads. To MSVC it is _In_reads_opt_(n), an annotation for /analyze. Under -fbounds-safety an array of yours shorter than the length you pass is then an error, and MSVC's /analyze warns of it. With the attributes alone clang checks nothing at your call: they are there for tools such as Swift to read. Under any other compiler it is empty. You never write it yourself.

DAEGUN_OUT
#if defined(__has_feature)
#if __has_feature(bounds_attributes) || __has_feature(bounds_safety_attributes)
#define DAEGUN_IN(n) __attribute__((__counted_by__(n)))
#define DAEGUN_OUT(n) __attribute__((__counted_by__(n)))
#define DAEGUN_OUT_OR_NULL(n) __attribute__((__counted_by_or_null__(n)))
#endif
#endif
#if !defined(DAEGUN_IN) && defined(_MSC_VER)
#include <sal.h>
#define DAEGUN_IN(n) _In_reads_opt_(n)
#define DAEGUN_OUT(n) _Out_writes_opt_(n)
#define DAEGUN_OUT_OR_NULL(n) _Out_writes_opt_(n)
#endif
#ifndef DAEGUN_IN
#define DAEGUN_IN(n)
#define DAEGUN_OUT(n)
#define DAEGUN_OUT_OR_NULL(n)
#endif

Marks a buffer parameter a call fills with the parameter that gives its room.

The counterpart of DAEGUN_IN for a buffer the call writes, as in DAEGUN_OUT(cap) size_t *out. It is __counted_by__(n) to clang with bounds safety on, _Out_writes_opt_(n) to MSVC's /analyze, and empty under any other compiler. You never write it yourself.

DAEGUN_OUT_OR_NULL
#if defined(__has_feature)
#if __has_feature(bounds_attributes) || __has_feature(bounds_safety_attributes)
#define DAEGUN_IN(n) __attribute__((__counted_by__(n)))
#define DAEGUN_OUT(n) __attribute__((__counted_by__(n)))
#define DAEGUN_OUT_OR_NULL(n) __attribute__((__counted_by_or_null__(n)))
#endif
#endif
#if !defined(DAEGUN_IN) && defined(_MSC_VER)
#include <sal.h>
#define DAEGUN_IN(n) _In_reads_opt_(n)
#define DAEGUN_OUT(n) _Out_writes_opt_(n)
#define DAEGUN_OUT_OR_NULL(n) _Out_writes_opt_(n)
#endif
#ifndef DAEGUN_IN
#define DAEGUN_IN(n)
#define DAEGUN_OUT(n)
#define DAEGUN_OUT_OR_NULL(n)
#endif

Marks a buffer parameter that may be NULL whatever its length.

Some calls let you leave a buffer out by passing NULL, whatever length you pass beside it: either buffer of daegun_font_coverage, for one. Such a buffer carries this in place of DAEGUN_OUT. Where it is not NULL it is held to the length, and where it is NULL the length says nothing about it.

It is __counted_by_or_null__(n) to clang with bounds safety on, _Out_writes_opt_(n) to MSVC's /analyze, and empty under any other compiler. You never write it yourself.

DAEGUN_COUNTED_BY
#if defined(__has_feature)
#if __has_feature(bounds_attributes) || __has_feature(bounds_safety_attributes)
#define DAEGUN_COUNTED_BY(n) __attribute__((__counted_by_or_null__(n)))
#define DAEGUN_LENT(n) __attribute__((__counted_by_or_null__(n)))
#endif
#endif
#if !defined(DAEGUN_COUNTED_BY) && defined(__GNUC__) && !defined(__clang__) && __GNUC__ >= 16 && !defined(__cplusplus)
#define DAEGUN_COUNTED_BY(n) __attribute__((counted_by(n)))
#endif
#ifndef DAEGUN_COUNTED_BY
#define DAEGUN_COUNTED_BY(n)
#endif

Marks a struct's pointer field with the field that counts what it points at.

The data of a daegun_bytes is marked DAEGUN_COUNTED_BY(len), which tells a compiler that data points at len items. An index of yours past the count is then caught at run time: GCC's -fsanitize=bounds reports it, and clang's -fbounds-safety traps. You never write it yourself.

It is __counted_by_or_null__(n) to clang with bounds safety on, and counted_by(n) to GCC 16 and later in C. Under an older GCC, under GCC in C++, and under every other compiler, it is empty.

DAEGUN_LENT
#if defined(__has_feature)
#if __has_feature(bounds_attributes) || __has_feature(bounds_safety_attributes)
#define DAEGUN_COUNTED_BY(n) __attribute__((__counted_by_or_null__(n)))
#define DAEGUN_LENT(n) __attribute__((__counted_by_or_null__(n)))
#endif
#endif
#ifndef DAEGUN_LENT
#define DAEGUN_LENT(n)
#endif

Marks a borrowed pointer with its count, in the places where GCC reads none.

The same mark as DAEGUN_COUNTED_BY, for three kinds of pointer: a view a call returns, counted by an out parameter, as daegun_blob_data returns one; the stops handed to a daegun_paint_visitor; and the data of a daegun_str, whose NUL lies one past its len.

It is __counted_by_or_null__(n) to clang with bounds safety on, and empty under every other compiler. You never write it yourself.

DAEGUN_NULLABLE
#if defined(__clang__) && defined(__has_feature)
#if __has_feature(nullability) && __has_feature(assume_nonnull)
#define DAEGUN_NULLABLE _Nullable
#define DAEGUN_NONNULL _Nonnull
#define DAEGUN_NONNULL_BEGIN _Pragma("clang diagnostic push") \
    _Pragma("clang diagnostic ignored \"-Wnullability-extension\"") _Pragma("clang assume_nonnull begin")
#define DAEGUN_NONNULL_END _Pragma("clang assume_nonnull end") _Pragma("clang diagnostic pop")
#endif
#endif
#ifndef DAEGUN_NULLABLE
#define DAEGUN_NULLABLE
#define DAEGUN_NONNULL
#define DAEGUN_NONNULL_BEGIN
#define DAEGUN_NONNULL_END
#endif

Marks a pointer that may be NULL.

Every pointer a call takes is required unless it carries this mark, and a required pointer that is NULL answers DAEGUN_NULL. The reference lists the marked parameters on each call. The pointer fields of every struct are marked too, since a struct is yours, zeroed, until a call fills it.

Under clang it is _Nullable, and each header is wrapped so that an unmarked pointer counts as required. clang then warns where you pass NULL for a required pointer. Under any other compiler it is empty, and the rule is kept at run time alone. You never write it yourself.

DAEGUN_NONNULL
#if defined(__clang__) && defined(__has_feature)
#if __has_feature(nullability) && __has_feature(assume_nonnull)
#define DAEGUN_NULLABLE _Nullable
#define DAEGUN_NONNULL _Nonnull
#define DAEGUN_NONNULL_BEGIN _Pragma("clang diagnostic push") \
    _Pragma("clang diagnostic ignored \"-Wnullability-extension\"") _Pragma("clang assume_nonnull begin")
#define DAEGUN_NONNULL_END _Pragma("clang assume_nonnull end") _Pragma("clang diagnostic pop")
#endif
#endif
#ifndef DAEGUN_NULLABLE
#define DAEGUN_NULLABLE
#define DAEGUN_NONNULL
#define DAEGUN_NONNULL_BEGIN
#define DAEGUN_NONNULL_END
#endif

Marks a pointer that is required, in the two places the headers spell that out.

One is an out that receives a pointer, as a handle out does: daegun_font *DAEGUN_NULLABLE *DAEGUN_NONNULL out. The inner mark says the pointer you get back may be NULL, as it is after a failure, and this one says that out itself is required. The other is an array parameter of fixed length, such as a color of three floats that daegun_blend takes: const float source[DAEGUN_NONNULL 3].

It is _Nonnull under clang and empty under any other compiler. You never write it yourself.

DAEGUN_NONNULL_BEGIN
#if defined(__clang__) && defined(__has_feature)
#if __has_feature(nullability) && __has_feature(assume_nonnull)
#define DAEGUN_NULLABLE _Nullable
#define DAEGUN_NONNULL _Nonnull
#define DAEGUN_NONNULL_BEGIN _Pragma("clang diagnostic push") \
    _Pragma("clang diagnostic ignored \"-Wnullability-extension\"") _Pragma("clang assume_nonnull begin")
#define DAEGUN_NONNULL_END _Pragma("clang assume_nonnull end") _Pragma("clang diagnostic pop")
#endif
#endif
#ifndef DAEGUN_NULLABLE
#define DAEGUN_NULLABLE
#define DAEGUN_NONNULL
#define DAEGUN_NONNULL_BEGIN
#define DAEGUN_NONNULL_END
#endif

Opens a stretch of header in which every unmarked pointer is required.

Under clang it is #pragma clang assume_nonnull begin, after a push of the diagnostic state that turns off the warning about nullability marks being an extension. From there to DAEGUN_NONNULL_END, a pointer not marked DAEGUN_NULLABLE counts as required. Under any other compiler it is empty.

The headers use it only through DAEGUN_HEADER_BEGIN, and you never write it yourself.

DAEGUN_NONNULL_END
#if defined(__clang__) && defined(__has_feature)
#if __has_feature(nullability) && __has_feature(assume_nonnull)
#define DAEGUN_NULLABLE _Nullable
#define DAEGUN_NONNULL _Nonnull
#define DAEGUN_NONNULL_BEGIN _Pragma("clang diagnostic push") \
    _Pragma("clang diagnostic ignored \"-Wnullability-extension\"") _Pragma("clang assume_nonnull begin")
#define DAEGUN_NONNULL_END _Pragma("clang assume_nonnull end") _Pragma("clang diagnostic pop")
#endif
#endif
#ifndef DAEGUN_NULLABLE
#define DAEGUN_NULLABLE
#define DAEGUN_NONNULL
#define DAEGUN_NONNULL_BEGIN
#define DAEGUN_NONNULL_END
#endif

Closes what DAEGUN_NONNULL_BEGIN opened.

Under clang it ends the assume_nonnull stretch and pops the diagnostic state that DAEGUN_NONNULL_BEGIN pushed, so the warning it turned off is as you had it for your own code. Under any other compiler it is empty. The headers use it only through DAEGUN_HEADER_END, and you never write it yourself.

DAEGUN_HEADER_BEGIN
#ifdef _MSC_VER
#define DAEGUN_HEADER_BEGIN DAEGUN_NONNULL_BEGIN __pragma(pack(push, 8))
#define DAEGUN_HEADER_END __pragma(pack(pop)) DAEGUN_NONNULL_END
#else
#define DAEGUN_HEADER_BEGIN DAEGUN_NONNULL_BEGIN _Pragma("pack(push, 8)")
#define DAEGUN_HEADER_END _Pragma("pack(pop)") DAEGUN_NONNULL_END
#endif

What each daegun header opens with: pointers required by default, and structs packed at 8.

Every header wraps its declarations between this and DAEGUN_HEADER_END. It is DAEGUN_NONNULL_BEGIN followed by #pragma pack(push, 8), written as __pragma under MSVC and as _Pragma elsewhere.

The packing guards against your own build settings. Every struct here is laid out at an alignment of 8, and the library reads its fields where that puts them. A /Zp switch or a #pragma pack in force where you include the header would otherwise move a field. You never write this macro yourself.

DAEGUN_HEADER_END
#ifdef _MSC_VER
#define DAEGUN_HEADER_BEGIN DAEGUN_NONNULL_BEGIN __pragma(pack(push, 8))
#define DAEGUN_HEADER_END __pragma(pack(pop)) DAEGUN_NONNULL_END
#else
#define DAEGUN_HEADER_BEGIN DAEGUN_NONNULL_BEGIN _Pragma("pack(push, 8)")
#define DAEGUN_HEADER_END _Pragma("pack(pop)") DAEGUN_NONNULL_END
#endif

What each daegun header closes with.

It undoes DAEGUN_HEADER_BEGIN in reverse order: #pragma pack(pop), then DAEGUN_NONNULL_END. After the include, your packing and your warnings are as they were before it. You never write it yourself.

DAEGUN_LAYOUT_ASSERT
#ifdef __cplusplus
#define DAEGUN_LAYOUT_ASSERT(cond, why) static_assert(cond, why)
#elif defined(_MSC_VER) && !defined(__STDC_VERSION__)
#define DAEGUN_LAYOUT_ASSERT(cond, why)
#else
#define DAEGUN_LAYOUT_ASSERT(cond, why) _Static_assert(cond, why)
#endif

A compile-time check that a struct has the size and layout the library expects.

The headers follow their struct definitions with checks such as DAEGUN_LAYOUT_ASSERT(sizeof(daegun_bounds) == 32, "bounds are four doubles"). The library repeats the same checks on its side, so a header and a library that disagree about a struct fail to build, with the message as the error, and never reach a running program.

It is static_assert in C++ and _Static_assert in C. MSVC's default C mode, the one a Visual Studio project builds in, has no _Static_assert, so there it is empty and the checks are skipped. You never write it yourself.

DAEGUN_LAYOUT_64
#if UINTPTR_MAX == 0xFFFFFFFFFFFFFFFFu
#define DAEGUN_LAYOUT_64 1
#endif

Defined as 1 on a 64-bit target, where the layout checks that depend on a target's widths apply.

Where a double follows a narrower field in a struct, as value follows tag in a daegun_coord, its offset depends on how the target aligns doubles. Every 64-bit target aligns them to 8, and 32-bit x86 aligns them to 4. The size of a struct that holds a pointer or a size_t, as every options struct does, depends on the target too. So the headers make the DAEGUN_LAYOUT_ASSERT checks on those structs only where this is defined, which is where UINTPTR_MAX shows a pointer of 64 bits.

On any other target it is left undefined. Nothing in your code needs it.

DAEGUN_DLL
#define DAEGUN_DLL

Define it before including daegun.h in a program that calls daegun from its Windows DLL.

The one macro here that the headers read and never define: it is yours to set. With it defined, DAEGUN_API declares every call as imported from the DLL, so each call goes straight to daegun-2.dll and skips a jump through a stub.

Define it on the compiler command line or above the first include, and link the import library of the DLL: cl /std:c11 /MD /DDAEGUN_DLL app.c daegun-2.dll.lib with MSVC, or gcc -DDAEGUN_DLL app.c daegun-2.dll.lib with MinGW.

Leave it undefined in a program that links the static library. Off Windows it changes nothing, whichever library you link.

/* In a program that calls daegun-2.dll: above the first include, or -DDAEGUN_DLL to the compiler. */
#define DAEGUN_DLL
#include "daegun.h"

if (!DAEGUN_ABI_COMPATIBLE(daegun_abi_version())) return 1;

Type to search.