Package com.jme3.scene

Class VertexBuffer

java.lang.Object
com.jme3.util.NativeObject
com.jme3.scene.VertexBuffer
All Implemented Interfaces:
Savable, Cloneable
public class VertexBuffer extends NativeObject implements Savable, 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.

  • Field Details

    • 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 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

    • name

      protected String name

  • Constructor Details

    • 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 Details

    • invariant

      public boolean invariant()

    • getOffset

      public int getOffset()
      Returns:
      The offset after which the data is sent to the GPU.
      See Also:

    • 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

      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 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 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:

    • 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, 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(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, 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 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:
      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:
      IllegalArgumentException - If the formats of the buffers do not match.

    • createBuffer

      public static 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 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(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 IOException
      Specified by:
      write in interface Savable
      Throws:
      IOException

    • read

      public void read(JmeImporter im) throws IOException
      Specified by:
      read in interface Savable
      Throws:
      IOException

    • getName

      public String getName()
      Returns the name of this `VertexBuffer`. If no name has been explicitly set, a default name is generated based on its class name and buffer type (e.g., "VertexBuffer(Position)").
      Returns:
      The name of the `VertexBuffer`.

    • setName

      public void setName(String name)
      Sets a custom name for this `VertexBuffer`.
      Parameters:
      name - The new name for the `VertexBuffer`. Can be null to revert to the default generated name.