 |
| |
The TVRD function returns the contents of the specified rectangular portion of the current graphics window or device. ( X 0 , Y 0 ) is the coordinate of the lower left corner of the area to be read and N x , N y is the size of the rectangle in columns and rows. The result is a byte array of dimensions N x by N y . All parameters are optional. If no arguments are supplied, the entire display device area is read.
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 .
The number of columns to read. The default is the width of the display device or window less X 0 .
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.
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.
If this keyword is present, it indicates that a true-color 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, n x , n y ) pixel-interleaved array if TRUE is 1; or an ( n x , 3, n y ) line-interleaved array if TRUE is 2; or an ( n x , n y , 3) image-interleaved array if TRUE is 3.
When using TVRD with the X Windows graphics device, there are two unexpected behaviors that can be confusing to users:
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 simply 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:
For a full description of backing store, See Backing Store . 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.