GRASS GIS 8 Programmer's Manual  8.4.0dev(2024)-9b28d7b83c
tileio.c
Go to the documentation of this file.
1 #include <stdio.h>
2 #include <stdlib.h>
3 #include <sys/types.h>
4 #include <unistd.h>
5 #include "raster3d_intern.h"
6 
7 /*---------------------------------------------------------------------------*/
8 
9 /*---------------------------------------------------------------------------*/
10 
11 /* EXPORTED FUNCTIONS */
12 
13 /*---------------------------------------------------------------------------*/
14 
15 /*---------------------------------------------------------------------------*/
16 
17 /*!
18  * \brief
19  *
20  * This function
21  * returns a pointer to a tile which contains the data for the tile with index
22  * <em>tileIndex</em>. The type of the data stored in the tile depends on the
23  * type specified at the initialization time of <em>map</em>. The functionality
24  * is different depending on whether <em>map</em> is old or new and depending on
25  * the cache-mode of <em>map</em>.<br>
26  *
27  * If <em>map</em> is old and the cache is not used the tile with
28  * <em>tileIndex</em> is read from file and stored in the buffer provided by the
29  * map structure. The pointer to this buffer is returned. If the buffer already
30  * contains the tile with <em>tileIndex</em> reading is skipped. Data which was
31  * stored in earlier calls to <tt>Rast3d_get_tile_ptr</tt> is destroyed. If the
32  * tile with <em>tileIndex</em> is not stored on the file corresponding to
33  * <em>map</em>, and <em>tileIndex</em> is a valid index the buffer is filled
34  * with NULL-values.<br>
35  *
36  * If <em>map</em> is old and the cache is used the tile with <em>tileIndex</em>
37  * is read from file and stored in one of the cache buffers. The pointer to
38  * buffer is returned. If no free cache buffer is available an unlocked
39  * cache-buffer is freed up and the new tile is stored in its place. If the
40  * tile with <em>tileIndex</em> is not stored on the file corresponding to
41  * <em>map</em>, and <em>tileIndex</em> is a valid index the buffer is filled
42  * with NULL-values. If one of the cache buffers already contains the tile with
43  * <em>tileIndex</em> reading is skipped and the pointer to this buffer is
44  * returned.<br>
45  *
46  * If <em>map</em> is new and the cache is not used the functionality is the
47  * same as if <em>map</em> is old and the cache is not used. If the tile with
48  * <em>tileIndex</em> is already stored on file, it is read into the buffer, if
49  * not, the cells are set to null-values. If the buffer corresponding to the
50  * pointer is used for writing, subsequent calls to <tt>Rast3d_get_tile_ptr</tt>
51  * may destroy the values already stored in the buffer. Use
52  * <tt>Rast3d_flush_tile</tt> to write the buffer to the file before reusing it
53  * for a different index. The use of this buffer as write buffer is
54  * discouraged.<br>
55  *
56  * If <em>map</em> is new and the cache is used the functionality is the same as
57  * if <em>map</em> is old and the cache is used with the following exception. If
58  * <em>tileIndex</em> is a valid index and the tile with this index is not found
59  * in the cache and is not stored on the file corresponding to <em>map</em>,
60  * then the file cache is queried next. If the file-cache contains the tile it
61  * is loaded into the cache (memory-cache). Only if the file-cache does not
62  * contain the tile it is filled with NULL-values. Tile contents of buffers are
63  * never destroyed. If a cache buffer needs to be freed up, and the tile stored
64  * in the buffer has not been written to the file corresponding to <em>map</em>
65  * yet, the tile is copied into the file-cache.<br>
66  *
67  * Care has to be taken if this function is used in non-cache mode since it is
68  * implicitly invoked every time a read or write request is issued. The only
69  * I/O-functions for which it is safe to assume that they do not invoke
70  * <tt>Rast3d_get_tile_ptr</tt> are <tt>Rast3d_read_tile()</tt> and
71  * <tt>Rast3d_write_tile()</tt> and their corresponding type-specific versions.
72  *
73  * \param map
74  * \param tileIndex
75  * \return void * a pointer to a buffer ... if successful,
76  * NULL ... otherwise.
77  */
78 
79 void *Rast3d_get_tile_ptr(RASTER3D_Map *map, int tileIndex)
80 {
81  void *ptr;
82 
83  if ((tileIndex >= map->nTiles) || (tileIndex < 0)) {
84  Rast3d_error("Rast3d_get_tile_ptr: tileIndex out of range");
85  return NULL;
86  }
87 
88  if (map->useCache) {
89  ptr = Rast3d_cache_elt_ptr(map->cache, tileIndex);
90  if (ptr == NULL) {
91  Rast3d_error("Rast3d_get_tile_ptr: error in Rast3d_cache_elt_ptr");
92  return NULL;
93  }
94  return ptr;
95  }
96 
97  if (map->currentIndex == tileIndex)
98  return map->data;
99 
100  map->currentIndex = tileIndex;
101  if (!Rast3d_read_tile(map, map->currentIndex, map->data, map->typeIntern)) {
102  Rast3d_error("Rast3d_get_tile_ptr: error in Rast3d_read_tile");
103  return NULL;
104  }
105 
106  return map->data;
107 }
108 
109 /*---------------------------------------------------------------------------*/
110 
111 /*!
112  * \brief
113  *
114  * Same functionality as <tt>Rast3d_get_tile_ptr()</tt> but does not return the
115  * pointer.
116  *
117  * \param map
118  * \param tileIndex
119  * \return 1 ... if successful,
120  * 0 ... otherwise.
121  */
122 
123 int Rast3d_tile_load(RASTER3D_Map *map, int tileIndex)
124 {
125  if (Rast3d_get_tile_ptr(map, tileIndex) == NULL) {
126  Rast3d_error("Rast3d_tile_load: error in Rast3d_get_tile_ptr");
127  return 0;
128  }
129 
130  return 1;
131 }
132 
133 /*---------------------------------------------------------------------------*/
134 
135 int Rast3d__remove_tile(RASTER3D_Map *map, int tileIndex)
136 {
137  if (!map->useCache)
138  return 1;
139 
140  if (!Rast3d_cache_remove_elt(map->cache, tileIndex)) {
141  Rast3d_error("Rast3d_removeTile: error in Rast3d_cache_remove_elt");
142  return 0;
143  }
144 
145  return 1;
146 }
#define NULL
Definition: ccmath.h:32
int Rast3d_cache_remove_elt(RASTER3D_cache *, int)
Definition: cache1.c:410
int Rast3d_read_tile(RASTER3D_Map *, int, void *, int)
Reads tile with index tileIndex into the tile buffer. The cells are stored with type type which must ...
Definition: tileread.c:151
void Rast3d_error(const char *,...) __attribute__((format(printf
void * Rast3d_cache_elt_ptr(RASTER3D_cache *, int)
Definition: cache1.c:468
int currentIndex
Definition: raster3d.h:156
char * data
Definition: raster3d.h:153
void * cache
Definition: raster3d.h:161
int useCache
Definition: raster3d.h:160
int typeIntern
Definition: raster3d.h:150
void * Rast3d_get_tile_ptr(RASTER3D_Map *map, int tileIndex)
This function returns a pointer to a tile which contains the data for the tile with index tileIndex....
Definition: tileio.c:79
int Rast3d_tile_load(RASTER3D_Map *map, int tileIndex)
Same functionality as Rast3d_get_tile_ptr() but does not return the pointer.
Definition: tileio.c:123
int Rast3d__remove_tile(RASTER3D_Map *map, int tileIndex)
Definition: tileio.c:135