IDXGIOutput1::DuplicateOutput Method

Creates a desktop duplication interface from the IDXGIOutput1 interface that represents an adapter output.

Syntax

public:
HRESULT DuplicateOutput(
         IUnknown *pDevice,
         IDXGIOutputDuplication **ppOutputDuplication
)

Parameters

pDevice
Type: IUnknown *

[in] A pointer to the Direct3D device interface that you can use to process the desktop image. This device must be created from the adapter to which the output is connected.

ppOutputDuplication
Type: IDXGIOutputDuplication **

[out] A pointer to a variable that receives the new IDXGIOutputDuplication interface.

Return value

Type: HRESULT

S_OK if DuplicateOutput successfully created the desktop duplication interface.
E_INVALIDARG for one of the following reasons:
- The specified device (pDevice) is invalid, was not created on the correct adapter, or was not created from IDXGIFactory1 (or a later version of a DXGI factory interface that inherits from IDXGIFactory1).
- The calling application is already duplicating this desktop output.
  For more information about this error, see Remarks.
E_ACCESSDENIED if the application does not have access privilege to the current desktop image. For example, only an application that runs at LOCAL_SYSTEM can access the secure desktop.
[Desktop:] DXGI_ERROR_UNSUPPORTED if the created IDXGIOutputDuplication interface does not support the current desktop mode or scenario. For example, 8bpp and non-DWM desktop modes are not supported.
DXGI_ERROR_NOT_CURRENTLY_AVAILABLE if DXGI reached the limit on the maximum number of concurrent duplication applications (default of four). Therefore, the calling application cannot create any desktop duplication interfaces until the other applications close.
DXGI_ERROR_SESSION_DISCONNECTED if DuplicateOutput failed because the session is currently disconnected.
Other error codes are described in the DXGI_ERROR topic.

Remarks

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 IDXGIFactory1 or a later version of a DXGI factory interface that inherits from IDXGIFactory1.

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 IDXGIOutputDuplication 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.

If DuplicateOutput fails with DXGI_ERROR_UNSUPPORTED, the application can wait for system notification of desktop switches and mode changes and then call DuplicateOutput again after such a notification occurs. For more information, see information in desktop switch (EVENT_SYSTEM_DESKTOPSWITCH) and mode change notification (WM_DISPLAYCHANGE).

Requirements

Header: Declared in dxgi1_2.h.