proland::TileProducer Class Reference
[producer]

An abstract producer of tiles. More...

#include <TileProducer.h>

List of all members.

Public Member Functions
	TileProducer (const char *type, const char *taskType, ptr< TileCache > cache, bool gpuProducer)
	Creates a new TileProducer.
virtual	~TileProducer ()
	Deletes this TileProducer.
float	getRootQuadSize ()
	Returns the size in meters of the root quad produced by this producer.
virtual void	setRootQuadSize (float size)
	Sets the size in meters of the root quad produced by this producer.
int	getId ()
	Returns the id of this producer.
virtual ptr< TileCache >	getCache ()
	Returns the TileCache that stores the tiles produced by this producer.
bool	isGpuProducer ()
	Returns true if this producer produces textures on GPU.
virtual int	getBorder ()
	Returns the size in pixels of the border of each tile.
virtual bool	hasTile (int level, int tx, int ty)
	Returns true if this producer can produce the given tile.
bool	hasChildren (int level, int tx, int ty)
	Returns true if this producer can produce the children of the given tile.
virtual TileCache::Tile *	findTile (int level, int tx, int ty, bool includeCache=false, bool done=false)
	Looks for a tile in the TileCache of this TileProducer.
virtual TileCache::Tile *	getTile (int level, int tx, int ty, unsigned int deadline)
	Returns the requested tile, creating it if necessary.
vec4f	getGpuTileCoords (int level, int tx, int ty, TileCache::Tile **tile)
	Returns the coordinates in the GPU storage of the given tile.
virtual bool	prefetchTile (int level, int tx, int ty)
	Schedules a prefetch task to create the given tile.
virtual void	putTile (TileCache::Tile *t)
	Decrements the number of users of this tile by one.
virtual void	invalidateTiles ()
	Invalidates the tiles produced by this producer.
virtual void	invalidateTile (int level, int tx, int ty)
	Invalidates the selected tile produced by this producer.
virtual void	update (ptr< SceneManager > scene)
	Updates the tiles produced by this producer, if necessary.
bool	updateTileMap (float splitDistance, vec2f camera, int maxLevel)
	Updates the GPU tile map for this producer.
virtual void	getReferencedProducers (vector< ptr< TileProducer > > &producers) const
	Returns the tile producers used by this TileProducer.
int	getLayerCount () const
	Returns the number of layers of this producer.
ptr< TileLayer >	getLayer (int index) const
	Returns the layer of this producer whose index is given.
bool	hasLayers () const
	Returns true if the list of layers is not empty.
void	addLayer (ptr< TileLayer > l)
	Adds a Layer to this producer.
Protected Member Functions
	TileProducer (const char *type, const char *taskType)
	Creates an uninitialized TileProducer.
void	init (ptr< TileCache > cache, bool gpuProducer)
	Initializes this TileProducer.
virtual void *	getContext () const
	Returns the context for the Task that produce the tile data.
virtual ptr< Task >	startCreateTile (int level, int tx, int ty, unsigned int deadline, ptr< Task > task, ptr< TaskGraph > owner)
	Starts the creation of a tile of this producer.
virtual void	beginCreateTile ()
	Sets the execution context for the Task that produces the tile data.
virtual bool	doCreateTile (int level, int tx, int ty, TileStorage::Slot *data)
	Creates the given tile.
virtual void	endCreateTile ()
	Restores the execution context for the Task that produces the tile data.
virtual void	stopCreateTile (int level, int tx, int ty)
	Stops the creation of a tile of this producer.
void	removeCreateTile (Task *t)
	Removes a task from the vector tasks.
ptr< TaskGraph >	createTaskGraph (ptr< Task > task)
	Creates a task graph for use in startCreateTile.
Private Member Functions
ptr< Task >	createTile (int level, int tx, int ty, TileStorage::Slot *data, unsigned int deadline, ptr< Task > old)
	Creates a Task to produce the data of the given tile.
Private Attributes
vector< ptr< TileLayer > >	layers
	The list of all the Layers used by this producer.
vector< Task * >	tasks
	The list of all the Tasks created by this producer.
char *	taskType
	The type of the Task that produce the actual tile data.
ptr< TileCache >	cache
	The tile cache that stores the tiles produced by this producer.
bool	gpuProducer
	True if this producer produces textures on GPU.
int	id
	The id of this producer.
float	rootQuadSize
	The size in meters of the root tile produced by this producer.
unsigned char *	tileMap
	The data of the tileMap texture line on GPU for this producer.
void *	mutex
	A mutex to serialize parallel accesses to tasks.

---

Detailed Description

An abstract producer of tiles.

Note that several TileProducer can share the same TileCache, and hence the same TileStorage.

Authors:

Eric Bruneton, Antoine Begault, Guillaume Piolat

---

Constructor & Destructor Documentation

