com.jme3.scene

Class VertexBuffer

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

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() Returns true if instanceSpan is more than 0 indicating that this vertex buffer contains per-instance data.
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.

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.

isInstanced

public boolean isInstanced()

Returns true if instanceSpan is more than 0 indicating that this vertex buffer contains per-instance data.

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.

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.

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

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

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