Packagestarling.rendering
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're writing your own rendering code (e.g. if you create custom display objects).

To render objects with Stage3D, you have to organize vertices and indices in so-called vertex- and index-buffers. Vertex buffers store the coordinates of the vertices that make up an object; index buffers reference those vertices to determine which vertices spawn up triangles. Those buffers reside in graphics memory and can be accessed very efficiently by the GPU.

Before you can move data into the buffers, you have to set it up in conventional memory — that is, in a Vector or a ByteArray. Since it's quite cumbersome to manually create and manipulate those data structures, the IndexData and VertexData classes provide a simple way to do just that. The data is stored sequentially (one vertex or index after the other) so that it can easily be uploaded to a buffer.

Vertex Format

The VertexData class requires a custom format string on initialization, or an instance of the VertexDataFormat class. Here is an example:

      vertexData = new VertexData("position:float2, color:bytes4");
      vertexData.setPoint(0, "position", 320, 480);
      vertexData.setColor(0, "color", 0xff00ff);

This instance is set up with two attributes: "position" and "color". The keywords after the colons depict the format and size of the data that each property uses; in this case, we store two floats for the position (for the x- and y-coordinates) and four bytes for the color. Please refer to the VertexDataFormat documentation for details.

The attribute names are then used to read and write data to the respective positions inside a vertex. Furthermore, they come in handy when copying data from one VertexData instance to another: attributes with equal name and data format may be transferred between different VertexData objects, even when they contain different sets of attributes or have a different layout.

Colors

Always use the format bytes4 for color data. The color access methods expect that format, since it's the most efficient way to store color data. Furthermore, you should always include the string "color" (or "Color") in the name of color data; that way, it will be recognized as such and will always have its value pre-filled with pure white at full opacity.

Premultiplied Alpha

Per default, color values are stored with premultiplied alpha values, which means that the rgb values were multiplied with the alpha values before saving them. You can change this behavior with the premultipliedAlpha property.

Beware: with premultiplied alpha, the alpha value always affects the resolution of the RGB channels. A small alpha value results in a lower accuracy of the other channels, and if the alpha value reaches zero, the color information is lost altogether.

Tinting

Some low-end hardware is very sensitive when it comes to fragment shader complexity. Thus, Starling optimizes shaders for non-tinted meshes. The VertexData class keeps track of its tinted-state, at least at a basic level: whenever you change color or alpha value of a vertex to something different than white (0xffffff) with full alpha (1.0), the tinted property is enabled.

However, that value is not entirely accurate: when you restore the color of just a range of vertices, or copy just a subset of vertices to another instance, the property might wrongfully indicate a tinted mesh. If that's the case, you can either call updateTinted() or assign a custom value to the tinted-property.

See also

VertexDataFormat
IndexData


Public Properties
 PropertyDefined By
  format : VertexDataFormat
The format that describes the attributes of each vertex.
VertexData
  formatString : String
[read-only] The format string that describes the attributes of each vertex.
VertexData
  numVertices : int
The total number of vertices.
VertexData
  premultipliedAlpha : Boolean
Indicates if color attributes should be stored premultiplied with the alpha value.
VertexData
  rawData : ByteArray
[read-only] The raw vertex data; not a copy!
VertexData
  size : int
[read-only] The size (in bytes) of the raw vertex data.
VertexData
  sizeIn32Bits : int
[read-only] The size (in 32 bit units) of the raw vertex data.
VertexData
  tinted : Boolean
Indicates if the mesh contains any vertices that are not white or not fully opaque.
VertexData
  vertexSize : int
[read-only] The size (in bytes) of each vertex.
VertexData
  vertexSizeIn32Bits : int
[read-only] The size (in 32 bit units) of each vertex.
VertexData
Public Methods
 MethodDefined By
  
VertexData(format:* = null, initialCapacity:int = 32)
Creates an empty VertexData object with the given format and initial capacity.
VertexData
  
clear():void
Explicitly frees up the memory used by the ByteArray.
VertexData
  
Creates a duplicate of the vertex data object.
VertexData
  
colorize(attrName:String = color, color:uint = 0xffffff, alpha:Number = 1.0, vertexID:int = 0, numVertices:int = -1):void
Writes the given RGB and alpha values to the specified vertices.
VertexData
  
copyAttributeTo(target:VertexData, targetVertexID:int, attrName:String, matrix:Matrix = null, vertexID:int = 0, numVertices:int = -1):void
Copies a specific attribute of all contained vertices (or a range of them, defined by 'vertexID' and 'numVertices') to another VertexData instance.
VertexData
  
copyTo(target:VertexData, targetVertexID:int = 0, matrix:Matrix = null, 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 target index.
VertexData
  
createVertexBuffer(upload:Boolean = false, bufferUsage:String = staticDraw):VertexBuffer3D
Creates a vertex buffer object with the right size to fit the complete data.
VertexData
  
getAlpha(vertexID:int, attrName:String = color):Number
Reads the alpha value from the specified vertex and attribute.
VertexData
  
getBounds(attrName:String = position, matrix:Matrix = null, vertexID:int = 0, numVertices:int = -1, out:Rectangle = null):Rectangle
Calculates the bounds of the 2D vertex positions identified by the given name.
VertexData
  
getBoundsProjected(attrName:String, matrix:Matrix3D, camPos:Vector3D, vertexID:int = 0, numVertices:int = -1, out:Rectangle = null):Rectangle
Calculates the bounds of the 2D vertex positions identified by the given name, projected into the XY-plane of a certain 3D space as they appear from the given camera position.
VertexData
  
getColor(vertexID:int, attrName:String = color):uint
Reads an RGB color from the specified vertex and attribute (no alpha).
VertexData
  
getFloat(vertexID:int, attrName:String):Number
Reads a float value from the specified vertex and attribute.
VertexData
  
getFormat(attrName:String):String
Returns the format of a certain vertex attribute, identified by its name.
VertexData
  
getOffset(attrName:String):int
Returns the offset (in bytes) of an attribute within a vertex.
VertexData
  
getOffsetIn32Bits(attrName:String):int
Returns the offset (in 32 bit units) of an attribute within a vertex.
VertexData
  
getPoint(vertexID:int, attrName:String, out:Point = null):Point
Reads a Point from the specified vertex and attribute.
VertexData
  
getPoint3D(vertexID:int, attrName:String, out:Vector3D = null):Vector3D
Reads a Vector3D from the specified vertex and attribute.
VertexData
  
getPoint4D(vertexID:int, attrName:String, out:Vector3D = null):Vector3D
Reads a Vector3D from the specified vertex and attribute, including the fourth coordinate ('w').
VertexData
  
getSize(attrName:String):int
Returns the size of a certain vertex attribute in bytes.
VertexData
  
getSizeIn32Bits(attrName:String):int
Returns the size of a certain vertex attribute in 32 bit units.
VertexData
  
hasAttribute(attrName:String):Boolean
Indicates if the VertexData instances contains an attribute with the specified name.
VertexData
  
scaleAlphas(attrName:String, factor:Number, vertexID:int = 0, numVertices:int = -1):void
Multiplies the alpha values of subsequent vertices by a certain factor.
VertexData
  
setAlpha(vertexID:int, attrName:String, alpha:Number):void
Writes the given alpha value to the specified vertex and attribute (range 0-1).
VertexData
  
setColor(vertexID:int, attrName:String, color:uint):void
Writes the RGB color to the specified vertex and attribute (alpha is not changed).
VertexData
  
setFloat(vertexID:int, attrName:String, value:Number):void
Writes a float value to the specified vertex and attribute.
VertexData
  
setPoint(vertexID:int, attrName:String, x:Number, y:Number):void
Writes the given coordinates to the specified vertex and attribute.
VertexData
  
setPoint3D(vertexID:int, attrName:String, x:Number, y:Number, z:Number):void
Writes the given coordinates to the specified vertex and attribute.
VertexData
  
setPoint4D(vertexID:int, attrName:String, x:Number, y:Number, z:Number, w:Number = 1.0):void
Writes the given coordinates to the specified vertex and attribute.
VertexData
  
setPremultipliedAlpha(value:Boolean, updateData:Boolean):void
Changes the way alpha and color values are stored.
VertexData
  
toString():String
Returns a string representation of the VertexData object, describing both its format and size.
VertexData
  
transformPoints(attrName:String, matrix:Matrix, vertexID:int = 0, numVertices:int = -1):void
Transforms the 2D positions of subsequent vertices by multiplication with a transformation matrix.
VertexData
  
translatePoints(attrName:String, deltaX:Number, deltaY:Number, vertexID:int = 0, numVertices:int = -1):void
Translates the 2D positions of subsequent vertices by a certain offset.
VertexData
  
trim():void
Optimizes the ByteArray so that it has exactly the required capacity, without wasting any memory.
VertexData
  
updateTinted(attrName:String = color):Boolean
Updates the tinted property from the actual color data.
VertexData
  
uploadToVertexBuffer(buffer:VertexBuffer3D, vertexID:int = 0, numVertices:int = -1):void
Uploads the complete data (or a section of it) to the given vertex buffer.
VertexData
Property Detail
formatproperty
format:VertexDataFormat

The format that describes the attributes of each vertex. When you assign a different format, the raw data will be converted accordingly, i.e. attributes with the same name will still point to the same data. New properties will be filled up with zeros (except for colors, which will be initialized with an alpha value of 1.0). As a side-effect, the instance will also be trimmed.


Implementation
    public function get format():VertexDataFormat
    public function set format(value:VertexDataFormat):void
formatStringproperty 
formatString:String  [read-only]

The format string that describes the attributes of each vertex.


Implementation
    public function get formatString():String
numVerticesproperty 
numVertices:int

The total number of vertices. If you make the object bigger, it will be filled up with 1.0 for all alpha values and zero for everything else.


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

Indicates if color attributes should be stored premultiplied with the alpha value. Changing this value does not modify any existing color data. If you want that, use the setPremultipliedAlpha method instead.

The default value is true.


Implementation
    public function get premultipliedAlpha():Boolean
    public function set premultipliedAlpha(value:Boolean):void
rawDataproperty 
rawData:ByteArray  [read-only]

The raw vertex data; not a copy!


Implementation
    public function get rawData():ByteArray
sizeproperty 
size:int  [read-only]

The size (in bytes) of the raw vertex data.


Implementation
    public function get size():int
sizeIn32Bitsproperty 
sizeIn32Bits:int  [read-only]

The size (in 32 bit units) of the raw vertex data.


Implementation
    public function get sizeIn32Bits():int
tintedproperty 
tinted:Boolean

Indicates if the mesh contains any vertices that are not white or not fully opaque. If false (and the value wasn't modified manually), the result is 100% accurate; true represents just an educated guess. To be entirely sure, you may call updateTinted().


Implementation
    public function get tinted():Boolean
    public function set tinted(value:Boolean):void
vertexSizeproperty 
vertexSize:int  [read-only]

The size (in bytes) of each vertex.


Implementation
    public function get vertexSize():int
vertexSizeIn32Bitsproperty 
vertexSizeIn32Bits:int  [read-only]

The size (in 32 bit units) of each vertex.


Implementation
    public function get vertexSizeIn32Bits():int
Constructor Detail
VertexData()Constructor
public function VertexData(format:* = null, initialCapacity:int = 32)

Creates an empty VertexData object with the given format and initial capacity.

Parameters
format:* (default = null) — Either a VertexDataFormat instance or a String that describes the data format. Refer to the VertexDataFormat class for more information. If you don't pass a format, the default MeshStyle.VERTEX_FORMAT will be used.
 
initialCapacity:int (default = 32) — The initial capacity affects just the way the internal ByteArray is allocated, not the numIndices value, which will always be zero when the constructor returns. The reason for this behavior is the peculiar way in which ByteArrays organize their memory:

The first time you set the length of a ByteArray, it will adhere to that: a ByteArray with length 20 will take up 20 bytes (plus some overhead). When you change it to a smaller length, it will stick to the original value, e.g. with a length of 10 it will still take up 20 bytes. However, now comes the weird part: change it to anything above the original length, and it will allocate 4096 bytes!

Thus, be sure to always make a generous educated guess, depending on the planned usage of your VertexData instances.

Method Detail
clear()method
public function clear():void

Explicitly frees up the memory used by the ByteArray.

clone()method 
public function clone():VertexData

Creates a duplicate of the vertex data object.

Returns
VertexData
colorize()method 
public function colorize(attrName:String = color, color:uint = 0xffffff, alpha:Number = 1.0, vertexID:int = 0, numVertices:int = -1):void

Writes the given RGB and alpha values to the specified vertices.

Parameters

attrName:String (default = color)
 
color:uint (default = 0xffffff)
 
alpha:Number (default = 1.0)
 
vertexID:int (default = 0)
 
numVertices:int (default = -1)

copyAttributeTo()method 
public function copyAttributeTo(target:VertexData, targetVertexID:int, attrName:String, matrix:Matrix = null, vertexID:int = 0, numVertices:int = -1):void

Copies a specific attribute of all contained vertices (or a range of them, defined by 'vertexID' and 'numVertices') to another VertexData instance. Beware that both name and format of the attribute must be identical in source and target. If the target is not big enough, it will be resized to fit all the new vertices.

If you pass a non-null matrix, the specified attribute will be transformed by that matrix before storing it in the target object. It must consist of two float values.

Parameters

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

copyTo()method 
public function copyTo(target:VertexData, targetVertexID:int = 0, matrix:Matrix = null, 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 target index. If the target is not big enough, it will be resized to fit all the new vertices.

If you pass a non-null matrix, the 2D position of each vertex will be transformed by that matrix before storing it in the target object. (The position being either an attribute with the name "position" or, if such an attribute is not found, the first attribute of each vertex. It must consist of two float values containing the x- and y-coordinates of the vertex.)

Source and target do not need to have the exact same format. Only properties that exist in the target will be copied; others will be ignored. If a property with the same name but a different format exists in the target, an exception will be raised. Beware, though, that the copy-operation becomes much more expensive when the formats differ.

Parameters

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

createVertexBuffer()method 
public function createVertexBuffer(upload:Boolean = false, bufferUsage:String = staticDraw):VertexBuffer3D

Creates a vertex buffer object with the right size to fit the complete data. Optionally, the current data is uploaded right away.

Parameters

upload:Boolean (default = false)
 
bufferUsage:String (default = staticDraw)

Returns
VertexBuffer3D
getAlpha()method 
public function getAlpha(vertexID:int, attrName:String = color):Number

Reads the alpha value from the specified vertex and attribute.

Parameters

vertexID:int
 
attrName:String (default = color)

Returns
Number
getBounds()method 
public function getBounds(attrName:String = position, matrix:Matrix = null, vertexID:int = 0, numVertices:int = -1, out:Rectangle = null):Rectangle

Calculates the bounds of the 2D vertex positions identified by the given name. The positions may optionally be transformed by a matrix before calculating the bounds. If you pass an 'out' Rectangle, 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

attrName:String (default = position)
 
matrix:Matrix (default = null)
 
vertexID:int (default = 0)
 
numVertices:int (default = -1)
 
out:Rectangle (default = null)

Returns
Rectangle
getBoundsProjected()method 
public function getBoundsProjected(attrName:String, matrix:Matrix3D, camPos:Vector3D, vertexID:int = 0, numVertices:int = -1, out:Rectangle = null):Rectangle

Calculates the bounds of the 2D vertex positions identified by the given name, projected into the XY-plane of a certain 3D space as they appear from the given camera position. Note that 'camPos' is expected in the target coordinate system (the same that the XY-plane lies in).

If you pass an 'out' Rectangle, 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

attrName:String
 
matrix:Matrix3D
 
camPos:Vector3D
 
vertexID:int (default = 0)
 
numVertices:int (default = -1)
 
out:Rectangle (default = null)

Returns
Rectangle
getColor()method 
public function getColor(vertexID:int, attrName:String = color):uint

Reads an RGB color from the specified vertex and attribute (no alpha).

Parameters

vertexID:int
 
attrName:String (default = color)

Returns
uint
getFloat()method 
public function getFloat(vertexID:int, attrName:String):Number

Reads a float value from the specified vertex and attribute.

Parameters

vertexID:int
 
attrName:String

Returns
Number
getFormat()method 
public function getFormat(attrName:String):String

Returns the format of a certain vertex attribute, identified by its name. Typical values: float1, float2, float3, float4, bytes4.

Parameters

attrName:String

Returns
String
getOffset()method 
public function getOffset(attrName:String):int

Returns the offset (in bytes) of an attribute within a vertex.

Parameters

attrName:String

Returns
int
getOffsetIn32Bits()method 
public function getOffsetIn32Bits(attrName:String):int

Returns the offset (in 32 bit units) of an attribute within a vertex.

Parameters

attrName:String

Returns
int
getPoint()method 
public function getPoint(vertexID:int, attrName:String, out:Point = null):Point

Reads a Point from the specified vertex and attribute.

Parameters

vertexID:int
 
attrName:String
 
out:Point (default = null)

Returns
Point
getPoint3D()method 
public function getPoint3D(vertexID:int, attrName:String, out:Vector3D = null):Vector3D

Reads a Vector3D from the specified vertex and attribute. The 'w' property of the Vector3D is ignored.

Parameters

vertexID:int
 
attrName:String
 
out:Vector3D (default = null)

Returns
Vector3D
getPoint4D()method 
public function getPoint4D(vertexID:int, attrName:String, out:Vector3D = null):Vector3D

Reads a Vector3D from the specified vertex and attribute, including the fourth coordinate ('w').

Parameters

vertexID:int
 
attrName:String
 
out:Vector3D (default = null)

Returns
Vector3D
getSize()method 
public function getSize(attrName:String):int

Returns the size of a certain vertex attribute in bytes.

Parameters

attrName:String

Returns
int
getSizeIn32Bits()method 
public function getSizeIn32Bits(attrName:String):int

Returns the size of a certain vertex attribute in 32 bit units.

Parameters

attrName:String

Returns
int
hasAttribute()method 
public function hasAttribute(attrName:String):Boolean

Indicates if the VertexData instances contains an attribute with the specified name.

Parameters

attrName:String

Returns
Boolean
scaleAlphas()method 
public function scaleAlphas(attrName:String, factor:Number, vertexID:int = 0, numVertices:int = -1):void

Multiplies the alpha values of subsequent vertices by a certain factor.

Parameters

attrName:String
 
factor:Number
 
vertexID:int (default = 0)
 
numVertices:int (default = -1)

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

Writes the given alpha value to the specified vertex and attribute (range 0-1).

Parameters

vertexID:int
 
attrName:String
 
alpha:Number

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

Writes the RGB color to the specified vertex and attribute (alpha is not changed).

Parameters

vertexID:int
 
attrName:String
 
color:uint

setFloat()method 
public function setFloat(vertexID:int, attrName:String, value:Number):void

Writes a float value to the specified vertex and attribute.

Parameters

vertexID:int
 
attrName:String
 
value:Number

setPoint()method 
public function setPoint(vertexID:int, attrName:String, x:Number, y:Number):void

Writes the given coordinates to the specified vertex and attribute.

Parameters

vertexID:int
 
attrName:String
 
x:Number
 
y:Number

setPoint3D()method 
public function setPoint3D(vertexID:int, attrName:String, x:Number, y:Number, z:Number):void

Writes the given coordinates to the specified vertex and attribute.

Parameters

vertexID:int
 
attrName:String
 
x:Number
 
y:Number
 
z:Number

setPoint4D()method 
public function setPoint4D(vertexID:int, attrName:String, x:Number, y:Number, z:Number, w:Number = 1.0):void

Writes the given coordinates to the specified vertex and attribute.

Parameters

vertexID:int
 
attrName:String
 
x:Number
 
y:Number
 
z:Number
 
w:Number (default = 1.0)

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

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

Parameters

value:Boolean
 
updateData:Boolean

toString()method 
public function toString():String

Returns a string representation of the VertexData object, describing both its format and size.

Returns
String
transformPoints()method 
public function transformPoints(attrName:String, matrix:Matrix, vertexID:int = 0, numVertices:int = -1):void

Transforms the 2D positions of subsequent vertices by multiplication with a transformation matrix.

Parameters

attrName:String
 
matrix:Matrix
 
vertexID:int (default = 0)
 
numVertices:int (default = -1)

translatePoints()method 
public function translatePoints(attrName:String, deltaX:Number, deltaY:Number, vertexID:int = 0, numVertices:int = -1):void

Translates the 2D positions of subsequent vertices by a certain offset.

Parameters

attrName:String
 
deltaX:Number
 
deltaY:Number
 
vertexID:int (default = 0)
 
numVertices:int (default = -1)

trim()method 
public function trim():void

Optimizes the ByteArray so that it has exactly the required capacity, without wasting any memory. If your VertexData object grows larger than the initial capacity you passed to the constructor, call this method to avoid the 4k memory problem.

updateTinted()method 
public function updateTinted(attrName:String = color):Boolean

Updates the tinted property from the actual color data. This might make sense after copying part of a tinted VertexData instance to another, since not each color value is checked in the process. An instance is tinted if any vertices have a non-white color or are not fully opaque.

Parameters

attrName:String (default = color)

Returns
Boolean
uploadToVertexBuffer()method 
public function uploadToVertexBuffer(buffer:VertexBuffer3D, vertexID:int = 0, numVertices:int = -1):void

Uploads the complete data (or a section of it) to the given vertex buffer.

Parameters

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