Graphics apps can use the DXGI API to retrieve an accurate set of graphics memory values on systems that have Windows Display Driver Model (WDDM) drivers. The following are the critical steps involved.

• Graphics driver model determination ? Because DXGI is only available on systems with WDDM drivers, the app must first confirm the driver model by using the following API.

   HasWDDMDriver()
              { LPDIRECT3DCREATE9EX pD3D9Create9Ex = null; HMODULE             hD3D9          = null; hD3D9 = LoadLibrary( L"d3d9.dll" ); if ( null == hD3D9 ) { return false; } // /*  Try to create IDirect3D9Ex interface (also known as a DX9L interface). This interface can only be created if the driver is a WDDM driver. */ // pD3D9Create9Ex = (LPDIRECT3DCREATE9EX) GetProcAddress( hD3D9, "Direct3DCreate9Ex" ); return pD3D9Create9Ex != null;
              } 

• Retrieval of graphics memory values.? After the app determines the driver model to be WDDM, the app can use the Direct3D 10 or later API and DXGI to get the amount of graphics memory. After you create a Direct3D device, use this code to obtain a structure that contains the amount of available graphics memory.

    * pDXGIDevice;
              hr = g_pd3dDevice->QueryInterface(__uuidof(), (void **)&pDXGIDevice);
               * pDXGIAdapter;
              pDXGIDevice->GetAdapter(&pDXGIAdapter);
               adapterDesc;
              pDXGIAdapter->GetDesc(&adapterDesc); 

When the EnumOutputs method succeeds and fills the ppOutput parameter with the address of the reference to the output interface, EnumOutputs increments the output interface's reference count. To avoid a memory leak, when you finish using the output interface, call the Release method to decrement the reference count.

EnumOutputs first returns the output on which the desktop primary is displayed. This output corresponds with an index of zero. EnumOutputs then returns other outputs.

Graphics apps can use the DXGI API to retrieve an accurate set of graphics memory values on systems that have Windows Display Driver Model (WDDM) drivers. The following are the critical steps involved.

• Graphics driver model determination ? Because DXGI is only available on systems with WDDM drivers, the app must first confirm the driver model by using the following API.

   HasWDDMDriver()
              { LPDIRECT3DCREATE9EX pD3D9Create9Ex = null; HMODULE             hD3D9          = null; hD3D9 = LoadLibrary( L"d3d9.dll" ); if ( null == hD3D9 ) { return false; } // /*  Try to create IDirect3D9Ex interface (also known as a DX9L interface). This interface can only be created if the driver is a WDDM driver. */ // pD3D9Create9Ex = (LPDIRECT3DCREATE9EX) GetProcAddress( hD3D9, "Direct3DCreate9Ex" ); return pD3D9Create9Ex != null;
              } 

• Retrieval of graphics memory values.? After the app determines the driver model to be WDDM, the app can use the Direct3D 10 or later API and DXGI to get the amount of graphics memory. After you create a Direct3D device, use this code to obtain a structure that contains the amount of available graphics memory.

    * pDXGIDevice;
              hr = g_pd3dDevice->QueryInterface(__uuidof(), (void **)&pDXGIDevice);
               * pDXGIAdapter;
              pDXGIDevice->GetAdapter(&pDXGIAdapter);
               adapterDesc;
              pDXGIAdapter->GetDesc(&adapterDesc); 

If the GetAdapter method succeeds, the reference count on the adapter interface will be incremented. To avoid a memory leak, be sure to release the interface when you are finished using it.

If the GetAdapter method succeeds, the reference count on the adapter interface will be incremented. To avoid a memory leak, be sure to release the interface when you are finished using it.

The CreateSurface method creates a buffer to exchange data between one or more devices. It is used internally, and you should not directly call it.

The runtime automatically creates an interface when it creates a Direct3D resource object that represents a surface. For example, the runtime creates an interface when it calls ID3D11Device::CreateTexture2D or ID3D10Device::CreateTexture2D to create a 2D texture. To retrieve the interface that represents the 2D texture surface, call ID3D11Texture2D::QueryInterface or ID3D10Texture2D::QueryInterface. In this call, you must pass the identifier of . If the 2D texture has only a single MIP-map level and does not consist of an array of textures, QueryInterface succeeds and returns a reference to the interface reference. Otherwise, QueryInterface fails and does not return the reference to .

The information returned by the pResidencyStatus argument array describes the residency status at the time that the QueryResourceResidency method was called.

If you call the QueryResourceResidency method during a device removed state, the pResidencyStatus argument will return the DXGI_RESIDENCY_RESIDENT_IN_SHARED_MEMORY flag.

The values for the Priority parameter function as follows:

• Positive values increase the likelihood that the GPU scheduler will grant GPU execution cycles to the device when rendering.
• Negative values lessen the likelihood that the device will receive GPU execution cycles when devices compete for them.
• The device is guaranteed to receive some GPU execution cycles at all settings.

To use the SetGPUThreadPriority method, you should have a comprehensive understanding of GPU scheduling. You should profile your application to ensure that it behaves as intended. If used inappropriately, the SetGPUThreadPriority method can impede rendering speed and result in a poor user experience.

The type of interface that is returned can be any interface published by the device. For example, it could be an * called pDevice, and therefore the REFIID would be obtained by calling __uuidof(pDevice).

SetPrivateData makes a copy of the specified data and stores it with the object.

Private data that SetPrivateData stores in the object occupies the same storage space as private data that is stored by associated Direct3D objects (for example, by a Microsoft Direct3D?11 device through ID3D11Device::SetPrivateData or by a Direct3D?11 child device through ID3D11DeviceChild::SetPrivateData).

The debug layer reports memory leaks by outputting a list of object interface references along with their friendly names. The default friendly name is "<unnamed>". You can set the friendly name so that you can determine if the corresponding object interface reference caused the leak. To set the friendly name, use the SetPrivateData method and the well-known private data () that is in D3Dcommon.h. For example, to give pContext a friendly name of My name, use the following code:

 static const char c_szName[] = "My name";
            hr = pContext->SetPrivateData( , sizeof( c_szName ) - 1, c_szName );
            

You can use to track down memory leaks and understand performance characteristics of your applications. This information is reflected in the output of the debug layer that is related to memory leaks (ID3D11Debug::ReportLiveDeviceObjects) and with the event tracing for Windows events that we've added to Windows?8.

This API associates an interface reference with the object.

When the interface is set its reference count is incremented. When the data are overwritten (by calling SPD or SPDI with the same ) or the object is destroyed, ::Release() is called and the interface's reference count is decremented.

If the data returned is a reference to an , or one of its derivative classes, previously set by IDXGIObject::SetPrivateDataInterface, you must call ::Release() on the reference before the reference is freed to decrement the reference count.

You can pass GUID_DeviceType in the Name parameter of GetPrivateData to retrieve the device type from the display adapter object (, , ).

To get the type of device on which the display adapter was created

1. Call IUnknown::QueryInterface on the or ID3D10Device object to retrieve the object.
2. Call GetParent on the object to retrieve the object.
3. Call GetPrivateData on the object with GUID_DeviceType to retrieve the type of device on which the display adapter was created. pData will point to a value from the driver-type enumeration (for example, a value from ).

On Windows?7 or earlier, this type is either a value from D3D10_DRIVER_TYPE or depending on which kind of device was created. On Windows?8, this type is always a value from . Don't use IDXGIObject::SetPrivateData with GUID_DeviceType because the behavior when doing so is undefined.

When you create a factory, the factory enumerates the set of adapters that are available in the system. Therefore, if you change the adapters in a system, you must destroy and recreate the object. The number of adapters in a system changes when you add or remove a display card, or dock or undock a laptop.

