.clang-format

@@ -1,6 +1,6 @@
 ---
 BasedOnStyle: Google
-AlignAfterOpenBracket: AlwaysBreak
+AlignAfterOpenBracket: Align
 AlignArrayOfStructures: Left
 AlignConsecutiveAssignments: None
 AlignConsecutiveDeclarations: None
@@ -9,7 +9,6 @@ AlignEscapedNewlines: Left
 AlignOperands: Align
 AlignTrailingComments: true
 AllowAllArgumentsOnNextLine: true
-AllowAllParametersOfDeclarationOnNextLine: true
 AllowShortBlocksOnASingleLine: Never
 AllowShortCaseLabelsOnASingleLine: false
 AllowShortFunctionsOnASingleLine: Inline
@@ -21,8 +20,11 @@ InsertBraces: true
 IndentAccessModifiers: true
 EmptyLineAfterAccessModifier: Never
 EmptyLineBeforeAccessModifier: LogicalBlock
-BinPackArguments: true
-BinPackParameters: true
+BinPackArguments: false
+BinPackParameters: false
+AllowAllParametersOfDeclarationOnNextLine: true
+ExperimentalAutoDetectBinPacking: false
+BreakBeforeBraces: Linux
 BreakBeforeBinaryOperators: NonAssignment
 BreakBeforeTernaryOperators: true
 BreakConstructorInitializers: AfterColon
@@ -58,7 +60,7 @@ SpaceAfterTemplateKeyword: true
 SpaceBeforeAssignmentOperators: true
 SpaceBeforeCpp11BracedList: true
 SpaceBeforeCtorInitializerColon: true
-SpaceBeforeParens: Never
+SpaceBeforeParens: ControlStatementsExceptControlMacros
 SpaceBeforeRangeBasedForLoopColon: true
 SpacesBeforeTrailingComments: 2
 SpaceInEmptyParentheses: false

.clang-tidy

@@ -139,8 +139,149 @@ readability-redundant-smartptr-get,
 readability-redundant-string-cstr,
 readability-redundant-string-init,
 readability-simplify-subscript-expr,
-readability-static-accessed-through-instance,
 readability-static-definition-in-anonymous-namespace,
 readability-string-compare,
 readability-uniqueptr-delete-release,
-readability-use-anyofallof'
+readability-use-anyofallof'
+CheckOptions:
+  bugprone-argument-comment.CommentBoolLiterals: '0'
+  bugprone-argument-comment.CommentCharacterLiterals: '0'
+  bugprone-argument-comment.CommentFloatLiterals: '0'
+  bugprone-argument-comment.CommentIntegerLiterals: '0'
+  bugprone-argument-comment.CommentNullPtrs: '0'
+  bugprone-argument-comment.CommentStringLiterals: '0'
+  bugprone-argument-comment.CommentUserDefinedLiterals: '0'
+  bugprone-argument-comment.IgnoreSingleArgument: '0'
+  bugprone-argument-comment.StrictMode: '0'
+  bugprone-assert-side-effect.AssertMacros: assert,NSAssert,NSCAssert
+  bugprone-assert-side-effect.CheckFunctionCalls: 'false'
+  bugprone-assert-side-effect.IgnoredFunctions: __builtin_expect
+  bugprone-dangling-handle.HandleClasses: 'std::basic_string_view;std::experimental::basic_string_view'
+  bugprone-dynamic-static-initializers.HeaderFileExtensions: ';h;hh;hpp;hxx'
+  bugprone-lambda-function-name.IgnoreMacros: 'false'
+  bugprone-misplaced-widening-cast.CheckImplicitCasts: 'false'
+  bugprone-not-null-terminated-result.WantToUseSafeFunctions: 'true'
+  bugprone-reserved-identifier.AggressiveDependentMemberLookup: 'false'
+  bugprone-reserved-identifier.AllowedIdentifiers: ''
+  bugprone-reserved-identifier.Invert: 'false'
+  bugprone-sizeof-expression.WarnOnSizeOfCompareToConstant: 'true'
+  bugprone-sizeof-expression.WarnOnSizeOfConstant: 'true'
+  bugprone-sizeof-expression.WarnOnSizeOfIntegerExpression: 'false'
+  bugprone-sizeof-expression.WarnOnSizeOfPointerToAggregate: 'true'
+  bugprone-sizeof-expression.WarnOnSizeOfThis: 'true'
+  bugprone-string-constructor.LargeLengthThreshold: '8388608'
+  bugprone-string-constructor.StringNames: '::std::basic_string;::std::basic_string_view'
+  bugprone-string-constructor.WarnOnLargeLength: 'true'
+  bugprone-suspicious-enum-usage.StrictMode: 'false'
+  bugprone-suspicious-include.HeaderFileExtensions: ';h;hh;hpp;hxx'
+  bugprone-suspicious-include.ImplementationFileExtensions: 'c;cc;cpp;cxx'
+  bugprone-suspicious-missing-comma.MaxConcatenatedTokens: '5'
+  bugprone-suspicious-missing-comma.RatioThreshold: '0.200000'
+  bugprone-suspicious-missing-comma.SizeThreshold: '5'
+  bugprone-suspicious-string-compare.StringCompareLikeFunctions: ''
+  bugprone-suspicious-string-compare.WarnOnImplicitComparison: 'true'
+  bugprone-suspicious-string-compare.WarnOnLogicalNotComparison: 'false'
+  bugprone-too-small-loop-variable.MagnitudeBitsUpperLimit: '16'
+  bugprone-unhandled-self-assignment.WarnOnlyIfThisHasSuspiciousField: 'true'
+  bugprone-unused-return-value.AllowCastToVoid: 'false'
+  bugprone-unused-return-value.CheckedFunctions: '::std::async;::std::launder;::std::remove;::std::remove_if;::std::unique;::std::unique_ptr::release;::std::basic_string::empty;::std::vector::empty;::std::back_inserter;::std::distance;::std::find;::std::find_if;::std::inserter;::std::lower_bound;::std::make_pair;::std::map::count;::std::map::find;::std::map::lower_bound;::std::multimap::equal_range;::std::multimap::upper_bound;::std::set::count;::std::set::find;::std::setfill;::std::setprecision;::std::setw;::std::upper_bound;::std::vector::at;::bsearch;::ferror;::feof;::isalnum;::isalpha;::isblank;::iscntrl;::isdigit;::isgraph;::islower;::isprint;::ispunct;::isspace;::isupper;::iswalnum;::iswprint;::iswspace;::isxdigit;::memchr;::memcmp;::strcmp;::strcoll;::strncmp;::strpbrk;::strrchr;::strspn;::strstr;::wcscmp;::access;::bind;::connect;::difftime;::dlsym;::fnmatch;::getaddrinfo;::getopt;::htonl;::htons;::iconv_open;::inet_addr;::isascii;::isatty;::mmap;::newlocale;::openat;::pathconf;::pthread_equal;::pthread_getspecific;::pthread_mutex_trylock;::readdir;::readlink;::recvmsg;::regexec;::scandir;::semget;::setjmp;::shm_open;::shmget;::sigismember;::strcasecmp;::strsignal;::ttyname'
+  bugprone-unused-return-value.CheckedReturnTypes: '::std::error_code;::std::error_condition;::std::errc;::std::expected;::boost::system::error_code'
+  cert-dcl16-c.NewSuffixes: 'L;LL;LU;LLU'
+  cert-err33-c.AllowCastToVoid: 'true'
+  cert-err33-c.CheckedFunctions: '::aligned_alloc;::asctime_s;::at_quick_exit;::atexit;::bsearch;::bsearch_s;::btowc;::c16rtomb;::c32rtomb;::calloc;::clock;::cnd_broadcast;::cnd_init;::cnd_signal;::cnd_timedwait;::cnd_wait;::ctime_s;::fclose;::fflush;::fgetc;::fgetpos;::fgets;::fgetwc;::fopen;::fopen_s;::fprintf;::fprintf_s;::fputc;::fputs;::fputwc;::fputws;::fread;::freopen;::freopen_s;::fscanf;::fscanf_s;::fseek;::fsetpos;::ftell;::fwprintf;::fwprintf_s;::fwrite;::fwscanf;::fwscanf_s;::getc;::getchar;::getenv;::getenv_s;::gets_s;::getwc;::getwchar;::gmtime;::gmtime_s;::localtime;::localtime_s;::malloc;::mbrtoc16;::mbrtoc32;::mbsrtowcs;::mbsrtowcs_s;::mbstowcs;::mbstowcs_s;::memchr;::mktime;::mtx_init;::mtx_lock;::mtx_timedlock;::mtx_trylock;::mtx_unlock;::printf_s;::putc;::putwc;::raise;::realloc;::remove;::rename;::scanf;::scanf_s;::setlocale;::setvbuf;::signal;::snprintf;::snprintf_s;::sprintf;::sprintf_s;::sscanf;::sscanf_s;::strchr;::strerror_s;::strftime;::strpbrk;::strrchr;::strstr;::strtod;::strtof;::strtoimax;::strtok;::strtok_s;::strtol;::strtold;::strtoll;::strtoul;::strtoull;::strtoumax;::strxfrm;::swprintf;::swprintf_s;::swscanf;::swscanf_s;::thrd_create;::thrd_detach;::thrd_join;::thrd_sleep;::time;::timespec_get;::tmpfile;::tmpfile_s;::tmpnam;::tmpnam_s;::tss_create;::tss_get;::tss_set;::ungetc;::ungetwc;::vfprintf;::vfprintf_s;::vfscanf;::vfscanf_s;::vfwprintf;::vfwprintf_s;::vfwscanf;::vfwscanf_s;::vprintf_s;::vscanf;::vscanf_s;::vsnprintf;::vsnprintf_s;::vsprintf;::vsprintf_s;::vsscanf;::vsscanf_s;::vswprintf;::vswprintf_s;::vswscanf;::vswscanf_s;::vwprintf_s;::vwscanf;::vwscanf_s;::wcrtomb;::wcschr;::wcsftime;::wcspbrk;::wcsrchr;::wcsrtombs;::wcsrtombs_s;::wcsstr;::wcstod;::wcstof;::wcstoimax;::wcstok;::wcstok_s;::wcstol;::wcstold;::wcstoll;::wcstombs;::wcstombs_s;::wcstoul;::wcstoull;::wcstoumax;::wcsxfrm;::wctob;::wctrans;::wctype;::wmemchr;::wprintf_s;::wscanf;::wscanf_s;'
+  cert-msc51-cpp.DisallowedSeedTypes: 'time_t,std::time_t'
+  cert-oop54-cpp.WarnOnlyIfThisHasSuspiciousField: 'false'
+  cert-str34-c.CharTypdefsToIgnore: ''
+  cert-str34-c.DiagnoseSignedUnsignedCharComparisons: 'false'
+  cppcoreguidelines-non-private-member-variables-in-classes.IgnoreClassesWithAllMemberVariablesBeingPublic: 'true'
+  cppcoreguidelines-pro-type-member-init.IgnoreArrays: 'false'
+  cppcoreguidelines-pro-type-member-init.UseAssignment: 'false'
+  cppcoreguidelines-pro-type-static-cast-downcast.StrictMode: 'true'
+  google-readability-braces-around-statements.ShortStatementLines: '1'
+  google-readability-function-size.StatementThreshold: '800'
+  google-readability-namespace-comments.ShortNamespaceLines: '10'
+  google-readability-namespace-comments.SpacesBeforeComments: '2'
+  hicpp-multiway-paths-covered.WarnOnMissingElse: 'false'
+  llvm-else-after-return.WarnOnConditionVariables: 'false'
+  llvm-else-after-return.WarnOnUnfixable: 'false'
+  llvm-qualified-auto.AddConstToQualified: 'false'
+  misc-throw-by-value-catch-by-reference.CheckThrowTemporaries: 'true'
+  misc-throw-by-value-catch-by-reference.WarnOnLargeObjects: 'false'
+  misc-uniqueptr-reset-release.IncludeStyle: llvm
+  modernize-avoid-bind.PermissiveParameterList: 'false'
+  modernize-deprecated-headers.CheckHeaderFile: 'false'
+  modernize-loop-convert.IncludeStyle: llvm
+  modernize-loop-convert.MakeReverseRangeFunction: ''
+  modernize-loop-convert.MakeReverseRangeHeader: ''
+  modernize-loop-convert.MaxCopySize: '16'
+  modernize-loop-convert.MinConfidence: reasonable
+  modernize-loop-convert.NamingStyle: CamelCase
+  modernize-loop-convert.UseCxx20ReverseRanges: 'true'
+  modernize-make-shared.IgnoreDefaultInitialization: 'true'
+  modernize-make-shared.IgnoreMacros: 'true'
+  modernize-make-shared.IncludeStyle: llvm
+  modernize-make-shared.MakeSmartPtrFunction: 'std::make_shared'
+  modernize-make-shared.MakeSmartPtrFunctionHeader: '<memory>'
+  modernize-make-unique.IgnoreDefaultInitialization: 'true'
+  modernize-make-unique.IgnoreMacros: 'true'
+  modernize-make-unique.IncludeStyle: llvm
+  modernize-make-unique.MakeSmartPtrFunction: 'std::make_unique'
+  modernize-make-unique.MakeSmartPtrFunctionHeader: '<memory>'
+  modernize-pass-by-value.IncludeStyle: llvm
+  modernize-pass-by-value.ValuesOnly: 'false'
+  modernize-raw-string-literal.DelimiterStem: lit
+  modernize-raw-string-literal.ReplaceShorterLiterals: 'false'
+  modernize-replace-auto-ptr.IncludeStyle: llvm
+  modernize-replace-disallow-copy-and-assign-macro.MacroName: DISALLOW_COPY_AND_ASSIGN
+  modernize-replace-random-shuffle.IncludeStyle: llvm
+  modernize-use-auto.MinTypeNameLength: '5'
+  modernize-use-auto.RemoveStars: 'false'
+  modernize-use-bool-literals.IgnoreMacros: 'true'
+  modernize-use-emplace.ContainersWithPush: '::std::stack;::std::queue;::std::priority_queue'
+  modernize-use-emplace.ContainersWithPushBack: '::std::vector;::std::list;::std::deque'
+  modernize-use-emplace.ContainersWithPushFront: '::std::forward_list;::std::list;::std::deque'
+  modernize-use-emplace.EmplacyFunctions: 'vector::emplace_back;vector::emplace;deque::emplace;deque::emplace_front;deque::emplace_back;forward_list::emplace_after;forward_list::emplace_front;list::emplace;list::emplace_back;list::emplace_front;set::emplace;set::emplace_hint;map::emplace;map::emplace_hint;multiset::emplace;multiset::emplace_hint;multimap::emplace;multimap::emplace_hint;unordered_set::emplace;unordered_set::emplace_hint;unordered_map::emplace;unordered_map::emplace_hint;unordered_multiset::emplace;unordered_multiset::emplace_hint;unordered_multimap::emplace;unordered_multimap::emplace_hint;stack::emplace;queue::emplace;priority_queue::emplace'
+  modernize-use-emplace.IgnoreImplicitConstructors: 'false'
+  modernize-use-emplace.SmartPointers: '::std::shared_ptr;::std::unique_ptr;::std::auto_ptr;::std::weak_ptr'
+  modernize-use-emplace.TupleMakeFunctions: '::std::make_pair;::std::make_tuple'
+  modernize-use-emplace.TupleTypes: '::std::pair;::std::tuple'
+  modernize-use-equals-default.IgnoreMacros: 'true'
+  modernize-use-equals-delete.IgnoreMacros: 'true'
+  modernize-use-nodiscard.ReplacementString: '[[nodiscard]]'
+  modernize-use-noexcept.ReplacementString: ''
+  modernize-use-noexcept.UseNoexceptFalse: 'true'
+  modernize-use-nullptr.IgnoredTypes: 'std::_CmpUnspecifiedParam::;^std::__cmp_cat::__unspec'
+  modernize-use-nullptr.NullMacros: 'NULL'
+  modernize-use-override.AllowOverrideAndFinal: 'false'
+  modernize-use-override.FinalSpelling: final
+  modernize-use-override.IgnoreDestructors: 'true'
+  modernize-use-override.IgnoreTemplateInstantiations: 'false'
+  modernize-use-override.OverrideSpelling: override
+  modernize-use-transparent-functors.SafeMode: 'false'
+  performance-faster-string-find.StringLikeClasses: '::std::basic_string;::std::basic_string_view'
+  performance-for-range-copy.AllowedTypes: ''
+  performance-for-range-copy.WarnOnAllAutoCopies: 'false'
+  performance-inefficient-string-concatenation.StrictMode: 'false'
+  performance-inefficient-vector-operation.EnableProto: 'false'
+  performance-inefficient-vector-operation.VectorLikeClasses: '::std::vector'
+  performance-move-const-arg.CheckMoveToConstRef: 'true'
+  performance-move-const-arg.CheckTriviallyCopyableMove: 'true'
+  performance-no-automatic-move.AllowedTypes: ''
+  performance-type-promotion-in-math-fn.IncludeStyle: llvm
+  performance-unnecessary-copy-initialization.AllowedTypes: ''
+  performance-unnecessary-copy-initialization.ExcludedContainerTypes: ''
+  performance-unnecessary-value-param.AllowedTypes: ''
+  performance-unnecessary-value-param.IncludeStyle: llvm
+  portability-simd-intrinsics.Std: ''
+  portability-simd-intrinsics.Suggest: 'false'
+  readability-avoid-const-params-in-decls.IgnoreMacros: 'true'
+  readability-braces-around-statements.ShortStatementLines: '0'
+  readability-const-return-type.IgnoreMacros: 'true'
+  readability-container-size-empty.ExcludedComparisonTypes: '::std::array'
+  readability-inconsistent-declaration-parameter-name.IgnoreMacros: 'true'
+  readability-inconsistent-declaration-parameter-name.Strict: 'false'
+  readability-redundant-declaration.IgnoreMacros: 'true'
+  readability-redundant-smartptr-get.IgnoreMacros: 'true'
+  readability-redundant-string-init.StringNames: '::std::basic_string_view;::std::basic_string'
+  readability-simplify-subscript-expr.Types: '::std::basic_string;::std::basic_string_view;::std::vector;::std::array;::std::span'
+  readability-uniqueptr-delete-release.PreferResetCall: 'false'

.github/workflows/build.yml

@@ -1,15 +1,22 @@
-name: All Builds
+name: Build
 
 on:
   push:
+    branches:
+      - '*'
+    # Runs on tag so the release workflow can use its artifact.
+    tags:
+      - "v*"
   pull_request:
   workflow_dispatch:
 
+
 env:
   QT_VERSION: 6.6.0
 
 jobs:
   Qtk:
+    name: Qtk Applications
     env:
       CONFIG: -DQTK_SUBMODULES=ON -DQTK_DEBUG=OFF -DQTK_CCACHE=OFF -DQTK_GUI=ON -DQTK_PLUGINS=OFF -DQTK_EXAMPLE=ON
     strategy:
@@ -29,10 +36,10 @@ jobs:
 
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Install Qt
-        uses: jurplel/install-qt-action@v2
+        uses: jurplel/install-qt-action@v4
         with:
           version: ${{ env.QT_VERSION }}
 
@@ -82,7 +89,7 @@ jobs:
 
       - name: Upload package artifacts (DEB)
         if: matrix.os == 'ubuntu-latest'
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: qtk-gui-${{ matrix.os }}
           path: |
@@ -95,9 +102,19 @@ jobs:
           cd build
           cpack -C Release -G NSIS
 
+      - name: Upload logs on failure (WIN)
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: Build-Logs
+          path: |
+            D:\a\qtk\qtk\build\packages\_CPack_Packages\win64\NSIS\NSISOutput.log
+            D:\a\qtk\qtk\build\CMakeFiles\CMakeOutput.log
+            D:\a\qtk\qtk\build\CMakeFiles\CMakeError.log
+
       - name: Upload package artifacts (WIN)
         if: matrix.os == 'windows-latest'
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: qtk-gui-${{ matrix.os }}
           path: |
@@ -112,16 +129,16 @@ jobs:
 
       - name: Upload package artifacts (OSX)
         if: matrix.os == 'macos-latest'
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: qtk-gui-${{ matrix.os }}
           path: |
             build/packages/*.tar.gz
 
       - name: Upload Qtk install directory
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
-          name: qtk-gui-${{ matrix.os }}-install
+          name: qtk-gui-${{ matrix.os }}-archive
           path: install/*
 
 # TODO: Enable after trimming resources.
@@ -132,7 +149,7 @@ jobs:
 #          cmake --build build/ --target package_source
 #
 #      - name: Upload package artifacts
-#        uses: actions/upload-artifact@v3
+#        uses: actions/upload-artifact@v4
 #        with:
 #          name: qtk-${{ matrix.os }}-packages
 #          path: |
@@ -140,6 +157,7 @@ jobs:
 #            !build/packages/_CPack_Packages/*
 
   Qtk-Library:
+    name: Qtk library
     env:
       CONFIG: -DQTK_SUBMODULES=ON -DQTK_DEBUG=OFF -DQTK_CCACHE=OFF -DQTK_GUI=OFF -DQTK_PLUGINS=OFF -DQTK_EXAMPLE=OFF
     strategy:
@@ -159,10 +177,10 @@ jobs:
 
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Install Qt
-        uses: jurplel/install-qt-action@v2
+        uses: jurplel/install-qt-action@v4
         with:
           version: ${{ env.QT_VERSION }}
 
@@ -180,13 +198,13 @@ jobs:
 
       - name: Build Qtk Library
         shell: bash
-        run: cmake --build build/ --config Release --target qtk_library -- ${{ matrix.flags }}
+        run: cmake --build build/ --config Release --target qtk -- ${{ matrix.flags }}
 
       # Packaging
 
       - name: Install Qtk Library
         shell: bash
-        run: cmake --install build/ --config Release --prefix=$(pwd)/install --component qtk_library
+        run: cmake --install build/ --config Release --prefix=$(pwd)/install --component qtk
 
       - name: Package Qtk Library
         shell: bash
@@ -201,7 +219,7 @@ jobs:
 
       - name: Upload package artifacts (DEB)
         if: matrix.os == 'ubuntu-latest'
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: libqtk-${{ matrix.os }}
           path: |
@@ -214,11 +232,21 @@ jobs:
           cd build
           cpack -C Release -G NSIS
 
+      - name: Upload logs on failure (WIN)
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: Build-Logs
+          path: |
+            D:\a\qtk\qtk\build\packages\_CPack_Packages\win64\NSIS\NSISOutput.log
+            D:\a\qtk\qtk\build\CMakeFiles\CMakeOutput.log
+            D:\a\qtk\qtk\build\CMakeFiles\CMakeError.log
+
       - name: Upload package artifacts (WIN)
         if: matrix.os == 'windows-latest'
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
-          name: qtk-${{ matrix.os }}
+          name: libqtk-${{ matrix.os }}
           path: |
             build/packages/*.exe
 
@@ -231,20 +259,21 @@ jobs:
 
       - name: Upload package artifacts (OSX)
         if: matrix.os == 'macos-latest'
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
-          name: qtk-${{ matrix.os }}
+          name: libqtk-${{ matrix.os }}
           path: |
             build/packages/*.tar.gz
 
       - name: Upload libqtk install
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         if: always()
         with:
-          name: libqtk-${{ matrix.os }}-install
+          name: libqtk-${{ matrix.os }}-archive
           path: install/*
 
   Qtk-Plugins:
+    name: Qtk Qt Designer Plugins
     env:
       CONFIG: -DQTK_SUBMODULES=ON -DQTK_DEBUG=OFF -DQTK_CCACHE=OFF -DQTK_GUI=OFF -DQTK_PLUGINS=ON -DQTK_EXAMPLE=OFF
     strategy:
@@ -264,10 +293,10 @@ jobs:
 
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Install Qt
-        uses: jurplel/install-qt-action@v2
+        uses: jurplel/install-qt-action@v4
         with:
           version: ${{ env.QT_VERSION }}
 
@@ -292,6 +321,7 @@ jobs:
         run: cmake --install build/ --config Release --component qtk_plugins
 
   Qtk-Assimp-Targets:
+    name: Qtk Assimp Platform Targets
     strategy:
       fail-fast: false
       matrix:
@@ -304,10 +334,10 @@ jobs:
 
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Install Qt
-        uses: jurplel/install-qt-action@v2
+        uses: jurplel/install-qt-action@v4
         with:
           version: ${{ env.QT_VERSION }}
 
@@ -330,3 +360,29 @@ jobs:
       - name: Build Qtk
         shell: bash
         run: cmake --build build/ --config Release
+
+  release:
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/')
+    needs: [Qtk, Qtk-Library, Qtk-Plugins]
+    steps:
+      - name: Download Installer Artifact
+        uses: actions/download-artifact@v4
+        with:
+          path: |
+            build/packages/*
+            install/*
+
+      - name: Create GitHub Release
+        id: create_release
+        uses: softprops/action-gh-release@v1
+        with:
+          name: Qtk ${{ github.ref_name }}
+          draft: true
+          prerelease: false
+          generate_release_notes: true
+          files: |
+            build/packages/*
+            install/*
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/linting.yml

@@ -9,10 +9,10 @@ jobs:
   Tidy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Install Qt
-        uses: jurplel/install-qt-action@v2
+        uses: jurplel/install-qt-action@v4
         with:
           version: '6.5.0'
 
@@ -22,7 +22,7 @@ jobs:
       - name: Build Qtk
         run: |
           cmake -B build -DQTK_SUBMODULES=OFF -DQTK_CCACHE=OFF -DQTK_PLUGINS=OFF -DQTK_GUI=ON
-          cmake --build build --target qtk_gui -- -j $(nproc)
+          cmake --build build --target qtk_gui qtk_example -- -j $(nproc)
 
       - uses: cpp-linter/cpp-linter-action@v2
         id: linter
@@ -30,7 +30,7 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
           # Use clang-tools 14
-          version: '14'
+          version: '18'
           # Don't use clang-format with this action
           # + Set to `file` to use .clang-format (Qtk formats with clang 15)
           style: ''
@@ -57,12 +57,12 @@ jobs:
       matrix:
         path:
           - 'src'
-          - 'app'
+          - 'example-app'
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: clang-format Check
         uses: jidicula/clang-format-action@v4.9.0
         with:
-          clang-format-version: '15'
+          clang-format-version: '18'
           check-path: ${{ matrix.path }}

.gitignore

@@ -5,7 +5,7 @@
 **/.vscode/**
 
 # CMake build files
-**/cmake-build-debug/**
+**/cmake-build-*/**
 **/build/**
 install
 

CMakeLists.txt

@@ -2,9 +2,9 @@
 ## Project for working with OpenGL and Qt6 widgets                            ##
 ##                                                                            ##
 ## Author: Shaun Reed | Contact: shaunrd0@gmail.com | URL: www.shaunreed.com  ##
-## All Content (c) 2023 Shaun Reed, all rights reserved                       ##
+## All Content (c) 2025 Shaun Reed, all rights reserved                       ##
 ################################################################################
-cmake_minimum_required(VERSION 3.23)
+cmake_minimum_required(VERSION 3.28)
 
 ################################################################################
 # Constants
@@ -18,6 +18,7 @@ set(CMAKE_CXX_STANDARD_REQUIRED ON)
 set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 set(CMAKE_MACOSX_BUNDLE ON)
 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
+set(CMAKE_AUTORCC_OPTIONS --binary)
 
 if(WIN32)
   set(CMAKE_COMPILE_WARNING_AS_ERROR OFF)
@@ -30,7 +31,7 @@ add_compile_options(-fPIC)
 ################################################################################
 project(
     #[[NAME]]   Qtk
-    VERSION     0.2
+    VERSION     0.3
     DESCRIPTION "Qt OpenGL library and desktop application."
     LANGUAGES   CXX C
 )
@@ -47,18 +48,10 @@ include(GNUInstallDirs)
 ################################################################################
 option(QTK_DEBUG "Enable debugger" OFF)
 option(QTK_SUBMODULES "Update external project (assimp) submodule" OFF)
-option(QTK_GUI "Build the Qtk desktop application" ON)
-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)
-
-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(
@@ -67,6 +60,18 @@ option(
     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
+    "Fetch model resources and build the GUI with an example scene." OFF
+)
+
+if (QTK_CCACHE)
+  set(CMAKE_CXX_COMPILER_LAUNCHER ccache)
+endif()
+
 if(QTK_DEBUG OR CMAKE_BUILD_TYPE MATCHES "^[Dd][Ee][Bb][Uu][Gg]$")
   set(QTK_DEBUG ON)
   set(CMAKE_BUILD_TYPE Debug)
@@ -79,10 +84,12 @@ endif()
 set(QT_INSTALL_DIR "$ENV{HOME}/Qt/6.5.0/gcc_64/lib/cmake" CACHE PATH "Path to Qt6 install.")
 if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
   set(CMAKE_INSTALL_PREFIX  "${CMAKE_BINARY_DIR}/install")
-endif ()
+endif()
 
 set(QTK_RESOURCES "${CMAKE_SOURCE_DIR}/resources")
 set(QTK_OSX_ICONS ${CMAKE_SOURCE_DIR}/resources/icons/osx/kilroy.icns)
+string(TIMESTAMP YEAR "%Y")
+set(QTK_COPYRIGHT "All Content © 2021-${YEAR} Shaun Reed, all rights reserved.")
 
 # Point CMAKE_PREFIX_PATH to Qt6 install directory
 # If Qtk is built within Qt Creator this is not required.
@@ -182,8 +189,8 @@ endif()
 add_subdirectory(src)
 
 if(QTK_EXAMPLE)
-  # Create a namespaced alias for linking with qtk_library in the example.
-  add_library(${PROJECT_NAME}::qtk_library ALIAS qtk_library)
+  # Create a namespaced alias for linking with libqtk in the example.
+  add_library(${PROJECT_NAME}::qtk ALIAS qtk)
   add_subdirectory(example-app EXCLUDE_FROM_ALL)
 endif()
 
@@ -198,3 +205,25 @@ foreach(VAR_NAME IN LISTS VAR_NAMES VAR_PATHS)
     message(STATUS "[Qtk] ${VAR_NAME}=${${VAR_NAME}}")
   endif()
 endforeach()
+message(STATUS "[Qtk] Installation prefix: ${CMAKE_INSTALL_PREFIX}")
+message(STATUS "[Qtk] Found Qt6: ${Qt6Core_VERSION}")
+
+# qt_generate_deploy_app_script is supported on Linux in QtCore >= 6.5.0.
+# qt_generate_deploy_app_script supports Windows and OSX in QtCore >= 6.3.
+# https://doc.qt.io/qt-6.5/qt-generate-deploy-app-script.html
+# https://doc.qt.io/archives/qt-6.4/qt-generate-deploy-app-script.html
+# The application can still build and run, we just can't install.
+if(QTK_GUI OR QTK_EXAMPLE)
+  if(UNIX AND NOT APPLE)
+    # Ubuntu 24.04 provides QtCore 6.4.2 in qt-base-dev.
+    # This version of qt_generate_deploy_app_script does not support Linux.
+    if (Qt6_VERSION VERSION_LESS "6.5.0")
+      message(WARNING "[Qtk] Installation is only supported on Qt >=6.5.\n")
+    endif()
+  elseif(APPLE OR WIN32)
+    # Predates qt_generate_deploy_app_script.
+    if (Qt6_VERSION VERSION_LESS "6.3.0")
+      message(WARNING "[Qtk] Installation is only supported on Qt >=6.5.\n")
+    endif()
+  endif()
+endif()

README.md

@@ -1,69 +1,135 @@
 # Qtk
 
-[![All Builds](https://github.com/shaunrd0/qtk/actions/workflows/all-builds.yml/badge.svg)](https://github.com/shaunrd0/qtk/actions/workflows/all-builds.yml)
+[![All Builds](https://github.com/shaunrd0/qtk/actions/workflows/all-builds.yml/badge.svg)](https://github.com/shaunrd0/qtk/actions/workflows/build.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 created primarily for my own learning
-purposes. The library 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.
+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 long-term goal for this project is to create a tool that I can use to
-practice shader coding or graphics programming techniques. In doing this I hope
-to also learn more about the Qt UI framework, and the CMake build system.
+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](https://doc.qt.io/qt-6/designer-creating-custom-widgets.html). These can be installed to Qt Designer for
+use in other Qt applications, or built exclusively for Qtk. See [Build Options](#build-options) for more details.
+
+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.
+
+![](resources/screenshots/screen.png)
+
+All side panels and toolbars are dockable widgets that can be popped out
+and reorganized as needed. Panels can also be stacked to create a docked widget with
+tabs. The central widget that provides the camera view into the scene cannot be
+detached from the main window in this way.
+
+![](resources/screenshots/screen-1.png)
+
+The small triangles floating near 3D models represent the light source being used for the shader.
+These appear on models using phong, specular, and diffuse lighting techniques.
+
+The example scene contains basic examples like texture mapping to make a crate from simple 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)
+
+Examples of Ambient, Diffuse, and Specular GLSL shaders.
+
+| Ambient                                               | Diffuse                                               | Specular                                               |
+|-------------------------------------------------------|-------------------------------------------------------|--------------------------------------------------------|
+| <img src="resources/screenshots/screen-ambient.png"/> | <img src="resources/screenshots/screen-diffuse.png"/> | <img src="resources/screenshots/screen-specular.png"/> |
+
+And more advanced techniques like Phong lighting (ambient + diffuse + specular) and normal mapping.
+
+![](resources/screenshots/screen-phong.png)
+
+| Normal Mapping Disabled                              | Normal Mapping Enabled                                 |
+|------------------------------------------------------|--------------------------------------------------------|
+| <img src="resources/screenshots/spartan-phong.png"/> | <img src="resources/screenshots/spartan-normals.png"/> |
+
+See the `View` toolbar menu to enable debug console widgets for open scenes or reopen previously closed panels.
 
 Key features that are planned:
 
-* Runtime loading of `.obj` or similar 3D models.
-* Drag-and-drop interaction for adding objects to the scene.
-* Runtime reloading of modified GLSL shaders attached to objects within scenes.
-* Multiple views of a scene at one time.
-* Camera control modes such as panning, orbiting, or following objects.
-* Save / load for scene data. The current inheritance model is temporary.
-* Basic text editor for quickly modifying shaders attached to objects.
-* Shader / object properties panel to modify related settings.
-* Reduce size of application resources and git references.
+- [x] Runtime loading of `.obj` or similar 3D models.
+- [x] Drag-and-drop interaction for adding objects to the scene.
+- [x] Shader / object properties panel to modify related settings.
+- [x] Reduce size of application resources and git references.
+- [ ] Runtime reloading of modified GLSL shaders attached to objects within scenes.
+- [ ] Multiple views of a scene at one time.
+- [ ] Camera control modes such as panning, orbiting, or following objects.
+- [ ] Save / load scene data. The current model requires writing C++ code.
+- [ ] Basic text editor for quickly modifying shaders attached to objects.
 
-The Qtk desktop application provides a model loader
-using [Assimp](https://assimp.org/) within a Qt widget application.
-
-For examples of using the Qtk API, see the `example-app` project in the root of
-this repository.
+For examples of using libqtk, see the [example-app](./example-app)
+project in the root of this repository.
 
 To get textures loading on models look
 into [material files](http://www.paulbourke.net/dataformats/mtl/)
-and see some examples in the `resources/models/` directory.
+and see some examples at [qtk-resources/resources/models](https://git.shaunreed.com/shaunrd0/qtk-resources/src/branch/master/models).
 
 ### Source Builds
 
 Qtk was developed and tested using CLion
 and [Qt Creator](https://github.com/qt-creator/qt-creator).
-Simply open the root `CMakeLists.txt` with either of these editors and
-configurations will be loaded.
+Simply open the root `CMakeLists.txt` with either of these editors and default
+configurations will be loaded. To simplify providing Qt to the build, Qt Creator
+is the recommended option.
 
-This project has been ported to **Qt 6.6.0**, which is not yet available in
-Ubuntu apt repositories.
-To run this project, you will *need* to
-install [Qt6 Open Source Binaries](https://www.qt.io/download-qt-installer) for
-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.
+If you have manually installed [Qt6 Open Source Binaries](https://www.qt.io/download-qt-installer)
+for your system, be sure to correctly set your `CMAKE_PREFIX_PATH` in the next steps.
+On Ubuntu 24.04 the default installation directory to use for this path using Qt 6.5.0 is `$HOME/Qt/6.5.0/gcc_64/lib/cmake`.
+
+The Ubuntu apt repositories contain all the packages we need to build all targets.
+To build Qtk desktop application with the scene in the screenshots below run the following commands.
+
+```bash
+sudo apt update && sudo apt install cmake build-essential git ccache libxkbcommon-dev libassimp-dev qt6-base-dev qt6-tools-dev
+cmake -DQTK_GUI_SCENE=ON -B build
+cmake --build build
+./build/bin/qtk_gui
+```
+
+#### Build Options
+
+Qtk is composed of three separate components.
+
+* The shared library [libqtk](./src/qtk) 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` in cmake, is always selected to build and install as
+it is required by all other components in this project.
+* The [Qtk desktop application](./src/app) 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](./src/designer-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.
-
-```bash
-sudo apt update -y && sudo apt install libassimp-dev cmake build-essential git ccache libgl1-mesa-dev libglvnd-dev zlib1g-dev -y
-git clone https://github.com/shaunrd0/qtk
-cd qtk
-# Configure the build with all components enabled
-cmake -B build-all -DQTK_GUI=ON -DQTK_PLUGINS=ON -DQTK_EXAMPLE=ON -DCMAKE_PREFIX_PATH=$HOME/Qt/6.6.0/gcc_64
-# Build all targets
-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
@@ -71,47 +137,57 @@ 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.
+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 GUI
+#### 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
-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
-```
+sudo apt update -y && sudo apt install cmake build-essential git ccache libxkbcommon-dev libassimp-dev qt6-base-dev qt6-tools-dev -y
+git clone https://github.com/shaunrd0/qtk
+cd qtk
+# Configure the build with all components enabled
+cmake -B build-all -DQTK_GUI=ON -DQTK_PLUGINS=ON -DQTK_EXAMPLE=ON -DCMAKE_PREFIX_PATH=$HOME/Qt/6.6.0/gcc_64
+# Build all targets
+cmake --build build-all/
+````
 
-If any errors are encountered loading plugins, we can debug plugin loading by
-setting the following environment variable -
+Now that we have all the components fully built, the following sections will
+install each component individually.
+If you want to uninstall previously installed components, run the following command.
 
 ```bash
-QT_DEBUG_PLUGINS=1 ./install/bin/qtk_gui
+sudo xargs rm -v < install_manifest.txt
 ```
 
-#### Qtk Library
+##### Qtk Library
 
-Qtk provides a simple library for working with QOpenGL.
+Shared libqtk 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)
-cmake --install build-all/ --component qtk_library --prefix=/usr/local
+cmake --build build-all/ --target qtk -- -j $(nproc)
+cmake --install build-all/ --component qtk --prefix=/usr/local
 -- Install configuration: "Release"
 -- Installing: /usr/local/lib/cmake/Qtk/QtkConfig.cmake
 -- Installing: /usr/local/lib/cmake/Qtk/QtkConfigVersion.cmake
 -- Installing: /usr/local/lib/cmake/Qtk/QtkTargets.cmake
 -- Installing: /usr/local/lib/cmake/Qtk/QtkTargets-release.cmake
--- Installing: /usr/local/lib/static/libqtk_library.a
+-- Installing: /usr/local/lib/static/libqtk.a
 -- Installing: /usr/local/include/qtk/camera3d.h
 -- Installing: /usr/local/include/qtk/input.h
 -- Installing: /usr/local/include/qtk/meshrenderer.h
@@ -128,7 +204,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.
@@ -149,19 +244,12 @@ cmake --build build-all/ --target qtk_plugins -- -j $(nproc)
 # The path here should be initialized during build configuration, so no need for --prefix
 cmake --install build-all/ --component qtk_plugins
 -- Install configuration: "Release"
--- Up-to-date: /home/shaun/Qt/6.6.0/gcc_64/../../Tools/QtCreator/lib/Qt/lib/libqtk_library.a
+-- Up-to-date: /home/shaun/Qt/6.6.0/gcc_64/../../Tools/QtCreator/lib/Qt/lib/libqtk.a
 -- Up-to-date: /home/shaun/Qt/6.6.0/gcc_64/../../Tools/QtCreator/lib/Qt/lib/libqtk_plugin_library.a
 -- 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
@@ -177,55 +265,29 @@ cmake --install build-all/ --component qtk_example --prefix=install
 See the README in the [example-app/](example-app) subdirectory for instructions
 on standalone builds.
 
-### Controls
-
-You can fly around the scene if you hold the right mouse button and use WASD.
-If you see a small triangle floating by a model it represents the light source
-that is being used for the shader rendering the model. These appear on models
-using phong, specular, and diffuse lighting techniques.
-
-Object names can be double-clicked in the tree view panel for quick camera
-navigation. All panels and toolbars are dockable widgets that can be popped out
-and reorganized as needed. Panels can be stacked to create a docked widget with
-tabs. The central widget that provides the camera view into the scene cannot be
-detached from the main window in this way. See the `View` menu to enable debug
-console widgets for open scenes or reopen previously closed panels.
-
-![](resources/screenshot.png)
-
-Spartan with no normals -
-
-![](resources/spartan-specular.png)
-
-Spartan with normals -
-
-![](resources/spartan-normals.png)
-
 #### Development
 
-This project uses version `15.0.5` of `clang-format`.
-Before merging any branch we should run `clang-tidy` followed by `clang-format`.
+This project is using `clang-format` version `>=15.0.5`.
+On Ubuntu 24.04, clang-format 18 is available to install in apt repositories.
 
 ```bash
-git clone git@github.com:llvm/llvm-project.git -b llvmorg-15.0.5
-cd llvm-project
-cmake -B build -DLLVM_ENABLE_PROJECTS=clang -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi" -DCMAKE_BUILD_TYPE=Release -G "Unix Makefiles" llvm
-cmake --build build -j $(nproc --ignore=2)
-sudo cmake --build build -j $(nproc --ignore=2) --target install
+sudo apt install clang-format clang-tidy
 ```
 
-If the `clang-format` version is any earlier than `15.0.0`,
-running `clang-format` will fail because this project uses configuration options
-made available since `15.0.0`.
+If `clang-format --version` is any earlier than `15.0.0`, running `clang-format` will fail because this project uses configuration options made available since `15.0.0`.
 
 ```bash
 clang-format --version
-clang-format version 15.0.5 (git@github.com:llvm/llvm-project.git 154e88af7ec97d9b9f389e55d45bf07108a9a097)
+Ubuntu clang-format version 18.1.3 (1ubuntu1)
 ```
 
 CLion has integration for IDE code reformatting actions with `clang-format`.
-If you're using CLion, the `.clang-format` configuration will be picked up by
-CLion automatically.
+If you're using CLion, the `.clang-format` configuration will be picked up by CLion automatically.
+
+This repository provides the [`tools/format.sh`](./tools/format.sh) helper script to run `clang-tidy` and `clang-format` on Ubuntu 24.04.
+Running the script will build Qtk, so it's important to ensure you can manually build from source first.
+
+If you'd still like to run these tools manually, see the instructions below.
 
 `clang-tidy` can be run with the following commands.
 
@@ -234,14 +296,18 @@ CLion automatically.
 cd qtk
 # Build
 cmake -B build && cmake --build build -- -j $(nproc)
-clang-tidy -p build/ --fix --config-file=.clang-tidy src/*.cpp src/*.h app/*.cpp app/*.h
+```
+
+```bash
+export SOURCES=src/**/*.cpp src/**/*.h example-app/*.cpp example-app/*.h
+run-clang-tidy -p build/ -j $(nproc --ignore=1) -fix -config-file=.clang-tidy $SOURCES
 ```
 
 Last we need to run `clang-format`, this can be done with the command directly.
 This will reformat all the code in the repository.
 
 ```bash
-clang-format -i --style=file:.clang-format src/app/*.cpp src/app/*.h src/qtk/*.cpp src/qtk/*.h example-app/*.cpp example-app/*.h
+clang-format -i --style=file:.clang-format $SOURCES
 ```
 
 `clang-format` can be run with git integration (or CLion if you prefer).
@@ -304,7 +370,7 @@ To generate packages for Qtk desktop application, we should
 set `-DQTK_GUI=ON`. If this option is not set we will only package libqtk.
 
 The NSIS installer will allow component-specific path modification for all of
-these installation components through a GUI install application.
+these installation components through a Windows GUI install application.
 
 ##### Resources
 

example-app/CMakeLists.txt

@@ -2,7 +2,7 @@
 ## Example client project using qtk                                           ##
 ##                                                                            ##
 ## Author: Shaun Reed | Contact: shaunrd0@gmail.com | URL: www.shaunreed.com  ##
-## All Content (c) 2023 Shaun Reed, all rights reserved                       ##
+## All Content (c) 2025 Shaun Reed, all rights reserved                       ##
 ################################################################################
 cmake_minimum_required(VERSION 3.23)
 
@@ -56,7 +56,7 @@ endif()
 
 # Allow add_subdirectory on this project to use target ALIAS if available.
 # If this example project is opened standalone we will use find_package.
-if(NOT TARGET Qtk::qtk_library)
+if(NOT TARGET Qtk::qtk)
   find_package(Qtk 0.2 REQUIRED)
 endif()
 
@@ -77,20 +77,27 @@ configure_file(
 
 qt_add_executable(qtk_example ${EXAMPLE_SOURCES})
 target_link_libraries(qtk_example PUBLIC Qt6::Widgets Qt6::OpenGLWidgets Qt6::Core)
-target_link_libraries(qtk_example PUBLIC Qtk::qtk_library)
+target_link_libraries(qtk_example PUBLIC Qtk::qtk)
 target_include_directories(qtk_example PRIVATE "${CMAKE_CURRENT_BINARY_DIR}")
 
-install(
-    TARGETS qtk_example
-    COMPONENT qtk_example
-    BUNDLE DESTINATION .
-    LIBRARY DESTINATION lib
-    ARCHIVE DESTINATION lib/static
-    RUNTIME DESTINATION bin
-)
-qt_generate_deploy_app_script(
-    TARGET qtk_example
-    OUTPUT_SCRIPT QTK_EXAMPLE_DEPLOY_SCRIPT
-    NO_UNSUPPORTED_PLATFORM_ERROR
-)
-install(SCRIPT ${QTK_EXAMPLE_DEPLOY_SCRIPT} COMPONENT qtk_example)
+# qt_generate_deploy_app_script supports Windows and OSX in QtCore >= 6.3.
+# qt_generate_deploy_app_script is supported on Linux in QtCore >= 6.5.0.
+if((Qt6_VERSION VERSION_GREATER_EQUAL "6.3.0" AND (WIN32 OR APPLE))
+    OR Qt6_VERSION VERSION_GREATER_EQUAL "6.5.0")
+  install(
+      TARGETS qtk_example
+      COMPONENT qtk_example
+      BUNDLE DESTINATION .
+      LIBRARY DESTINATION lib
+      ARCHIVE DESTINATION lib/static
+      RUNTIME DESTINATION bin
+  )
+  qt_generate_deploy_app_script(
+      TARGET qtk_example
+      OUTPUT_SCRIPT QTK_EXAMPLE_DEPLOY_SCRIPT
+      NO_UNSUPPORTED_PLATFORM_ERROR
+  )
+  install(SCRIPT ${QTK_EXAMPLE_DEPLOY_SCRIPT} COMPONENT qtk_example)
+elseif(NOT Qtk_IS_TOP_LEVEL)
+  message(WARNING "[Qtk] Installation is only supported on Qt >=6.5.\n")
+endif()

example-app/examplescene.cpp

@@ -11,26 +11,21 @@
 
 using namespace Qtk;
 
-ExampleScene::ExampleScene(Qtk::Scene * scene) : Qtk::SceneInterface(scene) {
+ExampleScene::ExampleScene()
+{
   setSceneName("Example Scene");
   getCamera().getTransform().setTranslation(-8.0f, 0.0f, 10.0f);
   getCamera().getTransform().setRotation(-5.0f, 0.0f, 1.0f, 0.0f);
 }
 
-ExampleScene::~ExampleScene() {}
+ExampleScene::~ExampleScene() = default;
 
-void ExampleScene::init() {
-  auto skybox = new Qtk::Skybox("Skybox");
-  setSkybox(skybox);
-
-  std::string spartanPath = QTK_EXAMPLE_SOURCE_DIR;
-  spartanPath += "/resources/models/spartan/spartan.obj";
-  auto spartan = new Model("spartan", spartanPath.c_str());
-  addObject(spartan);
-  spartan->getTransform().setTranslation(-4.0f, 0.0f, 0.0f);
+void ExampleScene::init()
+{
+  setSkybox(new Qtk::Skybox);
 
   auto mesh = addObject(
-      new Qtk::MeshRenderer("rightTriangle", Triangle(QTK_DRAW_ARRAYS)));
+      new Qtk::MeshRenderer("rightTriangle", Triangle(QTK_DRAW_ELEMENTS)));
   mesh->getTransform().setTranslation(-5.0f, 0.0f, -2.0f);
 
   // QTK_DRAW_ARRAYS is the default for generic shapes in qtk/shape.h
@@ -56,11 +51,20 @@ void ExampleScene::init() {
   mesh->setColor(GREEN);
 }
 
-void ExampleScene::draw() {
+void ExampleScene::draw()
+{
+  // The base class method _must_ be called first, before additional logic.
   Scene::draw();
+
+  // No additional custom draw logic for this example.
+  // QtkScene in Qtk desktop application is an example using custom draw logic.
 }
 
-void ExampleScene::update() {
+void ExampleScene::update()
+{
+  auto top_triangle = MeshRenderer::getInstance("topTriangle");
+  auto bottom_triangle = MeshRenderer::getInstance("bottomTriangle");
+
   // Pitch forward and roll sideways
   MeshRenderer::getInstance("leftTriangle")
       ->getTransform()
@@ -69,27 +73,20 @@ void ExampleScene::update() {
       ->getTransform()
       .rotate(0.75f, 0.0f, 0.0f, 1.0f);
 
+  // Make the top and bottom triangles slide left-to-right.
   static float translateX = 0.025f;
   float limit = -9.0f;  // Origin position.x - 2.0f
-  float posX = MeshRenderer::getInstance("topTriangle")
-                   ->getTransform()
-                   .getTranslation()
-                   .x();
-  if(posX < limit || posX > limit + 4.0f) {
+  float posX = top_triangle->getTransform().getTranslation().x();
+  if (posX < limit || posX > limit + 4.0f) {
     translateX = -translateX;
   }
-  MeshRenderer::getInstance("topTriangle")
-      ->getTransform()
-      .translate(translateX, 0.0f, 0.0f);
-  MeshRenderer::getInstance("bottomTriangle")
-      ->getTransform()
-      .translate(-translateX, 0.0f, 0.0f);
-  MeshRenderer::getInstance("topTriangle")
-      ->getTransform()
-      .rotate(0.75f, 0.2f, 0.0f, 0.4f);
-  MeshRenderer::getInstance("bottomTriangle")
-      ->getTransform()
-      .rotate(0.75f, 0.0f, 0.2f, 0.4f);
+
+  top_triangle->getTransform().translate(translateX, 0.0f, 0.0f);
+  bottom_triangle->getTransform().translate(-translateX, 0.0f, 0.0f);
+
+  // Apply some rotation to the triangles as they move left-to-right.
+  top_triangle->getTransform().rotate(0.75f, 0.2f, 0.0f, 0.4f);
+  bottom_triangle->getTransform().rotate(0.75f, 0.0f, 0.2f, 0.4f);
 
   MeshRenderer::getInstance("centerCube")
       ->getTransform()

example-app/examplescene.h

@@ -11,16 +11,30 @@
 
 #include <qtk/scene.h>
 
-class ExampleScene : public Qtk::SceneInterface {
+class ExampleScene : public Qtk::Scene
+{
   public:
-    ExampleScene(Qtk::Scene * scene);
+    explicit ExampleScene();
 
     ~ExampleScene();
 
+    /**
+     * Override the initialization logic for the scene.
+     * This method should up the scene's objects, skybox, etc.
+     */
     void init() override;
 
+    /**
+     * Optionally override the draw method for the scene.
+     *
+     * This is just here for example, it should be omitted entirely if we don't
+     * want to provide a custom implementation for the ExampleScene.
+     */
     void draw() override;
 
+    /**
+     * Update objects in the scene for translation or rotation.
+     */
     void update() override;
 };
 

example-app/examplewidget.cpp

@@ -11,7 +11,8 @@
 #include "examplewidget.h"
 
 ExampleWidget::ExampleWidget(QWidget * parent) :
-    QOpenGLWidget(parent), mScene(new ExampleScene(new Qtk::SceneEmpty)) {
+    QOpenGLWidget(parent), mScene(new ExampleScene)
+{
   // NOTE: The decorator pattern is used to save / load scenes in Qtk currently.
   // The initializer above sets mScene to the concrete decorator ExampleScene.
   // Qtk::SceneEmpty provides an empty scene as the concrete component.
@@ -27,7 +28,8 @@ ExampleWidget::ExampleWidget(QWidget * parent) :
   setFocusPolicy(Qt::ClickFocus);
 }
 
-void ExampleWidget::initializeGL() {
+void ExampleWidget::initializeGL()
+{
   initializeOpenGLFunctions();
   connect(this, SIGNAL(frameSwapped()), this, SLOT(update()));
   glEnable(GL_MULTISAMPLE);
@@ -40,18 +42,21 @@ void ExampleWidget::initializeGL() {
   glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
 }
 
-void ExampleWidget::resizeGL(int width, int height) {
+void ExampleWidget::resizeGL(int width, int height)
+{
   Qtk::Scene::getProjectionMatrix().setToIdentity();
   Qtk::Scene::getProjectionMatrix().perspective(
       45.0f, float(width) / float(height), 0.1f, 1000.0f);
 }
 
-void ExampleWidget::paintGL() {
+void ExampleWidget::paintGL()
+{
   glClear(GL_DEPTH_BUFFER_BIT | GL_COLOR_BUFFER_BIT);
   mScene->draw();
 }
 
-void ExampleWidget::update() {
+void ExampleWidget::update()
+{
   mScene->update();
   QWidget::update();
 }

example-app/examplewidget.h

@@ -14,7 +14,8 @@
 
 #include "examplescene.h"
 
-class ExampleWidget : public QOpenGLWidget, protected QOpenGLFunctions {
+class ExampleWidget : public QOpenGLWidget, protected QOpenGLFunctions
+{
     Q_OBJECT;
 
   public:

example-app/main.cpp

@@ -11,7 +11,8 @@
 
 #include "examplewidget.h"
 
-int main(int argc, char * argv[]) {
+int main(int argc, char * argv[])
+{
   QApplication app(argc, argv);
 
   auto window = new QMainWindow;

resources/icons/linux/linux-icons.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# $1: Input path to an image to use for generating icons.
+# Helper script to generate qtk's icons for Linux given a path to an input PNG.
+sudo apt install imagemagick
+
+convert "$1" -resize 256x256 kilroy-256.png
+convert "$1" -resize 128x128 kilroy-128.png
+convert "$1" -resize 64x64 kilroy-64.png
+convert "$1" -resize 48x48 kilroy-48.png
+convert "$1" -resize 32x32 kilroy-32.png
+convert "$1" -resize 16x16 kilroy-16.png

resources/icons/osx/README.md

@@ -1,13 +0,0 @@
-
-```bash
-sudo apt install icnsutils
-```
-
-```bash
-convert icon.png -resize 32x32 kilroy_32.png
-convert icon.png -resize 16x16 kilroy_16.png
-convert icon.png -resize 48x48 kilroy_48.png
-convert icon.png -resize 128x128 kilroy_128.png
-convert icon.png -resize 256x256 kilroy_256.png
-png2icns png2icns kilroy.icns kilroy_*.png
-```

resources/icons/osx/osx-icons.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# $1: Input path to an image to use for generating icons.
+# Helper script to generate qtk's icons for OSX given a path to an input PNG.
+sudo apt install icnsutils imagemagick
+
+convert "$1" -resize 32x32 kilroy_32.png
+convert "$1" -resize 16x16 kilroy_16.png
+convert "$1" -resize 48x48 kilroy_48.png
+convert "$1" -resize 128x128 kilroy_128.png
+convert "$1" -resize 256x256 kilroy_256.png
+# For the application bundle in OSX.
+png2icns png2icns kilroy.icns kilroy_*.png
+
+# For the splash image in DMG installers.
+convert "$1" -resize 800x600! kilroy_splash.png

resources/icons/win/win-icons.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# $1: Input path to an image to use for generating icons.
+# Helper script to generate qtk's icons for Windows given a path to an input PNG.
+sudo apt install imagemagick
+
+# For the NSIS (un)installer executable shortcut icon.
+convert "$1" -resize 256x256,128x128,64x64,48x48,32x32,16x16 -background transparent -colors 256 kilroy.ico
+
+# For the NSIS installer splash screen.
+convert "$1" -resize 164x314! -background white -flatten kilroy_splash.bmp

resources/minimal_resources.qrc

@@ -0,0 +1,21 @@
+<RCC>
+    <qresource prefix="/textures">
+        <file alias="crate.png">images/crate.png</file>
+        <file alias="stone.png">images/stone.png</file>
+        <file alias="wood.png">images/wood.png</file>
+        <file>skybox/back.png</file>
+        <file>skybox/bottom.png</file>
+        <file>skybox/front.png</file>
+        <file>skybox/left.png</file>
+        <file>skybox/right.png</file>
+        <file>skybox/top.png</file>
+    </qresource>
+    <qresource prefix="/icons">
+        <file>fontawesome-free-6.2.1-desktop/svgs/solid/cube.svg</file>
+        <file>fontawesome-free-6.2.1-desktop/svgs/regular/trash-can.svg</file>
+        <file>fontawesome-free-6.2.1-desktop/svgs/regular/folder-open.svg</file>
+        <file>fontawesome-free-6.2.1-desktop/svgs/regular/floppy-disk.svg</file>
+        <file>fontawesome-free-6.2.1-desktop/svgs/brands/git-alt.svg</file>
+        <file alias="icon.png">icons/icon.png</file>
+    </qresource>
+</RCC>

resources/models/alien-hominid/alien.mtl

@@ -1,55 +0,0 @@
-# Blender MTL File: 'None'
-# Material Count: 4
-
-newmtl AlienHominid
-Ns 225.000000
-Ka 1.000000 1.000000 1.000000
-Kd 0.800000 0.533344 0.000000
-Ks 0.500000 0.500000 0.500000
-Ke 0.000000 0.000000 0.000000
-Ni 1.450000
-d 1.000000
-illum 2
-map_Bump normal.png
-map_Kd diffuse.png
-map_Ns roughness.png
-refl specular.png
-
-newmtl Blaster
-Ns 225.000000
-Ka 1.000000 1.000000 1.000000
-Kd 0.800000 0.800000 0.800000
-Ks 0.500000 0.500000 0.500000
-Ke 0.000000 0.000000 0.000000
-Ni 1.450000
-d 1.000000
-illum 2
-map_Bump blaster_normal.png
-map_Kd blaster_diffuse.png
-map_Ke blaster_emissive.png
-map_Ns blaster_roughness.png
-refl blaster_specular.png
-
-newmtl Screenshot_2021-04-19_194508
-Ns 225.000000
-Ka 1.000000 1.000000 1.000000
-Kd 0.800000 0.800000 0.800000
-Ks 0.500000 0.500000 0.500000
-Ke 0.000000 0.000000 0.000000
-Ni 1.450000
-d 1.000000
-illum 2
-map_Kd smoke.png
-map_d smoke.png
-
-newmtl Untitled-1
-Ns 77.904748
-Ka 1.000000 1.000000 1.000000
-Kd 0.800000 0.800000 0.800000
-Ks 0.500000 0.500000 0.500000
-Ke 0.000000 0.000000 0.000000
-Ni 1.450000
-d 1.000000
-illum 2
-map_Kd Untitled-1.png
-map_d Untitled-1.png

resources/models/backpack/backpack.mtl

@@ -1,16 +0,0 @@
-# Blender MTL File: 'None'
-# Material Count: 1
-
-newmtl Scene_-_Root
-Ns 225.000000
-Ka 1.000000 1.000000 1.000000
-Kd 0.800000 0.800000 0.800000
-Ks 0.500000 0.500000 0.500000
-Ke 0.0 0.0 0.0
-Ni 1.450000
-d 1.000000
-illum 2
-map_Kd diffuse.jpg
-map_Bump normal.png
-map_Ks specular.jpg
-

resources/models/backpack/source_attribution.txt

@@ -1,3 +0,0 @@
-Model by Berk Gedik, from: https://sketchfab.com/3d-models/survival-guitar-backpack-low-poly-799f8c4511f84fab8c3f12887f7e6b36
-
-Modified material assignment (Joey de Vries) for easier load in OpenGL model loading chapter, and renamed albedo to diffuse and metallic to specular to match non-PBR lighting setup.

resources/models/bird/bird.mtl

@@ -1,7 +0,0 @@
-newmtl material_0
-map_bump normal.jpg
-norm normal.jpg
-map_Kd diffuse.jpg
-occlusion occlusion.jpg
-Pm 0
-Pr 0.793152

resources/models/floor.obj

@@ -1,12 +0,0 @@
-# Blender v2.82 (sub 7) OBJ File: ''
-# www.blender.org
-mtllib floor.mtl
-o floor
-v -1.000000 -0.000000 1.000000
-v 1.000000 -0.000000 1.000000
-v 1.000000 0.000000 -1.000000
-v -1.000000 0.000000 -1.000000
-vn 0.0000 1.0000 0.0000
-usemtl Default_OBJ
-s off
-f 1//1 2//1 3//1 4//1

resources/models/scythe/scythe.mtl

@@ -1,8 +0,0 @@
-# WaveFront *.mtl file (generated by CINEMA 4D)
-
-newmtl item/objectcomponents/weapon/staff_2h_artifactdeadwind_d_03.m2_Geoset_000
-Ka 0.25 0.25 0.25
-Kd 1 1 1
-map_Kd diffuse.png
-illum 7
-