gsxblt
Purpose
Moves a rectangular block in system or display adapter
memory from one location to another.
C Syntax
int gsxblt_ (srcpix, dstpix, mskpix, W, H, logop)
int *srcpix, *dstpix, *mskpix, *W, *H, *logop;
FORTRAN Syntax
INTEGER function gsxblt (srcpix, dstpix mskpix, W, H, logop)
INTEGER srcpix(*), dstpix(*), mskpix(*) W, H, logop
Pascal Syntax
FUNCTION gsxblt_ (
VAR srcpix, dstpix, mskpix: ARRAY [32| of INTEGER;
VAR W, H, logop : INTEGER
): INTEGER [PUBLIC|;
Description
The gsxblt subroutine moves a rectangular block of pixels
from one memory location to another, either in system
memory or in the display adapter frame buffer.
For FORTRAN specific address information, see "gsxptr."
The gsxblt subroutine is used to support windowing oper-
ations, such as overlays and movement around the screen.
The source rectangle and the destination rectangle can be
in either system or adapter pixel memory. The gsxblt
subroutine is also used for user defined cursors and the
save and restore of a pixel map for applications like
pop-up menus.
The mask operation provided by the gsxblt subroutine con-
trols which pixels in the destination rectangle can be
modified.
The relevant attributes are:
o Plane mask
o Color map.
Parameters
srcpix Contains the address of the source
pixel map.
dstpix Contains the address of the destination
pixel map.
mskpix Contains the address of the mask opera-
tion pixel map. This parameter should
equal 0 if there is no bit mask oper-
ator to apply. For Fortran applica-
tions, a valid mskpix array must always
be defined. If no masking is required,
the address field of the array,
mskpix[9|, must be initialized to 0.
The mskpix pixel map must always
consist of only 1 bit per pixel, and
the mask rectangle must always be the
same size as the source and destination
rectangles. In the mask rectangle, a 1
bit means that the corresponding pixel
in the destination rectangle can be
modified, while a 0 bit means the des-
tination pixel will not be modified.
W Defines the width of the rectangular
area to be transferred.
H Defines the height of the rectangular
area to be transferred.
logop Indicates the logical operation to
perform between the source pixel map
and the destination pixel map.
In the following table, please note:
o The source or tile (a special type
of source) pixels represent bits of
data to be merged in some way with
the corresponding bits of data in
the destination rectangle.
o The first three columns of the
table specify the operations you
can perform, and the Code column
contains the corresponding value
you should specify for the logop
parameter.
o There are two unique codes for each
logical operation, to be used
depending on whether the tiling bit
in the source pixel map is set.
Codes 0-15 must be used when the
tiling bit is not set, while codes
16-31 must be used when the tiling
bit is set.
o A ~ (tilde) represents the logical
INVERSE.
Type of Logical Type of Code
Source Operation Destination
Destination clear 0
Set Destination 15
No operation Destination 5
~Destination 10
Source REPLACE Destination 3
Source AND Destination 1
Source AND ~Destination 2
Source Exclusive-or Destination 6
Source OR Destination 7
Source OR ~Destination 11
~Source REPLACE Destination 12
~Source AND Destination 4
~Source AND ~Destination 8
~Source Exclusive-or Destination 9
~Source OR Destination 13
~Source OR ~Destination 14
Destination clear 16
Set Destination 31
No operation Destination 21
~Destination 26
Tile REPLACE Destination 19
Tile AND Destination 17
Tile AND ~Destination 18
Tile Exclusive-or Destination 22
Tile OR Destination 23
Tile OR ~Destination 27
~Tile REPLACE Destination 28
~Tile AND Destination 20
~Tile AND ~Destination 24
~Tile Exclusive-or Destination 25
~Tile OR Destination 29
~Tile OR ~Destination 30
A pixel map is a 32-bit array of integers that contains the following fields:
0 Device ID (0 for memory)
1 Flags
In the following explanations, bit 0 is the low-order bit.
o Plane (XY) format is selected when bit 0 is set and bits 1 and 2
are not set. Pixel (Z) format is selected when bits 0, 1, and 2
are not set.
o A repetitive tile is specified when bit 3 is set, while no tile
is specified when bit 3 is not set.
If the repetitive tile bit is set in the srcpix, pixel map, then
the Device ID field in that pixel map must equal 0. The tile
data must be in memory.
o Bit 4 selects the lower-left coordinate system when it is set,
and the upper-left coordinate system when it is not set.
2 Height (in pixels)
3 Width (in pixels)
This value must be an even multiple of 16 pixels for all pixel maps,
which means that all pixel maps must be at least 16 pixels wide.
4 Number of bits per pixel
5 Pixels per byte, right justified
6 Bytes per pixel
7 x offset
8 y offset
9 Address of upper-left corner of data
10 Foreground color index
11 Background color index
12 - 31 Reserved.
Definitions of pixel map terms include:
Device ID
This is a required parameter for all pixel map definitions. If the
pixel map being defined is a display adapter, this field must
contain the Device ID of that display adapter. If the pixel map
resides in system memory, then this field must equal "0".
Pixel format
Data stored in this format has all bits for a pixel stored
together. The data starts with the origin and increases first in
the x direction, then in the y direction.
As an example using the upper-left coordinate system, a pixel map
with 4 bits per pixel and 1 pixel per byte stores the 4 bits for
the pixel at location (0,0) in the first byte of the data area,
right justified in the byte. The 4 bits for the pixel at location
(1,0) are stored in the second byte, followed by the rest of the
pixel values in that row. When the end of the row is reached, the
next byte contains the 4 bits for the pixel at location (0,1), fol-
lowed by the rest of the pixel values in that row, and so on for
the entire image.
Plane format
Plane format indicates that each of the bits that make up a pixel
is stored in a separate, consecutive plane in memory. The most
significant bit is first, followed by the next significant, and so
on to the least significant bit, which is last. The bits within a
plane are packed together 8 bits per byte. Therefore, using the
upper-left coordinate system as an example, a pixel map with 4 bits
per pixel would consist of four separate planes of data with the
first bit value being the one for location (0,0) and increasing
first in the x direction, then in the y direction.
Repetitive tiling operation
This operation consists of repeatedly copying a 16-pixel wide by
16-pixel high tile rectangle pointed to by the tile pixel map data
address to fill a rectangular area of a size specified by the H and
W parameters of this call. The format of the tile data is deter-
mined by the format defined in the flags field of the tile pixel
map structure.
Upper-left coordinate system
This indicates that the upper-left corner of the pixel map is used
as the origin of the coordinate system, with increasing values of x
moving to the right and increasing values of y moving down. The x
offset and y offset are to set the upper-left corner of the rec-
tangle when using this coordinate system.
Lower-left coordinate system
This indicates that the lower-left corner of the pixel map is used
as the origin of the coordinate system, with increasing values of x
moving to the right and increasing values of y moving up. The x
offset and the y offset are set to the lower-left corner of the
rectangle when using this coordinate system. Note, however, that
the data address specified in the pixel map structure must always
point to the upper-left corner of the data area no matter which
coordinate system is defined.
Number of bits per pixel
This field identifies the number of bits of data required to define
a pixel value. For example, a simple monochrome display requires
only 1 bit per pixel, while a color display may require 4 bits of
information to define a pixel.
Number of pixels per byte
If the number of bits per pixel is less than 8, this field defines
how many pixels are stored in each byte of pixel map data. A pixel
map with only 1 bit per pixel must always store 8 pixels per byte.
It is strongly recommended that for between 2 and 7 bits per pixel,
you store data with only 1 pixel per byte.
Bytes per pixel
If the number of bits per pixel is greater than 8, this field
defines how many bytes are used to store each pixel. It is
strongly recommended that for between 9 and 16 bits per pixel, you
store data 2 bytes per pixel. For between 17 and 32 bits per
pixel, data should be stored 4 bytes per pixel.
Foreground color index
This specifies the color index value to use for a value of 1 in the
source pixel map during a color expansion operation.
Background color index
This specifies the color index value to use for a value of 0 in the
source pixel map during a color expansion operation.
A color expansion operation takes place automatically when the source pixel
map data area contains only 1 bit per pixel and the destination pixel map
data area is a color display adapter frame buffer defined to have more than 1
bit per pixel. In this case, when a 1 is specified in the source pixel map
data area, the foreground color index value specified in the destination
pixel map (dstpix) is written to the destination data area. When a 0 is
specified in the source pixel map data area, the background color index value
specified in the destination pixel map (dstpix) is written to the destination
data area.
The foreground color index and the background color index must be initialized
in the dstpix pixel map before calling this operation, but do not need to be
initialized in the srcpix or mskpix pixel maps.
Not all logical operations are supported for a color expansion operation.
The following table shows which operations are supported. In this table,
a ~ (tilde) represents the logical INVERSE. Note that the operations in the
left column of the table are for source pixel maps, while the operations in
the right column are for tile pixel maps.
Type of Operation Code Type of Operation Code
Destination clear 0 Destination clear 16
Set destination 15 Set destination 31
Destination 5 Destination 21
~Destination 10 ~Destination 26
Source 3 Tile 19
~Source 12 ~Tile 28
If a source or destination pixel map structure defines the active display
adapter, you do not need to initialize all the fields of that pixel map
structure. Device-dependent information, such as height, width, pixels per
byte, bytes per pixel, and address of data, is supplied automatically. You
must initialize the fields for device ID, bits per pixel, flags (except for
the data format bits), x offset, and y offset. Also, the foreground color
index and the background color index must be initialized if appropriate for
this adapter.
When initializing a pixel map structure to use as the mskpix parameter:
1. The flags field should equal a value of "0x01" if the upper-left coordi-
nate system will be used or "0x11" if the lower left coordinate system
will be used.
2. The number of bits per pixel must equal "1".
3. The number of pixels per byte must equal "8".
The GSL plane mask attribute applies to all gsxblt operations that use the
display adapter as the source or destination pixel map.
The GSL color map attribute applies to all gsxblt operations that use the
display adapter as the destination pixel map.
Return Value
GS_SUCC Successful.
GS_IWID Invalid width specification. The x_offset plus the W parameter of
one of the pixel maps exceeds the total width of that pixel map.
GS_IHEI Invalid height specification. The y_offset plus the H parameter of
one of the pixel maps exceeds the total height of that pixel map.
GS_NPLF Source and destination data formats do not match.
GS_INAC Virtual terminal inactive.
GS_CORD Invalid coordinate specified that placed the origin of the source,
destination, or mask rectangle outside its pixel map.
GS_IBPP Invalid value for bits per pixel in the source pixel map.
GS_CEXP Color expansion operation attempted, but the destination pixel map
was not a display adapter.
GS_PWID The width of one of the pixel maps is not an even multiple of 16
pixels.
Related Information
In this book: "gsxptr."