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

/*!
    \page studio-3d-model.html
    \previouspage studio-skeletal-components.html
    \nextpage studio-3d-materials.html

    \title 3D models

    The \l Components view features some built-in primitive 3D models. This allows
    you to add cubes, cones, cylinders, spheres, and planes (rectangles) to your scene.

    You can also use your own 3D models created with design tools. For more information,
    see \l {Importing 3D assets}.

    \image studio-3d-models.webp Various 3D models in the 3D view

    A model component loads mesh data from a file. Modify how the
    component is shaded by using materials. For more information, see
    \l {Materials and shaders} and \l {Material Editor and Browser}.

    \section1 Using a primitive 3D model

    To add a built-in primitive 3D model component to your UI, do one of the following:

    \list
      \li Drag a model component from \uicontrol Components >
      \uicontrol {Qt Quick 3D} to the \l {3D} view or to
      \l Navigator > \uicontrol {View3D} > \uicontrol Scene.
      \li Right-click in the \uicontrol 3D view and select
      \uicontrol Create > \uicontrol Primitives from the context menu.
    \endlist

    Double-clicking a 3D model in the \uicontrol 2D view opens the \uicontrol 3D view with
    the 3D model selected.

    \note If you can't find the model components in \uicontrol {Components}, add the
    \uicontrol QtQuick3D module to your project, as described in
    \l {Adding and Removing Modules}.

    \section1 Model properties

    To edit the 3D model properties, select the model and go to \l Properties >
    \uicontrol Model.

    \image studio-qtquick-3d-model.webp Model properties in the Properties view

    The following table introduces the available properties.

    \table
    \header
        \li Property
        \li Description
    \row
        \li Source
        \li Changes the model type. To add custom model types to the list,
            select \imageaddfile16px.
    \row
        \li Geometry
        \li Specifies a custom geometry for the model. If you use this property,
            the \uicontrol Source field must be empty.
    \row
        \li Materials
        \li Sets the material for the model. A model can consist of several sub-meshes,
            each of which can have its own material. To manage the materials:
            \list
                \li Select \imageplus to add materials to the list.
                \li Select \imageaddmaterial to edit the material.
                \li Select \imageclose to remove the material.
            \endlist
    \row
        \li Casts Shadows
        \li Enables the model to cast shadows on other models.
    \row
        \li Receives Shadows
        \li Enables the model to receive shadows.
    \row
        \li Casts Reflections
        \li Enables reflection probes to reflect the model.
    \row
        \li Receives Reflections
        \li Enables the model to receive reflections from the nearest reflection probe. The
            model must be inside at least one reflection probe to receive reflections.
    \row
        \li Is Pickable
        \li Enables ray cast-based picking for the model. To learn more about picking, see
            \l {Model::pickable} and \l {Qt Quick 3D - Picking example}.
    \row
        \li Used in Baked Lighting
        \li Makes the model contribute to baked lighting. For more information, see
            \l {Baked lightmaps}.
    \row
        \li Depth Bias
        \li Sets the depth bias of the model. This can prevent rendering issues and ensure
            that the shadows of the model are displayed correctly.
    \row
        \li LOD Bias
        \li Sets the level of detail bias. This adjusts how detailed textures appear at
            different distances.
    \endtable

    \section1 Tessellation properties in Qt 5

    The properties discussed in this section are only available if you selected
    \uicontrol {Qt 5} as the \uicontrol {Target Qt Version} when creating the
    project.

    \image studio-qtquick-3d-properties-tessellation.png Tessellation properties

    Tessellation refers to additional geometry that resembles tiling, which you
    can add to your model. To dynamically generate tessellation for the model,
    select \uicontrol Linear, \uicontrol Phong, or \uicontrol NPatch as the
    \uicontrol {Tessellation mode}. Tessellation is useful when using a
    displacement map with geometry, or to generate a smoother silhouette
    when zooming in.

    Specify an edge multiplier to the tessellation generator in the
    \uicontrol {Edge tessellation} field and an inner multiplier in
    the \uicontrol {Inner tessellation} field.

    To display a wireframe that highlights the additional geometry created by
    the tessellation generator, select the \uicontrol {Enable wireframe mode}
    check box.

*/
