// Copyright (C) 2019 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \qmlmodule QtQuick3D.Helpers
    \title Qt Quick 3D Helpers QML Types
    \brief Module containing helpers for creating applications using Qt Quick 3D.

    This module provides helper types that make it easier to develop applications
    using \l{Qt Quick 3D}.
*/

/*!
    \qmltype AxisHelper
    \inqmlmodule QtQuick3D.Helpers
    \inherits Node
    \brief Visual helper for showing the 3 axes and a grid in a 3D scene.

    \image axishelper.jpg

    The X axis is red, the Y axis is green, and the Z axis is blue.

    The example scene here has a Sphere at position \c{(0, 0, 0)} and an
    AxisHelper object. With the WasdController helper one can conveniently
    navigate the scene.

    \badcode
        View3D {
            anchors.fill: parent
            camera: camera

            PerspectiveCamera {
                id: camera
                position: Qt.vector3d(0, 0, 600)
            }

            DirectionalLight {
                position: Qt.vector3d(-500, 500, -100)
                color: Qt.rgba(0.4, 0.2, 0.6, 1.0)
                ambientColor: Qt.rgba(0.1, 0.1, 0.1, 1.0)
            }

            Model {
                source: "#Sphere"
                materials: [ DefaultMaterial { } ]
            }

            AxisHelper {
            }
        }

        WasdController {
            controlledObject: camera
        }
   \endcode
*/

/*! \qmlproperty color AxisHelper::gridColor
    Specifies the color of the grid. The default value is \c{Qt.rgba(0.8, 0.8, 0.8, 1)}.
*/
/*! \qmlproperty real AxisHelper::gridOpacity
    Specifies the opacity of the grid. The default value is 0.5.
*/
/*! \qmlproperty bool AxisHelper::enableXZGrid
    Enables the grid on XZ plane. The default value is true.
*/
/*! \qmlproperty bool AxisHelper::enableXYGrid
    Enables the grid on XY plane. The default value is false.
*/
/*! \qmlproperty bool AxisHelper::enableYZGrid
    Enables the grid on YZ plane. The default value is false.
*/
/*! \qmlproperty bool AxisHelper::enableAxisLines
    Enables showing the axis lines. The default value is true.
*/

/*!
    \qmltype WasdController
    \inqmlmodule QtQuick3D.Helpers
    \inherits Item
    \brief Control node position and orientation with keys and mouse.

    This helper allows the user to control a node using W, A, S, D, the arrow
    keys, and the mouse. Usually the controlled node is a Camera, specified in
    the controlledObject property.

    Adding a WasdController can be highly useful both in applications that wish
    to provide a standard way of navigating the scene, and also as a temporary
    measure during development and troubleshooting, as it allows inspecting the
    scene at run time via familiar keyboard and mouse navigation.

    The key bindings are as follows:

    \list
    \li \c W or \c up - go forward
    \li \c S or \c down - go backward
    \li \c A or \c left - strafe left
    \li \c D or \c right - strafe right
    \li \c R or \c {page up} - move up
    \li \c F or \c {page down} - move down
    \li \c shift together with other keys - move faster, depending on \l shiftSpeed
    \endlist

    The following snippet shows how a WasdController object can be added. By
    default both key and mouse based navigation is active, so in most cases
    there is no further configuration needed:

    \badcode
        View3D {
            anchors.fill: parent
            camera: camera
            PerspectiveCamera {
                id: camera
                position: Qt.vector3d(0, 0, 600)
            }
            ...
        }

        WasdController {
            controlledObject: camera
        }
    \endcode
*/

