Allow customizing OOB tiles in level_bgs_*

* Improve example to showcase this

Author: copyrat90

examples/parallax_level_bgs/src/main.cpp

@@ -9,6 +9,7 @@
 #include "ldtk_gen_idents.h"
 #include "ldtk_gen_project.h"
 
+#include <bn_assert.h>
 #include <bn_backdrop.h>
 #include <bn_blending.h>
 #include <bn_camera_ptr.h>
@@ -31,6 +32,7 @@ int main()
         "PAD: move camera",
         "A: toggle all layer bgs visibility",
         "B: toggle top layer bg visibility",
+        "L: toggle bottom layer oob tile",
     };
 
     bn::sprite_text_generator big_text_generator(common::variable_8x16_sprite_font);
@@ -75,6 +77,38 @@ int main()
             }
         }
 
+        if (bn::keypad::l_pressed())
+        {
+            // You MUST check if `level_bgs` has the background of the layer before calling gettes/setters;
+            // If `tiles_layer_8` doesn't have a single visible tile, it doesn't generate a BG, so it will error out.
+            if (level_bgs.has_background(ldtk::gen::layer_ident::tiles_layer_8))
+            {
+                ldtk::tile_grid_base::tile_info oob_tile_info =
+                    level_bgs.out_of_bound_tile_info(ldtk::gen::layer_ident::tiles_layer_8);
+
+                // Tile index `0` is always a valid tile index, which denotes a fully transparent tile.
+                if (oob_tile_info.index == 0)
+                {
+                    // Get the tile grid from the `tiles_layer_8` layer.
+                    // If `tiles_layer_8` was an auto-tile layer, you need to use `auto_layer_tiles()` instead.
+                    const ldtk::tile_grid_base* tile_grid =
+                        level.get_layer(ldtk::gen::layer_ident::tiles_layer_8).grid_tiles();
+                    BN_ASSERT(tile_grid != nullptr, "Layer is not a tile layer");
+
+                    // Set the tile to the same one as the top-left(x=0, y=0) tile in the grid.
+                    oob_tile_info = tile_grid->cell_tile_info(0, 0);
+                }
+                else // OOB tile was previously non-transparent
+                {
+                    // Set it to transparent again
+                    oob_tile_info.index = 0;
+                }
+
+                // Apply the OOB tile change
+                level_bgs.set_out_of_bound_tile_info(oob_tile_info, ldtk::gen::layer_ident::tiles_layer_8);
+            }
+        }
+
         static constexpr bn::fixed CAMERA_MOVE_SPEED = 4.0f;
 
         if (bn::keypad::left_held())

include/ldtk_level_bgs_builder.h

@@ -5,6 +5,7 @@
 
 #include "ldtk_gen_idents_fwd.h"
 #include "ldtk_level_bgs_ptr.h"
+#include "ldtk_tile_grid_base.h"
 
 #include <bn_camera_ptr.h>
 #include <bn_config_bgs.h>
@@ -394,6 +395,20 @@ class level_bgs_builder
     /// @brief Releases and returns the camera_ptr to attach to the level backgrounds to generate (if any).
     [[nodiscard]] auto release_camera() -> bn::optional<bn::camera_ptr>;
 
+    /// @brief Returns the tile info that fills the out-of-bound region of a level background.
+    /// @note Before calling this, you @b must make sure `has_background()` returns `true`.
+    /// @param layer_identifier identifier of the layer to get the tile info from.
+    [[nodiscard]] auto out_of_bound_tile_info(gen::layer_ident layer_identifier) const -> tile_grid_base::tile_info;
+
+    /// @brief Sets the tile info that fills the out-of-bound region of a level background.
+    /// @note Before calling this, you @b must make sure `has_background()` returns `true`. \n
+    /// Also, you @b must use the valid tile index for the background.
+    /// @param tile_info tile info to fill the out-of-bound region of a level background.
+    /// @param layer_identifier identifier of the layer to set the tile info to.
+    /// @return Reference to `this`.
+    auto set_out_of_bound_tile_info(tile_grid_base::tile_info oob_tile_info, gen::layer_ident layer_identifier)
+        -> level_bgs_builder&;
+
     /// @brief Generates and returns a `level_bgs_ptr` without releasing the acquired resources.
     [[nodiscard]] auto build() const -> level_bgs_ptr;
 
