graPHIGS Programming Interface: Subroutine Reference

The graPHIGS Programming Interface : Subroutine Reference

GPRDFB - Read Frame Buffer

GPRDFB (wsid, frame, sorigin, size, format, parm, torigin, data)

Purpose

Use GPRDFB to read pixel data from one of the workstation's frame buffer components into your target application image data. The specified bit depth of your target application image data must match the bit depth of the workstation's frame buffer component that contains the pixel data.

Use the Inquire Frame Buffer Characteristics (GPQFBC) inquiry subroutine to determine your workstation's frame buffer characteristics, in particular the bit depth of the workstation's frame buffer components.

The specified target rectangle need not be inside the target application image, but any portion of the target rectangle outside the image will be clipped. The pixel data returned is workstation dependent when all or part of the source rectangle is not visible. It is the application's responsibility to serialize access to the workstation during the read frame buffer operation. This means that other application processes should not attempt to modify the workstation while the read frame buffer is being performed. To guarantee the state of the frame buffer that is returned by this subroutine call (i.e., to ensure that all pending updates are in the returned data), the application should issue an Update Workstation (GPUPWS) subroutine before issuing this function.

This subroutine is assigned escape identifier 1007.

Note:

This subroutine is an escape subroutine and therefore may not be available on all workstations. Use the Inquire List of Available Escape Subroutines (GPQES) subroutine to determine if this subroutine is supported by an open workstation. If not supported, an error will be generated.

Parameters

wsid -- specified by user, fullword integer

Workstation identifier.

frame -- specified by user, fullword integer

Frame buffer component number. This parameter must be a valid frame buffer component of the workstation.

sorigin -- specified by user, two fullword integers

Source rectangle origin (x, y) (>=0)

size -- specified by user, two fullword integers

Rectangle size (SX, SY) (>=1)

format -- specified by user, fullword integer

Application image format (1=PIXEL_ARRAY )

parm -- specified by user, variable data

Format dependent parameters. The image format 1 requires the following parameters:

bit depth -- fullword integer (1, 2, 4, 8, or 16) This bit depth must match the frame buffer component bit depth.

x size -- fullword integer (>=1)

y size -- fullword integer (>=1)

pixel order -- fullword integer (1=LEFT_RIGHT_BOTTOM_TOP,2=LEFT_RIGHT_TOP_BOTTOM )

The product of the x size and the bit depth must to a multiple of 8. This is to ensure that each row of the application's image data starts on a byte boundary.

torigin -- specified by user, two fullword integers

Target rectangle origin (x, y) (>=0)

data -- returned by the graPHIGS API, array of pixels

Target application image data. The graPHIGS API returns the pixels within the intersection of the target application image data and the target rectangle.

The target application image data with bit depth of 16 will be handled as 16-bit halfwords. For all other bit depths, the application image data will be treated as 8-bit unsigned characters.

Error Codes

25: SPECIFIED WORKSTATION DOES NOT EXIST
119: FRAME BUFFER COMPONENT NUMBER IS INVALID
236: RECTANGLE DEFINITION IS INVALID
237: SPECIFIED APPLICATION IMAGE FORMAT IS NOT SUPPORTED
240: APPLICATION IMAGE DESCRIPTION IS INVALID
526: REQUESTED DATA NOT AVAILABLE FOR THIS FUNCTION
527: ESCAPE FUNCTION NOT AVAILABLE

Related Subroutines

GPQAI: Inquire List of Available Application Image Formats
GPQFBC: Inquire Frame Buffer Characteristics
GPQIBC: Inquire Image Board Characteristics
GPQIBF: Inquire Image Board Facilities
GPQIMC: Inquire Image Mapping Characteristics
GPQIMF: Inquire Image Mapping Facilities

RCP code

201346312 (X'0C004D08')