Skip to main content

Grim

grim_rs

Struct Grim 

Source 
pub struct Grim { /* private fields */ }
Expand description

Main interface for taking screenshots.

Provides methods for capturing screenshots of the entire screen, specific outputs, regions, or multiple outputs with different parameters.

Implementations§

Source§

impl Grim

Source

pub fn new() -> Result<Self>

Create a new Grim instance with auto-detected backend.

Establishes a connection to the Wayland compositor and initializes the necessary protocols for screen capture. Prefers ext-image-copy-capture-v1 when available, falling back to wlr-screencopy.

Use Grim::new_ext or Grim::new_wlr to force a specific backend.

§Errors

Returns an error if:

  • Cannot connect to the Wayland compositor
  • No capture protocol is available
  • Other initialization errors occur
§Example
use grim_rs::Grim;

let grim = Grim::new()?;
Source

pub fn new_ext() -> Result<Self>

Create a new Grim instance forcing ext-image-copy-capture-v1 backend.

Linux/Wayland only. On Windows this method returns Error::UnsupportedProtocol.

Fails if the compositor does not support this protocol (e.g. KDE, GNOME, or older Sway releases). Use Grim::new for auto-detection if you need to support multiple compositors.

§Errors

Returns Error::UnsupportedProtocol if ext-image-copy-capture-v1 is not available on the compositor, or if called on a non-Linux platform.

§Example
use grim_rs::Grim;

// Only works on compositors with ext-image-copy-capture-v1
// (Sway >= 2025, Hyprland, COSMIC)
let grim = Grim::new_ext()?;
Source

pub fn new_wlr() -> Result<Self>

Create a new Grim instance forcing wlr-screencopy backend.

Linux/Wayland only. On Windows this method returns Error::UnsupportedProtocol.

Fails if the compositor does not support this protocol. Use Grim::new for auto-detection if you need to support multiple compositors.

§Errors

Returns Error::UnsupportedProtocol if zwlr-screencopy-manager-v1 is not available on the compositor, or if called on a non-Linux platform.

§Example
use grim_rs::Grim;

// Only works on compositors with wlr-screencopy
// (older Sway, River, Wayfire, Niri)
let grim = Grim::new_wlr()?;
Source

pub fn get_outputs(&mut self) -> Result<Vec<Output>>

Get information about available display outputs.

Returns a list of all connected display outputs with their names, geometries, and scale factors.

§Errors

Returns an error if:

  • No outputs are available
  • Failed to retrieve output information
§Example
use grim_rs::Grim;

let mut grim = Grim::new()?;
let outputs = grim.get_outputs()?;

for output in outputs {
    println!("Output: {} ({}x{})", output.name(), output.geometry().width(), output.geometry().height());
}
Source

pub fn capture_all(&mut self) -> Result<CaptureResult>

Capture the entire screen (all outputs).

Captures a screenshot that includes all connected display outputs, arranged according to their physical positions.

§Errors

Returns an error if:

  • No outputs are available
  • Failed to capture the screen
  • Buffer creation failed
§Example
use grim_rs::Grim;

let mut grim = Grim::new()?;
let result = grim.capture_all()?;
println!("Captured screen: {}x{}", result.width(), result.height());
Source

pub fn capture_all_with_scale(&mut self, scale: f64) -> Result<CaptureResult>

Capture the entire screen (all outputs) with specified scale factor.

Captures a screenshot that includes all connected display outputs, arranged according to their physical positions, with a specified scale factor.

§Arguments
  • scale - Scale factor for the output image
§Errors

Returns an error if:

  • No outputs are available
  • Failed to capture the screen
  • Buffer creation failed
§Example
use grim_rs::Grim;

let mut grim = Grim::new()?;
let result = grim.capture_all_with_scale(1.0)?;
println!("Captured screen: {}x{}", result.width(), result.height());
Source

pub fn capture_output(&mut self, output_name: &str) -> Result<CaptureResult>

Capture a specific output by name.

Captures a screenshot of the specified display output.

§Arguments
  • output_name - Name of the output to capture (e.g., “eDP-1”, “HDMI-A-1”)
