Enum ImageSampler

pub enum ImageSampler {
    Default,
    Descriptor(ImageSamplerDescriptor),
}

Used in Image, this determines what image sampler to use when rendering. The default setting, ImageSampler::Default, will read the sampler from the ImagePlugin at setup. Setting this to ImageSampler::Descriptor will override the global default descriptor for this Image.

Variants

Default

Default image sampler, derived from the ImagePlugin setup.

Descriptor(ImageSamplerDescriptor)

Custom sampler for this image which will override global default.

Implementations

impl ImageSampler

pub fn linear() -> ImageSampler

Returns an image sampler with ImageFilterMode::Linear min and mag filters

Examples found in repository

examples/2d/texture_atlas.rs (line 65)

fn setup(
    mut commands: Commands,
    rpg_sprite_handles: Res<RpgSpriteFolder>,
    asset_server: Res<AssetServer>,
    mut texture_atlases: ResMut<Assets<TextureAtlasLayout>>,
    loaded_folders: Res<Assets<LoadedFolder>>,
    mut textures: ResMut<Assets<Image>>,
) {
    let loaded_folder = loaded_folders.get(&rpg_sprite_handles.0).unwrap();

    // create texture atlases with different padding and sampling

    let (texture_atlas_linear, linear_sources, linear_texture) = create_texture_atlas(
        loaded_folder,
        None,
        Some(ImageSampler::linear()),
        &mut textures,
    );
    let atlas_linear_handle = texture_atlases.add(texture_atlas_linear);

    let (texture_atlas_nearest, nearest_sources, nearest_texture) = create_texture_atlas(
        loaded_folder,
        None,
        Some(ImageSampler::nearest()),
        &mut textures,
    );
    let atlas_nearest_handle = texture_atlases.add(texture_atlas_nearest);

    let (texture_atlas_linear_padded, linear_padded_sources, linear_padded_texture) =
        create_texture_atlas(
            loaded_folder,
            Some(UVec2::new(6, 6)),
            Some(ImageSampler::linear()),
            &mut textures,
        );
    let atlas_linear_padded_handle = texture_atlases.add(texture_atlas_linear_padded.clone());

    let (texture_atlas_nearest_padded, nearest_padded_sources, nearest_padded_texture) =
        create_texture_atlas(
            loaded_folder,
            Some(UVec2::new(6, 6)),
            Some(ImageSampler::nearest()),
            &mut textures,
        );
    let atlas_nearest_padded_handle = texture_atlases.add(texture_atlas_nearest_padded);

    // setup 2d scene
    commands.spawn(Camera2d);

    // padded textures are to the right, unpadded to the left

    // draw unpadded texture atlas
    commands.spawn((
        Sprite::from_image(linear_texture.clone()),
        Transform {
            translation: Vec3::new(-250.0, -130.0, 0.0),
            scale: Vec3::splat(0.8),
            ..default()
        },
    ));

    // draw padded texture atlas
    commands.spawn((
        Sprite::from_image(linear_padded_texture.clone()),
        Transform {
            translation: Vec3::new(250.0, -130.0, 0.0),
            scale: Vec3::splat(0.8),
            ..default()
        },
    ));

    let font = asset_server.load("fonts/FiraSans-Bold.ttf");

    // padding label text style
    let text_style: TextFont = TextFont {
        font: font.clone(),
        font_size: 42.0,
        ..default()
    };

    // labels to indicate padding

    // No padding
    create_label(
        &mut commands,
        (-250.0, 330.0, 0.0),
        "No padding",
        text_style.clone(),
    );

    // Padding
    create_label(&mut commands, (250.0, 330.0, 0.0), "Padding", text_style);

    // get handle to a sprite to render
    let vendor_handle: Handle<Image> = asset_server
        .get_handle("textures/rpg/chars/vendor/generic-rpg-vendor.png")
        .unwrap();

    // configuration array to render sprites through iteration
    let configurations: [(
        &str,
        Handle<TextureAtlasLayout>,
        TextureAtlasSources,
        Handle<Image>,
        f32,
    ); 4] = [
        (
            "Linear",
            atlas_linear_handle,
            linear_sources,
            linear_texture,
            -350.0,
        ),
        (
            "Nearest",
            atlas_nearest_handle,
            nearest_sources,
            nearest_texture,
            -150.0,
        ),
        (
            "Linear",
            atlas_linear_padded_handle,
            linear_padded_sources,
            linear_padded_texture,
            150.0,
        ),
        (
            "Nearest",
            atlas_nearest_padded_handle,
            nearest_padded_sources,
            nearest_padded_texture,
            350.0,
        ),
    ];

    // label text style
    let sampling_label_style = TextFont {
        font,
        font_size: 25.0,
        ..default()
    };

    let base_y = 170.0; // y position of the sprites

    for (sampling, atlas_handle, atlas_sources, atlas_texture, x) in configurations {
        // render a sprite from the texture_atlas
        create_sprite_from_atlas(
            &mut commands,
            (x, base_y, 0.0),
            atlas_texture,
            atlas_sources,
            atlas_handle,
            &vendor_handle,
        );

        // render a label to indicate the sampling setting
        create_label(
            &mut commands,
            (x, base_y + 110.0, 0.0), // offset to y position of the sprite
            sampling,
            sampling_label_style.clone(),
        );
    }
}

pub fn nearest() -> ImageSampler

Returns an image sampler with ImageFilterMode::Nearest min and mag filters

Examples found in repository

examples/ui/ui_texture_slice_flip_and_tile.rs (line 25)

fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
    let image = asset_server.load_with_settings(
        "textures/fantasy_ui_borders/numbered_slices.png",
        |settings: &mut ImageLoaderSettings| {
            // Need to use nearest filtering to avoid bleeding between the slices with tiling
            settings.sampler = ImageSampler::nearest();
        },
    );

    let slicer = TextureSlicer {
        // `numbered_slices.png` is 48 pixels square. `BorderRect::square(16.)` insets the slicing line from each edge by 16 pixels, resulting in nine slices that are each 16 pixels square.
        border: BorderRect::square(16.),
        // With `SliceScaleMode::Tile` the side and center slices are tiled to fill the side and center sections of the target.
        // And with a `stretch_value` of `1.` the tiles will have the same size as the corresponding slices in the source image.
        center_scale_mode: SliceScaleMode::Tile { stretch_value: 1. },
        sides_scale_mode: SliceScaleMode::Tile { stretch_value: 1. },
        ..default()
    };

    // ui camera
    commands.spawn(Camera2d);

    commands
        .spawn(Node {
            width: Val::Percent(100.),
            height: Val::Percent(100.),
            justify_content: JustifyContent::Center,
            align_content: AlignContent::Center,
            flex_wrap: FlexWrap::Wrap,
            column_gap: Val::Px(10.),
            row_gap: Val::Px(10.),
            ..default()
        })
        .with_children(|parent| {
            for [columns, rows] in [[3., 3.], [4., 4.], [5., 4.], [4., 5.], [5., 5.]] {
                for (flip_x, flip_y) in [(false, false), (false, true), (true, false), (true, true)]
                {
                    parent.spawn((
                        ImageNode {
                            image: image.clone(),
                            flip_x,
                            flip_y,
                            image_mode: NodeImageMode::Sliced(slicer.clone()),
                            ..default()
                        },
                        Node {
                            width: Val::Px(16. * columns),
                            height: Val::Px(16. * rows),
                            ..default()
                        },
                    ));
                }
            }
        });
}

examples/asset/asset_settings.rs (line 68)

fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
    // Without any .meta file specifying settings, the default sampler [ImagePlugin::default()] is used for loading images.
    // If you are using a very small image and rendering it larger like seen here, the default linear filtering will result in a blurry image.
    // Useful note: The default sampler specified by the ImagePlugin is *not* the same as the default implementation of sampler. This is why
    // everything uses linear by default but if you look at the default of sampler, it uses nearest.
    commands.spawn((
        Sprite {
            image: asset_server.load("bevy_pixel_dark.png"),
            custom_size: Some(Vec2 { x: 160.0, y: 120.0 }),
            ..Default::default()
        },
        Transform::from_xyz(-100.0, 0.0, 0.0),
    ));

    // When a .meta file is added with the same name as the asset and a '.meta' extension
    // you can (and must) specify all fields of the asset loader's settings for that
    // particular asset, in this case [ImageLoaderSettings]. Take a look at
    // examples/asset/files/bevy_pixel_dark_with_meta.png.meta
    // for the format and you'll notice, the only non-default option is setting Nearest
    // filtering. This tends to work much better for pixel art assets.
    // A good reference when filling this out is to check out [ImageLoaderSettings::default()]
    // and follow to the default implementation of each fields type.
    // https://docs.rs/bevy/latest/bevy/render/texture/struct.ImageLoaderSettings.html#
    commands.spawn((
        Sprite {
            image: asset_server.load("bevy_pixel_dark_with_meta.png"),
            custom_size: Some(Vec2 { x: 160.0, y: 120.0 }),
            ..Default::default()
        },
        Transform::from_xyz(100.0, 0.0, 0.0),
    ));

    // Another option is to use the AssetServers load_with_settings function.
    // With this you can specify the same settings upon loading your asset with a
    // couple of differences. A big one is that you aren't required to set *every*
    // setting, just modify the ones that you need. It works by passing in a function
    // (in this case an anonymous closure) that takes a reference to the settings type
    // that is then modified in the function.
    // Do note that if you want to load the same asset with different settings, the
    // settings changes from any loads after the first of the same asset will be ignored.
    // This is why this one loads a differently named copy of the asset instead of using
    // same one as without a .meta file.
    commands.spawn((
        Sprite {
            image: asset_server.load_with_settings(
                "bevy_pixel_dark_with_settings.png",
                |settings: &mut ImageLoaderSettings| {
                    settings.sampler = ImageSampler::nearest();
                },
            ),
            custom_size: Some(Vec2 { x: 160.0, y: 120.0 }),
            ..Default::default()
        },
        Transform::from_xyz(0.0, 150.0, 0.0),
    ));

    commands.spawn(Camera2d);
}

examples/2d/texture_atlas.rs (line 73)

