From 37ddc12b54dad2c33ebf822661aa996680ef2a29 Mon Sep 17 00:00:00 2001 From: Ricardo Antunes Date: Sat, 9 Sep 2023 10:55:03 +0100 Subject: [PATCH] docs(engine): cleanup and document assets.bridge --- docs/pages/3_examples/2_engine/main.md | 1 + engine/samples/assets/bridge/main.cpp | 40 ++++++++++------- engine/samples/assets/bridge/page.md | 59 ++++++++++++++++++++++++++ 3 files changed, 84 insertions(+), 16 deletions(-) create mode 100644 engine/samples/assets/bridge/page.md diff --git a/docs/pages/3_examples/2_engine/main.md b/docs/pages/3_examples/2_engine/main.md index 9e63f45881..a0703a1a29 100644 --- a/docs/pages/3_examples/2_engine/main.md +++ b/docs/pages/3_examples/2_engine/main.md @@ -6,3 +6,4 @@ 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 +- @subpage examples-engine-assets-bridge - @copybrief examples-engine-assets-bridge diff --git a/engine/samples/assets/bridge/main.cpp b/engine/samples/assets/bridge/main.cpp index 601ae8eac2..a861d7c1b3 100644 --- a/engine/samples/assets/bridge/main.cpp +++ b/engine/samples/assets/bridge/main.cpp @@ -1,10 +1,3 @@ -/// @file -/// @brief A sample demonstrating how to create a custom asset bridge. -/// -/// This sample demonstrates how we can create a custom asset bridge to load assets of a custom -/// type. In this case, a bridge is created to load text files (.txt) as strings. The bridge is -/// registered with the asset manager, and then a text file is loaded and printed to the console. - #include #include @@ -14,8 +7,10 @@ using cubos::core::Settings; using cubos::core::ecs::Read; using cubos::core::ecs::Write; using cubos::core::memory::Stream; + using namespace cubos::engine; +/// [TextBridge] /// This bridge inherits from the FileBridge, since it will be loading/saving assets from/to single /// files. class TextBridge : public FileBridge @@ -25,7 +20,9 @@ class TextBridge : public FileBridge : FileBridge(typeid(std::string)) { } + /// [TextBridge] + /// [TextBridge::loadFromFile] bool loadFromFile(Assets& assets, const AnyAsset& handle, Stream& stream) override { // Dump the file's contents into a string. @@ -36,7 +33,9 @@ class TextBridge : public FileBridge assets.store(handle, std::move(contents)); return true; } + /// [TextBridge::loadFromFile] + /// [TextBridge::saveToFile] bool saveToFile(const Assets& assets, const AnyAsset& handle, Stream& stream) override { // Get the asset's data. @@ -47,35 +46,44 @@ class TextBridge : public FileBridge return true; } }; +/// [TextBridge::saveToFile] -// We specify the same UUID as the one defined in the `.meta` file. -static const Asset SampleAsset = AnyAsset("6f42ae5a-59d1-5df3-8720-83b8df6dd536"); - -static void config(Write settings) +static void configSystem(Write settings) { settings->setString("assets.io.path", SAMPLE_ASSETS_FOLDER); } -static void bridge(Write assets) +/// [Registering the bridge] +static void bridgeSystem(Write assets) { // Add a custom bridge to load .txt files. assets->registerBridge(".txt", std::make_unique()); } +/// [Registering the bridge] -static void load(Read assets) +/// [Loading the asset] +// Assets are identified through UUIDs which are defined in their .meta files. +static const Asset SampleAsset = AnyAsset("6f42ae5a-59d1-5df3-8720-83b8df6dd536"); + +static void loadSystem(Read assets) { // Access the text asset - will be loaded automatically. auto text = assets->read(SampleAsset); Stream::stdOut.print(*text); } +/// [Loading the asset] int main() { auto cubos = Cubos(); + + /// [Configuration] cubos.addPlugin(assetsPlugin); - cubos.startupSystem(config).tagged("cubos.settings"); - cubos.startupSystem(bridge).tagged("cubos.assets.bridge"); - cubos.startupSystem(load).tagged("cubos.assets"); + cubos.startupSystem(bridgeSystem).tagged("cubos.assets.bridge"); + cubos.startupSystem(loadSystem).tagged("cubos.assets"); + /// [Configuration] + + cubos.startupSystem(configSystem).tagged("cubos.settings"); cubos.run(); return 0; } diff --git a/engine/samples/assets/bridge/page.md b/engine/samples/assets/bridge/page.md new file mode 100644 index 0000000000..380cc8041b --- /dev/null +++ b/engine/samples/assets/bridge/page.md @@ -0,0 +1,59 @@ +# Custom Asset Bridges {#examples-engine-assets-bridge} + +@brief Creating your own bridges for the @ref assets-plugin plugin. + +This example demonstrates how we can create a custom asset bridge to load +assets of a given type. More specifically, we'll go through how we can create a +bridge which loads `std::string`s from text files. + +We define our bridge class by inheriting from @ref cubos::engine::FileBridge, +which offers a simple interface for loading and saving assets from files. + +@snippet assets/bridge/main.cpp TextBridge + +We pass `typeid(std::string)` to the base class, so that the engine knows which +type of assets this bridge can load. Then, we'll need to implement both the @ref +cubos::engine::FileBridge::loadFromFile "loadFromFile" and @ref +cubos::engine::FileBridge::saveToFile "saveToFile" methods. + +In the first method, we receive the @ref cubos::engine::Assets +"assets manager" where we should store the loaded data, the handle to the asset +we're loading, and a stream to read the file data from. + +@snippet assets/bridge/main.cpp TextBridge::loadFromFile + +In the second method, we receive the @ref cubos::engine::Assets +"assets manager", the handle to the asset we're saving, and a stream to write +the file data to. + +@snippet assets/bridge/main.cpp TextBridge::saveToFile + +Now that we have our bridge type, we must register it with the assets manager +before using it. + +@snippet assets/bridge/main.cpp Registering the bridge + +After this system runs, any time we load an asset whose path ends with `.txt`, +the assets manager will use our bridge to load it. + +In this sample we have a file `sample.txt` on the `assets/` directory containing the following text: + +@include assets/bridge/assets/sample.txt + +We also have a file `sample.txt.meta`, which describes the asset for the +engine. In this case, we only need to specify its UUID, which was generated on +a [UUID generator website](https://www.uuidgenerator.net/): + +@include assets/bridge/assets/sample.txt.meta + +Then, we can load it from our code: + +@snippet assets/bridge/main.cpp Loading the asset + +Some care must be taken when registering bridges or loading assets during the +startup phase. Systems which add bridges should be tagged with +`cubos.assets.bridge` so that they run before any assets are loaded. +Similarly, startup systems which load assets should be tagged with +`cubos.assets` so that they run after all bridges have been registered. + +@snippet assets/bridge/main.cpp Configuration