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