The TVRD function returns the contents of the specified rectangular portion of the current Direct Graphics window or device. (X0, Y0) is the coordinate of the lower left corner of the area to be read and Nx, Ny is the size of the rectangle in columns and rows. The result is a byte array of dimensions Nx by Ny. All parameters are optional. If no arguments are supplied, the entire display device area is read.
Important Note about TVRD and Backing Store
On some systems, when backing store is provided by the window system (the RETAIN keyword to DEVICE or WINDOW is set to 1), reading data from a window using TVRD may cause unexpected results. For example, data may be improperly read from the window even when the image displayed on screen is correct. Having IDL provide the backing store (set the RETAIN keyword to 2) ensures that the window contents will be read properly. More detailed notes about TVRD and the X Window system can be found below in Unexpected Results Using TVRD with X Windows.
Examples
T = TVRD()
To read from the display to an IDL variable or expression, use the TVRD function with either the CHANNEL parameter or TRUE keyword parameter. The calling sequence for TVRD is:
Result = TVRD([X0, Y0, Nx, Ny, Channel])
where (X0, Y0) specifies the window coordinate of the lower-left corner of the rectangle to be read, and (Nx, Ny) contains the number of columns and rows to read. Note that all parameters to TVRD are optional. If no arguments are supplied, the entire area of the display device is returned.
When used without the TRUE parameter, TVRD returns an (Nx, Ny) byte image read from the indicated channel. If the channel number is not specified or is zero, the maximum RGB value of each pixel is returned, approximating the luminance.
If present and nonzero, the TRUE keyword indicates that a TrueColor image is to be read and specifies the index of the dimension over which color is interleaved. The result is a (3, Nx, Ny) pixel interleaved array if TRUE is 1; or an (Nx, 3, Ny) line interleaved array if TRUE is 2; or an (Nx, Ny, 3) image interleaved array if TRUE is 3.
Some examples of TVRD follow.
R = TVRD(0, 0, 512, 512, 1)
T = TVRD(0, 0, 512, 512, TRUE = 2)
L = TVRD(0, 0, 512, 512)
Syntax
Result = TVRD( [X0 [, Y0 [, Nx [, Ny [, Channel]]]]] [, CHANNEL=value] [, /ORDER] [, TRUE={1 | 2 | 3}] [, /WORDS] )
Return Value
Returns a byte array of the specified dimensions.
Arguments
X0
The starting column of data to read. The default is 0.
Y0
The starting row of data to read. The default is 0.
Nx
The number of columns to read. The default is the width of the display device or window less X0.
Ny
The number of rows to read. The default is the height of the display device or window less Y0.
Channel
The memory channel to be read. If not specified, this argument is assumed to be zero. This parameter is ignored on display systems that have only one memory channel.
Keywords
CHANNEL
The memory channel to be read. The CHANNEL keyword is identical to the optional Channel argument.
Note: If the display is a 24-bit display, and both the CHANNEL and TRUE parameters are absent, the maximum RGB value in each pixel is returned.
ORDER
Set this keyword to override the current setting of the !ORDER system variable for the current image only. If set, it causes the image to be read from the top down instead of the normal bottom up.
TRUE
If this keyword is present, it indicates that a TrueColor image is to be read, if the display is capable. The value assigned to TRUE specifies the index of the dimension over which color is interleaved. The result is an (3, nx, ny) pixel-interleaved array if TRUE is 1; or an (nx, 3, ny) line-interleaved array if TRUE is 2; or an (nx, ny, 3) image-interleaved array if TRUE is 3.
Note: IDL returns the MAX of the three channels when you do TVRD without setting TRUE on a TrueColor system.
WORDS
Set this keyword to indicate that words are to be transferred from the device. This keyword is valid only when using devices that can transfer 16-bit pixels. The normal transfer uses 8-bit pixels. If this keyword is set, the function result is an integer array.
Unexpected Results Using TVRD with X Windows
When using TVRD with the X Windows graphics device, there are two unexpected behaviors that can be confusing to users:
- When reading from a window that is obscured by another window (i.e., the target window has another window “on top” or “in front” of it, or one window overlaps the target), TVRD may return the contents of the window in front as part of the image contained in the target window.
- When reading from an iconified window, the X server may return a stream of “BadMatch” protocol events.
IDL uses the Xlib function XGetSubImage() to implement TVRD. The following quote is from the documentation for XGetSubImage() found in The X Window System by Robert W. Scheifler and James Gettys, Second Edition, page 174. It explains the reasons for the behaviors described above:
“If the drawable is a window, the window must be viewable, and it must be the case that if there were no... overlapping windows, the specified rectangle of the window would be fully visible on the screen, ... or a BadMatch error results. If the window has backing-store, then the backing-store contents are returned for regions of the window that are obscured... If the window does not have backing-store, the returned contents of such obscured regions are undefined.”
Hence, the first behavior is caused by attempting to use TVRD on an obscured window that does not have backing store provided by the X server. The result in this case is undefined, meaning that the different servers can produce entirely different results. Many servers return the image of the obscuring window.
The second behavior is caused by attempting to read from a non-viewable (i.e., unmapped) window. Although IDL could refuse to allow TVRD to work with unmapped windows, some X servers return valid and useful results. Therefore, TVRD is allowed to attempt to read from unmapped windows.
Both of these behavior problems can be solved by using one of the following methods:
- Always make sure that your target window is mapped and is not obscured before using TVRD on it. The following IDL command can be used:
WSET, Window_Index
- Make IDL provide backing store (rather than the window system) by setting the RETAIN keyword to DEVICE or WINDOW equal to 2.
Note that under X Windows, backing store is a request that may or may not be honored by the X server. Many servers will honor backing store for 8-bit visuals but ignore them for 24-bit visuals because they require three times as much memory.
Version History
See Also
RDPIX Procedure, TV Procedure, WRITE_BMP