[Marble-commits] KDE/kdeedu/marble/src/lib

[Torsten Rahn]

SVN commit 1166337 by rahn:


- Class documentation for Tile classes



 M  +28 -0     AbstractTile.h  
 M  +2 -2      StackedTile.cpp  
 M  +6 -10     StackedTile.h  
 M  +56 -0     TextureTile.h  


--- trunk/KDE/kdeedu/marble/src/lib/AbstractTile.h #1166336:1166337
@@ -24,6 +24,26 @@
 class AbstractTilePrivate;
 class TileId;
 
+/*!
+    \class AbstractTile
+    \brief A class that provides the basic properties of tiles .
+
+    A tile is a chunk of data that describes the themed look of a certain 
+    (geographic) area for a given zoom level. Each tile can be identified via
+    a unique TileId.
+    
+    Depending on its type the tile can contain texture data, vector data 
+    or a set of even more tile data. 
+    
+    Usually the tiles are organized in so called quad tiles: This means that
+    with increasing zoom level four other tiles cover the same area as a 
+    single "parent" tile in the previous zoom level. These four tiles have 
+    the same pixel/file size as the "parent" tile.
+    
+    Via AbstractTile::used() it's possible to find out whether the tile is 
+    being displayed on the screen.
+*/
+
 class AbstractTile : public QObject
 {
     Q_OBJECT
@@ -34,8 +54,16 @@
     virtual ~AbstractTile();
 
  public:
+/*!
+    \brief Returns a unique ID for the tile.
+    \return A TileId object that encodes zoom level, position and map theme.
+*/     
     TileId const& id() const;
 
+/*!
+    \brief Returns whether the tile is being used on the screen.
+    \return Describes whether the tile is in active use by the texture mapping.
+*/     
     bool used() const;
     void setUsed( bool used );
 
--- trunk/KDE/kdeedu/marble/src/lib/StackedTile.cpp #1166336:1166337
@@ -5,9 +5,9 @@
 // find a copy of this license in LICENSE.txt in the top directory of
 // the source code.
 //
-// Copyright 2006-2007 Torsten Rahn <tackat at kde.org>
+// Copyright 2006-2010 Torsten Rahn <tackat at kde.org>
 // Copyright 2007      Inge Wallin  <ingwa at kde.org>
-// Copyright 2008      Jens-Michael Hoffmann <jensmh at gmx.de>
+// Copyright 2008-2010 Jens-Michael Hoffmann <jensmh at gmx.de>
 //
 
 #include "StackedTile.h"
--- trunk/KDE/kdeedu/marble/src/lib/StackedTile.h #1166336:1166337
@@ -5,15 +5,11 @@
 // find a copy of this license in LICENSE.txt in the top directory of
 // the source code.
 //
-// Copyright 2007-2009  Torsten Rahn <tackat at kde.org>
+// Copyright 2007-2010  Torsten Rahn <tackat at kde.org>
 // Copyright 2007       Inge Wallin  <ingwa at kde.org>
+// Copyright 2010       Jens-Michael Hoffmann <jensmh at gmx.de>
 //
 
-//
-// Description: StackedTile contains a single image quadtile 
-// and jumptables for faster access to the pixel data
-//
-
 #ifndef MARBLE_STACKEDTILE_H
 #define MARBLE_STACKEDTILE_H
 
@@ -36,9 +32,9 @@
 
 /*!
     \class StackedTile
-    \brief A single tile that is composed one or more different tile layers.
+    \brief A single tile that consists of a stack of TextureTile layers.
 
-    The StackedTile is a tile that covers a certain area and is used 
+    The StackedTile is a tile container that covers a certain area and is used 
     for a particular zoom level. It consists of a <b>stack of several
     individual thematic TextureTiles</b> that cover the very same area and 
     are used for the very same zoom level: This stack of TextureTiles is
@@ -48,9 +44,9 @@
     
     For rendering the whole stack of tiles gets merged and blended into a 
     single QImage. This merging/blending operation is usually only performed 
-    once the stack of tiles changes. As a result access to the visual 
+    once the stack of tiles changes visually. As a result access to the visual 
     composition of all TextureTile layers is very fast since it is reduced to 
-    a single QImage that also covers very little memory.
+    a single QImage that also consumes very little memory.
 
     The whole mechanism is comparable to layers in applications like
     Gimp or Photoshop (TM) which can be blended on top of each other via 
--- trunk/KDE/kdeedu/marble/src/lib/TextureTile.h #1166336:1166337
@@ -30,6 +30,31 @@
 class TileLoader;
 class StackedTileLoader;
 
+/*!
+    \class TextureTile
+    \brief A class that resembles a texture tile .
+
+    A texture tile provides a bitmap image for a certain (geographic) area and 
+    for a given zoom level. Each TextureTile can be identified via a unique 
+    TileId.
+    
+    A stack of TextureTiles that cover the same area and the same 
+    zoom level can be stored (and painted) layer by layer in a StackedTile object. 
+    For this purpose each TextureTile specifies a blending type. 
+
+    Usually the tiles are organized in so called quad tiles: This means that
+    with increasing zoom level four other tiles cover the same area as a 
+    single "parent" tile in the previous zoom level. These four tiles have 
+    the same pixel size as the "parent" tile.
+    
+    The process of "filling the tile with data is done in stages: The 
+    State describes the current progress of loading the data (Empty, Scaled, 
+    Expired, StateUptodate).
+    
+    The life time cycle of a TextureTile can also be influenced by its
+    expiration time which will trigger a reload of the tile data.
+*/
+
 class TextureTile
 {
     friend class TileLoader;
@@ -39,11 +64,42 @@
     TextureTile( TileId const & tileId, QImage const * image );
     ~TextureTile();
 
+/*!
+    \brief Returns a unique ID for the tile.
+    \return A TileId object that encodes zoom level, position and map theme.
+*/     
     TileId const & id() const;
+    
+/*!
+    \brief Returns a unique ID for the StackedTile that contains this tile.
+    \return A TileId object that encodes zoom level, position and map theme.
+*/         
     TileId const & stackedTileId() const;
+    
+/*!
+    \brief Returns the time at which the tile was previously loaded onto the harddisc.
+    \return A QDateTime object that holds the modification time of the tile.
+*/         
     QDateTime const & lastModified() const;
+    
+/*!
+    \brief Returns whether the tile is considered outdated.
+    \return Whether the tile needs to be reloaded according to its last modification time.
+*/         
     bool isExpired() const;
+    
+/*!
+    \brief Returns the QImage that describes the look of the TextureTile
+    \return A non-zero pointer to a QImage associated with the tile.
+*/
     QImage const * image() const;
+    
+/*!
+    \brief Returns the kind of blending used for the tile.
+    \return A pointer to the blending object used for painting/merging the TextureTile.
+    
+    If no blending is set the pointer returned will be zero.
+*/     
     Blending const * blending() const;
     int byteCount() const;