THE EMULATION LAYER

Previous versions of the tsmApi used a server-based paradigm as its central model. That is, you specified a particular tile set server to connect to and you could then only manipulate datasets on that server. The new tsmApi uses a connection-based paradigm so that you can manipulate any dataset on any server.

The advantages of this new connection oriented model are:

1. Cleaner interface that integrates with DPSS model more tightly and naturally.
2. Can access any number of datasets, on any server, and using any protocol (file, http, x-dpss).
3. Can now maintain state with a connection thus eradicating lots of global variables and allowing more efficent file and memory handling.
4. The library becomes more thread safe.

Most of the old tsmApi routines are still available in the current API and have been rewritten so that they take advantage of the new API calls. These functions are the emulation layer that sits on top of the new tsmApi in order to provide backward compatibility with the old server-centric model. In general, functions that begin tsmOpen/Close, and tsmGet/Put are part of the old API, whilst functions that begin tsmConnect/Disconnect and tsmRead/Write are part of the new API.

For those who have used the old tsmApi, the following two code segments illustrate how you used to access data with the old API, and how you should access data now.

   TsmHandle *tsmh;
   Pyramid   *pyramid;
   uchar     *tileBuffer;

   tsmh = tsmOpen( "~magic/TileSets" );
   pyramid = tsmGetPyramid( tsmh, "yosemite.oi" );
   tileBuffer = tsmMakeTileBuffer( pyramid );
   tsmGetTile( tsmh, pyramid, 0, 0, 2, tileBuffer );
   /* Do your tile processing here */
   free( tileBuffer );
   tsmFreePyramid( pyramid );
   tsmClose( tsmh );

   TsmConnection *connect;
   uchar         *tileBuffer;

   connect = tsmConnect( "~magic/TileSets/Pyramids/yosemite.oi" );
   tsmAllocReadTile( connect, 0, 0, 2, &tileBuffer );
   /* Do your tile processing here */
   tsmFreeTileBuffer( tileBuffer );
   tsmDisconnect( connect );

N.B. Although the old API is mostly emulated under the new tsmApi, you should endeavor to rewrite any critical code using the new API as this will be more efficient and will continue to be supported. In particular, the following old functions are not emulated in the new tsmApi:

tsmReOpen, tsmNumServers, tsmReGetGeoPyramid, tsmReGetPyramid, tsmGetAllGeoPyramids, tsmGetAllPyramids, tsmPrepareForDataSets, tsmChangeGeoPyramids, tsmGetNextTileHeader, tsmGetNextTileData, tsmSetGetTileFlag, tsmGetGetTileFlag, tsmSetUseNewTileFlag, tsmGetUseNewTileFlag, tsmSetReadTileFormat, tsmGetReadTileFormat, tsmGetTileJFIF, tsmStartLogging, tsmStopLogging, tsmSetJPEGQuality, tsmGetJPEGQuality, tsmSetHttpToLocalFile, tsmImg2Tile, tsmDem2Tile.

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