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: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.
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 ) — 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. |
clear | () | method |
public function clear():void
Explicitly 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):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 )
|
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 )
|
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 )
|
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 )
|
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 )
|
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 |
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):int
Returns the offset (in bytes) of an attribute within a vertex.
Parameters
attrName:String |
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 |
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 )
|
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 )
|
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 )
|
Vector3D |
getSize | () | method |
public function getSize(attrName:String):int
Returns the size of a certain vertex attribute in bytes.
Parameters
attrName:String |
int |
getSizeIn32Bits | () | method |
public function getSizeIn32Bits(attrName:String):int
Returns the size of a certain vertex attribute in 32 bit units.
Parameters
attrName:String |
int |
hasAttribute | () | method |
public function hasAttribute(attrName:String):Boolean
Indicates 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):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.
ReturnsString |
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 )
|
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 )
|