Cleanup and document engine-sample.cars

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

@@ -10,3 +10,4 @@ multiple plugins of the engine:
 - @subpage examples-engine-scene - @copybrief examples-engine-scene
 - @subpage examples-engine-assets - @copybrief examples-engine-assets
 - @subpage examples-engine-events - @copybrief examples-engine-events
+- @subpage examples-engine-voxels - @copybrief examples-engine-voxels

engine/samples/CMakeLists.txt

@@ -46,4 +46,4 @@ make_sample(DIR "assets/saving" ASSETS)
 make_sample(DIR "renderer")
 make_sample(DIR "collisions" COMPONENTS)
 make_sample(DIR "scene" COMPONENTS ASSETS)
-make_sample(DIR "cars" COMPONENTS ASSETS)
+make_sample(DIR "voxels" COMPONENTS ASSETS)

engine/samples/voxels/main.cpp

@@ -0,0 +1,84 @@
+#include <cubos/engine/settings/settings.hpp>
+#include <cubos/engine/renderer/directional_light.hpp>
+#include <cubos/engine/renderer/plugin.hpp>
+#include <cubos/engine/transform/plugin.hpp>
+#include <cubos/engine/voxels/plugin.hpp>
+
+using cubos::core::ecs::Commands;
+using cubos::core::ecs::Read;
+using cubos::core::ecs::Write;
+using cubos::core::gl::Grid;
+using cubos::core::gl::Palette;
+using namespace cubos::engine;
+
+/// [Get handles to assets]
+static const Asset<Grid> CarAsset = AnyAsset("059c16e7-a439-44c7-9bdc-6e069dba0c75");
+static const Asset<Palette> PaletteAsset = AnyAsset("1aa5e234-28cb-4386-99b4-39386b0fc215");
+/// [Get handles to assets]
+
+static void settingsSystem(Write<Settings> settings)
+{
+    settings->setString("assets.io.path", SAMPLE_ASSETS_FOLDER);
+}
+
+/// [Load and set palette]
+static void setPaletteSystem(Read<Assets> assets, Write<Renderer> renderer)
+{
+    // Read the palette's data and pass it to the renderer.
+    auto palette = assets->read(PaletteAsset);
+    (*renderer)->setPalette(*palette);
+}
+/// [Load and set palette]
+
+static void spawnCameraSystem(Commands cmds, Write<ActiveCameras> activeCameras)
+{
+    // Spawn the camera entity.
+    activeCameras->entities[0] =
+        cmds.create()
+            .add(Camera{.fovY = 60.0F, .zNear = 0.1F, .zFar = 1000.0F})
+            .add(Position{{50.0F, 50.0F, 50.0F}})
+            .add(Rotation{glm::quatLookAt(glm::normalize(glm::vec3{-1.0F, -1.0F, -1.0F}), glm::vec3{0.0F, 1.0F, 0.0F})})
+            .entity();
+}
+
+static void spawnLightSystem(Commands cmds)
+{
+    // Spawn the sun.
+    cmds.create()
+        .add(DirectionalLight{glm::vec3(1.0F), 1.0F})
+        .add(Rotation{glm::quat(glm::vec3(glm::radians(45.0F), glm::radians(45.0F), 0))});
+}
+
+/// [Spawn car system]
+static void spawnCarSystem(Commands cmds, Read<Assets> assets)
+{
+    // Calculate the necessary offset to center the model on (0, 0, 0).
+    auto car = assets->read(CarAsset);
+    glm::vec3 offset = glm::vec3(car->size().x, 0.0F, car->size().z) / -2.0F;
+
+    // Create the car entity
+    cmds.create()
+        .add(RenderableGrid{CarAsset, offset})
+        .add(LocalToWorld{});
+}
+/// [Spawn car system]
+
+int main(int argc, char** argv)
+{
+    Cubos cubos{argc, argv};
+
+    cubos.addPlugin(rendererPlugin);
+    /// [Adding the plugin]
+    cubos.addPlugin(voxelsPlugin);
+    /// [Adding the plugin]
+
+    cubos.startupSystem(settingsSystem).tagged("cubos.settings");
+    cubos.startupSystem(spawnCameraSystem);
+    cubos.startupSystem(spawnLightSystem);
+    /// [Adding systems]
+    cubos.startupSystem(setPaletteSystem).after("cubos.renderer.init");
+    cubos.system(spawnCarSystem);
+    /// [Adding systems]
+
+    cubos.run();
+}

engine/samples/voxels/page.md

@@ -0,0 +1,32 @@
+# Voxels {#examples-engine-voxels}
+
+@brief Using the @ref voxels-plugin plugin.
+
+This example shows the @ref voxels-plugin plugin, which registers asset bridges used to load voxel grids (`.grid`) and palettes (`.pal`). Check out the @ref examples-engine-assets-bridge sample for an introduction on the @ref assets-plugin plugin.
+
+It is very similar to the @ref examples-engine-renderer, differing only in the fact that in this sample the grid and palette are loaded from files.
+
+![](voxels/output.png)
+
+The plugin function is included from the @ref engine/voxels/plugin.hpp header.
+To see the asset, you'll also need to perform a basic configuration of the @ref renderer-plugin plugin like shown in the @ref examples-engine-renderer sample.
+
+@snippet voxels/main.cpp Adding the plugin
+
+Lets start by defining the handles of the assets we want to use, as done in the @ref examples-engine-assets sample.
+
+@snippet voxels/main.cpp Get handles to assets
+
+In this sample, instead of creating a new palette, we just read the data from the asset identified from the `PaletteAsset` handle we defined previously. Internally, the @ref cubos::engine::Assets "assets manager" will automatically load the palette asset if it hasn't been loaded before.
+
+@snippet voxels/main.cpp Load and set palette
+
+Now, we can create an entity with our car asset. 
+
+@snippet voxels/main.cpp Spawn car system
+
+Finally, we just add these systems. 
+
+@snippet voxels/main.cpp Adding systems
+
+And voilá, you now have a car floating in space.