////////////////////////////////////////////////////////////////////////////////
// License
////////////////////////////////////////////////////////////////////////////////

Use of this tool implies agreement with the `NVIDIA Driver License
Agreement`.  See the enclosed eula.txt document for the license text.

////////////////////////////////////////////////////////////////////////////////
// NVIDIA configureDdisplay.exe Overview
////////////////////////////////////////////////////////////////////////////////

The command line tool configureDdisplay.exe is used to remove displays
from the Windows desktop compositor, and to return displays to the Windows
desktop compositor. Displays removed from the desktop can be used by
other compositors.

The Windows OS has support for removing a display from the desktop so
that the display can be used by a compositor other than the desktop
compositor. Some related information can be found here:
https://learn.microsoft.com/en-us/windows-hardware/drivers/display/specialized-monitors
including a list of operating system editions that support this feature:
Windows Enterprise, and Windows Pro for Workstation.

Use of a display that is removed from the desktop compositor is
sometimes referred to as "direct display" or "direct to display" or
"dedicated display", and abbreviated "ddisplay". This tool is named
after the abbreviation "ddisplay".

////////////////////////////////////////////////////////////////////////////////
// Usage
////////////////////////////////////////////////////////////////////////////////

'configureDdisplay.exe' must be run with UAC elevation to make changes
to system state. Querying system state does not require UAC elevation.

Run 'configureDdisplay.exe --help' for a list of all supported options.

The configureDdisplay.exe command line tool can be used to perform the
following actions:

- The `status` command prints system state to stdout.

- The `identify` command displays system state on all accessible
  displays.
  
- The `remove-from-desktop` command removes a display from the desktop
  and instructs the driver service to manage the display.

- The `return-to-desktop` command returns a display to the desktop.

////////////////////////////////////////////////////////////////////////////////
// Using a removed-from-desktop display
////////////////////////////////////////////////////////////////////////////////

After a display has been removed from the desktop, the Windows desktop
can no longer be extended or cloned to the display. The display can be
acquired through one or more of the following APIs:

- A VK_KHR_display style VkSwapchainKHR: both managed and unmanaged
  displays, used by Vulkan applications.

- The NVAPI function NvAPI_DISP_AcquireDedicatedDisplay: only managed
  displays, used by D3D applications.

- The Windows API defined in the namespace Windows.Devices.Display.Core:
  only unmanaged displays.

For additional information, see the output of the command
`configureDdisplay.exe remove-from-desktop --help`.

////////////////////////////////////////////////////////////////////////////////
// Managed displays
////////////////////////////////////////////////////////////////////////////////

Managed displays enable a workflow where displays are first configured,
then later one or more applications use that exact display
configuration. This workflow can be valuable for environments including:
CAVE, power walls (such as found in retail shops and at airports), and
location based entertainment (such as amusement park rides).

An example workflow is:

- UserA configures the displays of a power wall into an NVIDIA Mosaic
(https://www.nvidia.com/en-us/design-visualization/solutions/nvidia-mosaic-technology/)
virtual display, synchronizes the displays with an external sync signal
using NVIDIA Quadro Sync
(https://www.nvidia.com/en-us/design-visualization/solutions/quadro-sync/),
and performs display calibration.

- Later, userB runs an application that uses that exact display
  configuration.

- Later, userB or userC runs the same or a different application that
uses that exact display configuration.

- These applications do not need to understand how to create and
  calibrate the display configuration. They leverage configuration and
  calibaration that was performed in the first step.

The NVIDIA display driver includes a service that "manages" displays.
Unmanaged displays are not "managed" by the service. For additional
information about interacting with managed and unmanaged displays, see
output of the command
`configureDdisplay.exe remove-from-desktop --help`.
