[Marble-commits] branches/KDE/4.5/kdeedu/marble/src/lib [BROKEN EMAIL]

[Torsten Rahn]

SVN commit 1166249 by rahn:


- Class documentation for StackedTile



 M  +3 -0      StackedTile.cpp  
 M  +66 -8     StackedTile.h  


--- branches/KDE/4.5/kdeedu/marble/src/lib/StackedTile.cpp #1166248:1166249
@@ -368,6 +368,9 @@
 
 void StackedTile::initResultTile()
 {
+    // TODO: Free all the TextureTiles once the completion status is reached 
+    // to save memory.
+    
     Q_ASSERT( hasTiles() );
     // if there are more than one active texture layers, we have to convert the
     // result tile into QImage::Format_ARGB32_Premultiplied to make blending possible
--- branches/KDE/4.5/kdeedu/marble/src/lib/StackedTile.h #1166248:1166249
@@ -34,6 +34,33 @@
 class TextureTile;
 class StackedTileLoader;
 
+/*!
+    \class StackedTile
+    \brief A single tile that is composed one or more different tile layers.
+
+    The StackedTile is a tile 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
+    built up from the ground: The first TextureTile at the bottom usually 
+    represents the ground surface. Optionally there might be a range of other
+    TextureTiles stacked on top which cover e.g. relief, streets and clouds.
+    
+    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 
+    composition of all TextureTile layers is very fast since it is reduced to 
+    a single QImage that also covers 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 
+    so called filters and can be merged into a single layer if required.
+
+    Restrictions: The TextureTiles that are part of the stack need to be of 
+    the same size and need to cover the same area at the same zoom level using 
+    the very same projection.
+*/
+
 class StackedTile : public AbstractTile
 {
     friend class StackedTileLoader;
@@ -49,22 +76,39 @@
     bool forMergedLayerDecorator() const;
     void setForMergedLayerDecorator();
 
+/*!
+    \brief Returns the stack of TextureTiles
+    \return A non-zero pointer to the container of TextureTile objects.
+*/
     QVector<QSharedPointer<TextureTile> > * tiles();
-    QImage const * resultTile() const;
+
+/*!
+    \brief Returns the QImage that describes the merged stack of TextureTiles
+    \return A non-zero pointer to the resulting QImage 
+*/
+    QImage const * resultTile() const; // Note: maybe this should be resultImage() ?
     QImage * resultTile();
 
-    // Here we retrieve the color value of the requested pixel on the tile.
-    // This needs to be done differently for grayscale ( uchar, 1 byte ).
-    // and color ( uint, 4 bytes ) images.
+/*!
+    \brief Returns the color value of the result tile at the given integer position.
+    \return The uint that describes the color value of the given pixel 
 
+    Note: for gray scale images the color value of a single pixel is described
+    via a uchar (1 byte) while for RGB(A) images uint (4 bytes) are used.
+*/
     uint pixel( int x, int y ) const;
     
-    // Here we retrieve the color value of the requested subpixel on the tile.
-    // This needs to be done differently for grayscale ( uchar, 1 byte ).
-    // and color ( uint, 4 bytes ) images.
-    // Subpixel calculation is done via bilinear interpolation.
+/*!
+    \brief Returns the color value of the result tile at a given floating point position.
+    \return The uint that describes the color value of the given pixel 
 
+    Subpixel calculation is done via bilinear interpolation.
+    
+    Note: for gray scale images the color value of a single pixel is described
+    via a uchar (1 byte) while for RGB(A) images uint (4 bytes) are used.
+*/    
     uint pixelF( qreal x, qreal y ) const;
+    // This method passes the top left pixel (if known already) for better performance
     uint pixelF( qreal x, qreal y, const QRgb& pixel ) const;
 
  protected:
@@ -74,10 +118,24 @@
     Q_DECLARE_PRIVATE( StackedTile )
     Q_DISABLE_COPY( StackedTile )
 
+    // TODO: move the private methods into the private class. 
+    
+/*!
+    \brief Appends a TextureTile to the stack und updates the completion state.
+*/    
     void addTile( QSharedPointer<TextureTile> const & );
+    
+/*!
+    \brief Updates the completion state based on the state of each TextureTile.
+*/    
     void deriveCompletionState();
     void initJumpTables();
+    
     bool hasTiles() const;
+    
+/*!
+    \brief This method performs the actual merge process.
+*/    
     void initResultTile();
 
     StackedTilePrivate *d;