Documentation of SFML 2.6.0

Warning: this page refers to an old version of SFML. Click here to switch to the latest version.
Loading...
Searching...
No Matches
sf::VertexBuffer Class Reference

Vertex buffer storage for one or more 2D primitives. More...

#include <SFML/Graphics/VertexBuffer.hpp>

Inheritance diagram for sf::VertexBuffer:
sf::Drawable sf::GlResource

Public Types

enum  Usage { Stream , Dynamic , Static }
 Usage specifiers. More...
 

Public Member Functions

 VertexBuffer ()
 Default constructor.
 
 VertexBuffer (PrimitiveType type)
 Construct a VertexBuffer with a specific PrimitiveType.
 
 VertexBuffer (Usage usage)
 Construct a VertexBuffer with a specific usage specifier.
 
 VertexBuffer (PrimitiveType type, Usage usage)
 Construct a VertexBuffer with a specific PrimitiveType and usage specifier.
 
 VertexBuffer (const VertexBuffer &copy)
 Copy constructor.
 
 ~VertexBuffer ()
 Destructor.
 
bool create (std::size_t vertexCount)
 Create the vertex buffer.
 
std::size_t getVertexCount () const
 Return the vertex count.
 
bool update (const Vertex *vertices)
 Update the whole buffer from an array of vertices.
 
bool update (const Vertex *vertices, std::size_t vertexCount, unsigned int offset)
 Update a part of the buffer from an array of vertices.
 
bool update (const VertexBuffer &vertexBuffer)
 Copy the contents of another buffer into this buffer.
 
VertexBufferoperator= (const VertexBuffer &right)
 Overload of assignment operator.
 
void swap (VertexBuffer &right)
 Swap the contents of this vertex buffer with those of another.
 
unsigned int getNativeHandle () const
 Get the underlying OpenGL handle of the vertex buffer.
 
void setPrimitiveType (PrimitiveType type)
 Set the type of primitives to draw.
 
PrimitiveType getPrimitiveType () const
 Get the type of primitives drawn by the vertex buffer.
 
void setUsage (Usage usage)
 Set the usage specifier of this vertex buffer.
 
Usage getUsage () const
 Get the usage specifier of this vertex buffer.
 

Static Public Member Functions

static void bind (const VertexBuffer *vertexBuffer)
 Bind a vertex buffer for rendering.
 
static bool isAvailable ()
 Tell whether or not the system supports vertex buffers.
 

Detailed Description

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);
Define a point with color and texture coordinates.
Definition: Vertex.hpp:43
@ Triangles
List of individual triangles.
See also
sf::Vertex, sf::VertexArray

Definition at line 46 of file VertexBuffer.hpp.

Member Enumeration Documentation

◆ Usage

Usage specifiers.

If data is going to be updated once or more every frame, set the usage to Stream. If data is going to be set once and used for a long time without being modified, set the usage to Static. For everything else Dynamic should be a good compromise.

Enumerator
Stream 

Constantly changing data.

Dynamic 

Occasionally changing data.

Static 

Rarely changing data.

Definition at line 60 of file VertexBuffer.hpp.

Constructor & Destructor Documentation

◆ VertexBuffer() [1/5]

sf::VertexBuffer::VertexBuffer ( )

Default constructor.

Creates an empty vertex buffer.

◆ VertexBuffer() [2/5]

sf::VertexBuffer::VertexBuffer ( PrimitiveType  type)
explicit

Construct a VertexBuffer with a specific PrimitiveType.

Creates an empty vertex buffer and sets its primitive type to type.

Parameters
typeType of primitive

◆ VertexBuffer() [3/5]

sf::VertexBuffer::VertexBuffer ( Usage  usage)
explicit

Construct a VertexBuffer with a specific usage specifier.

Creates an empty vertex buffer and sets its usage to usage.

Parameters
usageUsage specifier

◆ VertexBuffer() [4/5]

