pixmode Subroutine

GL3.2 for AIX: Graphics Library (GL) Technical Reference

pixmode Subroutine

Purpose

Controls the operation of pixmap transfers with the lrectread and lrectwrite subroutines.

Libraries

Graphics Library

C (libgl.a)

FORTRAN (libfgl.a)

C Syntax

void pixmode (Int32 mode, Int32 value)

FORTRAN Syntax

SUBROUTINE PIXMOD (mode, value)
INTEGER*4 mode, value

Description

The pixmode subroutine controls the manner in which the arguments of the lrectread and lrectwrite subroutines are interpreted while performing pixel transfers to and from the frame buffer. That is, the pixmode subroutine sets the attributes associated with a pixel-transfer operation. The attributes that can be set by this function do not control the operation of the rectcopy routine.

This subroutine is intended to provide a device-independent interface to the reading and writing of pixmaps. It should be used to specify the format of the pixmaps maintained by the application. Transfers occurring with the lrectread and lrectwrite subroutines then automatically convert the incoming or outgoing data to or from the appropriate format for the internal device of the frame buffer.

Only the lrectread and lrectwrite subroutines are affected by these attributes. The operation of the rectread, rectwrite, and rectcopy subroutines are not affected.

The following information describes the various pixel transfer modes that are supported on the POWER Gt4 and POWER Gt4x adapters.

Note: The 3-D Color Graphics Processor, the POWERgraphics GTO, and the POWERstation 730 adapters support only PM_FASTMODE.

Mode	Default and Behavior
PM_TTOB	Default = False Indicates pixel row ordering from top to bottom or bottom to top. A value of True indicates that the top row comes first in the data, followed by remaining rows, top to bottom. A value of False indicates that the bottom row comes first in the data, followed by remaining rows, bottom to top.
PM_STRIDE	Default = 0 Indicates the number of 32-bit words between the starts of successive scan lines. On the POWER Gt4 and POWER Gt4x adapters, the stride must be positive and greater than the width of the pixmap (the width as specified with the lrectread and lrectwrite subroutines). If the stride is less than the width, the stride is to be changed to equal the width. A stride factor that is different than the width is used to transfer subportions of an image to and from the screen. There are two scenarios: 1) A subportion of a large image on the system is to be transferred to the frame buffer. In this case, the row stride describes the length of a row on the system, while the arguments to the lrectwrite subroutine specify the subrectangle to be written. Note that the width specified through the lrectwrite subroutine is smaller than the row stride. 2) A subportion of a large image in the frame buffer is to be transferred to system memory. The subregion of the frame buffer is indicated with the lrectread subroutine. If the row stride factor is greater than the width specified with the lrectread subroutine, then only a width number of pixels in each row is transferred from the screen to the system. System memory beyond width, but before stride is not touched.
PM_SIZE	Default = 32 Indicates the number of bits between successive pixels in the data array. For instance, if the pixel size factor is 8, there are four pixels packed into one 32-bit word so that the system returns packed pixels while reading, and assumes that the user has presented packed pixels in the data when writing. The POWER Gt4 and POWER Gt4x adapters support values of 8 and 32. Other values are ignored. The setting of the PM_SIZE mode is ignored when reading from and writing to the overlay planes and the z-buffer. A size of 32 or one pixel per word is assumed.
PM_FASTMODE	Default = True Indicates that the pixel transfer mode should be set automatically to values that maximize the hardware performance of pixel transfers.
All Adapters	Default = False Pixel transfers proceed from left to right and then from bottom to top. Each pixel occupies one 32-bit word. RGB mode pixels are packed as 0xAABBGGRR. Colorindex mode pixels occupy the lowest order bits of the word.
3-D Color Graphics Processor	Default = True The behavior is the same as PM_FASTMODE with default = False.

Different adapters have different pixel transfer methods. If an adapter has more than one fast pixel transfer mode, values that are closest to the default values are chosen. The following information summarizes the fast transfer modes for the POWER Gt4 and POWER Gt4x adapters.

When PM_FASTMODE is set and True is specified, the pixel format depends on the current frame buffer configuration. When the window is in color-index mode, PM_SIZE is automatically set to 8; when in RGBmode, PM_SIZE is automatically set to 32.

The POWER Gt4 and POWER Gt4x adapters natively support a packed pixel mode, with four 8-bit pixels stuffed into a 32-bit word. To obtain this transfer mode in colorindex mode, set PM_SIZE to 8.

Parameters

mode	A token representing the transfer mode to be changed. The actual behavior of the device when placed in FASTMODE TRUE is device specific.
value	The value to be associated with the pixel transfer mode.

Implementation Specifics

This subroutine is part of GL in the AIXwindows Environment/6000 Version 1, Release 2 with AIXwindows/3D Feature.

The pixmode subroutine is currently inoperational on the POWERgraphics GXT1000.

Files

/usr/include/gl/gl.h	Contains C language constant and variable type definitions for GL.
/usr/include/gl/fgl.h	Contains FORTRAN constant and variable type definitions for GL.

Related Information

Drawing a rectangular array of pixels into the frame buffer with the rectwrite or lrectwrite subroutine.

Reading a rectangular array of pixels into host memory with the rectread or lrectread subroutine.

AIX Graphics Library Overview and Configuring the Frame Buffer.

Reading and Writing Pixels.