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 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. 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 RenderTarget &	getRenderTarget () const
	Return the RenderTarget object that this RenderingSurface is drawing to. More...

RenderTarget &	getRenderTarget ()

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

Event *	getEventObject (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, RenderQueue >	RenderQueueList
	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.

ScriptModule *	getScriptModule () const
	Helper to return the script module pointer or throw.

	EventSet (EventSet &)

EventSet &	operator= (EventSet &)

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)

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

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 ( 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 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

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

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 \e 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.

Public Member Functions

Static Public Attributes

Protected Types

Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation