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.4.4"
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::{
37//! io::{self, Write},
38//! time::Instant,
39//! };
40//!
41//! use windows_capture::{
42//! capture::{Context, GraphicsCaptureApiHandler},
43//! encoder::{AudioSettingsBuilder, ContainerSettingsBuilder, VideoEncoder, VideoSettingsBuilder},
44//! frame::Frame,
45//! graphics_capture_api::InternalCaptureControl,
46//! monitor::Monitor,
47//! settings::{ColorFormat, CursorCaptureSettings, DrawBorderSettings, Settings},
48//! };
49//!
50//! // Handles capture events.
51//! struct Capture {
52//! // The video encoder that will be used to encode the frames.
53//! encoder: Option<VideoEncoder>,
54//! // To measure the time the capture has been running
55//! start: Instant,
56//! }
57//!
58//! impl GraphicsCaptureApiHandler for Capture {
59//! // The type of flags used to get the values from the settings.
60//! type Flags = String;
61//!
62//! // The type of error that can be returned from `CaptureControl` and `start` functions.
63//! type Error = Box<dyn std::error::Error + Send + Sync>;
64//!
65//! // Function that will be called to create a new instance. The flags can be passed from settings.
66//! fn new(ctx: Context<Self::Flags>) -> Result<Self, Self::Error> {
67//! println!("Created with Flags: {}", ctx.flags);
68//!
69//! let encoder = VideoEncoder::new(
70//! VideoSettingsBuilder::new(1920, 1080),
71//! AudioSettingsBuilder::default().disabled(true),
72//! ContainerSettingsBuilder::default(),
73//! "video.mp4",
74//! )?;
75//!
76//! Ok(Self {
77//! encoder: Some(encoder),
78//! start: Instant::now(),
79//! })
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!(
89//! "\rRecording for: {} seconds",
90//! self.start.elapsed().as_secs()
91//! );
92//! io::stdout().flush()?;
93//!
94//! // Send the frame to the video encoder
95//! self.encoder.as_mut().unwrap().send_frame(frame)?;
96//!
97//! // Note: The frame has other uses too, for example, you can save a single frame to a file, like this:
98//! // frame.save_as_image("frame.png", ImageFormat::Png)?;
99//! // Or get the raw data like this so you have full control:
100//! // let data = frame.buffer()?;
101//!
102//! // Stop the capture after 6 seconds
103//! if self.start.elapsed().as_secs() >= 6 {
104//! // Finish the encoder and save the video.
105//! self.encoder.take().unwrap().finish()?;
106//!
107//! capture_control.stop();
108//!
109//! // Because there wasn't any new lines in previous prints
110//! println!();
111//! }
112//!
113//! Ok(())
114//! }
115//!
116//! // Optional handler called when the capture item (usually a window) closes.
117//! fn on_closed(&mut self) -> Result<(), Self::Error> {
118//! println!("Capture session ended");
119//!
120//! Ok(())
121//! }
122//! }
123//!
124//! // Gets the foreground window, refer to the docs for other capture items
125//! let primary_monitor = Monitor::primary().expect("There is no primary monitor");
126//!
127//! let settings = Settings::new(
128//! // Item to capture
129//! primary_monitor,
130//! // Capture cursor settings
131//! CursorCaptureSettings::Default,
132//! // Draw border settings
133//! DrawBorderSettings::Default,
134//! // The desired color format for the captured frame.
135//! ColorFormat::Rgba8,
136//! // Additional flags for the capture settings that will be passed to user defined `new` function.
137//! "Yea this works".to_string(),
138//! );
139//!
140//! // Starts the capture and takes control of the current thread.
141//! // The errors from handler trait will end up here
142//! Capture::start(settings).expect("Screen capture failed");
143//! ```
144#![warn(clippy::nursery)]
145#![warn(clippy::cargo)]
146#![warn(clippy::multiple_crate_versions)] // Should update as soon as possible
147
148/// Exported for the trait bounds
149pub use windows::Graphics::Capture::GraphicsCaptureItem as WindowsCaptureGraphicsCaptureItem;
150
151/// Contains the main capture functionality, including the `WindowsCaptureHandler` trait and related types.
152pub mod capture;
153/// Internal module for Direct3D 11 related functionality.
154mod d3d11;
155/// Contains the encoder functionality for encoding captured frames.
156pub mod encoder;
157/// Contains the `Frame` struct and related types for representing captured frames.
158pub mod frame;
159/// Contains the types and functions related to the Graphics Capture API.
160pub mod graphics_capture_api;
161/// Contains the functionality for working with monitors and screen information.
162pub mod monitor;
163/// Contains the `Settings` struct and related types for configuring the capture settings.
164pub mod settings;
165/// Contains the functionality for working with windows and capturing specific windows.
166pub mod window;