GPR_$REMAP_PIXELS GPR Calls GPR_$REMAP_PIXELS
NAME
gpr_$remap_pixels - remaps the display bitmap to pixel mode.
FORMAT
gpr_$remap_pixels (section_number, group_header, status))
DESCRIPTION
This routine changes the default memory mapping of a display or HDM bit-
map from plane to pixel mode.
Input Parameters
section_number
The number of the section to map. A section is a single component
of the image. For example, if you specify a pixel_size of one for
an eight-plane bitmap, the bitmap will have eight sections, numbered
0 - 7. If you specify a pixel_size of eight for a 24-plane bitmap,
it will have three sections, numbered 0 - 2. Most of the time, you
will want to set the section_number to zero. If you specify a
nonexistent section, GPR will not return an error and will use a
default of zero. This is a 2-byte integer.
Input/Output Parameters
group_header
This is a description of the bitmap, in gpr_$bmf_group_header_t for-
mat. The fields in the group header are:
n_sects
2-byte integer giving the number of sections in the group. GPR
fills in this value for you. Image planes are the planes used
for specifying the color.
pixel_size
2-byte integer representing the number of bits in the image
buffer of each pixel in the group. If you set this to zero,
you will get the default, which is a pixel_size of one (plane
mode).
allocated_size
2-byte integer. The number of bits per pixel allocated. GPR
fills in this value for you.
bytes_per_line
Number of bytes per row of bitmap (counting any padding at ends
of scanlines). GPR fills in this value for you.
bytes_per_sect
Number of bytes per section. GPR fills in this value for you.
If n_sects is zero, this value may also be zero.
storage_offset
UNIV_PTR to the beginning of the mapped section of the bitmap.
GPR fills in this value for you.
status Completion status, in status_$t format.
NOTES
gpr_$remap_pixels allows direct access only to display and HDM bitmaps.
Pixel mode direct access to display bitmaps is only available on the
DN3500A/F, DN3550A/B/F, DN4500A/B/F, and Series 10000VS.
In order to use gpr_$remap_pixels, either the display or the HDM bitmap
must be current. Use gpr_$set_bitmap to set the current bitmap.
You may wish to take the cursor down before reading or writing directly
to the bitmap.
Use either the storage offset from the group header or the pointer
returned from gpr_$inq_bitmap_pointer to get a pointer for writing
directly to the bitmap. If allocated_size is eight, this pointer points
to an array of eight-bit bytes. If allocated_size is 32, this pointer
points to an array of 32-bit longwords.
If your allocated_size equals one (plane access), you must use
gpr_$inq_bm_offset to get the bit offset for the bitmap.
gpr_$wrong_display_hardware can result if you attempt to map the display
with a pixel size or section number it does not support.
For this release, if you specify a pixel_size of 32, the highest eight
bits will be unpredictable.
When you enable direct access, you have access to the entire screen, even
when you are in direct display mode. Thus, you can write outside the
window. Use gpr_$inq_bitmap_dimensions and gpr_$inq_vis_list to deter-
mine the area on the screen where your application should draw. It is
the application's responsibility to keep its drawing in the window. On
the Series 10000VS, you can use gpr_$set_clip_window and
gpr_$set_clipping_active to keep your drawing within the window, but clip
rectangle mechanism does not work for direct access on other nodes.
Even though you can write to the entire screen, the origin of the coordi-
nate system is still at the upper left corner of the window.
You can move easily between direct access and GPR drawing calls. How-
ever, any GPR drawing call (for example, gpr_$line) automatically makes
the memory mapping of the bitmap invalid. To use direct access again, a
program must call gpr_$remap_pixels after the GPR drawing calls and
before using the pointer from storage_offset or gpr_$inq_bitmap_pointer.
Failure to call gpr_$remap_pixels before writing to the bitmap is a com-
mon cause of strange graphical results in programs using direct access.
Do not use gpr_$enable_direct_access after gpr_$remap_pixels.
gpr_$remap_pixels performs the same function as
gpr_$enable_direct_access, which is to allow all previous GPR calls to be
completed before enabling direct access.