Crazy Eddie's GUI System  0.8.4
CEGUI::RenderingSurface Class Reference

Class that represents a surface that can have geometry based imagery drawn to it. More...

Inherits CEGUI::EventSet, and CEGUI::AllocatedObject< RenderingSurface >.

Inherited by CEGUI::GUIContext, and CEGUI::RenderingWindow.

+ Collaboration diagram for CEGUI::RenderingSurface:

List of all members.

Public Member Functions

 RenderingSurface (RenderTarget &target)
 Constructor for RenderingSurface objects.
virtual ~RenderingSurface ()
 Destructor for RenderingSurface objects.
void addGeometryBuffer (const RenderQueueID queue, const GeometryBuffer &buffer)
 Add the specified GeometryBuffer to the specified queue for rendering when the RenderingSurface is drawn.
void removeGeometryBuffer (const RenderQueueID queue, const GeometryBuffer &buffer)
 Remove the specified GeometryBuffer from the specified queue.
void clearGeometry (const RenderQueueID queue)
 Clears all GeometryBuffers from the specified rendering queue.
void clearGeometry ()
 Clears all GeometryBuffers from all rendering queues.
virtual void draw ()
 Draw the GeometryBuffers for all rendering queues to the RenderTarget that this RenderingSurface is targetting.
virtual void invalidate ()
 Marks the RenderingSurface as invalid, causing the geometry to be rerendered to the RenderTarget next time draw is called.
bool isInvalidated () const
 Return whether this RenderingSurface is invalidated.
virtual bool isRenderingWindow () const
 Return whether this RenderingSurface is actually an instance of the RenderingWindow subclass.
virtual RenderingWindowcreateRenderingWindow (TextureTarget &target)
 Create and return a reference to a child RenderingWindow object that will render back onto this RenderingSurface when it's draw member function is called.
virtual void destroyRenderingWindow (RenderingWindow &window)
 Destroy a RenderingWindow we own. If we are not the present owner of the given RenderingWindow, nothing happens.
virtual void transferRenderingWindow (RenderingWindow &window)
 transfer ownership of the RenderingWindow to this RenderingSurface.
const RenderTargetgetRenderTarget () const
 Return the RenderTarget object that this RenderingSurface is drawing to.
RenderTargetgetRenderTarget ()

Static Public Attributes

static const String EventNamespace
 Namespace for global events from RenderingSurface objects.
static const String EventRenderQueueStarted
static const String EventRenderQueueEnded

Protected Types

typedef std::map
< RenderQueueID, RenderQueue
RenderQueueList
 collection type for the queues
typedef std::vector
< RenderingWindow
*CEGUI_VECTOR_ALLOC(RenderingWindow *) 
RenderingWindowList )
 collection type for created RenderingWindow objects

Protected Member Functions

virtual void drawContent ()
void draw (const RenderQueue &queue, RenderQueueEventArgs &args)
 draw a rendering queue, firing events before and after.
void detatchWindow (RenderingWindow &w)
 detatch ReneringWindow from this RenderingSurface
void attachWindow (RenderingWindow &w)
 attach ReneringWindow from this RenderingSurface

Protected Attributes

RenderQueueList d_queues
 the collection of RenderQueue objects.
RenderingWindowList d_windows
 collection of RenderingWindow object we own
RenderTargetd_target
 RenderTarget that this surface actually draws to.
bool d_invalidated
 holds invalidated state of target (as far as we are concerned)

Detailed Description

Class that represents a surface that can have geometry based imagery drawn to it.

A RenderingSurface has a number of queues that can be used for rendering; normal window rendering will typically be done on RQ_BASE queue, things that are overlaid everything else are rendered to RQ_OVERLAY.

The event EventRenderQueueStarted is fired before each queue is rendered and the event EventRenderQueueEnded is fired after each queue is rendered.
Note:
For performance reasons, events are only fired for queues that are in use; these are queues that have had some interaction - such as clearing or adding geometry.

Constructor & Destructor Documentation

Constructor for RenderingSurface objects.

Parameters:
targetRenderTarget object that will receive rendered output from the RenderingSurface being created.
Note:
The RenderingSurface does not take ownership of target. When the RenderingSurface is finally destroyed, the RenderTarget will not have been destroyed, and it should be destoyed by whover created it, if that is desired. One reason for this is that there is not an exclusive one to one mapping from RenderingSurface to RenderTarget objects; it's entirely feasable that multiple RenderingSurface objects could be targetting a shared RenderTarget).

Member Function Documentation

void CEGUI::RenderingSurface::addGeometryBuffer ( const RenderQueueID  queue,
const GeometryBuffer buffer 
)

Add the specified GeometryBuffer to the specified queue for rendering when the RenderingSurface is drawn.

