| Home
| Previous
| Next
| Up

SetVideoMode

Sets a specified display mode.

Declaration

N_int32 NAPI GA_initFuncs::SetVideoMode(
N_uint32 mode,
N_int32 *virtualX,
N_int32 *virtualY,
N_int32 *bytesPerLine,
N_int32 *maxMem,
N_int32 refreshRate,
GA_CRTCInfo *crtc)

Prototype In

snap/graphics.h

Parameters

mode | Mode number to set, including flags
virtualX | Requested virtual display X resolution (-1 to use default)
virtualY | Requested virtual display Y resolution (-1 to use default)
bytesPerLine | Returns the scanline width for the mode
maxMem | Returns the maximum addressable display memory limit
refreshRate | Refresh rate to set (0 for default)
crtc | CRTC information block if afRefreshCtrl specified

Return Value

0 on success, -1 on failure

Description

This function is used to initialize a specified display mode. The mode number passed to this function should be one of the values stored in the AvailableModes list of the GA_devCtx structure combined with any of the valid mode set flags defined in the GA_modeFlagsType enumeration. Any value outside of this set of values will cause this function to fail.

When the graphics mode is initialized, you can pass in a specific virtual X resolution to enable a wide virtual display mode, or an interleaved stereo display mode. If you pass in a value of -1, the physical X resolution for the display mode will be used to initialise the virtual X resolution. If you pass in a value other than -1, the driver will attempt to satisfy your request with the next largest value that the controller can actually support. The value programmed will be returned in the virtualX parameter on exit. It is possible that the graphics mode cannot have the scanline width changed, or that the scanline width requested was too large for the graphics mode to handle, in which case this function will fail.

The virtualY parameter should be filled in with the virtual desktop height if you plan to do virtual panning, and is mostly used to compute the number of available display pages for page flipping etc, as well as where the start of offscreen memory is for the offscreen buffer manager. If this value is set to -1, the physical Y resolution of the display mode will be used to initialise the virtual Y resolution. The actual value used will be returned in the virtualY parameter on exit.

On exit this function returns the number of bytes in a logical scanline in the bytesPerLine parameter. This can then be used to implement software rendering directly to the hardware linear framebuffer. The maximum addressable display memory limit is returned in the 'maxMem' parameter and defines the byte offset of the highest linear framebuffer address that can be used by the application. The amount of addressable framebuffer display memory may not extend to the end of physical display memory due to memory used by the driver for hardware cursors and patterns etc.

You can also elect to either use the default refresh rate for the display mode or force a speific refresh rate with the refreshRate parameter. If a value of 0 is passed for the refreshRate parameter, the user selected default refresh rate will be use. A value other than zero will try to set the requested refresh rate from the table of available refresh rates that the mode supports. Make sure you first check the list of available refresh rates reported by the GetVideoModeInfo function before calling this function, or this function will fail. For generic GTF refresh rate control use the gaRefreshCtrl flag and the refreshRate parameter will be ignored. Instead the CRTC timings passed in the crtc parameter will be used for the display mode. This is most useful for unusual refresh rates not listed in the refresh rate list, such as 120Hz and higher refresh rates of LC stereo shutter glasses, or to hit exact CRTC timings for special flat panel or fixed frequency monitors.

Note: It is highly recommended that applications do not change the user selected default refresh rate except for special circumstances where a specific refresh rate is required (such as 120Hz stereo for instance).

This function also accepts the flags defined in GA_modeFlagsType enumeration logically OR'ed with the passed display mode number. These flags change the way that the selected display mode mode is initialized as follows:

The gaDontClear flag is used to specify that the video memory should not be cleared when the graphics mode is initialized. By default the video memory will be cleared to all 0's by the driver.

The gaLinearBuffer flag is used to specify that the application wishes to enable the linear framebuffer version of the graphics mode. On many controllers, the acceleration features are only available in the linear framebuffers modes. Also note that on many new PCI devices, PCI burst mode is only enabled in the linear framebuffer modes, so these modes should be used whenever possible for maximum performance. Make sure that you check the gaHaveLinearBuffer flag in the Attributes member of the GA_modeInfo structure to determine if this is supported in the selected display mode.

The ga6BitDAC flag is used to force 8-bit display modes to set the RAMDAC to a VGA compatible 6-bit per primary mode, rather than the default 8-bit per primary mode. This is generally used to make the display mode compatible with the default VESA VBE and VGA display modes. Normally applications will not want to set this but instead leave the mode in the default 8-bits per primary setting. Note also that this has no effect on 15-bpp and higher display modes.

The gaNoAccel flag is used to initialise the display mode without initialising the hardware acceleration portions of the graphics chipset. This is generally used to implement VESA VBE compatible display modes where the hardware accelerator functions are not used (and the hardware accelerator state will not be touched or changed).

The gaRefreshCtrl flag can be set to enable generic GTF refresh rate control for the display mode. If this bit is set, the mode will be using the CRTC parameters and pixel clock values passed in the crtc parameter, rather than using the value passed in the refreshRate parameter. This allows the application program or operating system drivers to calculate a new set of CRTC values (preferrably using the VESA Generalized Timing Formula, or GTF specification) for the mode, and allow the refresh rate to be set to any supported value for the hardware.

The gaWindowedMode flag is specific to emulation display drivers such as the DirectX display driver. These drivers are implemented on top of an existing abstraction layer, and this flag is used to inform the driver that the mode being set is actually a windowed mode (ie: switch back to the regular desktop display mode).

The gaPartialModeSet flag can be set to tell the SNAP driver to only perform a partial mode set instead of a complete mode set. When this flag is used, the SNAP driver will only re-program the CRTC controller and pixel clock, but will not re-program the graphics engine components. This flag is primarily used to enable SNAP drivers to change the CRTC timings and refresh rate for an existing display driver without destroying the remaining state of the graphics card.

Note: When a linear framebuffer mode is enabled, it is the responsibility of the driver to ensure that all VGA memory resources such as the 0xA0000-0xBFFFF regions are disabled if possible. Ensuring these regions are disabled provides for the maximum performance when multiple display controllers are present in the system.

See Also

SetCustomVideoMode, GetVideoModeInfo, GetCustomVideoModeInfo, SetDisplayOutput, GetClosestPixelClock

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