tileio.c

Go to the documentation of this file.

#include <stdio.h>
#include <stdlib.h>
#include <sys/types.h>
#include <unistd.h>
#include "raster3d_intern.h"
 
/*---------------------------------------------------------------------------*/
 
/*---------------------------------------------------------------------------*/
 
/* EXPORTED FUNCTIONS */
 
/*---------------------------------------------------------------------------*/
 
/*---------------------------------------------------------------------------*/
 
/*!
 * \brief
 *
 * This function
 * returns a pointer to a tile which contains the data for the tile with index
 * <em>tileIndex</em>.  The type of the data stored in the tile depends on the
 * type specified at the initialization time of <em>map</em>.  The functionality
 * is different depending on whether <em>map</em> is old or new and depending on
 * the cache-mode of <em>map</em>.<br>
 *
 * If <em>map</em> is old and the cache is not used the tile with
 * <em>tileIndex</em> is read from file and stored in the buffer provided by the
 * map structure. The pointer to this buffer is returned. If the buffer already
 * contains the tile with <em>tileIndex</em> reading is skipped. Data which was
 * stored in earlier calls to <tt>Rast3d_get_tile_ptr</tt> is destroyed. If the
 * tile with <em>tileIndex</em> is not stored on the file corresponding to
 * <em>map</em>, and <em>tileIndex</em> is a valid index the buffer is filled
 * with NULL-values.<br>
 *
 * If <em>map</em> is old and the cache is used the tile with <em>tileIndex</em>
 * is read from file and stored in one of the cache buffers.  The pointer to
 * buffer is returned.  If no free cache buffer is available an unlocked
 * cache-buffer is freed up and the new tile is stored in its place.  If the
 * tile with <em>tileIndex</em> is not stored on the file corresponding to
 * <em>map</em>, and <em>tileIndex</em> is a valid index the buffer is filled
 * with NULL-values.  If one of the cache buffers already contains the tile with
 * <em>tileIndex</em> reading is skipped and the pointer to this buffer is
 * returned.<br>
 *
 * If <em>map</em> is new and the cache is not used the functionality is the
 * same as if <em>map</em> is old and the cache is not used.  If the tile with
 * <em>tileIndex</em> is already stored on file, it is read into the buffer, if
 * not, the cells are set to null-values.  If the buffer corresponding to the
 * pointer is used for writing, subsequent calls to <tt>Rast3d_get_tile_ptr</tt>
 * may destroy the values already stored in the buffer.  Use
 * <tt>Rast3d_flush_tile</tt> to write the buffer to the file before reusing it
 * for a different index.  The use of this buffer as write buffer is
 * discouraged.<br>
 *
 * If <em>map</em> is new and the cache is used the functionality is the same as
 * if <em>map</em> is old and the cache is used with the following exception. If
 * <em>tileIndex</em> is a valid index and the tile with this index is not found
 * in the cache and is not stored on the file corresponding to <em>map</em>,
 * then the file cache is queried next. If the file-cache contains the tile it
 * is loaded into the cache (memory-cache). Only if the file-cache does not
 * contain the tile it is filled with NULL-values.  Tile contents of buffers are
 * never destroyed. If a cache buffer needs to be freed up, and the tile stored
 * in the buffer has not been written to the file corresponding to <em>map</em>
 * yet, the tile is copied into the file-cache.<br>
 *
 * Care has to be taken if this function is used in non-cache mode since it is
 * implicitly invoked every time a read or write request is issued.  The only
 * I/O-functions for which it is safe to assume that they do not invoke
 * <tt>Rast3d_get_tile_ptr</tt> are <tt>Rast3d_read_tile()</tt> and
 * <tt>Rast3d_write_tile()</tt> and their corresponding type-specific versions.
 *
 *  \param map
 *  \param tileIndex
 *  \return void * a pointer to a buffer ... if successful,
 *                 NULL ... otherwise.
 */
void *Rast3d_get_tile_ptr(RASTER3D_Map *map, int tileIndex)
{
    void *ptr;
 
    if ((tileIndex >= map->nTiles) || (tileIndex < 0)) {
        Rast3d_error("Rast3d_get_tile_ptr: tileIndex out of range");
        return NULL;
    }
 
    if (map->useCache) {
        ptr = Rast3d_cache_elt_ptr(map->cache, tileIndex);
        if (ptr == NULL) {
            Rast3d_error("Rast3d_get_tile_ptr: error in Rast3d_cache_elt_ptr");
            return NULL;
        }
        return ptr;
    }
 
    if (map->currentIndex == tileIndex)
        return map->data;
 
    map->currentIndex = tileIndex;
    if (!Rast3d_read_tile(map, map->currentIndex, map->data, map->typeIntern)) {
        Rast3d_error("Rast3d_get_tile_ptr: error in Rast3d_read_tile");
        return NULL;
    }
 
    return map->data;
}
 
/*---------------------------------------------------------------------------*/
 
/*!
 * \brief
 *
 * Same functionality as <tt>Rast3d_get_tile_ptr()</tt> but does not return the
 * pointer.
 *
 *  \param map
 *  \param tileIndex
 *  \return 1 ... if successful,
 *          0 ... otherwise.
 */
int Rast3d_tile_load(RASTER3D_Map *map, int tileIndex)
{
    if (Rast3d_get_tile_ptr(map, tileIndex) == NULL) {
        Rast3d_error("Rast3d_tile_load: error in Rast3d_get_tile_ptr");
        return 0;
    }
 
    return 1;
}
 
/*---------------------------------------------------------------------------*/
 
int Rast3d__remove_tile(RASTER3D_Map *map, int tileIndex)
{
    if (!map->useCache)
        return 1;
 
    if (!Rast3d_cache_remove_elt(map->cache, tileIndex)) {
        Rast3d_error("Rast3d_removeTile: error in Rast3d_cache_remove_elt");
        return 0;
    }
 
    return 1;
}