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