Stellarium 0.12.2
List of all members | Public Member Functions | Protected Member Functions
StelRenderer Class Referenceabstract

Main class of the Renderer subsystem. More...

#include <StelRenderer.hpp>

Public Member Functions

virtual ~StelRenderer ()
 Destructor. More...
 
virtual bool init ()=0
 Initialize the renderer. More...
 
virtual QImage screenshot ()=0
 Take a screenshot and return it. More...
 
virtual void viewportHasBeenResized (const QSize size)=0
 Must be called once at startup and on every GL viewport resize, specifying new size. More...
 
virtual class StelIndexBuffercreateIndexBuffer (const IndexType type)=0
 Create an empty index buffer and return a pointer to it. More...
 
template<class V >
StelVertexBuffer< V > * createVertexBuffer (const PrimitiveType primitiveType)
 Create an empty vertex buffer and return a pointer to it. More...
 
template<class V >
void drawVertexBuffer (StelVertexBuffer< V > *vertexBuffer, class StelIndexBuffer *indexBuffer=NULL, StelProjectorP projector=StelProjectorP(NULL), bool dontProject=false)
 Draw contents of a vertex buffer. More...
 
template<class V >
void drawVertexBuffer (StelVertexBuffer< V > *vertexBuffer, class StelIndexBuffer *indexBuffer, StelProjector *projector, bool dontProject=false)
 Draw contents of a vertex buffer. More...
 
virtual void drawLine (const float startX, const float startY, const float endX, const float endY)
 Draw a line with current global color to the screen. More...
 
virtual void drawRect (const float x, const float y, const float width, const float height, const float angle=0.0f)=0
 Draw a rectangle to the screen. More...
 
virtual void drawTexturedRect (const float x, const float y, const float width, const float height, const float angle=0.0f)=0
 Draw a textured rectangle to the screen. More...
 
virtual void drawText (const TextParams &params)=0
 Draw text with specified parameters. More...
 
virtual void setFont (const QFont &font)=0
 Set font to use for drawing text. More...
 
virtual void renderFrame (StelRenderClient &renderClient)=0
 Render a frame. More...
 
StelTextureNewcreateTexture (const QString &filename, const TextureParams &params=TextureParams(), const TextureLoadingMode loadingMode=TextureLoadingMode_Normal)
 Create a texture from specified file or URL. More...
 
StelTextureNewcreateTexture (QImage &image, const TextureParams &params=TextureParams())
 Create a texture from an image. More...
 
StelTextureNewcreateTexture (const void *const data, const QSize size, const TextureDataFormat format, const TextureParams &params=TextureParams())
 Create a texture from raw data. More...
 
virtual bool areFloatTexturesSupported () const =0
 Returns true if floating point textures are supported, false otherwise. More...
 
StelTextureNewgetViewportTexture ()
 Get a texture of the viewport, with everything drawn to the viewport so far. More...
 
virtual StelGLSLShadercreateGLSLShader ()
 Create a GLSL shader. More...
 
virtual bool isGLSLSupported () const =0
 Are GLSL shaders supported? More...
 
virtual QSize getViewportSize () const =0
 Get size of the viewport in pixels. More...
 
virtual void setGlobalColor (const Vec4f &color)=0
 Set the global vertex color. More...
 
void setGlobalColor (const float r, const float g, const float b, const float a=1.0f)
 setGlobalColor overload specifying color channels directly instead of through Vec4f. More...
 
virtual void setBlendMode (const BlendMode blendMode)=0
 Set blend mode. More...
 
virtual void setCulledFaces (const CullFace cullFace)=0
 Set which faces (triangles) should be culled. More...
 
virtual void clearDepthBuffer ()=0
 Clear the depth buffer to zeroes, removing any depth information. More...
 
virtual void setDepthTest (const DepthTest test)=0
 Set depth test mode. More...
 
virtual void clearStencilBuffer ()=0
 Clear the stencil buffer to zeroes, removing any stencil information. More...
 
virtual void setStencilTest (const StencilTest test)=0
 Set stencil test mode. More...
 
virtual void swapBuffers ()=0
 Swap front and back buffers. More...
 
virtual StelRendererStatisticsgetStatistics ()=0
 Access statistics data. More...
 

Protected Member Functions

virtual StelVertexBufferBackendcreateVertexBufferBackend (const PrimitiveType primitiveType, const QVector< StelVertexAttribute > &attributes)=0
 Create a vertex buffer backend. More...
 
virtual void drawVertexBufferBackend (StelVertexBufferBackend *vertexBuffer, class StelIndexBuffer *indexBuffer, StelProjector *projector, const bool dontProject)=0
 Draw contents of a vertex buffer (backend). More...
 
virtual class StelTextureBackendcreateTextureBackend (const QString &filename, const TextureParams &params, const TextureLoadingMode loadingMode)=0
 Implementation of createTexture. More...
 
virtual class StelTextureBackendcreateTextureBackend (QImage &image, const TextureParams &params)=0
 Implementation of createTexture loading from image. More...
 
virtual class StelTextureBackendcreateTextureBackend (const void *data, const QSize size, const TextureDataFormat format, const TextureParams &params)=0
 Implementation of createTexture loading from raw data. More...
 
virtual class StelTextureBackendgetViewportTextureBackend ()=0
 Implementation of getViewportTexture. More...
 
virtual void destroyTextureBackend (class StelTextureBackend *backend)=0
 Destroy a StelTextureBackend. More...
 
virtual void bindTextureBackend (class StelTextureBackend *textureBackend, const int textureUnit)=0
 Bind a texture (following draw calls will use this texture on specified texture unit). More...
 

Detailed Description

Main class of the Renderer subsystem.

Handles all drawing functionality.

Note
This is an interface. It should have only functions, no data members, as it might be used in multiple inheritance.

Definition at line 248 of file StelRenderer.hpp.

Constructor & Destructor Documentation

virtual StelRenderer::~StelRenderer ( )
inlinevirtual

Destructor.

Definition at line 254 of file StelRenderer.hpp.

Member Function Documentation

virtual bool StelRenderer::areFloatTexturesSupported ( ) const
pure virtual

Returns true if floating point textures are supported, false otherwise.

Implemented in StelQGL2Renderer, and StelQGL1Renderer.

virtual void StelRenderer::bindTextureBackend ( class StelTextureBackend textureBackend,
const int  textureUnit 
)
protectedpure virtual

Bind a texture (following draw calls will use this texture on specified texture unit).

Parameters
textureBackendTexture to bind.
textureUnitTexture unit to use. If multitexturing is not supported, binds to texture units other than 0 are ignored.

Implemented in StelQGLRenderer.

virtual void StelRenderer::clearDepthBuffer ( )
pure virtual

Clear the depth buffer to zeroes, removing any depth information.

Implemented in StelQGLRenderer.

virtual void StelRenderer::clearStencilBuffer ( )
pure virtual

Clear the stencil buffer to zeroes, removing any stencil information.

Implemented in StelQGLRenderer.

virtual StelGLSLShader* StelRenderer::createGLSLShader ( )
inlinevirtual

Create a GLSL shader.

This can only be called if isGLSLSupported() is true.

The constructed shader must be deleted before the StelRenderer is destroyed.

Reimplemented in StelQGL2Renderer, and StelQGL1Renderer.

Definition at line 571 of file StelRenderer.hpp.

virtual class StelIndexBuffer* StelRenderer::createIndexBuffer ( const IndexType  type)
pure virtual

Create an empty index buffer and return a pointer to it.

Implemented in StelQGLRenderer.

StelTextureNew* StelRenderer::createTexture ( const QString &  filename,
const TextureParams params = TextureParams(),
const TextureLoadingMode  loadingMode = TextureLoadingMode_Normal 
)
inline

Create a texture from specified file or URL.

