MGL_createDisplayDC

Create a new display device context.

Declaration

MGLDC * MGLAPI MGL_createDisplayDC(
int mode,
int numBuffers,
int refreshRate)

Prototype In

mgraph.h

Parameters

mode | Graphics mode to initialise
numBuffers | Number of buffers to allocate for double/multi-buffering.
refreshRate | Requested refresh rate for the graphics mode

Return Value

Pointer to the newly created display device context, NULL on failure

Description

Creates a new display device context for drawing information directly to the hardware display device in fullscreen graphics modes. When the device context is created, the MGL will start the graphics mode specified in the mode parameter and initialize the specific device driver. If any prior display device contexts exist, they will all be destroyed before switching to the new display mode.

If you intend to use double or multi-buffered graphics using the display device, you should set the numBuffers to the number of buffers that you require, so that the device will be properly configured for multi-buffered operation. If you request more buffers than is currently available, this function will fail. Hence you should first call MGL_availablePages to determine how many buffers can be used in the desired graphics mode.

The refresh rate value that you pass in is a suggested value in that the MGL will attempt to set the refresh rate to this value, however if the hardware does not support that refresh rate the next lowest available refresh rate will be used instead. In some situations where no refresh rate control is available, the value will be ignored and the adapter default refresh rate will be used. If you dont care about the refresh rate and want to use the adapter default setting, pass in a value of MGL_DEFAULT_REFRESH.

Once the display device context has been allocated, the surface pointer of the MGLDC structure can be used to directly access the surface of the device context as a linear block of memory. The dimensions and pixel format of the device context surface are stored in the gmode_t field of the MGLDC structure, and you should use these values to write your own direct rendering code.

Note that all device contexts have an associated color palette, even RGB device contexts. In RGB modes the color palette is used for converting color index pixel values to RGB values during BitBlt operations and with the MGL_realColor and MGL_setColorCI function.

Note: To set an interlaced refresh rate, pass in the refresh rate as a negative value. Ie: Pass a value of -87 for 87Hz interlaced.

See Also

MGL_createMemoryDC, MGL_createScrollingDisplayDC, MGL_createStereoDisplayDC, MGL_destroyDC

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