Device Options and Enumeration

In just about all commercial games available today, users have the ability to customize their display options to suit their machine’s capabilities. In this tutorial, we will create_ a video options dialog that will allow users to select from such settings as display resolutions, color formats, refresh rates, depth formats, presentation intervals, and pretty much everything that is found in the PresentParameters class.

Note that this dialog uses the C-Unit GUI system. Since we haven’t learned about that yet, just think of it as a black box for now. We’ll learn about it in detail in a later tutorial.

In order to create_ this options dialog, we first have to enumerate all the different Device configurations that the client system supports. These configurations can be represented in a tree-like structure. At the top of the tree are the display adapters, or video cards. Each display adapter in a system is assigned an adapter ordinal. Usually, the adapter ordinal will be 0. The ordinal increments with each new adapter added to the system. Each display adapter also has its own set of DisplayModes that it can support and a set of Devices that it can create. The DisplayMode set specifies which screen resolution/color format/refresh rate combinations the adapter supports. The Device set is usually comprised of two Device types: a hardware device and a reference device. We pretty much always want the hardware device as a reference device is dreadfully slow and is used only to test features that are not currently implemented by the hardware.

Moving down the tree, we land on the Devices found in the list of Devices that the display adapter can make. As stated above, each Device has a unique DeviceType. Each Device also has its own Capabilities structure and list of settings that the Device supports. Each of these settings represents a unique combination of a backbuffer format, an adapter format, and either windowed or fullscreen mode. This brings us down another step of the tree.

Each Device has a list of Device settings. As stated previously, each of these settings represents a unique combination of a backbuffer format, an adapter format, and either windowed or fullscreen mode. Along with this unique combination are a bunch of lists of more settings that can be used with this combination. These additional settings include depth/stencil formats, multisample types, multisample qualities, presentation intervals, and vertex processing options. This node of the tree basically represents all the different combinations of PresentParameters that can be made given an adapter format, backbuffer format, and windowed or fullscreen flag.

The Device that we actually create_ will use a unique set of settings from the “Device Settings” node of the tree. And since we all know how nice pictures are, below is a picture of all that I just talked about:

These classes form the nodes of the tree that I described earlier. There’s a class for an adapter, a class for a DeviceType, and class for all the settings for each DeviceType. There’s also a class, DeviceSettings, that represents a unique set of all the settings put together. When we create_ or reset the Device, we’ll use the settings found in DeviceSettings to specify how to create_ or reset the Device.

To implement all this enumeration mumbo jumbo, the C-Unit Framework has a Graphics class that finds all the supported Device configurations and allows us to create_ a Device with one of these configurations. To do this, the Graphics class will store three different DeviceSettings instances: one for fullscreen mode, one for windowed mode, and one that we’ll use as the current settings, which will switch between the fullscreen and windowed settings. Before we can set the DeviceSettings instances, we have to enumerate through all the possible Device configurations that the system supports. To do this however, we’ll first create_ a few arrays that specify the possible values that the settings can take.

These arrays form all the different possible values that we will test support for. The contents of each array are specified in preference order. When we create_ the initial DeviceSettings instance, we’ll use the values found at the beginning of each array. If you don’t know what all these values are used for, head over to MSDN’s Direct3D page and practice your lookup skills Once these arrays are specified, we can begin the enumeration process.

The enumeration process begins in EnumerateAdapters, and works its way to the bottom of the tree, filling up the ArrayLists along the way.

We start by getting each of the adapters connected to the computer by looking through each of the AdapterInformation’s found in the Manager.Adapters property. After storing some adapter information, we move on to enumerate all the adapter’s supported DisplayModes in EnumerateDisplayModes.

All of an adapter’s supported DisplayModes are found in the aptly named property, AdapterInformation.SupportedDisplayModes. While we’re storing the DisplayModes, we’ll also keep a separate copy of the Format of each DisplayMode, which we will use to help define the rest of the settings.

