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 StelIndexBuffer *	createIndexBuffer (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...

StelTextureNew *	createTexture (const QString &filename, const TextureParams &params=TextureParams(), const TextureLoadingMode loadingMode=TextureLoadingMode_Normal)
	Create a texture from specified file or URL. More...

StelTextureNew *	createTexture (QImage &image, const TextureParams &params=TextureParams())
	Create a texture from an image. More...

StelTextureNew *	createTexture (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...

StelTextureNew *	getViewportTexture ()
	Get a texture of the viewport, with everything drawn to the viewport so far. More...

virtual StelGLSLShader *	createGLSLShader ()
	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 StelRendererStatistics &	getStatistics ()=0
	Access statistics data. More...

Protected Member Functions
virtual StelVertexBufferBackend *	createVertexBufferBackend (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 StelTextureBackend *	createTextureBackend (const QString &filename, const TextureParams &params, const TextureLoadingMode loadingMode)=0
	Implementation of createTexture. More...

virtual class StelTextureBackend *	createTextureBackend (QImage &image, const TextureParams &params)=0
	Implementation of createTexture loading from image. More...

virtual class StelTextureBackend *	createTextureBackend (const void *data, const QSize size, const TextureDataFormat format, const TextureParams &params)=0
	Implementation of createTexture loading from raw data. More...

virtual class StelTextureBackend *	getViewportTextureBackend ()=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

textureBackend	Texture to bind.
textureUnit	Texture 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

filename	File 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.
params	Texture parameters, such as filtering, wrapping, etc.
loadingMode	Texture 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

image	Image to load the texture from.
params	Texture 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

data	Pointer 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.
size	Size of the texture in pixels.
format	Format of pixels in data.
params	Texture 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

V	Vertex type. See the example in StelVertexBuffer documentation on how to define a vertex type.

Parameters

primitiveType Graphics 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

primitiveType	Graphics primitive type stored in the buffer.
attributes	Descriptions 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

startX	X position of the starting point of the line in pixels.
startY	Y position of the starting point of the line in pixels.
endX	X position of the ending point of the line in pixels.
endY	Y 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

x	X position of the top left corner on the screen in pixels.
y	Y position of the top left corner on the screen in pixels.
width	Width in pixels.
height	Height in pixels.
angle	Angle 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

params Parameters 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

x	X position of the top left corner on the screen in pixels.
y	Y position of the top left corner on the screen in pixels.
width	Width in pixels.
height	Height in pixels.
angle	Angle 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

vertexBuffer	Vertex buffer to draw.
indexBuffer	Index 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.
projector	Projector 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.
dontProject	Disable 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

vertexBuffer	Vertex buffer to draw.
indexBuffer	Index 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.
projector	Projector 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.
dontProject	Disable 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

renderClient Allows 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:

core/renderer/StelRenderer.hpp

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation