Packagestarling.styles
Classpublic class MeshStyle
InheritanceMeshStyle Inheritance EventDispatcher Inheritance Object

MeshStyles provide a means to completely modify the way a mesh is rendered. The base class provides Starling's standard mesh rendering functionality: colored and (optionally) textured meshes. Subclasses may add support for additional features like color transformations, normal mapping, etc.

Using styles

First, create an instance of the desired style. Configure the style by updating its properties, then assign it to the mesh. Here is an example that uses a fictitious ColorStyle:

      var image:Image = new Image(heroTexture);
      var colorStyle:ColorStyle = new ColorStyle();
      colorStyle.redOffset = 0.5;
      colorStyle.redMultiplier = 2.0;
      image.style = colorStyle;

Beware:

Creating your own styles

To create custom rendering code in Starling, you need to extend two classes: MeshStyle and MeshEffect. While the effect class contains the actual AGAL rendering code, the style provides the API that other developers will interact with.

Subclasses of MeshStyle will add specific properties that configure the style's outcome, like the redOffset and redMultiplier properties in the sample above. Here's how to properly create such a class:

If the style requires a custom vertex format, you must also:

When that's done, you can turn to the implementation of your MeshEffect; the createEffect-override will return an instance of this class. Directly before rendering begins, Starling will then call updateEffect to set it up.

See also

MeshEffect
VertexDataFormat
starling.display.Mesh


Public Properties
 PropertyDefined By
  color : uint
Changes the color of all vertices to the same value.
MeshStyle
  target : Mesh
[read-only] The target the style is currently assigned to.
MeshStyle
  texture : Texture
The texture that is mapped to the mesh (or null, if there is none).
MeshStyle
  textureRepeat : Boolean
Indicates if pixels at the edges will be repeated or clamped.
MeshStyle
  textureSmoothing : String
The smoothing filter that is used for the texture.
MeshStyle
  type : Class
[read-only] The actual class of this style.
MeshStyle
  vertexFormat : VertexDataFormat
[read-only] The format used to store the vertices.
MeshStyle
Protected Properties
 PropertyDefined By
  indexData : IndexData
[read-only] Returns a reference to the index data of the assigned target (or null if there is no target).
MeshStyle
  vertexData : 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
  
Creates a new MeshStyle instance.
MeshStyle
  
addEventListener(type:String, listener:Function):void
[override]
MeshStyle
  
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
  
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
  
canBatchWith(meshStyle:MeshStyle):Boolean
Indicates if the current instance can be batched with the given style.
MeshStyle
  
Creates a clone of this instance.
MeshStyle
  
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
  
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
  
getTexCoords(vertexID:int, out:Point = null):Point
Returns the texture coordinates of the vertex at the specified index.
MeshStyle
  
getVertexAlpha(vertexID:int):Number
Returns the alpha value of the vertex at the specified index.
MeshStyle
  
getVertexColor(vertexID:int):uint
Returns the RGB color of the vertex at the specified index.
MeshStyle
  
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
  
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
  
setTexCoords(vertexID:int, u:Number, v:Number):void
Sets the texture coordinates of the vertex at the specified index to the given values.
MeshStyle
  
setVertexAlpha(vertexID:int, alpha:Number):void
Sets the alpha value of the vertex at the specified index to a certain value.
MeshStyle
  
setVertexColor(vertexID:int, color:uint):void
Sets the RGB color of the vertex at the specified index to a certain value.
MeshStyle
  
setVertexPosition(vertexID:int, x:Number, y:Number):void
MeshStyle
  
updateEffect(effect:MeshEffect, state:RenderState):void
Updates the settings of the given effect to match the current style.
MeshStyle
Protected Methods
 MethodDefined By
  
onTargetAssigned(target:Mesh):void
Called when assigning a target mesh.
MeshStyle
  
Call this method if the target needs to be redrawn.
MeshStyle
Events
 Event Summary Defined By
  Dispatched every frame on styles assigned to display objects connected to the stage.MeshStyle
Public Constants
 ConstantDefined By
  VERTEX_FORMAT : VertexDataFormat
[static] The vertex format expected by this style (the same as found in the MeshEffect-class).
MeshStyle
Property Detail
colorproperty
color:uint

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


Implementation
    public function get color():uint
    public function set color(value:uint):void
indexDataproperty 
indexData:IndexData  [read-only]

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.


Implementation
    protected function get indexData():IndexData
targetproperty 
target:Mesh  [read-only]

The target the style is currently assigned to.


Implementation
    public function get target():Mesh
textureproperty 
texture:Texture

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


Implementation
    public function get texture():Texture
    public function set texture(value:Texture):void
textureRepeatproperty 
textureRepeat:Boolean

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

The default value is false.


Implementation
    public function get textureRepeat():Boolean
    public function set textureRepeat(value:Boolean):void
