Struct Texture

#[repr(C)]
pub struct Texture { /* private fields */ }

[Image] living on the graphics card that can be used for drawing.

Texture stores pixels that can be drawn, with a sprite for example.

A texture lives in the graphics card memory, therefore it is very fast to draw a texture to a render target, or copy a render target to a texture (the graphics card can access both directly).

Being stored in the graphics card memory has some drawbacks. A texture cannot be manipulated as freely as a [Image], you need to prepare the pixels first and then upload them to the texture in a single operation (see the various update methods below).

Texture makes it easy to convert from/to [Image], but keep in mind that these calls require transfers between the graphics card and the central memory, therefore they are slow operations.

A texture can be loaded from an image, but also directly from a file/memory/stream. The necessary shortcuts are defined so that you don’t need an image first for the most common cases. However, if you want to perform some modifications on the pixels before creating the final texture, you can load your file to a [Image], do whatever you need with the pixels, and then call [Texture::load_from_image].

Since they live in the graphics card memory, the pixels of a texture cannot be accessed without a slow copy first. And they cannot be accessed individually. Therefore, if you need to read the texture’s pixels (like for pixel-perfect collisions), it is recommended to store the collision information separately, for example in an array of booleans.

Like [Image], Texture can handle a unique internal representation of pixels, which is RGBA 32 bits. This means that a pixel must be composed of 8 bits red, green, blue and alpha channels – just like a Color.

Implementations

impl Texture

Creation and loading

pub fn create(&mut self, width: u32, height: u32) -> SfResult<()>

Create the texture.

If this function fails, the texture is left unchanged.

Returns whether creation was successful.

pub fn new() -> SfResult<FBox<Texture>>

Creates a new Texture

pub fn load_from_memory(&mut self, mem: &[u8]) -> SfResult<()>

Load texture from memory

The area argument can be used to load only a sub-rectangle of the whole image. If you want the entire image then use a default [IntRect]. If the area rectangle crosses the bounds of the image, it is adjusted to fit the image size.

Arguments

• mem - Pointer to the file data in memory
• area - Area of the image to load

pub fn load_from_file(&mut self, filename: &str) -> SfResult<()>

Load texture from a file

Arguments

• filename - Path of the image file to load

pub fn from_file(filename: &str) -> SfResult<FBox<Self>>

Convenience method to easily create and load a Texture from a file.

Examples found in repository

examples/borrowed-resources.rs (line 24)

fn main() -> SfResult<()> {
    example_ensure_right_working_dir();

    let mut window = RenderWindow::new(
        (800, 600),
        "Borrowed resources",
        Style::CLOSE,
        &Default::default(),
    )?;
    window.set_vertical_sync_enabled(true);

    // Create a new texture. (Hey Frank!)
    let frank = Texture::from_file("frank.jpeg")?;

    // Create a font.
    let font = Font::from_file("sansation.ttf")?;

    // Create a circle with the Texture.
    let mut circle = CircleShape::with_texture(&frank);
    circle.set_radius(70.0);
    circle.set_position((100.0, 100.0));

    // Create a Sprite.
    let mut sprite = Sprite::new();
    // Have it use the same texture as the circle.
    sprite.set_texture(&frank, true);
    sprite.set_position((400.0, 300.0));
    sprite.set_scale(0.5);

    // Create a ConvexShape using the same texture.
    let mut convex_shape = ConvexShape::with_texture(6, &frank);
    convex_shape.set_point(0, (400., 100.));
    convex_shape.set_point(1, (500., 70.));
    convex_shape.set_point(2, (450., 100.));
    convex_shape.set_point(3, (580., 150.));
    convex_shape.set_point(4, (420., 230.));
    convex_shape.set_point(5, (420., 120.));

    // Create an initialized text using the font.
    let mut title = Text::new("Borrowed resources example!".into(), &font, 50);

    // Create a second text using the same font.
    // This time, we create and initialize it separately.
    let mut second_text = Text::default();
    second_text.set_string("This text shares the same font with the title!".into());
    second_text.set_font(&font);
    second_text.set_fill_color(Color::GREEN);
    second_text.tf.position = [10.0, 350.0];
    second_text.set_character_size(20);

    // Create a third text using the same font.
    let mut third_text = Text::new("This one too!".into(), &font, 20);
    third_text.tf.position = [300.0, 100.0];
    third_text.set_fill_color(Color::RED);

    'mainloop: loop {
        while let Some(event) = window.poll_event() {
            match event {
                Event::Closed
                | Event::KeyPressed {
                    code: Key::Escape, ..
                } => break 'mainloop,
                _ => {}
            }
        }

        window.clear(Color::BLACK);
        let rs = RenderStates::DEFAULT;
        window.draw_circle_shape(&circle, &rs);
        window.draw_sprite(&sprite, &rs);
        window.draw_convex_shape(&convex_shape, &rs);
        title.draw(&mut *window, &rs);
        second_text.draw(&mut *window, &rs);
        third_text.draw(&mut *window, &rs);

        // Little test here for `Shape::points`
        let mut circ = CircleShape::new(4.0, 30);
        circ.set_origin(2.0);
        circ.set_fill_color(Color::YELLOW);

        for p in convex_shape.points() {
            circ.set_position(p);
            window.draw_circle_shape(&circ, &RenderStates::DEFAULT);
        }

        window.display();
    }
    Ok(())
}

