GA_modeInfo

Declaration

typedef struct {
N_uint32 dwSize;
N_uint32 Attributes;
N_uint16 XResolution;
N_uint16 YResolution;
N_uint8 XCharSize;
N_uint8 YCharSize;
N_uint32 BytesPerScanLine;
N_uint32 MaxBytesPerScanLine;
N_uint32 MaxScanLineWidth;
N_uint32 MaxScanLines;
N_uint32 LinearHeapStart;
N_uint32 MaxLinearOffset;
N_uint16 BitsPerPixel;
GA_pixelFormat PixelFormat;
N_uint16 MaxBuffers;
N_uint32 MaxPixelClock;
N_int32 DefaultRefreshRate;
N_int32 _FAR_ *RefreshRateList;
N_uint32 BitmapStartAlign;
N_uint32 BitmapStridePad;
N_uint32 MonoBitmapStartAlign;
N_uint32 MonoBitmapStridePad;
GA_bltFx _FAR_ *BitBltCaps;
GA_videoInf _FAR_ * _FAR_ *VideoWindows;
struct _GA_3DState _FAR_ *HW3DCaps;
N_flt32 MaxOOZ;
N_flt32 MaxOOW;
N_flt32 MaxOOS;
N_flt32 MaxOOT;
N_uint32 DepthFormats;
N_uint32 DepthStartAlign;
N_uint32 DepthStridePad;
N_uint32 TextureFormats;
N_uint32 TextureStartAlign;
N_uint32 TextureStridePad;
N_uint32 TextureMaxX;
N_uint32 TextureMaxY;
N_uint16 TextureMaxAspect;
N_uint32 StencilFormats;
N_uint32 StencilStartAlign;
N_uint32 StencilStridePad;
N_uint32 LinearSize;
N_uint32 LinearBasePtr;
N_uint32 AttributesExt;
N_uint16 PhysicalXResolution;
N_uint16 PhysicalYResolution;
} GA_modeInfo

Prototype In

snap/graphics.h

Description

Graphics mode information block. This structure contains detailed information about the capabilities and layout of a specific graphic mode.

The Attributes member contains a number of flags that describes certain important characteristics of the graphics mode, and the values this member contains are defined in the GA_AttributeFlagsType.

The XResolution and YResolution specify the logical width and height in pixel elements for this display mode. The logical resolution is the resolution of all available pixels in the display which may be larger than the physical resolution if the mode has hardware panning enabled. Hardware panning is enabled if the maximum physical resolution of the display device does not support the specific mode, such as when hot switching between a CRT monitor and an LCD panel or TV output device.

The BytesPerScanLine member specifies how many full bytes are in each logical scanline. The logical scanline could be equal to or larger than the displayed scanline, and can be changed when the display mode is first initialized.

The MaxBytesPerScanLine and MaxScanLineWidth members define the maximum virtual framebuffer coordinates that can be initialised for the mode, in both bytes and pixels respectively. If an attempt is made to initialize a graphics mode with values larger than these values, the mode set will fail.

The MaxScanLines member holds the total number of scanlines available in that graphics mode when initialised with the default scanline width. This field combined with BytesPerScanLine can be used to determine the maximum addressable display memory for drawing operations. This can also be used to determine how large a virtual screen image can be before initialising a graphics mode. This field also determines the addressable limit for X/Y based drawing functions in offscreen video memory.

The LinearHeapStart member determines the start of the linear only heap, if one is available. Some hardware has restrictions on the addressable memory for the (x,y) coordinates passed to the 2D drawing functions. If the hardware supports DrawRectLin and the BitBltLin family of functions, the memory past the (x,y) coordinate restriction can be accessed using those functions. Hence this member determines the start of this linear only heap as a byte offset from the beginning of display memory. Memory in the linear only heap can only be accessed directly via the linear framebuffer, or using DrawRectLin or the BitBitLin family of blitting functions. None of the X/Y based drawing functions can be used to draw to the linear only heap.

The MaxLinearOffset member hold the maximum addressable display memory offset for linear drawing functions (DrawRectLin, BitBltLin etc). If the hardware has restrictions on the addressable memory for the X/Y drawing functions, the linear only heap resides between LinearHeapStart and MaxLinearOffset. If the maximum addressable scanline value for a display mode is past the end of display memory (common for high resolution modes), then LinearHeapStart = MaxLinearOffset which indicates that there is no linear only heap for that display mode.

Note: There may well be some memory used by the graphics hardware for caching the hardware cursor, patterns and other data between the end of (MaxScanLines * BytesPerScanLine) and LinearHeapStart. Hence the application software must never write to the memory between (MaxScanLines * BytesPerScanLine) and LinearHeapStart.

The BitsPerPixel member specifies the number of bits per pixel for this display mode. For 5:5:5 format RGB modes this should contain a value of 15, and for 5:6:5 format RGB modes this should contain a value of 16. For 8:8:8 bit RGB modes this should contain a value of 24 and for 8:8:8:8 RGBA modes this should contain a value of 32. For 24 and 32bpp modes, the application should look at the pixel format mask values (see below) to determine the actual format of the pixels within the display buffer.

The MaxBuffers member specified the maximum number of display buffers that can be allocated in video memory for page flipping. This value is a convenience function only, and can be computed manually from the value of MaxScanLines / YResolution.

The MaxPixelClock member specifies the maximum possible pixel dot clock that can be selected in this display mode when a refresh controlled mode is selected. Any attempt to select a higher pixel clock will cause the mode set to fail. This member can be used to determine what the maximum available refresh rate for the display mode will be.

The RedMaskSize, GreenMaskSize, BlueMaskSize and RsvdMaskSize members define the size, in bits, of the red, green, and blue components of an RGB pixel respectively. A bit mask can be constructed from the MaskSize members using simple shift arithmetic. For example, the MaskSize values for an RGB 5:6:5 mode would be 5, 6, 5, and 0, for the red, green, blue, and reserved members respectively.

The RedFieldPosition, GreenFieldPosition, BlueFieldPosition and RsvdFieldPosition members define the bit position within the RGB pixel of the least significant bit of the respective color component. A color value can be aligned with its pixel member by shifting the value left by the FieldPosition. For example, the FieldPosition values for an RGB 5:6:5 mode would be 11, 5, 0, and 0, for the red, green, blue, and reserved members respectively.

The BitmapStartAlign member defines the alignment requirements in bytes for offscreen memory bitmaps for this graphics mode. If the value in here is set to 8 for instance, then the start for all offscreen bitmaps must be aligned to an 8 byte boundary in order to be used for offscreen bitmap blitting. Note that the BitmapStartAlign member also defines the alignment requirements for all buffers passed to the SetDrawBuffer function.

The BitmapStridePad member defines the alignment requirements in bytes for the stride of offscreen memory bitmaps (the number of bytes to move from one line of the bitmap to the next). If the value in here is set to 8 for instance, then the number of bytes for each scanline in the offscreen bitmap must be padded out to a multiple of 8 (inserting zeros if necessary when downloading a source bitmap to offscreen memory). Note that the BitmapStridePad member also defines the padding requirements for all buffers passed to the SetDrawBuffer function.

The MonoBitmapStartAlign member defines the alignment requirements in bytes for monochrome offscreen memory bitmaps for this graphics mode, which are used by the PutMonoImageMSBLin and PutMonoImageLSBLin functions. If the value in here is set to 8 for instance, then the start for all monochrome offscreen bitmaps must be aligned to an 8 byte boundary in order to be used by the PutMonoImageMSBLin and PutMonoImageLSBLin functions.

The MonoBitmapStridePad member defines the alignment requirements in bytes for the stride of monochrome offscreen memory bitmaps (the number of bytes to move from one line of the bitmap to the next). If the value in here is set to 8 for instance, then the number of bytes for each scanline in the monochrome offscreen bitmap must be padded out to a multiple of 8 (inserting zeros if necessary when downloading a source bitmap to offscreen memory).

The RefreshRateList member contains a list of all valid refresh rates supported by the display mode which can be passed to the SetVideoMode function. Interlaced modes are indicated by a negative refresh rate (ie: 48Hz Interlaced is -48). The current default refresh rate is stored in the DefaultRefreshRate member, and except for special circumstances the default refresh rate set by the user should be used rather than overriding the refresh rate.

The BitBltCaps member defines the extended hardware BitBlt capabilities for the graphics mode, and points to a static GA_bltFx structure. Refer to the documentation of GA_bltFx to determine what this structure contains.

The VideoWindows member defines the hardware video capabilities for each of up to a maximum number of hardware video overlay windows. The list of hardware video overlay window capabilities is terminated with a NULL pointer. For instance if only 2 hardware video windwos are supported, the first two entries in this array would point to valid GA_videoInf structures, while the third would contain a NULL terminating the list. Refer to the documentation of GA_videoInf to determine what these structures contains.

The HW3DCaps member defined the hardware 3D capabilities for the graphics mode, and points to a static GA_3DState structure. Refer to the documentation of GA_3DState to determine what this structure contains.

The LinearSize member is the 32-bit length of the linear frame buffer memory in bytes. In can be any length up to the size of the available video memory. The LinearBasePtr member is the 32-bit physical address of the start of frame buffer memory when the controller is in linear frame buffer memory mode for this particular graphics mode. If the linear framebuffer is not available, then this member will be zero.

The AttributesExt member contains a number of extended flags that describes certain important characteristics of the graphics mode, and the values this member contains are defined in the GA_AttributeExtFlagsType.

The PhysicalXResolution and PhysicalYResolution specify the physical width and height in pixel elements for this display mode. The physical resolution is the resolution of all visible pixels on the display, and may be smaller than the logical resolution if the mode has hardware panning enabled.

Note: The LinearSize and LinearBasePtr members are duplicated in the mode information block because they may possibly change locations in memory depending on the display mode. Normally applications will always use the value stored in the the GA_devCtx LinearMem pointer to directly access the framebuffer (which is automatically adjusted for you), however if the information about the framebuffer starting address needed to be reported to other applications directly, the values stored in this mode information block should be used.

Note: The memory pointed to by the RefreshRateList, BitBltCaps, VideoWindows and HW3DCaps fields will be reused the next time GetVideoModeInfo is called, so do not rely on the information in these fields to remain the same across calls to this function.

Note: The dwSize member is intended for future compatibility, and should be set to the size of the structure as defined in this header file. Future drivers will be compatible with older software by examiming this value.

Members

dwSize | Set to size of structure in bytes
Attributes | Mode attributes
XResolution | Logical horizontal resolution in pixels
YResolution | Logical vertical resolution in lines
XCharSize | Character cell X dimension for text modes
YCharSize | Character cell Y dimension for text modes
BytesPerScanLine | Bytes per horizontal scan line
MaxBytesPerScanLine | Maximum bytes per scan line
MaxScanLineWidth | Maximum pixels per scan line
MaxScanLines | Maximum number of scanlines for default scanline width
LinearHeapStart | Start of linear only heap (if any)
MaxLinearOffset | Maximum display memory offset for linear drawing
BitsPerPixel | Bits per pixel
PixelFormat | Pixel format for the display mode
MaxBuffers | Maximum number of display buffers
MaxPixelClock | Maximum pixel clock for mode
DefaultRefreshRate | Currently active default refresh rate
RefreshRateList | List of all valid refresh rates terminated with -1.
BitmapStartAlign | Linear bitmap start alignment in bytes
BitmapStridePad | Linear bitmap stride pad in bytes
MonoBitmapStartAlign | Linear bitmap start alignment in bytes
MonoBitmapStridePad | Linear bitmap stride pad in bytes
BitBltCaps | Hardware 2D BitBltFx capabilities
VideoWindows | Up to 8 hardware video overlays
HW3DCaps | Hardware 3D capabilities
MaxOOZ | Maximum ooz coordinate value in floating point
MaxOOW | Maximum oow coordinate value in floating point
MaxOOS | Maximum one over s coordinate value in floating point
MaxOOT | Maximum one over t coordinate value in floating point
DepthFormats | Depth buffer formats flags
DepthStartAlign | Depth buffer start alignment in bytes
DepthStridePad | Depth buffer stride pad in bytes
TextureFormats | Texture formats flags
TextureStartAlign | Texture start alignment in bytes
TextureStridePad | Texture stride pad in bytes
TextureMaxX | Maximum texture X dimension
TextureMaxY | Maximum texture Y dimension
TextureMaxAspect | Maximum texture aspect ratio (1:x)
StencilFormats | Stencil buffer formats flags
StencilStartAlign | Stencil buffer start alignment in bytes
StencilStridePad | Stencil buffer stride pad in bytes
LinearSize | Linear buffer size in bytes
LinearBasePtr | Physical addr of linear buffer
AttributesExt | Extended mode attributes flags
PhysicalXResolution | Physical horizontal resolution in pixels
PhysicalYResolution | Physical vertical resolution in lines

Copyright © 2002 SciTech Software, Inc. Visit our web site at http://www.scitechsoft.com