Struct TargetBin

pub struct TargetBin { /* private fields */ }

A bin that we’d like to play our incoming rectangles into

Implementations

impl TargetBin

pub fn coalesce_available_sections( _bin_section_index: usize, _compare_to_indices: Range<usize>, )

Over time as you use TargetBin.push_available_bin_section to return remove packed rectangles from the TargetBin, you may end up with neighboring bin sections that can be combined into a larger bin section.

Combining bin sections in this was is desirable because a larger bin section allows you to place larger rectangles that might not fit into the smaller bin sections.

In order to coalesce, or combine a bin section with other bin sections, we need to check every other available bin section to see if they are neighbors.

This means that fully coalescing the entire list of available bin sections is O(n^2) time complexity, where n is the number of available empty sections.

Basic Usage

let target_bin = my_target_bin();

for idx in 0..target_bin.available_bin_sections().len() {
    let len = target_bin.available_bin_sections().len();
    target_bin.coalesce_available_sections(idx, 0..len);
}

Distributing the Workload

It is possible that you are developing an application that can in some cases have a lot of heavily fragmented bins that need to be coalesced. If your application has a tight performance budget, such as a real time simulation, you may not want to do all of your coalescing at once.

This method allows you to split the work over many frames by giving you fine grained control over which bin sections is getting coalesced and which other bin sections it gets tested against.

So, for example, say you have an application where you want to fully coalesce the entire bin every ten seconds, and you are running at 60 frames per second. You would then distribute the coalescing work such that it would take 600 calls to compare every bin section.

Here’s a basic eample of splitting the work.

let target_bin = my_target_bin();

let current_frame: usize = get_current_frame() % 600;

for idx in 0..target_bin.available_bin_sections().len() {
    let len = target_bin.available_bin_sections().len();

    let start = len / 600 * current_frame;
    let end = start + len / 600;

    target_bin.coalesce_available_sections(idx, start..end);
}

impl TargetBin

pub fn push_available_bin_section( &mut self, bin_section: BinSection, ) -> Result<(), PushBinSectionError>

Push a BinSection to the list of remaining BinSection’s that rectangles can be placed in.

Performance

This checks that your BinSection does not overlap any other bin sections. In many cases this will be negligible, however it is important to note that this has a worst case time complexity of O(Width * Height * Depth), where the worst case is tht you have a bin full of 1x1x1 rectangles.

To skip the validity checks use TargetBin.push_available_bin_section_unchecked.

pub fn push_available_bin_section_unchecked(&mut self, bin_section: BinSection)

Push a BinSection to the list of remaining BinSection’s that rectangles can be placed in, without checking whether or not it is valid.

Use TargetBin.push_available_bin_section if you want to check that the new bin section does not overlap any existing bin sections nad that it is within the TargetBin’s bounds.

impl TargetBin

pub fn new(max_width: u32, max_height: u32, max_depth: u32) -> Self

pub fn available_bin_sections(&self) -> &Vec<BinSection>

The free BinSections within the TargetBin that rectangles can still be placed into.

pub fn remove_filled_section(&mut self, idx: usize)

Remove the section that was just split by a placed rectangle.

pub fn add_new_sections(&mut self, new_sections: [BinSection; 3])

When a section is filled it gets split into three new sections. Here we add those.

TODO: Ignore sections with a volume of 0

Trait Implementations

impl Clone for TargetBin

fn clone(&self) -> TargetBin

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TargetBin

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.