Using the Direct DrawEnumerateEx Function

The DirectDrawEnumerateEx() function provides a programmatic method of determining the number and type of DirectX-compatible display devices on a given system. The advantage of using this function is that you can call it without creating any objects or performing any other tasks. The call is a straightforward use of standard Win32 API callback functionality. With this in mind, let's look at the example code found in Listing 14.6. You can find the source code for this example in the \Chapter 14\C#\DirectXCaps and \Chapter 14\VB\DirectXCaps folders of the CD.

Listing 14.6: Enumerating Devices Using Code private void btnTest_Click(object sender, System.EventArgs e) {

Int32 Result; // The result of a call.

// Create the callback function pointer. Callbacks.DDEnumCallbackEx DDCB =

new Callbacks.DDEnumCallbackEx(DDCallback);

// Clear the display area. txtDevices.Clear();

// Call the function. This call will enumerate all of the devices. Result = Functions.DirectDrawEnumerateEx( DDCB,



// Check for errors, if (Result != Functions.DD_OK)

MessageBox.Show("The following DirectX error occured: " + Result.ToString("X"), "Application Error", MessageBoxButtons.OK, MessageBoxIcon.Error);

public Boolean DDCallback(IntPtr lpGUID,

String lpDriverDescription, String lpDriverName, IntPtr lpContext, HMONITOR hm)

// Create a StringBuilder to hold the data. // Initialize it with the current display text. StringBuilder SB = new StringBuilder(txtDevices.Text);

// Display the string data on screen. SB.Append(lpDriverName + "\r\n"); SB.Append(lpDriverDescription + "\r\n");

// Display the GUID on screen.

GUID DisplayGUID = new GUID(); Marshal.PtrToStructure(lpGUID, DisplayGUID); SB.Append("Driver GUID: ");

SB.Append(DisplayGUID.Data1.ToString() + "-"); SB.Append(DisplayGUID.Data2.ToString() + "-"); SB.Append(DisplayGUID.Data3.ToString() + "-");

Counter < DisplayGUID.Data4.Length; Counter++)


// Display the information on screen.

txtDevices.Text = SB.ToString();

// Continue the enumeration. return true;

Because the DirectXHelper library contains all of the declarations needed to use this function, we don't have to add anything special to the application. Execution begins with a call to the btnTest_Click() method. The code creates a new DDEnumCallbackEx() delegate and assigns the DDCallback() method to it. This is the callback function pointer we'll pass to the DirectDrawEnumerateEx() function. Remember that the DirectDrawEnumerateEx() function also accepts a pointer to a context object and requires that you tell it which devices to enumerate. The btnTest_Click() method should end with a call to the DirectDrawEnumerateEx() function.

Notice that, unlike the callback function examples in Chapter 5, this example checks the Result value on return from the DirectDrawEnumerateEx() function call. You can always rely on Windows to support a call that enumerates windows using a standard Win32 API call. However, there's no guarantee that the client machine will provide the required support for DirectX. The developer must include code that checks the Result value to ensure that the machine provides the required support. If it doesn't, then the developer needs to provide code to exit the application with a suitable error code. This bit of code shows a second use for the DirectDrawEnumerateExO function—validating a specific level of DirectX support. If this function fails, you know that the host machine lacks support for DirectX 6 or above.

The DirectDrawEnumerateEx() function will call the callback function DDCallback() for each DirectX compatible display device on the host system. Every device will return a driver name and description. However, the primary display adapter typically won't return a GUID or the handle of a display. Microsoft assumes that you already know this information and won't need additional input. Consequently, the DDCallbackO function always checks the lpGUID entry to ensure that it actually contains data. In all other ways, the DDCallbackO function is relatively simple and displays the data on screen. Figure 14.1 shows typical output from the example application.


* DirectDraw Capability Domo


Cvnwt D*r*e« l«»t


P»*r Dxptoy D»*«r

1 1

Figure 14.1: The example application enumerates the DirectX-compatible display devices on the host system.

Was this article helpful?

0 -1

Post a comment