fn setup(
    mut commands: Commands,
    rpg_sprite_handles: Res<RpgSpriteFolder>,
    asset_server: Res<AssetServer>,
    mut texture_atlases: ResMut<Assets<TextureAtlasLayout>>,
    loaded_folders: Res<Assets<LoadedFolder>>,
    mut textures: ResMut<Assets<Image>>,
) {
    let loaded_folder = loaded_folders.get(&rpg_sprite_handles.0).unwrap();

    // create texture atlases with different padding and sampling

    let (texture_atlas_linear, linear_sources, linear_texture) = create_texture_atlas(
        loaded_folder,
        None,
        Some(ImageSampler::linear()),
        &mut textures,
    );
    let atlas_linear_handle = texture_atlases.add(texture_atlas_linear);

    let (texture_atlas_nearest, nearest_sources, nearest_texture) = create_texture_atlas(
        loaded_folder,
        None,
        Some(ImageSampler::nearest()),
        &mut textures,
    );
    let atlas_nearest_handle = texture_atlases.add(texture_atlas_nearest);

    let (texture_atlas_linear_padded, linear_padded_sources, linear_padded_texture) =
        create_texture_atlas(
            loaded_folder,
            Some(UVec2::new(6, 6)),
            Some(ImageSampler::linear()),
            &mut textures,
        );
    let atlas_linear_padded_handle = texture_atlases.add(texture_atlas_linear_padded.clone());

    let (texture_atlas_nearest_padded, nearest_padded_sources, nearest_padded_texture) =
        create_texture_atlas(
            loaded_folder,
            Some(UVec2::new(6, 6)),
            Some(ImageSampler::nearest()),
            &mut textures,
        );
    let atlas_nearest_padded_handle = texture_atlases.add(texture_atlas_nearest_padded);

    // setup 2d scene
    commands.spawn(Camera2d);

    // padded textures are to the right, unpadded to the left

    // draw unpadded texture atlas
    commands.spawn((
        Sprite::from_image(linear_texture.clone()),
        Transform {
            translation: Vec3::new(-250.0, -130.0, 0.0),
            scale: Vec3::splat(0.8),
            ..default()
        },
    ));

    // draw padded texture atlas
    commands.spawn((
        Sprite::from_image(linear_padded_texture.clone()),
        Transform {
            translation: Vec3::new(250.0, -130.0, 0.0),
            scale: Vec3::splat(0.8),
            ..default()
        },
    ));

    let font = asset_server.load("fonts/FiraSans-Bold.ttf");

    // padding label text style
    let text_style: TextFont = TextFont {
        font: font.clone(),
        font_size: 42.0,
        ..default()
    };

    // labels to indicate padding

    // No padding
    create_label(
        &mut commands,
        (-250.0, 330.0, 0.0),
        "No padding",
        text_style.clone(),
    );

    // Padding
    create_label(&mut commands, (250.0, 330.0, 0.0), "Padding", text_style);

    // get handle to a sprite to render
    let vendor_handle: Handle<Image> = asset_server
        .get_handle("textures/rpg/chars/vendor/generic-rpg-vendor.png")
        .unwrap();

    // configuration array to render sprites through iteration
    let configurations: [(
        &str,
        Handle<TextureAtlasLayout>,
        TextureAtlasSources,
        Handle<Image>,
        f32,
    ); 4] = [
        (
            "Linear",
            atlas_linear_handle,
            linear_sources,
            linear_texture,
            -350.0,
        ),
        (
            "Nearest",
            atlas_nearest_handle,
            nearest_sources,
            nearest_texture,
            -150.0,
        ),
        (
            "Linear",
            atlas_linear_padded_handle,
            linear_padded_sources,
            linear_padded_texture,
            150.0,
        ),
        (
            "Nearest",
            atlas_nearest_padded_handle,
            nearest_padded_sources,
            nearest_padded_texture,
            350.0,
        ),
    ];

    // label text style
    let sampling_label_style = TextFont {
        font,
        font_size: 25.0,
        ..default()
    };

    let base_y = 170.0; // y position of the sprites

    for (sampling, atlas_handle, atlas_sources, atlas_texture, x) in configurations {
        // render a sprite from the texture_atlas
        create_sprite_from_atlas(
            &mut commands,
            (x, base_y, 0.0),
            atlas_texture,
            atlas_sources,
            atlas_handle,
            &vendor_handle,
        );

        // render a label to indicate the sampling setting
        create_label(
            &mut commands,
            (x, base_y + 110.0, 0.0), // offset to y position of the sprite
            sampling,
            sampling_label_style.clone(),
        );
    }
}

pub fn get_or_init_descriptor(&mut self) -> &mut ImageSamplerDescriptor

Initialize the descriptor if it is not already initialized.

Descriptor is typically initialized by Bevy when the image is loaded, so this is convenient shortcut for updating the descriptor.

Trait Implementations

impl Clone for ImageSampler

fn clone(&self) -> ImageSampler

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ImageSampler

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

Formats the value using the given formatter.

impl Default for ImageSampler

fn default() -> ImageSampler

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for ImageSampler

fn deserialize<__D>( __deserializer: __D, ) -> Result<ImageSampler, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for ImageSampler

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.