impl Texture

Query properties

pub fn size(&self) -> Vector2u

Return the size of the texture

Return the Size in pixels

pub fn maximum_size() -> u32

Get the maximum texture size allowed

Return the maximum size allowed for textures, in pixels

pub fn is_smooth(&self) -> bool

Tell whether the smooth filter is enabled or not for a texture

Return true if smoothing is enabled, false if it is disabled

pub fn is_repeated(&self) -> bool

Tell whether a texture is repeated or not

Return frue if repeat mode is enabled, false if it is disabled

pub fn is_srgb(&self) -> bool

Tell whether the texture source is converted from sRGB or not.

impl Texture

Set properties

pub fn set_smooth(&mut self, smooth: bool)

Enable or disable the smooth filter on a texture

Arguments

• smooth - true to enable smoothing, false to disable it

pub fn set_repeated(&mut self, repeated: bool)

Enable or disable repeating for a texture

epeating is involved when using texture coordinates outside the texture rectangle [0, 0, width, height]. In this case, if repeat mode is enabled, the whole texture will be repeated as many times as needed to reach the coordinate (for example, if the X texture coordinate is 3 * width, the texture will be repeated 3 times). If repeat mode is disabled, the “extra space” will instead be filled with border pixels. Warning: on very old graphics cards, white pixels may appear when the texture is repeated. With such cards, repeat mode can be used reliably only if the texture has power-of-two dimensions (such as 256x128). Repeating is disabled by default.

Arguments

• repeated - true to repeat the texture, false to disable repeating

pub fn set_srgb(&mut self, srgb: bool)

Enable or disable conversion from sRGB.

When providing texture data from an image file or memory, it can either be stored in a linear color space or an sRGB color space. Most digital images account for gamma correction already, so they would need to be “uncorrected” back to linear color space before being processed by the hardware. The hardware can automatically convert it from the sRGB color space to a linear color space when it gets sampled. When the rendered image gets output to the final framebuffer, it gets converted back to sRGB.

After enabling or disabling sRGB conversion, make sure to reload the texture data in order for the setting to take effect.

This option is only useful in conjunction with an sRGB capable framebuffer. This can be requested during window creation.

impl Texture

OpenGL interop

pub fn native_handle(&self) -> u32

Get the underlying OpenGL handle of the texture.

You shouldn’t need to use this function, unless you have very specific stuff to implement that SFML doesn’t support, or implement a temporary workaround until a bug is fixed.

pub fn bind(&self)

Bind a texture for rendering

This function is not part of the graphics API, it mustn’t be used when drawing SFML entities. It must be used only if you mix Texture with OpenGL code.

impl Texture

Copying and updating

pub unsafe fn update_from_window(&mut self, window: &Window, x: u32, y: u32)

Update a part of the texture from the contents of a window.

This function does nothing if either the texture or the window was not previously created.

Safety

No additional check is performed on the size of the window, passing an invalid combination of window size and offset will lead to an undefined behavior.

pub unsafe fn update_from_render_window( &mut self, render_window: &RenderWindow, x: u32, y: u32, )

Update a part of the texture from the contents of a render window.

This function does nothing if either the texture or the window was not previously created.

Safety

No additional check is performed on the size of the window, passing an invalid combination of window size and offset will lead to an undefined behavior.

pub unsafe fn update_from_texture(&mut self, texture: &Texture, x: u32, y: u32)

Update a part of this texture from another texture.

This function does nothing if either texture was not previously created.

Safety

No additional check is performed on the size of the texture, passing an invalid combination of texture size and offset will lead to an undefined behavior.

pub fn update_from_pixels( &mut self, pixels: &[u8], width: u32, height: u32, x: u32, y: u32, )

Update a part of the texture from an array of pixels.

The size of the pixel array must match the width and height arguments, and it must contain 32-bits RGBA pixels.

This function does nothing if the texture was not previously created.

Panics

Panics the provided parameters would result in out of bounds access.

pub fn swap(&mut self, other: &mut Texture)

Swap the contents of this texture with those of another.

impl Texture

Mipmapping

pub fn generate_mipmap(&mut self) -> SfResult<()>

Generate a mipmap using the current texture data.

Mipmaps are pre-computed chains of optimized textures. Each level of texture in a mipmap is generated by halving each of the previous level’s dimensions. This is done until the final level has the size of 1x1. The textures generated in this process may make use of more advanced filters which might improve the visual quality of textures when they are applied to objects much smaller than they are. This is known as minification. Because fewer texels (texture elements) have to be sampled from when heavily minified, usage of mipmaps can also improve rendering performance in certain scenarios.

Mipmap generation relies on the necessary OpenGL extension being available. If it is unavailable or generation fails due to another reason, this function will return false. Mipmap data is only valid from the time it is generated until the next time the base level image is modified, at which point this function will have to be called again to regenerate it.

Trait Implementations

impl Debug for Texture

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

Formats the value using the given formatter.

impl Drop for Texture

fn drop(&mut self)

Executes the destructor for this type.

impl ToOwned for Texture

type Owned = FBox<Texture>

The resulting type after obtaining ownership.

fn to_owned(&self) -> Self::Owned

Creates owned data from borrowed data, usually by cloning.

fn clone_into(&self, target: &mut Self::Owned)

Uses borrowed data to replace owned data, usually by cloning.