Module broccoli::collections

Container trees that deref to Tree

The relationships between Tree types:

TreeOwned -> TreeRef --> Tree
TreeOwnedInd -> TreeRefInd --> TreeRef --> Tree

where:
--> = Deref
-> = Function

TreeRef, like Tree, can be composed of anything that implements Aabb. TreeRefInd is composed of BBox<N,&mut T>

Overview

Tree is written in safe rust, and for most usecases, using Tree is enough. But in certain cases we want more control. The container trees in this module are for this purpose.

For example, with the regular Tree, you can't get access to the unerlying list of elements after the tree has been constructed.

use broccoli::{prelude::*,bbox,rect};
let mut k=[bbox(rect(0,10,0,10),8)];
let mut b=broccoli::new(&mut k);
b.find_colliding_pairs_mut(|a,b|{});
// k[0].inner=4;    //<---cannot re-borrow

This is because Tree constructs itself by splitting up the passed mutable slice to the point where the original mutable slice can't be retrieved.

If we use TreeRef, we can do the above like this:

use broccoli::{prelude::*,bbox,rect};
let mut k=[bbox(rect(0,10,0,10),8)];
let mut b=broccoli::collections::TreeRef::new(&mut k);
b.find_colliding_pairs_mut(|a,b|{});
*b.get_bbox_elements_mut().get_index_mut(0).inner_mut()=5;
b.find_colliding_pairs_mut(|a,b|{});

This is good and all, but having to work around the PMut pointer that protect the invariants of the tree is cumbersome. To get around that we can use TreeRefInd which adds a layer of indirection.

Unintuitively, this version that adds a layer of indirection is typically faster. Check the crate's book for more analysis. This does have some drawbacks in the sense that it uses more memory, as the aabbs are copied. Additionally, TreeRefInd provides collect functions that allow storing query results that can then be iterated through multiple times quickly.

use broccoli::{prelude::*,bbox,rect};
let mut k=[0];
let mut b=broccoli::collections::TreeRefInd::new(&mut k,|&mut d|rect(d,d,d,d));
b.find_colliding_pairs_mut(|a,b|{});
b.get_elements_mut()[0]=5;
b.find_colliding_pairs_mut(|a,b|{});

TreeRef and TreeRefInd are both lifetimed. If you want to store the tree inside an object there are TreeOwned and TreeOwnedInd equivalents.

An owned (Rect<N>,T) example

use broccoli::{BBox,bbox,rect,prelude::*,collections::*,DefaultA};

fn not_lifetimed()->TreeOwned<DefaultA,BBox<i32,f32>>
{
    let a=vec![bbox(rect(0,10,0,10),0.0)].into_boxed_slice();
    TreeOwned::new(a)
}

not_lifetimed();

An owned (Rect<N>,*mut T) example

use axgeom::*;
use broccoli::{*,collections::*,DefaultA};

fn not_lifetimed()->TreeOwnedInd<DefaultA,i32,Vec2<i32>>
{
    let rect=vec![vec2(0,10),vec2(3,30)].into_boxed_slice();
    TreeOwnedInd::new(rect,|&mut p|{
        let radius=vec2(10,10);
        Rect::from_point(p,radius)
    })
}

not_lifetimed();

Structs

CollidingPairs	CollidingPairs created via TreeRefInd::collect_colliding_pairs
CollidingPairsPar	CollidingPairsPar created via TreeRefInd::collect_colliding_pairs_par All colliding pairs partitioned into mutually exclusive sets so that they can be traversed in parallel
FilteredElements	Contains a filtered list of all elements in the tree from calling TreeRefInd::collect_all.
TreeOwned	See module documentation.
TreeOwnedInd	See module documentation.
TreeRef	See module documentation.
TreeRefInd	See module documentation.