VertexBuffer (jMonkeyEngine3)

java.lang.Object
- com.jme3.util.NativeObject
- - com.jme3.scene.VertexBuffer

All Implemented Interfaces:

Savable, java.lang.Cloneable
```
public class VertexBuffer
extends NativeObject
implements Savable, java.lang.Cloneable
```
A VertexBuffer contains a particular type of geometry data used by Meshes. Every VertexBuffer set on a Mesh is sent as an attribute to the vertex shader to be processed.
Several terms are used throughout the javadoc for this class, explanation:
- Element - A single element is the largest individual object inside a VertexBuffer. E.g. if the VertexBuffer is used to store 3D position data, then an element will be a single 3D vector.
- Component - A component represents the parts inside an element. For a 3D vector, a single component is one of the dimensions, X, Y or Z.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`VertexBuffer.Format` Specifies format of the data stored in the buffer.
`static class`	`VertexBuffer.Type` Type of buffer.
`static class`	`VertexBuffer.Usage` The usage of the VertexBuffer, specifies how often the buffer is used.

Field Summary

Fields
Modifier and Type	Field and Description
`protected VertexBuffer.Type`	`bufType`
`protected int`	`components`
`protected int`	`componentsLength` derived from components * format.getComponentSize()
`protected java.nio.Buffer`	`data`
`protected boolean`	`dataSizeChanged`
`protected VertexBuffer.Format`	`format`
`protected int`	`instanceSpan`
`protected int`	`lastLimit`
`protected boolean`	`normalized`
`protected int`	`offset`
`protected int`	`stride`
`protected VertexBuffer.Usage`	`usage`

Fields inherited from class com.jme3.util.NativeObject
handleRef, id, INVALID_ID, objectManager, OBJTYPE_AUDIOBUFFER, OBJTYPE_AUDIOSTREAM, OBJTYPE_BO, OBJTYPE_FILTER, OBJTYPE_FRAMEBUFFER, OBJTYPE_SHADER, OBJTYPE_SHADERSOURCE, OBJTYPE_TEXTURE, OBJTYPE_VERTEXBUFFER, updateNeeded

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`VertexBuffer()` Serialization only.
`protected`	`VertexBuffer(int id)`
	`VertexBuffer(VertexBuffer.Type type)` Creates an empty, uninitialized buffer.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`clearUpdateNeeded()` Internal use only.
`VertexBuffer`	`clone()` Creates a deep clone of the `VertexBuffer`.
`VertexBuffer`	`clone(VertexBuffer.Type overrideType)` Creates a deep clone of this VertexBuffer but overrides the `VertexBuffer.Type`.
`void`	`compact(int numElements)` Reduces the capacity of the buffer to the given amount of elements, any elements at the end of the buffer are truncated as necessary.
`void`	`convertToHalf()` Converts single floating-point data to `half` floating-point data.
`void`	`copyElement(int inIndex, VertexBuffer outVb, int outIndex)` Copies a single element of data from this `VertexBuffer` to the given output VertexBuffer.
`void`	`copyElements(int inIndex, VertexBuffer outVb, int outIndex, int len)` Copies a sequence of elements of data from this `VertexBuffer` to the given output VertexBuffer.
`static java.nio.Buffer`	`createBuffer(VertexBuffer.Format format, int components, int numElements)` Creates a `Buffer` that satisfies the given type and size requirements of the parameters.
`NativeObject`	`createDestructableClone()` Creates a shallow clone of this GL Object.
`protected void`	`deleteNativeBuffers()` Deletes any associated native `buffers`.
`void`	`deleteObject(java.lang.Object rendererObject)` Deletes the GL object from the GPU when it is no longer used.
`int`	`getBaseInstanceCount()` Returns the number of 'instances' in this VertexBuffer.
`VertexBuffer.Type`	`getBufferType()`
`java.nio.Buffer`	`getData()` Returns the raw internal data buffer used by this VertexBuffer.
`java.nio.Buffer`	`getDataReadOnly()` Returns a safe read-only version of this VertexBuffer's data.
`java.lang.Object`	`getElementComponent(int elementIndex, int componentIndex)` Get the component inside an element.
`VertexBuffer.Format`	`getFormat()`
`int`	`getInstanceSpan()`
`int`	`getNumComponents()`
`int`	`getNumElements()`
`int`	`getOffset()`
`int`	`getStride()`
`long`	`getUniqueId()` Returns a unique ID for this NativeObject.
`VertexBuffer.Usage`	`getUsage()`
`boolean`	`hasDataSizeChanged()` Returns true if the data size of the VertexBuffer has changed.
`boolean`	`invariant()`
`boolean`	`isInstanced()`
`boolean`	`isNormalized()`
`void`	`read(JmeImporter im)`
`void`	`resetObject()` Called when the GL context is restarted to reset all IDs.
`void`	`setElementComponent(int elementIndex, int componentIndex, java.lang.Object val)` Modify a component inside an element.
`void`	`setInstanced(boolean instanced)` Sets the instanceSpan to 1 or 0 depending on the value of instanced and the existing value of instanceSpan.
`void`	`setInstanceSpan(int i)` Sets how this vertex buffer matches with rendered instances where 0 means no instancing at all, ie: all elements are per vertex.
`void`	`setNormalized(boolean normalized)`
`void`	`setOffset(int offset)`
`void`	`setStride(int stride)` Set the stride (in bytes) for the data.
`void`	`setupData(VertexBuffer.Usage usage, int components, VertexBuffer.Format format, java.nio.Buffer data)` Called to initialize the data in the `VertexBuffer`.
`void`	`setUsage(VertexBuffer.Usage usage)`
`java.lang.String`	`toString()`
`void`	`updateData(java.nio.Buffer data)` Called to update the data in the buffer with new data.
`void`	`write(JmeExporter ex)`

