Cleanup and document engine-sample.renderer

docs/Doxyfile

@@ -5,15 +5,19 @@ PROJECT_NUMBER = @DOXYGEN_PROJECT_VERSION@
 # Add sources
 INPUT = @DOXYGEN_PROJECT_ROOT@/docs/pages \
         @DOXYGEN_PROJECT_ROOT@/core/include \
-        @DOXYGEN_PROJECT_ROOT@/engine/include
+        @DOXYGEN_PROJECT_ROOT@/core/samples \
+        @DOXYGEN_PROJECT_ROOT@/engine/include \
+        @DOXYGEN_PROJECT_ROOT@/engine/samples
 EXAMPLE_PATH = @DOXYGEN_PROJECT_ROOT@/core/samples \
                @DOXYGEN_PROJECT_ROOT@/engine/samples
 EXTRACT_ALL = YES
 EXTRACT_PRIVATE = YES
 EXTRACT_PRIV_VIRTUAL = YES
 RECURSIVE = YES
 OUTPUT_DIRECTORY = @DOXYGEN_OUTPUT_DIRECTORY@
-IMAGE_PATH = @DOXYGEN_PROJECT_ROOT@/docs/images
+IMAGE_PATH = @DOXYGEN_PROJECT_ROOT@/docs/images \
+             @DOXYGEN_PROJECT_ROOT@/core/samples \
+             @DOXYGEN_PROJECT_ROOT@/engine/samples
 
 # Use relative include paths
 FULL_PATH_NAMES = YES

docs/pages/3_examples/2_engine/main.md

@@ -2,4 +2,7 @@
 
 @brief Showcases features of the @ref engine library.
 
-@note Under construction.
+The following examples have fully documented tutorials on how to use the
+multiple plugins of the engine:
+
+- @subpage examples-engine-renderer - @copybrief examples-engine-renderer

engine/include/cubos/engine/renderer/plugin.hpp

@@ -20,6 +20,8 @@ namespace cubos::engine
     /// @defgroup renderer-plugin Renderer
     /// @ingroup engine
     /// @brief Creates and handles the lifecycle of a renderer.
+    /// @see Take a look at the @ref examples-engine-renderer example for a demonstration of this
+    /// plugin.
     ///
     /// Renders all entities with the @ref RenderableGrid component, using as cameras entities with
     /// the @ref Camera component selected by the @ref ActiveCameras resource. Lights are rendered

engine/samples/renderer/main.cpp

@@ -1,29 +1,27 @@
-#include <cubos/core/data/debug_serializer.hpp>
-#include <cubos/core/memory/stream.hpp>
 #include <cubos/core/settings.hpp>
 
 #include <cubos/engine/renderer/environment.hpp>
 #include <cubos/engine/renderer/light.hpp>
 #include <cubos/engine/renderer/plugin.hpp>
-#include <cubos/engine/renderer/renderer.hpp>
 #include <cubos/engine/transform/plugin.hpp>
 
 using cubos::core::Settings;
 using cubos::core::ecs::Commands;
 using cubos::core::ecs::Entity;
-using cubos::core::ecs::World;
 using cubos::core::ecs::Write;
+
 using namespace cubos::engine;
 
-static void settings(Write<Settings> settings)
+static void settingsSystem(Write<Settings> settings)
 {
+    // We don't load assets in this sample and we don't even have an assets folder, so we should
+    // disable assets IO.
     settings->setBool("assets.io.enabled", false);
 }
 
-static void setupScene(Commands commands, Write<Assets> assets, Write<ActiveCameras> camera, Write<Renderer> renderer,
-                       Write<RendererEnvironment> env)
+/// [Setting the palette]
+static void setPaletteSystem(Write<Renderer> renderer)
 {
-    using cubos::core::gl::Grid;
     using cubos::core::gl::Palette;
 
     // Create a simple palette with 3 materials (red, green and blue).
@@ -32,14 +30,46 @@ static void setupScene(Commands commands, Write<Assets> assets, Write<ActiveCame
         {{0, 1, 0, 1}},
         {{0, 0, 1, 1}},
     }});
+}
+/// [Setting the palette]
 
-    // Create a 2x2x2 grid whose voxels alternate between the materials defined above.
+/// [Spawning a voxel grid]
+static void spawnVoxelGridSystem(Commands commands, Write<Assets> assets)
+{
+    using cubos::core::gl::Grid;
+
+    // Create a 2x2x2 grid whose voxels alternate between the materials defined in the palette.
     auto gridAsset = assets->create(Grid{{2, 2, 2}, {1, 2, 3, 1, 2, 3, 1, 2}});
 
     // Spawn an entity with a renderable grid component and a identity transform.
     commands.create(RenderableGrid{gridAsset, {-1.0F, 0.0F, -1.0F}}, LocalToWorld{});
+}
+/// [Spawning a voxel grid]
+
+/// [Spawning a point light]
+static void spawnLightSystem(Commands commands)
+{
+    // Spawn a point light.
+    commands.create()
+        .add(PointLight{.color = {1.0F, 1.0F, 1.0F}, .intensity = 1.0F, .range = 10.0F})
+        .add(LocalToWorld{})
+        .add(Position{{1.0F, 3.0F, -2.0F}});
+}
+/// [Spawning a point light]
+
+/// [Setting the environment]
+static void setEnvironmentSystem(Write<RendererEnvironment> env)
+{
+    env->ambient = {0.2F, 0.2F, 0.2F};
+    env->skyGradient[0] = {0.1F, 0.2F, 0.4F};
+    env->skyGradient[1] = {0.6F, 0.6F, 0.8F};
+}
+/// [Setting the environment]
 
