Stellarium 0.12.0
Home · All Namespaces · All Classes · Functions · Coding Style · Scripting · Plugins · Renderer · File Structure

StelVertexBuffer< V > Class Template Reference

Vertex buffer interface. More...

#include <StelVertexBuffer.hpp>

List of all members.

Public Member Functions

 ~StelVertexBuffer ()
 Destroy the vertex buffer. StelVertexBuffer is deleted by the user, not StelRenderer.
void addVertex (const V &vertex)
 Add a new vertex to the end of the buffer.
getVertex (const int index) const
 Return vertex at specified index in the buffer.
void setVertex (const int index, const V &vertex)
 Set vertex at specified index in the buffer.
void lock ()
 Lock the buffer. Must be called before drawing.
void unlock ()
 Unlock the buffer. This is needed to modify the buffer after drawing.
bool locked () const
 Is this buffer locked?
int length () const
 Returns the number of vertices in the buffer.
PrimitiveType primitiveType () const
 Return the type of graphics primitives drawn with this vertex buffer.
virtual void clear ()
 Clear the buffer, removing all vertices.

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:
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:
vertex Vertex to add.

Definition at line 189 of file StelVertexBuffer.hpp.

template<class V>
virtual void StelVertexBuffer< V >::clear (  )  [inline, virtual]

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:
Generated on Thu Jan 31 14:05:47 2013 for Stellarium by  doxygen 1.6.3