/// MatchOptions struct specifies how the function makes decisions.  For example, if 
        /// the caller wants a hardware device with a back buffer format of A2B10G10R10 but the 
        /// hardware device on the system does not support A2B10G10R10 however a reference device is 
        /// installed that does, then the function has a choice to either use the reference device
        /// or to change to a back buffer format to compatible with the hardware device.  The match options lets the 
        /// caller control how these choices are made.
        /// 
        /// Each match option must be one of the following types: 
        /// MatchType.IgnoreInput: Uses the closest valid value to a default 
        /// MatchType.PreserveInput: Uses the input without change, but may cause no valid device to be found
        /// MatchType.ClosestToInput: Uses the closest valid value to the input 
        /// </summary>
        private DeviceSettings FindValidDeviceSettings(DeviceSettings settings, MatchOptions match)
        {
            // Build an optimal device settings structure based upon the match 
            // options.  If the match option is set to ignore, then a optimal default value is used.
            // The default value may not exist on the system, but later this will be taken 
            // into account.
            DeviceSettings optimalSettings = BuildOptimalDeviceSettings(settings, match);
            float bestRanking = -1.0f;
            EnumDeviceSettingsCombo bestDeviceSettingsCombo = new EnumDeviceSettingsCombo();

            // Find the best combination of:
            //      Adapter Ordinal
            //      Device Type
            //      Adapter Format
            //      Back Buffer Format
            //      Windowed
            // given what's available on the system and the match options combined with the device settings input.
            // This combination of settings is encapsulated by the EnumDeviceSettingsCombo class.
            DisplayMode adapterDesktopDisplayMode;
            for (int iAdapter = 0; iAdapter < Enumeration.AdapterInformationList.Count; iAdapter++)
            {
                EnumAdapterInformation adapterInfo = Enumeration.AdapterInformationList[iAdapter] as EnumAdapterInformation;
                
                // Get the desktop display mode of the adapter
                adapterDesktopDisplayMode = Manager.Adapters[(int)adapterInfo.AdapterOrdinal].CurrentDisplayMode;

                // Enum all the device types supported by this adapter to find the best device settings
                for (int iDeviceInfo = 0; iDeviceInfo < adapterInfo.deviceInfoList.Count; iDeviceInfo++)
                {
                    EnumDeviceInformation deviceInfo = adapterInfo.deviceInfoList[iDeviceInfo] as EnumDeviceInformation;
                    for (int iDeviceCombo = 0; iDeviceCombo<deviceInfo.deviceSettingsList.Count; iDeviceCombo++)
                    {
                        EnumDeviceSettingsCombo deviceSettings = deviceInfo.deviceSettingsList[iDeviceCombo] as EnumDeviceSettingsCombo;
                        // If windowed mode the adapter format has to be the same as the desktop 
                        // display mode format so skip any that don't match
                        if (deviceSettings.IsWindowed && (deviceSettings.AdapterFormat != adapterDesktopDisplayMode.Format))
                            continue;

                        // Skip any combo that doesn't meet the preserve match options
                        if(!DoesDeviceComboMatchPreserveOptions(deviceSettings, settings, match))
                            continue;           

                        // Get a ranking number that describes how closely this device combo matches the optimal combo
                        float curRanking = RankDeviceCombo(deviceSettings, optimalSettings, adapterDesktopDisplayMode);

                        // If this combo better matches the input device settings then save it
                        if (curRanking > bestRanking )
                        {
                            bestDeviceSettingsCombo = deviceSettings;
                            bestRanking = curRanking;
                        }                
                    }
                }
            }

            // If no best device combination was found then fail
            if (bestRanking == -1.0f)
            {
                throw new NoCompatibleDevicesException();
            }

            // Using the best device settings combo found, build valid device settings taking heed of 
            // the match options and the input device settings
            return BuildValidDeviceSettings(bestDeviceSettingsCombo, settings, match);
        }
        /// <summary>
        /// Calls FindValidDeviceSettings with default match options (all ignore)
        /// </summary>
        private DeviceSettings FindValidDeviceSettings(DeviceSettings settings)
        {
            return FindValidDeviceSettings(settings, new MatchOptions());
        }

        /// <summary>
        /// public helper function to build a device settings structure based upon the match 
        /// options.  If the match option is set to ignore, then a optimal default value is used.
        /// The default value may not exist on the system, but later this will be taken 
        /// into account.
        /// </summary>
        private DeviceSettings BuildOptimalDeviceSettings(DeviceSettings settings, MatchOptions match)
        {
            DeviceSettings optimal = new DeviceSettings(); // This will be what we return
            optimal.presentParams = new PresentParameters();

            //---------------------
            // Adapter ordinal
            //---------------------    
            if (match.AdapterOrdinal == MatchType.IgnoreInput)
                optimal.AdapterOrdinal = 0; 
            else
                optimal.AdapterOrdinal = settings.AdapterOrdinal;      

            //---------------------
            // Device type
            //---------------------
            if (match.DeviceType == MatchType.IgnoreInput)
                optimal.DeviceType = DeviceType.Hardware; 
            else
                optimal.DeviceType = settings.DeviceType;

            //---------------------
            // Windowed
            //---------------------
            if (match.Windowed == MatchType.IgnoreInput)
                optimal.presentParams.Windowed = true; 
            else
                optimal.presentParams.Windowed = settings.presentParams.Windowed;

            //---------------------
            // Adapter format
            //---------------------
            if (match.AdapterFormat == MatchType.IgnoreInput)
            {
                // If windowed, default to the desktop display mode
                // If fullscreen, default to the desktop display mode for quick mode change or 
                // default to Format.X8R8G8B8 if the desktop display mode is < 32bit
                DisplayMode adapterDesktopMode = Manager.Adapters[(int)optimal.AdapterOrdinal].CurrentDisplayMode;

                if (optimal.presentParams.Windowed || 
                    ManagedUtility.GetColorChannelBits(adapterDesktopMode.Format) >= 8 )
                    optimal.AdapterFormat = adapterDesktopMode.Format;
                else
                    optimal.AdapterFormat = Format.X8R8G8B8;
            }
            else
            {
                optimal.AdapterFormat = settings.AdapterFormat;
            }

            //---------------------
            // Vertex processing
            //---------------------
            if (match.VertexProcessing == MatchType.IgnoreInput)
                optimal.BehaviorFlags = CreateFlags.HardwareVertexProcessing; 
            else
                optimal.BehaviorFlags = settings.BehaviorFlags;

            //---------------------
            // Resolution
            //---------------------
            if (match.Resolution == MatchType.IgnoreInput)
            {
                // If windowed, default to 640x480
                // If fullscreen, default to the desktop res for quick mode change
                if (optimal.presentParams.Windowed )
                {
                    optimal.presentParams.BackBufferWidth = DefaultSizeWidth;
                    optimal.presentParams.BackBufferHeight = DefaultSizeHeight;
                }
                else
                {
                    DisplayMode adapterDesktopMode = Manager.Adapters[(int)optimal.AdapterOrdinal].CurrentDisplayMode;

                    optimal.presentParams.BackBufferWidth = adapterDesktopMode.Width;
                    optimal.presentParams.BackBufferHeight = adapterDesktopMode.Height;
                }
            }
            else
            {
                optimal.presentParams.BackBufferWidth = settings.presentParams.BackBufferWidth;
                optimal.presentParams.BackBufferHeight = settings.presentParams.BackBufferHeight;
            }

            //---------------------
            // Back buffer format
            //---------------------
            if (match.BackBufferFormat == MatchType.IgnoreInput)
                optimal.presentParams.BackBufferFormat = optimal.AdapterFormat; // Default to match the adapter format
            else
                optimal.presentParams.BackBufferFormat = settings.presentParams.BackBufferFormat;

            //---------------------
            // Back buffer count
            //---------------------
            if (match.BackBufferCount == MatchType.IgnoreInput)
                optimal.presentParams.BackBufferCount = 2; // Default to triple buffering for perf gain
            else
                optimal.presentParams.BackBufferCount = settings.presentParams.BackBufferCount;
   
            //---------------------
            // Multisample
            //---------------------
            if (match.MultiSample == MatchType.IgnoreInput)
                optimal.presentParams.MultiSampleQuality = 0; // Default to no multisampling 
            else
                optimal.presentParams.MultiSampleQuality = settings.presentParams.MultiSampleQuality;

            //---------------------
            // Swap effect
            //---------------------
            if (match.SwapEffect == MatchType.IgnoreInput)
                optimal.presentParams.SwapEffect = SwapEffect.Discard; 
            else
                optimal.presentParams.SwapEffect = settings.presentParams.SwapEffect;

            //---------------------
            // Depth stencil 
            //---------------------
            if (match.DepthFormat == MatchType.IgnoreInput &&
                match.StencilFormat == MatchType.IgnoreInput)
            {
                uint backBufferBits = ManagedUtility.GetColorChannelBits(optimal.presentParams.BackBufferFormat);
                if (backBufferBits >= 8)
                    optimal.presentParams.AutoDepthStencilFormat = DepthFormat.D32; 
                else
                    optimal.presentParams.AutoDepthStencilFormat = DepthFormat.D16; 
            }
            else
            {
                optimal.presentParams.AutoDepthStencilFormat = settings.presentParams.AutoDepthStencilFormat;
            }

            //---------------------
            // Present flags
            //---------------------
            if (match.PresentFlags == MatchType.IgnoreInput)
                optimal.presentParams.PresentFlag = PresentFlag.DiscardDepthStencil;
            else
                optimal.presentParams.PresentFlag = settings.presentParams.PresentFlag;

            //---------------------
            // Refresh rate
            //---------------------
            if (match.RefreshRate == MatchType.IgnoreInput)
                optimal.presentParams.FullScreenRefreshRateInHz = 0;
            else
                optimal.presentParams.FullScreenRefreshRateInHz = settings.presentParams.FullScreenRefreshRateInHz;

            //---------------------
            // Present interval
            //---------------------
            if (match.PresentInterval == MatchType.IgnoreInput)
            {
                // For windowed, default to PresentInterval.Immediate
                // which will wait not for the vertical retrace period to prevent tearing, 
                // but may introduce tearing.
                // For full screen, default to PresentInterval.Default 
                // which will wait for the vertical retrace period to prevent tearing.
                if (optimal.presentParams.Windowed )
                    optimal.presentParams.PresentationInterval = PresentInterval.Immediate;
                else
                    optimal.presentParams.PresentationInterval = PresentInterval.Default;
            }
            else
            {
                optimal.presentParams.PresentationInterval = settings.presentParams.PresentationInterval;
            }

            return optimal;
        }


        /// <summary>
        /// Builds valid device settings using the match options, the input device settings, and the 
        /// best device settings combo found.
        /// </summary>
        private DeviceSettings BuildValidDeviceSettings(EnumDeviceSettingsCombo deviceCombo, DeviceSettings settings, MatchOptions match)
        {
            DeviceSettings validSettings = new DeviceSettings();
            DisplayMode adapterDesktopDisplayMode = Manager.Adapters[(int)deviceCombo.AdapterOrdinal].CurrentDisplayMode;

            // For each setting pick the best, taking into account the match options and 
            // what's supported by the device

            //---------------------
            // Adapter Ordinal