/****************************************************************************
**
** Copyright (C) 2015 The Qt Company Ltd.
** Contact: http://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see http://www.qt.io/terms-conditions. For further
** information use the contact form at http://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
    \page highdpi.html
    \title High DPI Displays
    \brief Concepts of High DPI Displays

    \section1 High DPI Displays

    High DPI monitors and displays with superb image quality and crisp font rendering
    are becoming increasingly popular. For example, 4K monitors may have 3840x2160 pixels,
    resulting in a logical resolution of 192 DPI, whereas older monitors have around 1920x1080
    pixels at 96 DPI.

    \section2 Issues with High DPI

    High DPI Displays cause a number of issues for existing applications:

    \list
        \li Applications using UI designs with fixed coordinates look small.
            The combination of font size specification in points and other sizes in
            pixels is particularly problematic since points are independent of the monitor
            resolution. For example, a frame of 40x20 pixels around the text "hello"
            using a 12pt font looks correct on low resolution monitors,
            but the frame will be too small on high DPI monitors, causing the text
            to be clipped.

        \li Applications must adapt to situations where users have multiple displays with
            varying resolution.  For example, they might use a 4K monitor for the
            document window of an image editor and a low resolution monitor for the
            tool box.

        \li Backing store and pixmap buffers become quite large so that
            rendering may slow down.
    \endlist

    \section2 Operating System Support

    The operating systems supported by Qt offer the following support for high DPI displays:

    \section3 OS X

    On OS X, there is a separate, float-based user coordinate system (as opposed
    to Device Pixels). For high DPI monitors, the operating system will scale the
    contents using an efficient scaling algorithm that will make everything look
    very crisp (Retina Display).

    \note The scaling is not applied to Open GL windows.

    \section3 Microsoft Windows

    \section4 Scaling

    The user can choose a scaling factor from the control panel or via context menu.
    This works by making the functions for querying the system metrics return
    different values for standard font sizes, sizes of window borders, and so on.
    It does not perform any actual scaling.

    \section4 DPI Awareness

    An application on Windows can assume one of the following levels of "DPI Awareness":

    \table
        \header
            \li DPI Awareness Level
            \li Meaning

        \row
            \li DPI Unaware
            \li This level has been introduced in Windows-Vista. Windows will pretend to the
                application that it is running on a standard display of 96 DPI of 1920x1080
                and scale the application accordingly. It is intended to accommodate older
                applications designed for low DPI displays. Some artifacts may result from
                this type of scaling.

        \row
            \li System-DPI Aware
            \li This level has been introduced in Windows-Vista. It differs from
                \e{Per-Monitor DPI Aware} only when multiple monitors are connected.
                Windows will calculate a scaling suitable for all connected monitors.

        \row
            \li Per-Monitor DPI Aware
            \li This level has been introduced in Windows 8.1. Windows does not perform
                any scaling at all.

    \endtable

    Qt applications by default are \e{Per-Monitor DPI Aware} on Windows 8.1 or \e{System-DPI Aware}
    on older versions of Windows. As of Qt 5.4, the level can be specified by passing a parameter
    to the platform plugin (see \l{Using qt.conf}):

    \code
    <application> -platform windows:dpiawareness=0,1,2
    \endcode

    \section2 High DPI Support in Qt

    \list
        \li Ability to provide pixmaps or artwork for high resolution:
            see \l{Drawing High Resolution Versions of Pixmaps and Images}.

        \li Qt 5.6 supports cross-platform high-DPI scaling for legacy applications,
            similar to the scaling done natively by OS X. This allows applications written
            for low-DPI screens to run unchanged on high-DPI devices. This feature is
            opt-in, and can be enabled by the following environment variables:
            \list

                \li \c QT_AUTO_SCREEN_SCALE_FACTOR [boolean] enables automatic scaling,
                based on the pixel density of the monitor. This will not change the size
                of point sized fonts, since point is a physical unit of measure. Multiple
                screens may get different scale factors.

                \li \c QT_SCALE_FACTOR [numeric] defines a global scale
                factor for the whole application, including point sized fonts.

                \li \c QT_SCREEN_SCALE_FACTORS [list] specifies scale factors
                for each screen. This will not change the size
                of point sized fonts. This environment variable is
                mainly useful for debugging, or to work around monitors with wrong
                \l {https://en.wikipedia.org/wiki/Extended_Display_Identification_Data}
                {EDID information}(Extended Display Identification Data).

                The format can be either a semicolon-separated list of scale
                factors in the same order as QGuiApplication::screens(), or a
                semicolon-separated list of \c name=value pairs, where \c
                name is the same as QScreen::name().

                \endlist

            It is recommended to use the \c Fusion style.

            \note Non-integer scale factors may cause significant
            scaling/painting artifacts.

         \li The application attribute \c Qt::AA_EnableHighDpiScaling, introduced in Qt 5.6,
             enables automatic scaling based on the pixel density of the monitor.

         \li The application attribute \c Qt::AA_DisableHighDpiScaling, introduced in Qt 5.6,
             turns off all scaling. This is intended for applications that need to use
             actual window system coordinates, regardless of environment variables. This
             attribute takes priority over Qt::AA_EnableHighDpiScaling.

        \li An experimental implementation of high-DPI scaling was introduced in Qt 5.4.
            It was enabled by the environment variable \c QT_DEVICE_PIXEL_RATIO, which
            could be set to a numerical scale factor or \c "auto". This variable is
            deprecated in Qt 5.6.
        \endlist

    \section2 Migration of Existing Applications

    In order to get an application designed for low DPI values running on a high
    resolution monitors quickly, consider one of the scaling options (let the
    application run as \e{DPI Unaware} on Windows or set the environment
    variable \c QT_AUTO_SCREEN_SCALE_FACTOR to \c "1". These options may incur
    some scaling or painting artifacts, though.

    In the longer term, the application should be adapted to run unmodified:

    \list
        \li Always use the qreal versions of the QPainter drawing API.
        \li Size windows and dialogs in relation to the screen size.
        \li Replace hard-coded sizes in layouts and drawing code
            by values calculated from font metrics or screen size.
    \endlist

    \section2 Glossary Of High DPI Terms

    \table
        \header
            \li Term
            \li Definition

        \row
            \li Device Independent Pixels
            \li Pixels used by application (user space), subject to scaling by the operating
                system or Qt.

        \row
            \li Device Pixels
            \li Pixels of the display device.

        \row
            \li Device Pixel Ratio
            \li Scale factor applied by the operating system or Qt.

        \row
            \li Logical DPI
            \li Resolution used for converting font sizes defined in points to font sizes in pixels.
                Typically one of the standard values 96, 128, .. 192.

        \row
            \li Physical DPI
            \li Physical resolution obtained by dividing the size of the monitor by
                the number of pixels.

        \row
            \li Retina Display
            \li See \l{http://en.wikipedia.org/wiki/Retina_Display}{Wikipedia on Retina Displays}

        \row
            \li User Space
            \li The coordinate space the application uses (Device Independent Pixels).

    \endtable
*/
