com.jme3.scene
Class VertexBuffer

java.lang.Object
  extended by com.jme3.util.NativeObject
      extended by 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:


Nested Class Summary
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
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 lastLimit
           
protected  boolean normalized
           
protected  int offset
           
protected  int stride
           
protected  VertexBuffer.Usage usage
           
 
Fields inherited from class com.jme3.util.NativeObject
handleRef, id, type, updateNeeded
 
Constructor Summary
  VertexBuffer()
          Serialization only.
protected VertexBuffer(int id)
           
  VertexBuffer(VertexBuffer.Type type)
          Creates an empty, uninitialized buffer.
 
Method Summary
 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.
 void deleteObject(java.lang.Object rendererObject)
          Deletes the GL object from the GPU when it is no longer used.
 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 getNumComponents()
           
 int getNumElements()
           
 int getOffset()
           
 int getStride()
           
 VertexBuffer.Usage getUsage()
           
 boolean hasDataSizeChanged()
          Returns true if the data size of the VertexBuffer has changed.
 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 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
getId, 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

dataSizeChanged

protected transient boolean dataSizeChanged
Constructor Detail

VertexBuffer

public VertexBuffer(VertexBuffer.Type type)
Creates an empty, uninitialized buffer. Must call setupData() to initialize.


VertexBuffer

public VertexBuffer()
Serialization only. Do not use.


VertexBuffer

protected VertexBuffer(int id)
Method Detail

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)

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.

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.


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

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

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