IDLgrImage::SetTileData

The IDLgrImage::SetTileData procedure method stores tile data in the IDLgrImage tile data cache. If a tile has data loaded but not for the required level, the data associated with the next highest available level will be used instead. Otherwise, IDLgrImage renders the tile using the solid color specified by TILE_COLOR. An error is generated if any of the parameters are invalid. All units are in terms of pixels.

All image data tiles stored into the image object with SetTileData must be passed in arrays with consistent dimensions. That is, the number of channels and the interleave format must be the same for all tile data arrays. For example, if one tile is stored in an array with dimensions [3,200,340], then all other tile data arrays must have three dimensions where the first dimension value, the number of channels, is always 3. The other two dimension values, the width and height, can vary to express the tile size.

The first call to SetTileData after the object is created or after a call to DeleteTileData with the ALL keyword set determines the tile data array format to be used for all subsequent tiles. IDL generates an error if a tile data array is submitted with an inconsistent array format.

If data has already been set for the specified tile, it will be replaced by the data in the subsequent call to SetTileData.

Note: When you call IDLgrImage::SetProperty after calling SetTileData, and then draw the tiles, the image data may not be displayed. If you set an image property with SetProperty, IDL may update the image data and delete any tiles that were previously stored with the SetTileData method. If this occurs, set image properties before using SetTileData, or set image properties and then call QueryRequiredTiles to reacquire the tiles before setting and drawing the tiles.

Syntax

Obj->[IDLgrImage::]SetTileData, TileInfo, TileData [, NO_FREE=value]

Arguments

TileInfo

A named structure describing the tile or tiles for which the data is being set. The structures returned by the destination object’s QueryRequiredTiles method can be passed directly (one at a time) to SetTileData along with the corresponding tile data.

This structure contains the following fields:

Field	Data Type	Description
X	Long	The horizontal position of the left side of the tile(s) measured from the left of the image in pixels.
Y	Long	The vertical position of the bottom of the tile(s) measured from the bottom of the image in pixels.
WIDTH	Long	The width of the tile(s) in pixels.
HEIGHT	Long	The height of the tile(s) in pixels.
LEVEL	Long	The data resolution, where 0 is the full resolution image. A value of n (n > 0) indicates that the resolution is half that of the n-1 level.
DEST	OBJREF	The object reference to the destination object that displays the tiled IDLgrImage.

If a region of the image composed of multiple tiles is being set, X, Y, WIDTH, and HEIGHT must be multiples of the tile size (unless the region extends to the edge of the image in which case Width and Height do not need to be a multiple of the tile size).

TileData

The data for the specified tile.

Keywords

NO_FREE

Set this keyword if the tile data should remain loaded for the lifetime of the IDLgrImage, unless explicitly deleted by the DeleteTileData method. If the tile cache fills up, IDLgrImage might automatically delete the least recently used tile data from the cache to make room for new tile data. Setting this keyword prevents the IDLgrImage from automatically deleting this tile data in this situation.

Version History

6.2	Introduced