When the EnumAdapters method succeeds and fills the ppAdapter parameter with the address of the reference to the adapter interface, EnumAdapters increments the adapter interface's reference count. When you finish using the adapter interface, call the Release method to decrement the reference count before you destroy the reference.

EnumAdapters first returns the adapter with the output on which the desktop primary is displayed. This adapter corresponds with an index of zero. EnumAdapters next returns other adapters with outputs. EnumAdapters finally returns adapters without outputs.

The combination of WindowHandle and Flags informs DXGI to stop monitoring window messages for the previously-associated window.

If the application switches to full-screen mode, DXGI will choose a full-screen resolution to be the smallest supported resolution that is larger or the same size as the current back buffer size.

Applications can make some changes to make the transition from windowed to full screen more efficient. For example, on a WM_SIZE message, the application should release any outstanding swap-chain back buffers, call IDXGISwapChain::ResizeBuffers, then re-acquire the back buffers from the swap chain(s). This gives the swap chain(s) an opportunity to resize the back buffers, and/or recreate them to enable full-screen flipping operation. If the application does not perform this sequence, DXGI will still make the full-screen/windowed transition, but may be forced to use a stretch operation (since the back buffers may not be the correct size), which may be less efficient. Even if a stretch is not required, presentation may not be optimal because the back buffers might not be directly interchangeable with the front buffer. Thus, a call to ResizeBuffers on WM_SIZE is always recommended, since WM_SIZE is always sent during a fullscreen transition.

While windowed, the application can, if it chooses, restrict the size of its window's client area to sizes to which it is comfortable rendering. A fully flexible application would make no such restriction, but UI elements or other design considerations can, of course, make this flexibility untenable. If the application further chooses to restrict its window's client area to just those that match supported full-screen resolutions, the application can field WM_SIZING, then check against IDXGIOutput::FindClosestMatchingMode. If a matching mode is found, allow the resize. (The can be retrieved from IDXGISwapChain::GetContainingOutput. Absent subsequent changes to desktop topology, this will be the same output that will be chosen when alt-enter is fielded and fullscreen mode is begun for that swap chain.)

Applications that want to handle mode changes or Alt+Enter themselves should call MakeWindowAssociation with the DXGI_MWA_NO_WINDOW_CHANGES flag after swap chain creation. The WindowHandle argument, if non-null, specifies that the application message queues will not be handled by the DXGI runtime for all swap chains of a particular target . Calling MakeWindowAssociation with the DXGI_MWA_NO_WINDOW_CHANGES flag after swapchain creation ensures that DXGI will not interfere with application's handling of window mode changes or Alt+Enter.

If you attempt to create a swap chain in full-screen mode, and full-screen mode is unavailable, the swap chain will be created in windowed mode and DXGI_STATUS_OCCLUDED will be returned.

If the buffer width or the buffer height is zero, the sizes will be inferred from the output window size in the swap-chain description.

Because the target output can't be chosen explicitly when the swap chain is created, we recommend not to create a full-screen swap chain. This can reduce presentation performance if the swap chain size and the output window size do not match. Here are two ways to ensure that the sizes match:

• Create a windowed swap chain and then set it full-screen using IDXGISwapChain::SetFullscreenState.
• Save a reference to the swap chain immediately after creation, and use it to get the output window size during a WM_SIZE event. Then resize the swap chain buffers (with IDXGISwapChain::ResizeBuffers) during the transition from windowed to full-screen.

If the swap chain is in full-screen mode, before you release it you must use SetFullscreenState to switch it to windowed mode. For more information about releasing a swap chain, see the "Destroying a Swap Chain" section of DXGI Overview.

After the runtime renders the initial frame in full screen, the runtime might unexpectedly exit full screen during a call to IDXGISwapChain::Present. To work around this issue, we recommend that you execute the following code right after you call CreateSwapChain to create a full-screen swap chain (Windowed member of set to ).

 // Detect if newly created full-screen swap chain isn't actually full screen.
            * pTarget;  bFullscreen;
            if (SUCCEEDED(pSwapChain->GetFullscreenState(&bFullscreen, &pTarget)))
            { pTarget->Release();
            }
            else bFullscreen = ;
            // If not full screen, enable full screen again.
            if (!bFullscreen)
            { ShowWindow(hWnd, SW_MINIMIZE); ShowWindow(hWnd, SW_RESTORE); pSwapChain->SetFullscreenState(TRUE, null);
            }
            

You can specify and values in the swap-chain description that pDesc points to. These values allow you to use features like flip-model presentation and content protection by using pre-Windows?8 APIs.

However, to use stereo presentation and to change resize behavior for the flip model, applications must use the IDXGIFactory2::CreateSwapChainForHwnd method. Otherwise, the back-buffer contents implicitly scale to fit the presentation target size; that is, you can't turn off scaling.

A software adapter is a DLL that implements the entirety of a device driver interface, plus emulation, if necessary, of kernel-mode graphics components for Windows. Details on implementing a software adapter can be found in the Windows Vista Driver Development Kit. This is a very complex development task, and is not recommended for general readers.

Calling this method will increment the module's reference count by one. The reference count can be decremented by calling FreeLibrary.

The typical calling scenario is to call LoadLibrary, pass the handle to CreateSoftwareAdapter, then immediately call FreeLibrary on the DLL and forget the DLL's HMODULE. Since the software adapter calls FreeLibrary when it is destroyed, the lifetime of the DLL will now be owned by the adapter, and the application is free of any further consideration of its lifetime.

This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).

This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).

When you create a factory, the factory enumerates the set of adapters that are available in the system. Therefore, if you change the adapters in a system, you must destroy and recreate the object. The number of adapters in a system changes when you add or remove a display card, or dock or undock a laptop.

When the EnumAdapters1 method succeeds and fills the ppAdapter parameter with the address of the reference to the adapter interface, EnumAdapters1 increments the adapter interface's reference count. When you finish using the adapter interface, call the Release method to decrement the reference count before you destroy the reference.

EnumAdapters1 first returns the adapter with the output on which the desktop primary is displayed. This adapter corresponds with an index of zero. EnumAdapters1 next returns other adapters with outputs. EnumAdapters1 finally returns adapters without outputs.

This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).

We recommend that windowed applications call IsWindowedStereoEnabled before they attempt to use stereo. IsWindowedStereoEnabled returns TRUE if both of the following items are true:

• All adapters in the computer have drivers that are capable of stereo. This only means that the driver is implemented to the Windows Display Driver Model (WDDM) for Windows?8 (WDDM 1.2). However, the adapter does not necessarily have to be able to scan out stereo.
• The current desktop mode (desktop modes are mono) and system policy and hardware are configured so that the Desktop Window Manager (DWM) performs stereo composition on at least one adapter output.

The creation of a windowed stereo swap chain succeeds if the first requirement is met. However, if the adapter can't scan out stereo, the output on that adapter is reduced to mono.

The Direct3D 11.1 Simple Stereo 3D Sample shows how to add a stereoscopic 3D effect and how to respond to system stereo changes.

We recommend that windowed applications call IsWindowedStereoEnabled before they attempt to use stereo. IsWindowedStereoEnabled returns TRUE if both of the following items are true:

• All adapters in the computer have drivers that are capable of stereo. This only means that the driver is implemented to the Windows Display Driver Model (WDDM) for Windows?8 (WDDM 1.2). However, the adapter does not necessarily have to be able to scan out stereo.
• The current desktop mode (desktop modes are mono) and system policy and hardware are configured so that the Desktop Window Manager (DWM) performs stereo composition on at least one adapter output.

The creation of a windowed stereo swap chain succeeds if the first requirement is met. However, if the adapter can't scan out stereo, the output on that adapter is reduced to mono.

The Direct3D 11.1 Simple Stereo 3D Sample shows how to add a stereoscopic 3D effect and how to respond to system stereo changes.

If you specify the width, height, or both (Width and Height members of that pDesc points to) of the swap chain as zero, the runtime obtains the size from the output window that the hWnd parameter specifies. You can subsequently call the IDXGISwapChain1::GetDesc1 method to retrieve the assigned width or height value.

Because you can associate only one flip presentation model swap chain at a time with an , the Microsoft Direct3D?11 policy of deferring the destruction of objects can cause problems if you attempt to destroy a flip presentation model swap chain and replace it with another swap chain. For more info about this situation, see Deferred Destruction Issues with Flip Presentation Swap Chains.

For info about how to choose a format for the swap chain's back buffer, see Converting data for the color space.

If you specify the width, height, or both (Width and Height members of that pDesc points to) of the swap chain as zero, the runtime obtains the size from the output window that the pWindow parameter specifies. You can subsequently call the IDXGISwapChain1::GetDesc1 method to retrieve the assigned width or height value.

Because you can associate only one flip presentation model swap chain (per layer) at a time with a CoreWindow, the Microsoft Direct3D?11 policy of deferring the destruction of objects can cause problems if you attempt to destroy a flip presentation model swap chain and replace it with another swap chain. For more info about this situation, see Deferred Destruction Issues with Flip Presentation Swap Chains.

For info about how to choose a format for the swap chain's back buffer, see Converting data for the color space.

You cannot share resources across adapters. Therefore, you cannot open a shared resource on an adapter other than the adapter on which the resource was created. Call GetSharedResourceAdapterLuid before you open a shared resource to ensure that the resource was created on the appropriate adapter. To open a shared resource, call the ID3D11Device1::OpenSharedResource1 or ID3D11Device1::OpenSharedResourceByName method.

Platform Update for Windows?7:??On Windows?7 or Windows Server?2008?R2 with the Platform Update for Windows?7 installed, UnregisterStereoStatus has no effect. For more info about the Platform Update for Windows?7, see Platform Update for Windows 7.

Apps choose the Windows message that Windows sends when occlusion status changes.

If you call RegisterOcclusionStatusEvent multiple times with the same event handle, RegisterOcclusionStatusEvent fails with .

If you call RegisterOcclusionStatusEvent multiple times with the different event handles, RegisterOcclusionStatusEvent properly registers the events.

Platform Update for Windows?7:??On Windows?7 or Windows Server?2008?R2 with the Platform Update for Windows?7 installed, UnregisterOcclusionStatus has no effect. For more info about the Platform Update for Windows?7, see Platform Update for Windows 7.

You can use composition swap chains with either DirectComposition?s interface or XAML?s SwapChainBackgroundPanel class. For DirectComposition, you can call the IDCompositionVisual::SetContent method to set the swap chain as the content of a visual object, which then allows you to bind the swap chain to the visual tree. For XAML, the SwapChainBackgroundPanel class exposes a classic COM interface . You can use the ISwapChainBackgroundPanelNative::SetSwapChain method to bind to the XAML UI graph. For info about how to use composition swap chains with XAML?s SwapChainBackgroundPanel class, see DirectX and XAML interop.

The IDXGISwapChain::SetFullscreenState, IDXGISwapChain::ResizeTarget, IDXGISwapChain::GetContainingOutput, IDXGISwapChain1::GetHwnd, and IDXGISwapChain::GetCoreWindow methods aren't valid on this type of swap chain. If you call any of these methods on this type of swap chain, they fail.

For info about how to choose a format for the swap chain's back buffer, see Converting data for the color space.

For Direct3D 12, it's no longer possible to backtrack from a device to the that was used to create it. IDXGIFactory4::EnumAdapterByLuid enables an app to retrieve information about the adapter where a D3D12 device was created. IDXGIFactory4::EnumAdapterByLuid is designed to be paired with ID3D12Device::GetAdapterLuid. For more information, see DXGI 1.4 Improvements.

For more information, see DXGI 1.4 Improvements.

This method doesn't remove any messages from the message queue.

This method gets a message from the message queue after an optional retrieval filter has been applied.

Call this method twice to retrieve a message, first to obtain the size of the message and second to get the message. Here is a typical example:

 // Get the size of the message.
             messageLength = 0;
             hr = pInfoQueue->GetMessage(DXGI_DEBUG_ALL, 0, null, &messageLength); // Allocate space and get the message.
             * pMessage = (*)malloc(messageLength);
            hr = pInfoQueue->GetMessage(DXGI_DEBUG_ALL, 0, pMessage, &messageLength);
            

Get and set the message count limit with IDXGIInfoQueue::GetMessageCountLimit and IDXGIInfoQueue::SetMessageCountLimit, respectively.

When the number of messages in the message queue reaches the maximum limit, new messages coming in push old messages out.

An empty storage filter allows all messages to pass through.

A deny-all storage filter prevents all messages from passing through.

An empty retrieval filter allows all messages to pass through.

A deny-all retrieval filter prevents all messages from passing through.

This method is implemented by the developer.

This structure is used by the GetDisplayModeList and FindClosestMatchingMode methods.

The following format values are valid for display modes and when you create a bit-block transfer (bitblt) model swap chain. The valid values depend on the feature level that you are working with.

• Feature level >= 9.1

  • DXGI_FORMAT_R8G8B8A8_UNORM
  • DXGI_FORMAT_R8G8B8A8_UNORM_SRGB
  • DXGI_FORMAT_B8G8R8A8_UNORM (except 10.x on Windows?Vista)
  • DXGI_FORMAT_B8G8R8A8_UNORM_SRGB (except 10.x on Windows?Vista)

• Feature level >= 10.0

  • DXGI_FORMAT_R16G16B16A16_FLOAT
  • DXGI_FORMAT_R10G10B10A2_UNORM

• Feature level >= 11.0

  • DXGI_FORMAT_R10G10B10_XR_BIAS_A2_UNORM

You can pass one of these format values to ID3D11Device::CheckFormatSupport to determine if it is a valid format for displaying on screen. If ID3D11Device::CheckFormatSupport returns D3D11_FORMAT_SUPPORT_DISPLAY in the bit field to which the pFormatSupport parameter points, the format is valid for displaying on screen.

Starting with Windows?8 for a flip model swap chain (that is, a swap chain that has the DXGI_SWAP_EFFECT_FLIP_SEQUENTIAL value set in the SwapEffect member of ), you must set the Format member of to DXGI_FORMAT_R16G16B16A16_FLOAT, DXGI_FORMAT_B8G8R8A8_UNORM, or DXGI_FORMAT_R8G8B8A8_UNORM.

Because of the relaxed render target creation rules that Direct3D 11 has for back buffers, applications can create a DXGI_FORMAT_B8G8R8A8_UNORM_SRGB render target view from a DXGI_FORMAT_B8G8R8A8_UNORM swap chain so they can use automatic color space conversion when they render the swap chain.

On a high DPI desktop, GetDesc returns the visualized screen size unless the app is marked high DPI aware. For info about writing DPI-aware Win32 apps, see High DPI.

For info about using gamma correction, see Using gamma correction.

For info about using gamma correction, see Using gamma correction.

This API is similar to IDXGISwapChain::GetFrameStatistics.

On a high DPI desktop, GetDesc returns the visualized screen size unless the app is marked high DPI aware. For info about writing DPI-aware Win32 apps, see High DPI.

In general, when switching from windowed to full-screen mode, a swap chain automatically chooses a display mode that meets (or exceeds) the resolution, color depth and refresh rate of the swap chain. To exercise more control over the display mode, use this API to poll the set of display modes that are validated against monitor capabilities, or all modes that match the desktop (if the desktop settings are not validated against the monitor).

As shown, this API is designed to be called twice. First to get the number of modes available, and second to return a description of the modes.

 UINT num = 0;
             format = DXGI_FORMAT_R32G32B32A32_FLOAT;
            UINT flags         = DXGI_ENUM_MODES_INTERLACED; pOutput->GetDisplayModeList( format, flags, &num, 0); ...  * pDescs = new [num];
            pOutput->GetDisplayModeList( format, flags, &num, pDescs); 

FindClosestMatchingMode behaves similarly to the IDXGIOutput1::FindClosestMatchingMode1 except FindClosestMatchingMode considers only the mono display modes. IDXGIOutput1::FindClosestMatchingMode1 considers only stereo modes if you set the Stereo member in the structure that pModeToMatch points to, and considers only mono modes if Stereo is not set.

IDXGIOutput1::FindClosestMatchingMode1 returns a matched display-mode set with only stereo modes or only mono modes. FindClosestMatchingMode behaves as though you specified the input mode as mono.

A vertical blank occurs when the raster moves from the lower right corner to the upper left corner to begin drawing the next frame.

When you are finished with the output, call IDXGIOutput::ReleaseOwnership.

TakeOwnership should not be called directly by applications, since results will be unpredictable. It is called implicitly by the DXGI swap chain object during full-screen transitions, and should not be used as a substitute for swap-chain methods.

If you are not using a swap chain, get access to an output by calling IDXGIOutput::TakeOwnership and release it when you are finished by calling IDXGIOutput::ReleaseOwnership. An application that uses a swap chain will typically not call either of these methods.

For info about using gamma correction, see Using gamma correction.

For info about using gamma correction, see Using gamma correction.

For info about using gamma correction, see Using gamma correction.

IDXGIOutput::SetDisplaySurface should not be called directly by applications, since results will be unpredictable. It is called implicitly by the DXGI swap chain object during full-screen transitions, and should not be used as a substitute for swap-chain methods.

This method should only be called between IDXGIOutput::TakeOwnership and IDXGIOutput::ReleaseOwnership calls.

IDXGIOutput::GetDisplaySurfaceData can only be called when an output is in full-screen mode. If the method succeeds, DXGI fills the destination surface.

Use IDXGIOutput::GetDesc to determine the size (width and height) of the output when you want to allocate space for the destination surface. This is true regardless of target monitor rotation. A destination surface created by a graphics component (such as Direct3D 10) must be created with CPU-write permission (see D3D10_CPU_ACCESS_WRITE). Other surfaces should be created with CPU read-write permission (see D3D10_CPU_ACCESS_READ_WRITE). This method will modify the surface data to fit the destination surface (stretch, shrink, convert format, rotate). The stretch and shrink is performed with point-sampling.

This API is similar to IDXGISwapChain::GetFrameStatistics.

GetDisplayModeList1 is updated from GetDisplayModeList to return a list of structures, which are updated mode descriptions. GetDisplayModeList behaves as though it calls GetDisplayModeList1 because GetDisplayModeList can return all of the modes that are specified by DXGI_ENUM_MODES, including stereo mode. However, GetDisplayModeList returns a list of structures, which are the former mode descriptions and do not indicate stereo mode.

The GetDisplayModeList1 method does not enumerate stereo modes unless you specify the flag in the Flags parameter. If you specify , stereo modes are included in the list of returned modes that the pDesc parameter points to. In other words, the method returns both stereo and mono modes.

In general, when you switch from windowed to full-screen mode, a swap chain automatically chooses a display mode that meets (or exceeds) the resolution, color depth, and refresh rate of the swap chain. To exercise more control over the display mode, use GetDisplayModeList1 to poll the set of display modes that are validated against monitor capabilities, or all modes that match the desktop (if the desktop settings are not validated against the monitor).

The following example code shows that you need to call GetDisplayModeList1 twice. First call GetDisplayModeList1 to get the number of modes available, and second call GetDisplayModeList1 to return a description of the modes.

 UINT num = 0;	
             format = ;	
            UINT flags         = ; pOutput->GetDisplayModeList1( format, flags, &num, 0); ...  * pDescs = new [num];	
            pOutput->GetDisplayModeList1( format, flags, &num, pDescs); 

In general, when switching from windowed to full-screen mode, a swap chain automatically chooses a display mode that meets (or exceeds) the resolution, color depth and refresh rate of the swap chain. To exercise more control over the display mode, use this API to poll the set of display modes that are validated against monitor capabilities, or all modes that match the desktop (if the desktop settings are not validated against the monitor).

As shown, this API is designed to be called twice. First to get the number of modes available, and second to return a description of the modes.

 UINT num = 0;
             format = DXGI_FORMAT_R32G32B32A32_FLOAT;
            UINT flags         = DXGI_ENUM_MODES_INTERLACED; pOutput->GetDisplayModeList( format, flags, &num, 0); ...  * pDescs = new [num];
            pOutput->GetDisplayModeList( format, flags, &num, pDescs); 

Direct3D devices require UNORM formats.

FindClosestMatchingMode1 finds the closest matching available display mode to the mode that you specify in pModeToMatch.

If you set the Stereo member in the structure to which pModeToMatch points to specify a stereo mode as input, FindClosestMatchingMode1 considers only stereo modes. FindClosestMatchingMode1 considers only mono modes if Stereo is not set.

FindClosestMatchingMode1 resolves similarly ranked members of display modes (that is, all specified, or all unspecified, and so on) in the following order:

1. ScanlineOrdering
2. Scaling
3. Format
4. Resolution
5. RefreshRate

When FindClosestMatchingMode1 determines the closest value for a particular member, it uses previously matched members to filter the display mode list choices, and ignores other members. For example, when FindClosestMatchingMode1 matches Resolution, it already filtered the display mode list by a certain ScanlineOrdering, Scaling, and Format, while it ignores RefreshRate. This ordering doesn't define the absolute ordering for every usage scenario of FindClosestMatchingMode1, because the application can choose some values initially, which effectively changes the order of resolving members.

FindClosestMatchingMode1 matches members of the display mode one at a time, generally in a specified order.

If a member is unspecified, FindClosestMatchingMode1 gravitates toward the values for the desktop related to this output. If this output is not part of the desktop, FindClosestMatchingMode1 uses the default desktop output to find values. If an application uses a fully unspecified display mode, FindClosestMatchingMode1 typically returns a display mode that matches the desktop settings for this output. Because unspecified members are lower priority than specified members, FindClosestMatchingMode1 resolves unspecified members later than specified members.

GetDisplaySurfaceData1 is similar to IDXGIOutput::GetDisplaySurfaceData except GetDisplaySurfaceData1 takes an and IDXGIOutput::GetDisplaySurfaceData takes an .

GetDisplaySurfaceData1 returns an error if the input resource is not a 2D texture (represented by the interface) with an array size (ArraySize member of the structure) that is equal to the swap chain buffers.

The original IDXGIOutput::GetDisplaySurfaceData and the updated GetDisplaySurfaceData1 behave exactly the same. GetDisplaySurfaceData1 was required because textures with an array size equal to 2 (ArraySize = 2) do not implement .

You can call GetDisplaySurfaceData1 only when an output is in full-screen mode. If GetDisplaySurfaceData1 succeeds, it fills the destination resource.

Use IDXGIOutput::GetDesc to determine the size (width and height) of the output when you want to allocate space for the destination resource. This is true regardless of target monitor rotation. A destination resource created by a graphics component (such as Direct3D 11) must be created with CPU write permission (see D3D11_CPU_ACCESS_WRITE). Other surfaces can be created with CPU read-write permission (D3D11_CPU_ACCESS_READ | D3D11_CPU_ACCESS_WRITE). GetDisplaySurfaceData1 modifies the surface data to fit the destination resource (stretch, shrink, convert format, rotate). GetDisplaySurfaceData1 performs the stretch and shrink with point sampling.

