Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update setting-the-default-dpi-awareness-for-a-process.md #1912

Merged
merged 1 commit into from
Sep 26, 2024
Merged

Update setting-the-default-dpi-awareness-for-a-process.md #1912

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Update setting-the-default-dpi-awareness-for-a-process.md 
fix links
  • Loading branch information
@DJm00n
DJm00n authored Sep 11, 2024
commit 68bbb38ec71c06aa8e89d292da2ca0f2578a0353
22 changes: 8 additions & 14 deletions desktop-src/hidpi/setting-the-default-dpi-awareness-for-a-process.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ mtps_version: v=VS.85

# Setting the default DPI awareness for a process

Desktop applications on Windows can run in different DPI awareness modes. These modes enable different DPI scaling behavior and can use different coordinate spaces. For more information on DPI awareness, see [High DPI Desktop Application Development on Windows.](https://msdn.microsoft.com/library/mt843498\(v=vs.85\)) It is important that you explicitly set the default DPI awareness mode of your process so as to avoid unexpected behavior.
Desktop applications on Windows can run in different DPI awareness modes. These modes enable different DPI scaling behavior and can use different coordinate spaces. For more information on DPI awareness, see [High DPI Desktop Application Development on Windows](/windows/win32/hidpi/high-dpi-desktop-application-development-on-windows). It is important that you explicitly set the default DPI awareness mode of your process so as to avoid unexpected behavior.

There are two main methods to specify the default DPI awareness of a process:

Expand All @@ -29,9 +29,9 @@ There are two manifest settings that enable you to specify the process default D
The table below shows how to specify different process-default DPI awareness modes using the two manifest settings:


| Process default DPI awareness mode | <dpiAware> setting | <dpiAwareness> setting (Windows 10, version 1607 and later) |
| Process default DPI awareness mode | &lt;dpiAware&gt; setting | &lt;dpiAwareness&gt; setting<br/>(Windows 10, version 1607 and later) |
|------------------------------------|--------------------|--------------------------------------------------------------|
| unaware | <p>N/A (no dpiAware setting in manifest)</p><p>or</p><p>&lt;dpiAware&gt;false&lt;/dpiAware&gt;</p> | &lt;dpiAwareness&gt;unaware&lt;/dpiAwareness&gt; |
| unaware | N/A (no dpiAware setting in manifest)<br/>or<br/>&lt;dpiAware&gt;false&lt;/dpiAware&gt; | &lt;dpiAwareness&gt;unaware&lt;/dpiAwareness&gt; |
| System aware | &lt;dpiAware&gt;true&lt;/dpiAware&gt; | &lt;dpiAwareness&gt;system&lt;/dpiAwareness&gt; |
| Per Monitor | &lt;dpiAware&gt;true/pm&lt;dpiAware&gt; | &lt;dpiAwareness&gt;PerMonitor&lt;/dpiAwareness&gt; |
| Per Monitor V2 | Not supported | &lt;dpiAwareness&gt;PerMonitorV2&lt;/dpiAwareness&gt; |
Expand All @@ -57,20 +57,14 @@ The sample below shows both the \<dpiAwareness\> and the \<dpiAware\> settings b

Although it is not recommended, it is possible to set the default DPI awareness programmatically. Once a window (an HWND) has been created in your process, changing the DPI awareness mode is no longer supported. If you are setting the process-default DPI awareness mode programmatically, you must call the corresponding API before any HWNDs have been created.

There are multiple APIs that let you specify the default DPI awareness for your process. The current recommended API is [**SetProcessDpiAwarenessContext**](https://msdn.microsoft.com/library/mt807676\(v=vs.85\)), as older APIs offer less functionality.



There are multiple APIs that let you specify the default DPI awareness for your process. The current recommended API is [**SetProcessDpiAwarenessContext**](/windows/win32/api/winuser/nf-winuser-setprocessdpiawarenesscontext), as older APIs offer less functionality.

| API | Minimum version of Windows | DPI Unaware | System DPI Aware | Per Monitor DPI Aware |
|-----|----------------------------|-------------|------------------|-----------------------|
| <a href="/windows/win32/api/winuser/nf-winuser-setprocessdpiaware">SetProcessDPIAware</a> | Windows Vista | N/A | SetProcessDPIAware() | N/A |
| <a href="/windows/win32/api/shellscalingapi/nf-shellscalingapi-setprocessdpiawareness"><strong>SetProcessDpiAwareness</strong></a> | Windows 8.1 | SetProcessDpiAwareness(PROCESS_DPI_UNAWARE) | SetProcessDpiAwareness(PROCESS_SYSTEM_DPI_AWARE) | SetProcessDpiAwareness(PROCESS_PER_MONITOR_DPI_AWARE) |
| <a href="/windows/win32/api/winuser/nf-winuser-setprocessdpiawarenesscontext"><strong>SetProcessDpiAwarenessContext</strong></a> | Windows 10, version 1607 | SetProcessDpiAwarenessContext(DPI_AWARENESS_CONTEXT_UNAWARE) | SetProcessDpiAwarenessContext(DPI_AWARENESS_CONTEXT_SYSTEM_AWARE) | <p>SetProcessDpiAwarenessContext(DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE)</p><p>SetProcessDpiAwarenessContext(DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2)</p> |



| [SetProcessDPIAware](/windows/win32/api/winuser/nf-winuser-setprocessdpiaware) | Windows Vista | N/A | SetProcessDPIAware() | N/A |
| [SetProcessDpiAwareness](/windows/win32/api/shellscalingapi/nf-shellscalingapi-setprocessdpiawareness) | Windows 8.1 | SetProcessDpiAwareness(PROCESS_DPI_UNAWARE) | SetProcessDpiAwareness(PROCESS_SYSTEM_DPI_AWARE) | SetProcessDpiAwareness(PROCESS_PER_MONITOR_DPI_AWARE) |
| [SetProcessDpiAwarenessContext](/windows/win32/api/winuser/nf-winuser-setprocessdpiawarenesscontext) | Windows 10, version 1607 | SetProcessDpiAwarenessContext(DPI_AWARENESS_CONTEXT_UNAWARE) | SetProcessDpiAwarenessContext(DPI_AWARENESS_CONTEXT_SYSTEM_AWARE) | <p>SetProcessDpiAwarenessContext(DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE)</p><p>SetProcessDpiAwarenessContext(DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2)</p> |

## Process-default vs. Thread default

This document refers to setting the default DPI awareness for your process. This is because Windows 10 introduced support for running more than one DPI awareness mode within a single process (prior to Windows 10, the entire process had to conform to a single DPI awareness mode). Support for running more than one DPI awareness mode within a process is referred to as "mixed-mode DPI scaling". When using mixed-mode DPI scaling within your process, each top-level Window can run in a DPI awareness mode that may be different than that of the process default. Unless explicitly specified, each thread will default to the process default when created. For more information about mixed-mode DPI scaling, refer to the [Mixed-Mode DPI Scaling](https://msdn.microsoft.com/library/mt744321\(v=vs.85\)) article.
This document refers to setting the default DPI awareness for your process. This is because Windows 10 introduced support for running more than one DPI awareness mode within a single process (prior to Windows 10, the entire process had to conform to a single DPI awareness mode). Support for running more than one DPI awareness mode within a process is referred to as "mixed-mode DPI scaling". When using mixed-mode DPI scaling within your process, each top-level Window can run in a DPI awareness mode that may be different than that of the process default. Unless explicitly specified, each thread will default to the process default when created. For more information about mixed-mode DPI scaling, refer to the [Mixed-Mode DPI Scaling and DPI-aware APIs](/windows/win32/hidpi/high-dpi-improvements-for-desktop-applications) article.