Packagestarling.utils
Classpublic class VertexData
InheritanceVertexData Inheritance Object

The VertexData class manages a raw list of vertex information, allowing direct upload to Stage3D vertex buffers. You only have to work with this class if you create display objects with a custom render function. If you don't plan to do that, you can safely ignore it.

To render objects with Stage3D, you have to organize vertex data in so-called vertex buffers. Those buffers reside in graphics memory and can be accessed very efficiently by the GPU. Before you can move data into vertex buffers, you have to set it up in conventional memory - that is, in a Vector object. The vector contains all vertex information (the coordinates, color, and texture coordinates) - one vertex after the other.

To simplify creating and working with such a bulky list, the VertexData class was created. It contains methods to specify and modify vertex data. The raw Vector managed by the class can then easily be uploaded to a vertex buffer.

Premultiplied Alpha

The color values of the "BitmapData" object contain premultiplied alpha values, which means that the rgb values were multiplied with the alpha value before saving them. Since textures are created from bitmap data, they contain the values in the same style. On rendering, it makes a difference in which way the alpha value is saved; for that reason, the VertexData class mimics this behavior. You can choose how the alpha values should be handled via the premultipliedAlpha property.



Public Properties
 PropertyDefined By
  numVertices : int
The total number of vertices.
VertexData
  premultipliedAlpha : Boolean
Indicates if the rgb values are stored premultiplied with the alpha value.
VertexData
  rawData : Vector.<Number>
[read-only] The raw vertex data; not a copy!
VertexData
  tinted : Boolean
[read-only] Indicates if any vertices have a non-white color or are not fully opaque.
VertexData
Public Methods
 MethodDefined By
  
VertexData(numVertices:int, premultipliedAlpha:Boolean = false)
Create a new VertexData object with a specified number of vertices.
VertexData
  
append(data:VertexData):void
Appends the vertices from another VertexData object.
VertexData
  
clone(vertexID:int = 0, numVertices:int = -1):VertexData
Creates a duplicate of either the complete vertex data object, or of a subset.
VertexData
  
copyTo(targetData:VertexData, targetVertexID:int = 0, vertexID:int = 0, numVertices:int = -1):void
Copies the vertex data (or a range of it, defined by 'vertexID' and 'numVertices') of this instance to another vertex data object, starting at a certain index.
VertexData
  
copyTransformedTo(targetData:VertexData, targetVertexID:int = 0, matrix:Matrix = null, vertexID:int = 0, numVertices:int = -1):void
Transforms the vertex position of this instance by a certain matrix and copies the result to another VertexData instance.
VertexData
  
getAlpha(vertexID:int):Number
Returns the alpha value of a vertex in the range 0-1.
VertexData
  
getBounds(transformationMatrix:Matrix = null, vertexID:int = 0, numVertices:int = -1, resultRect:Rectangle = null):Rectangle
Calculates the bounds of the vertices, which are optionally transformed by a matrix.
VertexData
  
getBoundsProjected(transformationMatrix:Matrix3D, camPos:Vector3D, vertexID:int = 0, numVertices:int = -1, resultRect:Rectangle = null):Rectangle
Calculates the bounds of the vertices, projected into the XY-plane of a certain 3D space as they appear from a certain camera position.
VertexData
  
getColor(vertexID:int):uint
Returns the RGB color of a vertex (no alpha).
VertexData
  
getPosition(vertexID:int, position:Point):void
Returns the position of a vertex.
VertexData
  
getTexCoords(vertexID:int, texCoords:Point):void
Returns the texture coordinates of a vertex in the range 0-1.
VertexData
  
scaleAlpha(vertexID:int, factor:Number, numVertices:int = 1):void
Multiplies the alpha value of subsequent vertices with a certain factor.
VertexData
  
setAlpha(vertexID:int, alpha:Number):void
Updates the alpha value of a vertex (range 0-1).
VertexData
  
setColor(vertexID:int, color:uint):void
Updates the RGB color values of a vertex (alpha is not changed).
VertexData
  
setColorAndAlpha(vertexID:int, color:uint, alpha:Number):void
Updates the RGB color and alpha value of a vertex in one step.
VertexData
  
setPosition(vertexID:int, x:Number, y:Number):void
Updates the position values of a vertex.
VertexData
  
setPremultipliedAlpha(value:Boolean, updateData:Boolean = true):void
Changes the way alpha and color values are stored.
VertexData
  
