| Package | starling.rendering |
| Class | public class IndexData |
| Inheritance | IndexData  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 in a ByteArray (one index or vertex after the other) that can easily be uploaded to a buffer.
Basic Quad LayoutIn many cases, the indices we are working with will reference just quads, i.e. triangles composing rectangles. That means that many IndexData instances will contain similar or identical data — a great opportunity for optimization!
If an IndexData instance follows a specific layout, it will be recognized automatically and many operations can be executed much faster. In Starling, that layout is called "basic quad layout". In order to recognize this specific sequence, the indices of each quad have to use the following order:
n, n+1, n+2, n+1, n+3, n+2
The subsequent quad has to use n+4 as starting value, the next one
n+8, etc. Here is an example with 3 quads / 6 triangles:
0, 1, 2, 1, 3, 2, 4, 5, 6, 5, 7, 6, 8, 9, 10, 9, 11, 10
If you are describing quad-like meshes, make sure to always use this layout.
See also
| Property | Defined By | ||
|---|---|---|---|
| indexSizeInBytes : int [read-only] The number of bytes required for each index value. | IndexData | ||
| numIndices : int The total number of indices. | IndexData | ||
| numQuads : int The number of quads that can be spawned up with the contained indices. | IndexData | ||
| numTriangles : int The number of triangles that can be spawned up with the contained indices. | IndexData | ||
| rawData : ByteArray [read-only] The raw index data; not a copy! Beware: the referenced ByteArray may change any time. | IndexData | ||
| useQuadLayout : Boolean Indicates if all indices are following the basic quad layout. | IndexData | ||
| Method | Defined By | ||
|---|---|---|---|
IndexData(initialCapacity:int = 48) Creates an empty IndexData instance with the given capacity (in indices). | IndexData | ||
addQuad(a:uint, b:uint, c:uint, d:uint):void Appends two triangles spawning up the quad with the given indices. | IndexData | ||
addTriangle(a:uint, b:uint, c:uint):void Appends three indices representing a triangle. | IndexData | ||
clear():void Explicitly frees up the memory used by the ByteArray, thus removing all indices. | IndexData | ||
Creates a duplicate of the IndexData object. | IndexData | ||
copyTo(target:IndexData, targetIndexID:int = 0, offset:int = 0, indexID:int = 0, numIndices:int = -1):void Copies the index data (or a range of it, defined by 'indexID' and 'numIndices')
of this instance to another IndexData object, starting at a certain target index. | IndexData | ||
createIndexBuffer(upload:Boolean = false, bufferUsage:String = staticDraw):IndexBuffer3D Creates an index buffer object with the right size to fit the complete data. | IndexData | ||
getIndex(indexID:int):int Reads the index from the specified position. | IndexData | ||
offsetIndices(offset:int, indexID:int = 0, numIndices:int = -1):void Adds an offset to all indices in the specified range. | IndexData | ||
setIndex(indexID:int, index:uint):void Sets an index at the specified position. | IndexData | ||
toString():String Returns a string representation of the IndexData object,
including a comma-separated list of all indices. | IndexData | ||
toVector(out:Vector.<uint> = null):Vector.<uint> Creates a vector containing all indices. | IndexData | ||
trim():void Optimizes the ByteArray so that it has exactly the required capacity, without
wasting any memory. | IndexData | ||
uploadToIndexBuffer(buffer:IndexBuffer3D, indexID:int = 0, numIndices:int = -1):void Uploads the complete data (or a section of it) to the given index buffer. | IndexData | ||
| indexSizeInBytes | property |
indexSizeInBytes:int [read-only] The number of bytes required for each index value.
public function get indexSizeInBytes():int| numIndices | property |
numIndices:intThe total number of indices.
If this instance contains only standardized, basic quad indices, resizing will automatically fill up with appropriate quad indices. Otherwise, it will fill up with zeroes.
If you set the number of indices to zero, quad layout will be restored.
public function get numIndices():int public function set numIndices(value:int):void| numQuads | property |
numQuads:intThe number of quads that can be spawned up with the contained indices. (In other words: the number of triangles divided by two.)
public function get numQuads():int public function set numQuads(value:int):void| numTriangles | property |
numTriangles:intThe number of triangles that can be spawned up with the contained indices. (In other words: the number of indices divided by three.)
public function get numTriangles():int public function set numTriangles(value:int):void| rawData | property |
rawData:ByteArray [read-only] The raw index data; not a copy! Beware: the referenced ByteArray may change any time. Never store a reference to it, and never modify its contents manually.
public function get rawData():ByteArray| useQuadLayout | property |
useQuadLayout:BooleanIndicates if all indices are following the basic quad layout.
This property is automatically updated if an index is set to a value that violates
basic quad layout. Once the layout was violated, the instance will always stay that
way, even if you fix that violating value later. Only calling clear or
manually enabling the property will restore quad layout.
If you enable this property on an instance, all indices will immediately be replaced with indices following standard quad layout.
Please look at the class documentation for more information about that kind of layout, and why it is important.
The default value is true.
public function get useQuadLayout():Boolean public function set useQuadLayout(value:Boolean):void| IndexData | () | Constructor |
public function IndexData(initialCapacity:int = 48)Creates an empty IndexData instance with the given capacity (in indices).
ParametersinitialCapacity:int (default = 48)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 IndexData instances. |
| addQuad | () | method |
public function addQuad(a:uint, b:uint, c:uint, d:uint):voidAppends two triangles spawning up the quad with the given indices. The indices of the vertices are arranged like this:
a - b
| / |
c - d
To make sure the indices will follow the basic quad layout, make sure each
parameter increments the one before it (e.g. 0, 1, 2, 3).
Parameters
a:uint | |
b:uint | |
c:uint | |
d:uint |
| addTriangle | () | method |
public function addTriangle(a:uint, b:uint, c:uint):voidAppends three indices representing a triangle. Reference the vertices clockwise, as this defines the front side of the triangle.
Parameters
a:uint | |
b:uint | |
c:uint |
| clear | () | method |
public function clear():voidExplicitly frees up the memory used by the ByteArray, thus removing all indices. Quad layout will be restored (until adding data violating that layout).
| clone | () | method |
| copyTo | () | method |
public function copyTo(target:IndexData, targetIndexID:int = 0, offset:int = 0, indexID:int = 0, numIndices:int = -1):voidCopies the index data (or a range of it, defined by 'indexID' and 'numIndices') of this instance to another IndexData object, starting at a certain target index. If the target is not big enough, it will grow to fit all the new indices.
By passing a non-zero offset, you can raise all copied indices
by that value in the target object.
Parameters
target:IndexData | |
targetIndexID:int (default = 0) | |
offset:int (default = 0) | |
indexID:int (default = 0) | |
numIndices:int (default = -1) |
| createIndexBuffer | () | method |
public function createIndexBuffer(upload:Boolean = false, bufferUsage:String = staticDraw):IndexBuffer3DCreates an index 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) |
IndexBuffer3D |
| getIndex | () | method |
public function getIndex(indexID:int):intReads the index from the specified position.
Parameters
indexID:int |
int |
| offsetIndices | () | method |
public function offsetIndices(offset:int, indexID:int = 0, numIndices:int = -1):voidAdds an offset to all indices in the specified range.
Parameters
offset:int | |
indexID:int (default = 0) | |
numIndices:int (default = -1) |
| setIndex | () | method |
public function setIndex(indexID:int, index:uint):voidSets an index at the specified position.
Parameters
indexID:int | |
index:uint |
| toString | () | method |
public function toString():StringReturns a string representation of the IndexData object, including a comma-separated list of all indices.
ReturnsString |
| toVector | () | method |
public function toVector(out:Vector.<uint> = null):Vector.<uint>Creates a vector containing all indices. If you pass an existing vector to the method, its contents will be overwritten.
Parameters
out:Vector.<uint> (default = null) |
Vector.<uint> |
| trim | () | method |
public function trim():voidOptimizes the ByteArray so that it has exactly the required capacity, without wasting any memory. If your IndexData object grows larger than the initial capacity you passed to the constructor, call this method to avoid the 4k memory problem.
| uploadToIndexBuffer | () | method |
public function uploadToIndexBuffer(buffer:IndexBuffer3D, indexID:int = 0, numIndices:int = -1):voidUploads the complete data (or a section of it) to the given index buffer.
Parameters
buffer:IndexBuffer3D | |
indexID:int (default = 0) | |
numIndices:int (default = -1) |