OpenGUI::Renderer Class Reference

#include <OpenGUI_Renderer.h>

Detailed Description

Base class for all renderers. Any custom Renderer should inherit this base class.

Rendering call order

Here's a quick ordered list of what calls you can usually expect to receive during rendering loops.

        - preRenderSetup()
        - selectRenderContext()
                - clearContents()
                - doRenderOperation() (repeats as necessary)
        - selectRenderContext()
                - clearContents()
                - doRenderOperation() (repeats as necessary)
        - postRenderCleanup()

Note:: Renderers are singletons, but do not require any special action on the part of implementors. The singleton logic is automatically handled, so all you need to worry about is getting your implementation working.

Public Member Functions

Renderer ()

Constructor.

virtual ~Renderer ()

virtual Destructor

Required

virtual void selectViewport (Viewport *activeViewport)=0

This is called to tell the Renderer to change the active Viewport to the one provided.

virtual void preRenderSetup ()=0

This is always called by the System exactly once every frame before the calls to doRenderOperation() begin for a Viewport.

virtual void doRenderOperation (RenderOperation &renderOp)=0

This will be called for every render operation that needs to be performed.

virtual void postRenderCleanup ()=0

This is always called by the System exactly once every frame after all of the calls to doRenderOperation() have been completed for a Viewport.

virtual Texture * createTextureFromFile (const String &filename)=0

This is called whenever a texture needs to be created from a file.

virtual Texture * createTextureFromTextureData (const TextureData *textureData)=0

Create a texture from a TextureData object (memory).

virtual void updateTextureFromTextureData (Texture *texture, const TextureData *textureData)=0

Replaces an existing texture with the given TextureData.

virtual void destroyTexture (Texture *texturePtr)=0

Destroy a previously created Texture object.

RenderToTexture Support (optional)

virtual bool supportsRenderToTexture ()

Renderer implementations that do support Render to Texture contexts should return true. The default is to return false.

virtual void selectRenderContext (RenderTexture *context)

This is called to set the current rendering context.

virtual void clearContents ()

Should clear the contents of the current rendering context as appropriate.

virtual RenderTexture * createRenderTexture (const IVector2 &size)

Creates a render texture at the given size.

virtual void destroyRenderTexture (RenderTexture *texturePtr)

Destroy a previously created RenderTexture object.

Static Public Member Functions

static Renderer & getSingleton (void)

Retrieve the current singleton, if one exists. If none exists, this will cause an error.

static Renderer * getSingletonPtr (void)

Retrieve a pointer to the current singleton, if one exists. If none exists, this will return 0.

Constructor & Destructor Documentation

OpenGUI::Renderer::Renderer ( ) [inline]

Constructor.

virtual OpenGUI::Renderer::~Renderer ( ) [inline, virtual]

virtual Destructor

Member Function Documentation

virtual void OpenGUI::Renderer::clearContents ( ) [inline, virtual]

Should clear the contents of the current rendering context as appropriate.
When called, this function should clear the contents of the current rendering context.

Attention:
This virtual function has a default implementation. This allows renderer implementations that do not support render to texture to simply ignore the existence of this function and the correct functionality will take place.

RenderTexture * OpenGUI::Renderer::createRenderTexture ( const IVector2 & size ) [virtual]

Creates a render texture at the given size.
If your renderer implementation supports render to texture, this is where those render textures will be created.
The given size will be a desired size that is not necessarily a power of 2. If the renderer does not support non power of 2 textures, it is up to the Renderer implementation to increase the texture size to a power of 2, and perform any UV remapping necessary to provide proper texel alignment when rendering to and from the texture.

Note:
It is expected that all render textures are available for use by all other rendering contexts. In other words, it must be usable in render operations for every context, only excluding itself.

Attention:
This virtual function has a default implementation. This allows renderer implementations that do not support render to texture to simply ignore the existence of this function and the correct functionality will take place.

virtual Texture* OpenGUI::Renderer::createTextureFromFile ( const String & filename ) [pure virtual]

