Struct oxydyze::util::renderer::Texture

pub struct Texture { /* fields omitted */ }

A texture for a rendering context.

Every Texture is owned by a TextureCreator or Canvas (the latter is only possible with the unsafe_textures feature).

Differences between with and without unsafe_textures feature

Without the unsafe_textures, a texture is owned by a TextureCreator and a Texture cannot outlive its parent TextureCreator thanks to lifetimes. A texture is destroyed via its Drop implementation. While this is the most "Rust"-y way of doing things currently, it is pretty cumbersome to use in some cases.

That is why the feature unsafe_textures was brought to life: the lifetimes are gone, meaning that Textures can outlive their parents. That means that the Textures are not destroyed on Drop, but destroyed when their parents are. That means if you create 10 000 textures with this feature, they will only be destroyed after you drop the Canvas and every TextureCreator linked to it. While this feature is enabled, this is the safest way to free the memory taken by the Textures, but there is still another, unsafe way to destroy the Texture before its Canvas: the method destroy. This method is unsafe because you have to make sure the parent Canvas or TextureCreator is still alive while calling this method.

Calling the destroy method while no parent is alive is undefined behavior

With the unsafe_textures feature, a Texture can be safely accessed (but not destroyed) after the Canvas is dropped, but since any access (except destroy) requires the original Canvas, it is not possible to access a Texture while the Canvas is dropped.

Methods

impl Texture

pub unsafe fn destroy(self)

Destroy the Texture and its representation in the Renderer. This will most likely mean that the renderer engine will free video memory that was allocated for this texture.

This method is unsafe because since Texture does not have a lifetime, it is legal in Rust to make this texture live longer than the Renderer. It is however illegal to destroy a SDL_Texture after its SDL_Renderer, therefore this function is unsafe because of this.

Note however that you don't have to destroy a Texture before its Canvas, since whenever Canvas is destroyed, the SDL implementation will automatically destroy all the children Textures of that Canvas.

Calling this method while no parent is alive is undefined behavior

impl Texture

pub fn query(&self) -> TextureQuery

Queries the attributes of the texture.

pub fn set_color_mod(&mut self, red: u8, green: u8, blue: u8)

Sets an additional color value multiplied into render copy operations.

pub fn color_mod(&self) -> (u8, u8, u8)

Gets the additional color value multiplied into render copy operations.

pub fn set_alpha_mod(&mut self, alpha: u8)

Sets an additional alpha value multiplied into render copy operations.

pub fn alpha_mod(&self) -> u8

Gets the additional alpha value multiplied into render copy operations.

pub fn set_blend_mode(&mut self, blend: BlendMode)

Sets the blend mode used for drawing operations (Fill and Line).

pub fn blend_mode(&self) -> BlendMode

Gets the blend mode used for texture copy operations.

pub fn update<R>(
    &mut self,
    rect: R,
    pixel_data: &[u8],
    pitch: usize
) -> Result<(), UpdateTextureError> where
    R: Into<Option<Rect>>, 

Updates the given texture rectangle with new pixel data.

pitch is the number of bytes in a row of pixel data, including padding between lines

• If rect is None, the entire texture is updated.

pub fn update_yuv<R>(
    &mut self,
    rect: R,
    y_plane: &[u8],
    y_pitch: usize,
    u_plane: &[u8],
    u_pitch: usize,
    v_plane: &[u8],
    v_pitch: usize
) -> Result<(), UpdateTextureYUVError> where
    R: Into<Option<Rect>>, 

Updates a rectangle within a planar YV12 or IYUV texture with new pixel data.

pub fn with_lock<F, R, R2>(&mut self, rect: R2, func: F) -> Result<R, String> where
    F: FnOnce(&mut [u8], usize) -> R,
    R2: Into<Option<Rect>>, 

Locks the texture for write-only pixel access. The texture must have been created with streaming access.

F is a function that is passed the write-only texture buffer, and the pitch of the texture (size of a row in bytes).

Remarks

As an optimization, the pixels made available for editing don't necessarily contain the old texture data. This is a write-only operation, and if you need to keep a copy of the texture data you should do that at the application level.

pub unsafe fn gl_bind_texture(&mut self) -> (f32, f32)

Binds an OpenGL/ES/ES2 texture to the current context for use with when rendering OpenGL primitives directly.

pub unsafe fn gl_unbind_texture(&mut self)

Unbinds an OpenGL/ES/ES2 texture from the current context.

pub fn gl_with_bind<R, F>(&mut self, f: F) -> R where
    F: FnOnce(f32, f32) -> R, 

Binds and unbinds an OpenGL/ES/ES2 texture from the current context.

pub const fn raw(&self) -> *mut SDL_Texture