From 0e7ce66678e6f7e05b7354fb962dc100d74c745b Mon Sep 17 00:00:00 2001
From: Shyamnath Premnadh <Shyamnath.Premnadh@qt.io>
Date: Tue, 16 Apr 2024 14:28:52 +0200
Subject: Tooling: add pyside6-balsam

- Also add the relevant documentation

Pick-to: 6.7 6.6 6.5
Task-number: PYSIDE-2629
Change-Id: Ic2e7798a5f0ff7015cb87089dda2420ed6327ca2
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>
---
 sources/pyside-tools/CMakeLists.txt          |  3 +-
 sources/pyside-tools/pyside_tool.py          |  4 ++
 sources/pyside6/doc/tools/index.rst          | 16 +++++++-
 sources/pyside6/doc/tools/pyside6-balsam.rst | 59 ++++++++++++++++++++++++++++
 4 files changed, 80 insertions(+), 2 deletions(-)
 create mode 100644 sources/pyside6/doc/tools/pyside6-balsam.rst

(limited to 'sources')

diff --git a/sources/pyside-tools/CMakeLists.txt b/sources/pyside-tools/CMakeLists.txt
index 4f9d04354..308f7bbc7 100644
--- a/sources/pyside-tools/CMakeLists.txt
+++ b/sources/pyside-tools/CMakeLists.txt
@@ -45,7 +45,8 @@ else()
                         "${TOOLS_PATH}/qmllint${CMAKE_EXECUTABLE_SUFFIX}"
                         "${TOOLS_PATH}/qmlformat${CMAKE_EXECUTABLE_SUFFIX}"
                         "${TOOLS_PATH}/qmlls${CMAKE_EXECUTABLE_SUFFIX}"
-                        "${TOOLS_PATH}/qsb${CMAKE_EXECUTABLE_SUFFIX}")
+                        "${TOOLS_PATH}/qsb${CMAKE_EXECUTABLE_SUFFIX}"
+                        "${TOOLS_PATH}/balsam${CMAKE_EXECUTABLE_SUFFIX}")
 
         if (APPLE)
             list(APPEND directories "${TOOLS_PATH}/Assistant.app"
diff --git a/sources/pyside-tools/pyside_tool.py b/sources/pyside-tools/pyside_tool.py
index 64682e24d..32e0b917b 100644
--- a/sources/pyside-tools/pyside_tool.py
+++ b/sources/pyside-tools/pyside_tool.py
@@ -231,5 +231,9 @@ def qsb():
     qt_tool_wrapper("qsb", sys.argv[1:])
 
 
+def balsam():
+    qt_tool_wrapper("balsam", sys.argv[1:])
+
+
 if __name__ == "__main__":
     main()
diff --git a/sources/pyside6/doc/tools/index.rst b/sources/pyside6/doc/tools/index.rst
index b82e3fd71..900b2525a 100644
--- a/sources/pyside6/doc/tools/index.rst
+++ b/sources/pyside6/doc/tools/index.rst
@@ -187,5 +187,19 @@ Shader Tools
         :link: pyside6-qsb
         :link-type: ref
 
-        a command line tool provided by the Qt Shader Tools module to
+        a command-line tool provided by the Qt Shader Tools modules to
         generate and inspect .qsb files.
+
+Qt Quick 3D
+~~~~~~~~~~~
+
+.. grid:: 2
+    :gutter: 3 3 4 5
+
+    .. grid-item-card:: ``pyside6-balsam``
+        :link: pyside6-balsam
+        :link-type: ref
+
+        a command line tool that takes assets created in digital content
+        creation tools like Maya, 3ds Max or Blender and converts them into an
+        efficient runtime format for use with Qt Quick 3D.
diff --git a/sources/pyside6/doc/tools/pyside6-balsam.rst b/sources/pyside6/doc/tools/pyside6-balsam.rst
new file mode 100644
index 000000000..c6677f6a3
--- /dev/null
+++ b/sources/pyside6/doc/tools/pyside6-balsam.rst
@@ -0,0 +1,59 @@
+.. _pyside6-balsam:
+
+pyside6-balsam
+==============
+
+``pyside6-qsb`` is a tool that wraps the `balsam <Balsam Asset Import Tool>`_
+tool provided with Qt Quick 3D. The Balsam tool is a command line application
+that is part of Qt Quick 3D's asset conditioning pipeline. The purpose is to
+take assets created in digital content creation tools like `Maya`_, `3ds Max`_
+or `Blender`_ and converts them into an efficient runtime format for use with Qt
+Quick 3D. It is not possible, nor does it make sense to reference the
+interchange formats directly in applications because a large amount of
+resources are needed to parse and condition the content of the asset before it
+is usable for real-time rendering. Instead, the interchange formats can be
+converted via the Balsam tool into QML Components and resources like geometry
+and textures.
+
+
+For more information on how to use this tool, read Qt's documentation
+here: `Balsam Asset Import Tool`_.
+
+Usage
+-----
+
+.. code-block:: bash
+
+    pyside6-balsam [options] sourceFileName
+
+To convert a 3D asset contained in the file ``testModel.fbx`` with
+``pyside6-balsam`` the following command would be used:
+
+.. code-block:: bash
+
+    pyside6-balsam testModel.fbx
+
+This would generate the following files:
+
+* meshes/testModel.mesh
+* TestModel.qml
+
+Which can then be used in a Qt Quick 3D project by using that QML Component:
+
+.. code-block:: xml
+
+    import QtQuick3D 1.0
+
+    Scene {
+        Model {
+            source: "TestModel.qml"
+        }
+    }
+
+For other modes of operation, refer to the `Balsam Asset Import Tool`_.
+
+.. _`Balsam Asset Import Tool`: https://doc.qt.io/qt-6/qtquick3d-tool-balsam.html
+.. _Maya: https://www.autodesk.com/products/maya/overview
+.. _3ds Max: https://www.autodesk.com/products/3ds-max/overview
+.. _Blender: https://www.blender.org/
+
-- 
cgit v1.2.3