Crazy Eddies GUI System: CEGUI::RenderingSurface Class Reference

Crazy Eddies GUI System 0.7.6

- Main Page
- Related Pages
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

Public Member Functions | Static Public Attributes | Protected Types | Protected Member Functions | Protected Attributes
CEGUI::RenderingSurface Class Reference

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

Inheritance diagram for CEGUI::RenderingSurface:
[legend]
Collaboration diagram for CEGUI::RenderingSurface:
[legend]

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 RenderingWindow & | createRenderingWindow (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 RenderTarget & | getRenderTarget () const
| Return the RenderTarget object that this RenderingSurface is drawing to.
RenderTarget & | getRenderTarget ()
## 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 * > | RenderingWindowList
| collection type for created RenderingWindow objects
## Protected Member Functions
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
RenderTarget & | d_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

CEGUI::RenderingSurface::RenderingSurface | ( | RenderTarget & | target | ) |

Constructor for RenderingSurface objects.

Parameters:

  target | RenderTarget 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:

  queue | One of the RenderQueueID enumerated values indicating which prioritised queue the GeometryBuffer should be added to.
  buffer | GeometryBuffer 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.

void CEGUI::RenderingSurface::clearGeometry | ( |  | ) |

Clears all GeometryBuffers from all rendering queues.

Note:
  Clearing the rendering queues does destory the attached GeometryBuffers, which remain under thier original ownership.

void CEGUI::RenderingSurface::clearGeometry | ( | const RenderQueueID | queue | ) |

Clears all GeometryBuffers from the specified rendering queue.

Parameters:

  queue | One of the RenderQueueID enumerated values indicating which prioritised queue is to to be cleared.

Note:
  Clearing a rendering queue does destory the attached GeometryBuffers, which remain under thier original ownership.

virtual RenderingWindow& CEGUI::RenderingSurface::createRenderingWindow | ( | TextureTarget & | target | ) | `[virtual]`

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:

  target | TextureTarget 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.

virtual void CEGUI::RenderingSurface::destroyRenderingWindow | ( | RenderingWindow & | window | ) | `[virtual]`

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

Parameters:

  window | RenderingWindow 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::RenderingWindow.

const RenderTarget& CEGUI::RenderingSurface::getRenderTarget | ( |  | ) | const

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.

bool CEGUI::RenderingSurface::isInvalidated | ( |  | ) | const

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:
  - true to indicate the RenderingSurface is a RenderingWindow instance.
  - false to indicate the RenderingSurface is not a RenderingWindow.

Reimplemented in CEGUI::RenderingWindow.

void CEGUI::RenderingSurface::removeGeometryBuffer | ( | const RenderQueueID | queue,
|  | const GeometryBuffer & | buffer
| ) |  |

Remove the specified GeometryBuffer from the specified queue.

Parameters:

  queue | One of the RenderQueueID enumerated values indicating which prioritised queue the GeometryBuffer should be removed from.
  buffer | GeometryBuffer object to be removed from the specified rendering queue.

virtual void CEGUI::RenderingSurface::transferRenderingWindow | ( | RenderingWindow & | window | ) | `[virtual]`

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:

  window | RenderingWindow object that this RenderingSurface is to take ownership of.

## Member Data Documentation

const String CEGUI::RenderingSurface::EventRenderQueueEnded`[static]`

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.

const String CEGUI::RenderingSurface::EventRenderQueueStarted`[static]`

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.