windows_capture/
lib.rs

1//! # Windows Capture Rust Library
2//!
3//! **Windows Capture** is a highly efficient Rust and Python library that
4//! enables you to effortlessly capture the screen using the Graphics Capture
5//! API. This library allows you to easily capture the screen of your
6//! Windows-based computer and use it for various purposes, such as creating
7//! instructional videos, taking screenshots, or recording your gameplay. With
8//! its intuitive interface and robust functionality, Windows-Capture is an
9//! excellent choice for anyone looking for a reliable and easy-to-use screen
10//! capturing solution.
11//!
12//! ## Features
13//!
14//! - Only updates the frame when required.
15//! - High performance.
16//! - Easy to use.
17//! - Latest screen capturing API.
18//!
19//! ## Installation
20//!
21//! Add this library to your `Cargo.toml`:
22//!
23//! ```toml
24//! [dependencies]
25//! windows-capture = "1.5.0"
26//! ```
27//! or run this command
28//!
29//! ```text
30//! cargo add windows-capture
31//! ```
32//!
33//! ## Usage
34//!
35//! ```no_run
36//! use std::io::{self, Write};
37//! use std::time::Instant;
38//!
39//! use windows_capture::capture::{Context, GraphicsCaptureApiHandler};
40//! use windows_capture::encoder::{
41//!     AudioSettingsBuilder, ContainerSettingsBuilder, VideoEncoder, VideoSettingsBuilder,
42//! };
43//! use windows_capture::frame::Frame;
44//! use windows_capture::graphics_capture_api::InternalCaptureControl;
45//! use windows_capture::monitor::Monitor;
46//! use windows_capture::settings::{
47//!     ColorFormat, CursorCaptureSettings, DirtyRegionSettings, DrawBorderSettings,
48//!     MinimumUpdateIntervalSettings, SecondaryWindowSettings, Settings,
49//! };
50//!
51//! // Handles capture events.
52//! struct Capture {
53//!     // The video encoder that will be used to encode the frames.
54//!     encoder: Option<VideoEncoder>,
55//!     // To measure the time the capture has been running
56//!     start: Instant,
57//! }
58//!
59//! impl GraphicsCaptureApiHandler for Capture {
60//!     // The type of flags used to get the values from the settings.
61//!     type Flags = String;
62//!
63//!     // The type of error that can be returned from `CaptureControl` and `start`
64//!     // functions.
65//!     type Error = Box<dyn std::error::Error + Send + Sync>;
66//!
67//!     // Function that will be called to create a new instance. The flags can be
68//!     // passed from settings.
69//!     fn new(ctx: Context<Self::Flags>) -> Result<Self, Self::Error> {
70//!         println!("Created with Flags: {}", ctx.flags);
71//!
72//!         let encoder = VideoEncoder::new(
73//!             VideoSettingsBuilder::new(1920, 1080),
74//!             AudioSettingsBuilder::default().disabled(true),
75//!             ContainerSettingsBuilder::default(),
76//!             "video.mp4",
77//!         )?;
78//!
79//!         Ok(Self { encoder: Some(encoder), start: Instant::now() })
80//!     }
81//!
82//!     // Called every time a new frame is available.
83//!     fn on_frame_arrived(
84//!         &mut self,
85//!         frame: &mut Frame,
86//!         capture_control: InternalCaptureControl,
87//!     ) -> Result<(), Self::Error> {
88//!         print!("\rRecording for: {} seconds", self.start.elapsed().as_secs());
89//!         io::stdout().flush()?;
90//!
91//!         // Send the frame to the video encoder
92//!         self.encoder.as_mut().unwrap().send_frame(frame)?;
93//!
94//!         // Note: The frame has other uses too, for example, you can save a single frame
95//!         // to a file, like this: frame.save_as_image("frame.png", ImageFormat::Png)?;
96//!         // Or get the raw data like this so you have full
97//!         // control: let data = frame.buffer()?;
98//!
99//!         // Stop the capture after 6 seconds
100//!         if self.start.elapsed().as_secs() >= 6 {
101//!             // Finish the encoder and save the video.
102//!             self.encoder.take().unwrap().finish()?;
103//!
104//!             capture_control.stop();
105//!
106//!             // Because the previous prints did not include a newline.
107//!             println!();
108//!         }
109//!
110//!         Ok(())
111//!     }
112//!
113//!     // Optional handler called when the capture item (usually a window) is closed.
114//!     fn on_closed(&mut self) -> Result<(), Self::Error> {
115//!         println!("Capture session ended");
116//!
117//!         Ok(())
118//!     }
119//! }
120//!
121//! // Gets the primary monitor, refer to the docs for other capture items.
122//! let primary_monitor = Monitor::primary().expect("There is no primary monitor");
123//!
124//! let settings = Settings::new(
125//!     // Item to capture
126//!     primary_monitor,
127//!     // Capture cursor settings
128//!     CursorCaptureSettings::Default,
129//!     // Draw border settings
130//!     DrawBorderSettings::Default,
131//!     // Secondary window settings, if you want to include secondary windows in the capture
132//!     SecondaryWindowSettings::Default,
133//!     // Minimum update interval, if you want to change the frame rate limit (default is 60 FPS or 16.67 ms)
134//!     MinimumUpdateIntervalSettings::Default,
135//!     // Dirty region settings,
136//!     DirtyRegionSettings::Default,
137//!     // The desired color format for the captured frame.
138//!     ColorFormat::Rgba8,
139//!     // Additional flags for the capture settings that will be passed to the user-defined `new` function.
140//!     "Yea this works".to_string(),
141//! );
142//!
143//! // Starts the capture and takes control of the current thread.
144//! // The errors from the handler trait will end up here.
145//! Capture::start(settings).expect("Screen capture failed");
146//! ```
147#![warn(clippy::nursery)]
148#![warn(clippy::cargo)]
149#![warn(clippy::multiple_crate_versions)] // Should update as soon as possible
150
151/// Exported for the trait bounds
152pub use windows::Graphics::Capture::GraphicsCaptureItem as WindowsCaptureGraphicsCaptureItem;
153
154/// Contains the main capture functionality, including the `WindowsCaptureHandler` trait and related types.
155pub mod capture;
156/// Internal module for Direct3D 11 related functionality.
157mod d3d11;
158/// Contains the encoder functionality for encoding captured frames.
159pub mod encoder;
160/// Contains the `Frame` struct and related types for representing captured frames.
161pub mod frame;
162/// Contains the types and functions related to the Graphics Capture API.
163pub mod graphics_capture_api;
164/// Contains the functionality for working with monitors and screen information.
165pub mod monitor;
166/// Contains the `Settings` struct and related types for configuring the capture settings.
167pub mod settings;
168/// Contains the functionality for working with windows and capturing specific windows.
169pub mod window;
windows_capture/lib.rs

windows_capture/
lib.rs
