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

/*!
    \example intro
    \ingroup quick3d-examples
    \title Qt Quick 3D - Introduction
    \examplecategory {3D}
    \brief Demonstrates how to render a scene in Qt Quick 3D.
    \image intro.png

    This example gives an introductory overview of the basic Quick 3D features by going
    through the code of a simple example.

    \section1 Setting Up the Scene

    We set up the entire scene in the \e main.qml file.

    To be able to use the types in the QtQuick3D module, we must import it:

    \snippet intro/main.qml import

    To draw any 3D scene, we need a 3D viewport within the Qt Quick scene.  This is
    provided by the View3D class, and this is where we define our scene. It is also
    possible to have multiple views in one application, see \l{Qt Quick 3D - View3D
    Example}.

    We start with defining the environment of our scene. In this example we just clear the
    background color with \c skyblue, which we specify in a SceneEnvironment for the \c
    environment property of the view. SceneEnvironment describes various properties
    related to the environment of the scene, such as tonemapping settings, light probe
    settings for image based lighting, background mode, or ambient occlusion
    parameters. It can also control anti-aliasing, see \l{Qt Quick 3D - Antialiasing
    Example}. In our example we set the \c clearColor and \c backgroundMode properties
    to get a blue background.

    \snippet intro/main.qml environment

    \section1 Meshes

    To make the scene a bit more interesting we are now going to add some meshes. In Quick
    3D there are a number of builtin meshes for convenience, for example sphere, cube,
    cone, or cylinder. These are referenced by using the special identifiers, such as \c
    #Sphere, \c #Cube, or\c #Rectangle in the source property of a Model node. Besides the
    built-in primitives, a \c{.mesh} file can be specified. To generate \c{.mesh} files
    from FBX or glTF2 assets, the assets need to be processed using the \l{Balsam Asset
    Import Tool}. Below shows the code adding a blue sphere and a red flattened cylinder:

    \snippet intro/main.qml objects

    To add the meshes, we use two Model nodes, with \c #Sphere and \c #Cylinder as the
    \l{Model::source}{source} to load our built-in meshes. To give the model a color we
    need to first specify a material. In this case we use a \l PrincipledMaterial with a red
    and blue base color. There are three different materials available with different
    properties, namely PrincipledMaterial, SpecularGlossyMaterial and CustomMaterial, see \l{Qt
    Quick 3D - Principled Material Example} and \l{Programmable Materials, Effects,
    Geometry, and Texture data}. The mesh loaded by a \l Model can have multiple
    sub-meshes, and each sub-mesh needs to have a material specified. In the example only
    the built-in meshes are used, and those only have one sub-mesh each, and therefore it
    is sufficient to specify a single PrincipledMaterial in the
    \l{Model::materials}{materials} list.

    A \l Model is a \l Node, so it has an associated transformation. To apply a
    translation, we use the \c position property. It is also possible to rotate the model
    by setting the \c eulerRotation property. To make the cylinder look like a plate we
    set the \c scale property accordingly.

    \section1 Camera

    Then we define a camera, which specifies how the content of the 3D scene is projected
    onto a 2D surface. In this example, we use \l PerspectiveCamera which gives us a
    perspective projection. Orthographic projection is also possible through the
    OrthographicCamera type. The default orientation of the camera has its forward vector
    pointing along the negative Z axis and its up vector along the positive Y axis. The
    example moves the camera back to 300 on the Z axis. In addition, it is moved up an the
    Y axis a bit, and is rotated slightly around the X axis to look slightly downwards.

    \snippet intro/main.qml camera

    \section1 Lights

    The scene also needs a light source in order to be able to see the models in our
    scene. A DirectionalLight, which can be thought of as a distant sun shining from a
    certain direction, is added to the scene. There are two other light sources available,
    namely SpotLight and PointLight, see \l{Qt Quick 3D - Lights Example}.

    \snippet intro/main.qml light

    \section1 Animation

    Finally, we are also going to animate the sphere. We do this by applying a
    SequentialAnimation on the \c y component, moving the sphere up and down infinitely.

    \snippet intro/main.qml animation

    With all these parts working together we are able to render our 3D scene. This example
    touches only some of the basic capabilities of Qt Quick 3D. Visit the \l{Qt Quick 3D
    Examples and Tutorials}{examples} page for further examples.

*/