Options
All
  • Public
  • Public/Protected
  • All
Menu

Class IndexData

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:

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 VertexData

Hierarchy

  • IndexData

Index

Constructors

constructor

  • new IndexData(initialCapacity?: number): IndexData
  • 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.

    Parameters

    • Optional initialCapacity: number

    Returns IndexData

Properties

indexSizeInBytes

indexSizeInBytes: number

The number of bytes required for each index value.

numIndices

numIndices: number

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.

numQuads

numQuads: number

The number of quads that can be spawned up with the contained indices. (In other words: the number of triangles divided by two.)

numTriangles

numTriangles: number

The number of triangles that can be spawned up with the contained indices. (In other words: the number of indices divided by three.)

rawData

rawData: ByteArray

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.

useQuadLayout

useQuadLayout: boolean

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

Methods

addQuad

  • addQuad(a: number, b: number, c: number, d: number): void
  • 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).

    Parameters

    • a: number
    • b: number
    • c: number
    • d: number

    Returns void

addTriangle

  • addTriangle(a: number, b: number, c: number): void
  • Appends three indices representing a triangle. Reference the vertices clockwise, as this defines the front side of the triangle.

    Parameters

    • a: number
    • b: number
    • c: number

    Returns void

clear

  • clear(): void
  • Explicitly frees up the memory used by the ByteArray, thus removing all indices. Quad layout will be restored (until adding data violating that layout).

    Returns void

clone

copyTo

  • copyTo(target: IndexData, targetIndexID?: number, offset?: number, indexID?: number, numIndices?: number): 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. 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
    • Optional targetIndexID: number
    • Optional offset: number
    • Optional indexID: number
    • Optional numIndices: number

    Returns void

createIndexBuffer

  • createIndexBuffer(upload?: boolean, bufferUsage?: string): IndexBuffer3D
  • Creates an index buffer object with the right size to fit the complete data. Optionally, the current data is uploaded right away.

    Parameters

    • Optional upload: boolean
    • Optional bufferUsage: string

    Returns IndexBuffer3D

getIndex

  • getIndex(indexID: number): number

Protected get_indexSizeInBytes

  • get_indexSizeInBytes(): number

Protected get_numIndices

  • get_numIndices(): number

Protected get_numQuads

  • get_numQuads(): number

Protected get_numTriangles

  • get_numTriangles(): number

Protected get_rawData

  • get_rawData(): ByteArray

Protected get_useQuadLayout

  • get_useQuadLayout(): boolean

offsetIndices

  • offsetIndices(offset: number, indexID?: number, numIndices?: number): void

setIndex

  • setIndex(indexID: number, index: number): void

Protected set_numIndices

  • set_numIndices(value: number): number

Protected set_numQuads

  • set_numQuads(value: number): number

Protected set_numTriangles

  • set_numTriangles(value: number): number

Protected set_useQuadLayout

  • set_useQuadLayout(value: boolean): boolean

toString

  • toString(): string

toVector

  • toVector(out?: Vector<number>): Vector<number>
  • Creates a vector containing all indices. If you pass an existing vector to the method, its contents will be overwritten.

    Parameters

    • Optional out: Vector<number>

    Returns Vector<number>

trim

  • trim(): void
  • 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.

    Returns void

uploadToIndexBuffer

  • uploadToIndexBuffer(buffer: IndexBuffer3D, indexID?: number, numIndices?: number): void
  • Uploads the complete data (or a section of it) to the given index buffer.

    Parameters

    • buffer: IndexBuffer3D
    • Optional indexID: number
    • Optional numIndices: number

    Returns void

Generated using TypeDoc