§Errors

Returns an error if:

  • The specified output is not found
  • Failed to capture the output
  • Buffer creation failed
§Example
use grim_rs::Grim;

let mut grim = Grim::new()?;
// Get available outputs first
let outputs = grim.get_outputs()?;
if let Some(output) = outputs.first() {
    let result = grim.capture_output(output.name())?;
    println!("Captured output: {}x{}", result.width(), result.height());
}
Source

pub fn capture_output_with_scale( &mut self, output_name: &str, scale: f64, ) -> Result<CaptureResult>

Capture a specific output by name with specified scale factor.

Captures a screenshot of the specified display output with a specified scale factor.

§Arguments
  • output_name - Name of the output to capture (e.g., “eDP-1”, “HDMI-A-1”)
  • scale - Scale factor for the output image
§Errors

Returns an error if:

  • The specified output is not found
  • Failed to capture the output
  • Buffer creation failed
§Example
use grim_rs::Grim;

let mut grim = Grim::new()?;
// Get available outputs first
let outputs = grim.get_outputs()?;
if let Some(output) = outputs.first() {
    let result = grim.capture_output_with_scale(output.name(), 0.5)?;
    println!("Captured output at 50% scale: {}x{}", result.width(), result.height());
}
Source

pub fn capture_region(&mut self, region: Region) -> Result<CaptureResult>

Capture a specific region.

Captures a screenshot of the specified rectangular region.

§Arguments
  • region - The region to capture, specified as a Region
§Errors

Returns an error if:

  • No outputs are available
  • Failed to capture the region
  • Buffer creation failed
§Example
use grim_rs::{Grim, Region};

let mut grim = Grim::new()?;
// x=100, y=100, width=800, height=600
let region = Region::new(100, 100, 800, 600);
let result = grim.capture_region(region)?;
println!("Captured region: {}x{}", result.width(), result.height());
Source

pub fn capture_region_with_scale( &mut self, region: Region, scale: f64, ) -> Result<CaptureResult>

Capture a specific region with specified scale factor.

Captures a screenshot of the specified rectangular region with a specified scale factor.

§Arguments
  • region - The region to capture, specified as a Region
  • scale - Scale factor for the output image
§Errors

Returns an error if:

  • No outputs are available
  • Failed to capture the region
  • Buffer creation failed
§Example
use grim_rs::{Grim, Region};

let mut grim = Grim::new()?;
// x=100, y=100, width=800, height=600
let region = Region::new(100, 100, 800, 600);
let result = grim.capture_region_with_scale(region, 1.0)?;
println!("Captured region: {}x{}", result.width(), result.height());
Source

pub fn capture_outputs( &mut self, parameters: Vec<CaptureParameters>, ) -> Result<MultiOutputCaptureResult>

Capture multiple outputs with different parameters.

Captures screenshots of multiple outputs simultaneously, each with potentially different parameters (region, cursor inclusion, etc.).

§Arguments
  • parameters - Vector of CaptureParameters specifying what to capture from each output
§Errors

Returns an error if:

  • Any specified output is not found
  • Any specified region is outside the bounds of its output
  • Failed to capture any of the outputs
  • Buffer creation failed
§Example
use grim_rs::{Grim, CaptureParameters, Region};

let mut grim = Grim::new()?;

// Get available outputs
let outputs = grim.get_outputs()?;

// Prepare capture parameters for multiple outputs
let mut parameters = vec![
    CaptureParameters::new(outputs[0].name())
        .overlay_cursor(true)
];

// If we have a second output, capture a region of it
if outputs.len() > 1 {
    let region = Region::new(0, 0, 400, 300);
    parameters.push(
        CaptureParameters::new(outputs[1].name())
            .region(region)
    );
}

// Capture all specified outputs
let results = grim.capture_outputs(parameters)?;
println!("Captured {} outputs", results.outputs().len());
Source

pub fn capture_outputs_with_scale( &mut self, parameters: Vec<CaptureParameters>, default_scale: f64, ) -> Result<MultiOutputCaptureResult>

Capture outputs with scale factor.

