README and build options.

This commit is contained in:
Shaun Reed 2025-03-16 14:10:45 -04:00
parent c9004027b9
commit 8d7bbb75fb
2 changed files with 120 additions and 64 deletions

View File

@ -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)

160
README.md
View File

@ -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](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.
@ -24,7 +29,13 @@ detached from the main window in this way.
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 default scene contains basic examples like texture mapping to make a crate from basic cube geometry
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)
@ -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"/> |
@ -56,8 +67,8 @@ Key features that are planned:
- [ ] Basic text editor for quickly modifying shaders attached to objects.
- [ ] Reduce size of application resources and git references.
For examples of using the Qtk API, see the `example-app` project in the root of
this repository.
For examples of using the libqtk API, 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/)
@ -67,8 +78,9 @@ and see some examples in the `resources/models/` directory.
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.
@ -78,11 +90,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](./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_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](./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.
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 +155,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
install each component individually.
If you want to uninstall previously installed components, 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.
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)
@ -158,7 +198,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 +243,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
@ -238,14 +290,18 @@ If you'd still like to run these tools manually, see the instructions below.
cd qtk
# Build
cmake -B build && cmake --build build -- -j $(nproc)
clang-tidy -p build/ --fix --config-file=.clang-tidy src/**/*.cpp src/**/*.h example-app/*.cpp example-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/**/*.cpp src/**/*.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).