Module smithay::wayland::shm[−][src]

Expand description

SHM handling helpers

This module provides helpers to handle SHM-based buffers from wayland clients.

SHM (Shared Memory) is the most basic way wayland clients can send content to the compositor: by sending a file descriptor to some (likely RAM-backed) storage containing the actual data. This helper handles for you most of the logic for handling these file descriptor and accessing their contents as simple &[u8] slices.

This module is heavily inspired from the similar helpers of the wayland C libraries.

To use it, first add a ShmGlobal to your display, specifying the formats you want to support (ARGB8888 and XRGB8888 are always considered as supported, as specified by the wayland protocol).

extern crate wayland_server;
extern crate smithay;

use smithay::wayland::shm::init_shm_global;
use wayland_server::protocol::wl_shm::Format;

// Insert the ShmGlobal into your event loop
// Here, we specify that Yuyv and C8 format are supported
// additionally to the standard Argb8888 and Xrgb8888.
init_shm_global(
    &mut display,
    vec![Format::Yuyv, Format::C8],
    None // we don't provide a logger here
);

Then, when you have a WlBuffer and need to retrieve its contents, use the with_buffer_contents function to do it:

use smithay::wayland::shm::{with_buffer_contents, BufferData, BufferAccessError};

let content = with_buffer_contents(&buffer,
    |slice: &[u8], buffer_metadata: BufferData| {
        // do something to extract the contents of the buffer
    }
);

match content {
    Ok(something) =>  {
        /* `something` is the value you returned from the closure */
    },
    Err(BufferAccessError::NotManaged) => {
        /* This buffer is not managed by the SHM global, but by something else */
    },
    Err(BufferAccessError::BadMap) => {
        /* The client supplied invalid content specification for this buffer,
           and was killed.
         */
    }
}

Note

This handler makes itself safe regarding the client providing a wrong size for the memory pool by using a SIGBUS handler.

If you are already using an handler for this signal, you probably don’t want to use this handler.

with_buffer_contents

Call given closure with the contents of the given buffer

Module smithay::wayland::shm[−][src]

Structs

Enums

Functions