Struct Surface

pub struct Surface { /* private fields */ }

A software-rendered surface that is implicitly associated with the underlying window (like glutin::RawContext).

Implementations

impl Surface

pub unsafe fn new(window: &Window, context: &Context, config: &Config) -> Self

Construct and attach a surface to the specified window.

Unsafety: The constructed Surface must be dropped before window.

pub fn update_surface(&self, extent: [u32; 2], format: Format)

Update the properties of the surface.

After resizing a window, you must call this method irregardless of whether you want to change the image size or not. Also, you must call this method at least once before calling other methods.

The result of a mismatching image size is implementation-dependent. In general, you should use update_surface_to_fit.

Panics if:

• format is not in supported_formats().
• One of extent’s elements is zero.
• One or more swapchain images are locked.

pub fn update_surface_to_fit(&self, window: &Window, format: Format)

Update the properties of the surface. The surface size is automatically derived based on the window size.

This internally calls update_surface.

pub fn supported_formats(&self) -> impl Iterator<Item = Format> + '_

Enumerate supported pixel formats.

pub fn image_info(&self) -> ImageInfo

Get the ImageInfo describing the current swapchain images.

pub fn num_images(&self) -> usize

Get the number of swapchain images.

This value is automatically calculated when update_surface is called.

This value does not reflect the actual number of buffers that stand between the application and the display hardware. It’s only useful when does_preserve_image() == true and the application wants to track dirty regions in each swapchain image.

pub fn does_preserve_image(&self) -> bool

Get a flag indicating whether swapchain images preserve their contents when their indices are used again.

If this function returns true, the application can optimize rendering by only updating the dirty portions.

pub fn poll_next_image(&self) -> Option<usize>

Get the index of the next available swapchain image.

Returns None if no image is available. In this case, the function specified via ContextBuilder::with_ready_cb will be called when one is ready. If you call poll_next_image for multiple times before the callback function is called for the next time, and all of the calls to poll_next_image returns None, then the callback function will be called only once.

The application cannot rely on image unavailability for metering the rendering speed even if Config::vsync is enabled.

update_surface may or may not cancel the deferred call to the callback.

If an image is returned, this method does not remove the image from the set of avilable images. For example, if the application calls poll_next_image repeatedly, it may return the same image index for all of the calls.

pub fn lock_image(&self, i: usize) -> impl Deref<Target = [u8]> + DerefMut + '_

Lock a swapchain image at index i to access its contents.

i must be the index of a swapchain image acquired by poll_next_image.

Panics if the image is currently locked or not ready to be accessed by the application.

Given an ImageInfo, the length is calculated as: extent[1] * stride * 4.

pub fn present_image(&self, i: usize)

Enqueue the presentation of a swapchain image at index i.

This method removes the swapchain image at index i from the set of available images and enqueues it for presentation.

i must be the index of a swapchain image acquired by poll_next_image. The image must not be locked by lock_image.

Trait Implementations

impl Debug for Surface

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

Formats the value using the given formatter.