If an application wants to duplicate the entire desktop, it must create a desktop duplication interface on each active output on the desktop. This interface does not provide an explicit way to synchronize the timing of each output image. Instead, the application must use the time stamp of each output, and then determine how to combine the images.

For DuplicateOutput to succeed, you must create pDevice from or a later version of a DXGI factory interface that inherits from .

If the current mode is a stereo mode, the desktop duplication interface provides the image for the left stereo image only.

By default, only four processes can use a interface at the same time within a single session. A process can have only one desktop duplication interface on a single desktop output; however, that process can have a desktop duplication interface for each output that is part of the desktop.

For improved performance, consider using DuplicateOutput1.

See CreateSwapChainForCoreWindow for info on creating a foreground swap chain.

When AcquireNextFrame returns successfully, the calling application can access the desktop image that AcquireNextFrame returns in the variable at ppDesktopResource. If the caller specifies a zero time-out interval in the TimeoutInMilliseconds parameter, AcquireNextFrame verifies whether there is a new desktop image available, returns immediately, and indicates its outcome with the return value. If the caller specifies an INFINITE time-out interval in the TimeoutInMilliseconds parameter, the time-out interval never elapses.

AcquireNextFrame acquires a new desktop frame when the operating system either updates the desktop bitmap image or changes the shape or position of a hardware reference. The new frame that AcquireNextFrame acquires might have only the desktop image updated, only the reference shape or position updated, or both.

After an application creates an interface, it calls GetDesc to retrieve the dimensions of the surface that contains the desktop image. The format of the desktop image is always DXGI_FORMAT_B8G8R8A8_UNORM.

After an application creates an interface, it calls GetDesc to retrieve the dimensions of the surface that contains the desktop image. The format of the desktop image is always DXGI_FORMAT_B8G8R8A8_UNORM.

When AcquireNextFrame returns successfully, the calling application can access the desktop image that AcquireNextFrame returns in the variable at ppDesktopResource. If the caller specifies a zero time-out interval in the TimeoutInMilliseconds parameter, AcquireNextFrame verifies whether there is a new desktop image available, returns immediately, and indicates its outcome with the return value. If the caller specifies an INFINITE time-out interval in the TimeoutInMilliseconds parameter, the time-out interval never elapses.

AcquireNextFrame acquires a new desktop frame when the operating system either updates the desktop bitmap image or changes the shape or position of a hardware reference. The new frame that AcquireNextFrame acquires might have only the desktop image updated, only the reference shape or position updated, or both.

GetFrameDirtyRects stores a size value in the variable at pDirtyRectsBufferSizeRequired. This value specifies the number of bytes that GetFrameDirtyRects needs to store information about dirty regions. You can use this value in the following situations to determine the amount of memory to allocate for future buffers that you pass to pDirtyRectsBuffer:

• GetFrameDirtyRects fails with because the buffer is not big enough.
• GetFrameDirtyRects supplies a buffer that is bigger than necessary. The size value returned at pDirtyRectsBufferSizeRequired informs the caller how much buffer space was actually used compared to how much buffer space the caller allocated and specified in the DirtyRectsBufferSize parameter.

The caller can also use the value returned at pDirtyRectsBufferSizeRequired to determine the number of s returned in the pDirtyRectsBuffer array.

The buffer contains the list of dirty s for the current frame.

GetFrameMoveRects stores a size value in the variable at pMoveRectsBufferSizeRequired. This value specifies the number of bytes that GetFrameMoveRects needs to store information about moved regions. You can use this value in the following situations to determine the amount of memory to allocate for future buffers that you pass to pMoveRectBuffer:

• GetFrameMoveRects fails with because the buffer is not big enough.
• GetFrameMoveRects supplies a buffer that is bigger than necessary. The size value returned at pMoveRectsBufferSizeRequired informs the caller how much buffer space was actually used compared to how much buffer space the caller allocated and specified in the MoveRectsBufferSize parameter.

The caller can also use the value returned at pMoveRectsBufferSizeRequired to determine the number of structures returned.

The buffer contains the list of move RECTs for the current frame.

GetFramePointerShape stores a size value in the variable at pPointerShapeBufferSizeRequired. This value specifies the number of bytes that pPointerShapeBufferSizeRequired needs to store the new reference shape pixel data. You can use the value in the following situations to determine the amount of memory to allocate for future buffers that you pass to pPointerShapeBuffer:

• GetFramePointerShape fails with because the buffer is not big enough.
• GetFramePointerShape supplies a bigger than necessary buffer. The size value returned at pPointerShapeBufferSizeRequired informs the caller how much buffer space was actually used compared to how much buffer space the caller allocated and specified in the PointerShapeBufferSize parameter.

The pPointerShapeInfo parameter describes the new reference shape.

You can successfully call MapDesktopSurface if the DesktopImageInSystemMemory member of the structure is set to TRUE. If DesktopImageInSystemMemory is , MapDesktopSurface returns . Call IDXGIOutputDuplication::GetDesc to retrieve the structure.

The application must release the frame before it acquires the next frame. After the frame is released, the surface that contains the desktop bitmap becomes invalid; you will not be able to use the surface in a DirectX graphics operation.

For performance reasons, we recommend that you release the frame just before you call the IDXGIOutputDuplication::AcquireNextFrame method to acquire the next frame. When the client does not own the frame, the operating system copies all desktop updates to the surface. This can result in wasted GPU cycles if the operating system updates the same region for each frame that occurs. When the client acquires the frame, the client is aware of only the final update to this region; therefore, any overlapping updates during previous frames are wasted. When the client acquires a frame, the client owns the surface; therefore, the operating system can track only the updated regions and cannot copy desktop updates to the surface. Because of this behavior, we recommend that you minimize the time between the call to release the current frame and the call to acquire the next frame.

This structure is used by the Present1 method.

The scroll rectangle and the list of dirty rectangles could overlap. In this situation, the dirty rectangles take priority. Applications can then have pieces of dynamic content on top of a scrolled area. For example, an application could scroll a page and play video at the same time.

The following diagram and coordinates illustrate this example.

Parts of the previous frame and content that the application renders are combined to produce the final frame that the operating system presents on the display screen. Most of the window is scrolled from the previous frame. The application must update the video frame with the new chunk of content that appears due to scrolling.

The dashed rectangle shows the scroll rectangle in the current frame. The scroll rectangle is specified by the pScrollRect member. The arrow shows the scroll offset. The scroll offset is specified by the pScrollOffset member. Filled rectangles show dirty rectangles that the application updated with new content. The filled rectangles are specified by the DirtyRectsCount and pDirtyRects members.

The scroll rectangle and offset are not supported for the DXGI_SWAP_EFFECT_DISCARD or DXGI_SWAP_EFFECT_SEQUENTIAL present option. Dirty rectangles and scroll rectangle are not supported for multisampled swap chains.

The actual implementation of composition and necessary bitblts is different for the bitblt model and the flip model. For more info about these models, see DXGI Flip Model.

For more info about the flip-model swap chain and optimizing presentation, see Enhancing presentation with the flip model, dirty rectangles, and scrolled areas.

This structure is a member of the structure.

The structure operates under the following rules:

• 0/0 is legal and will be interpreted as 0/1.
• 0/anything is interpreted as zero.
• If you are representing a whole number, the denominator should be 1.

Subresource surface objects implement the interface, which inherits from and indirectly . Therefore, the GDI-interoperable methods of work if the original resource interface object was created with the GDI-interoperable flag (D3D11_RESOURCE_MISC_GDI_COMPATIBLE).

CreateSubresourceSurface creates a subresource surface that is based on the resource interface on which CreateSubresourceSurface is called. For example, if the original resource interface object is a 2D texture, the created subresource surface is also a 2D texture.

You can use CreateSubresourceSurface to create parts of a stereo resource so you can use Direct2D on either the left or right part of the stereo resource.

CreateSharedHandle only returns the NT handle when you created the resource as shared and specified that it uses NT handles (that is, you set the D3D11_RESOURCE_MISC_SHARED_NTHANDLE and D3D11_RESOURCE_MISC_SHARED_KEYEDMUTEX flags). If you created the resource as shared and specified that it uses NT handles, you must use CreateSharedHandle to get a handle for sharing. In this situation, you can't use the IDXGIResource::GetSharedHandle method because it will fail.

You can pass the handle that CreateSharedHandle returns in a call to the ID3D11Device1::OpenSharedResource1 method to give a device access to a shared resource that you created on a different device.

Because the handle that CreateSharedHandle returns is an NT handle, you can use the handle with CloseHandle, DuplicateHandle, and so on. You can call CreateSharedHandle only once for a shared resource; later calls fail. If you need more handles to the same shared resource, call DuplicateHandle. When you no longer need the shared resource handle, call CloseHandle to close the handle, in order to avoid memory leaks.

If you pass a name for the resource to lpName when you call CreateSharedHandle to share the resource, you can subsequently pass this name in a call to the ID3D11Device1::OpenSharedResourceByName method to give another device access to the shared resource. If you use a named resource, a malicious user can use this named resource before you do and prevent your app from starting. To prevent this situation, create a randomly named resource and store the name so that it can only be obtained by an authorized user. Alternatively, you can use a file for this purpose. To limit your app to one instance per user, create a locked file in the user's profile directory.

If you created the resource as shared and did not specify that it uses NT handles, you cannot use CreateSharedHandle to get a handle for sharing because CreateSharedHandle will fail.

This structure is a member of the structure.

The default sampler mode, with no anti-aliasing, has a count of 1 and a quality level of 0.

If multi-sample antialiasing is being used, all bound render targets and depth buffers must have the same sample counts and quality levels.

?

Use IDXGISurface::Map to access a surface from the CPU. To release a mapped surface (and allow GPU access) call IDXGISurface::Unmap.

Use IDXGISurface::Map to access a surface from the CPU. To release a mapped surface (and allow GPU access) call IDXGISurface::Unmap.

This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).

After you use the GetDC method to retrieve a DC, you can render to the DXGI surface by using GDI. The GetDC method readies the surface for GDI rendering and allows inter-operation between DXGI and GDI technologies.

Keep the following in mind when using this method:

• You must create the surface by using the D3D11_RESOURCE_MISC_GDI_COMPATIBLE flag for a surface or by using the DXGI_SWAP_CHAIN_FLAG_GDI_COMPATIBLE flag for swap chains, otherwise this method fails.
• You must release the device and call the IDXGISurface1::ReleaseDC method before you issue any new Direct3D commands.
• This method fails if an outstanding DC has already been created by this method.
• The format for the surface or swap chain must be DXGI_FORMAT_B8G8R8A8_UNORM_SRGB or DXGI_FORMAT_B8G8R8A8_UNORM.
• On GetDC, the render target in the output merger of the Direct3D pipeline is unbound from the surface. You must call the ID3D11DeviceContext::OMSetRenderTargets method on the device prior to Direct3D rendering after GDI rendering.
• Prior to resizing buffers you must release all outstanding DCs.

You can also call GetDC on the back buffer at index 0 of a swap chain by obtaining an from the swap chain. The following code illustrates the process.

 * g_pSwapChain = null;
            * g_pSurface1 = null;
            ...
            //Setup the device and and swapchain
            g_pSwapChain->GetBuffer(0, __uuidof(), (void**) &g_pSurface1);
            g_pSurface1->GetDC( , &g_hDC );
            ...      
            //Draw on the DC using GDI
            ...
            //When finish drawing release the DC
            g_pSurface1->ReleaseDC( null ); 

This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).

Use the ReleaseDC method to release the DC and indicate that your application finished all GDI rendering to this surface. You must call the ReleaseDC method before you can use Direct3D to perform additional rendering.

Prior to resizing buffers you must release all outstanding DCs.

For subresource surface objects that the IDXGIResource1::CreateSubresourceSurface method creates, GetResource simply returns the values that were used to create the subresource surface.

Current objects that implement are either resources or views. GetResource for these objects returns ?this? or the resource that supports the view respectively. In this situation, the subresource index is 0.

You cannot use GetFrameStatistics for swap chains that both use the bit-block transfer (bitblt) presentation model and draw in windowed mode.

You can only use GetFrameStatistics for swap chains that either use the flip presentation model or draw in full-screen mode. You set the value in the SwapEffect member of the structure to specify that the swap chain uses the flip presentation model.

Starting with Direct3D 11.1, we recommend to instead use because you can then use dirty rectangles and the scroll rectangle in the swap chain presentation and as such use less memory bandwidth and as a result less system power. For more info about using dirty rectangles and the scroll rectangle in swap chain presentation, see Using dirty rectangles and the scroll rectangle in swap chain presentation.

For the best performance when flipping swap-chain buffers in a full-screen application, see Full-Screen Application Performance Hints.

Because calling Present might cause the render thread to wait on the message-pump thread, be careful when calling this method in an application that uses multiple threads. For more details, see Multithreading Considerations.

?

For flip presentation model swap chains that you create with the value set, a successful presentation unbinds back buffer 0 from the graphics pipeline, except for when you pass the flag in the Flags parameter.

For info about how data values change when you present content to the screen, see Converting data for the color space.

If the method succeeds, the output interface will be filled and its reference count incremented. When you are finished with it, be sure to release the interface to avoid a memory leak.

The output is also owned by the adapter on which the swap chain's device was created.

You cannot call GetContainingOutput on a swap chain that you created with IDXGIFactory2::CreateSwapChainForComposition.

For info about presentation statistics for a frame, see .

Starting with Direct3D 11.1, consider using IDXGISwapChain1::Present1 because you can then use dirty rectangles and the scroll rectangle in the swap chain presentation and as such use less memory bandwidth and as a result less system power. For more info about using dirty rectangles and the scroll rectangle in swap chain presentation, see Using dirty rectangles and the scroll rectangle in swap chain presentation.

For the best performance when flipping swap-chain buffers in a full-screen application, see Full-Screen Application Performance Hints.

Because calling Present might cause the render thread to wait on the message-pump thread, be careful when calling this method in an application that uses multiple threads. For more details, see Multithreading Considerations.

?

For flip presentation model swap chains that you create with the DXGI_SWAP_EFFECT_FLIP_SEQUENTIAL value set, a successful presentation unbinds back buffer 0 from the graphics pipeline, except for when you pass the DXGI_PRESENT_DO_NOT_SEQUENCE flag in the Flags parameter.

For info about how data values change when you present content to the screen, see Converting data for the color space.

DXGI may change the display state of a swap chain in response to end user or system requests.

We recommend that you create a windowed swap chain and allow the end user to change the swap chain to full screen through SetFullscreenState; that is, do not set the Windowed member of to to force the swap chain to be full screen. However, if you create the swap chain as full screen, also provide the end user with a list of supported display modes because a swap chain that is created with an unsupported display mode might cause the display to go black and prevent the end user from seeing anything. Also, we recommend that you have a time-out confirmation screen or other fallback mechanism when you allow the end user to change display modes.

When the swap chain is in full-screen mode, a reference to the target output will be returned and its reference count will be incremented.

You can't resize a swap chain unless you release all outstanding references to its back buffers. You must release all of its direct and indirect references on the back buffers in order for ResizeBuffers to succeed.

