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

/*!
    \example principledmaterial
    \examplecategory {3D}
    \ingroup quick3d-examples
    \title Qt Quick 3D - Principled Material Example
    \examplecategory {3D}
    \brief Demonstrates the use of Principled Material.
    \image principledmaterial-example.png

    This example serves as interactive documentation for the usage of \l PrincipledMaterial.
    Each property of \l PrincipledMaterial comes with some explanation of how it is used as
    well as a way to experiment with adjusting each property.

    \section1 Usage

    This example is split into two views, the interactive documentation and controls on the
    left, and the 3D Viewer on the right. The 3D Viewer is interactive allowing the camera
    to be orbited around the target model. To reset the focus on a particular model, just
    touch or click the model to focus on. The split between the two views is resizable by
    dragging bar in between the views.

    The example is separated into multiple sections which group the various features of
    \l PrincipledMaterial into manageable chunks. Each section can be accessed by clicking
    on the tabs at the top of the explanation area.

    \section1 SpecularGlossyMaterial

    In addition to demonstrating the Metalness/Roughness PBR workflow provided by
    \l PrincipledMaterial it is possible to switch to using the Specular/Glossy
    workflow which uses the \l SpecularGlossyMaterial. This can be done by a switch in
    the Basics section.

    \section1 Resource Loader

    The more complex nature of this example also gives an opportunity to demonstrate
    the usage of the \l ResourceLoader component. When a model is no longer visible in
    the scene any resources associated with the model will be released by Qt Quick 3D
    (assuming none of the resources are used by other models in the scene.) In this
    example it is possible to hide the curtain model, and by doing so 2 meshes and 2
    texture would be released from GPU memory. The next time the curtain is made visible
    though, these resources would need to be re-uploaded to the GPU. On some hardware this
    uploading can causes a momentary drop in frame-rate, so to mitigate this a
    \l ResourceLoader component is used inside of the BackgroundCurtain component.

    \snippet principledmaterial/BackgroundCurtain.qml resource loader

    Here both the mesh files and textures are registered with a ResourceLoader.
    ResourceLoader will assure that any registered resources will always be ready
    for use in GPU memory, so now regardless of the visibility of the
    BackgroundCurtain, its resources will be preserved.

    The ResouceLoaded can also be used to preload resources, as shown with the \b point
    and \b line meshes under the "Special" tab.

    \snippet principledmaterial/main.qml resource loader

    Here the \l QUrl's of the mesh files are listed directly. Resources do not
    have to be associated with a Model to be used by a \l ResourceLoader.
*/


