Smithay

https://docs.rs/smithay/latest/
Admin
Smithay is a general framework for building Wayland compositors, providing low-level helpers and...
Tokens:1,297,444
Snippets:10,981
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Trim Start Matches Examples

Source: https://docs.rs/smithay/latest/smithay/wayland/xdg_activation/struct.XdgActivationToken.html

Demonstrates removing prefixes that match a specific pattern.

```rust
assert_eq!("11foo1bar11".trim_start_matches('1'), "foo1bar11");
assert_eq!("123foo1bar123".trim_start_matches(char::is_numeric), "foo1bar123");
```

--------------------------------

### Trim Start Examples

Source: https://docs.rs/smithay/latest/smithay/wayland/xdg_activation/struct.XdgActivationToken.html

Demonstrates trimming leading whitespace from strings, including handling of right-to-left languages.

```rust
let s = "  עברית  ";
assert!(Some('ע') == s.trim_start().chars().next());
```

--------------------------------

### Implementing DMABUF Handling in a Compositor

Source: https://docs.rs/smithay/latest/src/smithay/wayland/dmabuf/mod.rs.html

Example showing the implementation of DmabufHandler and BufferHandler, along with the setup of DmabufState and DmabufGlobal.

```rust
use smithay::{
    delegate_dmabuf,
    backend::allocator::dmabuf::{Dmabuf},
    reexports::{
        wayland_server::protocol::{
            wl_buffer::WlBuffer,
            wl_surface::WlSurface,
        }
    },
    wayland::{
        buffer::BufferHandler,
        dmabuf::{DmabufFeedback, DmabufFeedbackBuilder, DmabufGlobal, DmabufHandler, DmabufState, ImportNotifier}
    },
};

pub struct State {
    dmabuf_state: DmabufState,
    dmabuf_global: DmabufGlobal,
}

// Smithay's "DmabufHandler" also requires the buffer management utilities, you need to implement
// "BufferHandler".
impl BufferHandler for State {
    fn buffer_destroyed(&mut self, buffer: &wayland_server::protocol::wl_buffer::WlBuffer) {
        // All renderers can handle buffer destruction at this point. Some parts of window management may
        // also use this function.
        //
        // If you need to mark a dmabuf elsewhere in your state as destroyed, you use the "get_dmabuf"
        // function defined in this module to access the dmabuf associated the "Buffer".
    }
}

impl DmabufHandler for State {
    fn dmabuf_state(&mut self) -> &mut DmabufState {
        &mut self.dmabuf_state
    }

    fn dmabuf_imported(&mut self, global: &DmabufGlobal, dmabuf: Dmabuf, notifier: ImportNotifier) {
        // Here you should import the dmabuf into your renderer.
        //
        // The notifier is used to communicate whether import was successful. In this example we
        // call successful to notify the client import was successful.
        notifier.successful::<State>();
    }

    fn new_surface_feedback(
        &mut self,
        surface: &WlSurface,
        global: &DmabufGlobal,
    ) -> Option<DmabufFeedback> {
        // Here you can override the initial feedback sent to a client requesting feedback for a specific
        // surface. Returning `None` instructs the global to return the default feedback to the client which
        // is also the default implementation for this function when not overridden
        None
    }
}

// Delegate dmabuf handling for State to DmabufState.
delegate_dmabuf!(State);

# let mut display = wayland_server::Display::<State>::new().unwrap();
# let display_handle = display.handle();
// First a DmabufState must be created. This type is used to create some "DmabufGlobal"s
let mut dmabuf_state = DmabufState::new();

// ...identify primary render node and load dmabuf formats supported for rendering...
# let main_device = { todo!() };
# let formats: Vec<_> = { todo!() };

// Build the default feedback from the device node of the primary render node and
// the supported dmabuf formats
let default_feedback = DmabufFeedbackBuilder::new(main_device, formats).build().unwrap();

// And create the dmabuf global.
let dmabuf_global = dmabuf_state.create_global_with_default_feedback::<State>(
    &display_handle,
    &default_feedback,
);

let state = State {
    dmabuf_state,
    dmabuf_global,
};

// Rest of the compositor goes here...
```

--------------------------------

### Trim start matches example

Source: https://docs.rs/smithay/latest/smithay/wayland/xdg_activation/struct.XdgActivationToken.html

Demonstrates removing characters from the start of a string slice based on a pattern.

```rust
let x: &[_] = &['1', '2'];
assert_eq!("12foo1bar12".trim_start_matches(x), "foo1bar12");
```

--------------------------------

### Usage Example

Source: https://docs.rs/smithay/latest/smithay/macro.egl_platform.html

Demonstrates initializing an EGL platform using the macro with required extensions.

```rust
use smithay::backend::egl::{ffi, native::EGLPlatform};
use smithay::egl_platform;

// see: https://www.khronos.org/registry/EGL/extensions/KHR/EGL_KHR_platform_gbm.txt
egl_platform!(PLATFORM_GBM_KHR, native_display, &["EGL_KHR_platform_gbm"]);
```

--------------------------------

### start_wm

Source: https://docs.rs/smithay/latest/smithay/xwayland/xwm/struct.X11Wm.html

Initializes and starts a new window manager for a given Xwayland connection.

```APIDOC
### pub fn start_wm<D>(handle: LoopHandle<'static, D>, connection: UnixStream, client: Client) -> Result<Self, Box<dyn Error>>

Starts a new window manager for a given Xwayland connection. Requires the `xwayland` feature.
```

--------------------------------

### Option::as_slice Examples

Source: https://docs.rs/smithay/latest/smithay/backend/renderer/gles/ffi/types/type.GLDEBUGPROCKHR.html

Examples demonstrating the use of as_slice to treat an Option as a slice.

```rust
assert_eq!(
    [Some(1234).as_slice(), None.as_slice()],
    [&[1234][..], &[][..]],
);
```

```rust
for i in [Some(1234_u16), None] {
    assert_eq!(i.as_ref(), i.as_slice().first());
}
```

--------------------------------

### Option::is_none_or Examples

Source: https://docs.rs/smithay/latest/smithay/backend/renderer/gles/ffi/types/type.GLDEBUGPROCKHR.html

Examples demonstrating the use of the is_none_or method with a predicate.

```rust
let x: Option<u32> = Some(2);
assert_eq!(x.is_none_or(|x| x > 1), true);

let x: Option<u32> = Some(0);
assert_eq!(x.is_none_or(|x| x > 1), false);

let x: Option<u32> = None;
assert_eq!(x.is_none_or(|x| x > 1), true);

let x: Option<String> = Some("ownership".to_string());
assert_eq!(x.as_ref().is_none_or(|x| x.len() > 1), true);
println!("still alive {:?}", x);
```

--------------------------------

### Option::is_none Examples

Source: https://docs.rs/smithay/latest/smithay/backend/renderer/gles/ffi/types/type.GLDEBUGPROCKHR.html

Examples demonstrating the use of the is_none method on an Option.

```rust
let x: Option<u32> = Some(2);
assert_eq!(x.is_none(), false);

let x: Option<u32> = None;
assert_eq!(x.is_none(), true);
```

--------------------------------

### RefCell::take Example

Source: https://docs.rs/smithay/latest/smithay/wayland/commit_timing/type.CommitTimerStateUserData.html

Example usage of the take method on RefCell.

```rust
use std::cell::RefCell;

let c = RefCell::new(5);
let five = c.take();

assert_eq!(five, 5);
assert_eq!(c.into_inner(), 0);
```

--------------------------------

### Option::is_some_and Examples

Source: https://docs.rs/smithay/latest/smithay/backend/renderer/gles/ffi/types/type.GLDEBUGPROCKHR.html

Examples demonstrating the use of the is_some_and method with a predicate.

```rust
let x: Option<u32> = Some(2);
assert_eq!(x.is_some_and(|x| x > 1), true);

let x: Option<u32> = Some(0);
assert_eq!(x.is_some_and(|x| x > 1), false);

let x: Option<u32> = None;
assert_eq!(x.is_some_and(|x| x > 1), false);

let x: Option<String> = Some("ownership".to_string());
assert_eq!(x.as_ref().is_some_and(|x| x.len() > 1), true);
println!("still alive {:?}", x);
```

--------------------------------

### Initialize XdgShellState

Source: https://docs.rs/smithay/latest/src/smithay/wayland/shell/xdg/mod.rs.html

Example of initializing the shell state with a global resource.

```rust
let global = display.create_global::<D, XdgWmBase, _>(6, ());

XdgShellState {
    known_toplevels: Vec::new(),
    known_popups: Vec::new(),
    default_capabilities: capabilities.into(),
    global,
}
```

--------------------------------

### Option::as_ref Example

Source: https://docs.rs/smithay/latest/smithay/backend/renderer/gles/ffi/types/type.GLDEBUGPROCKHR.html

Example demonstrating the use of as_ref to convert an Option<String> to an Option<&String>.

```rust
let text: Option<String> = Some("Hello, world!".to_string());
// First, cast `Option<String>` to `Option<&String>` with `as_ref`,
// then consume *that* with `map`, leaving `text` on the stack.
let text_length: Option<usize> = text.as_ref().map(|s| s.len());
println!("still can print text: {text:?}");
```

--------------------------------

### Strip prefix examples

Source: https://docs.rs/smithay/latest/smithay/wayland/xdg_activation/struct.XdgActivationToken.html

Examples of removing a prefix exactly once if it exists, returning an Option.

```rust
assert_eq!("foo:bar".strip_prefix("foo:"), Some("bar"));
assert_eq!("foo:bar".strip_prefix("bar"), None);
assert_eq!("foofoo".strip_prefix("foo"), Some("foo"));
```

--------------------------------

### Option Product Iterator Examples

Source: https://docs.rs/smithay/latest/smithay/backend/renderer/gles/ffi/types/type.GLDEBUGPROCARB.html

Demonstrates how Option product behavior short-circuits on None values.

```rust
assert_eq!(res, Some(vec![1, 2, 3]));
```

```rust
let items = vec![2_u16, 1, 0];

let res: Option<Vec<u16>> = items
    .iter()
    .map(|x| x.checked_sub(1))
    .collect();

assert_eq!(res, None);
```

```rust
let items = vec![3_u16, 2, 1, 10];

let mut shared = 0;

let res: Option<Vec<u16>> = items
    .iter()
    .map(|x| { shared += x; x.checked_sub(2) })
    .collect();

assert_eq!(res, None);
assert_eq!(shared, 6);
```

--------------------------------

### Usage example for load_with

Source: https://docs.rs/smithay/latest/smithay/backend/egl/ffi/egl/fn.load_with.html

Example of using a custom loader function to resolve OpenGL symbols.

```rust
gl::load_with(|s| glfw.get_proc_address(s));
```

--------------------------------

### Trim prefix examples

Source: https://docs.rs/smithay/latest/smithay/wayland/xdg_activation/struct.XdgActivationToken.html

Experimental API examples for removing a prefix and returning the string slice directly for chaining.

```rust
#![feature(trim_prefix_suffix)]

// Prefix present - removes it
assert_eq!("foo:bar".trim_prefix("foo:"), "bar");
assert_eq!("foofoo".trim_prefix("foo"), "foo");

// Prefix absent - returns original string
assert_eq!("foo:bar".trim_prefix("bar"), "foo:bar");

// Method chaining example
assert_eq!("<https://example.com/>".trim_prefix('<').trim_suffix('>'), "https://example.com/");
```

--------------------------------

### Initialize and monitor udev devices

Source: https://docs.rs/smithay/latest/smithay/backend/udev/index.html

Demonstrates initializing the UdevBackend, retrieving the initial device list, and inserting the backend into a calloop event loop for monitoring.

```rust
use smithay::backend::udev::{UdevBackend, UdevEvent};

let udev = UdevBackend::new("seat0").expect("Failed to monitor udev.");

for (dev_id, node_path) in udev.device_list() {
    // process the initial list of devices
}

// setup the event source for long-term monitoring
loop_handle.insert_source(udev, |event, _, _dispatch_data| match event {
    UdevEvent::Added { device_id, path } => {
        // a new device has been added
    },
    UdevEvent::Changed { device_id } => {
        // a device has been changed
    },
    UdevEvent::Removed { device_id } => {
        // a device has been removed
    }
}).expect("Failed to insert the udev source into the event loop");
```

--------------------------------

### Initialize X11 Backend

Source: https://docs.rs/smithay/latest/smithay/backend/x11/index.html

Demonstrates the initialization of the X11 backend, window creation, and surface setup for rendering.

```rust
use smithay::backend::allocator::dmabuf::DmabufAllocator;
use smithay::backend::allocator::gbm::{GbmAllocator, GbmDevice, GbmBufferFlags};
use smithay::backend::egl::{EGLDisplay, EGLContext};
use smithay::utils::DeviceFd;
use std::collections::HashSet;

fn init_x11_backend(
   handle: calloop::LoopHandle<CompositorState>,
) -> Result<(), Box<dyn Error>> {
    // Create the backend
    let backend = X11Backend::new()?;

    // Get a handle from the backend to interface with the X server
    let x_handle = backend.handle();
    // Create a window
    let window = WindowBuilder::new()
        .title("Wayland inside X11")
        .build(&x_handle)
        .expect("Could not create window");

    // To render to a window, we need to create an X11 surface.

    // Get the DRM node used by the X server for direct rendering.
    let (_drm_node, fd) = x_handle.drm_node()?;
    // Create the gbm device for allocating buffers
    let device = GbmDevice::new(DeviceFd::from(fd))?;
    // Initialize EGL to retrieve the support modifier list
    let egl = unsafe { EGLDisplay::new(device.clone()).expect("Failed to create EGLDisplay") };
    let context = EGLContext::new(&egl).expect("Failed to create EGLContext");
    let modifiers = context.dmabuf_render_formats().iter().map(|format| format.modifier).collect::<HashSet<_>>();

    // Finally create the X11 surface, you will use this to obtain buffers that will be presented to the
    // window.
    let surface = x_handle.create_surface(&window, DmabufAllocator(GbmAllocator::new(device, GbmBufferFlags::RENDERING)), modifiers.into_iter());

    // Insert the backend into the event loop to receive events.
    handle.insert_source(backend, |event, _window, state| {
        // Process events from the X server that apply to the window.
    })?;

    Ok(())
}
```

--------------------------------

### X11Backend::new

Source: https://docs.rs/smithay/latest/smithay/backend/x11/struct.X11Backend.html

Initializes the X11 backend by connecting to the X server.

```APIDOC
## pub fn new() -> Result<X11Backend, X11Error>

### Description
Initializes the X11 backend by connecting to the X server.

### Returns
- **Result<X11Backend, X11Error>** - Returns an instance of X11Backend on success, or an X11Error if the connection fails.
```

--------------------------------

### Trim ASCII whitespace

Source: https://docs.rs/smithay/latest/smithay/backend/renderer/element/memory/struct.MemoryBuffer.html

Examples for trimming ASCII whitespace from the start, end, or both sides of a byte slice.

```rust
assert_eq!(b" \t hello world\n".trim_ascii_start(), b"hello world\n");
assert_eq!(b"  ".trim_ascii_start(), b"");
assert_eq!(b"".trim_ascii_start(), b"");
```

```rust
assert_eq!(b"\r hello world\n ".trim_ascii_end(), b"\r hello world");
assert_eq!(b"  ".trim_ascii_end(), b"");
assert_eq!(b"".trim_ascii_end(), b"");
```

```rust
assert_eq!(b"\r hello world\n ".trim_ascii(), b"hello world");
assert_eq!(b"  ".trim_ascii(), b"");
assert_eq!(b"".trim_ascii(), b"");
```

--------------------------------

### Instance::new

Source: https://docs.rs/smithay/latest/smithay/backend/vulkan/struct.Instance.html

Creates a new Vulkan Instance with default settings.

```APIDOC
## pub fn new(max_version: Version, app_info: Option<AppInfo>) -> Result<Instance, InstanceError>

### Description
Creates a new Vulkan Instance. This is the primary entry point for initializing the Vulkan state.

### Parameters
- **max_version** (Version) - Required - The maximum Vulkan version to request.
- **app_info** (Option<AppInfo>) - Optional - Application information to provide to the Vulkan driver.
```

--------------------------------

### Retrieve match indices for a pattern

Source: https://docs.rs/smithay/latest/smithay/wayland/xdg_activation/struct.XdgActivationToken.html

Use match_indices to get an iterator over disjoint matches and their starting indices.

```rust
let v: Vec<_> = "abcXXXabcYYYabc".match_indices("abc").collect();
assert_eq!(v, [(0, "abc"), (6, "abc"), (12, "abc")]);

let v: Vec<_> = "1abcabc2".match_indices("abc").collect();
assert_eq!(v, [(1, "abc"), (4, "abc")]);

let v: Vec<_> = "ababa".match_indices("aba").collect();
assert_eq!(v, [(0, "aba")]); // only the first `aba`
```

--------------------------------

### Instantiate and configure an Output

Source: https://docs.rs/smithay/latest/smithay/output/index.html

Demonstrates creating a new Output instance with physical properties and configuring its state, modes, and scaling.

```rust
use smithay::output::{Output, PhysicalProperties, Scale, Mode, Subpixel};
use smithay::utils::Transform;

// Create the Output with given name and physical properties.
let output = Output::new(
    "output-0".into(), // the name of this output,
    PhysicalProperties {
        size: (200, 150).into(),        // dimensions (width, height) in mm
        subpixel: Subpixel::HorizontalRgb,  // subpixel information
        make: "Screens Inc".into(),     // make of the monitor
        model: "Monitor Ultra".into(),  // model of the monitor
    },
);
// Now you can configure it
output.change_current_state(
    Some(Mode { size: (1920, 1080).into(), refresh: 60000 }), // the resolution mode,
    Some(Transform::Normal), // global screen transformation
    Some(Scale::Integer(1)), // global screen scaling factor
    Some((0,0).into()) // output position
);
// set the preferred mode
output.set_preferred(Mode { size: (1920, 1080).into(), refresh: 60000 });
// add other supported modes
output.add_mode(Mode { size: (800, 600).into(), refresh: 60000 });
output.add_mode(Mode { size: (1024, 768).into(), refresh: 60000 });
```

--------------------------------

### Initialize TextureRenderBuffer

Source: https://docs.rs/smithay/latest/src/smithay/backend/renderer/element/texture.rs.html

Shows the initial setup for a hardware-accelerated render buffer.

```rust
# use smithay::{
#     backend::renderer::{Color32F, DebugFlags, Frame, ImportMem, Renderer, Texture, TextureFilter, sync::SyncPoint, test::{DummyRenderer, DummyFramebuffer}},
#     utils::{Buffer, Physical},
# };
use std::time::{Duration, Instant};

use smithay::{
    backend::{
        allocator::Fourcc,
        renderer::{
            damage::OutputDamageTracker,
            element::{
                Kind,
                texture::{TextureRenderBuffer, TextureRenderElement},
            },
        },
    },
    utils::{Point, Rectangle, Size, Transform},
};

const WIDTH: i32 = 10;
```

--------------------------------

### Result::is_ok Example

Source: https://docs.rs/smithay/latest/smithay/backend/drm/output/type.DrmOutputManagerResult.html

Example of checking if a Result is Ok.

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_ok(), true);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_ok(), false);
```

--------------------------------

### Initialize tablet manager and seat

Source: https://docs.rs/smithay/latest/smithay/wayland/tablet_manager/index.html

A simplified example showing the initialization of the tablet manager global and adding a tablet to a seat.

```rust
// Init the manager global
let state = TabletManagerState::new::<D>(&display);

// Init the seat
let seat = Seat::<D>::new(
    &display,
    "seat-0".into(),
    None
);

use smithay::wyaldnd::tablet_manager::TabletSeatTrait;

seat
   .tablet_seat()                     // Get TabletSeat asosiated with this seat
   .add_tablet(                       // Add a new tablet to a seat
     display
     &TabletDescriptor {    
       name: "Test".into(),
       usb_id: None,
       syspath: None,
     }
   );
```

--------------------------------

### pub fn from_state(state: &State, mapping: &LedMapping) -> Self

Source: https://docs.rs/smithay/latest/smithay/input/keyboard/struct.LedState.html

Initializes a new LedState instance from the provided XKB state and mapping.

```APIDOC
## pub fn from_state(state: &State, mapping: &LedMapping) -> Self

### Description
Initialize the led state from an xkb state and mapping.

### Parameters
- **state** (&State) - The current XKB state.
- **mapping** (&LedMapping) - The LED mapping configuration.

### Returns
- **Self** - A new instance of LedState.
```

--------------------------------

### Result::flatten Example

Source: https://docs.rs/smithay/latest/smithay/backend/drm/output/type.DrmOutputManagerResult.html

Examples of flattening nested Results.

```rust
let x: Result<Result<&'static str, u32>, u32> = Ok(Ok("hello"));
assert_eq!(Ok("hello"), x.flatten());

let x: Result<Result<&'static str, u32>, u32> = Ok(Err(6));
assert_eq!(Err(6), x.flatten());

let x: Result<Result<&'static str, u32>, u32> = Err(6);
assert_eq!(Err(6), x.flatten());
```

```rust
let x: Result<Result<Result<&'static str, u32>, u32>, u32> = Ok(Ok(Ok("hello")));
assert_eq!(Ok(Ok("hello")), x.flatten());
assert_eq!(Ok("hello"), x.flatten().flatten());
```

--------------------------------

### Result::transpose Example

Source: https://docs.rs/smithay/latest/smithay/backend/drm/output/type.DrmOutputManagerResult.html

Example of transposing a Result of an Option.

```rust
#[derive(Debug, Eq, PartialEq)]
struct SomeErr;

let x: Result<Option<i32>, SomeErr> = Ok(Some(5));
let y: Option<Result<i32, SomeErr>> = Some(Ok(5));
assert_eq!(x.transpose(), y);
```

--------------------------------

### RefCell::swap Example

Source: https://docs.rs/smithay/latest/smithay/wayland/commit_timing/type.CommitTimerStateUserData.html

Example usage of the swap method on RefCell.

```rust
use std::cell::RefCell;
let c = RefCell::new(5);
let d = RefCell::new(6);
c.swap(&d);
assert_eq!(c, RefCell::new(6));
assert_eq!(d, RefCell::new(5));
```

--------------------------------

### RefCell::replace_with Example

Source: https://docs.rs/smithay/latest/smithay/wayland/commit_timing/type.CommitTimerStateUserData.html

Example usage of the replace_with method on RefCell.

```rust
use std::cell::RefCell;
let cell = RefCell::new(5);
let old_value = cell.replace_with(|&mut old| old + 1);
assert_eq!(old_value, 5);
assert_eq!(cell, RefCell::new(6));
```

--------------------------------

### Window Initialization

Source: https://docs.rs/smithay/latest/src/smithay/backend/x11/window_inner.rs.html

Logic for creating a new X11 window, setting up event masks, and configuring window attributes.

```rust
let window_aux = CreateWindowAux::new()
    .event_mask(
        EventMask::EXPOSURE // Be told when the window is exposed
    | EventMask::STRUCTURE_NOTIFY
    | EventMask::EXPOSURE
    | EventMask::NO_EVENT,
    )
    // Border pixel and color map need to be set if our depth may differ from the root depth.
    .border_pixel(screen.black_pixel)
    .colormap(colormap);

let _ = connection.create_window(
    depth.depth,
    window,
    screen.root,
    0,
    0,
    size.w,
    size.h,
    0,
    WindowClass::INPUT_OUTPUT,
    visual_id,
    &window_aux,
)?;

connection.xinput_xi_select_events(
    window,
    &[xinput::EventMask {
        deviceid: 1, // AllMasterDevices
        mask: vec![
            xinput::XIEventMask::KEY_PRESS
                | xinput::XIEventMask::KEY_RELEASE
```

--------------------------------

### RefCell::replace Example

Source: https://docs.rs/smithay/latest/smithay/wayland/commit_timing/type.CommitTimerStateUserData.html

Example usage of the replace method on RefCell.

```rust
use std::cell::RefCell;
let cell = RefCell::new(5);
let old_value = cell.replace(6);
assert_eq!(old_value, 5);
assert_eq!(cell, RefCell::new(6));
```

--------------------------------

### LibinputInputBackend::new

Source: https://docs.rs/smithay/latest/smithay/backend/libinput/struct.LibinputInputBackend.html

Initializes a new LibinputInputBackend instance from an existing libinput context.

```APIDOC
### pub fn new(context: Libinput) -> Self

Initializes a new `LibinputInputBackend` from a given already initialized libinput context.
```

--------------------------------

### Initialize LibinputInputBackend

Source: https://docs.rs/smithay/latest/src/smithay/backend/libinput/mod.rs.html

Create a new instance of the backend using an existing libinput context.

```rust
pub fn new(context: libinput::Libinput) -> Self {
        let span = debug_span!("backend_libinput");
        let _guard = span.enter();

        info!("Initializing a libinput backend");

        drop(_guard);
        LibinputInputBackend {
            context,
            token: None,
            span,
        }
    }
```

--------------------------------

### RefCell::into_inner Example

Source: https://docs.rs/smithay/latest/smithay/wayland/commit_timing/type.CommitTimerStateUserData.html

Example usage of the into_inner method on RefCell.

```rust
use std::cell::RefCell;

let c = RefCell::new(5);

let five = c.into_inner();
```

--------------------------------

### RefCell::new Example

Source: https://docs.rs/smithay/latest/smithay/wayland/commit_timing/type.CommitTimerStateUserData.html

Example usage of the new method on RefCell.

```rust
use std::cell::RefCell;

let c = RefCell::new(5);
```

--------------------------------

### Initialize XWM and Configure Properties

Source: https://docs.rs/smithay/latest/src/smithay/xwayland/xwm/mod.rs.html

Configures X11 root window properties and initializes the XWM state, including XSettings and XFixes extensions.

```rust
        conn.change_property32(
            PropMode::REPLACE,
            screen.root,
            atoms._NET_CLIENT_LIST,
            AtomEnum::WINDOW,
            &[],
        )?;
        conn.change_property32(
            PropMode::REPLACE,
            screen.root,
            atoms._NET_CLIENT_LIST_STACKING,
            AtomEnum::WINDOW,
            &[],
        )?;
        conn.change_property32(
            PropMode::REPLACE,
            screen.root,
            atoms._NET_ACTIVE_WINDOW,
            AtomEnum::WINDOW,
            &[0],
        )?;
        conn.change_property32(
            PropMode::REPLACE,
            screen.root,
            atoms._NET_SUPPORTING_WM_CHECK,
            AtomEnum::WINDOW,
            &[win],
        )?;
        conn.change_property32(
            PropMode::REPLACE,
            win,
            atoms._NET_SUPPORTING_WM_CHECK,
            AtomEnum::WINDOW,
            &[win],
        )?;
        conn.change_property8(
            PropMode::REPLACE,
            win,
            atoms._NET_WM_NAME,
            atoms.UTF8_STRING,
            "Smithay X WM".as_bytes(),
        )?;
        debug!(window = win, "Created WM Window");
        let xsettings = XSettings::new(&conn, screen.root_depth, screen.root, &atoms)?;
        conn.flush()?;

        let conn = Arc::new(conn);
        let source = X11Source::new(Arc::clone(&conn), win, atoms._SMITHAY_CLOSE_CONNECTION);

        let client_data = client.get_data::<XWaylandClientData>().unwrap();
        let client_scale = client_data.compositor_state.clone_client_scale();

        // We need this for the commit hook.
        client_data.user_data().insert_if_missing(|| id);

        let _xfixes_data = conn
            .query_extension(x11rb::protocol::xfixes::X11_EXTENSION_NAME.as_bytes())?
            .reply_unchecked()?
            .ok_or(ConnectionError::UnsupportedExtension)?;
        if !_xfixes_data.present {
            return Err(ConnectionError::UnsupportedExtension.into());
        }
        conn.xfixes_query_version(1, 0)?.reply_unchecked()?; // we just need version 1 for clipboard monitoring

        let clipboard = XWmSelection::new(&conn, &screen, &atoms, atoms.CLIPBOARD)?;
        let primary = XWmSelection::new(&conn, &screen, &atoms, atoms.PRIMARY)?;

        drop(_guard);
        let wm = Self {
            id,
            conn,
            client_scale,
            screen,
            atoms,
            xsettings,
            randr_primary,
            wm_window: win,
            _xfixes_data,
            clipboard,
            primary,
            unpaired_surfaces: Default::default(),
            sequences_to_ignore: Default::default(),
            windows: Vec::new(),
            client_list: Vec::new(),
            client_list_stacking: Vec::new(),
            span,
        };

        let event_handle = handle.clone();
        handle.insert_source(source, move |event, _, data| match event {
            calloop::channel::Event::Msg(event) => {
                if let Err(err) = handle_event(&event_handle, data, id, event) {
                    warn!(id = id.0, err = ?err, "Failed to handle X11 event");
                }
            }
            calloop::channel::Event::Closed => {
                data.disconnected(id);
            }
        })?;
        Ok(wm)
    }
```

--------------------------------

### Output Configuration

Source: https://docs.rs/smithay/latest/src/smithay/output.rs.html

Demonstrates how to instantiate an Output with physical properties and configure its state, including resolution modes and scaling.

```APIDOC
## Output Configuration

### Description
Creates a new output instance with specified physical properties and configures its current state, such as resolution, transformation, and scaling.

### Usage
```rust
use smithay::output::{Output, PhysicalProperties, Scale, Mode, Subpixel};
use smithay::utils::Transform;

// Create the Output with given name and physical properties.
let output = Output::new(
    "output-0".into(),
    PhysicalProperties {
        size: (200, 150).into(),
        subpixel: Subpixel::HorizontalRgb,
        make: "Screens Inc".into(),
        model: "Monitor Ultra".into(),
    },
);

// Configure current state
output.change_current_state(
    Some(Mode { size: (1920, 1080).into(), refresh: 60000 }),
    Some(Transform::Normal),
    Some(Scale::Integer(1)),
    Some((0,0).into())
);

// Set preferred mode and add supported modes
output.set_preferred(Mode { size: (1920, 1080).into(), refresh: 60000 });
output.add_mode(Mode { size: (800, 600).into(), refresh: 60000 });
```
```

--------------------------------

### Initialize EGLPlatform

Source: https://docs.rs/smithay/latest/smithay/backend/egl/native/struct.EGLPlatform.html

Demonstrates how to instantiate a new EGLPlatform with the required platform constant, name, display pointer, attributes, and extensions.

```rust
use smithay::backend::egl::{ffi, native::EGLPlatform};

EGLPlatform::new(ffi::egl::PLATFORM_GBM_KHR, "PLATFORM_GBM_KHR", native_display as *mut _, vec![ffi::egl::NONE as ffi::EGLint], &["EGL_KHR_platform_gbm"]);
```

--------------------------------

### Initialize and Configure Tablet Tool

Source: https://docs.rs/smithay/latest/src/smithay/wayland/tablet_manager/tablet_tool.rs.html

Configures a new tablet tool instance with hardware details and capabilities before finalizing the setup.

```rust
seat.version(),
                TabletToolUserData {
                    handle: self.clone(),
                    desc,
                    client_scale,
                },
            )
            .unwrap();

        seat.tool_added(&wl_tool);

        wl_tool._type(tool.tool_type.into());

        let high: u32 = (tool.hardware_serial >> 16) as u32;
        let low: u32 = tool.hardware_serial as u32;

        wl_tool.hardware_serial(high, low);

        let high: u32 = (tool.hardware_id_wacom >> 16) as u32;
        let low: u32 = tool.hardware_id_wacom as u32;
        wl_tool.hardware_id_wacom(high, low);

        if tool.capabilities.contains(TabletToolCapabilities::PRESSURE) {
            wl_tool.capability(zwp_tablet_tool_v2::Capability::Pressure);
        }

        if tool.capabilities.contains(TabletToolCapabilities::DISTANCE) {
            wl_tool.capability(zwp_tablet_tool_v2::Capability::Distance);
        }

        if tool.capabilities.contains(TabletToolCapabilities::TILT) {
            wl_tool.capability(zwp_tablet_tool_v2::Capability::Tilt);
        }

        if tool.capabilities.contains(TabletToolCapabilities::SLIDER) {
            wl_tool.capability(zwp_tablet_tool_v2::Capability::Slider);
        }

        if tool.capabilities.contains(TabletToolCapabilities::ROTATION) {
            wl_tool.capability(zwp_tablet_tool_v2::Capability::Rotation);
        }

        if tool.capabilities.contains(TabletToolCapabilities::WHEEL) {
            wl_tool.capability(zwp_tablet_tool_v2::Capability::Wheel);
        }

        wl_tool.done();
        self.inner.lock().unwrap().instances.push(wl_tool.downgrade());
    }
```

--------------------------------

### init

Source: https://docs.rs/smithay/latest/smithay/backend/winit/index.html

Creates a new WinitGraphicsBackend and a corresponding WinitEventLoop.

```APIDOC
## fn init()

### Description
Create a new `WinitGraphicsBackend`, which implements the `Renderer` trait and a corresponding `WinitEventLoop`.
```

--------------------------------

### Option::is_some Examples

Source: https://docs.rs/smithay/latest/smithay/backend/renderer/gles/ffi/types/type.GLDEBUGPROCKHR.html

Examples demonstrating the use of the is_some method on an Option.

```rust
let x: Option<u32> = Some(2);
assert_eq!(x.is_some(), true);

let x: Option<u32> = None;
assert_eq!(x.is_some(), false);
```

--------------------------------

### Initialize and delegate tablet manager

Source: https://docs.rs/smithay/latest/smithay/wayland/tablet_manager/index.html

Demonstrates the setup of TabletManagerState, seat creation, and trait delegation required for tablet support.

```rust
use smithay::{delegate_seat, delegate_tablet_manager};
use smithay::backend::input::TabletToolDescriptor;
use smithay::input::{Seat, SeatState, SeatHandler, pointer::CursorImageStatus};
use smithay::wayland::tablet_manager::{TabletManagerState, TabletDescriptor, TabletSeatHandler};
use smithay::reexports::wayland_server::{Display, protocol::wl_surface::WlSurface};


let mut seat_state = SeatState::<State>::new();
let tablet_state = TabletManagerState::new::<State>(&display_handle);
// add the seat state to your state
// ...

// create the seat
let seat = seat_state.new_wl_seat(
    &display_handle,          // the display
    "seat-0",                 // the name of the seat, will be advertized to clients
);

use smithay::wayland::tablet_manager::TabletSeatTrait;

seat
   .tablet_seat()                     // Get TabletSeat asosiated with this seat
   .add_tablet::<State>(              // Add a new tablet to a seat
     &display_handle,
     &TabletDescriptor {    
       name: "Test".into(),
       usb_id: None,
       syspath: None,
     }
   );

// implement the required traits
impl SeatHandler for State {
    type KeyboardFocus = WlSurface;
    type PointerFocus = WlSurface;
    type TouchFocus = WlSurface;
    fn seat_state(&mut self) -> &mut SeatState<Self> {
        &mut self.seat_state
    }
    fn focus_changed(&mut self, seat: &Seat<Self>, focused: Option<&WlSurface>) {
        // ...
    }
    fn cursor_image(&mut self, seat: &Seat<Self>, image: CursorImageStatus) {
        // ...
    }
}
delegate_seat!(State);

impl TabletSeatHandler for State {
    fn tablet_tool_image(&mut self, tool: &TabletToolDescriptor, image: CursorImageStatus) {
        // ...
    }
}
delegate_tablet_manager!(State);
```

--------------------------------

### Advertise and Configure a WlOutput

Source: https://docs.rs/smithay/latest/src/smithay/wayland/output/mod.rs.html

Demonstrates creating an Output, advertising it as a global to clients, and configuring its state and modes.

```rust
# extern crate wayland_server;
# extern crate smithay;
use smithay::delegate_output;
# use smithay::delegate_compositor;
use smithay::output::{Output, PhysicalProperties, Scale, Mode, Subpixel};
use smithay::utils::Transform;
use smithay::wayland::output::OutputHandler;
# use smithay::wayland::compositor::{CompositorHandler, CompositorState, CompositorClientState};
# use smithay::reexports::wayland_server::{Client, protocol::wl_surface::WlSurface};

# struct State;
# let mut display = wayland_server::Display::<State>::new().unwrap();
# let display_handle = display.handle();
// Create the Output with given name and physical properties.
let output = Output::new(
    "output-0".into(), // the name of this output,
    PhysicalProperties {
        size: (200, 150).into(),        // dimensions (width, height) in mm
        subpixel: Subpixel::HorizontalRgb,  // subpixel information
        make: "Screens Inc".into(),     // make of the monitor
        model: "Monitor Ultra".into(),  // model of the monitor
    },
);
// create a global, if you want to advertise it to clients
let _global = output.create_global::<State>(
    &display_handle,      // the display
); // you can drop the global, if you never intend to destroy it.
// Now you can configure it
output.change_current_state(
    Some(Mode { size: (1920, 1080).into(), refresh: 60000 }), // the resolution mode,
    Some(Transform::Normal), // global screen transformation
    Some(Scale::Integer(1)), // global screen scaling factor
    Some((0,0).into()) // output position
);
// set the preferred mode
output.set_preferred(Mode { size: (1920, 1080).into(), refresh: 60000 });
// add other supported modes
output.add_mode(Mode { size: (800, 600).into(), refresh: 60000 });
output.add_mode(Mode { size: (1024, 768).into(), refresh: 60000 });

impl OutputHandler for State {}
# impl CompositorHandler for State {
#     fn compositor_state(&mut self) -> &mut CompositorState { unimplemented!() }
#     fn client_compositor_state<'a>(&self, client: &'a Client) -> &'a CompositorClientState { unimplemented!() }
#     fn commit(&mut self, surface: &WlSurface) {}
# }

delegate_output!(State);
# delegate_compositor!(State);
```

--------------------------------

### Result::is_ok_and Example

Source: https://docs.rs/smithay/latest/smithay/backend/drm/output/type.DrmOutputManagerResult.html

Example of checking if a Result is Ok and matches a predicate.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.is_ok_and(|x| x > 1), true);

let x: Result<u32, &str> = Ok(0);
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<u32, &str> = Err("hey");
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<String, &str> = Ok("ownership".to_string());
assert_eq!(x.as_ref().is_ok_and(|x| x.len() > 1), true);
println!("still alive {:?}", x);
```

--------------------------------

### Initialize PhysicalDevice from handle

Source: https://docs.rs/smithay/latest/src/smithay/backend/vulkan/phd.rs.html

Constructs a PhysicalDevice instance by querying extensions and device properties. Requires the physical device to belong to the provided instance.

```rust
impl super::PhysicalDevice {
    /// # Safety:
    ///
    /// The physical device must belong to the specified instance.
    pub(super) unsafe fn from_phd(
        instance: &super::Instance,
        phd: vk::PhysicalDevice,
    ) -> VkResult<Option<super::PhysicalDevice>> {
        let instance = instance.clone();

        let extensions = unsafe { instance.handle().enumerate_device_extension_properties(phd) }?;
        let extensions = extensions
            .iter()
            .map(|extension| {
                // SAFETY: Vulkan guarantees the device name is valid UTF-8 with a null terminator.
                unsafe { CStr::from_ptr(&extension.extension_name as *const _) }.to_owned()
            })
            .collect::<Vec<_>>();

        if let Some(info) =
            unsafe { PhdInfo::from_phd(instance.handle(), instance.api_version(), phd, &extensions) }
        {
            let span = info_span!(parent: &instance.0.span, "backend_vulkan_device", name = info.name);
            Ok(Some(Self {
                phd,
                info,
                extensions,
                instance,
                span,
            }))
        } else {
            Ok(None)
        }
    }
}
```

--------------------------------

### Result::cloned Example

Source: https://docs.rs/smithay/latest/smithay/backend/drm/output/type.DrmOutputManagerResult.html

Examples of using the cloned method on Result references.

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

--------------------------------

### Initialize Pointer Gestures State

Source: https://docs.rs/smithay/latest/src/smithay/wayland/pointer_gestures.rs.html

Example of initializing the pointer gestures state and delegating it to the compositor state.

```rust
let state = PointerGesturesState::new::<State>(&display.handle());

delegate_pointer_gestures!(State);
```

--------------------------------

### Configure X11 Window Properties and Events

Source: https://docs.rs/smithay/latest/src/smithay/backend/x11/window_inner.rs.html

Sets up input event masks, present extension events, and window properties like WM_DELETE_WINDOW and WM_CLASS during window initialization.

```rust
xinput::XIEventMask::BUTTON_PRESS
                        | xinput::XIEventMask::BUTTON_RELEASE
                        | xinput::XIEventMask::MOTION
                        | xinput::XIEventMask::ENTER
                        | xinput::XIEventMask::LEAVE
                        | xinput::XIEventMask::FOCUS_IN
                        | xinput::XIEventMask::FOCUS_OUT,
                ],
            }],
        )?;

        // We only ever need one event id since we will only ever have one event context.
        let present_event_id = connection.generate_id()?;
        connection.present_select_input(
            present_event_id,
            window,
            present::EventMask::COMPLETE_NOTIFY | present::EventMask::IDLE_NOTIFY,
        )?;

        // Send requests to change window properties while we wait for the window creation request to complete.
        let window = WindowInner {
            connection: weak,
            id: window,
            root: screen.root,
            atoms,
            cursor_state: Arc::new(Mutex::new(CursorState::default())),
            size: Mutex::new(size),
            next_serial: AtomicU32::new(0),
            last_msc: Arc::new(AtomicU64::new(0)),
            format,
            depth,
            extensions,
            resize: Mutex::new(None),
        };

        // Enable WM_DELETE_WINDOW so our client is not disconnected upon our toplevel window being destroyed.
        connection.change_property32(
            PropMode::REPLACE,
            window.id,
            atoms.WM_PROTOCOLS,
            AtomEnum::ATOM,
            &[atoms.WM_DELETE_WINDOW],
        )?;

        // WM class cannot be safely changed later.
        let _ = connection.change_property8(
            PropMode::REPLACE,
            window.id,
            AtomEnum::WM_CLASS,
            AtomEnum::STRING,
            b"Smithay\0Wayland_Compositor\0",
        )?;

        window.set_title(title);
        window.map();

        // Flush requests to server so window is displayed.
        connection.flush()?;
```

--------------------------------

### Result::copied Example

Source: https://docs.rs/smithay/latest/smithay/backend/drm/output/type.DrmOutputManagerResult.html

Examples of using the copied method on Result references.

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

--------------------------------

### Trim end matches examples

Source: https://docs.rs/smithay/latest/smithay/wayland/xdg_activation/struct.XdgActivationToken.html

Examples of repeatedly removing suffixes that match a pattern.

```rust
assert_eq!("11foo1bar11".trim_end_matches('1'), "11foo1bar");
assert_eq!("123foo1bar123".trim_end_matches(char::is_numeric), "123foo1bar");
```

--------------------------------

### GbmGlesBackend::with_context_priority

Source: https://docs.rs/smithay/latest/smithay/backend/renderer/multigpu/gbm/struct.GbmGlesBackend.html

Initializes a new GbmGlesBackend with a specific ContextPriority.

```APIDOC
## pub fn with_context_priority(priority: ContextPriority) -> Self

### Description
Initializes a new GbmGlesBackend with a ContextPriority for instantiating GlesRenderers. Note that this is mutually exclusive with with_factory.
```

--------------------------------

### Strip suffix examples

Source: https://docs.rs/smithay/latest/smithay/wayland/xdg_activation/struct.XdgActivationToken.html

Examples of removing a suffix exactly once if it exists, returning an Option.

```rust
assert_eq!("bar:foo".strip_suffix(":foo"), Some("bar"));
assert_eq!("bar:foo".strip_suffix("bar"), None);
assert_eq!("foofoo".strip_suffix("foo"), Some("foo"));
```

--------------------------------

### Instance::new

Source: https://docs.rs/smithay/latest/src/smithay/backend/vulkan/mod.rs.html

Creates a new Vulkan Instance with the specified maximum version and optional application information.

```APIDOC
## Instance::new

### Description
Creates a new Vulkan Instance. This object tracks the application's Vulkan state and allows for physical device discovery.

### Parameters
- **max_version** (Version) - Required - The maximum Vulkan version to request.
- **app_info** (Option<AppInfo>) - Optional - Application metadata including name and version.
```

--------------------------------

### Initialize KDE Decoration Manager

Source: https://docs.rs/smithay/latest/src/smithay/wayland/shell/kde/decoration.rs.html

Registers the OrgKdeKwinServerDecorationManager global with the Wayland display.

```rust
display.create_global::<D, OrgKdeKwinServerDecorationManager, _>(1, data);

        Self {
            kde_decoration_manager,
            default_mode,
        }
    }

    /// Returns the id of the [`OrgKdeKwinServerDecorationManager`] global.
    pub fn global(&self) -> GlobalId {
        self.kde_decoration_manager.clone()
    }
}
```

--------------------------------

### Trim Right (Deprecated) Examples

Source: https://docs.rs/smithay/latest/smithay/wayland/xdg_activation/struct.XdgActivationToken.html

Legacy examples for trimming trailing whitespace, superseded by trim_end.

```rust
let s = " Hello\tworld\t";

assert_eq!(" Hello\tworld", s.trim_right());
```

```rust
let s = "English  ";
assert!(Some('h') == s.trim_right().chars().rev().next());

let s = "עברית  ";
assert!(Some('ת') == s.trim_right().chars().rev().next());
```

--------------------------------

### LibSeatSession::new

Source: https://docs.rs/smithay/latest/smithay/backend/session/libseat/struct.LibSeatSession.html

Creates a new session instance using libseat.

```APIDOC
## pub fn new() -> Result<(LibSeatSession, LibSeatSessionNotifier), Error>

### Description
Tries to create a new session via libseat.

### Returns
- **Result<(LibSeatSession, LibSeatSessionNotifier), Error>** - A tuple containing the session and its notifier, or an error if initialization fails.
```

--------------------------------

### Trim Left (Deprecated) Examples

Source: https://docs.rs/smithay/latest/smithay/wayland/xdg_activation/struct.XdgActivationToken.html

Legacy examples for trimming leading whitespace, superseded by trim_start.

```rust
let s = " Hello\tworld\t";

assert_eq!("Hello\tworld\t", s.trim_left());
```

```rust
let s = "  English";
assert!(Some('E') == s.trim_left().chars().next());

let s = "  עברית";
assert!(Some('ע') == s.trim_left().chars().next());
```
Tokens:
Raw