Methods inherited from class com.jme3.util.NativeObject
dispose, getId, getWeakRef, isUpdateNeeded, setId, setUpdateNeeded

Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - offset
```
protected int offset
```
  - lastLimit
```
protected int lastLimit
```
  - stride
```
protected int stride
```
  - components
```
protected int components
```
  - componentsLength
```
protected transient int componentsLength
```
    derived from components * format.getComponentSize()
  - data
```
protected java.nio.Buffer data
```
  - usage
```
protected VertexBuffer.Usage usage
```
  - bufType
```
protected VertexBuffer.Type bufType
```
  - format
```
protected VertexBuffer.Format format
```
  - normalized
```
protected boolean normalized
```
  - instanceSpan
```
protected int instanceSpan
```
  - dataSizeChanged
```
protected transient boolean dataSizeChanged
```
- Constructor Detail
  - VertexBuffer
```
public VertexBuffer(VertexBuffer.Type type)
```
    Creates an empty, uninitialized buffer. Must call setupData() to initialize.
    
    Parameters:
    
    type - the type of VertexBuffer, such as Position or Binormal
  - VertexBuffer
```
protected VertexBuffer()
```
    Serialization only. Do not use.
  - VertexBuffer
```
protected VertexBuffer(int id)
```
- Method Detail
  - invariant
```
public boolean invariant()
```
  - getOffset
```
public int getOffset()
```
    Returns:
    
    The offset after which the data is sent to the GPU.
    
    See Also:
    
    setOffset(int)
  - setOffset
```
public void setOffset(int offset)
```
    Parameters:
    
    offset - Specify the offset (in bytes) from the start of the buffer after which the data is sent to the GPU.
  - getStride
```
public int getStride()
```
    Returns:
    
    The stride (in bytes) for the data.
    
    See Also:
    
    setStride(int)
  - setStride
```
public void setStride(int stride)
```
    Set the stride (in bytes) for the data.
    If the data is packed in the buffer, then stride is 0, if there's other data that is between the current component and the next component in the buffer, then this specifies the size in bytes of that additional data.
    
    Parameters:
    
    stride - the stride (in bytes) for the data
  - getData
```
public java.nio.Buffer getData()
```
    Returns the raw internal data buffer used by this VertexBuffer. This buffer is not safe to call from multiple threads since buffers have their own internal position state that cannot be shared. Call getData().duplicate(), getData().asReadOnlyBuffer(), or the more convenient getDataReadOnly() if the buffer may be accessed from multiple threads.
    
    Returns:
    
    A native buffer, in the specified format.
  - getDataReadOnly
```
public java.nio.Buffer getDataReadOnly()
```
    Returns a safe read-only version of this VertexBuffer's data. The contents of the buffer will reflect whatever changes are made on other threads (eventually) but these should not be used in that way. This method provides a read-only buffer that is safe to _read_ from a separate thread since it has its own book-keeping state (position, limit, etc.)
    
    Returns:
    
    A rewound native buffer in the specified format that is safe to read from a separate thread from other readers.
  - getUsage
```
public VertexBuffer.Usage getUsage()
```
    Returns:
    
    The usage of this buffer. See VertexBuffer.Usage for more information.
  - setUsage
```
public void setUsage(VertexBuffer.Usage usage)
```
    Parameters:
    
    usage - The usage of this buffer. See VertexBuffer.Usage for more information.
  - setNormalized
```
public void setNormalized(boolean normalized)
```
    Parameters:
    
    normalized - Set to true if integer components should be converted from their maximal range into the range 0.0 - 1.0 when converted to a floating-point value for the shader. E.g. if the VertexBuffer.Format is VertexBuffer.Format.UnsignedInt, then the components will be converted to the range 0.0 - 1.0 by dividing every integer by 2^32.
  - isNormalized
