.. index::
    single: VertexBuffer

.. highlight:: javascript

.. _vertexbuffer:

-----------------------
The VertexBuffer Object
-----------------------

A VertexBuffer object is an optimal read-only container for vertex data.

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

A VertexBuffer object can be constructed with :ref:`GraphicsDevice.createVertexBuffer <graphicsdevice_createvertexbuffer>`.

Methods
=======

.. _vertexbuffer_setdata:

.. index::
    pair: VertexBuffer; setData

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

Set the data by passing in an array of numbers.

Vertex data stored on the VertexBuffer, it consists of an array of numbers,
one value for each component of every attribute of all vertices.
The number of components per attribute depends on the attribute format.

Create the VertexBuffer as dynamic if you are planning to update the vertex data at runtime.

Changing or requesting the vertex data can be an expensive operation.

**Syntax** ::

    // request all the data
    var vertexData = [100.0, 200.0, 3, 1000,
                      200.0, 200.0, 4, 2000,
                      100.0, 100.0, 5, 3000,
                      200.0, 100.0, 6, 4000]

    var offset = 0;
    var count = vertexData.length / vertexBuffer.stride;
    vertexBuffer.setData(vertexData, offset, count);

``vertexData``
    An array of numbers in the same format as the `data` element passed in to :ref:`createVertexBuffer <graphicsdevice_createvertexbuffer>`.

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

``count`` (Optional)
    The number of verticies to write. Optional, assumed to be size of the buffer if omitted.


.. index::
    pair: VertexBuffer; map

.. _vertexbuffer_map:

`map`
-----

**Summary**

Requests write access to a region of the VertexBuffer.

**Syntax** ::

    var writer = vertexBuffer.map(offset, count);
    if (writer)
    {
        for (var n = 0; n < count; n += 1)
        {
            // This VertexBuffer has 3 attributes
            writer(0, 1, 2, // first attribute has 3 components
                   0, 1, 2, // second attribute has also 3 components
                   0, 1);   // third attribute has only 2
        }

        vertexBuffer.unmap(writer);
    }

``offset`` (Optional)
    The zero-based index of the first vertex to map.
    If it is not specified the whole VertexBuffer will be mapped.

``count`` (Optional)
    The number of vertices to map.
    If it is not specified all the vertices after and including ``offset`` will be mapped.

Returns a vertex writer.
The writer can be called once for each mapped vertex to replace each of the components of every attribute.


.. index::
    pair: VertexBuffer; unmap

.. _vertexbuffer_unmap:

`unmap`
-------

**Summary**

Communicate to the VertexBuffer that write access to a mapped region is no longer required.

**Syntax** ::

    var writer = vertexBuffer.map(firstVertexToMap, numVerticesToMap);
    if (writer)
    {
        // Do something with the writer here

        vertexBuffer.unmap(writer);
    }

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

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

Properties
==========

.. index::
    pair: VertexBuffer; numVertices

`numVertices`
-------------

**Summary**

Number of vertices stored on the VertexBuffer.

**Syntax** ::

    var numVertices = vertexBuffer.numVertices;

.. note:: Read Only


.. index::
    pair: VertexBuffer; numAttributes

`numAttributes`
---------------

**Summary**

Number of attributes per vertex.

**Syntax** ::

    var numAttributes = vertexBuffer.numAttributes;

.. note:: Read Only


.. index::
    pair: VertexBuffer; attributes

`attributes`
------------

**Summary**

Array of strings with the format names of each vertex attribute.

**Syntax** ::

    var vertexAttributesArray = vertexBuffer.attributes;

.. note:: Read Only


.. index::
    pair: VertexBuffer; stride

`stride`
--------

**Summary**

The number of total components per vertex.
Each vertex attribute can have up to 4 components depending on the attribute format.

**Syntax** ::

    var vertexBufferStride = vertexBuffer.stride;

.. note:: Read Only


.. index::
    pair: VertexBuffer; dynamic

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

**Summary**

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

**Syntax** ::

    var isDynamic = vertexBuffer.dynamic;

.. note:: Read Only