@@ -425,6 +440,8 @@ class level_bgs_builder
         bn::green_swap_mode green_swap_mode = bn::green_swap_mode::DEFAULT;
         bool mosaic_enabled = false;
         bool blending_bottom_enabled = true;
+
+        tile_grid_base::tile_info oob_tile_info = {.index = 0, .x_flip = false, .y_flip = false};
     };
     /// @endcond
 

include/ldtk_level_bgs_ptr.h

@@ -4,6 +4,7 @@
 #pragma once
 
 #include "ldtk_gen_idents_fwd.h"
+#include "ldtk_tile_grid_base.h"
 
 #include <bn_camera_ptr.h>
 #include <bn_fixed_point.h>
@@ -398,6 +399,18 @@ class level_bgs_ptr
     /// @brief Removes the `bn::camera_ptr` attached to these level backgrounds (if any).
     void remove_camera();
 
+    /// @brief Returns the tile info that fills the out-of-bound region of a level background.
+    /// @note Before calling this, you @b must make sure `has_background()` returns `true`.
+    /// @param layer_identifier identifier of the layer to get the tile info from.
+    [[nodiscard]] auto out_of_bound_tile_info(gen::layer_ident layer_identifier) const -> tile_grid_base::tile_info;
+
+    /// @brief Sets the tile info that fills the out-of-bound region of a level background.
+    /// @note Before calling this, you @b must make sure `has_background()` returns `true`. \n
+    /// Also, you @b must use the valid tile index for the background.
+    /// @param oob_tile_info tile info to fill the out-of-bound region of a level background.
+    /// @param layer_identifier identifier of the layer to set the tile info to.
+    void set_out_of_bound_tile_info(tile_grid_base::tile_info oob_tile_info, gen::layer_ident layer_identifier);
+
 public:
     /// @brief Returns the internal handle.
     [[nodiscard]] const auto handle() const -> void*

src/ldtk_level_bgs_builder.cpp.h

@@ -217,6 +217,18 @@ auto level_bgs_builder::release_camera() -> bn::optional<bn::camera_ptr>
     return result;
 }
 
