Customizable out-of-bound tiles for ldtk::level_bgs_ptr

[copyrat90]

When ldtk::level_bgs_ptr tries to show the level tiles from the out-of-bound area, currently it just shows the empty tile:

butano-ldtk/src/ldtk_level_bgs_manager.cpp

Lines 301 to 306 in f255a34

	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;
	}

Which is the same behavior of LDtk's "foreground" parallax layer.

But, individual games might want to show tiles other than empty tile for the OOB ones.

1. They might want to show the filled wall tiles.
2. They might want to show the wrapped tiles.
   • The same behavior as bn::regular_bg_ptr, and bn::affine_bg_ptr when wrapping is enabled.

If I want to support both of these use-case, I need to design the API carefully to not confuse the users.
Or maybe I could just BN_ASSERT that both options are not enabled at the same time.

[copyrat90]

1. They might want to show the filled wall tiles for OOB ones.

This first feature was easy to implement:

butano-ldtk/src/ldtk_level_bgs_manager.cpp

Lines 306 to 311 in 005dd1f

	if (mx < 0 || mx >= grid.c_width() || my < 0 || my >= grid.c_height())
	{
	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;
	}

The APIs expect the user to set the valid OOB tile as ldtk::tile_grid_base::tile_info:

• level_bgs_ptr::set_out_of_bound_tile_info()
• level_bgs_builder::set_out_of_bound_tile_info()

Unfortunately, there's no support for tile fields, so it's not very intuitive to where to get this info from.
You could get this OOB tile info from:

1. Somewhere in the tile grid (or auto layer grid).
   • This was what I did in the example code:
     

     butano-ldtk/examples/parallax_level_bgs/src/main.cpp

     Lines 92 to 99 in 005dd1f

     	// 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);

2. Attach a custom data to the tile, and search it.
   • This is more complex and slower, but it won't rely on the grid contents

---

The wrapped tile might be a little bit more tricky to implement, as I want to avoid divmod cost if possible.
And currently I don't need it, so I'll do it later when someone needs it.

[copyrat90]

GValiente suggested this idea: Allow wrapping only for power of two level sizes.
Which would let you use cheap bitwise AND operation, instead of expensive modulo.

That's at least an improvement from not supporting wrapping at all.

What could go wrong?

• What if the user enables the wrapping and switches a level with ldtk::level_bgs_ptr::set_level() with a non power of two sized level?
  • I guess this one is a user's fault.