setTexCoords(vertexID:int, u:Number, v:Number):void
Updates the texture coordinates of a vertex (range 0-1).
VertexData
  
setUniformAlpha(alpha:Number):void
Sets all vertices of the object to the same alpha values.
VertexData
  
setUniformColor(color:uint):void
Sets all vertices of the object to the same color values.
VertexData
  
toString():String
Creates a string that contains the values of all included vertices.
VertexData
  
transformVertex(vertexID:int, matrix:Matrix, numVertices:int = 1):void
Transforms the position of subsequent vertices by multiplication with a transformation matrix.
VertexData
  
translateVertex(vertexID:int, deltaX:Number, deltaY:Number):void
Translate the position of a vertex by a certain offset.
VertexData
Public Constants
 ConstantDefined By
  COLOR_OFFSET : int = 2
[static] The offset of color data (r, g, b, a) within a vertex.
VertexData
  ELEMENTS_PER_VERTEX : int = 8
[static] The total number of elements (Numbers) stored per vertex.
VertexData
  POSITION_OFFSET : int = 0
[static] The offset of position data (x, y) within a vertex.
VertexData
  TEXCOORD_OFFSET : int = 6
[static] The offset of texture coordinates (u, v) within a vertex.
VertexData
Property Detail
numVerticesproperty
numVertices:int

The total number of vertices.


Implementation
    public function get numVertices():int
    public function set numVertices(value:int):void
premultipliedAlphaproperty 
premultipliedAlpha:Boolean

Indicates if the rgb values are stored premultiplied with the alpha value. If you change this value, the color data is updated accordingly. If you don't want that, use the 'setPremultipliedAlpha' method instead.


Implementation
    public function get premultipliedAlpha():Boolean
    public function set premultipliedAlpha(value:Boolean):void
rawDataproperty 
rawData:Vector.<Number>  [read-only]

The raw vertex data; not a copy!


Implementation
    public function get rawData():Vector.<Number>
tintedproperty 
tinted:Boolean  [read-only]

Indicates if any vertices have a non-white color or are not fully opaque.


Implementation
    public function get tinted():Boolean
Constructor Detail
VertexData()Constructor
public function VertexData(numVertices:int, premultipliedAlpha:Boolean = false)

Create a new VertexData object with a specified number of vertices.

Parameters
numVertices:int
 
premultipliedAlpha:Boolean (default = false)
Method Detail
append()method
public function append(data:VertexData):void

Appends the vertices from another VertexData object.

Parameters

data:VertexData

clone()method 
public function clone(vertexID:int = 0, numVertices:int = -1):VertexData

Creates a duplicate of either the complete vertex data object, or of a subset. To clone all vertices, set 'numVertices' to '-1'.

Parameters

vertexID:int (default = 0)
 
numVertices:int (default = -1)

Returns
VertexData
copyTo()method 
public function copyTo(targetData:VertexData, targetVertexID:int = 0, vertexID:int = 0, numVertices:int = -1):void

Copies the vertex data (or a range of it, defined by 'vertexID' and 'numVertices') of this instance to another vertex data object, starting at a certain index.

Parameters

targetData:VertexData
 
targetVertexID:int (default = 0)
 
vertexID:int (default = 0)
 
numVertices:int (default = -1)

copyTransformedTo()method 
public function copyTransformedTo(targetData:VertexData, targetVertexID:int = 0, matrix:Matrix = null, vertexID:int = 0, numVertices:int = -1):void

Transforms the vertex position of this instance by a certain matrix and copies the result to another VertexData instance. Limit the operation to a range of vertices via the 'vertexID' and 'numVertices' parameters.

Parameters

targetData:VertexData
 
targetVertexID:int (default = 0)
 
matrix:Matrix (default = null)
 
vertexID:int (default = 0)
 
numVertices:int (default = -1)

getAlpha()method 
public function getAlpha(vertexID:int):Number

Returns the alpha value of a vertex in the range 0-1.

Parameters

vertexID:int

Returns
Number
getBounds()method 
public function getBounds(transformationMatrix:Matrix = null, vertexID:int = 0, numVertices:int = -1, resultRect:Rectangle = null):Rectangle

Calculates the bounds of the vertices, which are optionally transformed by a matrix. If you pass a 'resultRect', the result will be stored in this rectangle instead of creating a new object. To use all vertices for the calculation, set 'numVertices' to '-1'.

