Stellarium 0.12.1
List of all members | Public Member Functions
StelVertexBuffer< V > Class Template Reference

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

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
vertexVertex 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
indexIndex 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
indexIndex of the vertex to set.
vertexValue 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: