.. index::
    single: IndexBuffer

.. highlight:: javascript

.. _indexbuffer:

----------------------
The IndexBuffer Object
----------------------

An IndexBuffer object is an optimal read-only container for index data.

Constructor
===========

IndexBuffers are created using :ref:`GraphicsDevice.createIndexBuffer <graphicsdevice_createindexbuffer>`.

Methods
=======

.. index::
    pair: IndexBuffer; setData

`setData`
---------
**Summary**

Set the data by passing in an array of numbers.

Create the IndexBuffer as dynamic if you are planning to update the index data at runtime.

**Syntax** ::

    var indexData = [0, 1, 2];
    var offset = 0;
    var count = indexData.length;
    indexBuffer.setData(indexData, offset, count);

``indexData``
    An array of numbers.

``offset`` (Optional)
    Offset in indicies from the beginning of the buffer. Optional, assumed to be 0 if omitted.

``count`` (Optional)
    The number of elements to write, normally indexData.length. Optional, assumed to be IndexBuffer.numIndices if omitted.

.. index::
    pair: IndexBuffer; map

`map`
-----

**Summary**

Requests write access to an IndexBuffer.

Create the IndexBuffer as dynamic if you are planning to update the index data at runtime.

**Syntax** ::

    var writer = indexBuffer.map(offset, count);
    if (writer)
    {
        for (var n = 0; n < (numIndices / 3); n += 1)
        {
            writer(n, (n + 1), (n + 2));
        }

        indexBuffer.unmap(writer);
    }

Returns an index writer.

``offset`` (Optional)
    Offset in indicies from the beginning of the buffer. Optional, assumed to be 0 if omitted.

``count`` (Optional)
    The number of elements to be written. Optional, assumed to be IndexBuffer.numIndices if omitted.

The writer can be called once for each mapped index.
It can also be called with multiple values in order to write multiple indices with just one call,
this is more optimal than a call per index but be careful not to write more indices than the ones the IndexBuffer was created with or
the writer will fail.

The entire contents of the buffer must be updated.

.. index::
    pair: IndexBuffer; unmap

`unmap`
-------

**Summary**

Communicate to the IndexBuffer that write access is no longer required.

**Syntax** ::

    var writer = indexBuffer.map();
    if (writer)
    {
        // Do something with the writer here

        indexBuffer.unmap(writer);
    }

``writer``
    The index writer returned by a previous call to ``map``.

This method **must** be called if ``map`` returns a valid writer.



Properties
==========

.. index::
    pair: IndexBuffer; numIndices

`numIndices`
-------------

**Summary**

Number of indices stored on the IndexBuffer.

**Syntax** ::

    var numIndices = indexBuffer.numIndices;

.. note:: Read Only

.. index::
    pair: IndexBuffer; format

`format`
--------

**Summary**

String with the format name of the index data.

**Syntax** ::

    var indexFormat = indexBuffer.format;

.. note:: Read Only


.. index::
    pair: IndexBuffer; dynamic

`dynamic`
---------

**Summary**

True if the IndexBuffer was created as dynamic and hence can be modified at runtime, false otherwise.

**Syntax** ::

    var isDynamic = indexBuffer.dynamic;

.. note:: Read Only