/*! \qmlproperty QtQuick3D::Node WasdController::controlledObject
    Specifies the node to control. This is typically a Camera object.
*/
/*! \qmlproperty real WasdController::speed
    Specifies the speed of navigation.
*/
/*! \qmlproperty real WasdController::shiftSpeed
    Specifies the speed multiplier that is active when the shift key is pressed.
*/
/*! \qmlproperty real WasdController::forwardSpeed
    Specifies the speed of navigation when the forward key is pressed.
*/
/*! \qmlproperty real WasdController::backSpeed
    Specifies the speed of navigation when the back key is pressed.
*/
/*! \qmlproperty real WasdController::rightSpeed
    Specifies the speed of navigation when the right key is pressed.
*/
/*! \qmlproperty real WasdController::leftSpeed
    Specifies the speed of navigation when the left key is pressed.
*/
/*! \qmlproperty real WasdController::upSpeed
    Specifies the speed of navigation when the up key is pressed.
*/
/*! \qmlproperty real WasdController::downSpeed
    Specifies the speed of navigation when the down key is pressed.
*/
/*! \qmlproperty real WasdController::xSpeed
    Specifies the speed of navigation when the mouse is moved along the X axis.
*/
/*! \qmlproperty real WasdController::ySpeed
    Specifies the speed of navigation when the mouse is moved along the Y axis.
*/
/*! \qmlproperty bool WasdController::xInvert
    Inverts the x-axis controls. The default value is false.
*/
/*! \qmlproperty bool WasdController::yInvert
    Inverts the y-axis controls. The default value is true.
*/
/*! \qmlproperty bool WasdController::mouseEnabled
    Enables mouse controls. The default value is true.
*/
/*! \qmlproperty bool WasdController::keysEnabled
    Enables key controls. The default value is true.
*/
/*! \qmlproperty bool WasdController::inputsNeedProcessing
    This property is true when there are inputs needing processing.
    \readonly
*/
/*! \qmlproperty enumeration WasdController::acceptedButtons
    Specifies the buttons accepted by the controller.
    \sa DragHandler, MultiPointHandler
*/

/*!
    \qmltype DebugView
    \inqmlmodule QtQuick3D.Helpers
    \inherits Rectangle
    \brief View to show render statistics.

    This helper allows viewing render performance statistics of a View3D.
    It shows the FPS, sync and render times.

    For example, the following snippet shows how a DebugView can be added that
    shows its information in the top-left corner of the Qt Quick scene:

    \badcode
        View3D {
            id: v3d
            anchors.fill: parent
            camera: camera
            PerspectiveCamera {
                id: camera
                position: Qt.vector3d(0, 0, 600)
            }
            ...
        }
        DebugView {
            source: v3d
        }
    \endcode
*/

/*! \qmlproperty var DebugView::source
    Specifies the source View3D to show the statistics from.
*/

/*!
    \qmltype OrbitCameraController
    \inqmlmodule QtQuick3D.Helpers
    \inherits Item
    \brief Camera Controller which rotates around an origin.

    This helper provides a way to rotate a camera around an origin. To function
    OrbitCameraController accepts a Node as the origin, and a Camera object
    which should be a child of the originNode to control. By only adjusting the z
    position of the child camera relative to the parent origin it has the effect
    of moving the camera nearer or farther from the target origin. By applying
    a rotation to the origin node, the child camera will be orbited around the
    origin node.

    The OrbitCameraController item itself is a 2D item that accepts input events
    so whatever it's size and position will be where input events are accepted.
    To zoom either use the scroll wheel of the mouse or perform a pinch gesture.
    To rotate click or touch and drag the area. To pan, hold control and drag
    the area. Panning will change the position of the origin node. It is also
    possible to perform a panning gesture by performing a two finger drag.

    \badcode
        View3D {
            camera: cameraNode
            Node {
                id: originNode
                PerspectiveCamera {
                    id: cameraNode
                    z: 100
                }
            }
            OrbitCameraController {
                anchors.fill: parent
                origin: originNode
                camera: cameraNode
            }
            ...
        }
    \endcode
*/

/*! \qmlproperty QtQuick3D::Node OrbitCameraController::origin
    Specifies the origin node to control. This is a required property and should
    be the parent of the \l camera
*/
/*! \qmlproperty QtQuick3D::Camera OrbitCameraController::camera
    Specifies the camera node to control. This is a required property and should
    be a child of the \l origin node.
*/
/*! \qmlproperty QtQuick3D::Node OrbitCameraController::xSpeed
    Specifies the speed of navigation when the mouse is moved along the X axis.
*/
/*! \qmlproperty QtQuick3D::Node OrbitCameraController::ySpeed
    Specifies the speed of navigation when the mouse is moved along the Y axis.
*/
/*! \qmlproperty bool OrbitCameraController::xInvert
    Inverts the x-axis controls. The default value is false.
*/
/*! \qmlproperty bool OrbitCameraController::yInvert
    Inverts the y-axis controls. The default value is true.
*/
/*! \qmlproperty bool OrbitCameraController::mouseEnabled
    Enables mouse controls. The default value is true.
*/
/*! \qmlproperty bool OrbitCameraController::panEnabled
    Enables panning controls. The default value is true.
*/
