GPR_$MAKE_BITMAP_FROM_ARRAY GPR Calls GPR_$MAKE_BITMAP_FROM_ARRAY
NAME
gpr$_make_bitmap_from_array - creates a bitmap descriptor pointing to a
given memory address (containing the image data).
FORMAT
gpr$_make_bitmap_from_array (size, attribs, groups, g_headers, bitmap,
status)
DESCRIPTION
This routine creates a bitmap descriptor pointing to a given memory
address (containing the image data).
gpr_$make_bitmap_from_array provides a way to generate a bitmap from an
array. The bitmap is stored in main memory in external bitmap file for-
mat. This feature enables BLT operations to be performed with the new
bitmap, which is adventageous if read/write pixel operations done with
arrays are limiting.
Input Parameters
size Size of bitmap in gpr_$offset_t format. In FORTRAN, declare a 2-
element array of INTEGER*2.
attribs
Attribute block descriptor in gpr_$attribute_desc_t format. This is
a 4-byte integer.
groups
The number of groups in the external bitmap. This is a 2-byte
integer. Possible values are 1 ..(gpr_$max_bmf_group+1). Currently,
a bitmap can contain only one group.
Input/Output Parameters
Group headers in gpr_$bmf_group_header_array_t format. Each element in
the array is in gpr_$bmf_group_header_t format. 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. Previously, this value had to be set equal to the
number of planes on the target node. Now, permissable values
range between 1 and 24 inclusive.
pixel_size
This is a 2-byte integer representing the number of bits per
pixel in each section of a group. Previously, this value had
to be 1. Now, you can set it to any value from 1 to 32.
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.
Output Parameters
bitmap
Returned bitmap descriptor in gpr_$bitmap_desc_t format.
status
Completion status, in status_$t format.
SEE ALSO
gpr_$deallocate_bitmap.
NOTES
To deallocate this type of bitmap, use gpr_$deallocate_bitmap. Since
this type of bitmap resides in main memory, it would also be deallocated
upon calling gpr_$terminate.