Trait Instance

pub trait Instance<B: Backend>:
    Any
    + Send
    + Sync
    + Sized {
    // Required methods
    fn create(name: &str, version: u32) -> Result<Self, UnsupportedBackend>;
    fn enumerate_adapters(&self) -> Vec<Adapter<B>>;
    unsafe fn create_surface(
        &self,
        raw_window_handle: &impl HasRawWindowHandle,
    ) -> Result<B::Surface, InitError>;
    unsafe fn destroy_surface(&self, surface: B::Surface);
    unsafe fn create_display_plane_surface<'a>(
        &self,
        display_plane: &DisplayPlane<'a, B>,
        plane_stack_index: u32,
        transformation: SurfaceTransform,
        alpha: DisplayPlaneAlpha,
        image_extent: Extent2D,
    ) -> Result<B::Surface, DisplayPlaneSurfaceError>;
}

An instantiated backend.

Any startup the backend needs to perform will be done when creating the type that implements Instance.

Examples

use gfx_backend_empty as backend;
use gfx_hal::Instance;

// Create a concrete instance of our backend (this is backend-dependent and may be more
// complicated for some backends).
let instance = backend::Instance::create("My App", 1).unwrap();
// We can get a list of the available adapters, which are either physical graphics
// devices, or virtual adapters. Because we are using the dummy `empty` backend,
// there will be nothing in this list.
for (idx, adapter) in instance.enumerate_adapters().iter().enumerate() {
    println!("Adapter {}: {:?}", idx, adapter.info);
}

Required Methods

fn create(name: &str, version: u32) -> Result<Self, UnsupportedBackend>

Create a new instance.

Arguments

• name - name of the application using the API.
• version - free form representation of the application’s version.

This metadata is passed further down the graphics stack.

Errors

Returns an Err variant if the requested backend is not supported on the current platform.

fn enumerate_adapters(&self) -> Vec<Adapter<B>>

Return all available graphics adapters.

unsafe fn create_surface( &self, raw_window_handle: &impl HasRawWindowHandle, ) -> Result<B::Surface, InitError>

Create a new surface.

Surfaces can be used to render to windows.

Safety

This method can cause undefined behavior if raw_window_handle isn’t a handle to a valid window for the current platform.

unsafe fn destroy_surface(&self, surface: B::Surface)

Destroy a surface, freeing the resources associated with it and releasing it from this graphics API.

Safety

unsafe fn create_display_plane_surface<'a>( &self, display_plane: &DisplayPlane<'a, B>, plane_stack_index: u32, transformation: SurfaceTransform, alpha: DisplayPlaneAlpha, image_extent: Extent2D, ) -> Result<B::Surface, DisplayPlaneSurfaceError>

Create a new surface from a display plane.

Surfaces can be used to render to windows.

Safety

This method can cause undefined behavior if raw_window_handle isn’t a handle to a valid window for the current platform.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors