Struct sdl2::render::TextureCreator

pub struct TextureCreator<T> { /* fields omitted */ }

Creates Textures that cannot outlive the creator

The TextureCreator does not hold a lifetime to its Canvas by design choice.

If a Canvas is dropped before its TextureCreator, it is still safe to use.

It is, however, useless.

Any Texture created here can only be drawn onto the original Canvas. A Texture used in a Canvas must come from a TextureCreator coming from that same Canvas. Using a Texture to render to a Canvas not being the parent of the Texture's TextureCreator is undefined behavior.

Methods

impl<T> TextureCreator<T>

Texture-creating methods for the renderer

pub fn raw(&self) -> *mut SDL_Renderer

pub fn default_pixel_format(&self) -> PixelFormatEnum

pub fn create_texture<F>(
    &self,
    format: F,
    access: TextureAccess,
    width: u32,
    height: u32
) -> Result<Texture, TextureValueError> where
    F: Into<Option<PixelFormatEnum>>, 

Creates a texture for a rendering context.

If format is None, the format will be the one the parent Window or Surface uses.

If format is Some(pixel_format), the default will be overridden, and the texture will be created with the specified format if possible. If the PixelFormat is not supported, this will return an error.

You should prefer the default format if possible to have performance gains and to avoid unsupported Pixel Formats that can cause errors. However, be careful with the default PixelFormat if you want to create transparent textures.

pub fn create_texture_static<F>(
    &self,
    format: F,
    width: u32,
    height: u32
) -> Result<Texture, TextureValueError> where
    F: Into<Option<PixelFormatEnum>>, 

Shorthand for create_texture(format, TextureAccess::Static, width, height)

pub fn create_texture_streaming<F>(
    &self,
    format: F,
    width: u32,
    height: u32
) -> Result<Texture, TextureValueError> where
    F: Into<Option<PixelFormatEnum>>, 

Shorthand for create_texture(format, TextureAccess::Streaming, width, height)

pub fn create_texture_target<F>(
    &self,
    format: F,
    width: u32,
    height: u32
) -> Result<Texture, TextureValueError> where
    F: Into<Option<PixelFormatEnum>>, 

Shorthand for create_texture(format, TextureAccess::Target, width, height)

pub fn create_texture_from_surface<S: AsRef<SurfaceRef>>(
    &self,
    surface: S
) -> Result<Texture, TextureValueError>

Creates a texture from an existing surface.

Remarks

The access hint for the created texture is [TextureAccess::Static].

use sdl2::pixels::PixelFormatEnum;
use sdl2::surface::Surface;
use sdl2::render::{Canvas, Texture};
use sdl2::video::Window;

// We init systems.
let sdl_context = sdl2::init().expect("failed to init SDL");
let video_subsystem = sdl_context.video().expect("failed to get video context");

// We create a window.
let window = video_subsystem.window("sdl2 demo", 800, 600)
    .build()
    .expect("failed to build window");

// We get the canvas from which we can get the `TextureCreator`.
let mut canvas: Canvas<Window> = window.into_canvas()
    .build()
    .expect("failed to build window's canvas");
let texture_creator = canvas.texture_creator();

let surface = Surface::new(512, 512, PixelFormatEnum::RGB24).unwrap();
let texture = texture_creator.create_texture_from_surface(surface).unwrap();

pub const unsafe fn raw_create_texture(&self, raw: *mut SDL_Texture) -> Texture

Create a texture from its raw SDL_Texture.

Trait Implementations

impl<T> LoadTexture for TextureCreator<T>

fn load_texture<P: AsRef<Path>>(&self, filename: P) -> Result<Texture, String>

Loads an SDL Texture from a file

fn load_texture_bytes(&self, buf: &[u8]) -> Result<Texture, String>

Loads an SDL Texture from a buffer that the format must be something supported by SDL2_image (png, jpeg, ect, but NOT RGBA8888 bytes for instance)