BITMAP_TO_FILE(3G)

NAME

bitmap_to_file − copy bitmap contents to a bitmap file

SYNOPSIS

C Syntax:

void bitmap_to_file(fildes,full_depth,spn,dpn,dest,full,
start,ystart,xlen,ylen,store_cmap)
int fildes,full_depth,spn,dpn;
char *dest;
int full;
float xstart,ystart;
int xlen,ylen;
int store_cmap;

void dcbitmap_to_file(fildes,full_depth,spn,dpn,dest,
full,xstart,ystart,xlen,ylen,store_cmap)
int fildes,full_depth,spn,dpn;
char *dest;
int full,xstart,ystart,xlen,ylen;
int store_cmap;

FORTRAN77 Syntax:

subroutine bitmap_to_file(fildes,full_depth,spn,dpn,dest,
full,xstart,ystart,xlen,ylen,store_cmap)
integer*4 fildes,full_depth,spn,dpn
character*(*) dest
integer*4 full
real xstart,ystart
integer*4 xlen,ylen
integer*4 store_cmap

subroutine dcbitmap_to_file(fildes,full_depth,spn,dpn,dest,
full,xstart,ystart,xlen,ylen,store_cmap)
integer*4 fildes,full_depth,spn,dpn
character*(*) dest
integer*4 full,xstart,ystart,xlen,ylen
integer*4 store_cmap

Pascal Syntax:

procedure bitmap_to_file(fildes,full_depth,spn,dpn:integer;
dest:string255;full:integer;xstart,ystart:real;
xlen,ylen,store_cmap:integer);

procedure dcbitmap_to_file(fildes,full_depth,spn,dpn:integer;
dest:string255;full,xstart,ystart,xlen,ylen,
store_cmap:integer);

DESCRIPTION

Input Parameters

fildes Integer file descriptor returned by gopen when the I/O path of a bitmap device is opened.

full_depth Indicates what source data is to be stored. If TRUE (1), all bitmap planes are transferred to the file, ignoring spn and dpn parameters. If FALSE (0), the parameter spn determines a single plane to be transferred.

spn Number of a single plane to copy to the file. It must be in the range 0 to n−1, where n is the number of planes in the bitmap.

dpn Destination plane number recorded in the file; can be any non-negative integer. Any plane number can be assigned to the data stored in the file. To mark the destination plane number to be the same as the source plane, set spn and dpn to the same value.

dest Pathname of the file to be written. If a file by the same name exists, it is overwritten by the new file.

full If TRUE (1), indicates that the full extent of the bitmap is to be stored. The parameters xstart, ystart, xlen, and ylen are ignored. If FALSE (0), the rectangle specified by the next four parameters is stored.

xstart, ystart Specify coordinates of the upper-left corner of the source rectangle in Virtual Device Coordinates (bitmap_to_file) or Device Coordinates (dcbitmap_to_file).

xlen, ylen Lengths, in pixels, of the sides of the rectangle to be stored.

store_cmap If TRUE (1), indicates that the current software color map is to be stored in the file. If FALSE (0), no color map is stored.

Discussion

Pixel data is considered to be an xlen by ylen pixel rectangle for the following discussion. The pixel data from the source beginning at upper left corner xstart,ystart is written into the destination file. If the full parameter is TRUE, the rectangle is determined by the bitmap extent.

If the file is written full-depth from a bitmap organized in pixel-major format, the file will be written in a pixel-major format. If the copy is full-depth from a plane-major bitmap, the file will be plane_major also. A single-plane copy always creates a plane_major file.

The actual rectangle written to the file is determined by the current clipping mode and hence a later call to inquire_file may return smaller dimensions than were specified in the procedure call that created the file.

Only currently displayed planes are stored. Non-displayed planes are stored as zeroes. If double-buffering is enabled, the currently displayed buffer is stored.

For full-depth operation from multi-bank graphics devices, the currently selected bank (as set by bank_switch is stored. If the current shade mode is CMAP_FULL, all appropriate banks are stored.

Museum

Related Articles