import MeshStyle from "./MeshStyle"; import VertexDataFormat from "../rendering/VertexDataFormat"; import RenderState from "../rendering/RenderState"; import MeshEffect from "../rendering/MeshEffect"; import Matrix from "openfl/geom/Matrix"; declare namespace starling.styles { /** * Provides support for signed distance fields to Starling meshes. * * * *

Signed distance field rendering allows bitmap fonts and other single colored shapes to * * be drawn without jagged edges, even at high magnifications. The technique was introduced in * * the SIGGRAPH paper Improved * * Alpha-Tested Magnification for Vector Textures and Special Effects by Valve Software. * *

* * * *

While bitmap fonts are a great solution to render text in a GPU-friendly way, they * * don't scale well. For best results, one has to embed the font in all the sizes used within * * the app. The distance field style solves this issue: instead of providing a standard * * black and white image of the font, it uses a signed distance field texture as * * its input (a texture that encodes, for each pixel, the distance to the closest edge of a * * vector shape). With this data, the shape can be rendered smoothly at almost any scale.

* * * *

Here are some tools that support creation of such distance field textures:

* * * * * * * *

The former tools convert arbitrary SVG or PNG images to distance field textures. * * To create distance field fonts, have a look at the following alternatives:

* * * * * * * * Single-Channel vs. Multi-Channel * * * *

The original approach for distance field textures uses just a single channel (encoding * * the distance of each pixel to the shape that's being represented). By utilizing * * all three color channels, however, the results can be greatly enhanced - a technique * * developed by Viktor Chlumský.

* * * *

Starling supports such multi-channel DF textures, as well. When using an appropriate * * texture, don't forget to enable the style's multiChannel property.

* * * * Special effects * * * *

Another advantage of this rendering technique: it supports very efficient rendering of * * some popular filter effects, in just one pass, directly on the GPU. You can add an * * outline around the shape, let it glow in an arbitrary color, or add * * a drop shadow.

* * * *

The type of effect currently used is called the 'mode'. * * Meshes with the same mode will be batched together on rendering.

* */ export class DistanceFieldStyle extends MeshStyle { /** * Creates a new distance field style. * * * * @param softness adds a soft transition between the inside and the outside. * * This should typically be 1.0 divided by the spread (in points) * * used when creating the distance field texture. * * @param threshold the value separating the inside from the outside of the shape. * * Range: 0 - 1. * */ constructor(softness?: number, threshold?: number); /** * Basic distance field rendering, without additional effects. */ static readonly MODE_BASIC = "basic"; /** * Adds an outline around the edge of the shape. */ static readonly MODE_OUTLINE = "outline"; /** * Adds a smooth glow effect around the shape. */ static readonly MODE_GLOW = "glow"; /** * Adds a drop shadow behind the shape. */ static readonly MODE_SHADOW = "shadow"; /** * @private */ override copyFrom(meshStyle: MeshStyle): void; /** * @private */ override createEffect(): MeshEffect; /** * @private */ override batchVertexData(targetStyle: MeshStyle, targetVertexID?: number, matrix?: Matrix, vertexID?: number, numVertices?: number): void; /** * @private */ override updateEffect(effect: MeshEffect, state: RenderState): void; /** * @private */ override canBatchWith(meshStyle: MeshStyle): boolean; /** * Restores basic render mode, i.e. smooth rendering of the shape. */ setupBasic(): void; /** * Sets up outline rendering mode. The 'width' determines the threshold where the * * outline ends; 'width + threshold' must not exceed '1.0'. * */ setupOutline(width?: number, color?: number, alpha?: number): void; /** * Sets up glow rendering mode. The 'blur' determines the threshold where the * * blur ends; 'blur + threshold' must not exceed '1.0'. * */ setupGlow(blur?: number, color?: number, alpha?: number): void; /** * Sets up shadow rendering mode. The 'blur' determines the threshold where the drop * * shadow ends; 'offsetX' and 'offsetY' are expected in points. * * * *

Beware that the style can only act within the limits of the mesh's vertices. * * This means that not all combinations of blur and offset are possible; too high values * * will cause the shadow to be cut off on the sides. Reduce either blur or offset to * * compensate.

* */ setupDropShadow(blur?: number, offsetX?: number, offsetY?: number, color?: number, alpha?: number): void; /** * The current render mode. It's recommended to use one of the 'setup...'-methods to * * change the mode, as those provide useful standard settings, as well. @default basic */ get mode(): string; set mode(value: string) /** * Indicates if the distance field texture utilizes multiple channels. This improves * * render quality, but requires specially created DF textures. @default false */ get multiChannel(): boolean; set multiChannel(value: boolean) /** * The threshold that will separate the inside from the outside of the shape. On the * * distance field texture, '0' means completely outside, '1' completely inside; the * * actual edge runs along '0.5'. @default 0.5 */ get threshold(): number; set threshold(value: number) /** * Indicates how soft the transition between inside and outside should be rendered. * * A value of '0' will lead to a hard, jagged edge; '1' will be just as blurry as the * * actual distance field texture. The recommend value should be 1.0 / spread * * (you determine the spread when creating the distance field texture). @default 0.125 */ get softness(): number; set softness(value: number) /** * The alpha value with which the inner area (what's rendered in 'basic' mode) is drawn. * * @default 1.0 */ get alpha(): number; set alpha(value: number) /** * The threshold that determines where the outer area (outline, glow, or drop shadow) * * ends. Ignored in 'basic' mode. */ get outerThreshold(): number; set outerThreshold(value: number) /** * The alpha value on the inner side of the outer area's gradient. * * Used for outline, glow, and drop shadow modes. */ get outerAlphaStart(): number; set outerAlphaStart(value: number) /** * The alpha value on the outer side of the outer area's gradient. * * Used for outline, glow, and drop shadow modes. */ get outerAlphaEnd(): number; set outerAlphaEnd(value: number) /** * The color with which the outer area (outline, glow, or drop shadow) will be filled. * * Ignored in 'basic' mode. */ get outerColor(): number; set outerColor(value: number) /** * The x-offset of the shadow in points. Note that certain combinations of offset and * * blur value can lead the shadow to be cut off at the edges. Reduce blur or offset to * * counteract. */ get shadowOffsetX(): number; set shadowOffsetX(value: number) /** * The y-offset of the shadow in points. Note that certain combinations of offset and * * blur value can lead the shadow to be cut off at the edges. Reduce blur or offset to * * counteract. */ get shadowOffsetY(): number; set shadowOffsetY(value: number) } } export default starling.styles.DistanceFieldStyle;