This section describes how to retrieve the information stored in an image.

The TVRD function reads the contents of the display device memory back into a variable. One use for this capability is to build up a complex display using many statements, and then read the resulting image back as a single unit for storage in a file.

The TVRD function returns the contents of the specified rectangular portion of the display subsystem’s memory. For example, if (X0 and Y0) are the starting column and row, respectively, of the data to be read, and Nx and Ny are the number of columns and rows to read, then an Nx-by-Ny byte array can be stored in the variable new_image with the command:

new_image = TVRD(X0, Y0, Nx, Ny)

If the system variable !Order is set to 0 then data are read from the bottom up, otherwise data are read from the top down.

The following statement inverts the 100-by-100 area of the display starting at coordinate position (200, 300):

; Reverse area.

TV, NOT TVRD(200, 300, 100, 100)

The following example copies part of an image, then resizes and displays the copied portion:

x=dist(300)

tvscl,x

x_rd=tvrd(0,0,150,150)

erase

tv,x_rd

tv,rebin(x_rd,300,300)

Not all image devices are able to support reading pixels back from device memory. If the current device has this ability, PV‑WAVE sets the eighth bit of !D.Flags. The following statement can be used to determine if the current device allows reading from display memory:

TEST = !D.Flags AND 128

TEST will be nonzero if the device allows such operations.

The TVCRS procedure manipulates the cursor of the image display. Normally, the cursor is disabled and is not visible. Supplying TVCRS with one parameter enables or disables the cursor; supplying TVCRS with two parameters enables the cursor and places it on pixel location (x, y).

TVCRS also takes various keywords that affect how it positions the cursor. Notably, the keywords Data, Device, and Normal specify the coordinate system. For details, see the entry for TVCRS in the PV‑WAVE Reference.