1Text API Overview 2============= 3*2D Graphics* is a broad area. It consists of a host of related, but different ideas and primitives 4- rectangles, lines, paths 5- images (often scaled, transformed, filtered) 6- text (also scalable and transformable) 7- ... 8 9Native (desktop, mobile) frameworks combine these primitives with common rendering constructs 10- transforms and clipping 11- colors, gradients, patterns 12- blending and colorspaces 13 14One 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: 15- CoreGraphics --> CoreText 16- Direct2D/X --> DirectWrite 17- Skia --> SkShaper 18 19This proposal embraces this pattern, and aims to expose this functionality to the Web. 20 21 22## Background 23 24Part 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. 25 26## Language and Alphabets 27 28### "The office 建造 is in München." 29 30This simple sentence is illustrative of some of the richness (i.e. complexity) of displaying text. Some examples 31- 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)). 32- 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. 33- The third word may not be reprsentable in the same font as the other words, so a different font may have been needed. 34 35This 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. 36 37## Fonts and Styles 38 39This [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. 40 41- family-name : "Helvetica", "Times New Roman", "Lucida Typewriter Sans", ... 42- font-style : bold, italic 43- font-weight : 100 .. 900 44- font-stretch : ultra-condensed .. ultra-expanded 45- font-variation-setting : 'wght' 850 or 'wdth' 25 or ... 46 47All 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). 48 49## Typefaces and Glyphs 50 51We 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). 52 53Along 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. 54 55Determining 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. 56 57## Summary 58 59We 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. 60 61The core [Shaping APIs](text_shaper.md) are detailed here. 62 63Assocated [Canvas2D extensions](text_c2d.md) are detailed here. 64 65Note: 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 . 66- drawn using WebGL or WebGPU 67- drawn using DOM (but utilizing line-breaking and metrics results) 68- drawn using a bespoke (i.e. wasm) renderer 69 70We are also proposing a lower level interface, one that just addresses exposing [unicode properties](uni_characterize.md). 71 72 73## Contributors: 74 [mikerreed](https://github.com/mikerreed), 75