From 9ffcf494b94cc02d0b057f1f03b4ba1307d9404e Mon Sep 17 00:00:00 2001
From: Chinedu Francis Nwafili <frankie.nwafili@gmail.com>
Date: Tue, 27 Apr 2021 01:53:22 -0400
Subject: [PATCH] Move background behind details arrow.

A bit long to keep in the top level of the README.
---
 README.md  | 30 +++++++++++++++++++++++++++++-
 src/lib.rs | 17 ++++++++++++++---
 2 files changed, 43 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 4c9093c..db09128 100644
--- a/README.md
+++ b/README.md
@@ -87,7 +87,7 @@ target_bins.insert(MyCustomBinId::DestinationBinTwo, TargetBin::new(4096, 4096,
 // Information about where each `MyCustomRectId` was placed
 let rectangle_placements = pack_rects(
     &rects_to_place,
-    target_bins,
+    &mut target_bins,
     &volume_heuristic,
     &contains_smallest_box
 ).unwrap();
@@ -97,6 +97,22 @@ let rectangle_placements = pack_rects(
 
 ## Background / Initial Motivation
 
+<details>
+<summary>
+Click to show the initial motivation for the library.
+
+In my application I've switched to dynamically placing textures into atlases at runtime
+instead of in how I previously used an asset compilation step, so some of the problems
+explained here are now moot.
+
+I still use rectangle-pack to power my runtime texture allocation, though,
+along with a handful of other strategies depending on the nature of the
+textures that need to be placed into the atlas.
+
+rectangle-pack knows nothing about textures, so you can use it for any form of bin
+packing, whether at runtime, during an offline step or any other time you like.
+</summary>
+
 I'm working on a game with some of the following texture atlas requirements (as of March 2020):
 
 - I need to be able to guarantee that certain textures are available in the same atlas.
@@ -139,6 +155,9 @@ The API shouldn't know about the specifics of any of these requirements - it sho
 > Given these rectangles that need to be placed, the maximum sizes of the target bins to place them in and some criteria about how to place and how not to place them,
 > where can I put all of these rectangles?
 
+</details>
+<p></p>
+
 ## Features
 
 - Place any number of 2d / 3d rectangles into any number of 2d / 3d target bins.
@@ -208,6 +227,15 @@ support our goal of flexibly supporting all use cases.
 
 - There is a third dimension.
 
+## In The Wild
+
+Here are some known production users of `rectangle-pack`.
+
+- [Akigi](https://akigi.com) uses `rectangle-pack` to power parts of its runtime texture allocation strategy.
+
+- [Bevy](https://github.com/bevyengine/bevy/blob/9ae56e860468aa3158a702cbcf64e511b84a4b1c/crates/bevy_sprite/Cargo.toml#L29) uses `rectangle-pack`
+  to create texture atlases.
+
 ## Contributing
 
 If you have a use case that isn't supported, a question, a patch, or anything else, go right ahead and open an issue or submit a pull request.
diff --git a/src/lib.rs b/src/lib.rs
index 9176516..26a89a0 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -34,6 +34,8 @@ mod box_size_heuristics;
 /// ## Example
 ///
 /// ```
+/// //! A basic example of packing rectangles into target bins
+///
 /// use rectangle_pack::{
 ///     GroupedRectsToPlace,
 ///     RectToInsert,
@@ -42,9 +44,11 @@ mod box_size_heuristics;
 ///     volume_heuristic,
 ///     contains_smallest_box
 /// };
-/// use std::collections::{BTreeMap};
+/// use std::collections::BTreeMap;
 ///
-/// // A rectangle ID just needs to meet these trait bounds (ideally also Copy)
+/// // A rectangle ID just needs to meet these trait bounds (ideally also Copy).
+/// // So you could use a String, PathBuf, or any other type that meets these
+/// // trat bounds. You do not have to use a custom enum.
 /// #[derive(Debug, Hash, PartialEq, Eq, Clone, Ord, PartialOrd)]
 /// enum MyCustomRectId {
 ///     RectOne,
@@ -53,6 +57,8 @@ mod box_size_heuristics;
 /// }
 ///
 /// // A target bin ID just needs to meet these trait bounds (ideally also Copy)
+/// // So you could use a u32, &str, or any other type that meets these
+/// // trat bounds. You do not have to use a custom enum.
 /// #[derive(Debug, Hash, PartialEq, Eq, Clone, Ord, PartialOrd)]
 /// enum MyCustomBinId {
 ///     DestinationBinOne,
@@ -61,8 +67,13 @@ mod box_size_heuristics;
 ///
 /// // A placement group just needs to meet these trait bounds (ideally also Copy).
 /// //
-/// // Groups are optional - they allow you to ensure that a set of rectangles will be placed
+/// // Groups allow you to ensure that a set of rectangles will be placed
 /// // into the same bin. If this isn't possible an error is returned.
+/// //
+/// // Groups are optional.
+/// //
+/// // You could use an i32, &'static str, or any other type that meets these
+/// // trat bounds. You do not have to use a custom enum.
 /// #[derive(Debug, Hash, PartialEq, Eq, Clone, Ord, PartialOrd)]
 /// enum MyCustomGroupId {
 ///     GroupIdOne