rectread or lrectread Subroutine

Purpose

Reads a rectangular array of pixels into host memory.

Libraries

Graphics Library

C (libgl.a)

FORTRAN (libfgl.a)

C Syntax

Int32 rectread
(Screencoord xll, Screencoord yll,
Screencoord xur, Screencoord yur,
Int16 *parray)

Int32 lrectread
(Screencoord xll, Screencoord yll,
Screencoord xur, Screencoord yur,
Int32 *parray)

FORTRAN Syntax

INTEGER*4 RECTRE(xll, yll, xur, yur, parray)
INTEGER*4 xll, yll, xur, yur
INTEGER*2 parray(1)

INTEGER*4 LRECTR(xll, yll, xur, yur, parray)
INTEGER*4 xll, yll, xur, yur, parray(1)

Note: For FORTRAN users, these subroutines accept long integer parameters (INTEGER*4) when started from a FORTRAN program, although they accept short integers when started from a C program. The C and FORTRAN syntax shown here reflect this difference.

Description

The rectread and lrectread subroutines each return a rectangular array of 16- and 32-bit pixels, respectively, to the host array specified in the parray parameter. For the lrectread subroutine, the parray parameter contains 32-bit packed RGB, RGBA, or z values. The returned value of this function is the number of pixels that the system actually reads, left to right, then bottom to top. The returned function value is 0 (zero) if any part of the specified rectangle is off the screen.

The returned data is undefined if the xll and yll parameters do not specify the lower-left corner of a rectangle that appears completely on the screen. All coordinates are relative to the lower left corner of the window and not to the screen or viewport.

When performing operations with the lrectread subroutine on the POWER Gt4 and POWER Gt4x in RGBmode with a specified pixel size of 32, pixels are returned with one 24-bit pixel packed in a 32-bit word. The high-order byte (the A byte) is set to the value 0xff.

The readsource subroutine specifies the pixel source from which the pixels are read.

The behavior of the lrectread subroutine is modified by the attributes set with the pixmode subroutine. Please refer to the pixmode subroutine for more detail.

1. Both the rectread and lrectread subroutines leave the current character position unpredictable.
2. Do not put the pixel array on the stack. Allocate the memory space for the pixel array dynamically, by using the malloc or calloc command (that is, place it on the heap), or specify it as a static variable. Do not specify the pixel array memory space as a block scope variable.
3. These subroutines cannot be used to add to a display list.

Parameters

All coordinates are relative to the lower-left corner of the window and not to the screen or viewport.

Return Value

The returned value of this function is the number of pixels that the system actually reads. The returned function value is 0 (zero) if any part of the specified rectangle is off the screen.

On the POWER GXT1000 adapter, the returned value of this function is always the width times height of the specified rectangle, or (xur - xll)(yur - yll).

Example

The example C language program paint.c uses the rectread subroutine to get the color index value for a single pixel.

Implementation Specifics

This subroutine is part of GL in the AIXwindows Environment/6000 Version 1, Release 2 with AIXwindows/3D Feature.

Files

Related Information

Specifying the source for pixels to be read with the readsource subroutine.

Controlling the transfer of pixels with the pixmode subroutine.

Copying a rectangle of pixels with an optional zoom with the rectcopy subroutine.

Drawing a rectangular array of pixels into the frame buffer with the rectwrite or lrectwrite subroutine.

AIX Graphics Library Overview, Reading and Writing Pixels, Using Viewports and Screenmasks, and Working in Color Map and RGB Modes.