The IDLgrPrinter::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.

Note: Printer support of tiled images is not available in vector mode (when the IDLgrPrinter::Draw method VECTOR keyword is set to 1). The bitmap mode (VECTOR=0) must be used.

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.

Printers are normally a higher resolution than a monitor; therefore higher resolution levels will be requested when calling QueryRequiredTiles on an IDLgrPrinter. QueryRequiredTiles on IDLgrPrinter also considers the value in the IDL_GR_TILECACHESIZE preference when calculating the required level. If the data for the required tiles at the required level will not fit in IDL_GR_TILECACHESIZE, the next-lower resolution level will be tried. This is repeated until a level that fits is found and this is returned by QueryRequiredTiles. This can be overridden by setting TILE_LEVEL_MODE to 0 (manual) and setting the required level in TILE_CURRENT_LEVEL on the tiled IDLgrImage before calling QueryRequiredTiles. However, if the total data exceeds IDL_GR_TILECACHESIZE, then some tiles will print blank. If there is sufficient RAM in the system, IDL_GR_TILECACHESIZE can be increased to enable higher-resolution printing. Setting 0 will allow an unlimited amount of tile data to be set, but note that printing may fail if all physical RAM is used.

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.


Result = Obj->[IDLgrPrinter::]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:


Data Type




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



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



The width of the tile in pixels.



The height of the tile in pixels.



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.



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.



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


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



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


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


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




Added PATH keyword to QueryRequiredTiles to handle aliases.