Edit

IDXGIOutputDuplication interface (dxgi1_2.h)

  • Article

The IDXGIOutputDuplication interface accesses and manipulates the duplicated desktop image.

Inheritance

The IDXGIOutputDuplication interface inherits from IDXGIObject. IDXGIOutputDuplication also has these types of members:

Methods

The IDXGIOutputDuplication interface has these methods.

 
IDXGIOutputDuplication::AcquireNextFrame

Indicates that the application is ready to process the next desktop image.
IDXGIOutputDuplication::GetDesc

Retrieves a description of a duplicated output. This description specifies the dimensions of the surface that contains the desktop image.
IDXGIOutputDuplication::GetFrameDirtyRects

Gets information about dirty rectangles for the current desktop frame.
IDXGIOutputDuplication::GetFrameMoveRects

Gets information about the moved rectangles for the current desktop frame.
IDXGIOutputDuplication::GetFramePointerShape

Gets information about the new pointer shape for the current desktop frame.
IDXGIOutputDuplication::MapDesktopSurface

Provides the CPU with efficient access to a desktop image if that desktop image is already in system memory.
IDXGIOutputDuplication::ReleaseFrame

Indicates that the application finished processing the frame.
IDXGIOutputDuplication::UnMapDesktopSurface

Invalidates the pointer to the desktop image that was retrieved by using IDXGIOutputDuplication::MapDesktopSurface.

Remarks

A collaboration application can use IDXGIOutputDuplication to access the desktop image. IDXGIOutputDuplication is supported in Desktop Window Manager (DWM) on non-8bpp DirectX full-screen modes and non-8bpp OpenGL full-screen modes. 16-bit or 32-bit GDI non-DWM desktop modes are not supported.

An application can use IDXGIOutputDuplication on a separate thread to receive the desktop images and to feed them into their specific image-processing pipeline. The application uses IDXGIOutputDuplication to perform the following operations:

  1. Acquire the next desktop image.
  2. Retrieve the information that describes the image.
  3. Perform an operation on the image. This operation can be as simple as copying the image to a staging buffer so that the application can read the pixel data on the image. The application reads the pixel data after the application calls IDXGISurface::Map. Alternatively, this operation can be more complex. For example, the application can run some pixel shaders on the updated regions of the image to encode those regions for transmission to a client.
  4. After the application finishes processing each desktop image, it releases the image, loops to step 1, and repeats the steps. The application repeats these steps until it is finished processing desktop images.
The following components of the operating system can generate the desktop image:
  • The DWM by composing the desktop image
  • A full-screen DirectX or OpenGL application
  • An application by switching to a separate desktop, for example, the secure desktop that is used to display the login screen
All current IDXGIOutputDuplication interfaces become invalid when the operating system switches to a different component that produces the desktop image or when a mode change occurs. In these situations, the application must destroy its current IDXGIOutputDuplication interface and create a new IDXGIOutputDuplication interface.

Examples of situations in which IDXGIOutputDuplication becomes invalid are:

  • Desktop switch
  • Mode change
  • Switch from DWM on, DWM off, or other full-screen application
In these situations, the application must release the IDXGIOutputDuplication interface and must create a new IDXGIOutputDuplication interface for the new content. If the application does not have the appropriate privilege to the new desktop image, its call to the IDXGIOutput1::DuplicateOutput method fails.

While the application processes each desktop image, the operating system accumulates all the desktop image updates into a single update. For more information about desktop updates, see Updating the desktop image data.

The desktop image is always in the DXGI_FORMAT_B8G8R8A8_UNORM format.

The IDXGIOutputDuplication interface does not exist for Windows Store apps.

Requirements

Requirement Value
Minimum supported client Windows 8 [desktop apps only]
Minimum supported server Windows Server 2012 [desktop apps only]
Target Platform Windows
Header dxgi1_2.h

See also

DXGI Interfaces

IDXGIObject