/*
  gammaray-qtquick2-inspector.qdoc

  This file is part of GammaRay, the Qt application inspection and manipulation tool.

  SPDX-FileCopyrightText: 2016 Klarälvdalens Datakonsult AB, a KDAB Group company <info@kdab.com>
  Author: Volker Krause <volker.krause@kdab.com>

  SPDX-License-Identifier: GPL-2.0-or-later

  Contact KDAB at <info@kdab.com> for commercial licensing options.
*/

/*!
    \nextpage {Widget Inspector}
    \previouspage {Tools}
    \page gammaray-qtquick2-inspector.html

    \title Qt Quick 2 Inspector

    \section1 Overview

    The Qt Quick 2 inspector is the tool of choice for investigating issues with a \l{Qt Quick} user interface. This includes:

    \list
        \li Inspecting the visual item hierarchy.
        \li Remote view of the rendered content with diagnostic overlays.
        \li Inspecting the scene graph used for rendering the user interface on the GPU or via the software renderer.
    \endlist

    If your target has multiple QQuickView instances, the combo box at the top can be used to switch between them.

    \section1 Item Tree

    The item tree is shown on the top left, and it contains the visual hierarchy of QQuickItem instances in the currently selected Qt Quick scene.
    This does not necessarily match the QObject parent/child hierarchy.
    The right side contains universal \l{Object Inspection} view.

    \image gammaray-qq2-inspector.png

    You can navigate to the object browser (and other applicable tools) using the context menu on the item tree. Similarly, you can
    navigate to the source code locations instantiating the current item, or the file declaring the type of the current item (if available).

    \section1 Remote View

    The remote view is shown to the lower left in the Qt Quick 2 inspector. Besides giving you a zoomable view of the rendered content,
    it provides a number of additional features:

    \list
        \li Element picking.
        \li Diagnostic overlays with layout information.
        \li Input event forwarding, for working with embedded targets.
        \li Color picking.
        \li A measurement tool.
        \li Taking screenshots of the target output, with or without diagnostic overlays.
    \endlist

    \image gammaray-qq2-qsg-visualize.png

    The diagnostic render modes include:
    \list
        \li Clipping visualization: Highlights items using clipping, which is a potentially expensive operations on the OpenGL render backend.
        \li Overdraw visualization: Allows to spot out-of-view elements that are drawn, as well as elements that are drawn on top of each other,
        both of which are potentially expensive operations.
        \li Batch visualization: Highlights items that are in the same render batch on the OpenGL renderer, as well as unmerged batches. Unmerged
        batches, and more batches in general, can have significant render performance impact with the OpenGL renderer.
        \li Change visualization: Highlights areas causing view updates.
        \li Control tracing: Highlights Qt Quick Controls 2 outlines, which can help to identify layouting issues.
        \li Showing a customized layouting grid.
        \li Slowing down the animation timer to diagnose motion design issues.
    \endlist

    Diagnostic render modes can be enabled individually, both on the target and the GammaRay client via the \uicontrol{Quick Scenes} > \uicontrol{Decorate Target}
    menu option, or the corresponding remote view toolbar action.

    \section1 Paint Analyzer

    When selecting a QQuickPaintedItem sub-class in the item tree, the paint analyzer tab is activated in the property view on the right.

    \image gammaray-qqpainteditem-paint-analyzer.png

    The \l{Paint Analyzer} allows you to inspect every single QPainter command that is executed, and look at the visual result after each step.

    When using the Qt Quick software renderer, a full-scene paint analysis is also available via the \uicontrol{Quick Scenes} menu
    (requires Qt 5.9.3 or newer).

    \section1 Scene Graph

    The scene graph view shows you the internal representation used by \l{Qt Quick} to render the current scene. This is particularly
    useful for debugging performance issues related to batching and rendering of custom QQuickItem sub-classes.

    \image gammaray-qq2-geometry.png

    For nodes in the scene graph you have access to:

    \list
        \li QSGNode properties, in particularly node flags and transformation matrices.
        \li Shader code, if the node has a material associated with it (see \l{Scene Graph Material}).
        \li Geometry and other per-vertex data, when looking at a geometry node (see \l{Scene Graph Geometry}).
        \li Texture data for image elements, shader effects or distance-field rendered text elements (see \l{Scene Graph Texture}).
    \endlist

    \section1 Examples

    The following examples make use of the Qt Quick inspector:
    \list
        \li \l{quick-event-handling}
        \li \l{quick-batching}
    \endlist
*/