Captures screenshots of multiple outputs simultaneously with a specific scale factor.

§Arguments
  • parameters - Vector of CaptureParameters with scale factors
  • default_scale - Default scale factor to use when not specified in parameters
§Errors

Returns an error if any of the outputs can’t be captured

Source

pub fn save_png<P: AsRef<Path>>( &self, data: &[u8], width: u32, height: u32, path: P, ) -> Result<()>

Save captured data as PNG.

Saves the captured image data to a PNG file.

§Arguments
  • data - Raw RGBA image data from a capture result
  • width - Width of the image in pixels
  • height - Height of the image in pixels
  • path - Path where to save the PNG file
§Errors

Returns an error if:

  • Failed to create or write to the file
  • Image processing failed
§Example
use grim_rs::Grim;
use chrono::Local;

let mut grim = Grim::new()?;
let result = grim.capture_all()?;

// Generate timestamped filename
let filename = format!("{}_grim.png", Local::now().format("%Y%m%d_%Hh%Mm%Ss"));
grim.save_png(result.data(), result.width(), result.height(), &filename)?;
Source

pub fn save_png_with_compression<P: AsRef<Path>>( &self, data: &[u8], width: u32, height: u32, path: P, compression: u8, ) -> Result<()>

Save captured data as PNG with compression level control.

Saves the captured image data to a PNG file with specified compression level.

§Arguments
  • data - Raw RGBA image data from a capture result
  • width - Width of the image in pixels
  • height - Height of the image in pixels
  • path - Path where to save the PNG file
  • compression - PNG compression level (0-9, where 9 is highest compression)
§Errors

Returns an error if:

  • Failed to create or write to the file
  • Image processing failed
§Example
use grim_rs::Grim;
use chrono::Local;

let mut grim = Grim::new()?;
let result = grim.capture_all()?;

// Generate timestamped filename
let filename = format!("{}_grim.png", Local::now().format("%Y%m%d_%Hh%Mm%Ss"));
grim.save_png_with_compression(result.data(), result.width(), result.height(), &filename, 9)?;
Source

pub fn save_jpeg<P: AsRef<Path>>( &self, data: &[u8], width: u32, height: u32, path: P, ) -> Result<()>

Save captured data as JPEG.

Saves the captured image data to a JPEG file.

This function is only available when the jpeg feature is enabled.

§Arguments
  • data - Raw RGBA image data from a capture result
  • width - Width of the image in pixels
  • height - Height of the image in pixels
  • path - Path where to save the JPEG file
§Errors

Returns an error if:

  • Failed to create or write to the file
  • Image processing failed
  • JPEG support is not enabled (when feature is disabled)
§Example
use grim_rs::Grim;
use chrono::Local;

let mut grim = Grim::new()?;
let result = grim.capture_all()?;

// Generate timestamped filename
let filename = format!("{}_grim.jpg", Local::now().format("%Y%m%d_%Hh%Mm%Ss"));
grim.save_jpeg(result.data(), result.width(), result.height(), &filename)?;
Source

pub fn save_jpeg_with_quality<P: AsRef<Path>>( &self, data: &[u8], width: u32, height: u32, path: P, quality: u8, ) -> Result<()>

Save captured data as JPEG with quality control.

Saves the captured image data to a JPEG file with specified quality.

This function is only available when the jpeg feature is enabled.

§Arguments
  • data - Raw RGBA image data from a capture result
  • width - Width of the image in pixels
  • height - Height of the image in pixels
  • path - Path where to save the JPEG file
  • quality - JPEG quality level (0-100, where 100 is highest quality)
§Errors

Returns an error if:

  • Failed to create or write to the file
  • Image processing failed
  • JPEG support is not enabled (when feature is disabled)
§Example
use grim_rs::Grim;
use chrono::Local;

let mut grim = Grim::new()?;
let result = grim.capture_all()?;

// Generate timestamped filename
let filename = format!("{}_grim.jpg", Local::now().format("%Y%m%d_%Hh%Mm%Ss"));
grim.save_jpeg_with_quality(result.data(), result.width(), result.height(), &filename, 90)?;
Source