```
public boolean isNormalized()
```
    Returns:
    
    True if integer components should be converted to the range 0-1.
    
    See Also:
    
    setNormalized(boolean)
  - setInstanced
```
public void setInstanced(boolean instanced)
```
    Sets the instanceSpan to 1 or 0 depending on the value of instanced and the existing value of instanceSpan.
    
    Parameters:
    
    instanced - true for instanced, false for not instanced
  - isInstanced
```
public boolean isInstanced()
```
    Returns:
    
    true if buffer contains per-instance data, otherwise false
  - setInstanceSpan
```
public void setInstanceSpan(int i)
```
    Sets how this vertex buffer matches with rendered instances where 0 means no instancing at all, ie: all elements are per vertex. If set to 1 then each element goes with one instance. If set to 2 then each element goes with two instances and so on.
    
    Parameters:
    
    i - the desired number of instances per element
  - getInstanceSpan
```
public int getInstanceSpan()
```
  - getBufferType
```
public VertexBuffer.Type getBufferType()
```
    Returns:
    
    The type of information that this buffer has.
  - getFormat
```
public VertexBuffer.Format getFormat()
```
    Returns:
    
    The format, or data type of the data.
  - getNumComponents
```
public int getNumComponents()
```
    Returns:
    
    The number of components of the given format per element.
  - getNumElements
```
public int getNumElements()
```
    Returns:
    
    The total number of data elements in the data buffer.
  - getBaseInstanceCount
```
public int getBaseInstanceCount()
```
    Returns the number of 'instances' in this VertexBuffer. This is dependent on the current instanceSpan. When instanceSpan is 0 then 'instances' is 1. Otherwise, instances is elements * instanceSpan. It is possible to render a mesh with more instances but the instance data begins to repeat.
    
    Returns:
    
    the number of instances
  - setupData
```
public void setupData(VertexBuffer.Usage usage,
                      int components,
                      VertexBuffer.Format format,
                      java.nio.Buffer data)
```
    Called to initialize the data in the VertexBuffer. Must only be called once.
    
    Parameters:
    
    usage - The usage for the data, or how often will the data be updated per frame. See the VertexBuffer.Usage enum.
    
    components - The number of components per element.
    
    format - The format, or data-type of a single component.
    
    data - A native buffer, the format of which matches the VertexBuffer.Format argument.
  - updateData
```
public void updateData(java.nio.Buffer data)
```
    Called to update the data in the buffer with new data. Can only be called after setupData( com.jme3.scene.VertexBuffer.Usage, int, com.jme3.scene.VertexBuffer.Format, java.nio.Buffer) has been called. Note that it is fine to call this method on the data already set, e.g. vb.updateData(vb.getData()), this will just set the proper update flag indicating the data should be sent to the GPU again.
    It is allowed to specify a buffer with different capacity than the originally set buffer, HOWEVER, if you do so, you must call Mesh.updateCounts() otherwise bizarre errors can occur.
    
    Parameters:
    
    data - The data buffer to set
  - hasDataSizeChanged
```
public boolean hasDataSizeChanged()
```
    Returns true if the data size of the VertexBuffer has changed. Internal use only.
    
    Returns:
    
    true if the data size has changed
  - clearUpdateNeeded
```
public void clearUpdateNeeded()
```
    Description copied from class: NativeObject
    
    Internal use only. Indicates that the state changes were applied.
    
    Overrides:
    
    clearUpdateNeeded in class NativeObject
  - convertToHalf
```
public void convertToHalf()
```
    Converts single floating-point data to half floating-point data.
  - compact
```
public void compact(int numElements)
```
    Reduces the capacity of the buffer to the given amount of elements, any elements at the end of the buffer are truncated as necessary.
    
    Parameters:
    
    numElements - The number of elements to reduce to.
  - setElementComponent
```
public void setElementComponent(int elementIndex,
                                int componentIndex,
                                java.lang.Object val)
```
    Modify a component inside an element. The val parameter must be in the buffer's format: VertexBuffer.Format.
    
    Parameters:
    
    elementIndex - The element index to modify
    
    componentIndex - The component index to modify
    
    val - The value to set, either byte, short, int or float depending on the VertexBuffer.Format.
  - getElementComponent
```
public java.lang.Object getElementComponent(int elementIndex,
                                            int componentIndex)
```
    Get the component inside an element.
    
    Parameters:
    
    elementIndex - The element index
    
    componentIndex - The component index
    
    Returns:
    
    The component, as one of the primitive types, byte, short, int or float.
  - copyElement
```
public void copyElement(int inIndex,
                        VertexBuffer outVb,
                        int outIndex)
```
    Copies a single element of data from this VertexBuffer to the given output VertexBuffer.
    
    Parameters:
    
    inIndex - The input element index
    
    outVb - The buffer to copy to
    
    outIndex - The output element index
    
    Throws:
    
    java.lang.IllegalArgumentException - If the formats of the buffers do not match.
  - copyElements
