readdisplay(3G)
readdisplay - reads a rectangular screen region, returning displayed pixel colors in a packed RGB format.
As shipped in IRIX 6.5.22. Unchanged since IRIX 6.5.
NAME readdisplay - reads a rectangular screen region, returning displayed pixel colors in a packed RGB format. C SPECIFICATION long readdisplay(Screencoord x1, Screencoord y1, Screencoord x2, Screencoord y2, unsigned long *parray, unsigned long *hints) 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 readdisplay which serves as a bit mask for enabling the various readdisplay modifiers delineated in the list of constants below. The constants are specified by bitwise ORing them, or by adding them. For example, readdisplay(0,0,99,99,parray,(RD_FREEZE+RD_ALPHAONE)); 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: RD_FREEZE 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 readdisplay 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. RD_ALPHAONE 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. RD_IGNORE_PUP ignores the contents of the pop-up framebuffer. RD_IGNORE_OVERLAY ignores the contents of the overlay framebuffer. RD_IGNORE_UNDERLAY ignores the contents of the underlay framebuffer. RD_OFFSCREEN 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 readdisplay 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 RD_IGNORE_UNDERLAY, RD_IGNORE_OVERLAY, or RD_IGNORE_PUP is set, the corresponding framebuffer data will not be included in the returned data. FUNCTION RETURN VALUE readdisplay returns the number of pixels read. NOTES This subroutine is available only in immediate mode. BUGS On IRIS-4D VGX and VGXT models, readdisplay does not correctly read the underlay planes when the program is double buffered.