Trait Surface

pub trait Surface: WasmNotSendSync {
    type A: Api;

    // Required methods
    unsafe fn configure(
        &self,
        device: &<Self::A as Api>::Device,
        config: &SurfaceConfiguration,
    ) -> Result<(), SurfaceError>;
    unsafe fn unconfigure(&self, device: &<Self::A as Api>::Device);
    unsafe fn acquire_texture(
        &self,
        timeout: Option<Duration>,
        fence: &<Self::A as Api>::Fence,
    ) -> Result<Option<AcquiredSurfaceTexture<Self::A>>, SurfaceError>;
    unsafe fn discard_texture(&self, texture: <Self::A as Api>::SurfaceTexture);
}

Required Associated Types

type A: Api

Required Methods

unsafe fn configure( &self, device: &<Self::A as Api>::Device, config: &SurfaceConfiguration, ) -> Result<(), SurfaceError>

Configure self to use device.

Safety

• All GPU work using self must have been completed.
• All AcquiredSurfaceTextures must have been destroyed.
• All Api::TextureViews derived from the AcquiredSurfaceTextures must have been destroyed.
• The surface self must not currently be configured to use any other Device.

unsafe fn unconfigure(&self, device: &<Self::A as Api>::Device)

Unconfigure self on device.

Safety

• All GPU work that uses surface must have been completed.
• All AcquiredSurfaceTextures must have been destroyed.
• All Api::TextureViews derived from the AcquiredSurfaceTextures must have been destroyed.
• The surface self must have been configured on device.

unsafe fn acquire_texture( &self, timeout: Option<Duration>, fence: &<Self::A as Api>::Fence, ) -> Result<Option<AcquiredSurfaceTexture<Self::A>>, SurfaceError>

Return the next texture to be presented by self, for the caller to draw on.

On success, return an AcquiredSurfaceTexture representing the texture into which the caller should draw the image to be displayed on self.

If timeout elapses before self has a texture ready to be acquired, return Ok(None). If timeout is None, wait indefinitely, with no timeout.

Using an AcquiredSurfaceTexture

On success, this function returns an AcquiredSurfaceTexture whose texture field is a SurfaceTexture from which the caller can borrow a Texture to draw on. The AcquiredSurfaceTexture also carries some metadata about that SurfaceTexture.

All calls to Queue::submit that draw on that Texture must also include the SurfaceTexture in the surface_textures argument.

When you are done drawing on the texture, you can display it on self by passing the SurfaceTexture and self to Queue::present.

If you do not wish to display the texture, you must pass the SurfaceTexture to self.discard_texture, so that it can be reused by future acquisitions.

Portability

Some backends can’t support a timeout when acquiring a texture. On these backends, timeout is ignored.

Safety

• The surface self must currently be configured on some Device.

• The fence argument must be the same Fence passed to all calls to Queue::submit that used Textures acquired from this surface.

• You may only have one texture acquired from self at a time. When acquire_texture returns Ok(Some(ast)), you must pass the returned SurfaceTexture ast.texture to either Queue::present or Surface::discard_texture before calling acquire_texture again.

unsafe fn discard_texture(&self, texture: <Self::A as Api>::SurfaceTexture)

Relinquish an acquired texture without presenting it.

After this call, the texture underlying SurfaceTexture may be returned by subsequent calls to self.acquire_texture.

Safety

• The surface self must currently be configured on some Device.

• texture must be a SurfaceTexture returned by a call to self.acquire_texture that has not yet been passed to Queue::present.

Implementors

impl Surface for Context

type A = Api

impl Surface for Surface

Available on vulkan only.

type A = Api