Merge branch 'scene-rework' of https://github.com/cpvrlab/SLProject4 …

…into scene-rework

docs/Doxyfile

@@ -911,9 +911,9 @@ INPUT                  = ../modules/sl/source \
                          ../modules/wai/source \
                          ../modules/utils/source \
                          ../modules/math/source \
-                         ../apps/app_demo_slproject/include \
-                         ../apps/app_demo_slproject/glfw \
-                         ../apps/app_demo_slproject/source \
+                         ../apps/app_demo_slproject \
+                         ../apps/app_demo_node \
+                         ../apps/source \
                          ../apps/app_demo_webgpu \
                          pages/Introduction.md \
                          pages/ExampleScenes.md \
@@ -930,6 +930,7 @@ INPUT                  = ../modules/sl/source \
                          pages/ExampleSkinnedAnimations.md \
                          pages/ExampleVolumeRendering.md \
                          pages/OnPaint.md \
+                         pages/AppFramework.md \
                          pages/Emscripten.md \
                          pages/BlenderToSL.md \
                          pages/SLProject.md
@@ -963,6 +964,7 @@ INPUT_ENCODING         = UTF-8
 
 FILE_PATTERNS          = *.cpp \
                          *.h \
+                         *.mm \
                          *.frag \
                          *.vert
 
@@ -1101,7 +1103,7 @@ USE_MDFILE_AS_MAINPAGE =
 # also VERBATIM_HEADERS is set to NO.
 # The default value is: NO.
 
-SOURCE_BROWSER         = NO
+SOURCE_BROWSER         = YES
 
 # Setting the INLINE_SOURCES tag to YES will include the body of functions,
 # classes and enums directly into the documentation.

docs/pages/AppFramework.md

@@ -0,0 +1,126 @@
+\page app-framework The %App Framework
+
+\section overview Overview
+
+SLProject provides a framework for quickly setting up platform-independent apps that run on Windows, macOS, Linux, Android, iOS, and the Web.
+The app framework is divided into three layers:
+
+- The **%App Layer** contains the code of your app. It contains the main function, some configuration code, and callbacks for hooking into
+  the SLProject systems. The central interface every app uses is the `App.h` header, which is implemented by the platform layer. 
+- The **Platform Layer** contains all platform-specific code for creating the rendering surface, setting up event handlers, etc. Every
+  platform has its own implementation of the `App.h`. The implementation corresponding to the target platform is selected at compile time by CMake.
+  The platform layer uses `SLInterface.h` to access SLProject modules.
+- The **SL Layer** contains all the SLProject libraries. This is where rendering, UI, math, asset loading, input handling, video capture, etc.
+  is done.
+
+<div style="width: 100%; justify-content: center; display: flex; margin: 20pt 0">
+    <img src="images/app_framework.svg" width="70%">
+</div>
+
+\section usage Usage
+
+\subsection cpp C++
+
+The main C++ file of an app looks something like this:
+
+```cpp
+#include <App.h>
+// Other includes...
+
+static SLScene* createScene(SLSceneID sceneID)
+{
+    return new AppExampleScene();
+}
+
+static void buildGui(SLScene* s, SLSceneView* sv)
+{
+    // ...
+}
+
+int SL_MAIN_FUNCTION(int argc, char* argv[])
+{
+    App::Config config;
+    config.argc         = argc,
+    config.argv         = argv;
+    config.windowWidth  = 640;
+    config.windowHeight = 480;
+    config.windowTitle  = "SLProject Example App";
+    config.onNewScene   = createScene;
+    config.onGuiBuild   = buildGui;
+    // More config...
+
+    return App::run(config);
+}
+```
+
+The main function is defined using a macro that expands to the name of the main function on
+the current platform. This is usually `main`, but on Android it expands to `slAndroidMain`,
+a fake main function that is called from the JNI to initialize the application because there is
+no actual `main` on Android.
+
+Inside the main function, an `App::Config` instance is created. This configuration specifies
+things like the window size, the ID of the start scene, or a callback for building the GUI.
+`App::run` is then called with this config to start the app. Every platform implements its own
+version of this function. The various implementations can be found in `apps/source/platforms`.
+Here's a list of all of them:
+
+- `AppGLFW.cpp` (Windows, macOS, Linux)
+- `AppEmscripten.cpp` (Web)
+- `AppAndroid.cpp` (Android)
+- `AppIOS.mm` (iOS)
+
+An implementation of `App::run` typically sets up the rendering surface, registers event handlers,
+loads core assets, starts the event loop, and returns when the program terminates.
+Only the Android version returns immediately because the event loop is handled by Java code and
+interacts with the app via the JNI.
+
+For more information on creating a new app, see
+[this wiki page](https://github.com/cpvrlab/SLProject4/wiki/Creating-a-New-App).
+
+\subsection cmake CMake
+
+New apps are added by calling the custom CMake function `sl_add_app`. This function is defined
+in `apps/CMakeLists.txt` and takes care of creating a new target and setting source files,
+headers, compile options, linked libraries, properties, etc. depending on the target platform.
+The function has parameters for specifying things like the name of the target, the platforms
+the app supports, additional source files (e.g. for scenes), the directory of the Android
+project, or iOS resources.
+
+`sl_add_app` uses the CMake variable `SL_PLATFORM` to decide which platform is currently being
+targeted. This variable is set in the top-level `CMakeLists.txt` based on the current target
+system. The possible platforms are:
+
+- `GLFW` (Windows, macOS, Linux)
+- `EMSCRIPTEN` (Web)
+- `ANDROID` (Android)
+- `IOS` (iOS)
+
+\section scene-loading Scene Loading
+
+A scene is loaded by setting the value of `AppDemo::sceneToLoad` to the ID of the new scene.
+Inside the event loop of every platform, we check whether this variable has a value and switch
+to the new scene if so:
+
+```cpp
+if (AppDemo::sceneToLoad)
+{
+    slSwitchScene(sv, *AppDemo::sceneToLoad);
+    AppDemo::sceneToLoad = {};
+}
+```
+
+Scene switching is implemented inside `AppLoad::switchScene`. This function calls the callback
+`AppConfig::onNewScene` to create a new scene instance. The callback is specified by the app and
+returns an instance of a class derived from `SLScene` (e.g. `AppDemoSceneMinimal`).
+After creating the new scene instance, we switch to it in two stages:
+
+1. Register assets to be loaded. We call the overloaded `SLScene::registerAssetsToLoad` so it can
+   register tasks on the `SLAssetLoader` to be executed asynchronously in a different thread.
+   Meanwhile, the event loop on the main thread continues running so we can for example render
+   a loading screen. Every frame, `SLAssetLoader::checkIfAsyncLoadingIsDone` is called to check whether
+   the worker thread is done. When that happens, the next stage is triggered.
+   Note: All I/O operations have to be registered here because they cannot be executed synchronously on
+   the main thread on the Emscripten platform.
+2. Assemble the scene. When the asset loader is done, we call the overloaded `SLScene::assemble`
+   function that uses the loaded assets to assemble the scene. After assembly, `AppDemo::scene`
+   is set to the new scene and the scene switch is completed.

docs/pages/BlenderToSL.md

@@ -1,7 +1,4 @@
 \page blender-to-sl Blender to SLProject Export
-\htmlonly
-<style>html{--content-maxwidth:auto}</style>
-\endhtmlonly
 \section intro Introduction
 <p>
 This page gives an overview of things to consider when preparing models created in the 3D software Blender for use in SLProject.

docs/pages/DataProtectionDeclaration.md

@@ -1,7 +1,4 @@
 \page data-protection-declaration SLProject Data Protection Declaration
-\htmlonly
-<style>html{--content-maxwidth:auto}</style>
-\endhtmlonly
 The SLProject uses the following permissions:
 
 * **Internet access**: If available the app downloads predefined camera calibration parameters.

docs/pages/Emscripten.md

@@ -1,7 +1,4 @@
 \page emscripten Emscripten
-\htmlonly
-<style>html{--content-maxwidth:auto}</style>
-\endhtmlonly
 SLProject can be built to run in a web browser. We use the [Emscripten](https://emscripten.org/) toolchain, which compiles C/C++ code to a binary instruction format called [WebAssembly](https://webassembly.org/). The generated Wasm module can be loaded by ordinary JavaScript at runtime. The browser then compiles the instructions to native machine code and runs it, making it possible to run high-performance code in the browser. To access OpenGL functions, browsers expose the [WebGL API](https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API), which Emscripten wraps in standard OpenGL headers. SLProject uses WebGL 2, which is based on OpenGL 3.0 ES. 
 Not all scenes from app-Demo-SLProject can run in the browser because OpenGL 4.0 functions are not available or because some OpenCV modules can't be compiled for WebAssembly.
 

docs/pages/ExampleGlTF.md

@@ -1,7 +1,4 @@
 \page example-gltf glTF File Format
-\htmlonly
-<style>html{--content-maxwidth:auto}</style>
-\endhtmlonly
 SLProject supports loading the [glTF model format](https://en.wikipedia.org/wiki/GlTF). This scene
 showcases loading and rendering the damaged helmet sample by Khronos. Notice how the environment is
 reflected onto the helmet. Note that it may take some time to load this scene since there is a lot of

docs/pages/ExampleImageBasedLighting.md

@@ -1,7 +1,4 @@
 \page example-ibl Image Based Lighting
-\htmlonly
-<style>html{--content-maxwidth:auto}</style>
-\endhtmlonly
 The following scene shows 7 x 7 spheres with different metallic (vertical) and 
 roughness (horizontal) material parameters. 
 These parameters can be passed either by float values or as textures per pixel.

docs/pages/ExampleLevelOfDetail.md

@@ -1,7 +1,4 @@
 \page example-lod Level of Detail
-\htmlonly
-<style>html{--content-maxwidth:auto}</style>
-\endhtmlonly
 The following scene shows 2500 corinthian columns with each 83k triangles in their highest resolution. 
 With 3 levels of detail the amount of geometry is reduced depending on the size of the bounding rectangle in screen space. 
 In addition, we do automatically a view frustum culling to optimize rendering performance.

docs/pages/ExampleNodeAnimations.md

@@ -1,7 +1,4 @@
 \page example-node-animations Node Animations
-\htmlonly
-<style>html{--content-maxwidth:auto}</style>
-\endhtmlonly
 See the appDemoLoadScene function in AppDemoLoad.cpp for this scene (SID_AnimationNode) 
 on how to create node animations and how to assign them to an SLNode instance.
 SLAnimation instances are created and controlled by the SLAnimManager. 

docs/pages/ExampleParticles.md

@@ -1,7 +1,4 @@
 \page example-particles Particle Systems
-\htmlonly
-<style>html{--content-maxwidth:auto}</style>
-\endhtmlonly
 The SLParticleSystem is the most complex derivative of the SLMesh class and allows the creation of highly
 configurable particle systems (PS). All its parameters can be modified in the _Properties_ tab (see menu Info > Properties).
 The implementation uses for rendering geometry shaders on systems that have OpenGL >= 4.1 or OpenGLES >= 3.2. All other

docs/pages/ExamplePathtracing.md

@@ -1,7 +1,4 @@
 \page example-pathtracing Path Tracing
-\htmlonly
-<style>html{--content-maxwidth:auto}</style>
-\endhtmlonly
 Alternatively you can render a scene with path tracing using the menu *Renderer > Path Tracing*.
 The path tracer is optimized for the Blinn-Phong reflection model extended with reflection and refraction coefficient.
 By default, the resolution 0.5 times the window resolution. You can adjust the path tracing setting over the menu *PT*.

docs/pages/ExampleRaytracing.md

@@ -1,7 +1,4 @@
 \page example-raytracing Ray Tracing
-\htmlonly
-<style>html{--content-maxwidth:auto}</style>
-\endhtmlonly
 Alternatively you can render a scene with ray tracing using the menu *Renderer > Ray Tracing*.
 The ray tracer is optimized for the Blinn-Phong reflection model. 
 By default, the resolution 0.5 times the window resolution. You can adjust the ray tracing setting over the menu *RT*.

docs/pages/ExampleRevolver.md

@@ -1,7 +1,4 @@
 \page example-revolver Revolving Meshes
-\htmlonly
-<style>html{--content-maxwidth:auto}</style>
-\endhtmlonly
 Examples of revolving mesh objects constructed by rotating a 2D curve. 
 The classes SLArrow, SLCone, SLCylinder, SLDisk, SLLens and SLSpheric inherit the SLRevolver class that inherits from SLMesh.
 

docs/pages/ExampleScenes.md

@@ -1,7 +1,4 @@
 \page example-scenes Online Example Scenes
-\htmlonly
-<style>html{--content-maxwidth:auto}</style>
-\endhtmlonly
 
 All examples presented here run live in browsers that support [WebAssembly](https://webassembly.org/) and the [Emscripten framework](https://emscripten.org/docs/introducing_emscripten/index.html).
 These are at the moment: Google Chrome, Firefox and Microsoft Edge.

docs/pages/ExampleShadowMapping.md

@@ -1,7 +1,4 @@
 \page example-shadow-mapping Shadow Mapping
-\htmlonly
-<style>html{--content-maxwidth:auto}</style>
-\endhtmlonly
 
 In this scene you can see all light types: Directional, rectangular, spot and point light. 
 All light types (SLLightDirect, SLLightRect, SLLightSpot) are derived from SLLight and can have a SLShadowMap. 

docs/pages/ExampleSkinnedAnimations.md

@@ -1,7 +1,4 @@
 \page example-skinned-animations Skinned Animations
-\htmlonly
-<style>html{--content-maxwidth:auto}</style>
-\endhtmlonly
 
 Skinned skeleton animation are imported at the moment with the Collada file format (DAE).
 Skinned skeleton animation are controlled by the SLAnimManager. Its interface is in the menu *Animation*.

docs/pages/ExampleVolumeRendering.md

@@ -1,8 +1,5 @@
 \page example-volume-rendering Volume Rendering
 
-\htmlonly
-<style>html{--content-maxwidth:auto}</style>
-\endhtmlonly
 Volume Rendering of an MRI angiography dataset. In the material properties you can adjust the transfer function for
 color and transparency points that transform the MRI intensities into color and transparency. Volume rendering is
 realized with a special fragment shader that performs a ray cast through the MRI volume.