1--- 2title: 'Text API Overview' 3linkTitle: 'Text API Overview' 4--- 5 6*2D Graphics* is a broad area. It consists of a host of related, but different ideas and primitives 7- rectangles, lines, paths 8- images (often scaled, transformed, filtered) 9- text (also scalable and transformable) 10- ... 11 12Native (desktop, mobile) frameworks combine these primitives with common rendering constructs 13- transforms and clipping 14- colors, gradients, patterns 15- blending and colorspaces 16 17One primitive in particular stands out: **Text**. It can be drawn with the same common constructs as rects and paths, but it has another component unrelated to actual drawing, a 'processing' step that is surprisingly complex and expensive: **Shaping**. The native frameworks recognized this, and offer a separate set of APIs just around this: 18- CoreGraphics --> CoreText 19- Direct2D/X --> DirectWrite 20- Skia --> SkShaper 21 22This proposal embraces this pattern, and aims to expose this functionality to the Web. 23 24 25## Background 26 27Part of this complexity lies in language and alphabets themselves, and part is due to how our system of fonts and font formats have evolved. This document does not claim to detail either of these, but will briefly touch on each to motivate the proposed API suite. 28 29## Language and Alphabets 30 31### "The office 大楼 is in München." 32 33This simple sentence is illustrative of some of the richness (i.e. complexity) of displaying text. Some examples 34- The 'ffi" in office (or possibly just the "fi") **could** be drawn with a specialized form called a [ligature](https://en.wikipedia.org/wiki/Ligature_(writing)). 35- The "ü" could have been drawn as a single shape, or it could have been drawn by separately drawing "u" followed by drawing the umlaut (¨) on top. 36- The third word may not be representable in the same font as the other words, so a different font may have been needed. 37 38This example in no way attempts to be complete or exhaustive, but it suggests the processing needed to go from just the 'letters' in a sentence, to the actual 'shapes' that must be found or composed from various fonts to finally be able to draw it. 39 40## Fonts and Styles 41 42This [site](https://www.w3schools.com/css/css_font.asp) has an excellent overview of some of the richess of specifying a "font" in CSS. While different native platforms have some variance, most support the following *mapping* from a description of a font, to the actual resource / file / blob containing the drawn shapes. 43 44- family-name : "Helvetica", "Times New Roman", "Lucida Typewriter Sans", ... 45- font-style : bold, italic 46- font-weight : 100 .. 900 47- font-stretch : ultra-condensed .. ultra-expanded 48- font-variation-setting : 'wght' 850 or 'wdth' 25 or ... 49 50All of these attributes (and more) go into the browser's search for the best matching font resource/file/blob. Let's call the resulting 'resource' a **Typeface**. Note: If the font supports variation-settings, our definition will also include the specific settings (e.g. a font resource + variation settings). 51 52## Typefaces and Glyphs 53 54We define a Typeface to be a coherent collection of shapes in a given typograph style (including any variation settings). Typically a typeface is stored in a single file or blob (e.g. an OpenType file). 55 56Along with a single Typeface we define the individual *shapes* or images in the typeface as **Glyphs**. Glyphs represent the smallest independent drawing element within a typeface. By convention, glyphs are identified by an *index*, ranging from 0 to however many are in a particular typeface. 57 58Determining what glyphs, in what order and positions, are needed to represent a set of letters, is the heart of **Shaping**, and it is this process, and resulting typefaces + positioned glyphs, that we propose exposing to Web Apps. 59 60## Summary 61 62We posit that drawing *internationally correct* Text is critical to most Web Apps, and that it is both complex to get correct, and can be computationally expensive. We propose exposing this processing to apps, providing them with results that can be efficiently drawn / animated. 63 64The core [Shaping APIs](/docs/dev/design/text_shaper) are detailed here. 65 66Associated [Canvas2D extensions](/docs/dev/design/text_c2d) are detailed here. 67 68Note: it is an explicit goal to **not** tie Shaping or its results to Canvas2D. We envision multiple scenarios where a framework or app will want to shape text, but not need a Canvas2D context . 69- drawn using WebGL or WebGPU 70- drawn using DOM (but utilizing line-breaking and metrics results) 71- drawn using a bespoke (i.e. wasm) renderer 72 73We are also proposing a lower level interface, one that just addresses exposing [unicode properties](/docs/dev/design/uni_characterize). 74 75 76## Contributors: 77 [mikerreed](https://github.com/mikerreed), 78