Parameters:
queueOne of the RenderQueueID enumerated values indicating which prioritised queue the GeometryBuffer should be added to.
bufferGeometryBuffer object to be added to the specified rendering queue.
Note:
The RenderingSurface does not take ownership of the GeometryBuffer, and does not destroy it when the RenderingSurface geometry is cleared. Rather, the RenderingSurface is just maintaining a list of thigs to be drawn; the actual GeometryBuffers can be re-used by whichever object does own them, and even changed or updated while still "attached" to a RenderingSurface.

Clears all GeometryBuffers from the specified rendering queue.

Parameters:
queueOne of the RenderQueueID enumerated values indicating which prioritised queue is to to be cleared.
Note:
Clearing a rendering queue does not destroy the attached GeometryBuffers, which remain under thier original ownership.

Clears all GeometryBuffers from all rendering queues.

Note:
Clearing the rendering queues does not destroy the attached GeometryBuffers, which remain under their original ownership.

Create and return a reference to a child RenderingWindow object that will render back onto this RenderingSurface when it's draw member function is called.

The RenderingWindow returned is initially owned by the RenderingSurface that created it.

Parameters:
targetTextureTarget object that will receive rendered output from the RenderingWindow being creatd.
Returns:
Reference to a RenderingWindow object.
Note:
Since RenderingWindow is a RenderingSurface, the same note from the constructor applies here, and that is the passed in TextureTarget remains under the ownership of whichever part of the system created it.

Destroy a RenderingWindow we own. If we are not the present owner of the given RenderingWindow, nothing happens.

Parameters:
windowRenderingWindow object that is to be destroyed.
Note:
Destroying a RenderingWindow will not also destroy the TextureTarget that was given when the RenderingWindow was created. The TextureTarget should be destoyed elsewhere.
virtual void CEGUI::RenderingSurface::draw ( ) [virtual]

Draw the GeometryBuffers for all rendering queues to the RenderTarget that this RenderingSurface is targetting.

The GeometryBuffers remain in the rendering queues after the draw operation is complete. This allows the next draw operation to occur without needing to requeue all the GeometryBuffers (if for instance the sequence of buffers to be drawn remains unchanged).

Reimplemented in CEGUI::GUIContext, and CEGUI::RenderingWindow.

virtual void CEGUI::RenderingSurface::drawContent ( ) [protected, virtual]

draw the surface content. Default impl draws the render queues. NB: Called between RenderTarget activate and deactivate calls.

Reimplemented in CEGUI::GUIContext.

Return the RenderTarget object that this RenderingSurface is drawing to.

Returns:
RenderTarget object that the RenderingSurface is using to draw it's output.
virtual void CEGUI::RenderingSurface::invalidate ( ) [virtual]

Marks the RenderingSurface as invalid, causing the geometry to be rerendered to the RenderTarget next time draw is called.

Note that some surface types can never be in a 'valid' state and so rerendering occurs whenever draw is called. This function mainly exists as a means to hint to other surface types - those that physically cache the rendered output - that geometry content has changed and the cached imagery should be cleared and redrawn.

Reimplemented in CEGUI::RenderingWindow.

Return whether this RenderingSurface is invalidated.

Returns:
  • true to indicate the RenderingSurface is invalidated and will be rerendered the next time the draw member function is called.
  • false to indicate the RenderingSurface is valid, and will not be rerendered the next time the draw member function is called, since it's cached imagery is up-to-date.

Note that some surface types can never be in a 'valid' state and so will always return true.

virtual bool CEGUI::RenderingSurface::isRenderingWindow ( ) const [virtual]

Return whether this RenderingSurface is actually an instance of the RenderingWindow subclass.

Returns:

Reimplemented in CEGUI::RenderingWindow.

Remove the specified GeometryBuffer from the specified queue.

Parameters:
queueOne of the RenderQueueID enumerated values indicating which prioritised queue the GeometryBuffer should be removed from.
bufferGeometryBuffer object to be removed from the specified rendering queue.

transfer ownership of the RenderingWindow to this RenderingSurface.

Transfer ownership of the given RenderingWindow to this RenderingSurface. The result is generally the same as if this RenderingSurface had created the RenderingWindow in the first place.

Parameters:
windowRenderingWindow object that this RenderingSurface is to take ownership of.

Member Data Documentation

Event fired when rendering of a RenderQueue completes for the RenderingSurface. Handlers are passed a const RenderQueueEventArgs reference with RenderQueueEventArgs::queueID set to one of the RenderQueueID enumerated values indicating the queue that has completed rendering.

Event fired when rendering of a RenderQueue begins for the RenderingSurface. Handlers are passed a const RenderQueueEventArgs reference with RenderQueueEventArgs::queueID set to one of the RenderQueueID enumerated values indicating the queue that is about to start rendering.

 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends