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

/*!
    \example skinning
    \ingroup quick3d-examples
    \title Qt Quick 3D - Simple Skinning Example
    \examplecategory {3D}
    \brief Demonstrates how to render a simple skinning animation in Qt Quick 3D.
    \image skinning.png
           {Two animated shapes showing skeletal deformation}

    Generally most \l{Vertex Skinning}{skin animations} will be designed by modeling tools, and Quick3D
    also supports glTF formats through the \l {Balsam Asset Import Tool}{Balsam importer}
    and \l{Qt Design Studio: Design Views}{Qt Design Studio}.
    This example shows how each property is used for the skin animation in Quick3D.

    \note All the data in this example come from \l
    {https://github.com/KhronosGroup/glTF-Tutorials/blob/master/gltfTutorial/gltfTutorial_020_Skins.md}
    {gfTF-Tutorial Skins}.

    \section1 Make a skinning geometry.

    To use custom geometry data, we will define a geometry having positions,
    joints, weights, and indexes.

    \snippet skinning/skingeometry.h geometry

    Each position is a vertex position and each vertex has 4 joints' indexes and
    corresponding weights.

    \section1 Set up skinned data in QML

    \section2  Position data and indexes

    We will draw 8 triangles with 10 vertexes. The table below shows the QML
    code and a visualization of the vertexes.

    \table
    \header
    \li QML Code
    \li Visualized
    \row
    \li
        \snippet skinning/SimpleSkinning.qml positions
        \snippet skinning/SimpleSkinning.qml triangles
    \li  \image vertexinfo.png "Vertex positions and geomery"
    \endtable

    \section2 Joints and weights data

    Every vertex needs to specify the indexes of the joints that should have an
    influence on it during the skinning process. For each vertex we store these
    indexes as 4D vectors (Qt limits the number of joints that may influence a
    vertex to 4). Our geometry will have just two joint nodes (0 and 1), but
    since we use 4D vectors we set the remaining two joint indexes and their
    weights to 0.

    \snippet skinning/SimpleSkinning.qml joints

    Corresponding weight values are as below.

    \snippet skinning/SimpleSkinning.qml weights

    \section2 Skeleton and Joint hierarchy

    For skinning, we add a \e skeleton property to the \l Model:

    \snippet skinning/SimpleSkinning.qml skeleton in Model
    \snippet skinning/SimpleSkinning.qml skeleton

    The two \l {Joint}{Joint}s are connected in a \l Skeleton. We will rotate \c
    joint1 45 degrees around the z-axis. The images below show how the joints
    are placed in the geometry and how the initial skeleton is oriented.

    \table
    \header
    \li Joints in the geometry
    \li Initial skeleton
    \row
    \li \image jointinfo.png "2 joints in the geometry"
    \li \image jointinfo2.png "Initial Skeleton"
    \endtable

    \section2 Placing models using inverseBindPoses

    Once a model has a valid \l {Model::skeleton}{skeleton}, it is necessary
    to define the \e {initial pose} of the skeleton. This defines the
    baseline for the skeletal animation: moving a joint from its initial
    position causes the model's vertexes to move according to the \c joints
    and \c weights tables. The geometry of each node is specified in a
    peculiar way: \l {Model::inverseBindPoses}{Model.inverseBindPoses} is set
    to the \e inverse of the matrix that would transform the joint to its
    initial position.  In order to move it to the center, we will simply set
    the same transform for both joints: a matrix that translates -0.5 along
    the x-axis and -1.0 along the y-axis.

    \table
    \header
    \li QML code
    \li Initial position
    \li Result
    \row
    \li \snippet skinning/SimpleSkinning.qml poses
    \li \image inverseBindPoses.png "Initial position"
    \li \image inverseBindPoses2.png "Transformed by InversebindPoses"
    \endtable

    \section1 Animate with Joint nodes

    Now that we have prepared a skinned object, we can animate it by changing
    the \l {Joint}{Joint}s' properties, specifically \e eulerRotation.

    \snippet skinning/SimpleSkinning.qml animation

    \section1 A more complete approach to skinning
    Skeleton is a resource but it's hierarchy and position is
    used for the Model's transformation.

    Instead of a \l Skeleton node, we can use the resource type \l Skin.
    Since the \l Skin type is not a spatial node in the scene, its position
    will not affect the model. A minimal working Skin node will normally
    consist of a node list, joints and an optional inverse bind matrices,
    inverseBindPoses.

    Using the \l Skin item the previous example can be written like this:

    \snippet skinning/SimpleSkinningNew.qml skin

    From the code snippet we can see that the \l Skin only has two lists,
    a joints and an inverseBindPoses, which differs from the \l Skeleton
    approach, as it does not have any hierarchy and just uses existing
    node's hierarchy.

    \snippet skinning/SimpleSkinningNew.qml skeleton
*/
