Packagestarling.styles
Classpublic class DistanceFieldStyle
InheritanceDistanceFieldStyle Inheritance MeshStyle Inheritance EventDispatcher Inheritance Object

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.


Public Properties
 PropertyDefined By
  alpha : Number
The alpha value with which the inner area (what's rendered in 'basic' mode) is drawn.
DistanceFieldStyle
 Inheritedcolor : uint
Changes the color of all vertices to the same value.
MeshStyle
  mode : String
The current render mode.
DistanceFieldStyle
  multiChannel : Boolean
Indicates if the distance field texture utilizes multiple channels.
DistanceFieldStyle
  outerAlphaEnd : Number
The alpha value on the outer side of the outer area's gradient.
DistanceFieldStyle
  outerAlphaStart : Number
The alpha value on the inner side of the outer area's gradient.
DistanceFieldStyle
  outerColor : uint
The color with which the outer area (outline, glow, or drop shadow) will be filled.
DistanceFieldStyle
  outerThreshold : Number
The threshold that determines where the outer area (outline, glow, or drop shadow) ends.
DistanceFieldStyle
  shadowOffsetX : Number
The x-offset of the shadow in points.
DistanceFieldStyle
  shadowOffsetY : Number
The y-offset of the shadow in points.
DistanceFieldStyle
  softness : Number
Indicates how soft the transition between inside and outside should be rendered.
DistanceFieldStyle
 Inheritedtarget : Mesh
[read-only] The target the style is currently assigned to.
MeshStyle
 Inheritedtexture : Texture
The texture that is mapped to the mesh (or null, if there is none).
MeshStyle
 InheritedtextureRepeat : Boolean
Indicates if pixels at the edges will be repeated or clamped.
MeshStyle
 InheritedtextureSmoothing : String
The smoothing filter that is used for the texture.
MeshStyle
  threshold : Number
The threshold that will separate the inside from the outside of the shape.
DistanceFieldStyle
 Inheritedtype : Class
[read-only] The actual class of this style.
MeshStyle
 InheritedvertexFormat : VertexDataFormat
[read-only] The format used to store the vertices.
MeshStyle
Protected Properties
 PropertyDefined By
 InheritedindexData : IndexData
[read-only] Returns a reference to the index data of the assigned target (or null if there is no target).
MeshStyle
 InheritedvertexData : VertexData
[read-only] Returns a reference to the vertex data of the assigned target (or null if there is no target).
MeshStyle
Public Methods
 MethodDefined By
  
DistanceFieldStyle(softness:Number = 0.125, threshold:Number = 0.5)
Creates a new distance field style.
DistanceFieldStyle
 Inherited
addEventListener(type:String, listener:Function):void
[override]
MeshStyle
 Inherited
batchIndexData(targetStyle:MeshStyle, targetIndexID:int = 0, offset:int = 0, indexID:int = 0, numIndices:int = -1):void
Copies the index data of the style's current target to the target of another style.
MeshStyle
 Inherited
batchVertexData(targetStyle:MeshStyle, targetVertexID:int = 0, matrix:Matrix = null, vertexID:int = 0, numVertices:int = -1):void
Copies the vertex data of the style's current target to the target of another style.
MeshStyle
 Inherited
canBatchWith(meshStyle:MeshStyle):Boolean
Indicates if the current instance can be batched with the given style.
MeshStyle
 Inherited
clone():MeshStyle
Creates a clone of this instance.
MeshStyle
 Inherited
copyFrom(meshStyle:MeshStyle):void
Copies all properties of the given style to the current instance (or a subset, if the classes don't match).
MeshStyle
 Inherited
createEffect():MeshEffect
Creates the effect that does the actual, low-level rendering.
MeshStyle
 Inherited
dispatchEvent(event:Event):void
Dispatches an event to all objects that have registered listeners for its type.
EventDispatcher
 Inherited
dispatchEventWith(type:String, bubbles:Boolean = false, data:Object = null):void
Dispatches an event with the given parameters to all objects that have registered listeners for the given type.
EventDispatcher
 Inherited
getTexCoords(vertexID:int, out:Point = null):Point
Returns the texture coordinates of the vertex at the specified index.
MeshStyle
 Inherited
getVertexAlpha(vertexID:int):Number
Returns the alpha value of the vertex at the specified index.
MeshStyle
 Inherited
getVertexColor(vertexID:int):uint
Returns the RGB color of the vertex at the specified index.
MeshStyle
 Inherited
getVertexPosition(vertexID:int, out:Point = null):Point
The position of the vertex at the specified index, in the mesh's local coordinate system.
MeshStyle
 Inherited
hasEventListener(type:String, listener:Function = null):Boolean
If called with one argument, figures out if there are any listeners registered for the given event type.
EventDispatcher
 Inherited
removeEventListener(type:String, listener:Function):void
[override]
MeshStyle
 Inherited
removeEventListeners(type:String = null):void
Removes all event listeners with a certain type, or all of them if type is null.
EventDispatcher
 Inherited
setTexCoords(vertexID:int, u:Number, v:Number):void
Sets the texture coordinates of the vertex at the specified index to the given values.
MeshStyle
  
setupBasic():void
Restores basic render mode, i.e.
DistanceFieldStyle
  
setupDropShadow(blur:Number = 0.2, offsetX:Number = 2, offsetY:Number = 2, color:uint = 0x0, alpha:Number = 0.5):void
Sets up shadow rendering mode.
DistanceFieldStyle
  
setupGlow(blur:Number = 0.2, color:uint = 0xffff00, alpha:Number = 0.5):void
Sets up glow rendering mode.
DistanceFieldStyle
  
setupOutline(width:Number = 0.25, color:uint = 0x0, alpha:Number = 1.0):void
Sets up outline rendering mode.
DistanceFieldStyle
 Inherited
setVertexAlpha(vertexID:int, alpha:Number):void
Sets the alpha value of the vertex at the specified index to a certain value.
MeshStyle
 Inherited
setVertexColor(vertexID:int, color:uint):void
Sets the RGB color of the vertex at the specified index to a certain value.
MeshStyle
 Inherited
setVertexPosition(vertexID:int, x:Number, y:Number):void
MeshStyle
 Inherited
updateEffect(effect:MeshEffect, state:RenderState):void
Updates the settings of the given effect to match the current style.
MeshStyle
Protected Methods
 MethodDefined By
 Inherited
onTargetAssigned(target:Mesh):void
Called when assigning a target mesh.
MeshStyle
 Inherited
setIndexDataChanged():void
Call this method when the index data changed.
MeshStyle
 Inherited
setRequiresRedraw():void
Call this method if the target needs to be redrawn.
MeshStyle
 Inherited
setVertexDataChanged():void
Call this method when the vertex data changed.
MeshStyle
Events
 Event Summary Defined By
 Inherited
enterFrame
Dispatched every frame on styles assigned to display objects connected to the stage.MeshStyle
Public Constants
 ConstantDefined By
  MODE_BASIC : String = basic
[static] Basic distance field rendering, without additional effects.
DistanceFieldStyle
  MODE_GLOW : String = glow
[static] Adds a smooth glow effect around the shape.
DistanceFieldStyle
  MODE_OUTLINE : String = outline
[static] Adds an outline around the edge of the shape.
DistanceFieldStyle
  MODE_SHADOW : String = shadow
[static] Adds a drop shadow behind the shape.
DistanceFieldStyle
  VERTEX_FORMAT : VertexDataFormat
[static] The vertex format expected by this style.
DistanceFieldStyle
Property Detail
alphaproperty
alpha:Number

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

The default value is 1.0.


Implementation
    public function get alpha():Number
    public function set alpha(value:Number):void
modeproperty 
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.

The default value is basic.


Implementation
    public function get mode():String
    public function set mode(value:String):void
multiChannelproperty 
multiChannel:Boolean

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

The default value is false.


Implementation
    public function get multiChannel():Boolean
    public function set multiChannel(value:Boolean):void
outerAlphaEndproperty 
outerAlphaEnd:Number

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


Implementation
    public function get outerAlphaEnd():Number
    public function set outerAlphaEnd(value:Number):void
outerAlphaStartproperty 
outerAlphaStart:Number

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


Implementation
    public function get outerAlphaStart():Number
    public function set outerAlphaStart(value:Number):void
outerColorproperty 
outerColor:uint

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


Implementation
    public function get outerColor():uint
    public function set outerColor(value:uint):void
outerThresholdproperty 
outerThreshold:Number

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


Implementation
    public function get outerThreshold():Number
    public function set outerThreshold(value:Number):void
shadowOffsetXproperty 
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.


Implementation
    public function get shadowOffsetX():Number
    public function set shadowOffsetX(value:Number):void
shadowOffsetYproperty 
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.


Implementation
    public function get shadowOffsetY():Number
    public function set shadowOffsetY(value:Number):void
softnessproperty 
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).

The default value is 0.125.


Implementation
    public function get softness():Number
    public function set softness(value:Number):void
thresholdproperty 
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'.

The default value is 0.5.


Implementation
    public function get threshold():Number
    public function set threshold(value:Number):void
Constructor Detail
DistanceFieldStyle()Constructor
public function DistanceFieldStyle(softness:Number = 0.125, threshold:Number = 0.5)

Creates a new distance field style.

Parameters
softness:Number (default = 0.125) — 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.
 
threshold:Number (default = 0.5) — the value separating the inside from the outside of the shape. Range: 0 - 1.
Method Detail
setupBasic()method
public function setupBasic():void

Restores basic render mode, i.e. smooth rendering of the shape.

setupDropShadow()method 
public function setupDropShadow(blur:Number = 0.2, offsetX:Number = 2, offsetY:Number = 2, color:uint = 0x0, alpha:Number = 0.5):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

blur:Number (default = 0.2)
 
offsetX:Number (default = 2)
 
offsetY:Number (default = 2)
 
color:uint (default = 0x0)
 
alpha:Number (default = 0.5)

setupGlow()method 
public function setupGlow(blur:Number = 0.2, color:uint = 0xffff00, alpha:Number = 0.5):void

Sets up glow rendering mode. The 'blur' determines the threshold where the blur ends; 'blur + threshold' must not exceed '1.0'.

Parameters

blur:Number (default = 0.2)
 
color:uint (default = 0xffff00)
 
alpha:Number (default = 0.5)

setupOutline()method 
public function setupOutline(width:Number = 0.25, color:uint = 0x0, alpha:Number = 1.0):void

Sets up outline rendering mode. The 'width' determines the threshold where the outline ends; 'width + threshold' must not exceed '1.0'.

Parameters

width:Number (default = 0.25)
 
color:uint (default = 0x0)
 
alpha:Number (default = 1.0)

Constant Detail
MODE_BASICConstant
public static const MODE_BASIC:String = basic

Basic distance field rendering, without additional effects.

MODE_GLOWConstant 
public static const MODE_GLOW:String = glow

Adds a smooth glow effect around the shape.

MODE_OUTLINEConstant 
public static const MODE_OUTLINE:String = outline

Adds an outline around the edge of the shape.

MODE_SHADOWConstant 
public static const MODE_SHADOW:String = shadow

Adds a drop shadow behind the shape.

VERTEX_FORMATConstant 
public static const VERTEX_FORMAT:VertexDataFormat

The vertex format expected by this style.





Mon Jul 26 2021, 10:58 AM +02:00