pub fn to_jpeg(&self, data: &[u8], width: u32, height: u32) -> Result<Vec<u8>>

Get image data as JPEG bytes.

Converts the captured image data to JPEG format and returns the bytes.

This function is only available when the jpeg feature is enabled.

§Arguments
  • data - Raw RGBA image data from a capture result
  • width - Width of the image in pixels
  • height - Height of the image in pixels
§Returns

Returns the JPEG-encoded image data as a vector of bytes.

§Errors

Returns an error if:

  • Image processing failed
  • JPEG support is not enabled (when feature is disabled)
§Example
use grim_rs::Grim;

let mut grim = Grim::new()?;
let result = grim.capture_all()?;
let jpeg_bytes = grim.to_jpeg(result.data(), result.width(), result.height())?;
println!("JPEG data size: {} bytes", jpeg_bytes.len());
Source

pub fn to_jpeg_with_quality( &self, data: &[u8], width: u32, height: u32, quality: u8, ) -> Result<Vec<u8>>

Get image data as JPEG bytes with quality control.

Converts the captured image data to JPEG format with specified quality and returns the bytes.

This function is only available when the jpeg feature is enabled.

§Arguments
  • data - Raw RGBA image data from a capture result
  • width - Width of the image in pixels
  • height - Height of the image in pixels
  • quality - JPEG quality level (0-100, where 100 is highest quality)
§Returns

Returns the JPEG-encoded image data as a vector of bytes.

§Errors

Returns an error if:

  • Image processing failed
  • JPEG support is not enabled (when feature is disabled)
§Example
use grim_rs::Grim;

let mut grim = Grim::new()?;
let result = grim.capture_all()?;
let jpeg_bytes = grim.to_jpeg_with_quality(result.data(), result.width(), result.height(), 90)?;
println!("JPEG data size: {} bytes", jpeg_bytes.len());
Source

pub fn to_png(&self, data: &[u8], width: u32, height: u32) -> Result<Vec<u8>>

Get image data as PNG bytes.

Converts the captured image data to PNG format and returns the bytes.

§Arguments
  • data - Raw RGBA image data from a capture result
  • width - Width of the image in pixels
  • height - Height of the image in pixels
§Returns

Returns the PNG-encoded image data as a vector of bytes.

§Errors

Returns an error if:

  • Image processing failed
§Example
use grim_rs::Grim;

let mut grim = Grim::new()?;
let result = grim.capture_all()?;
let png_bytes = grim.to_png(result.data(), result.width(), result.height())?;
println!("PNG data size: {} bytes", png_bytes.len());
Source

pub fn to_png_with_compression( &self, data: &[u8], width: u32, height: u32, compression: u8, ) -> Result<Vec<u8>>

Get image data as PNG bytes with compression level control.

Converts the captured image data to PNG format with specified compression level and returns the bytes.

§Arguments
  • data - Raw RGBA image data from a capture result
  • width - Width of the image in pixels
  • height - Height of the image in pixels
  • compression - PNG compression level (0-9, where 9 is highest compression)
§Returns

Returns the PNG-encoded image data as a vector of bytes.

§Errors

Returns an error if:

  • Image processing failed
§Example
use grim_rs::Grim;

let mut grim = Grim::new()?;
let result = grim.capture_all()?;
let png_bytes = grim.to_png_with_compression(result.data(), result.width(), result.height(), 9)?;
println!("PNG data size: {} bytes", png_bytes.len());
Source

pub fn read_region_from_stdin() -> Result<Region>

Read region from stdin.

Reads a region specification from standard input in the format “x,y widthxheight”.

§Returns

Returns a Region representing the region read from stdin.

§Errors

Returns an error if:

  • Failed to read from stdin
  • The input format is invalid
§Example
use grim_rs::{Grim, Region};

// Parse region from string (same format as stdin would provide)
let region = "100,100 800x600".parse::<Region>()?;
println!("Region: {}", region);
Source

pub fn write_png_to_stdout( &self, data: &[u8], width: u32, height: u32, ) -> Result<()>

Write image data to stdout as PNG.

Writes captured image data directly to standard output in PNG format.

