Add documentation for TileProviderByLevel (#3446)

---------

Co-authored-by: Ylva Selling <ylva.selling@gmail.com>

data/assets/examples/tileprovider/tileproviderbylevel/bylevel.asset

@@ -0,0 +1,62 @@
+-- Basic
+-- This example file adds two layers to a globe. The first layer being used is showing
+-- a cloud layer and at higher levels a Blue Marble image is used instead. Recommended
+-- reading for this example is the documentation on the
+-- [DefaultTileProvider](#globebrowsing_defaulttileprovider).
+
+-- Download some example images that we can use
+local images = asset.resource({
+  Name = "Earth Textures",
+  Type = "HttpSynchronization",
+  Identifier = "earth_textures",
+  Version = 3
+})
+
+-- Define the TileProvider
+local TileProvider = {
+  Identifier = "Example",
+  Type = "TileProviderByLevel",
+  Enabled = true,
+  LevelTileProviders = {
+    {
+      -- Show only a cloud layer for the first 3 layers (2, 3, 4)
+      MaxLevel = 4,
+      TileProvider = {
+        Identifier = "Blue_Marble_Clouds",
+        FilePath = images .. "earth_clouds.jpg"
+      }
+    },
+    {
+      -- Then transition fade into the Blue Marble image representation
+      MaxLevel = 22,
+      TileProvider = {
+        Identifier = "Blue_Marble",
+        FilePath = images .. "earth_bluemarble.jpg"
+      }
+    }
+  }
+}
+
+-- Define the scene graph node
+local Node = {
+  Identifier = "TileProviderByLevel_Example",
+  Renderable = {
+    Type = "RenderableGlobe",
+    Layers = {
+      -- The globe has exactly one layer, which is the one we defined above
+      ColorLayers = { TileProvider }
+    }
+  },
+  GUI = {
+    Name = "TileProviderByLevel - Basic",
+    Path = "/Examples"
+  }
+}
+
+asset.onInitialize(function()
+  openspace.addSceneGraphNode(Node)
+end)
+
+asset.onDeinitialize(function()
+  openspace.removeSceneGraphNode(Node)
+end)

modules/globebrowsing/src/tileprovider/tileproviderbylevel.cpp

@@ -27,11 +27,28 @@
 #include <openspace/documentation/documentation.h>
 
 namespace {
+    // This tile provider will switch between different tile providers specified within
+    // based on the level of detail that is requested by the Globe. All other things being
+    // equal, this corresponds to the distance of the camera to the planet, with a closer
+    // distance resulting in a higher lever. Due to technical reasons, the available
+    // levels are in the range [2, 22] and each increase in levels corresponds to a
+    // doubling in the effective resolution. For a given requested level, the tile
+    // provider that has the largest `MaxLevel` that is not greater than the requested
+    // level will be used.
     struct [[codegen::Dictionary(TileProviderByLevel)]] Parameters {
+        // Each collection describes a distinct layer which can be toggled at a specified
+        // max level at which it is requested.
         struct Provider {
+            // The maximum level until which the tile provider is used. This number is
+            // inclusive, meaning that a value of 4 causes the tile provider to be used
+            // at level 4 but not at level 5.
             int maxLevel [[codegen::greaterequal(0)]];
-            ghoul::Dictionary tileProvider;
+
+            // The tile provider that should be used at this stage.
+            ghoul::Dictionary tileProvider [[codegen::reference("globebrowsing_layer")]];
         };
+
+        // The list of all tile providers that are used by this TileProviderByLevel.
         std::vector<Provider> levelTileProviders;
     };
 #include "tileproviderbylevel_codegen.cpp"