[gdal-dev] Where is GDALRasterBlock documentation?

[Even Rouault]

Le Monday 03 August 2009 18:07:33 Jorge Arévalo, vous avez écrit :
> Hello,
>
> Why GDALRasterBlock definition doesn't appear in the GDAL class list
> at http://www.gdal.org/annotated.html ?

Technical reason : It would just require to add a missing line
//! Raster block
before
class CPL_DLL GDALRasterBlock
in gcore/gdal_priv.h

More realistic reason : very few methods of GDALRasterBlock are properly 
documented + the fact it is a very internal thing that only interest GDAL 
developers themselves, not GDAL API users and very few GDAL driver 
developers.

>
> I'm trying to implement a cache-block system for GDAL WKT Raster
> driver, but I'm not sure if I should use this class. Maybe is
> deprecated?

It's not deprecated : it is actively used by GDALRasterBand.

But I'm not sure what/why you want to do about block caching for WKT raster 
driver. Is this a harddisk block caching or a RAM block caching ? If it's RAM 
block caching, you don't need to do anything as it is the purpose of the 
GDALRasterBlock/GDALRasterBand and doesn't require to write code to benefit 
from it.

Here's a synthesis of how it works :
The GDALRasterBand object has an array of pointers to blocks (papoBlocks). 
Initially, all the pointers are set to NULL.  When a GDALRasterIO() / 
GDALDatasetRasterIO() is issued, the default implementation in 
GDALRasterBand::IRasterIO() in gcore/rasterio.cpp will divide the requested 
source window into a list of blocks matching the block size of the band. It 
will call the GetLockedBlockRef() method of GDALRasterBand to see if there's 
already a matching block stored in papoBlocks. If yes, fine : the caller will 
fetch the pixel buffer from the cached block. If not, it will call the 
IReadBlock() method on the band (your implementation in WKTRaster driver for 
example) and will store the resulting buffer in a new GDALRasterBlock object 
(the cached pixel buffer is allocated by GDALRasterBlock::Internalize()). 
This object will be chained to other previously cached GDALRasterBlock (the 
cache is global to all the opened datasets, and that's one of the tricky 
point of the implementation : safe use in multithreading context). When there 
are too many cached blocks in RAM, GDALRasterBlock::Internalize(), through 
GDALFlushCacheBlock(), can evict the least recently used blocks from the list 
and nullify their corresponding entries into the papoBlocks array of their 
rasterbands. When a dataset is closed and its raster band destroyed or 
flushed, all the non-NULL blocks in papoBlocks will be flushed. I described 
here a read scenario, but it only works for a write scenario. Each block has 
a dirty flag to know if it must be written with IWriteBlock() before being 
deleted.

>
> Thanks in advance
>
> Best regards,
> Jorge
> _______________________________________________
> gdal-dev mailing list
> gdal-dev at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/gdal-dev