/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of Qt 3D Studio.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!

\title Exporting from Blender
\page exporting-from-blender.html
\ingroup qt3dstudio-best-practices

It is possible to export meshes, lights, cameras, transform animations (scale/rotation/location),
UV layouts, pivot points, object hierarchy and material slots from Blender to Qt 3D Studio.

\section1 Exporting Models

\section2 Create Material Slots

Material slots needs to be created and assigned in Blender before the export. If this is not done,
one default material slot will be used for the object in Qt 3D Studio.

\note Only material slots that has a material and that are assign to a mesh on the exported
object, will be imported in Qt 3D Studio.

To create material slots, follow the steps below.

\list 1
  \li In the properties panel, select the material tab.
  \li Press the + to add a new material slots.
  \li Press the \uicontrol{New} button.
  \image 3D_Content/blender-export-1.png
  \li Repeat steps 2 to 4 for each material slot to create.
\endlist

By default, the first material slot will be assigned to the object

To assign a different material slot to the object, or to assign several material slots to the
same object, follow the steps below.

\list 1
  \li In edit mode, select the desired faces.
  (\e{Shift + Right Mouse Click} to multi select, \e{A} to select all faces).
  \li In the properties panel, select the material tab.
  \li In the material slots list, select the desired material slot.
  \li Press the \uicontrol{Assign} button to assign the selected material slot to selected faces.
  \image 3D_Content/blender-export-3.png
\endlist

In Studio, you will see all materials in the scene graph.
\image 3D_Content/blender-export-7.png

\section2 UV Unwrap Models

UV unwrapping your model will create a UV layout. Without a UV layout you will not be able to
render any textures on your model in Qt 3D Studio.

There are many different ways and techniques to unwrap 3D meshes. The most basic way to do it in
Blender is described below.

\list 1
  \li In edit mode, press \e A to select the whole mesh.
  \li Press \e U, then select \uicontrol{Unwrap} from the context menu.
  \image 3D_Content/blender-export-2.png
\endlist

\section2 Triangulate

\list 1
  \li In object mode, select the object.
  \li In the properties panel, select the modifiers tab.
  \li In the drop down list, select \uicontrol{Triangulate}.
  \image 3D_Content/blender-export-4.png
  \li Press \uicontrol{Apply}.
\endlist

\note When exporting as COLLADA, it is possible to do the triangulation in the actual export step.

\section2 Bake Actions for Animations

\note This step is necessary only if you are exporting animations that are using custom curves
or object constraints to control the animation.

Actions are data-blocks containing animation data. If you are exporting animations you need to
bake actions.

\list 1
  \li Press \e{space bar}.
  \li Type \e{bake actions}.
  \li Press \e Enter.
\endlist

\section2 Apply Location, Rotation and Scale

\note This should \b not be done when exporting animations.

Applying transform values will reset the object's location, rotation and scale values. Location and
rotation values will change to 0 while scale values will change to 1. The object itself will not
visually change.

\list 1
  \li In object mode, select the object.
  \li Press \e{Ctrl + A}.
  \li Select Location.
  \li From the check box in the panel, check also Rotation and Scale.
  \image 3D_Content/blender-export-5.png
\endlist

\note Applying Location will also reset the object's origin (pivot point).

\section1 Exporting Lights

You can export lights of any light type from Blender to use in Qt 3D Studio.

The following properties will be imported into Qt 3D Studio:
\list
  \li Position, rotation, scale
  \li Brightness
  \li Light color
  \li Cast shadows
\endlist

Light type will be imported (and converted if needed).

\table
  \header
    \li
      Light type in Blender
    \li
      Will import to Qt 3D Studio as...
  \row
    \li
      Point
    \li
      Point
  \row
    \li
      Area
    \li
      Area
  \row
    \li
      Sun
    \li
      Directional
  \row
    \li
      Spot
    \li
      Directional
  \row
    \li
      Hemi
    \li
      Directional
\endtable

\section1 Exporting Cameras

You can export perspective and orthographic cameras from Blender to use in Qt 3D Studio.

The following properties will be imported into Qt 3D Studio:
\list
  \li Position, rotation, scale
  \li Clipping start/end
  \li Focal Length (perspective camera only).
\endlist

\section1 Exporting COLLADA from Blender

\list 1
  \li From the file menu, select \uicontrol {File > Export > Collada (.dae)}.
  \li Ensure that \uicontrol Triangulation is checked on, unless you already have
  triangulated all meshes.
  \li Press the \uicontrol {Export COLLADA} button.
\endlist

\section1 Exporting FBX from Blender

In order to export as FBX, you will need to have an FBX export add-on installed and enabled
in Blender. With the default installation of Blender, the \c {Import-Export: FBX format} should be
installed. If you do not have the option to export as FBX avaialble, ensure that the add-on is
enabled by following the steps below:

\list 1
  \li
  From the file menu, select \uicontrol {File > User Preferences}.
  \li
  Select \uicontrol{Add-ons} from the top menu bar.
  \li
  Search for \e{fbx}.
  \li
  The add-on should now be visible, enable it by clicking the check box next to its name.
\endlist

\image enable-fbx-addon-blender.png

Next, to export as FBX, follow the steps below:

\list 1
  \li From the file menu, select \uicontrol {File > Export > FBX (.fbx)}.
  \li Under the \uicontrol Main tab, set \uicontrol Forward to \c{Y Forward} and \uicontrol Up
  to \c{Z Up}.
  \image blender-fbx-export-axis.png
  \li For animations, ensure that \uicontrol {Baked Animation} under the \uicontrol Animation
  tab is checked on.
  \image 3D_Content/blender-export-6.png
  \li Press the \uicontrol {Export FBX} button.
\endlist

*/