Name Description Size
allocator.rs 38994
bucketed.rs 36205
ffi.rs 3808
lib.rs Dynamic texture atlas allocation using the shelf packing algorithm. ## Texture atlas allocation The goal of a texture atlas allocator is to pack multiple rectangles into a larger one. When rendering 2D or 3D graphics on the GPU, this packing important for draw call batching. This crate provides two implementations of the shelf packing algorithm for *dynamic* texture atlas allocation (dynamic here means supporting both allocation and deallocation). [A thousand ways to pack the bin](https://github.com/juj/RectangleBinPack/blob/master/RectangleBinPack.pdf) is a good resource to learn about rectangle packing algorithms, although it does not not cover deallocation which complicates the problem space a fair bit. The shelf packing algorithm is explained in the above document. It isn't the most efficient packing strategy, however its simplicity makes it possible to support reasonably fast deallocation. Note that the [guillotiere](https://crates.io/crates/guillotiere) crate implements a similar API using the guillotine packing algorithm and may or may not provide better results depending on the type of workload. ## Two allocators - [`AtlasAllocator`] Tracks allocations for each individual item and does a reasonable job of dealing with fragmentation, at a runtime cost. - [`BucketedAtlasAllocator`] groups items by buckets and only reclaim the space occupied by a bucket when all of its items are deallocated. In addition, it has limited support for merging consecutive empty shelves. These limitations allow faster allocation and deallocation, making it an appealing option when the atlas is expected to hold a very large amount of small items. Both allocators support: - Requiring an alignment for the items. - Packing into vertical shelves instead of horizontal ones (might provide a better output for some workloads). - Splitting the allocator into multiple columns in order to make shelves smaller and allow more of them. - Dumping the content of the atlas in SVG format for easy debugging. See [`AllocatorOptions`](struct.AllocatorOptions.html) In addition, this repository contains a command-line application to experiment with and test the implementations interactively. ## Example ```rust use etagere::*; let mut atlas = AtlasAllocator::new(size2(1000, 1000)); let a = atlas.allocate(size2(100, 100)).unwrap(); let b = atlas.allocate(size2(900, 200)).unwrap(); println!("Allocated {:?} and {:?}", a.rectangle, b.rectangle); atlas.deallocate(a.id); let c = atlas.allocate(size2(300, 200)).unwrap(); atlas.deallocate(c.id); atlas.deallocate(b.id); ``` ## License Licensed under either of * Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0) * MIT license ([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT) at your option. [`AtlasAllocator`]: struct.AtlasAllocator.html [`BucketedAtlasAllocator`]: struct.BucketedAtlasAllocator.html 5507