Vertex buffer interface. More...

#include <StelVertexBuffer.hpp>

Public Member Functions
	~StelVertexBuffer ()
	Destroy the vertex buffer. StelVertexBuffer is deleted by the user, not StelRenderer. More...

void	addVertex (const V &vertex)
	Add a new vertex to the end of the buffer. More...

V	getVertex (const int index) const
	Return vertex at specified index in the buffer. More...

void	setVertex (const int index, const V &vertex)
	Set vertex at specified index in the buffer. More...

void	lock ()
	Lock the buffer. Must be called before drawing. More...

void	unlock ()
	Unlock the buffer. This is needed to modify the buffer after drawing. More...

bool	locked () const
	Is this buffer locked? More...

int	length () const
	Returns the number of vertices in the buffer. More...

PrimitiveType	primitiveType () const
	Return the type of graphics primitives drawn with this vertex buffer. More...

virtual void	clear ()
	Clear the buffer, removing all vertices. More...

Detailed Description

template<class V>
class StelVertexBuffer< V >

Vertex buffer interface.

Each StelRenderer backend might have a different vertex buffer buffer implementation. StelVertexBuffer, created by the StelRenderer's createVertexBuffer() function wraps this backend.

StelVertexBuffer supports basic operations such as adding, getting and modifying vertices. It can be locked to allow uploading the data to the GPU, and unlocked to modify the buffer.

For drawing (by a StelRenderer), the vertex buffer must be locked. To access/modify vertices, it must be unlocked. A newly created vertex buffer is always unlocked.

Template Parameters

V	Vertex type. The addVertex(), getVertex() and setVertex() functions work with this type. This allows the API to be minimal and safe at the same time (no way to mess up vertex format).

The vertex type is defined by the user. Some commonly used vertex types are in the file GenericVertexTypes.hpp.

Example vertex type:

struct MyVertex
{
    // Vertex data members (attributes). 
    Vec3f position;
    Vec2f texCoord;
    
    // This macro specifies metadata (data type and interpretation)
    // of each attribute.  Data type can be Vec2f, Vec3f or Vec4f.
    // Interpretation can be Position, TexCoord, Normal or Color.
    // Two attributes must never have the same interpretation
    // (this is asserted by the vertex buffer backend at run time).
    //
    // Note:
    // Attribute interpretations are processed at runtime, so if there 
    // is an error here, Stellarium will crash with an assertion failure and an 
    // error message.
    //
    // (C++11 TODO) This might be changed with constexpr
    VERTEX_ATTRIBUTES(Vec3f Position, Vec2f TexCoord);
};

Note: There are some requirements for a vertex type. These are verified at run time. The requirements are:

A position attribute is required.
Any texture coordinates must be 2D. There is no 1D or 3D texture support right now.
Any normals must be 3D.

Note: When drawing with a custom StelProjector (using StelRenderer::drawVertexBuffer), only 3D vertex positions are supported.; Currently, the GL2 backend only supports some combinations of attribute interpretations (e.g. just position, position-color, etc.). This is because every such combination needs a custom shader. If you get an assertion error about an unimplemented shader for vertex format, feel free to add it (in StelQGL2Renderer). All vertex formats currently used in Stellarium are already covered.

See Also: AttributeType, AttributeInterpretation, StelVertexAttribute, StelRenderer

API design notes

Currently, vertices must be accessed individually through functions that might have considerable overhead (at least due to indirect call through the virtual function table).

If vertex processing turns out to be too slow, the solution is not to allow direct access to data through the pointer, as that ties us to a particular implementation (array in memory) and might be completely unusable with e.g. VBO based backends.

Rather, considerable speedup could be achieved by adding member functions to add, get and set ranges of vertices.

E.g.:

void addVertexRange(const QVector<V>& vertices)
void getVertexRange(QVector<V>& outVertices, uint start, uint end)
void setVertexRange(const QVector<V> vertices, uint start, uint end)

Note that end might be unnecessary in setVertexRange.

This is still not the same speedup as direct access (due to copying in get/set), but should allow for considerably faster implementations than accessing vertices individually, without forcing backends to store vertices in a particular way.

An alternative, possibly better (especially with C++11) option for modifying vertices would be to use a function pointer / function object to process each vertex.

Vertex buffer backend

VertexBuffer is currently separated into frontend (StelVertexBuffer), which allows type-safe vertex buffer construction thanks to templates, and backend, which doesn't know the vertex type and works on raw data described by metadata generated by the VERTEX_ATTRIBUTES macro in the vertex type.

This is because virtual methods can't be templated. There might be a workaround for this, but I'm not aware of any at the moment.

Definition at line 171 of file StelVertexBuffer.hpp.

Constructor & Destructor Documentation

template<class V>

StelVertexBuffer< V >::~StelVertexBuffer ( )

inline

Destroy the vertex buffer. StelVertexBuffer is deleted by the user, not StelRenderer.

Definition at line 179 of file StelVertexBuffer.hpp.

Member Function Documentation

template<class V>

void StelVertexBuffer< V >::addVertex ( const V & vertex )

inline

Add a new vertex to the end of the buffer.

The buffer must not be locked.

Parameters

vertex Vertex to add.

Definition at line 189 of file StelVertexBuffer.hpp.

template<class V>

virtual void StelVertexBuffer< V >::clear ( )

inlinevirtual

Clear the buffer, removing all vertices.

The buffer must not be locked.

The backend implementation might reuse previously allocated storage after clearing, so calling clear() might be more efficient than destroying a buffer and then constructing a new one.

Definition at line 271 of file StelVertexBuffer.hpp.

template<class V>

V StelVertexBuffer< V >::getVertex ( const int index ) const

inline

Return vertex at specified index in the buffer.

The buffer must not be locked.

Parameters

index Index of the vertex to get.

Returns: Vertex at specified index.

Definition at line 203 of file StelVertexBuffer.hpp.

template<class V>

int StelVertexBuffer< V >::length ( ) const

inline

Returns the number of vertices in the buffer.

Definition at line 253 of file StelVertexBuffer.hpp.

template<class V>

void StelVertexBuffer< V >::lock ( )

inline

Lock the buffer. Must be called before drawing.

Definition at line 233 of file StelVertexBuffer.hpp.

template<class V>

bool StelVertexBuffer< V >::locked ( ) const

inline

Is this buffer locked?

Definition at line 247 of file StelVertexBuffer.hpp.

template<class V>

PrimitiveType StelVertexBuffer< V >::primitiveType ( ) const

inline

Return the type of graphics primitives drawn with this vertex buffer.

Definition at line 259 of file StelVertexBuffer.hpp.

template<class V>

void StelVertexBuffer< V >::setVertex	(	const int	index,
		const V &	vertex
	)

inline

Set vertex at specified index in the buffer.

The buffer must not be locked.

Parameters

index	Index of the vertex to set.
vertex	Value to set the vertex to.

Definition at line 224 of file StelVertexBuffer.hpp.

template<class V>

void StelVertexBuffer< V >::unlock ( )

inline

Unlock the buffer. This is needed to modify the buffer after drawing.

Definition at line 240 of file StelVertexBuffer.hpp.

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

core/renderer/StelVertexBuffer.hpp

Public Member Functions

Detailed Description

template<class V> class StelVertexBuffer< V >

API design notes

Vertex buffer backend

Constructor & Destructor Documentation

Member Function Documentation

template<class V>
class StelVertexBuffer< V >