This is called whenever a texture needs to be created from a file.
Custom renderers are required to implement this function to provide the system a generalized method of creating a texture. Basically, this function is given a file name, and through any amount of smoke and magic, the system expects to receive back a pointer to a Texture object that can be later referenced within RenderOperation objects that are passed to doRenderOperation(). Most implementations simply load the data as necessary for their graphics API and store their graphics API specific texture handles in customized Texture objects.
The short explanation is: Texture objects are almost entirely for Renderer use only, and as such you can do nearly whatever you want with them, so long as they can be used later to signify which texture we want drawn on a set of polygons.

Parameters:

filename The filename of the source image data.

Returns:
A TexturePtr to a Texture object on success, or TexturePtr(0) on fail.

Note:
It is expected that all textures are available for use by all rendering contexts.

virtual Texture* OpenGUI::Renderer::createTextureFromTextureData ( const TextureData * textureData ) [pure virtual]

Create a texture from a TextureData object (memory).
The passed in TextureData object does not become the sole property of the createTextureFromTextureData() function. So it must not attempt to delete it. It is the responsibility of the TextureData creator to clean up the TextureData object when it is no longer needed. The caller must guarantee that the given TextureData object is valid for the entire lifetime of the texture. Meaning that it cannot be deleted until after destroyTexture() has been called to destroy the texture that is based upon the TextureData.

Note:
It is expected that all textures are available for use by all rendering contexts.

void OpenGUI::Renderer::destroyRenderTexture ( RenderTexture * texturePtr ) [virtual]

Destroy a previously created RenderTexture object.
Whatever needs to happen to properly destroy a RenderTexture object, custom Renderers need to implement that functionality here.

Note:
This function is called automatically by the TextureManager to destroy RenderTexture objects. Since the Renderer created the Texture object (via new), it is also responsible for performing the delete of that RenderTexture. This function is called after OpenGUI is assured that no remaining handles to the texture remain, so if the Renderer does not delete the memory here, it will leak.

Attention:
This virtual function has a default implementation. This allows renderer implementations that do not support render to texture to simply ignore the existence of this function and the correct functionality will take place.

virtual void OpenGUI::Renderer::destroyTexture ( Texture * texturePtr ) [pure virtual]

Destroy a previously created Texture object.
Whatever needs to happen to properly destroy a Texture object, custom Renderers need to implement that functionality here.

Note:
This function is called automatically by the TextureManager to destroy Texture objects. Since the Renderer created the Texture object (via new), it is also responsible for performing the delete of that Texture. This function is called after OpenGUI is assured that no remaining handles to the texture remain, so if the Renderer does not delete the memory here, it will leak.

virtual void OpenGUI::Renderer::doRenderOperation ( RenderOperation & renderOp ) [pure virtual]

This will be called for every render operation that needs to be performed.
This function is passed a RenderOperation object, by reference, for every render operation that needs to take place to properly draw the gui.
For any given render context, the RenderOperations passed to this object will always assume that 0,0 x 1,1 is the full range of the render target. 0,0 being the upper left, and 1,1 being the lower right.
Texture UVs are always expressed as values between 0.0 and 1.0. Texture::getUVs() is not currently used within OpenGUI.
The render operations provided to this function are guaranteed to be:

Ordered back to front (painter's algorithm).
Necessary: all 100% alpha'ed out operations will not make it this far. (Don't bother to validate the data, it has been done for you already)
Fully populated as the RenderOperation documentation requires.

Note:
Expect this function to be called a LOT. Keep it small, keep it fast.

Renderer & OpenGUI::Renderer::getSingleton ( void ) [static]

Retrieve the current singleton, if one exists. If none exists, this will cause an error.

Renderer * OpenGUI::Renderer::getSingletonPtr ( void ) [static]

Retrieve a pointer to the current singleton, if one exists. If none exists, this will return 0.

virtual void OpenGUI::Renderer::postRenderCleanup ( ) [pure virtual]

This is always called by the System exactly once every frame after all of the calls to doRenderOperation() have been completed for a Viewport.
Much like preRenderSetup(), this gives the renderer an opportunity to perform whatever tasks it feels are necessary to return the render system back to a usable state for the application.

