Crazy Eddie's GUI System  0.8.7
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:

Public Member Functions

 RenderingSurface (RenderTarget &target)
 Constructor for RenderingSurface objects. More...
 
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. More...
 
void removeGeometryBuffer (const RenderQueueID queue, const GeometryBuffer &buffer)
 Remove the specified GeometryBuffer from the specified queue. More...
 
void clearGeometry (const RenderQueueID queue)
 Clears all GeometryBuffers from the specified rendering queue. More...
 
void clearGeometry ()
 Clears all GeometryBuffers from all rendering queues. More...
 
virtual void draw ()
 Draw the GeometryBuffers for all rendering queues to the RenderTarget that this RenderingSurface is targetting. More...
 
virtual void invalidate ()
 Marks the RenderingSurface as invalid, causing the geometry to be rerendered to the RenderTarget next time draw is called. More...
 
bool isInvalidated () const
 Return whether this RenderingSurface is invalidated. More...
 
virtual bool isRenderingWindow () const
 Return whether this RenderingSurface is actually an instance of the RenderingWindow subclass. More...
 
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. More...
 
virtual void destroyRenderingWindow (RenderingWindow &window)
 Destroy a RenderingWindow we own. If we are not the present owner of the given RenderingWindow, nothing happens. More...
 
virtual void transferRenderingWindow (RenderingWindow &window)
 transfer ownership of the RenderingWindow to this RenderingSurface. More...
 
const RenderTargetgetRenderTarget () const
 Return the RenderTarget object that this RenderingSurface is drawing to. More...
 
RenderTargetgetRenderTarget ()
 
- Public Member Functions inherited from CEGUI::EventSet
 EventSet ()
 Constructor for EventSet objects.
 
virtual ~EventSet (void)
 Destructor for EventSet objects.
 
void addEvent (const String &name)
 Creates a new Event object with the given name and adds it to the EventSet. More...
 
void addEvent (Event &event)
 Adds the given Event object to the EventSet. Ownership of the object passes to EventSet and it will be deleted when it is removed from the EventSet - whether explicitly via removeEvent or when the EventSet is destroyed. More...
 
void removeEvent (const String &name)
 Removes the Event with the given name. All connections to the event are disconnected, and the underlying Event object is destroyed. More...
 
void removeEvent (Event &event)
 Removes the given event from the EventSet. All connections to the event are disconnected, and the event object is destroyed. More...
 
void removeAllEvents (void)
 Remove all Event objects from the EventSet. Add connections will be disconnected, and all Event objects destroyed.
 
bool isEventPresent (const String &name)
 Checks to see if an Event with the given name is present in this EventSet. More...
 
virtual Event::Connection subscribeEvent (const String &name, Event::Subscriber subscriber)
 Subscribes a handler to the named Event. If the named Event is not yet present in the EventSet, it is created and added. More...
 
virtual Event::Connection subscribeEvent (const String &name, Event::Group group, Event::Subscriber subscriber)
 Subscribes a handler to the specified group of the named Event. If the named Event is not yet present in the EventSet, it is created and added. More...
 
template<typename Arg1 , typename Arg2 >
Event::Connection subscribeEvent (const String &name, Arg1 arg1, Arg2 arg2)
 Subscribes a handler to the named Event. If the named Event is not yet present in the EventSet, it is created and added. More...
 
template<typename Arg1 , typename Arg2 >
Event::Connection subscribeEvent (const String &name, Event::Group group, Arg1 arg1, Arg2 arg2)
 Subscribes a handler to the named Event. If the named Event is not yet present in the EventSet, it is created and added. More...
 
virtual Event::Connection subscribeScriptedEvent (const String &name, const String &subscriber_name)
 Subscribes the named Event to a scripted funtion. More...
 
virtual Event::Connection subscribeScriptedEvent (const String &name, Event::Group group, const String &subscriber_name)
 Subscribes the specified group of the named Event to a scripted funtion. More...
 
virtual void fireEvent (const String &name, EventArgs &args, const String &eventNamespace="")
 Fires the named event passing the given EventArgs object. More...
 
bool isMuted (void) const
 Return whether the EventSet is muted or not. More...
 
void setMutedState (bool setting)
 Set the mute state for this EventSet. More...
 
EventgetEventObject (const String &name, bool autoAdd=false)
 Return a pointer to the Event object with the given name, optionally adding such an Event object to the EventSet if it does not already exist. More...
 
EventIterator getEventIterator (void) const
 Return a EventSet::EventIterator object to iterate over the events currently added to the EventSet.
 

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, RenderQueueRenderQueueList
 collection type for the queues
 
typedef std::vector< RenderingWindow *CEGUI_VECTOR_ALLOC(RenderingWindow *)> RenderingWindowList
 collection type for created RenderingWindow objects
 
- Protected Types inherited from CEGUI::EventSet
typedef std::map< String, Event *, StringFastLessCompare CEGUI_MAP_ALLOC(String, Event *)> EventMap
 

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 Member Functions inherited from CEGUI::EventSet
void fireEvent_impl (const String &name, EventArgs &args)
 Implementation event firing member.
 
ScriptModulegetScriptModule () const
 Helper to return the script module pointer or throw.
 
 EventSet (EventSet &)
 
 EventSet (const EventSet &)
 
EventSetoperator= (EventSet &)
 
EventSetoperator= (const EventSet &)
 

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)
 
- Protected Attributes inherited from CEGUI::EventSet
EventMap d_events
 
bool d_muted
 true if events for this EventSet have been muted.
 

Additional Inherited Members

- Public Types inherited from CEGUI::EventSet
typedef ConstMapIterator< EventMap > EventIterator
 

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
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.
void CEGUI::RenderingSurface::clearGeometry ( const RenderQueueID  queue)

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.
void CEGUI::RenderingSurface::clearGeometry ( )

Clears all GeometryBuffers from all rendering queues.

Note
Clearing the rendering queues does not destroy the attached GeometryBuffers, which remain under their 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
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.
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
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 ( )
protectedvirtual

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

Reimplemented in CEGUI::GUIContext.

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

Reimplemented in CEGUI::RenderingWindow.

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

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.
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
windowRenderingWindow 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.