The texture must be deleted before the StelRenderer is destroyed.

This method never fails, but the texture returned might have the Error status. Even in that case, the texture can be bound, but a placeholder texture will be used internally instead.

Parameters
filenameFile name or URL of the image to load the texture from. If it's a file and it's not found, it's searched for in the textures/ directory. Some renderer backends might also support compressed textures with custom file formats. These backend-specific files should not be specified by filename - instead, if a compressed texture with the same file name but different extension exists, it will be used. E.g. the GLES backend prefers a .pvr version of a texture if PVR is supported and it exists.
paramsTexture parameters, such as filtering, wrapping, etc.
loadingModeTexture loading mode to use. Normal immediately loads the texture, Asynchronous starts loading it in a background thread and LazyAsynchronous starts loading it when it's first needed.
Returns
New texture.
Note
Some renderer backends only support textures with power of two dimensions (e.g. 512x512 or 2048x256). On these backends, loading a texture with non-power-of-two dimensions will fail and result in a StelTextureNew with status of TextureStatus_Error.

Definition at line 461 of file StelRenderer.hpp.

StelTextureNew* StelRenderer::createTexture ( QImage &  image,
const TextureParams params = TextureParams() 
)
inline

Create a texture from an image.

The texture must be deleted before the StelRenderer is destroyed.

This method never fails, but the texture returned might have the Error status. Even in that case, the texture can be bound, but a placeholder texture will be used internally instead.

The texture is created immediately, as with TextureLoadingMode_Normal.

Parameters
imageImage to load the texture from.
paramsTexture parameters, such as filtering, wrapping, etc.
Returns
New texture.
Note
Some renderer backends only support textures with power of two dimensions (e.g. 512x512 or 2048x256). On these backends, loading a texture with non-power-of-two dimensions will fail and result in a StelTextureNew with status of TextureStatus_Error.

Definition at line 500 of file StelRenderer.hpp.

StelTextureNew* StelRenderer::createTexture ( const void *const  data,
const QSize  size,
const TextureDataFormat  format,
const TextureParams params = TextureParams() 
)
inline

Create a texture from raw data.

Used to load textures from image data unsupported by QImage, e.g. floating point textures.

Note
If creating a floating point texture, use areFloatTexturesSupported() to determine if if floating point textures are supported.

The texture must be deleted before the StelRenderer is destroyed.

This method never fails, but the texture returned might have the Error status. Even in that case, the texture can be bound, but a placeholder texture will be used internally instead.

The texture is created immediately, as with TextureLoadingMode_Normal.

Parameters
dataPointer to raw image data. Size of the data must be size.width() * size.height() * pixelSize, where pixelSize is size of a pixel of specified format.
sizeSize of the texture in pixels.
formatFormat of pixels in data.
paramsTexture parameters, such as filtering, wrapping, etc.
Returns
New texture.
Note
Some renderer backends only support textures with power of two dimensions (e.g. 512x512 or 2048x256). On these backends, loading a texture with non-power-of-two dimensions will fail and result in a StelTextureNew with status of TextureStatus_Error.

Definition at line 537 of file StelRenderer.hpp.

virtual class StelTextureBackend* StelRenderer::createTextureBackend ( const QString &  filename,
const TextureParams params,
const TextureLoadingMode  loadingMode 
)
protectedpure virtual

Implementation of createTexture.

Returns texture backend to be wrapped in a StelTextureNew. Must not fail, but can return a backend in error state.

See Also
createTexture

Implemented in StelQGLRenderer.

virtual class StelTextureBackend* StelRenderer::createTextureBackend ( QImage &  image,
const TextureParams params 
)
protectedpure virtual

Implementation of createTexture loading from image.

Returns texture backend to be wrapped in a StelTextureNew. Must not fail, but can return a backend in error state.

See Also
createTexture

Implemented in StelQGLRenderer.

virtual class StelTextureBackend* StelRenderer::createTextureBackend ( const void *  data,
const QSize  size,
const TextureDataFormat  format,
const TextureParams params 
)
protectedpure virtual