After the DisplayModes have been enumerated, we enumerate the Devices with EnumerateDevices. In EnumerateDevices, we create_ a new DeviceEnum instance for each DeviceType. We’ll store the Capabilities of the Device with the help of the Manager.GetDeviceCaps method. Note that a DeviceType.Software device will throw an exception, which is not big deal so we’ll just catch it and do nothing. After we have the Capabilities, we move on to EnumerateDeviceSettings. If any settings are enumerated, we add the DeviceEnum to our list of Devices.

EnumerateDeviceSettings begins by creating a new DeviceSettingsEnum instance. However, we will only create_ an instance if the current settings so far are supported by the display adapter. We can check for support by using the Manager.CheckDeviceType method. After filling out the members of the DeviceSettingsEnum that we already know, we move on to enumerate the rest of the Device settings.

The last four enumerate methods, EnumerateDepthStencilFormats, EnumerateMultiSampleTypes, EnumerateVertexProcessingTypes, and EnumeratePresentIntervals all fill up their respective ArrayLists of the current DeviceSettingsEnum instance. The Depth/Stencil Format list is filled up with the help of the Manager.CheckDeviceFormat and Manager.CheckDepthStencilMatch methods. The MultiSample type and quality lists are filled up with the help of the Manager.CheckDeviceMultiSampleType method. Finally, the VertexProcessing and PresentInterval lists are filled up by checking the values in the Capabilities structure. After all the foreach loops finish, we’ll have all the possible Device configurations stored neatly away in our AdapterEnum ArrayList.

Once we have enumerated all the Device configurations, we’ll use the above methods to create_ our initial DeviceSettings instances. As stated earlier, the Graphics class will have one DeviceSettings instance for windowed mode and one for fullscreen mode. To initialize these instances, we’ll look through all the supported Device configurations that we enumerated and pick out the best configuration for windowed mode and best for fullscreen mode. While the “best” configuration can change from person to person, I simply chose the best windowed configuration as the one which uses a hardware device and where the adapter format is the same as the backbuffer format. For the fullscreen configuration, I chose one which uses a hardware device and where the adapter format is the same as both the backbuffer format and the current DisplayMode format.

At this point we have enumerated all possible Device configurations that our system can support and we have chosen a couple of initial configurations to get us up and running. Now we need to be able to choose from among the slew of Device configurations. That is where DeviceOptionsDialog comes in.

The DeviceOptionsDialog class inherits from GameState so we can add it to the Framework’s state stack. When the user toggle the dialog, it is added to the stack and when the user hits the OK or Cancel button, it is removed from the stack.

DeviceOptionsDialog manipulates a DeviceSettings object through a series of C-Unit GUI ComboBoxes. Again, since we haven’t learned about the GUI yet, ignore all that code and focus on the UpdateControlValues method.

The main workhorse method of DeviceOptionsDialog is the UpdateControlValues method. The UpdateControlValues method will take in a DeviceSettings instance, and set all the values of the ComboBoxes based on the values of the DeviceSettings parameter. This includes leaving out incompatible values and only displaying values that are valid with the currently selected values. For example, some refresh rates are only available with certain screen resolutions. So the only selectable refresh rates will be those that are valid with the currently selected resolution.

Whenever a new value is selected, the OnControl method is called where the new value is stored in the m_newSettings instance. After we store the new value, the Controls are all updated to account for the new value by calling the UpdateControlValues method.

Notice that when some values are changed, other values are selected automatically. For example, when we toggle the Fullscreen Mode Radio button (in OnControl: case (int)ControlID.RadioFullscreen), the backbuffer format is automatically changed to the same format as the adapter. We do this because values currently selected in some fields may not be compatible with new values that we select, so we need to adjust the values accordingly. Once a new set of values is created, it’s just a matter of handing them off to the Framework so it can update_ the Device. DeviceOptionsDialog tells the Framework about the new settings in OnUpdateFrame.

We know know enough about the C-Unit Framework that we can start rendering interesting geometry…like triangles…