readdi(3G)
readdi - reads a rectangular screen region, returning displayed pixel colors in a packed RGB format.
As shipped in IRIX 6.5.19. Unchanged since IRIX 6.5.
NAME readdi - reads a rectangular screen region, returning displayed pixel colors in a packed RGB format. FORTRAN 77 SPECIFICATION subroutine readdi(x1, y1, x2, y2, newx, integer*4 x1, y1, x2, y2, hints integer*4 parray(*) PARAMETERS x1 expects the x screen coordinate of one corner of the rectangle. y1 expects the y screen coordinate of one corner of the rectangle. x2 expects the x screen coordinate of the opposite corner of the rectangle. y2 expects the y screen coordinate of the opposite corner of the rectangle. These coordinates are relative to the lower-left pixel on the screen, whose coordinates are 0,0. It does not matter whether x1 is greater than or less than x2, nor y1 greater than or less than y2. The rectangle specification is inclusive. Thus the rectangle specified by coordinates 5,10,14,6 is 10 pixels wide and 5 pixels high. parray expects the array that is to receive the pixels that are read. Pixels are returned in packed ABGR format, with red occupying the lower 8 bits and alpha (if available) occupying the upper 8 bits. Returned alpha is one (0xff) if the pixel is in color index mode or if no alpha bitplanes are present. Return order is left-to- right, then bottom-to-top, i.e. 6 7 8 3 4 5 0 1 2 hints hints is an unsigned long passed to readdi which serves as a bit mask for enabling the various readdi modifiers delineated in the list of constants below. The constants are specified by bitwise ORing them, or by adding them. For example, readdi(0,0,99,99,parray,(RDFREZ + RDALPH)) blocks graphics while reading the display and returns an image in which alpha is equal to one. These modifiers are hints, not directives, and are therefore ignored by systems that do not support the requested feature. The following hints are available: RDFREZ freezes the screen by blocking all graphics calls until the read is completed. This assures that the returned data accurately represents what was being displayed at the time of the call. If graphics calls are allowed to proceed while readdi is executing, it is possible that the returned data may not resemble what was displayed at the time of execution, since drawing commands and commands that affect the display state ( etc.) can change the displayed data while it is being read. RDALPH returns all alpha values set to one (represented as 0xff in the color space of this command). If not requested, actual alpha values are returned if alpha planes are installed and the pixel is in RGB mode. One (0xff) is returned for pixels in color index mode or if no alpha planes are installed. RDIGPU ignores the contents of the pop-up framebuffer. RDIGOV ignores the contents of the overlay framebuffer. RDIGOV ignores the contents of the underlay framebuffer. RDOFFS Data read beyond the framebuffer boundary is returned equal to zero, regardless of the setting of this hint. Reading beyond the framebuffer boundary may reduce performance. DESCRIPTION readdi generates the displayed value of each addressed pixel, taking into account all display bitplanes and modes except those of the cursor. The ABGR values returned therefore correspond to the values viewed on the monitor, with the following exceptions: 1. The returned values are not gamma corrected. 2. The cursor will not appear in the returned data. 3. If either of the hints RDIGUN, RDIGOV, or RDIGPU is set, the corresponding framebuffer data will not be included in the returned data. FUNCTION RETURN VALUE readdi returns the number of pixels read. NOTES This subroutine is available only in immediate mode. BUGS On IRIS-4D VGX and VGXT models, readdi does not correctly read the underlay planes when the program is double buffered.