Implementation of createTexture loading from raw data.

Returns texture backend to be wrapped in a StelTextureNew. Must not fail, but can return a backend in error state.

See Also
createTexture

Implemented in StelQGLRenderer.

template<class V >
StelVertexBuffer<V>* StelRenderer::createVertexBuffer ( const PrimitiveType  primitiveType)
inline

Create an empty vertex buffer and return a pointer to it.

The vertex buffer must be deleted by the user once it is not used (and before the Renderer is destroyed).

Template Parameters
VVertex type. See the example in StelVertexBuffer documentation on how to define a vertex type.
Parameters
primitiveTypeGraphics primitive type stored in the buffer.
Returns
New vertex buffer storing vertices of type V.

Definition at line 283 of file StelRenderer.hpp.

virtual StelVertexBufferBackend* StelRenderer::createVertexBufferBackend ( const PrimitiveType  primitiveType,
const QVector< StelVertexAttribute > &  attributes 
)
protectedpure virtual

Create a vertex buffer backend.

Used by createVertexBuffer.

This allows each Renderer backend to create its own vertex buffer backend.

Parameters
primitiveTypeGraphics primitive type stored in the buffer.
attributesDescriptions of all attributes of the vertex type stored in the buffer.
Returns
Pointer to a vertex buffer backend specific to the Renderer backend.

Implemented in StelQGL2Renderer, and StelQGL1Renderer.

virtual void StelRenderer::destroyTextureBackend ( class StelTextureBackend backend)
protectedpure virtual

Destroy a StelTextureBackend.

The backend might be destroyed, but the implementation might also cache the texture, not destroying it if it has muliple users.

Implemented in StelQGLRenderer.

virtual void StelRenderer::drawLine ( const float  startX,
const float  startY,
const float  endX,
const float  endY 
)
virtual

Draw a line with current global color to the screen.

Parameters
startXX position of the starting point of the line in pixels.
startYY position of the starting point of the line in pixels.
endXX position of the ending point of the line in pixels.
endYY position of the ending point of the line in pixels.
virtual void StelRenderer::drawRect ( const float  x,
const float  y,
const float  width,
const float  height,
const float  angle = 0.0f 
)
pure virtual

Draw a rectangle to the screen.

The rectangle will be colored by the global color (which can be specified by setGlobalColor()).

The rectangle can be rotated around its center by an angle specified in degrees.

Parameters
xX position of the top left corner on the screen in pixels.
yY position of the top left corner on the screen in pixels.
widthWidth in pixels.
heightHeight in pixels.
angleAngle to rotate the rectangle around its center in degrees.

Implemented in StelQGLRenderer.

virtual void StelRenderer::drawText ( const TextParams params)
pure virtual

Draw text with specified parameters.

Parameters are specified by a builder-style struct.

Examples:

// Note that text position and string must be always specified, so they
// are in the constructor.
// Draw with default parameters (no rotation, no shift, no gravity, 2D projection).
renderer->drawText(TextParams(16, 16, "Hello World"));
// Rotate by 30 degrees.
renderer->drawText(TextParams(16, 16 "Hello World!").angleDegrees(30.0f));
// Rotate by 30 degrees and shift by (8, 4) in rotated direction.
renderer->drawText(TextParams(16, 16 "Hello World!").angleDegrees(30.0f).shift(8.0f, 4.0f));
Parameters
paramsParameters of the text to draw.
See Also
TextParams

Implemented in StelQGLRenderer.

virtual void StelRenderer::drawTexturedRect ( const float  x,
const float  y,
const float  width,
const float  height,
const float  angle = 0.0f 
)
pure virtual

Draw a textured rectangle to the screen.

The rectangle will be textured by the currently bound texture.

The rectangle can be rotated around its center by an angle specified in degrees.

Parameters
xX position of the top left corner on the screen in pixels.
yY position of the top left corner on the screen in pixels.
widthWidth in pixels.
heightHeight in pixels.
angleAngle to rotate the rectangle around its center in degrees.