Direct references are held by the application after it calls AddRef on a resource.

Indirect references are held by views to a resource, binding a view of the resource to a device context, a command list that used the resource, a command list that used a view to that resource, a command list that executed another command list that used the resource, and so on.

Before you call ResizeBuffers, ensure that the application releases all references (by calling the appropriate number of Release invocations) on the resources, any views to the resource, and any command lists that use either the resources or views, and ensure that neither the resource nor a view is still bound to a device context. You can use ID3D11DeviceContext::ClearState to ensure that all references are released. If a view is bound to a deferred context, you must discard the partially built command list as well (by calling ID3D11DeviceContext::ClearState, then ID3D11DeviceContext::FinishCommandList, then Release on the command list). After you call ResizeBuffers, you can re-query interfaces via IDXGISwapChain::GetBuffer.

For swap chains that you created with DXGI_SWAP_CHAIN_FLAG_GDI_COMPATIBLE, before you call ResizeBuffers, also call IDXGISurface1::ReleaseDC on the swap chain's back-buffer surface to ensure that you have no outstanding GDI device contexts (DCs) open.

We recommend that you call ResizeBuffers when a client window is resized (that is, when an application receives a WM_SIZE message).

The only difference between IDXGISwapChain::ResizeBuffers in Windows?8 versus Windows?7 is with flip presentation model swap chains that you create with the DXGI_SWAP_EFFECT_FLIP_SEQUENTIAL or DXGI_SWAP_EFFECT_FLIP_DISCARD value set. In Windows?8, you must call ResizeBuffers to realize a transition between full-screen mode and windowed mode; otherwise, your next call to the IDXGISwapChain::Present method fails.

ResizeTarget resizes the target window when the swap chain is in windowed mode, and changes the display mode on the target output when the swap chain is in full-screen mode. Therefore, apps can call ResizeTarget to resize the target window (rather than a Microsoft Win32API such as SetWindowPos) without knowledge of the swap chain display mode.

If a Windows Store app calls ResizeTarget, it fails with .

You cannot call ResizeTarget on a swap chain that you created with IDXGIFactory2::CreateSwapChainForComposition.

Apps must still call IDXGISwapChain::ResizeBuffers after they call ResizeTarget because only ResizeBuffers can change the back buffers. But, if those apps have implemented window resize processing to call ResizeBuffers, they don't need to explicitly call ResizeBuffers after they call ResizeTarget because the window resize processing will achieve what the app requires.

If the method succeeds, the output interface will be filled and its reference count incremented. When you are finished with it, be sure to release the interface to avoid a memory leak.

The output is also owned by the adapter on which the swap chain's device was created.

You cannot call GetContainingOutput on a swap chain that you created with IDXGIFactory2::CreateSwapChainForComposition.

You cannot use GetFrameStatistics for swap chains that both use the bit-block transfer (bitblt) presentation model and draw in windowed mode.

You can only use GetFrameStatistics for swap chains that either use the flip presentation model or draw in full-screen mode. You set the DXGI_SWAP_EFFECT_FLIP_SEQUENTIAL value in the SwapEffect member of the structure to specify that the swap chain uses the flip presentation model.

For info about presentation statistics for a frame, see .

The semantics of GetFullscreenDesc are identical to that of the IDXGISwapchain::GetDesc method for -based swap chains.

Applications call the IDXGIFactory2::CreateSwapChainForHwnd method to create a swap chain that is associated with an .

Temporary mono is a feature where a stereo swap chain can be presented using only the content in the left buffer. To present using the left buffer as a mono buffer, an application calls the IDXGISwapChain1::Present1 method with the DXGI_PRESENT_STEREO_TEMPORARY_MONO flag. All windowed swap chains support temporary mono. However, full-screen swap chains optionally support temporary mono because not all hardware supports temporary mono on full-screen swap chains efficiently.

If the method succeeds, the runtime fills the buffer at ppRestrictToOutput with a reference to the restrict-to output interface. This restrict-to output interface has its reference count incremented. When you are finished with it, be sure to release the interface to avoid a memory leak.

The output is also owned by the adapter on which the swap chain's device was created.

The semantics of GetFullscreenDesc are identical to that of the IDXGISwapchain::GetDesc method for -based swap chains.

Applications call the IDXGIFactory2::CreateSwapChainForHwnd method to create a swap chain that is associated with an .

Applications call the IDXGIFactory2::CreateSwapChainForCoreWindow method to create a swap chain that is associated with an CoreWindow object.

An app can use Present1 to optimize presentation by specifying scroll and dirty rectangles. When the runtime has information about these rectangles, the runtime can then perform necessary bitblts during presentation more efficiently and pass this metadata to the Desktop Window Manager (DWM). The DWM can then use the metadata to optimize presentation and pass the metadata to indirect displays and terminal servers to optimize traffic over the wire. An app must confine its modifications to only the dirty regions that it passes to Present1, as well as modify the entire dirty region to avoid undefined resource contents from being exposed.

For flip presentation model swap chains that you create with the DXGI_SWAP_EFFECT_FLIP_SEQUENTIAL value set, a successful presentation results in an unbind of back buffer 0 from the graphics pipeline, except for when you pass the DXGI_PRESENT_DO_NOT_SEQUENCE flag in the Flags parameter.

For info about how data values change when you present content to the screen, see Converting data for the color space.

For info about calling Present1 when your app uses multiple threads, see Multithread Considerations and Multithreading and DXGI.

Temporary mono is a feature where a stereo swap chain can be presented using only the content in the left buffer. To present using the left buffer as a mono buffer, an application calls the IDXGISwapChain1::Present1 method with the DXGI_PRESENT_STEREO_TEMPORARY_MONO flag. All windowed swap chains support temporary mono. However, full-screen swap chains optionally support temporary mono because not all hardware supports temporary mono on full-screen swap chains efficiently.

If the method succeeds, the runtime fills the buffer at ppRestrictToOutput with a reference to the restrict-to output interface. This restrict-to output interface has its reference count incremented. When you are finished with it, be sure to release the interface to avoid a memory leak.

The output is also owned by the adapter on which the swap chain's device was created.

The background color affects only swap chains that you create with DXGI_SCALING_NONE in windowed mode. You pass this value in a call to IDXGIFactory2::CreateSwapChainForHwnd, IDXGIFactory2::CreateSwapChainForCoreWindow, or IDXGIFactory2::CreateSwapChainForComposition. Typically, the background color is not visible unless the swap-chain contents are smaller than the destination window.

When you set the background color, it is not immediately realized. It takes effect in conjunction with your next call to the IDXGISwapChain1::Present1 method. The DXGI_PRESENT flags that you pass to IDXGISwapChain1::Present1 can help achieve the effect that you require. For example, if you call SetBackgroundColor and then call IDXGISwapChain1::Present1 with the Flags parameter set to DXGI_PRESENT_DO_NOT_SEQUENCE, you change only the background color without changing the displayed contents of the swap chain.

When you call the IDXGISwapChain1::Present1 method to display contents of the swap chain, IDXGISwapChain1::Present1 uses the value that is specified in the AlphaMode member of the structure to determine how to handle the a member of the DXGI_RGBA structure, the alpha value of the background color, that achieves window transparency. For example, if AlphaMode is DXGI_ALPHA_MODE_IGNORE, IDXGISwapChain1::Present1 ignores the a member of DXGI_RGBA.

You can only use SetRotation to rotate the back buffers for flip-model swap chains that you present in windowed mode.

SetRotation isn't supported for rotating the back buffers for flip-model swap chains that you present in full-screen mode. In this situation, SetRotation doesn't fail, but you must ensure that you specify no rotation (DXGI_MODE_ROTATION_IDENTITY) for the swap chain. Otherwise, when you call IDXGISwapChain1::Present1 or IDXGISwapChain::Present to present a frame, the presentation fails.

