/****************************************************************************
**
** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** 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 Digia.  For licensing terms and
** conditions see http://qt.digia.com/licensing.  For further information
** use the contact form at http://qt.digia.com/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 winrt_support.html
    \title Qt for WinRT
    \brief Provides insight into Qt's WinRT port and how to use it.

    Qt for WinRT allows you to run Qt applications on devices supporting the
    Windows Store App APIs. This includes Modern UI applications in Windows 8.1
    and up, as well as devices running the Windows RT and Windows
    Phone 8.

    Microsoft introduced a new design paradigm with the Windows 8 Modern UI. A
    core part of this new approach is Windows Runtime (WinRT) that supports
    development using different programming languages, such as C++/CX (component
    extensions), C# VB.NET, or JavaScript. The Qt port uses the C++
    capabilities. While WinRT supports the component extensions internally, they
    are not used inside Qt and you do not need to use them. WinRT applications
    run in a sandboxed environment for security reasons and support different
    architectures, such as ARM and x86.

    \section1 Requirements

    Development for Windows Runtime requires a Microsoft Windows development host.
    The minimum version supported is Windows 8.1.

    Depending on your device target you will need the following tools provided
    by Microsoft to be installed:

    \table
    \header
        \li Device Target
        \li Environment
    \row
        \li Windows 8.1 Modern UI
        \li Visual Studio 2013 for Windows
    \row
        \li Windows RT
        \li Visual Studio 2013 for Windows
    \row
        \li Windows Phone 8
        \li Visual Studio 2012 for Windows Phone
    \endtable

    If you are targeting a remote device, please follow all instructions by
    Visual Studio to set it up correctly.

    \section1 Getting Started

    \section2 Building Applications

    You can develop applications for WinRT just as any other Qt applications.
    Use your favorite editor or IDE (such as Qt Creator) and create your
    application or load a Qt example. Then run \c qmake and \c {nmake/jom} to
    build your application.

    \section3 Building Applications with Visual Studio

    To launch your project with Visual Studio a corresponding project needs to
    be created. \c qmake supports converting a \c .pro project into Visual
    Studio format by passing the parameters \c -tp vc.

    \code
      qmake -tp vc <your project>.pro
    \endcode

    Be aware of using the correct match of \c qmake and Visual Studio. As the
    Visual Studio format is generic, it does not return an immediate error if
    for instance you open a Windows Phone project inside Visual Studio
    for Windows.

    This creates a project which supports building applications and running them
    with Visual Studio. It does not embed Qt libraries into the package and
    requires you to add them manually. For this purpose, the command line
    tool \l{The Windows Deployment Tool}{windeployqt} has been included in the installed package. To
    enable automatic parsing of dependencies and adding the libraries and
    dependencies into the application package, create the project with the
    following options:

    \code
      qmake -tp vc <your project>.pro "CONFIG+=windeployqt"
    \endcode

    \section3 Building Applications with Qt Creator

    You will not need to do any conversion to open your project in Qt Creator.
    Please follow the generic instructions on how to open and build a project.

    Qt Creator deploys your application on the WinRT device, if the
    device is detected by the PC.

    \note Remote PCs, such as the Surface, are not yet supported for deployment by Creator.

    \section1 Building from source

    We assume that you have cloned the Qt 5 repositories (or obtained
    the Qt sources elsewhere) and followed the platform-independent
    requirements for building Qt. The process of building Qt is found
    in the \l{Building Qt Sources} page.

    Qt for WinRT is always built as a cross-build, because tools, such as qmake,
    are built as desktop applications. For compiling those, a desktop development
    environment is required. If you have installed Visual Studio 2013 for Windows,
    this will only create binaries for WinRT. You will need Visual Studio for
    Windows Desktop as well to create those desktop tools.

    The WinRT mkspec format is \c {<platform>-<architecture>-<toolchain>}
    where \e platform can be \c winrt or \c winphone and architecture can be
    \c arm, \c x86, or \c x64. The following is an example of building qtbase
    for WinRT:
    \code
        > ./configure -xplatform winrt-x64-msvc2012 -developer-build -release
        > nmake/jom
    \endcode

    \section1 Running Applications from Command Line

    WinRT applications must be packaged (including all dependencies) and
    installed or registered with the application service in order to be
    launched. \l{winrtrunner}{The WinRT Runner Tool} can be used to
    launch these applications from the command line.

    \section2 Package Content
    Package content
    consists of the application executable and its dependencies, as for every
    Windows application. The dependencies are the needed (Qt)
    libraries and plugins. Note that Qt plugins have to be put into a folder
    named after their category (platforms, imageformats, and so on) without
    using a \c plugins folder as root. For more information, see
    \l{Qt for Windows - Deployment}.

    Additionally, any pre-compiled shaders used by OpenGL applications must
    also be packaged. See \l{OpenGL Shaders on WinRT}.

    As WinRT applications are run in a sandboxed environment, setting
    the path variable to point to the files required will not work.

    The \l{The Windows Deployment Tool}{windeployqt} convenience tool looks up
    the application's dependencies
    and copies Qt libraries and plugins to the appropriate directories, as
    necessary.

    In order to be able to run debug builds of your applications you have to
    register the correct VCLib debug framework. This framework provides the
    \b{C++ Runtime} for Modern UI applications and its files can usually be found in
    \b{<Path to Microsoft SDKs>\\<Windows version>\\ExtensionSDKs\\Microsoft.VCLibs\\<VC Version>\\AppX\\Debug\\<CPU architecture>}
    To register the debug VCLibs for x64 for Visual Studio 2013
    on Windows 8.1, run the following command in PowerShell:
    \code
        > Add-AppxPackage 'C:\Program Files (x86)\Microsoft SDKs\Windows\v8.1\ExtensionSDKs\Microsoft.VCLibs\12.0\AppX\Debug\x64\Microsoft.VCLibs.x64.Debug.12.00.appx'
    \endcode
    \note \l{winrtrunner}{The WinRT Runner Tool} installs these dependencies automatically.

    Because all resources are placed to one directory, you can register the
    directory using an XML file (AppxManifest.xml) and Windows Powershell. The reference
    for these manifest files can be found
    \l{http://msdn.microsoft.com/en-us/library/windows/apps/br211473.aspx}{here}.
    If you are using a debug build, your AppxManifest has to provide information about
    its dependency on the just added VCLibs. Additionally, the target processor
    architecture must be specified (as opposed to the default, 'neutral').
    As soon as these requirements are met, change into your \e packaged directory in
    PowerShell and call:
    \code
        > Add-AppxPackage -Register AppxManifest.xml
    \endcode
    \note \l{winrtrunner}{The WinRT Runner Tool} can perform the same operation with the --install option.

    If that worked, you should be able to find your application in Windows 8's
    start screen. To remove your application, use Windows' built-in way to
    uninstall applications (right-click or tap and hold the application and
    choose \c{Uninstall}).
    \note \l{winrtrunner}{The WinRT Runner Tool} can perform the same operation with the --remove option.

    \section2 WinRT Runner Tool
    \target winrtrunner
    The WinRT Runner Tool can be found in QTDIR/bin/winrtrunner. It is
    intended to aid in the deployment, launching, and debugging of Qt for WinRT
    applications. It can be used from the command line, or invoked by the IDE.

    \badcode
    Usage: winrtrunner.exe [options] package [arguments]
    winrtrunner installs, runs, and collects test results for packages made with Qt.

    Options:
      --test                            Installs, starts, collects output, stops (if
                                        needed), and uninstalls the package. This is
                                        the default action of winrtrunner.
      --start                           Starts the package. The package is installed
                                        if it is not already installed. Pass
                                        --install to force reinstallation.
      --debug <debugger>                Starts the package with the debugger
                                        attached. The package is installed if it is
                                        not already installed. Pass --install to
                                        force reinstallation.
      --debugger-arguments <arguments>  Sets the arguments to be passed to the
                                        debugger when --debug is used. If no
                                        debugger was provided, this option is ignored.
      --suspend                         Suspends a running package. When combined
                                        with --stop or --test, the app will be
                                        suspended before being terminated.
      --stop                            Terminates a running package. Can be be
                                        combined with --start and --suspend.
      --wait <seconds>                  If the package is running, waits the given
                                        number of seconds before continuing to the
                                        next task. Passing 0 causes the runner to
                                        wait indefinitely.
      --install                         (Re)installs the package.
      --remove                          Uninstalls the package.
      --device <name|index>             Specifies the device to target as a device
                                        name or index. Use --list-devices to find
                                        available devices. The default device is the
                                        first device found for the active run
                                        profile.
      --profile <name>                  Forces a particular run profile.
      --list-devices                    Lists the available devices (for use with
                                        --device).
      --verbose <level>                 Sets the verbosity level of the message output
                                        (0 - silent, 1 - info, 2 - debug). Defaults
                                        to 1.
      --ignore-errors                   Always exits with code 0, regardless of the
                                        error state.
      -?, -h, --help                    Displays this help.

    Arguments:
      package [arguments]               The executable or package manifest to act
                                        upon. Arguments after the package name will
                                        be passed to the application when it starts.
    \endcode

    \section1 OpenGL Shaders on WinRT
    Qt for WinRT uses \l{ANGLE} to provide its OpenGL implementation, which generates
    Direct3D HLSL from OpenGL shader source code, and this source code must be
    compiled before it can be used by OpenGL APIs, such as those used by the
    \l{Qt Quick Scene Graph}. This is normally accomodated at runtime by the
    D3D Compiler DLL. However, the traditional D3D Compiler DLL is not available
    for use by Windows Phone 8.0 applications. Therefore, a proxy drop-in replacement,
    \c{d3dcompiler_qt.dll}, was created to provide precompiled shader binaries
    from a service running on the host machine, or from a local file path or
    \l{The Qt Resource System}{resource file}.
    \note The D3D Compiler API is allowed in Windows 8.1 and Windows Phone 8.1, so
    shader precompilation is not required (but may still be used) on those platforms.

    \section2 Using the Qt D3D Shader Service
    \target qtd3dservice
    The Qt D3D Shader Service can be found in QTDIR/bin/qtd3dservice. It is designed
    to automatically detect Qt applications running locally and on connected
    Windows Phone devices and emulators. To use it, simply start the \c{qtd3dservice}
    executable with no arguments. It will then run indefinitely, servicing applications
    until it is stopped. Other options may be passed to get additional debug output
    or collect information on previously observed shader sources and binaries.

    \badcode
    Usage: qtd3dservice.exe [options]

    Options:
      --output <file>    Writes output to a file.
      --verbose <level>  Sets the verbosity level of the message output (0 - silent,
                         1 -info, 2 - debug). Defaults to 1.
      --list-source      Lists the known shader sources. Use with --app and/or
                         --device to narrow the scope.
      --list-binary      Lists the known shader binaries. Use with --app and/or
                         --device to narrow the scope.
      --app <name>       Specifies the application to act upon.
      --device <name>    Specifies the device to act upon.
      --qrc              Outputs the content of --list-source/--list-binary in Qt
                         resource file format.
      -?, -h, --help     Displays this help.
    \endcode

    \section2 Packaging Shaders for Deployment
    While \l{qtd3dservice} will pick up shader sources and generate shader binaries
    during runtime, it obviously cannot be used in published applications. It is
    the responsibility of the developer to package these shader "blobs" with the
    application before publishing. To do so, first run through your application
    on the target device to make sure all shader sources have been compiled. You
    can confirm this by running the application without the shader service
    running, as the blobs will be picked up from the local device cache.

    Once this has been done, generate a QRC for packaging the shader blobs into
    the application. For example, to get a QRC for a Windows Phone device and an
    application ID of {975735f9-70ac-4593-b1cb-a9bec8cad348}, you would use the
    following command:
    \code
        > qtd3dservice --list-binary --qrc --device 0 --app {975735f9-70ac-4593-b1cb-a9bec8cad348} --output /path/to/project/shaders.qrc
    \endcode

    You may then include this file in your qmake project file using the following
    line:
    \code
        RESOURCES += shaders.qrc
    \endcode
    The precompiled shaders will be used by ANGLE when encountered in your
    application.
*/