-    // Spawn the left camera entity.
+/// [Spawn the cameras]
+static void spawnCamerasSystem(Commands commands, Write<ActiveCameras> camera)
+{
+    // Spawn the a camera entity for the first viewport.
     camera->entities[0] =
         commands.create()
             .add(Camera{.fovY = 60.0F, .zNear = 0.1F, .zFar = 100.0F})
@@ -48,29 +78,29 @@ static void setupScene(Commands commands, Write<Assets> assets, Write<ActiveCame
             .add(Rotation{glm::quatLookAt(glm::normalize(glm::vec3{1.0F, 0.0F, 1.0F}), glm::vec3{0.0F, 1.0F, 0.0F})})
             .entity();
 
-    // Split the screen but use the same camera.
+    // Add two other viewports using the same camera, which splits the screen in three.
     camera->entities[1] = camera->entities[0];
     camera->entities[2] = camera->entities[0];
-
-    // Spawn a point light.
-    commands.create()
-        .add(PointLight{.color = {1.0F, 1.0F, 1.0F}, .intensity = 1.0F, .range = 10.0F})
-        .add(LocalToWorld{})
-        .add(Position{{1.0F, 3.0F, -2.0F}});
-
-    // Set the ambient light.
-    env->ambient = {0.2F, 0.2F, 0.2F};
-    env->skyGradient[0] = {0.1F, 0.2F, 0.4F};
-    env->skyGradient[1] = {0.6F, 0.6F, 0.8F};
 }
+/// [Spawn the cameras]
 
-int main(int argc, char** argv)
+int main()
 {
-    Cubos cubos(argc, argv);
+    Cubos cubos{};
 
+    /// [Adding the plugin]
     cubos.addPlugin(rendererPlugin);
+    /// [Adding the plugin]
+
+    cubos.startupSystem(settingsSystem).tagged("cubos.settings");
+
+    /// [Adding the systems]
+    cubos.startupSystem(setPaletteSystem).afterTag("cubos.renderer.init");
+    cubos.startupSystem(spawnVoxelGridSystem);
+    cubos.startupSystem(spawnLightSystem);
+    cubos.startupSystem(setEnvironmentSystem);
+    cubos.startupSystem(spawnCamerasSystem);
+    /// [Adding the systems]
 
-    cubos.startupSystem(settings).tagged("cubos.settings");
-    cubos.startupSystem(setupScene).afterTag("cubos.renderer.init");
     cubos.run();
 }

engine/samples/renderer/page.md

@@ -0,0 +1,47 @@
+# Renderer {#examples-engine-renderer}
+
+@brief Using the @ref renderer-plugin plugin.
+
+This example shows how the @ref renderer-plugin plugin can be used and
+configured with a simple scene, lighting and split-screen rendering.
+
+![](renderer/output.png)
+
+The plugin function is included from the @ref engine/renderer/plugin.hpp header.
+You may need to include other headers, depending on what you want to access.
+
+@snippet renderer/main.cpp Adding the plugin
+
+The first thing we're going to worry about is setting the
+@ref cubos::core::gl::Palette "Palette" the renderer will use. This palette
+would usually be loaded from a file, but for this example we'll just create it
+manually.
+
+@snippet renderer/main.cpp Setting the palette
+
+We should also spawn a @ref cubos::core::gl::Grid "voxel grid", so we have
+something to render.
+
+@snippet renderer/main.cpp Spawning a voxel grid
+
+If we don't add any lights, the scene will be completely dark. Lets add a
+simple @ref cubos::engine::PointLight "PointLight".
+
+@snippet renderer/main.cpp Spawning a point light
+
+We can also add some ambient lighting, and even add a sky gradient, through the
+@ref cubos::engine::RendererEnvironment "RendererEnvironment" resource.
+
+@snippet renderer/main.cpp Setting the environment
+
+Lastly, without a camera, we won't be able to see anything. Cameras can be set
+using the @ref cubos::engine::ActiveCameras "ActiveCameras" resource.
+
+@snippet renderer/main.cpp Spawn the cameras
+
+Then, its just a matter of adding these systems to the engine. The only one
+which requires special attention is the `setPaletteSystem`. This system
+accesses the @ref cubos::engine::Renderer "Renderer" resource, which is only
+initialized on the tag `cubos.renderer.init`.
+
+@snippet renderer/main.cpp Adding the systems