TSLAcceleratorConfiguration Class Reference

Detailed Description

This structure allows the user to configure the Accelerated Surface tile strategy, OpenGL/DirectX texture filtering and drawing options.

The number of tiles required in the x and y axis directions is very dependent on the size of the displayed area (in pixels) and the size of the tiles.

If a Dynamic Arc map is loaded and the Dynamic Arc flag is set on the Drawing Surface the number of tiles in the X direction should be increased.

In addition Graphics Card hardware and the OpenGL/DirectX implementation may impose limitations on the size of the texture tiles and number of textures.

On calling setConfiguration on the Drawing Surface a redraw of the surface should be carried out as the map tiles may have been invalidated.

The constructor for this class sets the variables to sensible defaults. It is however advisable to query the settings before changing as you may disable settings you would not want to disable (work arounds for particular graphics cards).

Public Member Functions
	TSLAcceleratorConfiguration ()
void	atiGDIRenderBug (const bool state)
bool	atiGDIRenderBug () const
void	dynamicArcTolerance (const double percentage)
double	dynamicArcTolerance () const
bool	immediateDraw ()
void	immediateDraw (bool enable)
bool	keepMapTilesUntilReplaced ()
void	keepMapTilesUntilReplaced (bool keep)
void	numberTilesX (const int numX)
void	numberTilesY (const int numY)
int	numberTilesX () const
int	numberTilesY () const
bool	swapBuffers () const
void	swapBuffers (bool swap_buffers)
void	textureFilterNearest (bool nearest)
bool	textureFilterNearest () const
void	textureBorder (bool border)
bool	textureBorder () const
int	tileSize () const
void	tileSize (const int pixels)
void	viewExpansion (double percent)
double	viewExpansion () const

Constructor & Destructor Documentation

TSLAcceleratorConfiguration()

TSLAcceleratorConfiguration::TSLAcceleratorConfiguration ( )

inline

Constructor.

Sets the defaults.

Class TSLAcceleratorConfiguration

Member Function Documentation

atiGDIRenderBug() [1/2]

bool TSLAcceleratorConfiguration::atiGDIRenderBug ( ) const

inline

Returns the current setting for the ATI GDI rendering work around.

atiGDIRenderBug() [2/2]

void TSLAcceleratorConfiguration::atiGDIRenderBug ( const bool state )

inline

There is a problem with current ATI graphics cards and DirectX where by GDI and DirectX graphics drawing becomes interleaved. Setting this to true enables the work around.

The work around is enabled by default if we detect an ATI graphics card. The default set by the constructor of this card is false. It is therefore advisable to query the initial configuration.

Parameters

state

true enable work around, false disable work around.

dynamicArcTolerance() [1/2]

double TSLAcceleratorConfiguration::dynamicArcTolerance ( ) const

inline

Returns the Dynamic Arc tile tolerance.

dynamicArcTolerance() [2/2]

void TSLAcceleratorConfiguration::dynamicArcTolerance ( const double percentage )

inline

Dynamic Arc tile tolerance.

This is specified as a percentage of the tile width.

The scaling in the x-axis changes with latitude when Dynamic Arc is turned on.

Because the extent of the tiles will therefore continuously change with panning a tolerance has to be used to ensure that the tile cache is not flushed too often. If the tile cache is flushed too often then the performance will be adversely affected.

Setting the value to 100% will disable the flush of the cache. However items drawn will appear either stretched or squashed depending upon the Dynamic Arc scale in operation when the original tile was created. This effect is likely to appear in bands above and below the current middle of the view area.

When the cache is flushed tiles will be requested immediately. This will cause the foreground thread to appear to block while the tiles are drawn.

To mitigate this there are two options available:

    keepMapTilesUntilReplaced
    immediateDraw

The defaults for these options are specified in their documentation as they differ for each platform.

Parameters

percentage

percentage of the tile width (Default 10% set by constructor)

immediateDraw() [1/2]

bool TSLAcceleratorConfiguration::immediateDraw ( )

inline

Returns true if we do immediate draws. This will usually occur on pans when a dynamic arc map is being displayed.

See the setter method for a more detailed discussion.

immediateDraw() [2/2]

void TSLAcceleratorConfiguration::immediateDraw ( bool enable )

inline

If this option is enabled the effect is that in certain situations map tiles will be rendered immediately blocking the application until all the tiles have been drawn.

This is particularly noticeable with Dynamic Arc maps where if the Dynamic Arc Tolerance is exceeded the map tile cache will be flushed and the application will block until a new set of tiles have been created to stop the issue with a blank screen being created.

By disabling this option the tiles will be rendered by the background thread as normal. However if you do not turn on the Keep Textures option (keepMap TilesUntilReplaced) the screen will go blank.

This option is enabled by default on Windows and disabled on X11 (threading with Xlib means that this option can not be enabled).

This option only affects the Multi-threaded Renderer.

Parameters

enable

enables immediate draw mode, false disables immediate draw.

keepMapTilesUntilReplaced() [1/2]

bool TSLAcceleratorConfiguration::keepMapTilesUntilReplaced ( )

inline

Returns the true if the map files are to be kept until replaced, false if they are to be immediately discarded.

keepMapTilesUntilReplaced() [2/2]

void TSLAcceleratorConfiguration::keepMapTilesUntilReplaced ( bool keep )

inline

If true this causes the Accelerator to retain the current set of map tiles until replacement tiles are available.

The effect of this when enabled is:

When zooming in less detail will be displayed, i.e. the map will appear blocky. The amount of blockyness will depend on the amount of zoom occurring.

When zooming out the map detail will appear more detailed and areas around the edge will not be drawn until the replacement tiles are available.

