Creates an empty IndexData instance with the given capacity (in indices).
@param initialCapacity
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 IndexData instances.
The number of bytes required for each index value.
The 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.
The number of quads that can be spawned up with the contained indices. (In other words: the number of triangles divided by two.)
The number of triangles that can be spawned up with the contained indices. (In other words: the number of indices divided by three.)
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.
Indicates 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.
@default true
Appends 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
).
Appends three indices representing a triangle. Reference the vertices clockwise, as this defines the front side of the triangle.
Explicitly frees up the memory used by the ByteArray, thus removing all indices. Quad layout will be restored (until adding data violating that layout).
Creates a duplicate of the IndexData object.
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. 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.
Creates an index buffer object with the right size to fit the complete data. Optionally, the current data is uploaded right away.
Reads the index from the specified position.
Adds an offset to all indices in the specified range.
Sets an index at the specified position.
Returns a string representation of the IndexData object, including a comma-separated list of all indices.
Creates a vector containing all indices. If you pass an existing vector to the method, its contents will be overwritten.
Optimizes 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.
Uploads the complete data (or a section of it) to the given index buffer.
Generated using TypeDoc
The IndexData class manages a raw list of vertex indices, allowing direct upload to Stage3D index 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 in a ByteArray (one index or vertex after the other) that can easily be uploaded to a buffer.
Basic Quad Layout
In 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:
The subsequent quad has to use
n+4
as starting value, the next onen+8
, etc. Here is an example with 3 quads / 6 triangles:If you are describing quad-like meshes, make sure to always use this layout.
@see VertexData