```
public void copyElements(int inIndex,
                         VertexBuffer outVb,
                         int outIndex,
                         int len)
```
    Copies a sequence of elements of data from this VertexBuffer to the given output VertexBuffer.
    
    Parameters:
    
    inIndex - The input element index
    
    outVb - The buffer to copy to
    
    outIndex - The output element index
    
    len - The number of elements to copy
    
    Throws:
    
    java.lang.IllegalArgumentException - If the formats of the buffers do not match.
  - createBuffer
```
public static java.nio.Buffer createBuffer(VertexBuffer.Format format,
                                           int components,
                                           int numElements)
```
    Creates a Buffer that satisfies the given type and size requirements of the parameters. The buffer will be of the type specified by format and would be able to contain the given number of elements with the given number of components in each element.
    
    Parameters:
    
    format - the desired format of components, such as Float or Half
    
    components - the number of components per element (≥1, ≤4)
    
    numElements - the desired capacity (number of elements)
    
    Returns:
    
    a new Buffer
  - clone
```
public VertexBuffer clone()
```
    Creates a deep clone of the VertexBuffer.
    
    Overrides:
    
    clone in class NativeObject
    
    Returns:
    
    Deep clone of this buffer
  - clone
```
public VertexBuffer clone(VertexBuffer.Type overrideType)
```
    Creates a deep clone of this VertexBuffer but overrides the VertexBuffer.Type.
    
    Parameters:
    
    overrideType - The type of the cloned VertexBuffer
    
    Returns:
    
    A deep clone of the buffer
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class NativeObject
  - resetObject
```
public void resetObject()
```
    Description copied from class: NativeObject
    
    Called when the GL context is restarted to reset all IDs. Prevents "white textures" on display restart.
    
    Specified by:
    
    resetObject in class NativeObject
  - deleteObject
```
public void deleteObject(java.lang.Object rendererObject)
```
    Description copied from class: NativeObject
    
    Deletes the GL object from the GPU when it is no longer used. Called automatically by the GL object manager.
    
    Specified by:
    
    deleteObject in class NativeObject
    
    Parameters:
    
    rendererObject - The renderer to be used to delete the object
  - deleteNativeBuffers
```
protected void deleteNativeBuffers()
```
    Description copied from class: NativeObject
    
    Deletes any associated native buffers. This is necessary because it is unlikely that native buffers will be garbage collected naturally (due to how GC works), therefore the collection must be handled manually. Only implementations that manage native buffers need to override this method. Note that the behavior that occurs when a deleted native buffer is used is not defined, therefore this method is protected
    
    Overrides:
    
    deleteNativeBuffers in class NativeObject
  - createDestructableClone
```
public NativeObject createDestructableClone()
```
    Description copied from class: NativeObject
    
    Creates a shallow clone of this GL Object. The deleteObject method should be functional for this object.
    
    Specified by:
    
    createDestructableClone in class NativeObject
    
    Returns:
    
    a new instance
  - getUniqueId
```
public long getUniqueId()
```
    Description copied from class: NativeObject
    
    Returns a unique ID for this NativeObject. No other NativeObject shall have the same ID.
    
    Specified by:
    
    getUniqueId in class NativeObject
    
    Returns:
    
    unique ID for this NativeObject.
  - write
```
public void write(JmeExporter ex)
           throws java.io.IOException
```
    Specified by:
    
    write in interface Savable
    
    Throws:
    
    java.io.IOException
  - read
```
public void read(JmeImporter im)
          throws java.io.IOException
```
    Specified by:
    
    read in interface Savable
    
    Throws:
    
    java.io.IOException

Class VertexBuffer

Nested Class Summary

Field Summary

Fields inherited from class com.jme3.util.NativeObject

Constructor Summary

Method Summary

Methods inherited from class com.jme3.util.NativeObject

Methods inherited from class java.lang.Object

Field Detail

offset

lastLimit

stride

components

componentsLength

data

usage

bufType

format

normalized

instanceSpan

dataSizeChanged

Constructor Detail

VertexBuffer

VertexBuffer

VertexBuffer

Method Detail

invariant

getOffset

setOffset

getStride

setStride

getData

getDataReadOnly

getUsage

setUsage

setNormalized

isNormalized

setInstanced

isInstanced

setInstanceSpan

getInstanceSpan

getBufferType

getFormat

getNumComponents

getNumElements

getBaseInstanceCount

setupData

updateData

hasDataSizeChanged

clearUpdateNeeded

convertToHalf

compact

setElementComponent

getElementComponent

copyElement

copyElements

createBuffer

clone

clone

toString

resetObject

deleteObject

deleteNativeBuffers

createDestructableClone

getUniqueId

write

read