GODPAPER | All Packages | All Classes | Index | Frames No Frames |
VertexData

Package | starling.utils
Class | public class VertexData
Inheritance | VertexData 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

| Property | Defined 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

| Method | Defined 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
|  | 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

| Constant | Defined 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

numVertices | property

`numVertices:int`

The total number of vertices.

Implementation
`public function get numVertices():int`
`public function set numVertices(value:int):void`

premultipliedAlpha | property |

`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`

rawData | property |

`rawData:Vector.<Number>` [read-only]

The raw vertex data; not a copy!

Implementation
`public function get rawData():Vector.<Number>`

tinted | property |

`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`

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_OFFSET | Constant

`public static const COLOR_OFFSET:int = 2`

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

ELEMENTS_PER_VERTEX | Constant |

`public static const ELEMENTS_PER_VERTEX:int = 8`

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

POSITION_OFFSET | Constant |

`public static const POSITION_OFFSET:int = 0`

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

TEXCOORD_OFFSET | Constant |

`public static const TEXCOORD_OFFSET:int = 6`

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

Thu Jan 16 2014, 01:11 PM +08:00