| Package | starling.rendering |
| Class | public class VertexData |
| Inheritance | VertexData  Object |
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 FormatThe 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.
ColorsAlways 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.
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.
TintingSome 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
| Property | Defined 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 | ||
| Method | Defined 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 | ||
| format | property |
format:VertexDataFormatThe 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.
public function get format():VertexDataFormat public function set format(value:VertexDataFormat):void| formatString | property |
formatString:String [read-only] The format string that describes the attributes of each vertex.
public function get formatString():String| numVertices | property |
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.
public function get numVertices():int public function set numVertices(value:int):void| premultipliedAlpha | property |
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.
public function get premultipliedAlpha():Boolean public function set premultipliedAlpha(value:Boolean):void| rawData | property |
rawData:ByteArray [read-only] The raw vertex data; not a copy!
public function get rawData():ByteArray| size | property |
size:int [read-only] The size (in bytes) of the raw vertex data.
public function get size():int| sizeIn32Bits | property |
sizeIn32Bits:int [read-only] The size (in 32 bit units) of the raw vertex data.
public function get sizeIn32Bits():int| tinted | property |
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().
public function get tinted():Boolean public function set tinted(value:Boolean):void| vertexSize | property |
vertexSize:int [read-only] The size (in bytes) of each vertex.
public function get vertexSize():int| vertexSizeIn32Bits | property |
vertexSizeIn32Bits:int [read-only] The size (in 32 bit units) of each vertex.
public function get vertexSizeIn32Bits():int| VertexData | () | Constructor |
public function VertexData(format:* = null, initialCapacity:int = 32)Creates an empty VertexData object with the given format and initial capacity.
Parametersformat:* (default = null)MeshStyle.VERTEX_FORMAT will be used.
| |
initialCapacity:int (default = 32)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. |
| clear | () | method |
public function clear():voidExplicitly frees up the memory used by the ByteArray.
| clone | () | method |
| colorize | () | method |
public function colorize(attrName:String = color, color:uint = 0xffffff, alpha:Number = 1.0, vertexID:int = 0, numVertices:int = -1):voidWrites 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):voidCopies 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):voidCopies 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):VertexBuffer3DCreates 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) |
VertexBuffer3D |
| getAlpha | () | method |
public function getAlpha(vertexID:int, attrName:String = color):NumberReads the alpha value from the specified vertex and attribute.
Parameters
vertexID:int | |
attrName:String (default = color) |
Number |
| getBounds | () | method |
public function getBounds(attrName:String = position, matrix:Matrix = null, vertexID:int = 0, numVertices:int = -1, out:Rectangle = null):RectangleCalculates 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) |
Rectangle |
| getBoundsProjected | () | method |
public function getBoundsProjected(attrName:String, matrix:Matrix3D, camPos:Vector3D, vertexID:int = 0, numVertices:int = -1, out:Rectangle = null):RectangleCalculates 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) |
Rectangle |
| getColor | () | method |
public function getColor(vertexID:int, attrName:String = color):uintReads an RGB color from the specified vertex and attribute (no alpha).
Parameters
vertexID:int | |
attrName:String (default = color) |
uint |
| getFloat | () | method |
public function getFloat(vertexID:int, attrName:String):NumberReads a float value from the specified vertex and attribute.
Parameters
vertexID:int | |
attrName:String |
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 |
String |
| getOffset | () | method |
public function getOffset(attrName:String):intReturns the offset (in bytes) of an attribute within a vertex.
Parameters
attrName:String |
int |
| getOffsetIn32Bits | () | method |
public function getOffsetIn32Bits(attrName:String):intReturns the offset (in 32 bit units) of an attribute within a vertex.
Parameters
attrName:String |
int |
| getPoint | () | method |
public function getPoint(vertexID:int, attrName:String, out:Point = null):PointReads a Point from the specified vertex and attribute.
Parameters
vertexID:int | |
attrName:String | |
out:Point (default = null) |
Point |
| getPoint3D | () | method |
public function getPoint3D(vertexID:int, attrName:String, out:Vector3D = null):Vector3DReads 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) |
Vector3D |
| getPoint4D | () | method |
public function getPoint4D(vertexID:int, attrName:String, out:Vector3D = null):Vector3DReads a Vector3D from the specified vertex and attribute, including the fourth coordinate ('w').
Parameters
vertexID:int | |
attrName:String | |
out:Vector3D (default = null) |
Vector3D |
| getSize | () | method |
public function getSize(attrName:String):intReturns the size of a certain vertex attribute in bytes.
Parameters
attrName:String |
int |
| getSizeIn32Bits | () | method |
public function getSizeIn32Bits(attrName:String):intReturns the size of a certain vertex attribute in 32 bit units.
Parameters
attrName:String |
int |
| hasAttribute | () | method |
public function hasAttribute(attrName:String):BooleanIndicates if the VertexData instances contains an attribute with the specified name.
Parameters
attrName:String |
Boolean |
| scaleAlphas | () | method |
public function scaleAlphas(attrName:String, factor:Number, vertexID:int = 0, numVertices:int = -1):voidMultiplies 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):voidWrites 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):voidWrites 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):voidWrites 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):voidWrites 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):voidWrites 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):voidWrites 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):voidChanges the way alpha and color values are stored. Optionally updates all existing vertices.
Parameters
value:Boolean | |
updateData:Boolean |
| toString | () | method |
public function toString():StringReturns a string representation of the VertexData object, describing both its format and size.
ReturnsString |
| transformPoints | () | method |
public function transformPoints(attrName:String, matrix:Matrix, vertexID:int = 0, numVertices:int = -1):voidTransforms 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):voidTranslates 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():voidOptimizes 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) |
Boolean |
| uploadToVertexBuffer | () | method |
public function uploadToVertexBuffer(buffer:VertexBuffer3D, vertexID:int = 0, numVertices:int = -1):voidUploads the complete data (or a section of it) to the given vertex buffer.
Parameters
buffer:VertexBuffer3D | |
vertexID:int (default = 0) | |
numVertices:int (default = -1) |