virtual void OpenGUI::Renderer::preRenderSetup ( ) [pure virtual]

This is always called by the System exactly once every frame before the calls to doRenderOperation() begin for a Viewport.
The primary purpose of this is to provide the renderer an opportunity to configure the projection matrix as it feels necessary, as well as set any graphics API options that will be used on all (or most) render operations.
It is guaranteed that this function will be called before the usage of any Viewport.

virtual void OpenGUI::Renderer::selectRenderContext ( RenderTexture * context ) [inline, virtual]

This is called to set the current rendering context.
Calls to doRenderOperation() that occur after this function is called should draw to the RenderTexture that was last sent via this function.

Attention:
This virtual function has a default implementation. This allows renderer implementations that do not support render to texture to simply ignore the existence of this function and the correct functionality will take place.

Parameters:

context A pointer to the render texture that is to become the new context, or 0 (NULL) to set the context to the default context (current Viewport) as was previously selected by selectViewport()

Note:
This is not guaranteed to be called every frame. It is only called when a context change is absolutely necessary.

virtual void OpenGUI::Renderer::selectViewport ( Viewport * activeViewport ) [pure virtual]

This is called to tell the Renderer to change the active Viewport to the one provided.
This function will never occur between a preRenderSetup()/postRenderCleanup() combination.

bool OpenGUI::Renderer::supportsRenderToTexture ( ) [virtual]

Renderer implementations that do support Render to Texture contexts should return true. The default is to return false.

Attention:
This virtual function has a default implementation. This allows renderer implementations that do not support render to texture to simply ignore the existence of this function and the correct functionality will take place.

virtual void OpenGUI::Renderer::updateTextureFromTextureData ( Texture * texture,

const TextureData * textureData

) [pure virtual]

Replaces an existing texture with the given TextureData.
This should cause a Renderer implementation to completely replace the contents of a texture with the newly provided data. The given texture pointer must remain valid, but other than that it doesn't matter how this is achieved internally. Renderer implementations can feel free to discard their hardware textures and rebuild from scratch if they choose.

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

OpenGUI_Renderer.h
OpenGUI_Renderer.cpp


Public Member Functions
	Renderer ()
	Constructor.
virtual	~Renderer ()
	virtual Destructor
Required
virtual void	selectViewport (Viewport *activeViewport)=0
	This is called to tell the Renderer to change the active Viewport to the one provided.
virtual void	preRenderSetup ()=0
	This is always called by the System exactly once every frame before the calls to doRenderOperation() begin for a Viewport.
virtual void	doRenderOperation (RenderOperation &renderOp)=0
	This will be called for every render operation that needs to be performed.
virtual void	postRenderCleanup ()=0
	This is always called by the System exactly once every frame after all of the calls to doRenderOperation() have been completed for a Viewport.
virtual Texture *	createTextureFromFile (const String &filename)=0
	This is called whenever a texture needs to be created from a file.
virtual Texture *	createTextureFromTextureData (const TextureData *textureData)=0
	Create a texture from a TextureData object (memory).
virtual void	updateTextureFromTextureData (Texture texture, const TextureData textureData)=0
	Replaces an existing texture with the given TextureData.
virtual void	destroyTexture (Texture *texturePtr)=0
	Destroy a previously created Texture object.
RenderToTexture Support (optional)
virtual bool	supportsRenderToTexture ()
	Renderer implementations that do support Render to Texture contexts should return `true`. The default is to return `false`.
virtual void	selectRenderContext (RenderTexture *context)
	This is called to set the current rendering context.
virtual void	clearContents ()
	Should clear the contents of the current rendering context as appropriate.
virtual RenderTexture *	createRenderTexture (const IVector2 &size)
	Creates a render texture at the given size.
virtual void	destroyRenderTexture (RenderTexture *texturePtr)
	Destroy a previously created RenderTexture object.
Static Public Member Functions
static Renderer &	getSingleton (void)
	Retrieve the current singleton, if one exists. If none exists, this will cause an error.
static Renderer *	getSingletonPtr (void)
	Retrieve a pointer to the current singleton, if one exists. If none exists, this will return 0.