Implemented in StelQGLRenderer.

template<class V >
void StelRenderer::drawVertexBuffer ( StelVertexBuffer< V > *  vertexBuffer,
class StelIndexBuffer indexBuffer = NULL,
StelProjectorP  projector = StelProjectorP(NULL),
bool  dontProject = false 
)
inline

Draw contents of a vertex buffer.

Parameters
vertexBufferVertex buffer to draw.
indexBufferIndex buffer specifying which vertices from the buffer to draw. If NULL, indexing will not be used and vertices will be drawn directly in order they are in the buffer.
projectorProjector to project vertices' positions before drawing. Also determines viewport to draw in. If NULL, no projection will be done and the vertices will be drawn directly.
dontProjectDisable vertex position projection. (Projection matrix and viewport information of the projector are still used) This is a hack to support StelSkyDrawer, which already projects the star positions before drawing them. Avoid using this if possible. StelSkyDrawer might be refactored in future to remove the need for dontProject, in which case it should be removed.
Note
When drawing with a custom StelProjector only 3D vertex positions are supported.

Definition at line 311 of file StelRenderer.hpp.

template<class V >
void StelRenderer::drawVertexBuffer ( StelVertexBuffer< V > *  vertexBuffer,
class StelIndexBuffer indexBuffer,
StelProjector projector,
bool  dontProject = false 
)
inline

Draw contents of a vertex buffer.

This version takes a StelProjector* instead of StelProjectorP - this is not a problem, as the renderer subsystem doesn't store or delete the projector.

Parameters
vertexBufferVertex buffer to draw.
indexBufferIndex buffer specifying which vertices from the buffer to draw. If NULL, indexing will not be used and vertices will be drawn directly in order they are in the buffer.
projectorProjector to project vertices' positions before drawing. Also determines viewport to draw in. If NULL, no projection will be done and the vertices will be drawn directly.
dontProjectDisable vertex position projection. (Projection matrix and viewport information of the projector are still used) This is a hack to support StelSkyDrawer, which already projects the star positions before drawing them. Avoid using this if possible. StelSkyDrawer might be refactored in future to remove the need for dontProject, in which case it should be removed.
Note
When drawing with a custom StelProjector only 3D vertex positions are supported.

Definition at line 344 of file StelRenderer.hpp.

virtual void StelRenderer::drawVertexBufferBackend ( StelVertexBufferBackend vertexBuffer,
class StelIndexBuffer indexBuffer,
StelProjector projector,
const bool  dontProject 
)
protectedpure virtual

Draw contents of a vertex buffer (backend).

Used by drawVertexBuffer.

See Also
drawVertexBuffer

Implemented in StelQGL2Renderer, and StelQGL1Renderer.

virtual StelRendererStatistics& StelRenderer::getStatistics ( )
pure virtual

Access statistics data.

Contents are backend specific - might include thing like vertices per frame, estimated texture memory, etc. .

User code might add its own statistics as well (e.g. StelSkyDrawer).

Implemented in StelQGLRenderer.

virtual QSize StelRenderer::getViewportSize ( ) const
pure virtual

Get size of the viewport in pixels.

Implemented in StelQGLRenderer.

StelTextureNew* StelRenderer::getViewportTexture ( )
inline

Get a texture of the viewport, with everything drawn to the viewport so far.

Note
Since some backends only support textures with power of two dimensions, the returned texture might be larger than the viewport in which case only the part of the texture matching viewport size (returned by getViewportSize) will be taken up by the viewport.
Returns
Viewport texture.

Definition at line 561 of file StelRenderer.hpp.

virtual class StelTextureBackend* StelRenderer::getViewportTextureBackend ( )
protectedpure virtual

Implementation of getViewportTexture.

See Also
getViewportTexture.

Implemented in StelQGLRenderer.

virtual bool StelRenderer::init ( )
pure virtual

