diff --git a/README.md b/README.md index fd020e69..c468da61 100644 --- a/README.md +++ b/README.md @@ -192,12 +192,17 @@ Create a Path that represents the given text. * `x`: Horizontal position of the beginning of the text. (default: `0`) * `y`: Vertical position of the *baseline* of the text. (default: `0`) * `fontSize`: Size of the text in pixels (default: `72`). +* `options`: _{GlyphRenderOptions}_ passed to each glyph, see below -Options is an optional object containing: +Options is an optional _{GlyphRenderOptions}_ object containing: +* `script`: script used to determine which features to apply (default: `"DFLT"` or `"latn"`) +* `language`: language system used to determine which features to apply (default: `"dflt"`) * `kerning`: if true takes kerning information into account (default: `true`) * `features`: an object with [OpenType feature tags](https://docs.microsoft.com/en-us/typography/opentype/spec/featuretags) as keys, and a boolean value to enable each feature. Currently only ligature features `"liga"` and `"rlig"` are supported (default: `true`). * `hinting`: if true uses TrueType font hinting if available (default: `false`). +* `colorFormat`: the format colors are converted to for rendering (default: `"hexa"`). Can be `"rgb"`/`"rgba"` for `rgb()`/`rgba()` output, `"hex"`/`"hexa"` for 6/8 digit hex colors, or `"hsl"`/`"hsla"` for `hsl()`/`hsla()` output. `"bgra"` outputs an object with r, g, b, a keys (r/g/b from 0-255, a from 0-1). `"raw"` outputs an integer as used in the CPAL table. +* `fill`: font color, the color used to render each glyph (default: `"black"`) _**Note:** there is also `Font.getPaths()` with the same arguments, which returns a list of Paths._ @@ -207,6 +212,7 @@ Create a Path that represents the given text. * `x`: Horizontal position of the beginning of the text. (default: `0`) * `y`: Vertical position of the *baseline* of the text. (default: `0`) * `fontSize`: Size of the text in pixels (default: `72`). +* `options`: _{GlyphRenderOptions}_ passed to each glyph, see `Font.getPath()` Options is an optional object containing: * `kerning`: if `true`, takes kerning information into account (default: `true`) @@ -244,7 +250,101 @@ bounding box than its advance width. This corresponds to `canvas2dContext.measureText(text).width` * `fontSize`: Size of the text in pixels (default: `72`). -* `options`: See `Font.getPath()` +* `options`: _{GlyphRenderOptions}_, see `Font.getPath()` + +#### The `Font.palettes` object (`PaletteManager`) + +This allows to manage the palettes and colors in the CPAL table, without having to modify the table manually. + +###### `Font.palettes.add(colors)` +Add a new palette. +* `colors`: (optional) colors to add to the palette, differences to existing palettes will be filled with the defaultValue. + +###### `Font.palettes.delete(paletteIndex)` +Deletes a palette by its zero-based index +* `paletteIndex`: zero-based palette index + +###### `Font.palettes.deleteColor(colorIndex, replacementIndex)` +Deletes a specific color index in all palettes and updates all layers using that color with the color currently held in the replacement index +* `colorIndex`: index of the color that should be deleted +* `replacementIndex`: index (according to the palette before deletion) of the color to replace in layers using the color to be to deleted + +###### `Font.palettes.cpal()` +Returns the font's cpal table, or false if it does not exist. Used internally. + +###### `Font.palettes.ensureCPAL(colors)` +Mainly used internally. Makes sure that the CPAL table exists or is populated with default values. +* `colors`: (optional) colors to populate on creation +returns `true` if it was created, `false` if it already existed. + +###### `Font.palettes.extend(num)` +Extend all existing palettes and the numPaletteEntries value by a number of color slots +* `num`: number of additional color slots to add to all palettes + +###### `Font.palettes.fillPalette(palette, colors, colorCount)` +Fills a set of palette colors (from a palette index, or a provided array of CPAL color values) with a set of colors, falling back to the default color value, until a given count. *It does not modify the existing palette, returning a new array instead!* Use `Font.palettes.setColor()` instead if needed. +* `palette`: palette index or an Array of CPAL color values to fill the palette with, the rest will be filled with the default color +* `colors`: array of color values to fill the palette with, in a format supported as an output of `colorFormat` in _{GlyphRenderOptions}_, see `Font.getPath()`. CSS color names are also supported in browser context. +* `colorCount`: Number of colors to fill the palette with, defaults to the value of the numPaletteEntries field + +###### `Font.palettes.getAll(colorFormat)` +Returns an array of arrays of color values for each palette, optionally in a specified color format +* `colorFormat`: (optional) See _{GlyphRenderOptions}_ at `Font.getPath()`, (default: `"hexa"`) + +###### `Font.palettes.getColor(index, paletteIndex, colorFormat)` +Get a specific palette by its zero-based index +* `index`: zero-based index of the color in the palette +* `paletteIndex`: zero-based palette index (default: 0) +* `colorFormat`: (optional) See _{GlyphRenderOptions}_ at `Font.getPath()`, (default: `"hexa"`) + +###### `Font.palettes.get(paletteIndex, colorFormat)` +Get a specific palette by its zero-based index +* `paletteIndex`: zero-based palette index +* `colorFormat`: (optional) See _{GlyphRenderOptions}_ at `Font.getPath()`, (default: `"hexa"`) + +###### `Font.palettes.setColor(index, colors, paletteIndex)` +Set one or more colors on a specific palette by its zero-based index +* `index`: zero-based color index to start filling from +* `color`: color value or array of color values in a color notation supported as an output of `colorFormat` in _{GlyphRenderOptions}_, see `Font.getPath()`. CSS color names are also supported in browser context. +* `paletteIndex`: zero-based palette index (default: 0) + +###### `Font.palettes.toCPALcolor(color)` +Converts a color value string to a CPAL integer color value +* `color`: string in a color notation supported as an output of `colorFormat` in _{GlyphRenderOptions}_, see `Font.getPath()`. CSS color names are also supported in browser context. + + +##### The `Font.layers` object (`LayerManager`) + +This allows to manage the color glyph layers in the COLR table, without having to modify the table manually. + +###### `Font.layers.add(glyphIndex, layers, position)` +Adds one or more layers to a glyph, at the end or at a specific position. +* `glyphIndex`: glyph index to add the layer(s) to. +* `layers`: layer object {glyph, paletteIndex}/{glyphID, paletteIndex} or array of layer objects. +* `position`: position to insert the layers at (will default to adding at the end). + +###### `Font.layers.ensureCOLR()` +Mainly used internally. Ensures that the COLR table exists and is populated with default values. + +###### `Font.layers.get(glyphIndex)` +Gets the layers for a specific glyph +* `glyphIndex` +Returns an array of `{glyph, paletteIndex}` layer objects. + +###### `Font.layers.remove(glyphIndex, start, end = start)` +Removes one or more layers from a glyph. +* `glyphIndex`: glyph index to remove the layer(s) from +* `start`: index to remove the layer at +* `end`: (optional) if provided, removes all layers from start index to (and including) end index + +###### `Font.layers.setPaletteIndex(glyphIndex, layerIndex, paletteIndex)` +Sets a color glyph layer's paletteIndex property to a new index +* `glyphIndex`: glyph in the font by zero-based glyph index +* `layerIndex`: layer in the glyph by zero-based layer index +* `paletteIndex`: new color to set for the layer by zero-based index in any palette + +###### `Font.layers.updateColrTable(glyphIndex, layers)` +Mainly used internally. Updates the colr table, adding a baseGlyphRecord if needed, ensuring that it's inserted at the correct position, updating numLayers, and adjusting firstLayerIndex values for all baseGlyphRecords according to any deletions or insertions. #### The Glyph object A Glyph is an individual mark that often corresponds to a character. Some glyphs, such as ligatures, are a combination of many characters. Glyphs are the basic building blocks of a font. @@ -259,24 +359,28 @@ A Glyph is an individual mark that often corresponds to a character. Some glyphs * `xMin`, `yMin`, `xMax`, `yMax`: The bounding box of the glyph. * `path`: The raw, unscaled path of the glyph. -##### `Glyph.getPath(x, y, fontSize)` +##### `Glyph.getPath(x, y, fontSize, options, font)` Get a scaled glyph Path object for use on a drawing context. * `x`: Horizontal position of the glyph. (default: `0`) * `y`: Vertical position of the *baseline* of the glyph. (default: `0`) * `fontSize`: Font size in pixels (default: `72`). +* `options`: _{GlyphRenderOptions}_, see `Font.getPath()` +* `font`: a font object, needed for rendering COLR/CPAL fonts to get the layers and colors ##### `Glyph.getBoundingBox()` Calculate the minimum bounding box for the unscaled path of the given glyph. Returns an `opentype.BoundingBox` object that contains `x1`/`y1`/`x2`/`y2`. If the glyph has no points (e.g. a space character), all coordinates will be zero. -##### `Glyph.draw(ctx, x, y, fontSize)` +##### `Glyph.draw(ctx, x, y, fontSize, options, font)` Draw the glyph on the given context. * `ctx`: The drawing context. * `x`: Horizontal position of the glyph. (default: `0`) * `y`: Vertical position of the *baseline* of the glyph. (default: `0`) * `fontSize`: Font size, in pixels (default: `72`). +* `options`: _{GlyphRenderOptions}_, see `Font.getPath()` +* `font`: a font object, needed for rendering COLR/CPAL fonts to get the layers and colors -##### `Glyph.drawPoints(ctx, x, y, fontSize)` +##### `Glyph.drawPoints(ctx, x, y, fontSize, options, font)` Draw the points of the glyph on the given context. On-curve points will be drawn in blue, off-curve points will be drawn in red. The arguments are the same as `Glyph.draw()`. @@ -291,6 +395,9 @@ The arguments are the same as `Glyph.draw()`. ##### `Glyph.toPathData(options)`, `Glyph.toDOMElement(options)`, `Glyph.toSVG(options)`, `Glyph.fromSVG(pathData, options)`, These are currently only wrapper functions for their counterparts on Path objects (see documentation there), but may be extended in the future to pass on Glyph data for automatic calculation. +##### `Glyph.getLayers(font)` +Gets the color glyph layers for this glyph from the specified font's COLR/CPAL tables + ### The Path object Once you have a path through `Font.getPath()` or `Glyph.getPath()`, you can use it. diff --git a/docs/examples/creating-fonts.html b/docs/examples/creating-fonts.html index 88948f3b..78677eba 100644 --- a/docs/examples/creating-fonts.html +++ b/docs/examples/creating-fonts.html @@ -139,7 +139,7 @@
var x = 50; var y = 120; var fontSize = 72; - glyph.draw(ctx, x, y, fontSize); + glyph.draw(ctx, x, y, fontSize, {}, font2); glyph.drawPoints(ctx, x, y, fontSize); glyph.drawMetrics(ctx, x, y, fontSize); } diff --git a/docs/examples/reading-writing.html b/docs/examples/reading-writing.html index d7c27d9b..5e56b0b0 100644 --- a/docs/examples/reading-writing.html +++ b/docs/examples/reading-writing.html @@ -71,7 +71,7 @@ const x = 50; const y = 120; const fontSize = 72; - glyph.draw(ctx, x, y, fontSize); + glyph.draw(ctx, x, y, fontSize, {}, font2); glyph.drawPoints(ctx, x, y, fontSize); glyph.drawMetrics(ctx, x, y, fontSize); } diff --git a/docs/font-inspector.html b/docs/font-inspector.html index 52e1ea14..b515dd5e 100644 --- a/docs/font-inspector.html +++ b/docs/font-inspector.html @@ -76,10 +76,17 @@opentype.js is available on GitHub under the MIT License.
@@ -127,7 +134,7 @@opentype.js is available on GitHub under the MIT License.
@@ -60,6 +69,8 @@