rectwrite or lrectwrite Subroutine

Purpose

Draws a rectangular array of pixels into the frame buffer.

Libraries

Graphics Library

C (libgl.a)

FORTRAN (libfgl.a)

C Syntax

void rectwrite
(Screencoord xll, Screencoord yll, 
Screencoord xur, Screencoord yur,
Int16 *parray)

void lrectwrite
(Screencoord xll, Screencoord yll, 
Screencoord xur, Screencoord yur, 
Int32 *parray)

FORTRAN Syntax

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

SUBROUTINE LRECTW(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 invoked from a FORTRAN program, although they accept short integers when invoked from a C program. The C and FORTRAN syntax shown here reflect this difference.

Description

The rectwrite and lrectwrite subroutines draw pixels taken from the host array specified in the parray parameter into the specified rectangular framebuffer region. Both procedures are functionally the same. They differ only in that the rectwrite subroutine expects 16-bit values, and the lrectwrite subroutine expects 32-bit values. The system draws pixels left to right, then bottom to top. All normal drawing modes apply.

When the frame buffer is configured to be 8 bits deep, only the lowest 8 bits of the parray parameter are used to fill the frame buffer. If the frame buffer has been configured to be 12 bits deep (for example, if the system is in color map, singlemap, doublebuffer mode), only the lowest 12 bits are written. If the frame buffer has been configured to be 24 bits deep (for instance, in singlebuffer RGB mode), only the lowest 24 bits are written.

Because of the foregoing reasons, using the rectwrite subroutine in 24-bit mode is not logical. Use the lrectwrite subroutine instead. Likewise, do not use the rectwrite subroutine to write into the z-buffer.

In a similar manner, these subroutines can be used to write into the overlay or underlay planes. Note that not all supported graphics adapters have 24-bit-deep frame buffers or have z-buffers.

Note: Both the rectwrite and lrectwrite subroutines leave the current character position unpredictable.

If the zoom factors set by the rectzoom subroutine are both 1.0, the screen region xll through xur, yll through yur, are filled. Other zoom factors result in filling past xur and/or past yur (xll, yll is always the lower left corner of the filled region).

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

1. 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.
2. These subroutines cannot be used to add to a display list.

Parameters

Implementation Specifics

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

Files

Related Information

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

Controlling the transfer of pixels with the pixmode subroutine.

Reading a rectangular array of pixels into host memory with the rectread or lrectread subroutine.

Specifying a zoom factor for rectangle copies and writes with the rectzoom subroutine.

AIX Graphics Library Overview, Reading and Writing Pixels, Configuring the Frame Buffer, and Working in Color Map and RGB Modes.