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 0The 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_errorstill 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 -1A 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_erroris 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 -2Font 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_openanswers it for bytes that are not a font. The reason indaegun_last_errornames 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 -3An 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
sizeis below what daegun 2.0 defined.The reason in
daegun_last_errorsays 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 -4The 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, anddaegun_last_erroris 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 -6A 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 -7A 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_openanswers it for a font with noheadtable to give the units per em, or nomaxptable to give the glyph count. The reason indaegun_last_errornames 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 -8The 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_flattenanswers this when a path flattens to more thanDAEGUN_MAX_FLATTEN_POINTSpoints, or holds more than twice that many. The reason is indaegun_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 -9The glyph has no outline to draw.
A failure, with its reason in
daegun_last_error.daegun_font_quadsanswers 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 -10A 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_outlineanswers this for a transform that scales a glyph past that range, and draws nothing. The reason is indaegun_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 0x020000uThe ABI version of the header your program is compiled against.
It is packed as
daegun_abi_versionpacks 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, andDAEGUN_ABI_COMPATIBLEsays 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 asdaegun_abi_versionreturns it andDAEGUN_ABI_VERSIONholds it. Each is a constant expression when its argument is, so each works in#iftoo.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_COMPATIBLEdoes 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
vcan serve a program built against this header.True when
vhas the same major asDAEGUN_ABI_VERSIONand a minor no lower. The patch is not compared. Pass it whatdaegun_abi_versionreturns, once at startup, and stop if it is false.It is a constant expression when
vis, so it works in#iftoo.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))) #endifBuilds a
daegun_tagfrom four characters.The first argument becomes the high byte, so
DAEGUN_TAG('w', 'g', 'h', 't')is0x77676874. It is a constant expression, so it works in an initializer and as acaselabel. 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_castand 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) #endifA tag's four characters, first to last, as four
chararguments.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 0Across the line: the orientation of horizontal text.
DAEGUN_HORIZONTALandDAEGUN_VERTICALare the two orientation codes. A call with anorientationparameter takes one to say which way a metric, an advance or a run of text goes:daegun_font_advance,daegun_font_line_metricsanddaegun_font_caret_positionsare three such calls. A value that is neither answersDAEGUN_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 1Down the line: the orientation of vertical text, as CJK text is often set.
A font without vertical metrics still answers.
daegun_font_advancethen 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 0The 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_stylewrites one of them: at the default instance from flags in the font'sOS/2andheadtables, 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 1The font is italic: its
OS/2table or itsheadtable flags it so.DAEGUN_STYLE_OBLIQUE#define DAEGUN_STYLE_OBLIQUE 2The font is oblique: a slanted form of an upright design, flagged in its
OS/2table.A font may set this flag beside the italic one.
daegun_font_stylelooks for it first, so such a font answers oblique.DAEGUN_CACHE_SHAPE#define DAEGUN_CACHE_SHAPE 0The 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 todaegun_font_set_cache_budget,daegun_font_cache_stats,daegun_font_clear_cacheordaegun_font_set_cache_poolto 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_shapeanddaegun_font_shape_bidikeep a run in it only where theirdaegun_shape_optionsset 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_layoutkeeps the runs of the lines it sets.daegun_font_shape_intoneither 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_releaselets them go.DAEGUN_CACHE_INSTANCE#define DAEGUN_CACHE_INSTANCE 1The 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_instancemade 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, withdaegun_font_subset,daegun_font_subset_textordaegun_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 2The outline cache: glyph outlines that
daegun_font_prewarmdrew ahead of use.It holds only what
daegun_font_prewarmputs in it: drawing a glyph that was not prewarmed keeps nothing.daegun_font_outline,daegun_font_glyph_boundsand 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 3The 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 thatdaegun_rasterizer_glyph,daegun_rasterizer_color_glyphordaegun_rasterizer_distance_fielddrew 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_budgetsets.
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 0x01uEvery glyph of the font has the same width.
The
DAEGUN_PDF_bits are the flags of a PDF font descriptor, whichdaegun_font_pdf_flagsanswers 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
posttable'sisFixedPitchfield is not 0.DAEGUN_PDF_SERIF#define DAEGUN_PDF_SERIF 0x02uThe glyphs have serifs.
Set when the class in the
OS/2table's family class, the high byte offamily_classin adaegun_os2, is one of the serif classes: 1 to 5, or 7.DAEGUN_PDF_SYMBOLIC#define DAEGUN_PDF_SYMBOLIC 0x04uThe font is a symbol font, or maps a character outside the Adobe standard Latin set.
Set for a Windows symbol font, one whose
cmaptable 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_NONSYMBOLICis.DAEGUN_PDF_SCRIPT#define DAEGUN_PDF_SCRIPT 0x08uThe glyphs look like handwriting.
Set when the class in the
OS/2table's family class is 10, the script class.DAEGUN_PDF_NONSYMBOLIC#define DAEGUN_PDF_NONSYMBOLIC 0x20uThe font is not a symbol font and maps no character outside the Adobe standard Latin set, control codes aside.
Set whenever
DAEGUN_PDF_SYMBOLICis not, so every answer holds exactly one of the two. A font with nocmaptable gets this one.DAEGUN_PDF_ITALIC#define DAEGUN_PDF_ITALIC 0x40uThe glyphs slant.
Set when the italic angle, the one
daegun_font_italic_angleanswers, is not 0.DAEGUN_DEFAULT_POINT_SIZE#define DAEGUN_DEFAULT_POINT_SIZE 12The point size tracking is read at when no usable size is given: 12.
daegun_font_trackingreads at this size when itspoint_sizeis not a finite number above zero. Shaping tracks a run at it when its options are NULL, sethas_point_sizefalse, or give apoint_sizethat is not a finite number above zero.DAEGUN_STAT_SINGLE#define DAEGUN_STAT_SINGLE 0One value on one axis.
The
DAEGUN_STAT_codes are thekindof adaegun_stat_value.STAThas four kinds of value, and the code says which fields of the struct mean anything. For this kind they areaxis_indexandvalue: Inter names 700 on its weight axis Bold.DAEGUN_STAT_RANGE#define DAEGUN_STAT_RANGE 1A range of values on one axis, with the value the name is for.
The fields that count are
axis_index,min,maxandvalue, which holds the nominal value. Source Serif 4 calls weights 650 to 750 Bold, named for 700.DAEGUN_STAT_LINKED#define DAEGUN_STAT_LINKED 2One value on one axis, with a second value it is linked to.
The fields that count are
axis_index,valueandlinked_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 3Values on several axes, named together.
The fields that count are
combo_startandcombo_count, which pick the pairs of axis and value out of the arraydaegun_stat_combo_valueslends.axis_indexandvalueare 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 0A base glyph: a letter or symbol that stands by itself, and that marks attach to.
The
DAEGUN_GLYPH_CLASS_codes are whatdaegun_font_glyph_classwrites: the kind of glyph a font'sGDEFtable 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 1A ligature: one glyph that stands for several characters, such as fi.
DAEGUN_GLYPH_CLASS_MARK#define DAEGUN_GLYPH_CLASS_MARK 2A mark: an accent or vowel sign that attaches to another glyph.
DAEGUN_GLYPH_CLASS_COMPONENT#define DAEGUN_GLYPH_CLASS_COMPONENT 3A component: one part of a glyph that is built from several.
DAEGUN_MAX_GLYPH_NAME#define DAEGUN_MAX_GLYPH_NAME 63The longest glyph name, in bytes.
It is the limit the
posttable sets on a name, and daegun holds the names of a CFF font to it as well. A buffer ofDAEGUN_MAX_GLYPH_NAME + 1bytes fits any namedaegun_font_glyph_namewrites, 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 0The 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_shaperreports it, anddaegun_shaper_namegives 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,
scriptof the options set toqaag, in either case, picksDAEGUN_SHAPER_MYANMAR_ZAWGYI, whatever the text. Otherwise the script of the run decides, which isseed_scriptof 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 underDFLT. 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 isDFLTorlatn, as it is when the font has no lookups under the script's own tag or thescriptthe 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 noGSUBtable, leaves them their own. An Indic script under a version 3 tag, such asdev3, takes the Universal model, and Myanmar under its older tagmymrthe general one. Last, where the font'smorxtable shapes the run, any model but the general one gives way toDAEGUN_SHAPER_DUMBER.DAEGUN_SHAPER_DUMBER#define DAEGUN_SHAPER_DUMBER 1The model that stands in for a script's own where the font's
morxtable 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_DEFAULTeven wheremorxshapes it, so this code does not tell you whethermorxran.DAEGUN_SHAPER_ARABIC#define DAEGUN_SHAPER_ARABIC 2Joining, for Arabic and Syriac.
DAEGUN_SHAPER_HANGUL#define DAEGUN_SHAPER_HANGUL 3Hangul's syllables.
DAEGUN_SHAPER_HEBREW#define DAEGUN_SHAPER_HEBREW 4Hebrew's marks.
DAEGUN_SHAPER_INDIC#define DAEGUN_SHAPER_INDIC 5The syllables of the Indic scripts, Devanagari and its kin.
DAEGUN_SHAPER_KHMER#define DAEGUN_SHAPER_KHMER 6Khmer's syllables.
DAEGUN_SHAPER_MYANMAR#define DAEGUN_SHAPER_MYANMAR 7Myanmar's syllables.
DAEGUN_SHAPER_MYANMAR_ZAWGYI#define DAEGUN_SHAPER_MYANMAR_ZAWGYI 8Myanmar text in the older Zawgyi encoding.
You ask for it by setting
scriptof adaegun_shape_optionstoDAEGUN_TAG('Q', 'a', 'a', 'g'), in upper or lower case. Thelanguageof 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 9The marks of Thai and Lao.
DAEGUN_SHAPER_UNIVERSAL#define DAEGUN_SHAPER_UNIVERSAL 10The 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 0The direction the text itself reads in: left to right or right to left, taken from its script.
The
DAEGUN_DIRECTION_codes go indirectionof adaegun_shape_options. This one is 0, so options fromdaegun_shape_options_defaultalready hold it.DAEGUN_DIRECTION_LTR#define DAEGUN_DIRECTION_LTR 1Left to right, as Latin text runs.
DAEGUN_DIRECTION_RTL#define DAEGUN_DIRECTION_RTL 2Right to left, as Arabic and Hebrew text run.
DAEGUN_DIRECTION_TTB#define DAEGUN_DIRECTION_TTB 3Top 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 4Bottom to top.
DAEGUN_CLUSTER_MONOTONE_GRAPHEMES#define DAEGUN_CLUSTER_MONOTONE_GRAPHEMES 0A grapheme is one cluster, and clusters stay in text order. The default.
The
DAEGUN_CLUSTER_codes go incluster_levelof adaegun_shape_optionsand decide howdaegun_shaped_run_clustersgroups 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 1A 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 2A 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 3A grapheme is one cluster, in whatever order shaping leaves the glyphs.
DAEGUN_IGNORABLES_HIDE#define DAEGUN_IGNORABLES_HIDE 0Default ignorables stay in the run as an invisible glyph with an advance of 0. The default.
The
DAEGUN_IGNORABLES_codes go inignorablesof adaegun_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 aninvisible_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 withDAEGUN_IGNORABLES_REMOVE.DAEGUN_IGNORABLES_REMOVE#define DAEGUN_IGNORABLES_REMOVE 1Default ignorables are left out of the run altogether.
DAEGUN_IGNORABLES_PRESERVE#define DAEGUN_IGNORABLES_PRESERVE 2Default 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_glyphof the options,.notdefby default.DAEGUN_BASE_AUTO#define DAEGUN_BASE_AUTO -1The 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 asdaegun_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 0The paragraph reads left to right, whatever its first character.
DAEGUN_BASE_RTL#define DAEGUN_BASE_RTL 1The 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 0The script is written left to right across a line, as Latin, Greek and Devanagari are.
The two
DAEGUN_SCRIPT_DIRECTION_codes are whatdaegun_script_directionwrites. 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 1The script is written right to left across a line, as Arabic, Hebrew and Syriac are.
DAEGUN_GC_UNASSIGNED#define DAEGUN_GC_UNASSIGNED 0Cn: 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, anddaegun_general_categorywrites 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_LETTERtoDAEGUN_GC_UPPERCASE_LETTER, a mark any fromDAEGUN_GC_SPACING_MARKtoDAEGUN_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 1Cc: a control code, such as a tab or a line feed.
DAEGUN_GC_FORMAT#define DAEGUN_GC_FORMAT 2Cf: 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 3Co: a private use character, such as U+E000, whose meaning is left to whoever uses it.
DAEGUN_GC_SURROGATE#define DAEGUN_GC_SURROGATE 4Cs: a surrogate code point, U+D800 to U+DFFF.
daegun_general_categorynever writes it. A surrogate is not a character that text can hold, and passing one answersDAEGUN_INVALID_ARGUMENT.DAEGUN_GC_LOWERCASE_LETTER#define DAEGUN_GC_LOWERCASE_LETTER 5Ll: a lowercase letter, such as
a.DAEGUN_GC_MODIFIER_LETTER#define DAEGUN_GC_MODIFIER_LETTER 6Lm: 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 7Lo: 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 8Lt: a titlecase letter, a digraph whose first part alone is capital, such as U+01C5.
DAEGUN_GC_UPPERCASE_LETTER#define DAEGUN_GC_UPPERCASE_LETTER 9Lu: an uppercase letter, such as
A.DAEGUN_GC_SPACING_MARK#define DAEGUN_GC_SPACING_MARK 10Mc: 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 11Me: 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 12Mn: 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 13Nd: a decimal digit,
0to9and the digits of other scripts, such as the Arabic-Indic zero U+0660.DAEGUN_GC_LETTER_NUMBER#define DAEGUN_GC_LETTER_NUMBER 14Nl: a number written as a letter, such as the Roman numeral U+2160.
DAEGUN_GC_OTHER_NUMBER#define DAEGUN_GC_OTHER_NUMBER 15No: any other number, such as the superscript two U+00B2 or the fraction U+00BD.
DAEGUN_GC_CONNECT_PUNCTUATION#define DAEGUN_GC_CONNECT_PUNCTUATION 16Pc: punctuation that joins words, such as the underscore.
DAEGUN_GC_DASH_PUNCTUATION#define DAEGUN_GC_DASH_PUNCTUATION 17Pd: a dash or a hyphen.
DAEGUN_GC_CLOSE_PUNCTUATION#define DAEGUN_GC_CLOSE_PUNCTUATION 18Pe: a closing bracket, such as
).DAEGUN_GC_FINAL_PUNCTUATION#define DAEGUN_GC_FINAL_PUNCTUATION 19Pf: a closing quotation mark, such as U+00BB or U+2019.
DAEGUN_GC_INITIAL_PUNCTUATION#define DAEGUN_GC_INITIAL_PUNCTUATION 20Pi: an opening quotation mark, such as U+00AB or U+201C.
DAEGUN_GC_OTHER_PUNCTUATION#define DAEGUN_GC_OTHER_PUNCTUATION 21Po: any other punctuation, such as
!, a comma or a period.DAEGUN_GC_OPEN_PUNCTUATION#define DAEGUN_GC_OPEN_PUNCTUATION 22Ps: an opening bracket, such as
(.DAEGUN_GC_CURRENCY_SYMBOL#define DAEGUN_GC_CURRENCY_SYMBOL 23Sc: a currency sign, such as
$.DAEGUN_GC_MODIFIER_SYMBOL#define DAEGUN_GC_MODIFIER_SYMBOL 24Sk: a modifier symbol, an accent that stands by itself, such as
^.DAEGUN_GC_MATH_SYMBOL#define DAEGUN_GC_MATH_SYMBOL 25Sm: a math symbol, such as
+or=.DAEGUN_GC_OTHER_SYMBOL#define DAEGUN_GC_OTHER_SYMBOL 26So: any other symbol, such as the copyright sign U+00A9 or an emoji.
DAEGUN_GC_LINE_SEPARATOR#define DAEGUN_GC_LINE_SEPARATOR 27Zl: the line separator, U+2028.
DAEGUN_GC_PARAGRAPH_SEPARATOR#define DAEGUN_GC_PARAGRAPH_SEPARATOR 28Zp: the paragraph separator, U+2029.
DAEGUN_GC_SPACE_SEPARATOR#define DAEGUN_GC_SPACE_SEPARATOR 29Zs: 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 0R: 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, anddaegun_vertical_orientationwrites one.In vertical text
daegun_font_layout, with its defaultDAEGUN_TEXT_ORIENTATION_MIXED, sets a character upright where its code isDAEGUN_VO_UPRIGHTorDAEGUN_VO_TRANSFORMED_UPRIGHT, and where it isDAEGUN_VO_TRANSFORMED_ROTATEDanddaegun_vertical_formfinds 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 1Tr: 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 2Tu: 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 3U: 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 0Lines 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 inalignof adaegun_layout_optionsand say where each line sits in the measure, which ismax_inline_size. You see the result in theoffsetof eachdaegun_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 1Lines 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 2Lines are centered in the measure.
DAEGUN_ALIGN_JUSTIFY#define DAEGUN_ALIGN_JUSTIFY 3Lines 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_linehashard_breaktrue. A line with no space to widen sits at the start edge too.With
DAEGUN_BREAK_OPTIMALa 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 0Lines run across and stack downward. The default.
The
DAEGUN_WRITING_codes go inwriting_modeof adaegun_layout_options. In the two vertical modes lines run top to bottom,max_inline_sizeis the height of a column, thebaselineof eachdaegun_layout_lineis measured from the left edge of the block, and the font's vertical line metrics space the columns.daegun_writing_mode_is_verticaltells the vertical modes from this one.DAEGUN_WRITING_VERTICAL_RL#define DAEGUN_WRITING_VERTICAL_RL 1Lines 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 2Lines 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 0In 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 intext_orientationof adaegun_layout_optionsand say how characters stand in vertical lines. They change nothing in horizontal text. The rule Unicode gives is the vertical orientation of UAX #50.uprightof eachdaegun_layout_runsays 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 1In 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 2In vertical text every character lies on its side.
DAEGUN_BREAK_GREEDY#define DAEGUN_BREAK_GREEDY 0Each line takes as much text as fits before the next one starts. The default.
The
DAEGUN_BREAK_codes go instrategyof adaegun_layout_optionsand 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 1The 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 0The 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, forwhichofdaegun_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 1The GSUB lookups a level turns off to shrink a line.
DAEGUN_JSTF_SHRINKAGE_ENABLE_GPOS#define DAEGUN_JSTF_SHRINKAGE_ENABLE_GPOS 2The GPOS lookups a level turns on to shrink a line.
DAEGUN_JSTF_SHRINKAGE_DISABLE_GPOS#define DAEGUN_JSTF_SHRINKAGE_DISABLE_GPOS 3The GPOS lookups a level turns off to shrink a line.
DAEGUN_JSTF_EXTENSION_ENABLE_GSUB#define DAEGUN_JSTF_EXTENSION_ENABLE_GSUB 4The GSUB lookups a level turns on to extend a line.
DAEGUN_JSTF_EXTENSION_DISABLE_GSUB#define DAEGUN_JSTF_EXTENSION_DISABLE_GSUB 5The GSUB lookups a level turns off to extend a line.
DAEGUN_JSTF_EXTENSION_ENABLE_GPOS#define DAEGUN_JSTF_EXTENSION_ENABLE_GPOS 6The GPOS lookups a level turns on to extend a line.
DAEGUN_JSTF_EXTENSION_DISABLE_GPOS#define DAEGUN_JSTF_EXTENSION_DISABLE_GPOS 7The GPOS lookups a level turns off to extend a line.
DAEGUN_ADJUST_SHRINK#define DAEGUN_ADJUST_SHRINK 0Make 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 asadjustmenttodaegun_font_shape_justified, anddaegun_font_justifyreports the way it went inadjustmentof adaegun_justification.DAEGUN_ADJUST_EXTEND#define DAEGUN_ADJUST_EXTEND 1Make 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 0The verb that starts a contour, taking one point: where the contour begins.
The
DAEGUN_VERB_values are the bytes thatdaegun_path_verbslends, and theverbsof adaegun_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 1The verb for a straight line, taking one point: where the line ends.
DAEGUN_VERB_QUAD#define DAEGUN_VERB_QUAD 2The verb for a quadratic curve, taking two points: its control, then its end.
DAEGUN_VERB_CUBIC#define DAEGUN_VERB_CUBIC 3The verb for a cubic curve, taking three points: its two controls, then its end.
DAEGUN_VERB_CLOSE#define DAEGUN_VERB_CLOSE 4The verb that closes a contour, taking no point.
DAEGUN_JOIN_MITER#define DAEGUN_JOIN_MITER 0A sharp corner: the stroke's two edges run on until they meet in a point.
The
DAEGUN_JOIN_codes go injoinof adaegun_stroke_styleand say how a stroke turns a corner of the path. A code that is none of them answersDAEGUN_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 asDAEGUN_JOIN_BEVELcuts it. That is what keeps a hairpin turn from growing a spike.DAEGUN_JOIN_ROUND#define DAEGUN_JOIN_ROUND 1A 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 2A 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 0The stroke ends flat, exactly where the path ends.
The
DAEGUN_CAP_codes go incapof adaegun_stroke_styleand 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 answersDAEGUN_INVALID_ARGUMENT.A contour that is a single point, a
daegun_path_move_towith 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 1The 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_towith nothing after it, draws a full circle as wide as the stroke. Closed, it draws nothing.DAEGUN_CAP_SQUARE#define DAEGUN_CAP_SQUARE 2The 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 1048576The most points
daegun_path_flattenkeeps, and the mostdaegun_path_stroke_simplifiedholds to resolve.Either call answers
DAEGUN_LIMIT_EXCEEDEDfor 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 0No 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 inhintingof adaegun_outline_options, anddaegun_font_hinted_outlinetakes one as itsmode.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 fromdaegun_outline_options_defaultalready hold it.daegun_font_hinted_outlineanswersDAEGUN_ABSENTfor it.DAEGUN_HINT_FONT#define DAEGUN_HINT_FONT 1The 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
INSTCTRLinstruction. 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_GRIDflag 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 3One 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
fpgmtable) and a CVT program (thepreptable) 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_FONThints 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 4The 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 0The point lies on the outline.
The
DAEGUN_POINT_codes are whatdaegun_hinted_outline_kindsgives 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 1The 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_drawworks that out for you.DAEGUN_POINT_CUBIC#define DAEGUN_POINT_CUBIC 2One 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 0The bitmap is a PNG file, as the font stores it.
The
DAEGUN_BITMAP_codes are theformatof adaegun_bitmap_infoand say what itsdataholds. 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.widthandheightare 0, as the PNG's header holds its size.Every picture from
sbixcomes this way, and so do the PNG pictures of the other tables, such as thoseCBDTholds in Noto Color Emoji. daegun never hands out decoded color pixels.DAEGUN_BITMAP_COVERAGE#define DAEGUN_BITMAP_COVERAGE 1The 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.
dataholdswidthtimesheightbytes, 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 0A 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 theruleof adaegun_scene_opthat fills and of adaegun_clip_shape, and therulethatdaegun_rasterizer_pathanddaegun_rasterizer_path_intotake.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_sceneuses this rule for every fill and every clip shape.DAEGUN_FILL_EVENODD#define DAEGUN_FILL_EVENODD 1A 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 0Nothing 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 theblendof adaegun_scene_opwhose kind isDAEGUN_OP_PUSH_LAYER, themodeof adaegun_paint_nodewhose kind isDAEGUN_PAINT_COMPOSITE, and themodethatdaegun_blendanddaegun_compositetake. 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_SCREENtoDAEGUN_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 asDAEGUN_COMPOSITE_SRC_OVERlays it.A font's composite mode that COLR does not define is read as this one, as the OpenType spec asks.
daegun_compositedoes the arithmetic of any of the 28 for one pixel.DAEGUN_COMPOSITE_SRC#define DAEGUN_COMPOSITE_SRC 1The layer alone: the backdrop is dropped, where the layer has ink and where it has none.
DAEGUN_COMPOSITE_DEST#define DAEGUN_COMPOSITE_DEST 2The backdrop alone: the layer is dropped.
DAEGUN_COMPOSITE_SRC_OVER#define DAEGUN_COMPOSITE_SRC_OVER 3The 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 4The backdrop over the layer, so the layer shows only where the backdrop is transparent.
DAEGUN_COMPOSITE_SRC_IN#define DAEGUN_COMPOSITE_SRC_IN 5The layer, only where the backdrop has ink. The backdrop itself is dropped.
DAEGUN_COMPOSITE_DEST_IN#define DAEGUN_COMPOSITE_DEST_IN 6The backdrop, only where the layer has ink. The layer itself is dropped.
DAEGUN_COMPOSITE_SRC_OUT#define DAEGUN_COMPOSITE_SRC_OUT 7The layer, only where the backdrop has no ink. The backdrop itself is dropped.
DAEGUN_COMPOSITE_DEST_OUT#define DAEGUN_COMPOSITE_DEST_OUT 8The 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 9The layer over the backdrop, but only where the backdrop has ink.
DAEGUN_COMPOSITE_DEST_ATOP#define DAEGUN_COMPOSITE_DEST_ATOP 10The backdrop over the layer, but only where the layer has ink.
DAEGUN_COMPOSITE_XOR#define DAEGUN_COMPOSITE_XOR 11Each where the other has no ink: where both have ink, neither shows.
DAEGUN_COMPOSITE_PLUS#define DAEGUN_COMPOSITE_PLUS 12The two added together, channel by channel, which lightens where they overlap.
DAEGUN_COMPOSITE_SCREEN#define DAEGUN_COMPOSITE_SCREEN 13Lightens: 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 14Multiplies where the backdrop's color is dark and screens where it is light.
It is
DAEGUN_COMPOSITE_HARD_LIGHTwith the two colors' roles swapped.DAEGUN_COMPOSITE_DARKEN#define DAEGUN_COMPOSITE_DARKEN 15The darker of the two colors, channel by channel.
DAEGUN_COMPOSITE_LIGHTEN#define DAEGUN_COMPOSITE_LIGHTEN 16The lighter of the two colors, channel by channel.
DAEGUN_COMPOSITE_COLOR_DODGE#define DAEGUN_COMPOSITE_COLOR_DODGE 17Brightens the backdrop by the layer's color: the lighter the layer, the brighter the result.
DAEGUN_COMPOSITE_COLOR_BURN#define DAEGUN_COMPOSITE_COLOR_BURN 18Darkens the backdrop by the layer's color: the darker the layer, the darker the result.
DAEGUN_COMPOSITE_HARD_LIGHT#define DAEGUN_COMPOSITE_HARD_LIGHT 19Multiplies where the layer's color is dark and screens where it is light.
DAEGUN_COMPOSITE_SOFT_LIGHT#define DAEGUN_COMPOSITE_SOFT_LIGHT 20A 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 21The difference of the two colors, channel by channel: the darker taken from the lighter.
DAEGUN_COMPOSITE_EXCLUSION#define DAEGUN_COMPOSITE_EXCLUSION 22Like
DAEGUN_COMPOSITE_DIFFERENCE, with less contrast.DAEGUN_COMPOSITE_MULTIPLY#define DAEGUN_COMPOSITE_MULTIPLY 23Darkens: 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 24The layer's hue with the backdrop's saturation and luminosity.
DAEGUN_COMPOSITE_HSL_SATURATION#define DAEGUN_COMPOSITE_HSL_SATURATION 25The layer's saturation with the backdrop's hue and luminosity.
DAEGUN_COMPOSITE_HSL_COLOR#define DAEGUN_COMPOSITE_HSL_COLOR 26The layer's hue and saturation with the backdrop's luminosity.
DAEGUN_COMPOSITE_HSL_LUMINOSITY#define DAEGUN_COMPOSITE_HSL_LUMINOSITY 27The layer's luminosity with the backdrop's hue and saturation.
DAEGUN_EXTEND_PAD#define DAEGUN_EXTEND_PAD 0A 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 theextendof adaegun_gradientand of adaegun_paint_nodethat is a gradient. The values are COLR's own.DAEGUN_EXTEND_REPEAT#define DAEGUN_EXTEND_REPEAT 1A gradient's stops repeat past its ends, first to last each time.
DAEGUN_EXTEND_REFLECT#define DAEGUN_EXTEND_REFLECT 2A 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 0A path filled with a color or a gradient.
The
DAEGUN_OP_codes are thekindof adaegun_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 1Starts a clip: until the
DAEGUN_OP_POP_CLIPthat pairs with it, drawing shows only inside its shapes.Its shapes are entries
shapes_startup toshapes_endof whatdaegun_scene_shapeslends, 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 2Ends the clip that the last
DAEGUN_OP_PUSH_CLIPstill open started.DAEGUN_OP_PUSH_LAYER#define DAEGUN_OP_PUSH_LAYER 3Starts a layer: until the
DAEGUN_OP_POP_LAYERthat pairs with it, drawing goes into a transparent layer of its own.It carries the
blendandopacityits layer is composited with when it is popped.DAEGUN_OP_POP_LAYER#define DAEGUN_OP_POP_LAYER 4Ends the last layer still open and composites it onto what lies below.
The layer goes on by the
blendandopacityof theDAEGUN_OP_PUSH_LAYERthat started it. This op has no fields of its own.DAEGUN_GRADIENT_LINEAR#define DAEGUN_GRADIENT_LINEAR 0A gradient along a line:
valueshold x0, y0, x1, y1.The
DAEGUN_GRADIENT_codes are thekindof adaegun_gradient, and say what itsvalueshold. Positions are in the gradient's own space, which itstransformtakes 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 1A gradient between two circles:
valueshold 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 2A gradient around a center:
valueshold 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_angleand offset 1 atend_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 underDAEGUN_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 0A gradient blends between its stops in linear light, with alpha premultiplied, as the OpenType spec asks.
The
DAEGUN_INTERPOLATE_codes go ininterpolationofdaegun_scene_rampand 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 colordaegun_ramp_atanswers 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 1A 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_LIGHTgives 188, 0, 188.DAEGUN_PAINT_LAYERS#define DAEGUN_PAINT_LAYERS 0A stack of paints: its children are painted in turn, the first at the bottom.
The
DAEGUN_PAINT_codes are thekindof adaegun_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_GLYPHclips 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_centerandstops_countare 0, whileendis set for every paint andstops_startholds where the graph's stops stood when the paint came, so go bystops_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
centerwhere itshas_centeris 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 1Its 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_outlinedraws.DAEGUN_PAINT_COLR_GLYPH#define DAEGUN_PAINT_COLR_GLYPH 2Another 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 3One color over the whole region clipped to: the node's
color, or the text's color whereforegroundis true.It has no children.
DAEGUN_PAINT_LINEAR_GRADIENT#define DAEGUN_PAINT_LINEAR_GRADIENT 4A gradient along a line, over the whole region clipped to.
The node's
valuesholdx0, 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 arestops_countof the graph's stops fromstops_start, andextendsays how the colors go on past the first and last stop. It has no children.DAEGUN_PAINT_RADIAL_GRADIENT#define DAEGUN_PAINT_RADIAL_GRADIENT 5A gradient between two circles, over the whole region clipped to.
The node's
valuesholdx0, y0, r0, x1, y1, r1. The colors start on the circle centered at (x0, y0) with radiusr0and end on the one centered at (x1, y1) with radiusr1. Stops andextendare read as forDAEGUN_PAINT_LINEAR_GRADIENT. It has no children.DAEGUN_PAINT_SWEEP_GRADIENT#define DAEGUN_PAINT_SWEEP_GRADIENT 6A gradient that sweeps around a point, over the whole region clipped to.
The node's
valuesholdcx, 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 andextendare read as forDAEGUN_PAINT_LINEAR_GRADIENT. It has no children.DAEGUN_PAINT_TRANSFORM#define DAEGUN_PAINT_TRANSFORM 7Its one child drawn through a matrix.
The node's
valuesholdxx, 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 8Its one child moved by
dx, dy, the first two of the node'svalues, in font units.DAEGUN_PAINT_SCALE#define DAEGUN_PAINT_SCALE 9Its one child scaled by
sxacross andsyup, the first two of the node'svalues.The scale is about the node's
centerwherehas_centeris true, and about the origin otherwise.DAEGUN_PAINT_SCALE_UNIFORM#define DAEGUN_PAINT_SCALE_UNIFORM 10Its one child scaled the same both ways by
s, the first of the node'svalues.The scale is about the node's
centerwherehas_centeris true, and about the origin otherwise.DAEGUN_PAINT_ROTATE#define DAEGUN_PAINT_ROTATE 11Its one child turned by
angle, the first of the node'svalues, in degrees counterclockwise.It turns about the node's
centerwherehas_centeris true, and about the origin otherwise.DAEGUN_PAINT_SKEW#define DAEGUN_PAINT_SKEW 12Its one child slanted by
x_angleandy_angle, the first two of the node'svalues, 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 positivex_angleleans the top of the child to the left, the way a counterclockwise turn would. Wherehas_centeris true the skew is about the node'scenterin 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 13Two children combined: the first, the source, composited onto the second, the backdrop, by the node's
mode.modeis aDAEGUN_COMPOSITE_code. A composite always has its two children, the source first.daegun_compositeworks 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 0The 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 incornerofdaegun_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 1The 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 2The 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 3The 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 0The 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_classanswers for a glyph the class table doesn't list.DAEGUN_AAT_CLASS_DELETED_GLYPH#define DAEGUN_AAT_CLASS_DELETED_GLYPH 2The class of glyph 0xFFFF, class 2: the mark a machine leaves where it deleted a glyph.
daegun_aat_state_table_classanswers it for glyph 0xFFFF, whatever the class table says.DAEGUN_AAT_STATE_START_OF_TEXT#define DAEGUN_AAT_STATE_START_OF_TEXT 0The state every machine starts in, state 0.
Pass it as
statetodaegun_aat_state_table_entryto 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 4The most samples a layout takes for each pixel, in either direction.
Three limits on what
daegun_subpixel_layout_from_weightstakes, each answeringDAEGUN_INVALID_ARGUMENTpast it.DAEGUN_MAX_OVERSAMPLEboundsoversample_xandoversample_y.DAEGUN_MAX_TAPS, which is it plus 4, boundstaps_xandtaps_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 thatdaegun_subpixel_layout_weightslends.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 8The most taps a layout's filter has, in either direction.
DAEGUN_MAX_WEIGHTS#define DAEGUN_MAX_WEIGHTS 64The most weights one channel of a filter has:
DAEGUN_MAX_TAPSsquared.DAEGUN_STRIPES_RGB#define DAEGUN_STRIPES_RGB 0Red, green, blue: from left to right for stripes side by side, from top to bottom for stacked ones.
The
DAEGUN_STRIPES_codes are theorderthatdaegun_subpixel_layout_horizontal,daegun_subpixel_layout_verticalanddaegun_subpixel_layout_unfilteredtake. 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 1Blue, green, red: from left to right, or from top to bottom for stacked stripes.
DAEGUN_MAX_SIDE#define DAEGUN_MAX_SIDE 16384The most pixels an image a rasterizer lends is across or down.
daegun_rasterizer_glyph,daegun_rasterizer_color_glyph,daegun_rasterizer_pathanddaegun_rasterizer_distance_fieldanswerDAEGUN_LIMIT_EXCEEDEDfor an image wider or taller than this. A draw into adaegun_targettakes any size, so draw a glyph that large in tiles withdaegun_rasterizer_glyph_into.DAEGUN_MAX_DRAW_BYTES#define DAEGUN_MAX_DRAW_BYTES 268435456The 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_SIDEeven 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 withDAEGUN_LIMIT_EXCEEDEDbefore 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 beforeDAEGUN_MAX_SIDEon a square image, and sooner still for a subpixel layout, a color glyph with layers or aDAEGUN_FIELD_MSDFfield. A draw into adaegun_targetholds 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 0Coverage as it is, exact: each byte is the share of the pixel the glyph covers. The default.
The
DAEGUN_GAMMA_codes go ingammaof adaegun_raster_optionsand 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_SRGBhands such a compositor the alpha that makes its blend of thetextcolor 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 1Alpha for a compositor that blends sRGB values as they are, worked out for text of the options'
textcolor.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.
contrastof the options can thicken the coverage first.DAEGUN_FIELD_SDF#define DAEGUN_FIELD_SDF 0A signed distance field: one byte a pixel, the distance to the outline.
The
DAEGUN_FIELD_codes are thefieldthatdaegun_rasterizer_distance_fieldtakes. Both kinds store, for each pixel, the distance from its center to the outline, positive inside, as the byte127.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 1A 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_SDFfield.
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 #endifHow every call is declared: imported from the DLL where
DAEGUN_DLLasks 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_DLLdefined, it declares each call as imported fromdaegun-2.dll(dllimport), which saves every call a jump through a stub. WithoutDAEGUN_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 withDAEGUN_DLLdefined, 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 #endifC'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:
/Gvand/Gzunder MSVC, and-mrtdunder 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
__cdeclunder MSVC,__attribute__((cdecl))under GCC and clang on 32-bit x86, and empty everywhere else.DAEGUN_CALLBACK#define DAEGUN_CALLBACK DAEGUN_CALLC's calling convention for a function you hand to daegun.
It is
DAEGUN_CALLunder a second name, and every callback type in the headers carries it: the functions of adaegun_penand of adaegun_paint_visitor, adaegun_word_segmenter, and thekey_atthatdaegun_search_recordstakes.This is one of the two macros here that you may write yourself. Build with
/Gvor/Gzunder MSVC, or with-mrtdon 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 #endifMakes 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_versionreturns. Ignore one and a compiler that knows the mark warns. A call made for its effect alone, such asdaegun_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(...) #endifTells 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_newanddaegun_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_freeanddaegun_font_open_ownedfor a buffer, so GCC's analyzer and-Wmismatched-dealloccan follow the pointer to it, and on a call that never returns NULL, such asdaegun_path_new, they addreturns_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) #endifTells a compiler how many bytes an allocating call returns.
It is on
daegun_font_buffer_newalone, and says the buffer is as large as thelenyou 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/analyzethat 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 #endifTells a compiler that a call answers from its arguments alone.
It marks calls that read no memory and change nothing, such as
daegun_abi_versionanddaegun_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 #endifTells a compiler that a call is rarely made.
It is on
daegun_last_error,daegun_status_nameanddaegun_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) #endifTells 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 positionp, counted from 1, is an array the call reads, holding as many items as the argument at positionnsays.DAEGUN_WRITESis 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, andDAEGUN_INandDAEGUN_OUTcarry 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) #endifTells GCC that a call fills an array, and which argument gives its room.
The counterpart of
DAEGUN_READSfor a buffer the call writes:DAEGUN_WRITES(p, n)says the argument at positionphas room for as many items as the argument at positionnsays. 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) #endifMarks an array parameter a call reads with the parameter that counts it.
It says what
DAEGUN_READSsays, written on the parameter itself and naming the count by name, as inDAEGUN_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-safetyan array of yours shorter than the length you pass is then an error, and MSVC's/analyzewarns 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) #endifMarks a buffer parameter a call fills with the parameter that gives its room.
The counterpart of
DAEGUN_INfor a buffer the call writes, as inDAEGUN_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) #endifMarks 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 ofDAEGUN_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) #endifMarks a struct's pointer field with the field that counts what it points at.
The
dataof adaegun_bytesis markedDAEGUN_COUNTED_BY(len), which tells a compiler thatdatapoints atlenitems. An index of yours past the count is then caught at run time: GCC's-fsanitize=boundsreports it, and clang's-fbounds-safetytraps. You never write it yourself.It is
__counted_by_or_null__(n)to clang with bounds safety on, andcounted_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) #endifMarks 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, asdaegun_blob_datareturns one; the stops handed to adaegun_paint_visitor; and thedataof adaegun_str, whose NUL lies one past itslen.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 #endifMarks 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 #endifMarks 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 thatoutitself is required. The other is an array parameter of fixed length, such as a color of three floats thatdaegun_blendtakes:const float source[DAEGUN_NONNULL 3].It is
_Nonnullunder 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 #endifOpens 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 toDAEGUN_NONNULL_END, a pointer not markedDAEGUN_NULLABLEcounts 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 #endifCloses what
DAEGUN_NONNULL_BEGINopened.Under clang it ends the
assume_nonnullstretch and pops the diagnostic state thatDAEGUN_NONNULL_BEGINpushed, 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 throughDAEGUN_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 #endifWhat 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 isDAEGUN_NONNULL_BEGINfollowed by#pragma pack(push, 8), written as__pragmaunder MSVC and as_Pragmaelsewhere.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
/Zpswitch or a#pragma packin 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 #endifWhat each daegun header closes with.
It undoes
DAEGUN_HEADER_BEGINin reverse order:#pragma pack(pop), thenDAEGUN_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) #endifA 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_assertin C++ and_Static_assertin 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 #endifDefined as 1 on a 64-bit target, where the layout checks that depend on a target's widths apply.
Where a
doublefollows a narrower field in a struct, asvaluefollowstagin adaegun_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 asize_t, as every options struct does, depends on the target too. So the headers make theDAEGUN_LAYOUT_ASSERTchecks on those structs only where this is defined, which is whereUINTPTR_MAXshows a pointer of 64 bits.On any other target it is left undefined. Nothing in your code needs it.
DAEGUN_DLL#define DAEGUN_DLLDefine it before including
daegun.hin 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_APIdeclares every call as imported from the DLL, so each call goes straight todaegun-2.dlland 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.libwith MSVC, orgcc -DDAEGUN_DLL app.c daegun-2.dll.libwith 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;