GSXBLT(3g,L) AIX Technical Reference GSXBLT(3g,L)
-------------------------------------------------------------------------------
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.
The gsxblt subroutine is used to support windowing operations, 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 controls which pixels in
the destination rectangle can be modified.
The relevant attributes are:
o Plane mask
o Color map.
Parameters
Processed November 7, 1990 GSXBLT(3g,L) 1
GSXBLT(3g,L) AIX Technical Reference GSXBLT(3g,L)
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 operation pixel map. This
parameter should equal 0 if there is no bit mask operator to
apply. For Fortran applications, 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 destination 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
Source Operation Destination Code
Destination clear 0
Set Destination 15
No operation Destination 5
~Destination 10
Source REPLACE Destination 3
Source AND Destination 1
Processed November 7, 1990 GSXBLT(3g,L) 2
GSXBLT(3g,L) AIX Technical Reference GSXBLT(3g,L)
Type of Logical Type of
Source Operation Destination Code
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) (from gsqdsp)
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.
Processed November 7, 1990 GSXBLT(3g,L) 3
GSXBLT(3g,L) AIX Technical Reference GSXBLT(3g,L)
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), followed 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
Processed November 7, 1990 GSXBLT(3g,L) 4
GSXBLT(3g,L) AIX Technical Reference GSXBLT(3g,L)
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 determined 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 rectangle 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.
Processed November 7, 1990 GSXBLT(3g,L) 5
GSXBLT(3g,L) AIX Technical Reference GSXBLT(3g,L)
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.
For VGA, 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 coordinate
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.
Processed November 7, 1990 GSXBLT(3g,L) 6
GSXBLT(3g,L) AIX Technical Reference GSXBLT(3g,L)
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."
Processed November 7, 1990 GSXBLT(3g,L) 7