sf::VertexBuffer::VertexBuffer ( PrimitiveType  type,
Usage  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.

Parameters
typeType of primitive
usageUsage specifier

◆ VertexBuffer() [5/5]

sf::VertexBuffer::VertexBuffer ( const VertexBuffer copy)

Copy constructor.

Parameters
copyinstance to copy

◆ ~VertexBuffer()

sf::VertexBuffer::~VertexBuffer ( )

Destructor.

Member Function Documentation

◆ bind()

static void sf::VertexBuffer::bind ( const VertexBuffer vertexBuffer)
static

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::bind(&vb1);
// draw OpenGL stuff that use vb1...
// draw OpenGL stuff that use vb2...
// draw OpenGL stuff that use no vertex buffer...
Vertex buffer storage for one or more 2D primitives.
static void bind(const VertexBuffer *vertexBuffer)
Bind a vertex buffer for rendering.
Parameters
vertexBufferPointer to the vertex buffer to bind, can be null to use no vertex buffer

◆ create()

bool sf::VertexBuffer::create ( std::size_t  vertexCount)

Create the vertex buffer.

Creates the vertex buffer and allocates enough graphics memory to hold vertexCount vertices. Any previously allocated memory is freed in the process.

In order to deallocate previously allocated memory pass 0 as vertexCount. Don't forget to recreate with a non-zero value when graphics memory should be allocated again.

Parameters
vertexCountNumber of vertices worth of memory to allocate
Returns
True if creation was successful

◆ getNativeHandle()

unsigned int sf::VertexBuffer::getNativeHandle ( ) const

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

◆ getPrimitiveType()

PrimitiveType sf::VertexBuffer::getPrimitiveType ( ) const

Get the type of primitives drawn by the vertex buffer.

Returns
Primitive type

◆ getUsage()

Usage sf::VertexBuffer::getUsage ( ) const

Get the usage specifier of this vertex buffer.

Returns
Usage specifier

◆ getVertexCount()

std::size_t sf::VertexBuffer::getVertexCount ( ) const

Return the vertex count.

Returns
Number of vertices in the vertex buffer

◆ isAvailable()

static bool sf::VertexBuffer::isAvailable ( )
static

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

◆ operator=()

VertexBuffer & sf::VertexBuffer::operator= ( const VertexBuffer right)

Overload of assignment operator.

Parameters
rightInstance to assign
Returns
Reference to self

◆ setPrimitiveType()

void sf::VertexBuffer::setPrimitiveType ( PrimitiveType  type)

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.

Parameters
typeType of primitive

◆ setUsage()

void sf::VertexBuffer::setUsage ( Usage  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.

Parameters
usageUsage specifier

◆ swap()

void sf::VertexBuffer::swap ( VertexBuffer right)

Swap the contents of this vertex buffer with those of another.

Parameters
rightInstance to swap with

◆ update() [1/3]

bool sf::VertexBuffer::update ( const Vertex vertices)

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.

Parameters
verticesArray of vertices to copy to the buffer
Returns
True if the update was successful

◆ update() [2/3]

bool sf::VertexBuffer::update ( const Vertex vertices,
std::size_t  vertexCount,
unsigned int  offset 
)

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 vertexCount is equal to the size of the currently created buffer, its whole contents are replaced.

If offset is 0 and vertexCount is greater than the size of the currently created buffer, a new buffer is created containing the vertex data.

If offset is 0 and vertexCount is less than the size of the currently created buffer, only the corresponding region is updated.

If offset is not 0 and offset + vertexCount 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.

Parameters
verticesArray of vertices to copy to the buffer
vertexCountNumber of vertices to copy
offsetOffset in the buffer to copy to
Returns
True if the update was successful

◆ update() [3/3]

bool sf::VertexBuffer::update ( const VertexBuffer vertexBuffer)

Copy the contents of another buffer into this buffer.

Parameters
vertexBufferVertex buffer whose contents to copy into this vertex buffer
Returns
True if the copy was successful

The documentation for this class was generated from the following file: