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< TileCachegetCache ()
 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::TilefindTile (int level, int tx, int ty, bool includeCache=false, bool done=false)
 Looks for a tile in the TileCache of this TileProducer.
virtual TileCache::TilegetTile (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< TileLayergetLayer (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< TileCachecache
 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

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

True if this producer produces textures on GPU.

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.

A mutex to serialize parallel accesses to tasks.

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.

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.


Generated on Sat May 12 09:41:38 2012 for proland by  doxygen 1.6.1