When panning the behaviour should be similar to when this option is disabled. However when you have a Dynamic Arc map the blocking when the Dynamic Arc tolerance is exceed will not occur if you have also disabled the Immediate Draw (see immediateDraw).

In certain situations you may have for a short time different levels of detail of information visible.

The effect when this option is disabled:

If asynchronous zoom is enabled the screen will be displayed in the map background colour.

If panning a dynamic arc map and the dynamic arc tolerance is exceeded then the screen may be displayed in the map background colour or the application may block while the tiles are re-created. The effect is dependent upon the Immediate Draw option setting.

Defaults: This option is enabled internally by default on X11 and disabled internally by default on Windows.

Renderers Affected: This option only affects the Multi-threaded Renderer.

Parameters

keep	true keep the map tiles until they are replaced by a new set, false discard immediately.

numberTilesX() [1/2]

int TSLAcceleratorConfiguration::numberTilesX ( ) const

inline

Returns the number of tiles along the x-axis.

numberTilesX() [2/2]

void TSLAcceleratorConfiguration::numberTilesX ( const int numX )

inline

Sets the number of tiles along the x-axis.

This value is nominal in that the actual number of tiles used will be dependent on the window width along with an addition of a buffer around the edge of the window.

The number of tiles in the X and Y axis will be used to set a limit on the number held in the tile cache.

Parameters

numX	number of tiles along the x-axis (default 4 set by constructor).

numberTilesY() [1/2]

int TSLAcceleratorConfiguration::numberTilesY ( ) const

inline

Returns the number of tiles along the y-axis.

numberTilesY() [2/2]

void TSLAcceleratorConfiguration::numberTilesY ( const int numY )

inline

Sets the number of tiles along the y-axis.

This value is nominal in that the actual number of tiles used will be dependent on the window width along with an addition of a buffer around the edge of the window.

The number of tiles in the X and Y axis will be used to set a limit on the number held in the tile cache.

Parameters

numY	number of tiles along the y-axis (default 4 set by constructor).

swapBuffers() [1/2]

bool TSLAcceleratorConfiguration::swapBuffers ( ) const

inline

Returns true if buffers are swapped by the Surface.

Returns false if the buffers are not swapped by the Surface (it is then up to the user of the Surface to swap the buffers).

swapBuffers() [2/2]

void TSLAcceleratorConfiguration::swapBuffers ( bool swap_buffers )

inline

Controls if the Surface swaps the drawing buffers.

Parameters

swap	true surface swaps the drawing buffers. False then the user is responsible for swapping the buffers.

textureBorder() [1/2]

bool TSLAcceleratorConfiguration::textureBorder ( ) const

inline

Returns the current setting for texture border.

textureBorder() [2/2]

void TSLAcceleratorConfiguration::textureBorder ( bool border )

inline

Allows the user to specify if a map tile has a border. The default is not to have a texture border.

A texture border is supported by drawing a part of the surrounding map on the edge of the tile.

They are very useful when the filter is set to GL_LINEAR as this filter will use the border as a sample.

If you decide not to turn on texture borders then it is possible that the tile boundaries will be visible as a faint blank line when linear filtering is used (depends on Graphics Card).

Parameters

border	true create a texture border, false do not create a texture border.
Notes	Depending on the size of the texture tile there may be a slight misalignment when borders are turned on.

The DirectX implementation does not support a texture border.

textureFilterNearest() [1/2]

bool TSLAcceleratorConfiguration::textureFilterNearest ( ) const

inline

Returns the texture filter setting.

Returns true for GL_NEAREST, false for GL_LINEAR.

textureFilterNearest() [2/2]

void TSLAcceleratorConfiguration::textureFilterNearest ( bool nearest )

inline

This method allows you to change the texture filter setting.

The texture tiles are filtered by default with GL_NEAREST filter setting.

The other possibility is GL_LINEAR.

GL_NEAREST is usually the best setting for performance, but may affect the display of fine detail maps (usually if the pixel mapping is not one to one).

GL_LINEAR is usually the best for display of fine detail maps, but may be slower.

The performance of your graphics hardware will affect the filter setting you wish to use.

NOTE: DirectX implementation does not currently support changing the texture filter setting.

Parameters

nearest

true sets the filter to GL_NEAREST, false sets the filter to GL_LINEAR.

tileSize() [1/2]

int TSLAcceleratorConfiguration::tileSize ( ) const

inline

Returns the size of a tile in pixels.

tileSize() [2/2]

void TSLAcceleratorConfiguration::tileSize ( const int pixels )

inline

Sets the size of a tile in pixels.

The height must be of the form 2^m (where m is an integer).

For example:

32, 64, 128, 256, 512.

If a WMS Data-Layer is attached to an Accelerated Surface the tile size of the layer and surface must match.

Parameters

pixels

number of pixels (default 512 set by constructor)

viewExpansion() [1/2]

double TSLAcceleratorConfiguration::viewExpansion ( ) const

inline

Returns the percent view expansion.

viewExpansion() [2/2]

void TSLAcceleratorConfiguration::viewExpansion ( double percent )

inline

To ensure that the background map tiles are generated before they are required the area being viewed needs to be expanded. Any tiles which fall within this expanded view are requested from the background renderer.

The value passed to this method affects how much the view is expanded. The expansion is always square. Rotating the view will also affect the view area taken into account.

If the expansion percent will affect the amount of time it takes to display after a zoom or large pan as the number of tiles requested will vary depending on the expansion set.

Additionally ensure that the numberTilesX and numberTilesY takes account of the set expansion.

Parameters

percent

percent view expansion (positive)