The IDLgrBuffer::QueryRequiredTiles function method is used in conjunction with an IDLgrImage object that supports tiling. Initially, this type of IDLgrImage object contains no data. Call this method to determine what data to load into this destination object based on which tiles are visible in a view. Pass the results to IDLgrImage::SetTileData to load the required portion of the tiled image. When the Draw method is called, the destination object contains the image tiles that are the results of this method’s query.

This method returns an array of named structures containing information about the tiles that are required, or a scalar integer with the value 0 if no tiles are required. The application can check that COUNT is greater than 0 before accessing the returned array.

Note: If the device is in Color Index mode (COLOR_MODEL=1) or the image has RENDER_METHOD=1 set, then IDL will generate an error as tiling is not supported under these circumstances.

Syntax


Result = Obj->[IDLgrBuffer::]QueryRequiredTiles( View, Image [, ALL_VISIBLE=value] [, COUNT=variable] [, PATH=objref(s)])

Return Value


Returns an array of named structures containing information about the tiles that are required, or a scalar integer with the value 0 if no tiles are required.

Each structure in the array describes one required tile and has the following fields:

Field

Data Type

Description

X

Long

The horizontal position of the left side of the tile measured from the left of the image in pixels.

Y

Long

The vertical position of the bottom of the tile measured from the bottom of the image in pixels.

WIDTH

Long

The width of the tile in pixels.

HEIGHT

Long

The height of the tile 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 was used to query for the required tiles.

The X, Y, WIDTH and HEIGHT elements are all relative to the specified LEVEL. For example, say a large image (level 0) has dimensions of 10000 by 10000 pixels. The tile structure [2048, 2048, 1024, 1024, 0] specifies a 1024 by 1024 pixel area where the lower-left corner of the tile is (2048, 2048) pixels from the lower-left corner of the original, level 0 image. This is shown in the left portion of the following figure.

When you zoom out to 50% of the original resolution, you can load the level 1 image (5000 by 5000 pixels), a subsampled version of the large image. Here, the tile [1024, 1024, 1024, 1024, 1] specifies a 1024 by 1024 pixel area of the image with the lower-left corner being (1024, 1024) from the lower-left corner of the image. Both of these tiles have their lower-left corner at the same physical location of the image, but the second tile covers four times the area as it is a lower resolution version of the data.

Arguments


View

An object reference to the IDLgrView object used to render the image object. This is required so the visible tiles can be determined.

Image

An object reference to the tiled IDLgrImage object that will be tested to determine which of its tiles are required.

Keywords


ALL_VISIBLE

Set this keyword if QueryRequiredTiles should return all tiles that are visible even if they already have tile data loaded at the required level.

COUNT

Set this keyword equal to a named variable that, on return, contains the number of tiles that are required.

PATH

Set this keyword equal to a vector of object references that uniquely defines the path through the graphics hierarchy used to compute which tiles are visible. Each object specified must contain an alias; tile visibility is computed for the version of the image object (specified by Image) that lies at the end of the specified path.

Specifying a unique path through the graphics hierarchy may require multiple objects if multiple aliases are used. If multiple objects are required to define the value of PATH, the objects must be specified in the order they appear in the path, beginning with the object that is closest to the root of the hierarchy.

If this keyword is not set, the path from Image to the top of the graphics hierarchy is determined by the PARENT properties of the objects in the hierarchy. In this case, no alias paths are followed.

Note: For more information on aliases, refer to the ALIAS keyword in IDLgrModel::Add.

Version History


6.2

Introduced

7.0

Added PATH keyword to QueryRequiredTiles to handle aliases.