/****************************************************************************
**
** Copyright (c) 2014 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of Qt Creator
**
**
** GNU Free Documentation License
**
** 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.
**
**
****************************************************************************/

// **********************************************************************
// NOTE: the sections are not ordered by their logical order to avoid
// reshuffling the file each time the index order changes (i.e., often).
// Run the fixnavi.pl script to adjust the links to the index order.
// **********************************************************************

/*!
    \contentspage {Qt Creator Manual}
    \previouspage creator-analyze-mode.html
    \page creator-qml-performance-monitor.html
    \nextpage creator-valgrind-overview.html

    \title Profiling QML Applications

    To monitor the performance of an application in the QML Profiler:

    \list 1

        \li To be able to profile an application, you must set up QML debugging
            for the project. For more information, see
            \l{Setting Up QML Debugging}.

        \li In the \gui Projects mode, select a \l{glossary-buildandrun-kit}
            {kit} with Qt version 4.7.4 or later.

            \note To profile applications on devices, you must install Qt 4.7.4
            or later libraries on them.

        \li Select \gui {Analyze > QML Profiler} to profile the current
            application.

        \li Select the
            \inlineimage qtcreator-analyze-start-button.png
            (\gui Start) button to start the application from the
            QML Profiler.

            \note If data collection does not start automatically, select the
            \inlineimage qtcreator-analyzer-button.png
            (\gui {Enable Profiling}) button.

    \endlist

    When you start analyzing an application, the application is launched, and
    the QML Profiler immediately begins to collect data. This is indicated by
    the time running in the \gui Elapsed field.

    Data is collected until you select the \gui {Enable Profiling} button. Data
    collection
    takes time, and therefore, there might be a delay
    before the data is displayed.

    Do not use application commands to exit the application, because data is
    sent to the QML Profiler when you select the \gui {Enable Profiling} button.
    The application continues to run for some seconds, after which it is stopped
    automatically. If you exit the application, the data is not sent.

    Select the \gui {Disable Profiling} button to disable the automatic
    start of the data collection when an
    application is launched. Data collection starts when you select the button
    again.

    To save all the collected data, right-click any QML Profiler view to open
    the context menu, and then select \gui {Save QML Trace}. To view the saved
    data, select \gui {Load QML Trace}. You can also deliver the saved data to
    other developers for examination or load data saved by them.

    \section1 Attaching to Running Qt Quick Applications

    To profile Qt Quick applications that are not launched by \QC, select
    \gui {Analyze > QML Profiler (External)}. You must enable QML debugging for
    the application in the project build settings. For more information, see
    \l{Setting Up QML Debugging}.

    In the \gui {QML Profiler} dialog, \gui Port field, specify the port to
    listen to.

    \section1 Analyzing Collected Data

    The \gui Timeline view displays graphical representations of QML and
    JavaScript execution and a condensed view of all recorded events.

    \image qtcreator-qml-performance-monitor.png "QML Profiler"

    Each row in the timeline (6) describes a type of QML events that were
    recorded. Move the cursor on an event on a row to see how long it takes and
    where in the source it is being called. To display the information only when
    an event is selected, disable the \gui {View Event Information on Mouseover}
    button (5).

    The outline (10) summarizes the period for which data was collected. Drag
    the zoom range (8) or click the outline to move on the outline. You can
    also move between events by selecting the \gui {Jump to Previous Event} (1)
    and \gui {Jump to Next Event} (2) buttons.

    Select the \gui {Show Zoom Slider} button (3) to open a slider that you can
    use to set the zoom level. You can also drag the zoom handles (9). To reset
    the default zoom level, right-click the timeline to open the context menu,
    and select \gui {Reset Zoom}.

    \section2 Selecting Event Ranges

    You can select an event range (7) to view the frame rate of events and to
    compare it with the frame rate of similar events. Select the
    \gui {Select Range} button (4) to activate the selection tool. Then click in
    the timeline to specify the beginning of the event range. Drag the selection
    handle to define the end of the range. The length of the range indicates the
    frame rate of the event.

    You can use event ranges also to measure delays between two subsequent
    events. Place a range between the end of the first event and the beginning
    of the second event. The \gui Duration field displays the delay between the
    events in milliseconds.

    To zoom into an event range, double-click it.

    To remove an event range, close the \gui Selection dialog.

    \section2 Understanding the Data

    Generally, events in the timeline view indicate how long QML or JavaScript
    execution took. Move the mouse over them to see details. For most events,
    they include location in source code, duration and some relevant parts of
    the source code itself.

    You can click on an event to move the cursor in the code editor to the part
    of the code the event is associated with.

    The following types of events are displayed in the timeline view on one or
    several rows. The availability of event types depends on the version of Qt
    the application was compiled with, the version of Qt Quick it is using, and
    whether \QC or \QCE is used to profile it.

    \table

    \header
        \li Event Type
        \li Description
        \li Minimum Qt Version
        \li Qt Quick Version
        \li Enterprise Feature

    \row
        \li \gui {Pixmap Cache}
        \li Displays the general amount of pixmap data cached, in pixels. In
            addition, displays a separate event for each picture being loaded,
            with specifics about its file name and size.
        \li Qt 5.1
        \li Qt Quick 2
        \li Yes

    \row
        \li \gui {Scene Graph}
        \li Displays the time when scene graph frames are rendered and some
            additional timing information for the various stages executed to do
            so.
        \li Qt 5.1
        \li Qt Quick 2
        \li Yes
    \row
        \li \gui {Memory Usage}
        \li Displays block allocations of the JavaScript memory manager.
            Generally, the memory manager will reserve larger blocks of memory
            in one piece and later hand them out to the application in smaller
            bits. If the application requests single blocks of memory
            surpassing a certain size, the memory manager will allocate those
            separately. Those two modes of operation are shown as events of
            different colors.

            The second row displays the actual usage of the allocated memory.
            This is the amount of JavaScript heap the application has actually
            requested.
        \li Qt 5.4
        \li Qt Quick 2
        \li Yes

    \row
        \li \gui Painting
        \li Displays the time spent painting the scene for each frame.
        \li Qt 4.7.4
        \li Qt Quick 1
        \li No

    \row
        \li \gui Animations
        \li Displays the amount of animations that are active and the frame
            rate that they are running at.

            Information about render thread animations is displayed for
            applications that are built with Qt 5.3 or later. Render thread
            animations are shown in a separate row then.
        \li Qt 5.0 (Qt 5.3)
        \li Qt Quick 2
        \li No

    \row
        \li \gui Compiling
        \li Displays the time spent compiling the QML files.
        \li Qt 4.7.4
        \li Qt Quick 1 or Qt Quick 2
        \li No

    \row
        \li \gui Creating
        \li Displays the time spent creating the elements in the scene. In Qt
            Quick 2, creation of elements takes place in two stages. The first
            stage is for the creation of the data structures, including child
            elements. The second stage represents the completion callbacks. Not
            all elements trigger completion callbacks, though. The stages are
            shown as separate events in the timeline.

            For Qt Quick 2 applications compiled with versions of Qt before
            5.2.1 only the creation of top-level elements is shown, as single
            events.
        \li Qt 4.7.4 (Qt 5.2.1)
        \li Qt Quick 1 or Qt Quick 2
        \li No

    \row
        \li \gui Binding
        \li Displays the time when a binding is evaluated and how long the
            evaluation takes.
        \li Qt 4.7.4
        \li Qt Quick 1 or Qt Quick 2
        \li No

    \row
        \li \gui {Handling Signal}
        \li Displays the time when a signal is handled and how long the
            handling takes.
        \li Qt 4.7.4
        \li Qt Quick 1 or Qt Quick 2
        \li No

    \row
        \li \gui JavaScript
        \li Displays the time spent executing the actual JavaScript behind
            bindings and signal handlers. It lists all the JavaScript functions
            you may be using to evaluate bindings or handle signals.
        \li Qt 5.3
        \li Qt Quick 2
        \li No

    \endtable

    \section1 Viewing Events

    The \gui Events view displays the number of times each binding, create,
    compile, JavaScript, or signal event is triggered and the average time it
    takes. This allows you to examine which events you need to optimize. A high
    number of occurrences might indicate that an event is triggered
    unnecessarily. To view the median, longest, and shortest time for the
    occurrences, select \gui {Extended Event Statistics} in the context menu.

    Click on an event to move to it in the source code
    in the code editor.

    JavaScript events often duplicate bindings or signals, so you can show and
    hide them by selecting \gui {Show JavaScript Events} in the context menu.
    To show and hide QML events (\gui Create, \gui Compile, and \gui Signal),
    select \gui {Show QML Events}.

    \image qtcreator-analyzer-bindings.png "Events view"

    The \gui Callers and \gui Callees panes show dependencies between events.
    They allow you to examine the internal functions of the application.
    The \gui Callers pane summarizes the QML events that trigger a binding.
    This tells you what caused a change in a binding.
    The \gui Callees pane summarizes the QML events that a binding triggers.
    This tells you which QML events are affected if you change a binding.

    Click on an event to move to it in the source code in the code editor.

    When you select an event in the \gui Timeline view, information about it is
    displayed in the \gui Events view. To view an event range in the \gui Events
    view, select \gui {Limit Events Pane to Current Range} in the context menu
    in the \gui Timeline view.

    To copy the contents of one view or row to the clipboard, select
    \gui {Copy Table} or \gui {Copy Row} in the context menu.

    JavaScript events are shown in the \gui Events view only for applications
    that use Qt Quick 2 and are compiled with Qt 5.3 or later. For applications
    that use Qt Quick 2 and are built with Qt 5.0 or 5.1, you can view
    information about JavaScript events in the separate \gui JavaScript view.

    \section2 Viewing More Data

    The QML JavaScript engine optimizes trivial bindings. The QML Profiler
    may not receive all information about optimized bindings, and therefore,
    it may display the text \gui {<bytecode>} and the message
    \gui {Source code not available} in the \gui Callers and \gui {Callees}
    panes.

    To inspect the optimized bindings, turn off the QML optimizer by setting
    the environment variable QML_DISABLE_OPTIMIZER to 1. To set the environment
    variable for the current project in the project settings:

    \list 1

        \li Select \gui {Projects > Run}.

        \li In \gui {Run Environment}, click \gui Add.

        \li Add the QML_DISABLE_OPTIMIZER variable and set its value to 1.

    \endlist

*/