proland::TileProducer::TileProducer	(	const char *	type,
		const char *	taskType,
		ptr< TileCache >	cache,
		bool	gpuProducer
	)

Creates a new TileProducer.

Parameters:

	type	the type of this producer.
	taskType	the type of the Task that produce the actual tile data.
	cache	the tile cache that stores the tiles produced by this producer.
	gpuProducer	true if this producer produces textures on GPU.

virtual proland::TileProducer::~TileProducer

(

)

[virtual]

Deletes this TileProducer.

proland::TileProducer::TileProducer	(	const char *	type,
		const char *	taskType
	)			[protected]

Creates an uninitialized TileProducer.

Parameters:

	type	the type of this producer.
	taskType	the type of the Task that produce the actual tile data.

---

Member Function Documentation

void proland::TileProducer::addLayer

(

ptr< TileLayer >

l

)

Adds a Layer to this producer.

Parameters:

l

the layer to be added.

virtual void proland::TileProducer::beginCreateTile

(

)

[protected, virtual]

Sets the execution context for the Task that produces the tile data.

This is only needed for GPU tasks (see Task::begin). The default implementation of this method calls Layer::beginCreateTile on each Layer of this producer.

ptr<TaskGraph> proland::TileProducer::createTaskGraph

(

ptr< Task >

task

)

[protected]

Creates a task graph for use in startCreateTile.

Parameters:

task

a task that will be added to the returned task graph.

Returns:

a task graph containing 'task', for use in startCreateTile.

ptr<Task> proland::TileProducer::createTile	(	int	level,
		int	tx,
		int	ty,
		TileStorage::Slot *	data,
		unsigned int	deadline,
		ptr< Task >	old
	)			[private]

Creates a Task to produce the data of the given tile.

Parameters:

	level	the tile's quadtree level.
	tx	the tile's quadtree x coordinate.
	ty	the tile's quadtree y coordinate.
	data	where the produced tile data must be stored.
	deadline	the deadline at which the tile data must be ready. 0 means the current frame.
	t	the existing task to create this tile if it still exists, or NULL.

virtual bool proland::TileProducer::doCreateTile	(	int	level,
		int	tx,
		int	ty,
		TileStorage::Slot *	data
	)			[protected, virtual]

Creates the given tile.

If this task requires tiles produced by other producers (or other tiles produced by this producer), these tiles must be acquired and released in startCreateTile and stopCreateTile with getTile and putTile, and retrieved in this method with findTile. The default implementation of this method calls Layer::doCreateTile on each Layer of this producer.

Parameters:

	level	the tile's quadtree level.
	tx	the tile's quadtree x coordinate.
	ty	the tile's quadtree y coordinate.
	data	where the created tile data must be stored.

Returns:

true the result of this creation is different from the result of the last creation of this tile. See Task::run.

virtual void proland::TileProducer::endCreateTile

(

)

[protected, virtual]

Restores the execution context for the Task that produces the tile data.

This is only needed for GPU tasks (see Task::end). The default implementation of this method calls Layer::endCreateTile on each Layer of this producer.

virtual TileCache::Tile* proland::TileProducer::findTile	(	int	level,
		int	tx,
		int	ty,
		bool	includeCache = false,
		bool	done = false
	)			[virtual]

Looks for a tile in the TileCache of this TileProducer.

Parameters:

	level	the tile's quadtree level.
	tx	the tile's quadtree x coordinate.
	ty	the tile's quadtree y coordinate.
	includeCache	true to include both used and unused tiles in the search, false to include only the used tiles.
	done	true to check that the tile's creation task is done.

Returns:

the requested tile, or NULL if it is not in the TileCache or if 'done' is true, if it is not ready. This method does not change the number of users of the returned tile.

virtual int proland::TileProducer::getBorder

(

)

[virtual]

Returns the size in pixels of the border of each tile.

Tiles made of raster data may have a border that contains the value of the neighboring pixels of the tile. For instance if the tile size (returned by TileStorage::getTileSize) is 196, and if the tile border is 2, this means that the actual tile data is 192x192 pixels, with a 2 pixel border that contains the value of the neighboring pixels. Using a border introduces data redundancy but is usefull to get the value of the neighboring pixels of a tile without needing to load the neighboring tiles.

virtual ptr<TileCache> proland::TileProducer::getCache

(

)

[virtual]

Returns the TileCache that stores the tiles produced by this producer.

virtual void* proland::TileProducer::getContext

(

)

const [protected, virtual]

Returns the context for the Task that produce the tile data.

This is only needed for GPU tasks (see Task::getContext). The default implementation of this method does nothing and returns NULL.

vec4f proland::TileProducer::getGpuTileCoords	(	int	level,
		int	tx,
		int	ty,
		TileCache::Tile **	tile
	)

Returns the coordinates in the GPU storage of the given tile.

If the given tile is not in the GPU storage, this method uses the first ancestor of this tile that is in the storage. It then returns the coordinates of the area of this ancestor tile that correspond to the requested tile.

Parameters:

	level	the tile's quadtree level.
	tx	the tile's quadtree x coordinate.
	ty	the tile's quadtree y coordinate.
[in,out]	tile	the tile (level,tx,ty) or its first ancestor that is in the storage, if known. If no tile is specified (passing NULL) this method finds it and returns it in this parameter.

Returns:

the coordinates in the GPU storage texture of the requested tile. The x,y components correspond to the lower left corner of the tile in the GPU storage texture. The z,w components correspond to the width and height of the tile. All components are in texture coordinates, between 0 and 1. If the tile has borders, the returned coordinates correspond to the inside of the tile, excluding its border.

int proland::TileProducer::getId

(

)

Returns the id of this producer.

This id is local to the TileCache used by this producer, and is used to distinguish all the producers that use this cache.

ptr<TileLayer> proland::TileProducer::getLayer

(

int

index

)

const

Returns the layer of this producer whose index is given.

Parameters:

index

a layer index between 0 and getLayerCount (exclusive).

int proland::TileProducer::getLayerCount

(

)

const

Returns the number of layers of this producer.

virtual void proland::TileProducer::getReferencedProducers

(

vector< ptr< TileProducer > > &

producers

)

const [virtual]

Returns the tile producers used by this TileProducer.

Parameters:

[out]

producers

the tile producers used by this TileProducer.

float proland::TileProducer::getRootQuadSize

(

)

Returns the size in meters of the root quad produced by this producer.

virtual TileCache::Tile* proland::TileProducer::getTile	(	int	level,
		int	tx,
		int	ty,
		unsigned int	deadline
	)			[virtual]

Returns the requested tile, creating it if necessary.

If the tile is currently in use it is returned directly. If it is in cache but unused, it marked as used and returned. Otherwise a new tile is created, marked as used and returned. In all cases the number of users of this tile is incremented by one.

Parameters:

	level	the tile's quadtree level.
	tx	the tile's quadtree x coordinate.
	ty	the tile's quadtree y coordinate.
	deadline	the deadline at which the tile data must be ready. 0 means the current frame.

Returns:

the requested tile, or NULL if there is no room left in the TileStorage to store the requested tile.

bool proland::TileProducer::hasChildren	(	int	level,
		int	tx,
		int	ty
	)

Returns true if this producer can produce the children of the given tile.

Parameters:

	level	the tile's quadtree level.
	tx	the tile's quadtree x coordinate.
	ty	the tile's quadtree y coordinate.

bool proland::TileProducer::hasLayers

(

)

const

Returns true if the list of layers is not empty.

False otherwise.

virtual bool proland::TileProducer::hasTile	(	int	level,
		int	tx,
		int	ty
	)			[virtual]

Returns true if this producer can produce the given tile.

Parameters:

	level	the tile's quadtree level.
	tx	the tile's quadtree x coordinate.
	ty	the tile's quadtree y coordinate.

void proland::TileProducer::init	(	ptr< TileCache >	cache,
		bool	gpuProducer
	)			[protected]

Initializes this TileProducer.

Parameters:

	cache	the tile cache that stores the tiles produced by this producer.
	gpuProducer	true if this producer produces textures on GPU.

virtual void proland::TileProducer::invalidateTile	(	int	level,
		int	tx,
		int	ty
	)			[virtual]

Invalidates the selected tile produced by this producer.

This means that the tasks to produce the actual data of this tile will be automatically reexecuted before the data can be used.

virtual void proland::TileProducer::invalidateTiles

(

)

[virtual]

Invalidates the tiles produced by this producer.

This means that the tasks to produce the actual data of these tiles will be automatically reexecuted before the data can be used.

bool proland::TileProducer::isGpuProducer

(

)

Returns true if this producer produces textures on GPU.

virtual bool proland::TileProducer::prefetchTile	(	int	level,
		int	tx,
		int	ty
	)			[virtual]

Schedules a prefetch task to create the given tile.

If the requested tile is currently in use or in cache but unused, this method does nothing. Otherwise it gets an unused tile storage (evicting an unused tile if necessary), and then creates and schedules a task to produce the data of the requested tile.

Parameters:

	level	the tile's quadtree level.
	tx	the tile's quadtree x coordinate.
	ty	the tile's quadtree y coordinate.

Returns:

true if this method has been able to schedule a prefetch task for the given tile.

virtual void proland::TileProducer::putTile

(

TileCache::Tile *

t

)

[virtual]

Decrements the number of users of this tile by one.

If this number becomes 0 the tile is marked as unused, and so can be evicted from the cache at any moment.

Parameters:

t

