Struct Surface

pub struct Surface<'a> { /* private fields */ }

Available on crate feature dep_sdl3 only.

Holds an Arc<SurfaceContext>.

Note: If a Surface goes out of scope but it cloned its context, then the SDL_Surface will not be free’d until there are no more references to the SurfaceContext.

Implementations

impl<'a> Surface<'a>

pub unsafe fn from_ll<'b>(raw: *mut SDL_Surface) -> Surface<'b>

pub fn new( width: u32, height: u32, format: PixelFormat, ) -> Result<Surface<'static>, Error>

Creates a new surface using a pixel format.

Example

use sdl3::pixels::PixelFormat;
use sdl3::surface::Surface;

let surface = Surface::new(512, 512, PixelFormat::RGB24).unwrap();

pub fn from_pixelmasks( width: u32, height: u32, masks: &PixelMasks, ) -> Result<Surface<'static>, Error>

Creates a new surface using pixel masks.

Example

use sdl3::pixels::PixelFormat;
use sdl3::surface::Surface;

let masks = PixelFormat::RGB24.into_masks().unwrap();
let surface = Surface::from_pixelmasks(512, 512, &masks).unwrap();

pub fn from_data( data: &'a mut [u8], width: u32, height: u32, pitch: u32, format: PixelFormat, ) -> Result<Surface<'a>, Error>

Creates a new surface from an existing buffer, using a pixel format.

pub fn from_data_pixelmasks( data: &'a mut [u8], width: u32, height: u32, pitch: u32, masks: &PixelMasks, ) -> Result<Surface<'a>, Error>

Creates a new surface from an existing buffer, using pixel masks.

pub fn as_texture<'b, T>( &self, texture_creator: &'b TextureCreator<T>, ) -> Result<Texture<'b>, TextureValueError>

A convenience function for TextureCreator::create_texture_from_surface.

use sdl3::pixels::PixelFormat;
use sdl3::surface::Surface;
use sdl3::render::{Canvas, Texture};
use sdl3::video::Window;

// We init systems.
let sdl_context = sdl3::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("sdl3 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();
let texture_creator = canvas.texture_creator();

let surface = Surface::new(512, 512, PixelFormat::RGB24).unwrap();
let texture = surface.as_texture(&texture_creator).unwrap();

pub fn load_bmp_rw( iostream: &mut IOStream<'_>, ) -> Result<Surface<'static>, Error>

pub fn load_bmp<P>(path: P) -> Result<Surface<'static>, Error>

where P: AsRef<Path>,

pub fn into_canvas(self) -> Result<Canvas<Surface<'a>>, Error>

Creates a Software Canvas to allow rendering in the Surface itself. This Canvas will never be accelerated materially, so there is no performance change between Surface and Canvas coming from a Surface.

The only change is this case is that Canvas has a better API to draw stuff in the Surface in that case, but don’t expect any performance changes, there will be none.

pub fn context(&self) -> Arc<SurfaceContext<'a>>

Methods from Deref<Target = SurfaceRef>

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

pub fn width(&self) -> u32

pub fn height(&self) -> u32

pub fn pitch(&self) -> u32

pub fn size(&self) -> (u32, u32)

pub fn rect(&self) -> Rect

Gets the rect of the surface.

pub fn pixel_format(&self) -> PixelFormat

pub fn pixel_format_enum(&self) -> PixelFormat

pub fn with_lock<R, F>(&self, f: F) -> R

where F: FnOnce(&[u8]) -> R,

Locks a surface so that the pixels can be directly accessed safely.

pub fn with_lock_mut<R, F>(&mut self, f: F) -> R

where F: FnOnce(&mut [u8]) -> R,

Locks a surface so that the pixels can be directly accessed safely.

pub unsafe fn without_lock(&self) -> Option<&[u8]>

Returns the Surface’s pixel buffer if the Surface doesn’t require locking (e.g. it’s a software surface).

pub unsafe fn without_lock_mut(&mut self) -> Option<&mut [u8]>

Returns the Surface’s pixel buffer if the Surface doesn’t require locking (e.g. it’s a software surface).

pub unsafe fn must_lock(&self) -> bool

Returns true if the Surface needs to be locked before accessing the Surface pixels.

pub fn save_bmp_rw(&self, iostream: &mut IOStream<'_>) -> Result<(), Error>

pub fn save_bmp<P>(&self, path: P) -> Result<(), Error>

where P: AsRef<Path>,

pub fn set_palette(&mut self, palette: &Palette) -> Result<(), Error>

pub fn enable_RLE(&mut self)

pub fn disable_RLE(&mut self)

pub fn set_color_key(&mut self, enable: bool, color: Color) -> Result<(), Error>

pub fn color_key(&self) -> Result<Color, Error>

The function will fail if the surface doesn’t have color key enabled.

pub fn set_color_mod(&mut self, color: Color)

pub fn color_mod(&self) -> Color

pub fn fill_rect<R>(&mut self, rect: R, color: Color) -> Result<(), Error>

where R: Into<Option<Rect>>,

pub fn fill_rects(&mut self, rects: &[Rect], color: Color) -> Result<(), Error>

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

pub fn alpha_mod(&self) -> u8

pub fn set_blend_mode(&mut self, mode: BlendMode) -> Result<(), Error>

The function will fail if the blend mode is not supported by SDL.

pub fn blend_mode(&self) -> BlendMode

pub fn set_clip_rect<R>(&mut self, rect: R) -> bool

where R: Into<Option<Rect>>,

Sets the clip rectangle for the surface.

If the rectangle is None, clipping will be disabled.

pub fn clip_rect(&self) -> Option<Rect>

Gets the clip rectangle for the surface.

Returns None if clipping is disabled.

pub fn convert(&self, format: &PixelFormat) -> Result<Surface<'static>, Error>

Copies the surface into a new one that is optimized for blitting to a surface of a specified pixel format.

pub fn convert_format( &self, format: PixelFormat, ) -> Result<Surface<'static>, Error>

Copies the surface into a new one of a specified pixel format.

pub fn blit<R1, R2>( &self, src_rect: R1, dst: &mut SurfaceRef, dst_rect: R2, ) -> Result<Option<Rect>, Error>

where R1: Into<Option<Rect>>, R2: Into<Option<Rect>>,

Performs surface blitting (surface copying).

Returns the final blit rectangle, if a dst_rect was provided.

pub unsafe fn lower_blit<R1, R2>( &self, src_rect: R1, dst: &mut SurfaceRef, dst_rect: R2, ) -> Result<(), Error>

where R1: Into<Option<Rect>>, R2: Into<Option<Rect>>,

Performs low-level surface blitting.

Unless you know what you’re doing, use blit() instead, which will clip the input rectangles. This function could crash if the rectangles aren’t pre-clipped to the surface, and is therefore unsafe.

pub unsafe fn soft_stretch_linear<R1, R2>( &self, src_rect: R1, dst: &mut SurfaceRef, dst_rect: R2, ) -> Result<Option<Rect>, Error>

where R1: Into<Option<Rect>>, R2: Into<Option<Rect>>,

Performs bilinear scaling between two surfaces of the same format, 32BPP.

Returns the final blit rectangle, if a dst_rect was provided.

pub fn blit_scaled<R1, R2>( &self, src_rect: R1, dst: &mut SurfaceRef, dst_rect: R2, scale_mode: SDL_ScaleMode, ) -> Result<Option<Rect>, Error>

where R1: Into<Option<Rect>>, R2: Into<Option<Rect>>,

Performs scaled surface bliting (surface copying).

Returns the final blit rectangle, if a dst_rect was provided.

pub unsafe fn lower_blit_scaled<R1, R2>( &self, src_rect: R1, dst: &mut SurfaceRef, dst_rect: R2, scale_mode: SDL_ScaleMode, ) -> Result<(), Error>

where R1: Into<Option<Rect>>, R2: Into<Option<Rect>>,

Performs low-level scaled surface blitting.

Unless you know what you’re doing, use blit_scaled() instead, which will clip the input rectangles. This function could crash if the rectangles aren’t pre-clipped to the surface, and is therefore unsafe.

Trait Implementations

impl AsMut<SurfaceRef> for Surface<'_>

fn as_mut(&mut self) -> &mut SurfaceRef

Converts this type into a mutable reference of the (usually inferred) input type.

impl AsRef<SurfaceRef> for Surface<'_>

fn as_ref(&self) -> &SurfaceRef

Converts this type into a shared reference of the (usually inferred) input type.

impl Deref for Surface<'_>

type Target = SurfaceRef

The resulting type after dereferencing.

fn deref(&self) -> &SurfaceRef

Dereferences the value.

impl DerefMut for Surface<'_>

fn deref_mut(&mut self) -> &mut SurfaceRef

Mutably dereferences the value.

impl<'s> RenderTarget for Surface<'s>

type Context = SurfaceContext<'s>