Parameters

transformationMatrix:Matrix (default = null)
 
vertexID:int (default = 0)
 
numVertices:int (default = -1)
 
resultRect:Rectangle (default = null)

Returns
Rectangle
getBoundsProjected()method 
public function getBoundsProjected(transformationMatrix:Matrix3D, camPos:Vector3D, vertexID:int = 0, numVertices:int = -1, resultRect:Rectangle = null):Rectangle

Calculates the bounds of the vertices, projected into the XY-plane of a certain 3D space as they appear from a certain camera position. Note that 'camPos' is expected in the target coordinate system (the same that the XY-plane lies in). If you pass a 'resultRectangle', the result will be stored in this rectangle instead of creating a new object. To use all vertices for the calculation, set 'numVertices' to '-1'.

Parameters

transformationMatrix:Matrix3D
 
camPos:Vector3D
 
vertexID:int (default = 0)
 
numVertices:int (default = -1)
 
resultRect:Rectangle (default = null)

Returns
Rectangle
getColor()method 
public function getColor(vertexID:int):uint

Returns the RGB color of a vertex (no alpha).

Parameters

vertexID:int

Returns
uint
getPosition()method 
public function getPosition(vertexID:int, position:Point):void

Returns the position of a vertex.

Parameters

vertexID:int
 
position:Point

getTexCoords()method 
public function getTexCoords(vertexID:int, texCoords:Point):void

Returns the texture coordinates of a vertex in the range 0-1.

Parameters

vertexID:int
 
texCoords:Point

scaleAlpha()method 
public function scaleAlpha(vertexID:int, factor:Number, numVertices:int = 1):void

Multiplies the alpha value of subsequent vertices with a certain factor.

Parameters

vertexID:int
 
factor:Number
 
numVertices:int (default = 1)

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

Updates the alpha value of a vertex (range 0-1).

Parameters

vertexID:int
 
alpha:Number

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

Updates the RGB color values of a vertex (alpha is not changed).

Parameters

vertexID:int
 
color:uint

setColorAndAlpha()method 
public function setColorAndAlpha(vertexID:int, color:uint, alpha:Number):void

Updates the RGB color and alpha value of a vertex in one step.

Parameters

vertexID:int
 
color:uint
 
alpha:Number

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

Updates the position values of a vertex.

Parameters

vertexID:int
 
x:Number
 
y:Number

setPremultipliedAlpha()method 
public function setPremultipliedAlpha(value:Boolean, updateData:Boolean = true):void

Changes the way alpha and color values are stored. Optionally updates all exisiting vertices.

Parameters

value:Boolean
 
updateData:Boolean (default = true)

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

Updates the texture coordinates of a vertex (range 0-1).

Parameters

vertexID:int
 
u:Number
 
v:Number

setUniformAlpha()method 
public function setUniformAlpha(alpha:Number):void

Sets all vertices of the object to the same alpha values.

Parameters

alpha:Number

setUniformColor()method 
public function setUniformColor(color:uint):void

Sets all vertices of the object to the same color values.

Parameters

color:uint

toString()method 
public function toString():String

Creates a string that contains the values of all included vertices.

Returns
String
transformVertex()method 
public function transformVertex(vertexID:int, matrix:Matrix, numVertices:int = 1):void

Transforms the position of subsequent vertices by multiplication with a transformation matrix.

Parameters

vertexID:int
 
matrix:Matrix
 
numVertices:int (default = 1)

translateVertex()method 
public function translateVertex(vertexID:int, deltaX:Number, deltaY:Number):void

Translate the position of a vertex by a certain offset.

Parameters

vertexID:int
 
deltaX:Number
 
deltaY:Number

Constant Detail
COLOR_OFFSETConstant
public static const COLOR_OFFSET:int = 2

The offset of color data (r, g, b, a) within a vertex.

ELEMENTS_PER_VERTEXConstant 
public static const ELEMENTS_PER_VERTEX:int = 8

The total number of elements (Numbers) stored per vertex.

POSITION_OFFSETConstant 
public static const POSITION_OFFSET:int = 0

The offset of position data (x, y) within a vertex.

TEXCOORD_OFFSETConstant 
public static const TEXCOORD_OFFSET:int = 6

The offset of texture coordinates (u, v) within a vertex.