+auto level_bgs_builder::out_of_bound_tile_info(gen::layer_ident layer_identifier) const -> tile_grid_base::tile_info
+{
+    return bg_attr(layer_identifier).oob_tile_info;
+}
+
+auto level_bgs_builder::set_out_of_bound_tile_info(tile_grid_base::tile_info oob_tile_info,
+                                                   gen::layer_ident layer_identifier) -> level_bgs_builder&
+{
+    bg_attr(layer_identifier).oob_tile_info = oob_tile_info;
+    return *this;
+}
+
 auto level_bgs_builder::build() const -> level_bgs_ptr
 {
     return level_bgs_ptr::create(*this);

src/ldtk_level_bgs_manager.cpp

@@ -51,11 +51,14 @@ struct bg_t
     const layer& layer_instance;
     const tile_grid_base& grid;
 
+    tile_grid_base::tile_info oob_tile;
+
     alignas(int) bn::regular_bg_map_cell cells[ROWS * COLUMNS];
     bn::regular_bg_map_item map_item;
     bn::regular_bg_ptr bg_ptr;
     bn::regular_bg_map_ptr map_ptr;
     bool next_visible;
+    bool force_reload;
     bool grid_bloated;
 
     bg_t(const level& lv_, const layer& layer_, const bn::fixed_point& cam_applied_pos, const level_bgs_builder&);
@@ -156,18 +159,20 @@ bg_t::bg_t(const level& lv_, const layer& layer_, const bn::fixed_point& cam_app
            const level_bgs_builder& builder)
     : lv(lv_), layer_instance(layer_),
       grid(layer_.auto_layer_tiles() ? *layer_.auto_layer_tiles() : *layer_.grid_tiles()),
-      map_item(cells[0], bn::size(COLUMNS, ROWS)), bg_ptr(init_bg_ptr(layer_, cam_applied_pos, builder)),
-      map_ptr(bg_ptr.map()), next_visible(bg_ptr.visible()), grid_bloated(grid.bloated())
+      oob_tile(builder.out_of_bound_tile_info(layer_.identifier())), map_item(cells[0], bn::size(COLUMNS, ROWS)),
+      bg_ptr(init_bg_ptr(layer_, cam_applied_pos, builder)), map_ptr(bg_ptr.map()), next_visible(bg_ptr.visible()),
+      force_reload(false), grid_bloated(grid.bloated())
 {
 }
 
 void bg_t::update(const bn::fixed_point& next_cam_applied_pos, const bn::fixed_point& prev_cam_applied_pos)
 {
     if (next_visible)
     {
-        if (!bg_ptr.visible())
+        if (force_reload || !bg_ptr.visible())
         {
             update_all_cells(next_cam_applied_pos);
+            force_reload = false;
         }
         // Update cells when level position changed
         else if (next_cam_applied_pos != prev_cam_applied_pos)
@@ -300,9 +305,9 @@ void bg_t::reset_rows(const int level_8x8_first_y, const int level_8x8_last_y, c
 
             if (mx < 0 || mx >= grid.c_width() || my < 0 || my >= grid.c_height())
             {
-                m_tile_info.index = 0;
-                m_tile_info.x_flip = false;
-                m_tile_info.y_flip = false;
+                m_tile_info.index = oob_tile.index;
+                m_tile_info.x_flip = oob_tile.x_flip;
+                m_tile_info.y_flip = oob_tile.y_flip;
             }
             else
             {
@@ -380,9 +385,9 @@ void bg_t::reset_columns(const int level_8x8_first_y, const int level_8x8_last_y
 
             if (mx < 0 || mx >= grid.c_width() || my < 0 || my >= grid.c_height())
             {
-                m_tile_info.index = 0;
-                m_tile_info.x_flip = false;
-                m_tile_info.y_flip = false;
+                m_tile_info.index = oob_tile.index;
+                m_tile_info.x_flip = oob_tile.x_flip;
+                m_tile_info.y_flip = oob_tile.y_flip;
             }
             else
             {
@@ -872,4 +877,18 @@ void remove_camera(id_t id)
     lv->cam.reset();
 }
 
+auto out_of_bound_tile_info(id_t id, gen::layer_ident layer_identifier) -> tile_grid_base::tile_info
+{
+    auto lv = static_cast<const lv_t*>(id);
+    return lv->get_bg(layer_identifier).oob_tile;
+}
+
+void set_out_of_bound_tile_info(id_t id, tile_grid_base::tile_info oob_tile_info, gen::layer_ident layer_identifier)
+{
+    auto lv = static_cast<lv_t*>(id);
+    auto& bg = lv->get_bg(layer_identifier);
+    bg.oob_tile = oob_tile_info;
+    bg.force_reload = true;
+}
+
 } // namespace ldtk::level_bgs_manager

src/ldtk_level_bgs_manager.h

@@ -4,6 +4,7 @@
 #pragma once
 
 #include "ldtk_gen_idents_fwd.h"
+#include "ldtk_tile_grid_base.h"
 
 #include <bn_fixed.h>
 #include <bn_fixed_point_fwd.h>
@@ -121,6 +122,10 @@ void set_camera(id_t id, bn::camera_ptr&& camera);
 
 void remove_camera(id_t id);
 
+[[nodiscard]] auto out_of_bound_tile_info(id_t id, gen::layer_ident layer_identifier) -> tile_grid_base::tile_info;
+
+void set_out_of_bound_tile_info(id_t id, tile_grid_base::tile_info oob_tile_info, gen::layer_ident layer_identifier);
+
 } // namespace level_bgs_manager
 
 } // namespace ldtk

src/ldtk_level_bgs_ptr.cpp.h

@@ -414,4 +414,15 @@ void level_bgs_ptr::remove_camera()
     level_bgs_manager::remove_camera(_handle);
 }
 
+auto level_bgs_ptr::out_of_bound_tile_info(gen::layer_ident layer_identifier) const -> tile_grid_base::tile_info
+{
+    return level_bgs_manager::out_of_bound_tile_info(_handle, layer_identifier);
+}
+
+void level_bgs_ptr::set_out_of_bound_tile_info(tile_grid_base::tile_info oob_tile_info,
+                                               gen::layer_ident layer_identifier)
+{
+    level_bgs_manager::set_out_of_bound_tile_info(_handle, oob_tile_info, layer_identifier);
+}
+
 } // namespace ldtk