GPR_$OPEN_BITMAP_FILE GPR Calls GPR_$OPEN_BITMAP_FILE
NAME
gpr_$open_bitmap_file - opens a bitmap stored on disk.
FORMAT
gpr_$open_bitmap_file (access, filename, filename_size, version, size,
groups, group_header, attribs, bitmap, created,
status)
DESCRIPTION
This routine opens (for creating or accessing) a bitmap stored on disk.
Input Parameters
access
One of four ways to access external bitmap objects, in
gpr_$access_mode_t format. This is a 2-byte integer. Specify one of
the following values:
gpr_$create
Allocates a new file on disk for storage of a graphic image.
gpr_$update
Allows you to modify a previously created file or create a new
one.
gpr_$write
allows you to write to an existing file.
gpr_$readonly
allows you to read a previously created file.
filename
The pathname of the bitmap file, in name_$long_pname_t format.
filename_size
The length of the filename. This is a 2-byte integer. If you
specify 0 when creating the file, the system will create a temporary
file.
Input/Output Parameters
version
The version number on the header of the external bitmap file, in
gpr_$version_t format. This is a two-element array of two 2-byte
integers: a major version number and a minor version number.
Currently, version is not used and is always returned as major ver-
sion 1, minor version 1. If you specify an access other than
gpr_$create, GPR ignores the value specified for version and returns
the values allocated when the file was created.
size Bitmap width and height, in gpr_$offset_t format. This is a two-
element array of 2-byte integers. The first element is bitmap
width, in raster units; the second element is the bitmap height, in
raster units. Possible values for x are 1-4096; possible values for
y are 1-4096. You can get the bitmap width and height by calling
gpr_$inq_disp_characteristics. If you are not creating the file,
GPR ignores the value specified for size and returns the values
allocated when the file was created.
groups
The number of groups in external bitmaps. This is a 2-byte integer.
Possible values range from 1 to (gpr_$max_bmf_group +1). Currently,
a bitmap can contain only 1 group. If you are not creating the
file, GPR ignores the value specified for groups and returns the
value allocated when the file was created.
group_header
Description of the external bitmap, in gpr_$bmf_group_header_array_t
format. This is an array [0..gpr_$max_bmf_group] of
gpr_$bmf_group_header_t. A description of the fields in a group
header and the possible values are listed below. If you are not
creating the file, GPR ignores all of the values specified in
group_header, and returns the values allocated when the file was
created.
n_sects
This is a 2-byte integer representing the number of sections in
the group. Permissable values range between 1 and 32
inclusive.
pixel_size
This is a 2-byte integer representing the number of bits per
pixel in each section of a group. This value can be between 1
and 32, inclusive.
allocated_size
This is a 2-byte integer representing the number of bits that
the system uses to store the value of one pixel. The only
legal values for allocated_size are 0, 1, 8, 16, and 32.
Choosing 0 means that the system will calculate allocated_size
for you. If you choose a number other then 0, than the value
you choose must be greater than or equal to pixel_size.
bytes_per_line
This is a 2-byte integer representing the number of bytes in
one row of one plane of the bitmap. The value must be a multi-
ple of 4 large enough to contain all the bytes in one line. If
you set bytes_per_line to 0 when creating the file, GPR will
perform the necessary calculations and return the appropriate
value into the parameter.
bytes_per_sect
The number of bytes_per_line multiplied by the height of the
bitmap. This value must then be either rounded up to a page
boundary, or for small bitmaps rounded up to the next largest
binary submultiple of a page, for example, one-half, one-
fourth, or one-eighth. One page equals 1024 bytes.
bytes_per_sect is a 4-byte integer. If you set bytes_per_sect
to 0 when you create the file, then GPR will perform the neces-
sary calculations and return the correct value into the parame-
ter. bytes_per_sect is not necessarily a multiple of
bytes_per_line. GPR will leave unused space at the end of one
section to satisfy alignment constraints. The result is that
the next section starts on an alignment boundary, which is nor-
mally a page boundary.
storage_offset
GPR returns this UNIV_PTR parameter which points to the begin-
ning of the group storage area.
Input Parameters
attribs
The attributes which the bitmap will use, in gpr_$attribute_desc_t
format. This is a 4-byte integer.
Output Parameters
bitmap
Descriptor of the bitmap, in gpr_$bitmap_desc_t format. This is a
4-byte integer.
created
Boolean (logical) value which specifies whether the bitmap file was
created. If the value is true, the file was created.
status
Completion status, in status_$t format.
SEE ALSO
gpr_$allocate_attribute_block, gpr_$allocate_bitmap.
NOTES
In a plane-oriented external bitmap, a section is equivalent to one
plane. Therefore, if your node contains eight planes, you store the
external bitmap in eight different sections for a plane-oriented external
bitmap. In practical terms, you have to set n_sects to the number of
planes and pixel_size to 1.
In a pixel-oriented external bitmap, you can store the entire bitmap in
one section,even if the node contains many planes. In other words, a
pixel-oriented bitmap stores the value of one pixel in consecutive bits,
instead of scattered around a disk file. For example, suppose you want
to create a pixel-oriented external bitmap for an 8-plane node. In this
case, we suggest setting n_sects to 1 and pixel_size to 8.
Drawing, fill, and text operations cannot be performed directly to a
pixel-oriented bitmap. You can, however, do these operations to the
display bitmap and then blt the display bitmap to a pixel-oriented bit-
map.
The access parameter specifies one of four ways to use external bitmaps.
As shown in the table below, the value given for this parameter deter-
mines whether the parameters version, size, groups, and group_headers are
input (IN) or output (OUT). The values for these parameters are used to
validate your input with gpr_$create and gpr_$update.
________________________________________________________
|gpr_$create | gpr_$update | gpr_$write | gpr_$readonly |
|____________|_____________|____________|_______________|
|IN | IN/OUT | OUT | OUT |
|____________|_____________|____________|_______________|
gpr_$create indicates that you want a new external bitmap file.
gpr_$update means that you want to create a new file or overwrite an
existing one.
When you specify gpr_$create as the access parameter and you specify a
filename that already exists, the file is superceded only if it is a bit-
map file. If the file is not a bitmap file, you get the error message
"name_$already_exists."
For gpr_$update, the existing file must have the same number of planes as
the application is trying to write.
Attributes are not stored with the bitmap. You assign attributes when
you open the bitmap file. See the routines gpr_$allocate_attribute_block
and gpr_$allocate_bitmap.
To close an external bitmap file, either exit GPR with gpr_$terminate or
call gpr_$deallocate_bitmap.