gridvid/
lib.rs

1#![warn(missing_docs)]
2//! Gridvid is a Rust wrapper library for rendering MP4 videos from 2D vectors using a minimal interface.
3//!
4//! The outer vector translates to the X-axis and the inner vectors translate to the Y-axis.
5//!
6//! ## Basic Usage
7//!
8//! ```
9//! # fn main() -> gridvid::Result<()> {
10//!     use gridvid::Encoder;
11//!
12//!     // Create a 2D Vec of any element type, bool in this example
13//!     let mut grid: Vec<Vec<bool>> = vec![vec![false; 10]; 10];
14//!     let filename = std::env::temp_dir().join("gridvid_example.mp4");
15//!
16//!     // fn to map grid element reference to RGB tuple `(u8, u8, u8)`
17//!     let convert = |&b: &bool| if b { (0, 0, 255) } else { (0, 0, 0) };
18//!
19//!     // Initialize video encoder
20//!     let mut video = Encoder::new(&filename, Box::new(convert)).build()?;
21//!
22//!     // Update the grid as desired, adding a new frame for each grid state
23//!     for i in 0..grid.len() {
24//!         grid[i][i] = true;
25//!         video.add_frame(&grid)?;
26//!     }
27//!
28//!     // Write encoded video to output file
29//!     video.close()?;
30//!     println!("Output written to: {}", &filename.display());
31//! #
32//! #    // Remove file so doctest can be repeated
33//! #    std::fs::remove_file(&filename)?;
34//! #    Ok(())
35//! # }
36//! ```
37//! This sample code renders and exports the following:
38//!
39//! <video controls style="display: block; max-width: 360px" src="https://user-images.githubusercontent.com/65624699/224349598-32c3c34c-fde2-4194-a398-fe7cde6b3335.mp4"></video>
40//!
41//! ## Options Summary
42//! ```
43//! # fn main() -> gridvid::Result<()> {
44//! #
45//!     use gridvid::{Encoder, Gridlines, Scaling};
46//!
47//! #    let convert = |&b: &bool| if b { (0, 0, 255) } else { (0, 0, 0) };
48//! #    let filename = std::env::temp_dir().join("gridvid_demo.mp4");
49//! #    
50//!     let mut video = Encoder::new(&filename, Box::new(convert))
51//!         .fps(20)    // Set video frame rate to 20 fps
52//!
53//!         // Video Frame Scaling options
54//!         .scale(Scaling::Uniform(16))        // Upscale by a factor of 16
55//!         .scale(Scaling::MaxSize(720, 480))  // Scale to 720x480, keeping aspect ratio
56//!         .scale(Scaling::Stretch(720, 480))  // Stretch to 720x480, ignoring aspect ratio
57//!
58//!         // Gridline options
59//!         .gridlines(Gridlines::Show((255,255,255)))  // Set gridline color to white
60//!         .gridlines(Gridlines::Hide)                 // Hide gridlines
61//!         .build()?;
62//! #
63//! #    // Remove file so doctest can be repeated
64//! #    std::fs::remove_file(&filename)?;
65//! #
66//! #    Ok(())
67//! # }
68//! ```
69//!
70//! # [Encoder] Defaults:
71//! - Video frame rate is 4 [fps].
72//! - Black gridlines are inserted in between elements: [`Gridlines(0,0,0)`](Gridlines)
73//! - Video is scaled to 720x720: [`MaxSize(720, 720)`](Scaling)
74//!
75//! [fps]: EncoderBuilder::fps
76
77mod encoder;
78mod error;
79
80#[doc(inline)]
81pub use encoder::{Converter, Encoder, EncoderBuilder, Gridlines, Result, Rgb, Scaling};
82#[doc(inline)]
83pub use error::{Error, OPENH264_MAX_SIZE};
gridvid/lib.rs

gridvid/
lib.rs
