{"id":13732021,"url":"https://github.com/azmr/blit-fonts","last_synced_at":"2025-05-08T06:31:03.962Z","repository":{"id":74906981,"uuid":"123101505","full_name":"azmr/blit-fonts","owner":"azmr","description":"A family of small, fast, and simple bitmap fonts in single-file C headers","archived":false,"fork":false,"pushed_at":"2018-04-17T10:06:27.000Z","size":73,"stargazers_count":61,"open_issues_count":1,"forks_count":3,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-08-04T02:10:41.883Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/azmr.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2018-02-27T08:58:54.000Z","updated_at":"2024-07-23T21:46:51.000Z","dependencies_parsed_at":"2023-02-28T04:15:43.577Z","dependency_job_id":null,"html_url":"https://github.com/azmr/blit-fonts","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azmr%2Fblit-fonts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azmr%2Fblit-fonts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azmr%2Fblit-fonts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azmr%2Fblit-fonts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/azmr","download_url":"https://codeload.github.com/azmr/blit-fonts/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224707596,"owners_count":17356362,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T02:01:44.051Z","updated_at":"2024-11-14T23:30:48.009Z","avatar_url":"https://github.com/azmr.png","language":"C","funding_links":[],"categories":["Graphics"],"sub_categories":[],"readme":"# Blit\n_A family of small, fast, and simple bitmap fonts in single-file C headers_\n\n[[go to repository]](https://github.com/azmr/blit-fonts)\n\nThese are not intended as a replacement for fancy user fonts.\nI see them being useful for quickly getting up debug text on a PC without having to link an external font file, or for embedded developers with limited memory.\n\n## Contents\n- [blit16](#blit16)\n- [blit32](#blit32)\n- [API](#api)\n\t- [Functions](#functions)\n\t- [Constants](#constants)\n\t- [Types](#types)\n\t- [Globals](#globals)\n\t- [Compile-time options](#compile-time-options)\n- [How it works](#how-it-works)\n- [Recommended Libraries](#recommended-libraries)\n- [License](#license)\n\n## blit16\n![blit16 glyphs](img/blit16.png)\n\n## blit32\n![blit32 glyphs](img/blit32.png)\n\n## API\n_Replace the prefix if using a different font._\n\n### Functions\n``` c\n/* Draw strings into a pixel buffer. Overwrites any pixels drawn to (no alpha). */\n/* returns number of lines printed */\nint blit16_TextNExplicit(unsigned int *Buffer, unsigned int Value, int Scale,\n                         int BufWidth, int BufHeight, int Wrap,\n                         int StartX, int StartY, int StrLen, char *String)\n/* Buffer              - the array of pixels that you're drawing into.\n * Value               - text colour value, uint by default, but can be changed as shown below.\n *                       Should work for most representations.\n * Scale               - simple integer scaling of glyph 'pixels' to buffer pixels.\n *                       e.g. a value of 3 would draw a 3x3 square for each 'pixel'.\n * BufWidth, BufHeight - width and height of the buffer being drawn into.\n * Wrap                - controls what happens when the text reaches the edge of the buffer.\n *                       blit_Clip (0) stops printing, blit_Wrap continues on the next line.\n *                       Wrapping is only done per character, not per word.\n * StartX, StartY      - x and y in the buffer for the top-left of the glyph's bounding box.\n * StrLen              - maximum length of string from pointer if '\\0' is not hit first.\n *                       If negative, will just run to the first null terminator.\n * String              - the text you want to draw on the screen.\n */\n\n/* The same as above, but no need to specify negative StrLen */\nblit16_TextExplicit(unsigned int *Buffer, unsigned int Value, int Scale,\n                    int BufWidth, int BufHeight, int Wrap,\n                    int StartX, int StartY, char *String)\n\n/* Use a blit_props struct to keep the infrequently changing elements together */\nblit16_TextNProps(blit_props Props, int StartX, int StartY, int StrLen, char *String)\nblit16_TextProps(blit_props Props, int StartX, int StartY, char *String)\n\n/* Use the properties in the global font */\nblit16_TextN(int StartX, int StartY, int StrLen, char *String)\nblit16_Text(int StartX, int StartY, char *String)\n\n/* Scale the font metrics pointed to in the font */\nvoid blit16_Scale(blit16_font *Font, int Scale)\n\n/* Convert between ASCII code (or character literals) and the associated glyph index. */\nblit_IndexFromASCII(unsigned int ascii);\nblit_ASCIIFromIndex(unsigned int index);\n```\n\n### Constants\n``` c\n                       /* (all dimensions in glyph pixels)                    */\nblit16_WIDTH           /* Width of glyphs                                     */\nblit16_HEIGHT          /* Height of glyphs (excluding descender)              */\nblit16_ADVANCE         /* Distance between start of 1 character and the next  */\nblit16_DESCENDER       /* Maximum distance of descenders below baseline       */\nblit16_BASELINE_OFFSET /* Distance between baseline and top of next character */\nblit16_ROW_ADVANCE     /* Distance between baseline of 1 row and the next     */\n```\n\n### Types\n``` c\ntypedef unsigned short blit16_glyph;\n\n/* Keep infrequently changing properties together, see above for explanations */\ntypedef struct blit_props\n{\n\tunsigned int *Buffer; /* changeable to a custom pixel type */\n\tunsigned int  Value;  /* ... see the compile-time options  */\n\t         int  Scale;\n\t         int  BufWidth;\n\t         int  BufHeight;\n\tenum {blit_Clip, blit_Wrap} Wrap;\n} blit_props;\n\n/* This is just a convenience wrapper around the array:\n * - simplify calls even more\n * - reference the constants in a debugger\n * - keep scaled versions of the constants above\n */\ntypedef struct blit16_font\n{\n\tconst blit16_glyph Glyphs[blit_NUM_GLYPHS];\n\tconst unsigned int Width;\n\tconst unsigned int Height;\n\tconst unsigned int Descender;\n\tconst unsigned int Advance;\n\tconst unsigned int RowAdvance;\n\t        blit_props Props;\n} blit16_font;\n```\n\n### Globals\n``` c\n/* Contains the main font data.\n * Set the Props for this to use the blit16_Text[N] functions, and\n * (optionally) use blit16_Scale on it to keep the metrics up to date.\n */\nblit16_font Blit16\n```\n\n### Compile-time options\n``` c\n/* determines the pixel type that blit draws (defaults to unsigned int) */\n#define blit_pixel your_pixel_type_here\n\n/* removes the inline qualifier from all functions */\n#define blit_NO_INLINE\n\n/* replaces all inline functions with macro equivalents */\n#define blit16_MACRO_INLINE\n\n/* removes blit16_font, blit16_Scale, and replaces Blit16 with blit16_Glyphs */\n#define blit16_ARRAY_ONLY\n\n/* removes all string functions except blit16_StringNExplicit */\n#define blit16_NO_HELPERS\n```\n\n## How it works \n1) Draw the bitmap for a glyph in your text editor, using characters that represent pixels being on ('#'), or off (' ').\n(You can better see what the end result will be with a square font)\n``` c\n/* ASCII: 49, Char: '1', Name: One */\nchar Glyph_One[] =\n/*        012 */\n/* 0 */  \" # \"\n/* 1 */  \"## \"\n/* 2 */  \" # \"\n/* 3 */  \" # \"\n/* 4 */  \"###\";\n```\n2) This is treated by C as a single linear string...\n``` c\n\" # ##  #  # ###\"\n```\n...which can be easily translated to bits by treating spaces as 0s and #s as 1s.\n(This is reversed because processing it is slightly more convenient that way round.)\n``` c\n 111010010011010\n```\n3) This can then be represented as a number (in hexadecimal).\n``` c\n0x749a\n```\n(One happy coincidence of this format is that space is represented by the number 0)\n\n4) Collect a lot of these into an array, sorted in the ASCII code order (omitting the non-printable characters, starting with space at ASCII code 32).\n``` c\ntypedef unsigned short blit16_glyph;\n\nblit16_glyph blit16_Glyphs[95] = {\n0x0000,0x2092,0x002d,0x5f7d,0x279e,0x52a5,0x7ad6,0x0012,\n0x4494,0x1491,0x017a,0x05d0,0x1400,0x01c0,0x0400,0x12a4,\n0x2b6a,0x749a,0x752a,0x38a3,0x4f4a,0x38cf,0x3bce,0x12a7,\n0x3aae,0x49ae,0x0410,0x1410,0x4454,0x0e38,0x1511,0x10e3,\n0x73ee,0x5f7a,0x3beb,0x624e,0x3b6b,0x73cf,0x13cf,0x6b4e,\n0x5bed,0x7497,0x2b27,0x5add,0x7249,0x5b7d,0x5b6b,0x3b6e,\n0x12eb,0x4f6b,0x5aeb,0x388e,0x2497,0x6b6d,0x256d,0x5f6d,\n0x5aad,0x24ad,0x72a7,0x6496,0x4889,0x3493,0x002a,0xf000,\n0x0011,0x6b98,0x3b79,0x7270,0x7b74,0x6750,0x95d6,0xb9ee,\n0x5b59,0x6410,0xb482,0x56e8,0x6492,0x5be8,0x5b58,0x3b70,\n0x976a,0xcd6a,0x1370,0x38f0,0x64ba,0x3b68,0x2568,0x5f68,\n0x54a8,0xb9ad,0x73b8,0x64d6,0x2492,0x3593,0x03e0,\n};\n\n```\n6) TADAA! We have a font.\n7) Extra fanciness - eagle-eyed readers may have noticed that I'm only using 15 of the 16 available bytes in the example.\nThe 16th is set as a flag for shifting the character's pixel grid down, to allow for descenders without a larger glyph type size.\nDepending on the glyph type and aspect ratio, there may be no space for such a flag, or for multiple (e.g. 0-3 descender levels for a 32-bit glyph: `(5 * 6) % 32 == 2; 1 \u003c\u003c 2 == 4;`)\n\n## Recommended Libraries\n- [sweet](https://github.com/azmr/sweet) (my single-header C test suite)\n- [live_edit](https://github.com/azmr/live_edit) (my single-header C library-loading/tweaking/debugging/profiling tools)\n- [STB libraries](https://github.com/nothings/stb) (lots of excellent single-header libraries, including `stb_truetype.h` for when you want proper fonts)\n- [tigr](https://bitbucket.org/rmitton/tigr) (multiplatform 'Tiny Graphics' header. Easy to set up. Plays nicely with blit fonts.)\n\n## License\n\n```\nISC License\nCopyright (c) 2018 Andrew Reece\n\nPermission to use, copy, modify, and/or distribute this software for any\npurpose with or without fee is hereby granted, provided that the above\ncopyright notice and this permission notice appear in all copies.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\" AND THE AUTHOR DISCLAIMS ALL WARRANTIES\nWITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF\nMERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR\nANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES\nWHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN\nACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF\nOR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.\n```\n\nIf this license is not suitable for your circumstances, please let me know and I'll see what I can do to make it work for you.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazmr%2Fblit-fonts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fazmr%2Fblit-fonts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazmr%2Fblit-fonts/lists"}