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