Options
All
  • Public
  • Public/Protected
  • All
Menu

Class DistanceFieldStyle

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:

  • Field Agent - a Ruby script that uses ImageMagick to create single-channel distance field textures. Part of the Starling download ('util' directory).
  • msdfgen - an excellent and fast open source command line tool that creates multi- and single-channel 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:

  • msdf-bmfont-xml - a command line tool powered by msdf and thus producing excellent multi-channel output.
  • Littera - a free online bitmap font generator.
  • Hiero - a cross platform tool.
  • BMFont - Windows-only, from AngelCode.

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.

Hierarchy

Index

Constructors

constructor

  • 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.

    Parameters

    • Optional softness: number
    • Optional threshold: number

    Returns DistanceFieldStyle

Properties

alpha

alpha: number

The alpha value with which the inner area (what's rendered in 'basic' mode) is drawn. @default 1.0

color

color: number

Changes the color of all vertices to the same value. The getter simply returns the color of the first vertex.

indexData

indexData: IndexData

Returns a reference to the index data of the assigned target (or null if there is no target). Beware: the style itself does not own any indices; it is limited to manipulating those of the target mesh.

mode

mode: string

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

multiChannel

multiChannel: boolean

Indicates if the distance field texture utilizes multiple channels. This improves render quality, but requires specially created DF textures. @default false

outerAlphaEnd

outerAlphaEnd: number

The alpha value on the outer side of the outer area's gradient. Used for outline, glow, and drop shadow modes.

outerAlphaStart

outerAlphaStart: number

The alpha value on the inner side of the outer area's gradient. Used for outline, glow, and drop shadow modes.

outerColor

outerColor: number

The color with which the outer area (outline, glow, or drop shadow) will be filled. Ignored in 'basic' mode.

outerThreshold

outerThreshold: number

The threshold that determines where the outer area (outline, glow, or drop shadow) ends. Ignored in 'basic' mode.

shadowOffsetX

shadowOffsetX: 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.

shadowOffsetY

shadowOffsetY: 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.

softness

softness: 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

target

target: Mesh

The target the style is currently assigned to.

texture

texture: Texture

The texture that is mapped to the mesh (or null, if there is none).

textureRepeat

textureRepeat: boolean

Indicates if pixels at the edges will be repeated or clamped. Only works for power-of-two textures. @default false

textureSmoothing

textureSmoothing: string

The smoothing filter that is used for the texture. @default bilinear

threshold

threshold: number

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

type

type: any

The actual class of this style.

vertexData

vertexData: VertexData

Returns a reference to the vertex data of the assigned target (or null if there is no target). Beware: the style itself does not own any vertices; it is limited to manipulating those of the target mesh.

vertexFormat

vertexFormat: VertexDataFormat

The format used to store the vertices.

Static MODE_BASIC

MODE_BASIC: string

Basic distance field rendering, without additional effects.

Static MODE_GLOW

MODE_GLOW: string

Adds a smooth glow effect around the shape.

Static MODE_OUTLINE

MODE_OUTLINE: string

Adds an outline around the edge of the shape.

Static MODE_SHADOW

MODE_SHADOW: string

Adds a drop shadow behind the shape.

Static VERTEX_FORMAT

VERTEX_FORMAT: VertexDataFormat

The vertex format expected by this style.

Methods

addEventListener

  • addEventListener(type: string, listener: Function): void

batchIndexData

  • batchIndexData(targetStyle: MeshStyle, targetIndexID?: number, offset?: number, indexID?: number, numIndices?: number): void
  • Copies the index data of the style's current target to the target of another style. The given offset value will be added to all indices during the process.

    This method is used when batching meshes together for rendering. The parameter targetStyle will point to the style of a MeshBatch (a subclass of Mesh). Subclasses may override this method if they need to modify the index data in that process.

    Parameters

    • targetStyle: MeshStyle
    • Optional targetIndexID: number
    • Optional offset: number
    • Optional indexID: number
    • Optional numIndices: number

    Returns void

Protected batchVertexData

  • batchVertexData(targetStyle: MeshStyle, targetVertexID?: number, matrix?: Matrix, vertexID?: number, numVertices?: number): void

Protected canBatchWith

  • canBatchWith(meshStyle: MeshStyle): boolean

clone

Protected copyFrom

Protected createEffect

dispatchEvent

  • dispatchEvent(event: Event): void
  • Dispatches an event to all objects that have registered listeners for its type. If an event with enabled 'bubble' property is dispatched to a display object, it will travel up along the line of parents, until it either hits the root object or someone stops its propagation manually.

    Parameters

    Returns void

dispatchEventWith

  • dispatchEventWith(type: string, bubbles?: boolean, data?: any): void

getTexCoords

  • getTexCoords(vertexID: number, out?: Point): Point

getVertexAlpha

  • getVertexAlpha(vertexID: number): number

getVertexColor

  • getVertexColor(vertexID: number): number

getVertexPosition

  • getVertexPosition(vertexID: number, out?: Point): Point
  • The position of the vertex at the specified index, in the mesh's local coordinate system.

    Only modify the position of a vertex if you know exactly what you're doing, as some classes might not work correctly when their vertices are moved. E.g. the Quad class expects its vertices to spawn up a perfectly rectangular area; some of its optimized methods won't work correctly if that premise is no longer fulfilled or the original bounds change.

    Parameters

    • vertexID: number
    • Optional out: Point

    Returns Point

Protected get_alpha

  • get_alpha(): number

Protected get_color

  • get_color(): number

Protected get_indexData

Protected get_mode

  • get_mode(): string

Protected get_multiChannel

  • get_multiChannel(): boolean

Protected get_outerAlphaEnd

  • get_outerAlphaEnd(): number

Protected get_outerAlphaStart

  • get_outerAlphaStart(): number

Protected get_outerColor

  • get_outerColor(): number

Protected get_outerThreshold

  • get_outerThreshold(): number

Protected get_shadowOffsetX

  • get_shadowOffsetX(): number

Protected get_shadowOffsetY

  • get_shadowOffsetY(): number

Protected get_softness

  • get_softness(): number

Protected get_target

  • get_target(): Mesh

Protected get_texture

Protected get_textureRepeat

  • get_textureRepeat(): boolean

Protected get_textureSmoothing

  • get_textureSmoothing(): string

Protected get_threshold

  • get_threshold(): number

Protected get_type

  • get_type(): any

Protected get_vertexData

Protected get_vertexFormat

hasEventListener

  • hasEventListener(type: string, listener?: any): boolean

removeEventListener

  • removeEventListener(type: string, listener: Function): void

removeEventListeners

  • removeEventListeners(type?: string): void

setTexCoords

  • setTexCoords(vertexID: number, u: number, v: number): void

setVertexAlpha

  • setVertexAlpha(vertexID: number, alpha: number): void

setVertexColor

  • setVertexColor(vertexID: number, color: number): void

setVertexPosition

  • setVertexPosition(vertexID: number, x: number, y: number): void

Protected set_alpha

  • set_alpha(value: number): number

Protected set_color

  • set_color(value: number): number

Protected set_mode

  • set_mode(value: string): string

Protected set_multiChannel

  • set_multiChannel(value: boolean): boolean

Protected set_outerAlphaEnd

  • set_outerAlphaEnd(value: number): number

Protected set_outerAlphaStart

  • set_outerAlphaStart(value: number): number

Protected set_outerColor

  • set_outerColor(value: number): number

Protected set_outerThreshold

  • set_outerThreshold(value: number): number

Protected set_shadowOffsetX

  • set_shadowOffsetX(value: number): number

Protected set_shadowOffsetY

  • set_shadowOffsetY(value: number): number

Protected set_softness

  • set_softness(value: number): number

Protected set_texture

Protected set_textureRepeat

  • set_textureRepeat(value: boolean): boolean

Protected set_textureSmoothing

  • set_textureSmoothing(value: string): string

Protected set_threshold

  • set_threshold(value: number): number

setupBasic

  • setupBasic(): void

setupDropShadow

  • setupDropShadow(blur?: number, offsetX?: number, offsetY?: 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.

    Parameters

    • Optional blur: number
    • Optional offsetX: number
    • Optional offsetY: number
    • Optional color: number
    • Optional alpha: number

    Returns void

setupGlow

  • setupGlow(blur?: 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'.

    Parameters

    • Optional blur: number
    • Optional color: number
    • Optional alpha: number

    Returns void

setupOutline

  • setupOutline(width?: number, color?: number, alpha?: number): void
  • Sets up outline rendering mode. The 'width' determines the threshold where the outline ends; 'width + threshold' must not exceed '1.0'.

    Parameters

    • Optional width: number
    • Optional color: number
    • Optional alpha: number

    Returns void

Protected updateEffect

Generated using TypeDoc