TSLAcceleratedMTRenderControl Class Reference

Inheritance diagram for TSLAcceleratedMTRenderControl:

Detailed Description

This class provides a simple multi-threaded Render Control.

The user must be careful to ensure that data is loaded into a layer before the layer is added to the drawing surface.

Layers which are double buffered are added to the background thread. Because of this these layers should only be modified when this control's stop Thread() method as been called.

Adding, removing and modifying layers should only occur when the background thread has been stopped.

Do not share map datalayers between Accelerated Surfaces or surfaces which have a multi-threaded loader.

Do not share layers which are dynamic between Accelerated Surfaces.

When the thread starts the priority of the thread is set to TSLPriorityMTBelow.

The default implementations are for:

• Windows.
• Linux NativeThreads (pthreads) on X11 targets.
• pthreads on VxWorks

Multi-Thread Guidelines

Introducing multi-threading complicates matters as MapLink is not completely thread safe.

A few simple rules need to be followed to use MapLink in a threaded environment.

• Do not share Map Datalayers between threads.
• Do not share Map Datalayers between Accelerated Drawing Surfaces when using the Multithreaded Render Control.

The control's stopThread() method should be called before doing any of the following:

• Loading Configuration files.
• Loading Map data.
• Adding or Removing a Datalayer from any Drawing Surface.
• Deleting a Drawing Surface or Datalayer.
• Loading and adding CoordinateSystems and CoordinateSystem registries.
• Terrain can not be used in multiple threads as the Cache is static and not protected.
• Don't setup a Persistent cache with shared layers.
• Querying a coordinate system or registry while loading or adding in another thread is not thread safe.
• Seamless Layer Manager etc are not thread safe on X11 targets (Datalayer should be).
• Don't shared Display connections between threads on X11. Resources are keyed on the Display.

When using a multi-threaded renderer you must not use the following classes and methods:

• TSLFileLoaderMT
• TSLFileLoaderRemote
• TSLMapDataLayer::configurePersistentCache(...)

Implementation Limitations:

VxWorks default stack size may be insufficient.

X11 requires two independent connections to the X-Server. One for the TSLAcceleratedSurface and one for this thread.

Public Member Functions
	TSLAcceleratedMTRenderControl (bool loadTileInThread=false, bool createDisplayListInThread=false, TSLAcceleratedRedrawCallback redrawCallback=NULL, void *redrawArg=NULL, TSLTextureTileRenderedCallback tileRenderedCallback=NULL, void *tileRenderedArg=NULL, size_t stackSize=0)
virtual	~TSLAcceleratedMTRenderControl ()
TSLPriorityEnum	getPriority () const
virtual bool	isThreaded () const
virtual void	renderTile (TSLTextureTile *tile, TSLAcceleratedRenderer *renderer)
bool	resumeThread ()
virtual void	returnObject (void *object, TSLAcceleratedRenderer *renderer)
void	setPriority (TSLPriorityEnum priority)
int	startThread ()
bool	stopThread ()
Public Member Functions inherited from TSLAcceleratedRenderControl
virtual	~TSLAcceleratedRenderControl ()
TSLAcceleratedRenderer *	getRenderer ()

Additional Inherited Members
Protected Member Functions inherited from TSLAcceleratedRenderControl
	TSLAcceleratedRenderControl (TSLAcceleratedRedrawCallback redrawCallback=NULL, void *redrawArg=NULL, TSLTextureTileRenderedCallback tileRenderedCallback=NULL, void *tileRenderedArg=NULL)
void	callTileRenderedCallback (int numberLeft=0)
void	callRedrawCallback ()

Constructor & Destructor Documentation

TSLAcceleratedMTRenderControl()

TSLAcceleratedMTRenderControl::TSLAcceleratedMTRenderControl	(	bool	loadTileInThread = false,
		bool	createDisplayListInThread = false,
		TSLAcceleratedRedrawCallback	redrawCallback = NULL,
		void *	redrawArg = NULL,
		TSLTextureTileRenderedCallback	tileRenderedCallback = NULL,
		void *	tileRenderedArg = NULL,
		size_t	stackSize = 0 )

This class implements a simple multi-threaded render control.

Parameters

loadTileInThread	Set to true if the tile is to be loaded to graphics memory in the context of the background thread. This may not work on all cards.
createDisplayListInThread	If loadTileInThread is true and works, then this option will be used. This indicates that the tile should be compiled into a display list.
redrawCallback	The method to call when a redraw of the display is required.
redrawArg	User provided argument to be passed to redrawCallback.
tileRenderedCallback	The method to be called when a tile has been loaded. Can be used to cause a redraw of the display.
tileRenderedArg	User provided argument to be passed to tileRendered Callback.
stackSize	define the stack size of the thread (only relevant for X11 targets)
Limitations
X11	requires shared pixmaps. Only 16 bit visual is supported.
VxWorks	requires application to be built in a particular way (see Release Notes).

Creating a display list in the background thread context may not improve performance for all graphics cards.

Loading a tile into the graphics memory in the background thread context may not work on all graphics cards.

~TSLAcceleratedMTRenderControl()

virtual TSLAcceleratedMTRenderControl::~TSLAcceleratedMTRenderControl ( )

virtual

Destroys the thread.

Member Function Documentation

getPriority()

TSLPriorityEnum TSLAcceleratedMTRenderControl::getPriority

(

)

const

Returns the thread priority.

isThreaded()

virtual bool TSLAcceleratedMTRenderControl::isThreaded ( ) const

virtual

This method returns true if the Render Control is multi-threaded.

Implements TSLAcceleratedRenderControl.

renderTile()

virtual void TSLAcceleratedMTRenderControl::renderTile ( TSLTextureTile * tile, TSLAcceleratedRenderer * renderer )

virtual

This method is called by the Accelerated Surface to render a tile.

The method adds the tile to an internal queue and wakes the render thread.

The method does not wait for the tile to be rendered.

This method should not be called by any user code.

Implements TSLAcceleratedRenderControl.

resumeThread()

bool TSLAcceleratedMTRenderControl::resumeThread

(

)

Resumes the thread execution.

Any pan/zooms that have occurred while the background render thread is suspended will be processed on resumeThread() being called.

Note: For the thread to be terminated on exit the thread should be running.

Returns true if successful. False if the thread has not been stopped, started or has/is terminating.

returnObject()

virtual void TSLAcceleratedMTRenderControl::returnObject ( void * object, TSLAcceleratedRenderer * renderer )

virtual

This method is called by the Accelerated Surface to return an object to the Render Control cache.

This method should not be called by any user code.

Implements TSLAcceleratedRenderControl.

setPriority()

void TSLAcceleratedMTRenderControl::setPriority

(

TSLPriorityEnum

priority

)

Sets the thread priority.

Parameters

priority

the required priority

startThread()

int TSLAcceleratedMTRenderControl::startThread

(

)

Starts the thread.

If you subsequently stop the thread call resumeThread to restart the thread.

stopThread()

bool TSLAcceleratedMTRenderControl::stopThread

(

)

Stops the thread from running.

Call resumeThread() to continue.

Any pan/zooms that have occurred while the background render thread is suspended will be processed on resumeThread() being called.

The principle purpose of this method is to help with calling methods in Map Link which are not multithreaded safe.

Returns true if successful.

Returns false if the thread has been stopped or has not been started or has/is terminating.

False may be returned if the synchronisation process failed.