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