Secondary Display Drivers (Windows Embedded CE 6.0)

Article
01/05/2012

1/6/2010

In addition to the primary display, Windows Embedded CE–based platforms can support additional display devices.

These additional display devices might be used, for example, to support Video Graphics Adapter (VGA) output to a CRT screen.

Drivers for such additional display devices are called secondary display drivers.

Secondary Display Driver Hardware

Hardware platforms might have a secondary display controller. Use a secondary display driver to manage the secondary display controller.

You can have two different display cards in the system at once. GWES enables the first card in the HKEY_LOCAL_MACHINE\System\GDI\DisplayCandidates registry key as the primary.

This registry key is usually set up in Platform.reg. If there are no display driver registry settings in the DisplayCandidates subkey, GWES enables the first one in the HKEY_LOCAL_MACHINE\System\GDI\Drivers registry key.

If the display controller resides on a removable medium, such as a PC card, the secondary display driver can be implemented as one or two DLLs.

In practice, you typically implement two separate DLLs:

A secondary display driver that exposes the built-in display DDI
A driver that exposes the stream interface

The following code shows example registry entries for setting up multiple display driver candidates on a PCI bus.

[HKEY_LOCAL_MACHINE\System\GDI\DisplayCandidates]
   "Candidate1"="Drivers\\BuiltIn\\PCI\\Instance\\Primary"
   "Candidate2"="Drivers\\BuiltIn\\PCI\\Instance\\Secondary"

[$(PCI_BUS_ROOT)\Template\Primary]
   "DisplayDll"="ddi_primary.dll"
   <other PCI info here>

[$(PCI_BUS_ROOT)\Template\Secondary]
   "DisplayDll"="ddi_secondary.dll"
   <other PCI info here>

The following code shows example registry entries for setting up multiple display driver candidates on a bus other than a PCI bus.

 [HKEY_LOCAL_MACHINE\System\GDI\DisplayCandidates]
   "Candidate1"="Drivers\\Display\\Primary"
   "Candidate2"="Drivers\\Display\\Secondary"

[HKEY_LOCAL_MACHINE\Drivers\Display\Primary]
   "DisplayDll"="ddi_primary.dll"
   <other display specific info here>

[HKEY_LOCAL_MACHINE\Drivers\Display\Secondary]
   "DisplayDll"="ddi_secondary.dll"
   <other display specific info here>

In both examples above, GDI would first search for the Candidate1 display driver, then the Candidate2 driver, and if there were additional candidates it would go on to search those in succession as well. Once GDI successfully finds the DLL associated with a candidate, that candidate becomes the primary display and it ignores all subsequent candidates.

Loading Secondary Display Drivers

Load your secondary display driver by calling CreateDC. CreateDC returns a handle to a device context that is associated with the secondary display driver. This is something that you must do explicitly. GDI does not search through the list of display candidates to automatically load a secondary display.

If you have your secondary display driver entered in the list of display candidates and GDI somehow fails to load the primary display driver, then GDI will load the secondary display driver as the primary because it is next in the list of candidates.

An application can use the device context returned by CreateDC similarly to a device context associated with the primary display driver: the text and graphics APIs work with the device context.

However, applications cannot use Window Manager functions with the device context because the Window Manager was not involved in creating it. Thus, applications are responsible for rendering the entire display on the secondary display device.

The secondary display driver must create registry entries that enable the device to be detected.

If you want to create the appearance of windows, menus, dialog boxes, and scroll bars on the secondary display, your application must draw those items itself, using the text and graphics APIs.

The only way to copy from the primary to the secondary is through a device independent bitmap, which must be selected into a primary compatible DC; then it must have the primary copied onto it; and finally it must be selected into a secondary compatible DC and copied to the secondary.

Copying from one device to the other without doing this will result in an exception because one display driver will attempt to access the other display driver's surfaces.

The secondary display driver is unloaded when there are no remaining device contexts associated with it. When multiple display devices are being used, the GDI ensures that all drawing calls are routed to the appropriate display driver.

The Device Manager loads the stream interface driver when a user connects the display adapter to the system and registers the driver's special device file name (for example, VGA1:). The secondary display driver gets a handle to the stream interface driver by calling the CreateFile function on the VGA1: device file name.

Secondary Display Driver Implementation

You can create a single DLL that behaves as both a secondary display driver and a stream driver.

In this case, the Device Manager loads this combined driver in its own process space to serve as an ordinary stream interface driver, whereas GWES would load the same driver in its process space to act as the secondary display driver.

Implement the secondary display driver as an ordinary Windows Embedded CE–based display driver, and expose the same display DDI as other display drivers.

The ATI display driver can have multiple instances of itself on a PCI bus.

If you implement a combined driver, be aware that because the driver DLL is loaded in separate process spaces, it cannot share global data without using shared memory or a memory-mapped file. Further, having the driver loaded twice wastes system resources.

Display device drivers do not use many stream interface functions because display devices are not oriented to work with streams of data. Display drivers only need stubs for those functions. For these interfaces, the driver should handle the call and return.

The driver's XXX_Init (Device Manager) and XXX_Deinit (Device Manager) functions are exceptions. The driver should handle calls to these functions correctly.

When the display adapter is connected to the system, the Device Manager calls XXX_Init.

When the adapter is disconnected, the Device Manager calls XXX_Deinit. The XXX_Deinit function deletes data structures and registry entries that were created by the driver's XXX_Init function.

The secondary display driver handles the graphics processing. When the secondary display driver needs to communicate with the display controller, it uses the stream interface's XXX_IOControl (Device Manager) function.

Secondary Display Drivers (Windows Embedded CE 6.0)

Secondary Display Driver Hardware

Loading Secondary Display Drivers

Secondary Display Driver Implementation

See Also

Reference

Concepts

Other Resources

Additional resources