Initialize the renderer.

Must be called before any other methods.

Returns
true on success, false if there was an error.

Implemented in StelQGLRenderer, StelQGL2Renderer, and StelQGL1Renderer.

virtual bool StelRenderer::isGLSLSupported ( ) const
pure virtual

Are GLSL shaders supported?

Implemented in StelQGL2Renderer, and StelQGL1Renderer.

virtual void StelRenderer::renderFrame ( StelRenderClient renderClient)
pure virtual

Render a frame.

This might not render the entire frame - if rendering takes too long, the backend may (or may not) suspend the rendering to finish it next time renderFrame is called.

Parameters
renderClientAllows the renderer to draw the scene in parts.
See Also
StelRenderClient

Implemented in StelQGLRenderer.

virtual QImage StelRenderer::screenshot ( )
pure virtual

Take a screenshot and return it.

Implemented in StelQGLRenderer.

virtual void StelRenderer::setBlendMode ( const BlendMode  blendMode)
pure virtual

Set blend mode.

Used to enable/disable transparency and similar effects.

On startup, the blend mode is BlendMode_None.

Implemented in StelQGLRenderer.

virtual void StelRenderer::setCulledFaces ( const CullFace  cullFace)
pure virtual

Set which faces (triangles) should be culled.

Front faces are usually those whose vertices are in counter-clockwise order, but a StelProjector might flip this order after projection. If such a StelProjector is used with StelRenderer::drawVertexBuffer(), front faces will be clock wise. This doesn't affect the user in any way as the projection is done inside renderer.

However, if doing manual projection and sending the already projected vertices for drawing, this order will be flipped, so previously counter-clockwise(front) faces will be clock-wise (back) faces, so if culling is used, opposite face should be used with setCulledFaces().

Whether a StelProjector changes clockwise-counterclockwise winding can be determined by StelProjector::flipFrontBackFace().

Implemented in StelQGLRenderer.

virtual void StelRenderer::setDepthTest ( const DepthTest  test)
pure virtual

Set depth test mode.

Depth test is implemented to be as specific as possible, only supporting what Stellarium needs. This might be counterintuitive, as much of the power of OpenGL is removed. However, this makes it easier to implement different Renderer backends that might not necessarily be based on OpenGL.

Implemented in StelQGLRenderer.

virtual void StelRenderer::setFont ( const QFont &  font)
pure virtual

Set font to use for drawing text.

Implemented in StelQGLRenderer.

virtual void StelRenderer::setGlobalColor ( const Vec4f color)
pure virtual

Set the global vertex color.

Default color is white.

This color is used when rendering vertex formats that have no vertex color attribute, lines, non-textured rectangles, etc. .

Per-vertex color completely overrides this (this is to keep behavior from before the GL refactor unchanged).

Note
Color channel values can be outside of the 0-1 range.

Implemented in StelQGLRenderer.

void StelRenderer::setGlobalColor ( const float  r,
const float  g,
const float  b,
const float  a = 1.0f 
)
inline

setGlobalColor overload specifying color channels directly instead of through Vec4f.

See Also
setGlobalColor

Definition at line 602 of file StelRenderer.hpp.

virtual void StelRenderer::setStencilTest ( const StencilTest  test)
pure virtual

Set stencil test mode.

Stencil test is implemented to be as specific as possible, only supporting what Stellarium needs. This might be counterintuitive, as much of the power of OpenGL is removed. However, this makes it easier to implement different Renderer backends that might not necessarily be based on OpenGL.

Implemented in StelQGLRenderer.

virtual void StelRenderer::swapBuffers ( )
pure virtual

Swap front and back buffers.

This is only needed before the Renderer takes control of frame start/end, e.g. during loading at startup.

Implemented in StelQGLRenderer.

virtual void StelRenderer::viewportHasBeenResized ( const QSize  size)
pure virtual

Must be called once at startup and on every GL viewport resize, specifying new size.

Implemented in StelQGLRenderer.


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