§Arguments
  • data - Raw RGBA image data from a capture result
  • width - Width of the image in pixels
  • height - Height of the image in pixels
§Errors

Returns an error if:

  • Failed to write to stdout
  • Image processing failed
§Example
use grim_rs::Grim;

let mut grim = Grim::new()?;
let result = grim.capture_all()?;
grim.write_png_to_stdout(result.data(), result.width(), result.height())?;
Source

pub fn write_png_to_stdout_with_compression( &self, data: &[u8], width: u32, height: u32, compression: u8, ) -> Result<()>

Write image data to stdout as PNG with compression level.

Writes captured image data directly to standard output in PNG format with specified compression.

§Arguments
  • data - Raw RGBA image data from a capture result
  • width - Width of the image in pixels
  • height - Height of the image in pixels
  • compression - PNG compression level (0-9, where 9 is highest compression)
§Errors

Returns an error if:

  • Failed to write to stdout
  • Image processing failed
§Example
use grim_rs::Grim;

let mut grim = Grim::new()?;
let result = grim.capture_all()?;
grim.write_png_to_stdout_with_compression(result.data(), result.width(), result.height(), 6)?;
Source

pub fn write_jpeg_to_stdout( &self, data: &[u8], width: u32, height: u32, ) -> Result<()>

Write image data to stdout as JPEG.

Writes captured image data directly to standard output in JPEG format.

§Arguments
  • data - Raw RGBA image data from a capture result
  • width - Width of the image in pixels
  • height - Height of the image in pixels
§Errors

Returns an error if:

  • Failed to write to stdout
  • Image processing failed
  • JPEG support is not enabled
§Example
use grim_rs::Grim;

let mut grim = Grim::new()?;
let result = grim.capture_all()?;
grim.write_jpeg_to_stdout(result.data(), result.width(), result.height())?;
Source

pub fn write_jpeg_to_stdout_with_quality( &self, data: &[u8], width: u32, height: u32, quality: u8, ) -> Result<()>

Write image data to stdout as JPEG with quality control.

Writes captured image data directly to standard output in JPEG format with specified quality.

§Arguments
  • data - Raw RGBA image data from a capture result
  • width - Width of the image in pixels
  • height - Height of the image in pixels
  • quality - JPEG quality level (0-100, where 100 is highest quality)
§Errors

Returns an error if:

  • Failed to write to stdout
  • Image processing failed
  • JPEG support is not enabledvidence: lib.rs Symbol: to_png_with_compression
§Example
use grim_rs::Grim;

let mut grim = Grim::new()?;
let result = grim.capture_all()?;
grim.write_jpeg_to_stdout_with_quality(result.data(), result.width(), result.height(), 90)?;

Auto Trait Implementations§

§

impl !RefUnwindSafe for Grim

§

impl !UnwindSafe for Grim

§

impl Freeze for Grim

§

impl Send for Grim

§

impl Sync for Grim

§

impl Unpin for Grim

§

impl UnsafeUnpin for Grim

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> Downcast for T
where T: Any,

Source§

fn into_any(self: Box<T>) -> Box<dyn Any>

Convert Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>. Box<dyn Any> can then be further downcast into Box<ConcreteType> where ConcreteType implements Trait.
Source§

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

Convert Rc<Trait> (where Trait: Downcast) to Rc<Any>. Rc<Any> can then be further downcast into Rc<ConcreteType> where ConcreteType implements Trait.
Source§

fn as_any(&self) -> &(dyn Any + 'static)

Convert &Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &Any’s vtable from &Trait’s.
Source§

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

Convert &mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &mut Any’s vtable from &mut Trait’s.
Source§

impl<T> DowncastSync for T
where T: Any + Send + Sync,

Source§

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>

Convert Arc<Trait> (where Trait: Downcast) to Arc<Any>. Arc<Any> can then be further downcast into Arc<ConcreteType> where ConcreteType implements Trait.
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

impl<T> Pointable for T

Source§

const ALIGN: usize

The alignment of pointer.
Source§

type Init = T

The type for initializers.
Source§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
Source§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
Source§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
Source§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.