[gdal-dev] Where is GDALRasterBlock documentation?

[Jorge Arévalo]

Hello,

2009/8/3 Even Rouault <even.rouault at mines-paris.org>:
> 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.
>

The simplest caching system. Then, I suppose RAM caching system. I
simply want to avoid one call to IReadBlock ( = 1 spatial query) for
each block of needed data.


> 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()).

Understood until here.

> 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).

I have a doubt here. What is exactly the "cache system"? Each
RasterBand has its own array of GDALRasterBlocks, but this array is
local to the Band, not global to all the datasets. So, this array of
chained blocks on each band can't be the "cache system"...


> 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.
>

So, in a read scenario, the cache blocks are simply deleted when
closing the dataset. In a pure read scenario, you don't really need to
flush blocks, because they aren't modified. Am I right?

Many thanks for the GREAT explanation.

Best regards,
Jorge

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