textureSmoothingproperty 
textureSmoothing:String

The smoothing filter that is used for the texture.

The default value is bilinear.


Implementation
    public function get textureSmoothing():String
    public function set textureSmoothing(value:String):void
typeproperty 
type:Class  [read-only]

The actual class of this style.


Implementation
    public function get type():Class
vertexDataproperty 
vertexData:VertexData  [read-only]

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.


Implementation
    protected function get vertexData():VertexData
vertexFormatproperty 
vertexFormat:VertexDataFormat  [read-only]

The format used to store the vertices.


Implementation
    public function get vertexFormat():VertexDataFormat
Constructor Detail
MeshStyle()Constructor
public function MeshStyle()

Creates a new MeshStyle instance. Subclasses must provide a constructor that can be called without any arguments.

Method Detail
addEventListener()method
override public function addEventListener(type:String, listener:Function):void

Parameters

type:String
 
listener:Function

batchIndexData()method 
public function 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. 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
 
targetIndexID:int (default = 0)
 
offset:int (default = 0)
 
indexID:int (default = 0)
 
numIndices:int (default = -1)

batchVertexData()method 
public function 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. If you pass a matrix, all vertices will be transformed 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 vertex data in that process.

Parameters

targetStyle:MeshStyle
 
targetVertexID:int (default = 0)
 
matrix:Matrix (default = null)
 
vertexID:int (default = 0)
 
numVertices:int (default = -1)

canBatchWith()method 
public function canBatchWith(meshStyle:MeshStyle):Boolean

Indicates if the current instance can be batched with the given style. To be overridden by subclasses if default behavior is not sufficient. The base implementation just checks if the styles are of the same type and if the textures are compatible.

Parameters

meshStyle:MeshStyle

Returns
Boolean
clone()method 
public function clone():MeshStyle

Creates a clone of this instance. The method will work for subclasses automatically, no need to override it.

Returns
MeshStyle
copyFrom()method 
public function copyFrom(meshStyle:MeshStyle):void

Copies all properties of the given style to the current instance (or a subset, if the classes don't match). Must be overridden by all subclasses!

Parameters

meshStyle:MeshStyle

createEffect()method 
public function createEffect():MeshEffect

Creates the effect that does the actual, low-level rendering. To be overridden by subclasses!

Returns
MeshEffect
getTexCoords()method 
public function getTexCoords(vertexID:int, out:Point = null):Point

Returns the texture coordinates of the vertex at the specified index.

Parameters

vertexID:int
 
out:Point (default = null)

Returns
Point
getVertexAlpha()method 
public function getVertexAlpha(vertexID:int):Number

Returns the alpha value of the vertex at the specified index.

Parameters

vertexID:int

Returns
Number
getVertexColor()method 
public function getVertexColor(vertexID:int):uint

Returns the RGB color of the vertex at the specified index.

Parameters

vertexID:int

Returns
uint
getVertexPosition()method 
public function getVertexPosition(vertexID:int, out:Point = null):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:int
 
out:Point (default = null)

Returns
Point
onTargetAssigned()method 
protected function onTargetAssigned(target:Mesh):void

Called when assigning a target mesh. Override to plug in class-specific logic.

Parameters

target:Mesh

removeEventListener()method 
override public function removeEventListener(type:String, listener:Function):void

Parameters

type:String
 
listener:Function

setRequiresRedraw()method 
protected function setRequiresRedraw():void

Call this method if the target needs to be redrawn. The call is simply forwarded to the mesh.

setTexCoords()method 
public function setTexCoords(vertexID:int, u:Number, v:Number):void

Sets the texture coordinates of the vertex at the specified index to the given values.

Parameters

vertexID:int
 
u:Number
 
v:Number

setVertexAlpha()method 
public function setVertexAlpha(vertexID:int, alpha:Number):void

Sets the alpha value of the vertex at the specified index to a certain value.

Parameters

vertexID:int
 
alpha:Number

setVertexColor()method 
public function setVertexColor(vertexID:int, color:uint):void

Sets the RGB color of the vertex at the specified index to a certain value.

Parameters

vertexID:int
 
color:uint

setVertexPosition()method 
public function setVertexPosition(vertexID:int, x:Number, y:Number):void

Parameters

vertexID:int
 
x:Number
 
y:Number

updateEffect()method 
public function updateEffect(effect:MeshEffect, state:RenderState):void

Updates the settings of the given effect to match the current style. The given effect will always match the class returned by createEffect.

To be overridden by subclasses!

Parameters

effect:MeshEffect
 
state:RenderState

Event Detail
enterFrame Event
Event Object Type: starling.events.EnterFrameEvent

Dispatched every frame on styles assigned to display objects connected to the stage.

Constant Detail
VERTEX_FORMATConstant
public static const VERTEX_FORMAT:VertexDataFormat

The vertex format expected by this style (the same as found in the MeshEffect-class).