[ Previous | Next | Contents | Glossary | Home | Search ]
GL3.2 for AIX: Graphics Library (GL) Technical Reference

readRGB Subroutine

Purpose

Returns values of specific pixels in RGB mode.

Libraries

Graphics Library

C (libgl.a)

FORTRAN (libfgl.a)

C Syntax

Int32 readRGB
(Int16 number, 
RGBvalue red[ ], RGBvalue green[ ], RGBvalue blue[ ])

FORTRAN Syntax

INTEGER*4 FUNCTION READRG(number, red, green, blue)
INTEGER*4 number
CHARACTER*(*) red, green, blue;
Note: For FORTRAN users, this function accepts long integer parameters (INTEGER*4) when invoked from a FORTRAN program, although it accepts short integers when invoked from a C program. The C and FORTRAN syntax shown here reflect this difference.

Description

The readRGB subroutine attempts to read specific pixel values from the frame buffer in RGB mode. The returned value of this function is the number of pixels actually read. A returned function value of 0 (zero) indicates that the starting point is not a valid character position.

The readRGB subroutine reads the pixel values into the arrays specified by the red, green, and blue parameters starting from the current character position along a single scan line (constant y) in the direction of increasing x.

The readRGB subroutine returns the number of pixels read, which is the number requested if the starting point is a valid character position (inside the current viewport). The subroutine returns 0 (zero) if the starting point is not a valid character position. The values of pixels read outside of the viewport or screenmask are undefined.

The readRGB subroutine updates the current character position to one pixel to the right of the last one read. The current character position is undefined if the new position is outside the viewport.

Use the readsource subroutine to specify which buffer is read. In RGB double buffer mode, by default the back buffer is read.

The rectread subroutine provides significantly better performance for pixel block transfers. Even when only one row of pixels needs to be read, use the rectread subroutine.

  1. This subroutine is available only in RGB mode. For new development, use the lrectread subroutine.
  2. This subroutine cannot be used to add to a display list.
  3. The use of this subroutine is deprecated. Do not use the readRGB subroutine in new development.

Parameters

number Specifies the number of pixels read by the function.
red Specifies the array in which the red pixel values will be stored.
green Specifies the array in which the green pixel values will be stored.
blue Specifies the array in which the blue pixel values will be stored.

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.

Implementation Specifics

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

Files

/usr/include/gl/gl.h Contains C language constant and variable type definitions for GL.
/usr/include/gl/fgl.h Contains FORTRAN constant and variable type definitions for GL.

Related Information

Returning the value of specific pixels in color map mode with the readpixels subroutine.

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

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

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

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

Painting a row of pixels on the screen in RGB mode with the writeRGB subroutine.

AIX Graphics Library Overview, Configuring the Frame Buffer, Creating Animated Scenes, Reading and Writing Pixels, Using Viewports and Screenmasks, and Working in Color Map and RGB Modes.


[ Previous | Next | Contents | Glossary | Home | Search ]