README and build options.

+ Use run-clang-tidy in format script.
+ Fix missing return in QtkWidgetManager.
+ Fix CI tag ref.
+ Add output when starting GUI to explain controls.

.github/workflows/build.yml

@@ -363,7 +363,7 @@ jobs:
 
   release:
     runs-on: ubuntu-latest
-    if: startsWith(github.event.workflow_run.head_branch, 'v')
+    if: startsWith(github.ref, 'refs/tags/')
     needs: [Qtk, Qtk-Library, Qtk-Plugins]
     steps:
       - name: Download Installer Artifact
@@ -378,8 +378,7 @@ jobs:
         id: create_release
         uses: softprops/action-gh-release@v1
         with:
-          tag_name: ${{ github.event.workflow_run.head_branch }}
-          name: Qtk ${{ github.event.workflow_run.head_branch }}
+          name: Qtk ${{ github.ref_name }}
           draft: true
           prerelease: false
           generate_release_notes: true

CMakeLists.txt

@@ -48,9 +48,20 @@ include(GNUInstallDirs)
 ################################################################################
 option(QTK_DEBUG "Enable debugger" OFF)
 option(QTK_SUBMODULES "Update external project (assimp) submodule" OFF)
-option(QTK_PLUGINS "Install Qtk plugins to Qt Creator path." OFF)
 option(QTK_EXAMPLE "Build the Qtk example desktop application" ON)
 option(QTK_CCACHE "Enable ccache" ON)
+# Install Qtk for use within Qt Creator projects only, instead of system-wide.
+option(QTK_PREFIX_QTCREATOR "Install Qtk to Qt Creator. Untested." OFF)
+# Option for bringing your own assimp installation; Otherwise not needed
+# + If assimp is available system-wide we can just set QTK_SUBMODULES OFF
+option(
+    QTK_ASSIMP_NEW_INTERFACE
+    "Use the assimp::assimp interface (WIN / OSX)"
+    OFF
+)
+
+# Qtk Component Options
+option(QTK_PLUGINS "Install Qtk plugins to Qt Designer path." OFF)
 # Options for qtk_gui
 option(QTK_GUI "Build the Qtk desktop application" ON)
 option(QTK_GUI_SCENE
@@ -61,17 +72,6 @@ if (QTK_CCACHE)
   set(CMAKE_CXX_COMPILER_LAUNCHER ccache)
 endif()
 
-# Install Qtk for use within Qt Creator projects only, instead of system-wide.
-option(QTK_PREFIX_QTCREATOR "Install Qtk to Qt Creator. Untested." OFF)
-
-# Option for bringing your own assimp installation; Otherwise not needed
-# + If assimp is available system-wide we can just set QTK_SUBMODULES OFF
-option(
-    QTK_ASSIMP_NEW_INTERFACE
-    "Use the assimp::assimp interface (WIN / OSX)"
-    OFF
-)
-
 if(QTK_DEBUG OR CMAKE_BUILD_TYPE MATCHES "^[Dd][Ee][Bb][Uu][Gg]$")
   set(QTK_DEBUG ON)
   set(CMAKE_BUILD_TYPE Debug)

README.md

@@ -3,11 +3,16 @@
 [![All Builds](https://github.com/shaunrd0/qtk/actions/workflows/all-builds.yml/badge.svg)](https://github.com/shaunrd0/qtk/actions/workflows/all-builds.yml)
 [![Linting](https://github.com/shaunrd0/qtk/actions/workflows/linting.yml/badge.svg)](https://github.com/shaunrd0/qtk/actions/workflows/linting.yml)
 
-Qtk is a Qt OpenGL graphics library that wraps some QOpenGL functionality in convenience classes
-that allow rendering geometry in 2D and 3D using custom GLSL shader programs.
-
-The Qtk desktop application provides a model loader using [Assimp](https://assimp.org/) within a Qt widget application.
+Qtk desktop application provides a model loader using [Assimp](https://assimp.org/) within a Qt widget application.
 You can fly around the scene using WASD while holding down the left or right mouse button.
+[QtkWidget](./src/designer-plugins/qtkwidget.h) is the primary QOpenGLWidget used to render the scene and handle input.
+
+The underlying shared library [libqtk](./src/qtk) wraps QOpenGL objects in convenience classes that leverage
+lower-level OpenGL APIs to handle the rendering process manually. Many of these classes offer
+ways to expand the low-level OpenGL logic within a Qt application without having to set up much scaffolding.
+
+The Qtk GUI is built using custom [Qt Designer plugins](). These can be installed to Qt Designer for
+use in other Qt applications, or built exclusively for Qtk. See
 
 Object names can be double-clicked in the tree view panel for quick camera navigation.
 Properties of the object, like shader code and translation / scale, can be viewed and modified in the side panel.
@@ -25,6 +30,12 @@ The small triangles floating near 3D models represent the light source being use
 These appear on models using phong, specular, and diffuse lighting techniques.
 
 The default scene contains basic examples like texture mapping to make a crate from basic cube geometry
+This scene is used in the following screenshots, and can be built locally by enabling
+the `QTK_GUI_SCENE` [Build Option](#build-options) described below. Because this scene
+uses large 3D model resources, this option is disabled by default.
+
+The default scene with this option disabled is empty, but comes with a default skybox.
+Models can be added to the scene by clicking and dragging an `.obj` into the scene view.
 
 ![](resources/screenshots/screen-texture.png)
 
@@ -38,7 +49,7 @@ And more advanced techniques like Phong lighting (ambient + diffuse + specular)
 
 ![](resources/screenshots/screen-phong.png)
 
-| Normal Mapping Disabled                              | Normal Mapping Enabled                                 | 
+| Normal Mapping Disabled                              | Normal Mapping Enabled                                 |
 |------------------------------------------------------|--------------------------------------------------------|
 | <img src="resources/screenshots/spartan-phong.png"/> | <img src="resources/screenshots/spartan-normals.png"/> |
 
@@ -78,11 +89,60 @@ your system, **version 6.6.0** or later.
 Be sure to take note of the Qt6 installation directory, as we will need it to
 correctly set our `CMAKE_PREFIX_PATH` in the next steps.
 
+#### Build Options
+
+Qtk is composed of three separate components.
+
+* The shared library libqtk provides classes that leverage QOpenGL functionality
+while still using lower-level OpenGL APIs to customize the rendering process.
+Many of these classes can be further expanded, such as [Qtk::Scene](./src/qtk/scene.h).
+This taget, `qtk_library` in cmake, is always selected to build and install as
+it is required by all other components in this project.
+* The Qtk desktop application is built using libqtk within a Qt application.
+This target, `qtk_gui` in cmake, is optional and can be controlled using the `QTK_GUI` option below.
+* The GUI for the Qtk desktop application is constructed using a custom set of Qt Designer widget plugins that are also built using libqtk.
+If `QTK_GUI` is disabled this target (`qtk_plugins`) is optional and can be controlled using the `QTK_PLUGINS` options below.
+
+
+| Name                     | Description                                                  | Default |
+|--------------------------|--------------------------------------------------------------|:--------|
+| QTK_DEBUG                | Enable debug mode.                                           | OFF     |
+| QTK_SUBMODULES           | Use git submodules to fetch assimp dependency.               | OFF     |
+| QTK_EXAMPLE              | Build the libqtk example desktop application.                | ON      |
+| QTK_CCACHE               | Enable CCACHE.                                               | ON      |
+| QTK_ASSIMP_NEW_INTERFACE | Use the assimp::assimp interface. Recommended for WIN / OSX. | OFF     |
+| QTK_PLUGINS*             | Install Qtk plugins to Qt Designer.                          | OFF     |
+| QTK_GUI                  | Build and install Qtk desktop application.                   | ON      |
+| QTK_GUI_SCENE            | Fetch external 3D model resources for example scene.         | OFF     |
+
+*The Qtk plugins are always built if QTK_GUI is enabled. Disabling this option
+with QTK_GUI set will not mark the plugins for installation if we do
+`cmake --install build/` without selecting a component. If both QTK_GUI and
+QTK_PLUGINS are unset, neither will be built.
+
 If you are building on **Windows / Mac**, consider setting
 the `-DQTK_ASSIMP_NEW_INTERFACE` cmake build option.
 
-If the build is configured with all options enabled, we can subsequently install
-individual components as needed with cmake.
+By default, the build will not initialize Assimp as a git submodule and build
+from source.
+We can turn this on by setting the `-DQTK_SUBMODULES=ON` flag when running
+CMake.
+Building using this option will fetch and build Assimp for us, but builds will
+take longer as a result.
+Using `-DQTK_SUBMODULES=ON` supports providing assimp on cross-platform builds (
+Windows / Mac / Linux) and may be easier to configure.
+
+```bash
+cmake -B build-all -DQTK_GUI=ON -DQTK_PLUGINS=ON -DQTK_EXAMPLE=ON -DQTK_SUBMODULES=ON -DCMAKE_PREFIX_PATH=$HOME/Qt/6.6.0/gcc_64
+```
+
+#### Qtk Components
+
+As described in [Build Options](#build-options), Qtk is composed of three separate components.
+Each component can be individually selected for building or installation.
+
+For this example we will configure the build with all options enabled.
+In the separate sections below we can install individual components with cmake.
 
 ```bash
 sudo apt update -y && sudo apt install libassimp-dev cmake build-essential git ccache libgl1-mesa-dev libglvnd-dev zlib1g-dev -y
@@ -94,44 +154,23 @@ cmake -B build-all -DQTK_GUI=ON -DQTK_PLUGINS=ON -DQTK_EXAMPLE=ON -DCMAKE_PREFIX
 cmake --build build-all/
 ````
 
-By default, the build will not initialize Assimp as a git submodule and build
-from source.
-We can turn this on by setting the `-DQTK_SUBMODULES=ON` flag when running
-CMake.
-Building using this option will fetch and build Assimp for us, but builds will
-take longer as a result.
-Using `-DQTK_SUBMODULES=ON` supports providing assimp on cross-platform builds (
-Windows / Mac / Linux) and may be easier
-to configure.
+Now that we have all the components fully built, the following sections will
+cover installing each component individually.
+If you want to uninstall a previously installed component, run the following command.
 
 ```bash
-cmake -B build-all -DQTK_GUI=ON -DQTK_PLUGINS=ON -DQTK_EXAMPLE=ON -DQTK_SUBMODULES=ON -DCMAKE_PREFIX_PATH=$HOME/Qt/6.6.0/gcc_64
+sudo xargs rm -v < install_manifest.txt
 ```
 
-#### Qtk GUI
+##### Qtk Library
 
-```bash
-cmake --build build-all/ --target qtk_gui -- -j $(nproc)
-# Install Qtk desktop application (output removed)
-# Installation prefix path must be absolute, since Qtk uses Qt deploy tools.
-cmake --install build-all/ --component qtk_gui --prefix=$(pwd)/install
-./install/bin/qtk_gui
-```
-
-If any errors are encountered loading plugins, we can debug plugin loading by
-setting the following environment variable -
-
-```bash
-QT_DEBUG_PLUGINS=1 ./install/bin/qtk_gui
-```
-
-#### Qtk Library
-
-Qtk provides a simple library for working with QOpenGL.
+Qtk provides a simple library for working with lower-level OpenGL to customize the rendering process.
 We can install this library on a system path or a custom path and then
 set `CMAKE_PREFIX_PATH` to point to this location when building an application
 using libqtk.
 
+Here we will install to the `/usr/local/` path.
+
 ```bash
 # Install libqtk only
 cmake --build build-all/ --target qtk_library -- -j $(nproc)
@@ -158,7 +197,26 @@ cmake --install build-all/ --component qtk_library --prefix=/usr/local
 -- Installing: /usr/local/include/qtk/transform3D.h
 ```
 
-#### Qtk Plugin Collection
+##### Qtk GUI
+
+The Qtk desktop application can be built and installed with the following commands.
+
+```bash
+cmake --build build-all/ --target qtk_gui -- -j $(nproc)
+# Install Qtk desktop application (output removed)
+# Installation prefix path must be absolute, since Qtk uses Qt deploy tools.
+cmake --install build-all/ --component qtk_gui --prefix=$(pwd)/install
+./install/bin/qtk_gui
+```
+
+If any errors are encountered loading plugins, we can debug plugin loading by
+setting the following environment variable -
+
+```bash
+QT_DEBUG_PLUGINS=1 ./install/bin/qtk_gui
+```
+
+##### Qtk Plugin Collection
 
 This project defines a collection of widget plugins for use with Qt Designer.
 These plugins were used to build the interface for the Qtk desktop application.
@@ -184,14 +242,7 @@ cmake --install build-all/ --component qtk_plugins
 -- Up-to-date: /home/shaun/Qt/6.6.0/gcc_64/../../Tools/QtCreator/lib/Qt/plugins/designer/libqtk_collection.so
 ```
 
-To uninstall after a previous installation, we can run the following command
-from the root of the repository.
-
-```bash
-xargs rm < build/install_manifest.txt
-```
-
-#### Qtk Example
+#### Example libqtk Application
 
 There is a simple example of using libqtk in the [example-app/](example-app)
 directory. The example can be built standalone using `find_package` or as a

src/designer-plugins/qtkwidget.cpp

@@ -98,6 +98,18 @@ void QtkWidget::initializeGL()
             this,
             SLOT(messageLogged(QOpenGLDebugMessage)));
     mDebugLogger->startLogging();
+    mConsole->sendLog(
+        "Object files such as .obj can be dragged into the scene to load new "
+        "models.",
+        DebugContext::Warn);
+    mConsole->sendLog("Click and hold LMB or RMB to move the camera with WASD.",
+                      DebugContext::Warn);
+    mConsole->sendLog(
+        "Click an object name in the side panel to view or modify properties.",
+        DebugContext::Warn);
+    mConsole->sendLog(
+        "Double click an object name to move the camera to it's position.",
+        DebugContext::Warn);
   }
 
   printContextInformation();

src/designer-plugins/qtkwidget.h

@@ -264,6 +264,7 @@ namespace Qtk
               << "[QtkWidgetManager " << this
               << " ] Failed to add a QtkWidget with the previously used name '"
               << name << "'";
+          return;
         }
         qDebug() << this << " Adding new QtkWidget named '" << name << "'";
         mQtkWidgets[name] = widget;

src/designer-plugins/treeview.cpp

@@ -19,6 +19,8 @@ Qtk::TreeView::TreeView(QWidget * parent) :
     QDockWidget(parent), ui(new Ui::TreeView)
 {
   ui->setupUi(this);
+  connect(
+      ui->treeWidget, &QTreeWidget::itemClicked, this, &TreeView::itemSelect);
   connect(ui->treeWidget,
           &QTreeWidget::itemDoubleClicked,
           this,
@@ -72,3 +74,10 @@ void Qtk::TreeView::itemFocus(QTreeWidgetItem * item, int column)
   // Emit signal from qtk widget for new object focus. Triggers GUI updates.
   emit QtkWidget::mWidgetManager.get_widget()->objectFocusChanged(name);
 }
+
+void Qtk::TreeView::itemSelect(QTreeWidgetItem * item, int column)
+{
+  // Emit signal from qtk widget for new object focus. Triggers GUI updates.
+  const QString & name = item->text(column);
+  emit QtkWidget::mWidgetManager.get_widget()->objectFocusChanged(name);
+}

src/designer-plugins/treeview.h

@@ -58,6 +58,16 @@ namespace Qtk
        */
       void itemFocus(QTreeWidgetItem * item, int column);
 
+      /**
+       * Set the object to show details for.
+       * Triggered by QTreeWidget::itemClicked signal.
+       *
+       * @param item The item that was clicked
+       * @param column The column of the item that was double clicked.
+       *    This param is currently not used but required for this signal.
+       */
+      void itemSelect(QTreeWidgetItem * item, int column);
+
     private:
       /*************************************************************************
        * Private Members

tools/format.sh

@@ -11,5 +11,6 @@ cmake -B build && cmake --build build -- -j $(nproc --ignore=1)
 
 # Run clang-tidy and clang-format
 SOURCES="src/**/*.cpp src/**/*.h example-app/*.cpp example-app/*.h"
-clang-tidy -p build/ --fix --config-file=.clang-tidy $SOURCES
+run-clang-tidy \
+    -p build/ -j $(nproc --ignore=1) -fix -config-file=.clang-tidy $SOURCES
 clang-format -i --style=file:.clang-format $SOURCES