a tile currently in use.

void proland::TileProducer::removeCreateTile

(

Task *

t

)

[protected]

Removes a task from the vector tasks.

This is used to avoid delete-calls for objects that were already deleted. This is called when a task created by this producer gets deleted.

virtual void proland::TileProducer::setRootQuadSize

(

float

size

)

[virtual]

Sets the size in meters of the root quad produced by this producer.

Parameters:

size

the size of the root quad of this producer.

virtual ptr<Task> proland::TileProducer::startCreateTile	(	int	level,
		int	tx,
		int	ty,
		unsigned int	deadline,
		ptr< Task >	task,
		ptr< TaskGraph >	owner
	)			[protected, virtual]

Starts the creation of a tile of this producer.

This method is used for producers that need tiles produced by other producers to create a tile. In these cases this method must acquire these other tiles with getTile so that these tiles are available with findTile during the actual tile creation in doCreateTile.

Parameters:

	level	the tile's quadtree level.
	tx	the tile's quadtree x coordinate.
	ty	the tile's quadtree y coordinate.
	deadline	the deadline at which the tile data must be ready. 0 means the current frame.
	task	the task to produce the tile itself.
	owner	the task graph that contains 'task', or NULL. This task graph can be used if 'task' depends on other tasks. These other tasks must then be added to 'owner'.

Returns:

the task or task graph to produce the tile itself, and all the tiles needed to produce it. The default implementation of this method calls Layer::startCreateTile on each layer, and returns 'owner' if it is not NULL (otherwise it returns 'task'). NOTE: if a task graph is returned, it must be created with createTaskGraph.

virtual void proland::TileProducer::stopCreateTile	(	int	level,
		int	tx,
		int	ty
	)			[protected, virtual]

Stops the creation of a tile of this producer.

This method is used for producers that need tiles produced by other producers to create a tile. In these cases this method must release these other tiles with putTile so that these tiles can be evicted from the cache after use. The default implementation of this method calls Layer::stopCreateTile on each Layer of this producer.

Parameters:

	level	the tile's quadtree level.
	tx	the tile's quadtree x coordinate.
	ty	the tile's quadtree y coordinate.

virtual void proland::TileProducer::update

(

ptr< SceneManager >

scene

)

[virtual]

Updates the tiles produced by this producer, if necessary.

The default implementation of this method does nothing.

bool proland::TileProducer::updateTileMap	(	float	splitDistance,
		vec2f	camera,
		int	maxLevel
	)

Updates the GPU tile map for this producer.

A GPU tile map allows a GPU shader to retrieve the data of any tile from its level,tx,ty coordinates, thanks to a mapping between these coordinates and texture tile storage u,v coordinates, stored in the tile map. This is only possible if the quadtree of tiles is subdivided only based on the distance to the camera. The camera position and the subdivision parameters are needed to create the tile map and to decode it on GPU.

Parameters:

	splitDistance	the distance at which a quad is subdivided. In fact a quad is supposed to be subdivided if the camera distance is less than splitDistance times the quad size (in meters).
	camera	the camera position. This position, together with splitDistance and rootQuadSize completely define the current quadtree (i.e. which quads are subdivided, and which are not).
	maxLevel	the maximum subdivision level of the quadtree (included).

Returns:

true if the tile storage for this producer has a tile map (see GPUTileStorage::getTileMap). Otherwise this method does nothing.

---

Member Data Documentation

ptr<TileCache> proland::TileProducer::cache [private]

The tile cache that stores the tiles produced by this producer.

bool proland::TileProducer::gpuProducer [private]

True if this producer produces textures on GPU.

int proland::TileProducer::id [private]

The id of this producer.

This id is local to the TileCache used by this producer, and is used to distinguish all the producers that use this cache.

vector< ptr<TileLayer> > proland::TileProducer::layers [private]

The list of all the Layers used by this producer.

void* proland::TileProducer::mutex [private]

A mutex to serialize parallel accesses to tasks.

float proland::TileProducer::rootQuadSize [private]

The size in meters of the root tile produced by this producer.

vector<Task*> proland::TileProducer::tasks [private]

The list of all the Tasks created by this producer.

char* proland::TileProducer::taskType [private]

The type of the Task that produce the actual tile data.

unsigned char* proland::TileProducer::tileMap [private]

The data of the tileMap texture line on GPU for this producer.

If a quadtree is subdivided based only on the distance to the camera, it is possible to compute on GPU which level,tx,ty tile corresponds to an x,y position in meters. But in order to compute where the data of this tile is stored in a texture tile storage, the mapping between level,tx,ty coordinates and texture tile storage u,v coordinates is needed. A tileMap provides this information (it must be updated each time the camera moves or the tile storage layout changes). Each line of this tileMap corresponds to a single producer. Only GPU producers can have a tileMap.