---
title: "Introduction to hexfont"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to hexfont}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

### Table of Contents

* [Overview](#overview)
* [Included hex font files](#hex)
* [Examples](#examples)
* [License](#license)

## <a name="overview">Overview</a>

This is an R data package that includes most "hex" font files from the [GNU Unifont](https://unifoundry.com/unifont/index.html) project compressed by `xz`.  It includes a convenience function that loads several of them as a [{bittermelon}](https://github.com/trevorld/bittermelon) `bm_font()` object.  GNU Unifont is a duospaced bitmap font (8x16 and 16x16 glyphs) that pretty much covers all of the official Unicode glyphs plus several of the artificial scripts in the [(Under-)ConScript Unicode Registry](https://www.kreativekorp.com/ucsur/).

## <a name="hex">Included hex font files</a>

`{hexfont}` includes most of the hex font files included in the [GNU Unifont](https://unifoundry.com/unifont/index.html)
source code distribution.  The version number is stripped from the file names in the `precompiled` directory and
the hex fonts are all compressed by `xz` but other than that the hex fonts are otherwise unchanged.  Due to CRAN size limitations we omit the "precompiled" `unifont_all` hex file (this is presumably the concatenation of the "precompiled" `unifont` and `unifont_upper` hex files).

```{css, echo=FALSE}
pre,code {
    font-family: Dejavu Sans Mono,FreeMono,monospace;
    line-height: 1.0;
    font-size: 100%;
}
```

```r
hex_dir <- system.file("font", package = "hexfont")
list.files(hex_dir, pattern = ".hex.xz", recursive = TRUE)
```

```
##  [1] "plane00/alt/codepage-437.hex.xz"           
##  [2] "plane00/alt/izmg16-plane00-FFxx.hex.xz"    
##  [3] "plane00/alt/mongolian-vertical.hex.xz"     
##  [4] "plane00/alt/phags-pa-vertical.hex.xz"      
##  [5] "plane00/alt/quad-width.hex.xz"             
##  [6] "plane00/alt/reiwa-vertical.hex.xz"         
##  [7] "plane00/alt/uni0009-orig.hex.xz"           
##  [8] "plane00/copyleft.hex.xz"                   
##  [9] "plane00/custom00.hex.xz"                   
## [10] "plane00/hangul-syllables.hex.xz"           
## [11] "plane00/izmg16-plane00.hex.xz"             
## [12] "plane00/omit.hex.xz"                       
## [13] "plane00/plane00-nonprinting.hex.xz"        
## [14] "plane00/plane00-unassigned.hex.xz"         
## [15] "plane00/pua.hex.xz"                        
## [16] "plane00/spaces.hex.xz"                     
## [17] "plane00/unifont-base.hex.xz"               
## [18] "plane00/wqy.hex.xz"                        
## [19] "plane00csur/plane00csur-nonprinting.hex.xz"
## [20] "plane00csur/plane00csur-spaces.hex.xz"     
## [21] "plane00csur/plane00csur-unassigned.hex.xz" 
## [22] "plane00csur/plane00csur.hex.xz"            
## [23] "plane01/plane01-nonprinting.hex.xz"        
## [24] "plane01/plane01-noscript.hex.xz"           
## [25] "plane01/plane01-space.hex.xz"              
## [26] "plane01/plane01-unassigned.hex.xz"         
## [27] "plane01/plane01.hex.xz"                    
## [28] "plane01/space.hex.xz"                      
## [29] "plane02/izmg16-plane02.hex.xz"             
## [30] "plane02/zh-plane02.hex.xz"                 
## [31] "plane03/zh-plane03.hex.xz"                 
## [32] "plane0E/plane0E-nonprinting.hex.xz"        
## [33] "plane0E/plane0E-unassigned.hex.xz"         
## [34] "plane0E/plane0E.hex.xz"                    
## [35] "plane0Fcsur/plane0Fcsur-nonprinting.hex.xz"
## [36] "plane0Fcsur/plane0Fcsur.hex.xz"            
## [37] "precompiled/unifont_jp_sample.hex.xz"      
## [38] "precompiled/unifont_jp.hex.xz"             
## [39] "precompiled/unifont_sample.hex.xz"         
## [40] "precompiled/unifont_upper_sample.hex.xz"   
## [41] "precompiled/unifont_upper.hex.xz"          
## [42] "precompiled/unifont.hex.xz"
```

## <a name="examples">Examples</a>

The main function `unifont()` loads in several GNU Unifont hex files at the same time as a [{bittermelon}](https://github.com/trevorld/bittermelon) `bm_font()` object.  Arguments:

| Argument | Meaning | Default |
--- | --- | ---
| upper | Include glyphs above the Unicode Basic Multilingual plane | `TRUE` | 
| jp | Use Japanese version of Chinese characters | `FALSE` | 
| csur | Include (Under-)Conscript Unicode Registry glyphs | `TRUE` |
| sample | Add circle to "Combining" characters | `FALSE` | 
| ucp | Character vector of Unicode Code Points to only load | `NULL` |
| cache | Read/write a pre-compiled font from/to `tools::R_user_dir("hexfont", "cache")` | `FALSE` |


```r
library("bittermelon")
library("hexfont")
system.time(font <- unifont(cache = FALSE)) # Unifont is a **big** font
```

```
##    user  system elapsed 
##  96.128   0.120  96.268
```

```r
length(font) |> prettyNum(big.mark = ",") # number of glyphs
```

```
## [1] "123,234"
```

```r
object.size(font) |> format(units = "MB") # memory used
```

```
## [1] "189 Mb"
```

```r
# Faster to load from a cache
system.time(font <- unifont(cache = TRUE))
```

```
##    user  system elapsed 
##   0.643   0.000   0.644
```

```r
# Or just load the subset of GNU Unifont you need
s <- "ï¼²å¾ˆæ£’ï¼"
system.time(font_s <- unifont(ucp = str2ucp(s)))
```

```
##    user  system elapsed 
##    0.61    0.00    0.61
```

```r
# Mandarin Chinese
as_bm_bitmap(s, font = font_s) |>
    bm_compress("v")
```

```
##                     â–ˆ â–„â–„â–„â–„â–„â–„â–„      â–ˆ      â–ˆ                     
##    â–„â–„â–„â–„â–„â–„â–„        â–„â–€  â–ˆ     â–ˆ      â–ˆ  â–€â–€â–€â–€â–ˆâ–€â–€â–€â–€      â–„â–ˆâ–„        
##     â–ˆ     â–€â–„     â–€  â–ˆ â–ˆâ–€â–€â–€â–€â–€â–ˆ   â–€â–€â–€â–ˆâ–€â–€ â–€â–€â–ˆâ–€â–€â–€â–€       â–ˆâ–ˆâ–ˆ        
##     â–ˆ     â–„â–€      â–„â–ˆ  â–ˆâ–„â–„â–„â–„â–„â–ˆ     â–ˆâ–ˆâ–„ â–€â–€â–ˆâ–€â–€â–€â–ˆâ–€â–€      â–€â–ˆâ–€        
##     â–ˆâ–€â–€â–€â–ˆâ–€      â–„â–€ â–ˆ  â–ˆ  â–ˆ  â–„â–€   â–ˆ â–ˆ â–€â–„â–€  â–ˆ  â–€â–„       â–ˆ         
##     â–ˆ    â–€â–„        â–ˆ  â–ˆ   â–ˆâ–€    â–€  â–ˆ    â–€â–€â–ˆâ–€â–€                   
##    â–„â–ˆâ–„    â–„â–ˆâ–„      â–ˆ  â–ˆ â–„  â–€â–„      â–ˆ  â–€â–€â–€â–€â–ˆâ–€â–€â–€â–€       â–ˆ         
##                    â–ˆ  â–ˆâ–€     â–€â–€    â–ˆ      â–ˆ
```

```r
# Emoji
as_bm_bitmap("ðŸðŸ²ðŸµ", font = font) |>
    bm_compress("v")
```

```
##   â–„â–„       â–„â–„           â–„â–„â–„            â–„â–„       
## â–„â–€  â–€â–„â–„â–„â–„â–„â–€  â–€â–„       â–„â–ˆâ–€           â–„â–ˆâ–€â–ˆâ–ˆâ–€â–ˆâ–„    
## â–ˆ    â–€   â–€    â–ˆ      â–„â–ˆâ–ˆâ–ˆâ–ˆ       â–„â–€â–ˆ â–„â–„  â–„â–„ â–ˆâ–€â–„ 
## â–„â–ˆ   â–€   â–€   â–ˆâ–„   â–„â–„â–ˆâ–ˆâ–„â–ˆâ–ˆâ–ˆâ–ˆâ–ˆ     â–€â–„â–ˆ â–€â–€  â–€â–€ â–ˆâ–„â–€ 
## â–„â–ˆâ–€    â–„    â–€â–ˆâ–„ â–„â–ˆâ–„â–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆ     â–„â–€      â–€â–„   
##   â–€â–„  â–€â–€â–€  â–„â–€   â–€â–€â–€â–€â–€â–ˆâ–ˆâ–ˆâ–€â–€â–ˆâ–ˆâ–ˆâ–ˆâ–ˆ    â–ˆ â–€â–„â–„â–„â–„â–€ â–ˆ   
##     â–€â–€â–„â–„â–„â–€â–€        â–„â–ˆâ–ˆâ–ˆ   â–ˆâ–ˆâ–ˆâ–ˆâ–€     â–€â–€â–„â–„â–„â–„â–€â–€    
##                   â–€â–€â–€     â–€â–€â–€
```

```r
# Klingon
as_bm_list("ï£‘ï£ï£¦ï£™ï£—ï£˜", font = font) |>
    bm_pad(type = "trim", left = 1L, right = 1L) |>
    bm_call(cbind) |>
    bm_compress("v")
```

```
##                                                                               
##     â–„â–ˆâ–„ â–„â–„â–ˆâ–ˆâ–€â–€  â–€â–€â–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆ               â–„â–€       â–„â–ˆâ–„    â–„â–ˆâ–€  â–€â–ˆâ–„    â–„â–„       
##  â–„â–„â–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–€            â–€â–ˆâ–ˆ â–€            â–„â–ˆâ–€       â–ˆâ–ˆâ–ˆâ–€â–€  â–ˆâ–ˆâ–ˆ    â–ˆâ–ˆ   â–€â–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆ 
##   â–€â–ˆâ–ˆ  â–ˆâ–ˆ             â–„â–ˆâ–ˆâ–ˆ    â–„â–ˆ      â–„â–ˆâ–ˆ       â–ˆâ–ˆâ–€      â–€â–ˆâ–ˆâ–„â–„â–ˆâ–€      â–ˆâ–ˆâ–€ â–€â–ˆâ–ˆ 
##    â–€    â–ˆâ–„           â–ˆâ–ˆâ–ˆ      â–ˆâ–ˆâ–ˆâ–„â–„â–„â–„â–„â–ˆâ–ˆ      â–„â–ˆâ–ˆâ–ˆ        â–€â–ˆâ–ˆâ–ˆâ–€      â–„â–ˆâ–€   â–ˆâ–€ 
##          â–ˆâ–„          â–€â–ˆâ–„      â–ˆâ–ˆâ–€â–€â–€â–€â–€â–€â–ˆâ–ˆâ–ˆ    â–„â–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–ˆâ–„       â–€â–ˆâ–„     â–„â–ˆâ–€   â–ˆâ–€  
##           â–€â–„           â–€â–€â–„   â–„â–€        â–€â–ˆâ–„         â–€â–€â–„        â–€â–€â–„  â–„â–€    â–€    
## 
```

```r
# Tengwar with combining glyphs
bml <- as_bm_list("î€„î€”îŠî€…î€€î€î€¢îŠî€ƒîŽ", font = font)
to_raise <- which(names(bml) %in% c("U+E04A", "U+E04E"))
bml[to_raise] <- bm_shift(bml[to_raise], top = 1L)
bml |> bm_compose(pua_combining = unifont_combining()) |>
    bm_pad(type = "trim", left = 1L, right = 1L) |>
    bm_call(cbind) |>
    bm_compress("v")
```

```
##                  â–„                    â–ˆâ–ˆ       â–„      â–„ â–„   
##                 â–ˆ â–€                 â–„â–„  â–„â–„    â–ˆ â–€    â–ˆ â–ˆ â–€  
##                 â–€                   â–€â–€  â–€â–€    â–€      â–€ â–€    
##  â–ˆâ–„â–€â–€â–ˆâ–„â–„â–€â–€â–ˆâ–„  â–ˆâ–„â–€â–€â–ˆâ–„  â–ˆâ–„â–€â–€â–ˆâ–„â–„â–€â–€â–ˆâ–„   â–ˆâ–„â–€â–€â–ˆâ–„ â–€â–€â–€â–ˆâ–€â–€â–€â–€ â–€â–ˆâ–ˆâ–€â–€â–€â–ˆ 
##  â–ˆ    â–ˆ    â–ˆ  â–ˆ    â–ˆ  â–ˆ   â–„â–ˆ   â–„â–ˆ   â–ˆ    â–ˆ   â–ˆ       â–ˆâ–„  â–„â–ˆ 
##  â–ˆ  â–€â–€   â–€â–€   â–€  â–€â–€   â–ˆâ–€â–€â–€â–€â–€â–€â–€â–€â–€â–€â–€  â–ˆ  â–€â–€   â–„â–€        â–€â–€â–€ â–ˆ 
##  â–ˆ                    â–ˆ             â–ˆ       â–ˆ             â–ˆ 
##  â–ˆ                    â–ˆ             â–ˆ       â–€â–ˆâ–„â–„â–„â–€        â–ˆ
```

## <a name="license">License</a>

The overall license for this package is GPL (>=2) but the bundled hex font files 
are also available under more permissive terms.  Excerpt from `font/COPYING` 

> License for `font/plane00/jiskan16-plane00.hex` and
> `font/plane02/jiskan16-plane02.hex`:
> 
>      These two files are in the Public Domain.  They were created
>      from Public Domain BDF font files jiskan16-2004-1.bdf and
>      jiskan16-2000-2.bdf.
> 
> 
> License for font files except the jiskan16 files mentioned above
> are dual-licensed under the SIL Open Font License version 1.1,
> and under this GNU license:
> 
>      All glyphs are released under the GNU General Public License
>      (GPL) version 2 or (at your option) a later version, with the
>      GNU font embedding exception:
> 
>           ** GPL v2.0 license with font embedding exception:
> 
>           As a special exception, if you create a document which
>           uses this font, and embed this font or unaltered portions
>           of this font into the document, this font does not by
>           itself cause the resulting document to be covered by
>           the GNU General Public License. This exception does not
>           however invalidate any other reasons why the document
>           might be covered by the GNU General Public License.
>           If you modify this font, you may extend this exception
>           to your version of the font, but you are not obligated
>           to do so. If you do not wish to do so, delete this
>           exception statement from your version.