Struct forma_render::Composition

pub struct Composition { /* private fields */ }

A composition is an ordered collection of Layers. It is the only means through which content can be rendered.

The composition works similarly to a HashMap<Order, Layer>.

Examples

let mut composition = Composition::new();

let layer0 = composition.create_layer();
let layer1 = composition.create_layer();

assert!(composition.insert(Order::new(0).unwrap(), layer0).is_none());
assert!(composition.insert(Order::new(0).unwrap(), layer1).is_some()); // Some(layer0)

Implementations

impl Composition

pub fn new() -> Self

Creates a new composition.

Examples

let composition = Composition::new();

assert!(composition.is_empty());

pub fn create_layer(&mut self) -> Layer

Creates a new Layer which is enabled by default.

Examples

let mut composition = Composition::new();

let _layer = composition.create_layer();

pub fn is_empty(&self) -> bool

Checks if the composition is empty.

Examples

let composition = Composition::new();

assert!(composition.is_empty());

pub fn len(&self) -> usize

Returns the numbers of Layers in this composition.

Examples

let composition = Composition::new();

assert_eq!(composition.len(), 0);

pub fn insert(&mut self, order: Order, layer: Layer) -> Option<Layer>

Inserts a layer at specified order and optionally returns the layer already at order if any.

Examples

let mut composition = Composition::new();

let mut layer0 = composition.create_layer();
let layer1 = composition.create_layer();

layer0.disable();

assert!(composition.insert(Order::new(0).unwrap(), layer0).is_none());

match composition.insert(Order::new(0).unwrap(), layer1) {
    Some(layer0) if !layer0.is_enabled() => (),
    _ => unreachable!(),
}

pub fn remove(&mut self, order: Order) -> Option<Layer>

Removes a layer at specified order and optionally returns the layer already at order if any.

Examples

let mut composition = Composition::new();

let layer0 = composition.create_layer();
let layer1 = composition.create_layer();

assert!(composition.insert(Order::new(0).unwrap(), layer0).is_none());
assert!(composition.insert(Order::new(0).unwrap(), layer1).is_some()); // Some(layer0)

pub fn get_order_if_stored(&self, geom_id: GeomId) -> Option<Order>

Optionally recover the order of presently-stored Layer by its geom_id. Bear in mind that clearing its geometry will reset the ID which will need to be refreshed.

Examples

let mut composition = Composition::new();

let layer = composition.create_layer();

let id0 = layer.geom_id();
let order = Order::new(0).unwrap();

assert_eq!(composition.get_order_if_stored(id0), None);

// Post-insertion, the geometry is accessible by ID.
composition.insert(Order::new(0).unwrap(), layer);
assert_eq!(composition.get_order_if_stored(id0), Some(order));

let layer = composition.get_mut(order).unwrap();

layer.clear();

let id1 = layer.geom_id();

assert_ne!(id0, id1);

// Old ID canot be use any longer.
assert_eq!(composition.get_order_if_stored(id0), None);

// Since is has not been removed, the geometry is still accessible by ID.
assert_eq!(composition.get_order_if_stored(id1), Some(order));

// Post-remove, the geometry is no longer accessible.
composition.remove(order);
assert_eq!(composition.get_order_if_stored(id1), None);

pub fn get(&self, order: Order) -> Option<&Layer>

Optionally returns a reference to the layer stored at specified order.

Examples

let mut composition = Composition::new();

let layer = composition.create_layer();
let order = Order::new(0).unwrap();

composition.insert(order, layer);

assert!(composition.get(order).is_some());

pub fn get_mut(&mut self, order: Order) -> Option<&mut Layer>

Optionally returns a mutable reference to the layer stored at specified order.

Examples

let mut composition = Composition::new();

let layer = composition.create_layer();
let order = Order::new(0).unwrap();

composition.insert(order, layer);

assert!(composition.get_mut(order).is_some());

pub fn get_mut_or_insert_default(&mut self, order: Order) -> &mut Layer

Creates and inserts a default layer into the composition, returning a mutable reference to it. it is a combined form of Self::create_layer and Self::insert/Self::get_mut.

It is especially useful when wanting to update a specific layer for multiple frames.

Examples

let mut composition = Composition::new();

let line = PathBuilder::new().line_to(Point::new(10.0, 10.0)).build();

composition.get_mut_or_insert_default(Order::new(0).unwrap()).insert(&line);

pub fn layers(&self) -> impl ExactSizeIterator<Item = (Order, &Layer)> + '_

Returns an ExactSizeIterator over all order/layer reference pairs.

Examples

let mut composition = Composition::new();

composition.get_mut_or_insert_default(Order::new(0).unwrap());
composition.get_mut_or_insert_default(Order::new(1).unwrap());

assert_eq!(composition.layers().count(), 2);

pub fn layers_mut(
    &mut self
) -> impl ExactSizeIterator<Item = (Order, &mut Layer)> + '_

Returns an ExactSizeIterator over all order/mutable layer reference pairs.

Examples

let mut composition = Composition::new();

composition.get_mut_or_insert_default(Order::new(0).unwrap());
composition.get_mut_or_insert_default(Order::new(1).unwrap());

assert_eq!(composition.layers_mut().count(), 2);

pub fn compact_geom(&mut self)

Forces the composition to run geometry garbage collection if more than half the memory occupied by it is not accessible anymore by the end-user. (i.e. by Layer::clear or Layer::drop)

Examples

let mut composition = Composition::new();

// Insertions and removals/clears happen here.

composition.compact_geom();

Trait Implementations

impl Debug for Composition

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

Formats the value using the given formatter.

impl Default for Composition

fn default() -> Composition

Returns the “default value” for a type.