class SF::VertexBuffer
inherits Reference
#
Vertex buffer storage for one or more 2D primitives
SF::VertexBuffer is a simple wrapper around a dynamic
buffer of vertices and a primitives type.
Unlike SF::VertexArray, the vertex data is stored in
graphics memory.
In situations where a large amount of vertex data would
have to be transferred from system memory to graphics memory
every frame, using SF::VertexBuffer can help. By using a
SF::VertexBuffer, data that has not been changed between frames
does not have to be re-transferred from system to graphics
memory as would be the case with SF::VertexArray. If data transfer
is a bottleneck, this can lead to performance gains.
Using SF::VertexBuffer, the user also has the ability to only modify
a portion of the buffer in graphics memory. This way, a large buffer
can be allocated at the start of the application and only the
applicable portions of it need to be updated during the course of
the application. This allows the user to take full control of data
transfers between system and graphics memory if they need to.
In special cases, the user can make use of multiple threads to update vertex data in multiple distinct regions of the buffer simultaneously. This might make sense when e.g. the position of multiple objects has to be recalculated very frequently. The computation load can be spread across multiple threads as long as there are no other data dependencies.
Simultaneous updates to the vertex buffer are not guaranteed to be carried out by the driver in any specific order. Updating the same region of the buffer from multiple threads will not cause undefined behaviour, however the final state of the buffer will be unpredictable.
Simultaneous updates of distinct non-overlapping regions of the buffer are also not guaranteed to complete in a specific order. However, in this case the user can make sure to synchronize the writer threads at well-defined points in their code. The driver will make sure that all pending data transfers complete before the vertex buffer is sourced by the rendering pipeline.
It inherits SF::Drawable, but unlike other drawables it
is not transformable.
Example:
sf::Vertex vertices[15];
// [...]
sf::VertexBuffer triangles(sf::Triangles);
triangles.create(15);
triangles.update(vertices);
// [...]
window.draw(triangles);
See also: SF::Vertex, SF::VertexArray
Included modules
SF::Drawable
SF::GlResource
Constructors#
.new(type : PrimitiveType, usage : VertexBuffer::Usage)#
Construct a VertexBuffer with a specific PrimitiveType and usage specifier
Creates an empty vertex buffer and sets its primitive type to type and usage to usage.
- type - Type of primitive
- usage - Usage specifier
.new(type : PrimitiveType)#
Construct a VertexBuffer with a specific PrimitiveType
Creates an empty vertex buffer and sets its primitive type to type.
- type - Type of primitive
.new(usage : VertexBuffer::Usage)#
Construct a VertexBuffer with a specific usage specifier
Creates an empty vertex buffer and sets its usage to usage.
- usage - Usage specifier
.new(*args, **kwargs) : self#
Shorthand for vertex_buffer = VertexBuffer.new; vertex_buffer.create(...); vertex_buffer
Raises InitError on failure
Class methods#
.available? : Bool#
Tell whether or not the system supports vertex buffers
This function should always be called before using
the vertex buffer features. If it returns false, then
any attempt to use SF::VertexBuffer will fail.
Returns: True if vertex buffers are supported, false otherwise
.bind(vertex_buffer : VertexBuffer | Nil)#
Bind a vertex buffer for rendering
This function is not part of the graphics API, it mustn't be
used when drawing SFML entities. It must be used only if you
mix SF::VertexBuffer with OpenGL code.
sf::VertexBuffer vb1, vb2;
...
sf::VertexBuffer::bind(&vb1);
// draw OpenGL stuff that use vb1...
sf::VertexBuffer::bind(&vb2);
// draw OpenGL stuff that use vb2...
sf::VertexBuffer::bind(NULL);
// draw OpenGL stuff that use no vertex buffer...
- vertex_buffer - Pointer to the vertex buffer to bind, can be null to use no vertex buffer
Methods#
#create(vertex_count : Int) : Bool#
Create the vertex buffer
Creates the vertex buffer and allocates enough graphics memory to hold vertex_count vertices. Any previously allocated memory is freed in the process.
In order to deallocate previously allocated memory pass 0 as vertex_count. Don't forget to recreate with a non-zero value when graphics memory should be allocated again.
- vertex_count - Number of vertices worth of memory to allocate
Returns: True if creation was successful
#dup : VertexBuffer#
Returns a shallow copy of this object.
This allocates a new object and copies the contents of
self into it.
#native_handle : Int32#
Get the underlying OpenGL handle of the vertex buffer.
You shouldn't need to use this function, unless you have very specific stuff to implement that SFML doesn't support, or implement a temporary workaround until a bug is fixed.
Returns: OpenGL handle of the vertex buffer or 0 if not yet created
#primitive_type : PrimitiveType#
Get the type of primitives drawn by the vertex buffer
Returns: Primitive type
#primitive_type=(type : PrimitiveType)#
Set the type of primitives to draw
This function defines how the vertices must be interpreted when it's time to draw them.
The default primitive type is SF::Points.
- type - Type of primitive
#swap(right : VertexBuffer)#
Swap the contents of this vertex buffer with those of another
- right - Instance to swap with
#update(vertices : Array(Vertex) | Slice(Vertex), offset : Int) : Bool#
Update a part of the buffer from an array of vertices
offset is specified as the number of vertices to skip from the beginning of the buffer.
If offset is 0 and vertex_count is equal to the size of the currently created buffer, its whole contents are replaced.
If offset is 0 and vertex_count is greater than the size of the currently created buffer, a new buffer is created containing the vertex data.
If offset is 0 and vertex_count is less than the size of the currently created buffer, only the corresponding region is updated.
If offset is not 0 and offset + vertex_count is greater than the size of the currently created buffer, the update fails.
No additional check is performed on the size of the vertex array, passing invalid arguments will lead to undefined behavior.
- vertices - Array of vertices to copy to the buffer
- vertex_count - Number of vertices to copy
- offset - Offset in the buffer to copy to
Returns: True if the update was successful
#update(vertices : Vertex) : Bool#
Update the whole buffer from an array of vertices
The vertex array is assumed to have the same size as the created buffer.
No additional check is performed on the size of the vertex array, passing invalid arguments will lead to undefined behavior.
This function does nothing if vertices is null or if the buffer was not previously created.
- vertices - Array of vertices to copy to the buffer
Returns: True if the update was successful
#update(vertex_buffer : VertexBuffer) : Bool#
Copy the contents of another buffer into this buffer
- vertex_buffer - Vertex buffer whose contents to copy into this vertex buffer
Returns: True if the copy was successful
#usage : VertexBuffer::Usage#
Get the usage specifier of this vertex buffer
Returns: Usage specifier
#usage=(usage : VertexBuffer::Usage)#
Set the usage specifier of this vertex buffer
This function provides a hint about how this vertex buffer is going to be used in terms of data update frequency.
After changing the usage specifier, the vertex buffer has to be updated with new data for the usage specifier to take effect.
The default primitive type is SF::VertexBuffer::Stream.
- usage - Usage specifier
#vertex_count : Int32#
Return the vertex count
Returns: Number of vertices in the vertex buffer