Struct ascending_graphics::AtlasSet

pub struct AtlasSet<U: Hash + Eq + Clone = String, Data: Copy + Default = i32> {

    pub texture: Texture,
    pub texture_view: TextureView,
    pub layers: Vec<Atlas>,
    pub extent: Extent3d,
    pub store: Slab<(Allocation<Data>, U)>,
    pub lookup: HashMap<U, usize>,
    pub cache: LruCache<usize, usize>,
    pub last_used: HashSet<usize>,
    pub format: TextureFormat,
    pub max_layers: usize,
    pub deallocations_limit: usize,
    pub layer_check_limit: usize,
    pub layer_free_limit: usize,
    pub use_ref_count: bool,
    pub texture_group: TextureGroup,
}

AtlasSet is used to hold and contain the data of many Atlas layers. Each Atlas keeps track of the allocations allowed. Each allocation is a given Width/Height as well as Position that a Texture image can fit within the atlas.

We try to use Store to keep all Allocations localized so if they need to be unloaded, migrated or replaced then the system can prevent improper rendering using a outdated Allocation. We will also attempt to keep track of reference counts loading the Index and try to keep track of LRU cache and a list of last used Indexs. This will help reduce errors and can help to reduce Vram and Later Reduce Fragmentation of the Atlas.

FRAGMENTATION************* Fragmentation of a Atlas is when you Deallocate and Allocate new image textures into the Atlas. As this occurs there is a possibility that Small spots that can not be used in the Atlas to appear. These small Sections might get merged into larger Sections upon Deallocation of neighboring Allocations, But in some Cases these might over run the Atlas cuasing use to use way more Vram than is needed. To fix this we must migrate all loaded Allocations to a new Atlas and either move the old atlas to the back of the list for reuse or unload it. We can accomplish knowing when to migrate the atlas by setting a deallocations_limit. We also can know when to unload a empty layer by using the layer_free_limit. This will allow us to control VRam usage.

TODO Keep track of Indexs within an Atlas. TODO Create Migration Check function. TODO Add way to tell if any texture needs to migrate. TODO Add limitations to a migrating texture so we only move a bit at a time. TODO Add Ability to Tell user through API that Vertexs and Indicies need to be TODO reloaded upon migration changes.

Fields

texture: Texture

Texture in GRAM

texture_view: TextureView

Texture View for WGPU

layers: Vec<Atlas>

Layers of texture.

extent: Extent3d

Holds the Original Texture Size and layer information.

store: Slab<(Allocation<Data>, U)>

Store the Allocations se we can easily remove and update them. use a Generation id to avoid conflict if users use older allocation id’s. Also stores the Key associated with the Allocation.

lookup: HashMap<U, usize>

for key to index lookups.

cache: LruCache<usize, usize>

keeps a list of least used allocations so we can unload them when need be. Also include the RefCount per ID lookup. we use this to keep track of when Fonts need to be unloaded. this only helps to get memory back but does not fix fragmentation of the Atlas.

last_used: HashSet<usize>

List of allocations used in the last frame to ensure we dont unload what is in use.

format: TextureFormat

Format the Texture uses.

max_layers: usize

When the System will Error if reached. This is the max allowed Layers Default is 256 as Most GPU allow a max of 256.

deallocations_limit: usize

Limit of deallocations allowed before we attempt to migrate the textures allocations to fix fragmentation. TODO Think of better way to figure out fragmentations.

layer_check_limit: usize

amount of layers in memory before we start checking for fragmentations.

layer_free_limit: usize

When we should free empty layers. this must be more than 1 otherwise will cause issues.

use_ref_count: bool

uses the refcount to unload rather than the unused. must exist for fonts to unload correctly and must be set to false for them.

texture_group: TextureGroup

Texture Bind group for Atlas

Implementations

impl<U: Hash + Eq + Clone, Data: Copy + Default> AtlasSet<U, Data>

pub fn new( renderer: &mut GpuRenderer, format: TextureFormat, use_ref_count: bool ) -> Self

pub fn upload_allocation( &mut self, buffer: &[u8], allocation: &Allocation<Data>, renderer: &GpuRenderer )

pub fn clear(&mut self)

pub fn trim(&mut self)

pub fn promote_by_key(&mut self, key: U)

pub fn promote(&mut self, id: usize)

pub fn lookup(&self, key: &U) -> Option<usize>

Get the ID of a image if it is loaded.

pub fn peek_by_key(&mut self, key: &U) -> Option<&(Allocation<Data>, U)>

pub fn peek(&mut self, id: usize) -> Option<&(Allocation<Data>, U)>

pub fn contains_key(&mut self, key: &U) -> bool

pub fn contains(&mut self, id: usize) -> bool

pub fn get_by_key(&mut self, key: &U) -> Option<Allocation<Data>>

pub fn get(&mut self, id: usize) -> Option<Allocation<Data>>

pub fn remove_by_key(&mut self, key: &U) -> Option<usize>

Removing will leave anything using the texture inable to load the correct texture if a new texture is loaded in the olds place. TODO Redo texture system so texture allocations are not held by the images but instead TODO are held by the system so we can reload images later on if they got unloaded.

returns the layer id if removed otherwise None for everything else.

pub fn remove(&mut self, id: usize) -> Option<usize>

pub fn upload( &mut self, key: U, bytes: &[u8], width: u32, height: u32, data: Data, renderer: &GpuRenderer ) -> Option<usize>

pub fn upload_with_alloc( &mut self, key: U, bytes: &[u8], width: u32, height: u32, data: Data, renderer: &GpuRenderer ) -> Option<(usize, Allocation<Data>)>

pub fn size(&self) -> UVec3

pub fn bind_group(&self) -> &BindGroup