bevy_datasize

bevy_datasize is a library for tracking memory usage in Bevy apps.

bevy_datasize uses the DataSize trait from the datasize crate to estimate the runtime memory usage of any components, resources, or assets that are registered with the MemoryUsagePlugin.

The DataSize trait can be derived for your own custom types, and you can inject custom estimators for third party types that do not implement DataSize. See the datasize docs for more info on that.

Docs

Rustdocs for the main branch can be found here

Examples

Basic Usage

The following example demonstrates how to show the memory usage of all loaded Images:

use bevy::prelude::*;
use bevy_datasize::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(DefaultMemoryUsagePlugins)
        .add_system(print_image_usage)
        .run();
}

fn print_image_usage(memory_usage: Res<MemoryUsage>) {
    let MemoryStats {
        count,
        total_stack_bytes,
        total_heap_bytes,
    } = memory_usage.get_stats::<Image>().unwrap();

    println!("Image count: {count}");
    println!("Total stack usage: {total_stack_bytes} bytes");
    println!("Total heap usage: {total_heap_bytes} bytes");
}

Custom Data Types

The following example demonstrates how to track memory usage for a custom Component type when using minimal plugins:

use bevy::prelude::*;
use bevy_datasize::prelude::*;

#[derive(Component, DataSize)]
struct MyComponent {
    data: Vec<u8>,
}

fn main() {
    App::new()
        .add_plugins(MinimalPlugins)
        .add_plugin(MemoryUsagePlugin)
        .register_sized_component::<MyComponent>()
        .add_system(print_custom_usage)
        .run();
}

fn print_custom_usage(memory_usage: Res<MemoryUsage>) {
    let MemoryStats {
        count,
        total_stack_bytes,
        total_heap_bytes,
    } = memory_usage.get_stats::<MyComponent>().unwrap();

    println!("MyComponent count: {count}");
    println!("MyComponent total stack usage: {total_stack_bytes} bytes");
    println!("MyComponent total heap usage: {total_heap_bytes} bytes");
}

More

See the examples directory for more examples.

Optional Features

bevy_datasize can be configured very granularly to only pull in the parts of bevy that you need for your app.

Default features

This gives you support for all of the Bevy-internal data types that bevy_datasize supports:

[dependencies]
bevy_datasize = "0.0.1"

Minimal features

This gives you support for only your own custom datatypes:

[dependencies]
bevy_datasize = { version = "0.0.1", default-features = false }

Other configurations

This, for example, gives you support for all rendering resources:

[dependencies]
bevy_datasize = { version = "0.0.1", default-features = false, features = ["render"] }

Or just for Image assets:

[dependencies]
bevy_datasize = { version = "0.0.1", default-features = false, features = ["image"] }

See the Cargo.toml to see all the available features.

Feature Checklist

This crate is still in development. Everybody loves checklists!

Main functionality features

• Tracking custom types
• Retrieving memory usage statistics from a resource
• Throttling the statistics gathering
• Hooking memory usage statistics up to Diagnostics
• Categories / category hierarchy
• Visual debugging and/or integration with bevy_inspector_egui

Supported Bevy types

So far, the following types have built-in support for memory tracking:

• Types in bevy::audio
  • Audio
  • AudioSource¹
• Types in bevy::render
  • Mesh
  • GpuMesh
  • Image
  • GpuImage
  • Shader¹
  • RenderGraph
  • TextureCache¹
  • ComponentUniforms
  • VisibleEntities
  • ComputedVisibility
  • Visibility
  • ExtractedView
• Types in bevy::gltf
  • Gltf
  • GltfMesh
  • GltfNode
  • GltfPrimitive
• Types in bevy::pbr
  • StandardMaterial
  • GpuStandardMaterial
  • MeshUniform
  • MeshViewBindGroup
  • AmbientLight
  • Clusters
  • CubemapVisibleEntities
  • DirectionalLight
  • ExtractedAmbientLight
  • ExtractedClusterConfig
  • ExtractedClustersPointLights
  • ExtractedDirectionalLight
  • ExtractedPointLight
  • GpuDirectionalLight
  • GpuLights
  • GpuPointLight
  • GpuPointLights
  • PointLight
  • ShadowView
  • ViewClusterBindings
  • ViewLightEntities
  • ViewLightsUniformOffset
  • ViewShadowBindings
  • VisiblePointLights
  • Wireframe
• Types in bevy::scene
  • Scene
  • DynamicScene
• Types in bevy::sprite
  • Sprite
  • SpriteBatch
  • TextureAtlasSprite
  • TextureAtlas
  • ColorMaterial
  • GpuColorMaterial
  • ExtractedSprites
  • Mesh2dUniform
  • Mesh2dViewBindGroup
• Types in bevy::transform
  • Transform
  • GlobalTransform
  • Children
  • Parent
  • PreviousParent
• Types in bevy::text
  • Font¹
  • FontAtlasSet
  • Text
  • Text2dSize
• Types in bevy::ui
  • CalculatedClip
  • CalculatedSize
  • ExtractedUiNodes
  • Node
  • Style
  • UiBatch
  • UiImage

License

Licensed under either of

• Apache License, Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (http://opensource.org/licenses/MIT)

at your option.

Copyright Ben Reeves 2022

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Footnotes

1. It may not be possible to estimate the size of this type. ↩ ↩² ↩³ ↩⁴