This method is only valid for use on swap chains created with DXGI_SWAP_CHAIN_FLAG_FRAME_LATENCY_WAITABLE_OBJECT. Otherwise, the result will be .

The enumerated type is used by the Flags member of the or structure to identify the type of DXGI adapter.

For more information about alpha mode, see .

This enum is used within DXGI in the CheckColorSpaceSupport, SetColorSpace1 and CheckOverlayColorSpaceSupport methods. It is also referenced in D3D11 video methods such as ID3D11VideoContext1::VideoProcessorSetOutputColorSpace1, and D2D methods such as ID2D1DeviceContext2::CreateImageSourceFromDxgi.

The following color parameters are defined:

You call the IDXGIAdapter2::GetDesc2 method to retrieve the granularity level at which the GPU can be preempted from performing its current compute task. The operating system specifies the compute granularity level in the ComputePreemptionGranularity member of the structure.

Selecting the CENTERED or STRETCHED modes can result in a mode change even if you specify the native resolution of the display in the . If you know the native resolution of the display and want to make sure that you do not initiate a mode change when transitioning a swap chain to full screen (either via ALT+ENTER or IDXGISwapChain::SetFullscreenState), you should use UNSPECIFIED.

This enum is used by the and structures.

This enum is used by the and structures.

The value for each value is determined from this macro that is defined in DXGItype.h:

 #define _FACDXGI    0x87a
            #define MAKE_DXGI_STATUS(code)  MAKE_HRESULT(0, _FACDXGI, code)
            

For example, DXGI_STATUS_OCCLUDED is defined as 0x087A0001:

 #define DXGI_STATUS_OCCLUDED                    MAKE_DXGI_STATUS(1)
            

This enum is used by the CheckFeatureSupport method.

This enum is used by the structure.

You call the IDXGIAdapter2::GetDesc2 method to retrieve the granularity level at which the GPU can be preempted from performing its current graphics rendering task. The operating system specifies the graphics granularity level in the GraphicsPreemptionGranularity member of the structure.

The following figure shows granularity of graphics rendering tasks.

This enum is used by the SetHDRMetaData method.

Use this enumeration when you call IDXGIInfoQueue::GetMessage to retrieve a message and when you call IDXGIInfoQueue::AddMessage to add a message. When you create an info queue filter, you can use these values to allow or deny any categories of messages to pass through the storage and retrieval filters.

Use this enumeration when you call IDXGIInfoQueue::GetMessage to retrieve a message and when you call IDXGIInfoQueue::AddMessage to add a message. Also, use this enumeration with IDXGIInfoQueue::AddApplicationMessage.

This enum is used by QueryVideoMemoryInfo and SetVideoMemoryReservation.

Refer to the remarks for .

Priority determines how likely the operating system is to discard an offered resource. Resources offered with lower priority are discarded first.

This enum is used by QueryResourceResidency.

The eviction priority is a memory-management variable that is used by DXGI for determining how to populate overcommitted memory.

You can set priority levels other than the defined values when appropriate. For example, you can set a resource with a priority level of 0x78000001 to indicate that the resource is slightly above normal.

The DXGI_SCALING_NONE value is supported only for flip presentation model swap chains that you create with the DXGI_SWAP_EFFECT_FLIP_SEQUENTIAL value. You pass these values in a call to IDXGIFactory2::CreateSwapChainForHwnd, IDXGIFactory2::CreateSwapChainForCoreWindow, or IDXGIFactory2::CreateSwapChainForComposition.

DXGI_SCALING_ASPECT_RATIO_STRETCH will prefer to use a horizontal fill, otherwise it will use a vertical fill, using the following logic.

Note that outputWidth and outputHeight are the pixel sizes of the presentation target size. In the case of CoreWindow, this requires converting the logicalWidth and logicalHeight values from DIPS to pixels using the window's DPI property.

This enumeration is used by the and structures.

To use multisampling with DXGI_SWAP_EFFECT_SEQUENTIAL or DXGI_SWAP_EFFECT_FLIP_SEQUENTIAL, you must perform the multisampling in a separate render target. For example, create a multisampled texture by calling ID3D11Device::CreateTexture2D with a filled structure (BindFlags member set to D3D11_BIND_RENDER_TARGET and SampleDesc member with multisampling parameters). Next call ID3D11Device::CreateRenderTargetView to create a render-target view for the texture, and render your scene into the texture. Finally call ID3D11DeviceContext::ResolveSubresource to resolve the multisampled texture into your non-multisampled swap chain.

The primary difference between presentation models is how back-buffer contents get to the Desktop Window Manager (DWM) for composition. In the bitblt model, which is used with the DXGI_SWAP_EFFECT_DISCARD and DXGI_SWAP_EFFECT_SEQUENTIAL values, contents of the back buffer get copied into the redirection surface on each call to IDXGISwapChain1::Present1. In the flip model, which is used with the DXGI_SWAP_EFFECT_FLIP_SEQUENTIAL value, all back buffers are shared with the DWM. Therefore, the DWM can compose straight from those back buffers without any additional copy operations. In general, the flip model is the more efficient model. The flip model also provides more features, such as enhanced present statistics.

When you call IDXGISwapChain1::Present1 on a flip model swap chain (DXGI_SWAP_EFFECT_FLIP_SEQUENTIAL) with 0 specified in the SyncInterval parameter, IDXGISwapChain1::Present1's behavior is the same as the behavior of Direct3D 9Ex's IDirect3DDevice9Ex::PresentEx with D3DSWAPEFFECT_FLIPEX and D3DPRESENT_FORCEIMMEDIATE. That is, the runtime not only presents the next frame instead of any previously queued frames, it also terminates any remaining time left on the previously queued frames.

Regardless of whether the flip model is more efficient, an application still might choose the bitblt model because the bitblt model is the only way to mix GDI and DirectX presentation. In the flip model, the application must create the swap chain with DXGI_SWAP_CHAIN_FLAG_GDI_COMPATIBLE, and then must use GetDC on the back buffer explicitly. After the first successful call to IDXGISwapChain1::Present1 on a flip-model swap chain, GDI no longer works with the that is associated with that swap chain, even after the destruction of the swap chain. This restriction even extends to methods like ScrollWindowEx.

For more info about the flip-model swap chain and optimizing presentation, see Enhancing presentation with the flip model, dirty rectangles, and scrolled areas.

Use a DXGI 1.1 factory to generate objects that enumerate adapters, create swap chains, and associate a window with the alt+enter key sequence for toggling to and from the full-screen display mode.

If the CreateDXGIFactory1 function succeeds, the reference count on the interface is incremented. To avoid a memory leak, when you finish using the interface, call the IDXGIFactory1::Release method to release the interface.

This entry point is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).

• Adapter with the output on which the desktop primary is displayed. This adapter corresponds with an index of zero.
• Adapters with outputs.
• Adapters without outputs.

This function accepts a flag indicating whether DXGIDebug.dll is loaded. The function otherwise behaves identically to CreateDXGIFactory1.

This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).

Use the GetDesc1 method to get a DXGI 1.1 description of an adapter. To get a DXGI 1.0 description, use the method.

This method is not supported by DXGI 1.0, which shipped in Windows?Vista and Windows Server?2008. DXGI 1.1 support is required, which is available on Windows?7, Windows Server?2008?R2, and as an update to Windows?Vista with Service Pack?2 (SP2) (KB 971644) and Windows Server?2008 (KB 971512).

Use the GetDesc1 method to get a DXGI 1.1 description of an adapter. To get a DXGI 1.0 description, use the method.