tsmApi: Tutorial


READING TILES WITH MANUAL BUFFER ALLOCATION

We saw in the previous tutorial how you can read tiles from a connection. This involved the tsmApi managing all of the tile and header buffers for you. There are alternative forms of the tile reading functions that will allow you to manage the allocation of tile buffers yourself. To enable this, we need a routine to allocate a tile buffer: 

   uchar *tileBuffer;

   tileBuffer = tsmAllocTileBuffer( connect );
   /* do some tile buffer manipuations */
   tsmFreeTileBuffer( tileBuffer );

We now have two new calls: tsmReadTile (the counterpart of tsmAllocReadTile), and tsmReadNextTile (the counterpart of tsmAllocReadNextTile). You can use these calls anywhere where you might previously have used tsmAllocReadTile or tsmAllocReadNextTile. For example, the following code segment will use tsmReadTile to read a single tile from a dataset after allocating it in the program: 

   connect = tsmConnect( name, "r", NULL );
   tileBuffer = tsmAllocTileBuffer( connect );
   tsmReadTile( connect, 0, 0, 1, tileBuffer );
   /* Do some processing on the tile buffer */
   tsmFreeTileBuffer( tileBuffer );
   tsmDisconnect( connect );
As before, we also build request lists of tiles and have these read into tile header and data buffers that we have already allocated. For example: 
   TsmTileHeader *tileHeader;
   uchar         *tileBuffer;

   tsmTileReqBegin( connect );
   tsmTileReqAdd( connect, 0, 0, 2, TSM_NOW );
   /* any more tsmTileReqAdd calls */
   tsmTileReqEnd( connect );  /* sends the request list */

   tileHeader = tsmAllocTileHeader();
   tileBuffer = tsmAllocTileBuffer();

   tsmReadNextTile( connect, tileHeader, tileBuffer );
   /* more tsmReadNextTile calls to read in all tiles */
These function calls are provided largely for legacy reasons. It is advised that you use the tsmAllocRead* versions which allow tsmApi to handle the tile allocation for you. This latter scheme of reading data offers a number of advantages, e.g.
  1. If data is retrieved within tsmApi using multi-threaded tile readers, then the tsmAllocRead calls allow tsmApi to efficiently manage tile buffers, prefetch data, and avoid costly memory copy operations.
  2. tsmApi is free to choose efficent memory allocation schemes that will benefit your application
  3. You do not need to worry about allocating memory (just freeing it when you are finished with it).
  4. tsmApi can be clever and reuse tile buffers, i.e. just because the function is called tsmAllocReadTile doesn't mean that it is allocating a new tile buffer every time. When you call tsmFreeTileBuffer tsmApi could recycle that buffer for later use.
  5. Your code becomes less cluttered.

Next Tutorial: Copying Data
Previous Tutorial: Reading Tiles From a Dataset
Manual Page References: tsmReadTile, tsmReadNextTile

Back to The tsmApi Home Page / The tsmApi Tutorials Page

Martin Reddy, <reddy@ai.sri.com> / Yvan Leclerc, <leclerc@ai.sri.com>
Last modified: Wed Aug 23 00:45:22 PDT 2000