block_read(3G)

NAME

block_read, dcblock_read, intblock_read − frame buffer to main memory block transfer procedure.

SYNOPSIS

C Syntax:

void block_read(fildes,x_source,y_source,length_x,length_y,
pixel_data,raw);
int fildes;
float x_source,y_source;
int length_x,length_y,raw;
unsigned char pixel_data[];

void dcblock_read(fildes,x_source,y_source,length_x,length_y,
pixel_data,raw);
int fildes,x_source,y_source,length_x,length_y,raw;
unsigned char pixel_data[];

void intblock_read(fildes,x_source,y_source,length_x,length_y,
pixel_data,raw);
int fildes,x_source,y_source,length_x,length_y,raw;
unsigned char pixel_data[];

FORTRAN77 Syntax:

subroutine block_read(fildes,x_source,y_source,length_x,length_y,
pixel_data,raw)
integer*4 fildes
real x_source,y_source
integer*4 length_x,length_y,raw
character*(*) pixel_data()

subroutine dcblock_read(fildes,x_source,y_source,length_x,length_y,
pixel_data,raw)
integer*4 fildes,x_source,y_source,length_x,length_y,raw
character*(*) pixel_data()

subroutine intblock_read(fildes,x_source,y_source,length_x,length_y,
pixel_data,raw)
integer*4 fildes,x_source,y_source,length_x,length_y,raw
character*(*) pixel_data()

Pascal Syntax:

type
gbyte=0..255;

procedure block_read(fildes:integer;
x_source,y_source:real;length_x,length_y:integer;
var pixel_data:packed array[lo..hi:integer] of gbyte;raw:integer);

procedure dcblock_read(fildes:integer;
x_source,y_source,length_x,length_y:integer;
var pixel_data:packed array[lo..hi:integer] of gbyte;raw:integer);

procedure intblock_read(fildes:integer;
x_source,y_source,length_x,length_y:integer;
var pixel_data:packed array[lo..hi:integer] of gbyte;raw:integer);

DESCRIPTION

Input Parameters

fildes Integer file descriptor returned by gopen when an I/O path to a graphics device is opened.

x_source,y_source
Coordinates of upper left corner of the source in virtual device coordinates ( block_read, intblock_read) or device coordinates ( dcblock_read).

length_x,length_y
Length (in pixels) of the x and y sides of the block to be read.

raw If FALSE (0), each pixel is written as a 1 byte quantity. There are no padding bytes. Therefore, with FORTRAN, four pixels are written for each 32-bit integer array element.

If TRUE (1), the data is organized in a device dependent format. Some devices may format the device with multiple pixels per byte. Other devices may allow different formats that can be set with a call to the gescape R_BIT_MODE. Other functions, such as clipping, may also behave in a device dependent manner. See the Starbase Device Driver Library for details.

Output Parameters

pixel_data Packed array of pixel data to be transferred. This data is returned by the procedure.

Discussion

Pixel_data is considered to be a length_x by length_y byte rectangle for the following discussion. The returned array will contain frame buffer values from the source rectangle beginning at location (x_source,y_source) with dimensions of length_x and length_y combined with the values in pixel_data using the current drawing_mode. Write_enable does not have any effect on block_read. Pixels are placed in the array in order: left to right, then from top to bottom. If the clip_indicator is not CLIP_OFF, pixel_data values outside the intersection of the source rectangle and the current clip boundaries are left untouched. In all cases the dimensions of the resultant pixel_data rectangle is preserved.

This is the exact inverse operation of block_write (except for write_enable).

For multi-bank graphics devices the block read comes from the bank currently selected by bank_switch.

For device-independent operation do not use raw mode. Raw mode should only be used where speed of image read is critical and the number of pixels read is not critical. This speed improvement is significant only if the device frame buffer organization is not one byte or word per pixel.

Block_read and intblock_read are performed using virtual device coordinate values and dcblock_read is performed using device coordinate values.

Integer operations are only available when using the INT_XFORM gopen mode. When in INT_XFORM mode, floating point operations are not available for that fildes. Floating point operations are the default, or can be specified with FLOAT_XFORM mode. For a list of integer operations, floating point operations and common operations see the starbase.3g manual page.

Museum

Related Articles