1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
//! Recipes: getting frames and sound out of common engines and libraries.
//!
//! None of these crates is a dependency of tvpipe; the snippets show the
//! shape of the code, written against the versions current when this was
//! written (they are not compiled here).
//!
//! # CPU framebuffers
//!
//! - **pixels**: the frame is RGBA8: `Options::video(w, h, fps,
//! PixelFormat::Rgba)`, then `stream.write_video(pixels.frame(), pts)`.
//! - **softbuffer** and **minifb**: `u32` pixels `0x00RRGGBB`, whose
//! little-endian bytes are B, G, R, 0: [`PixelFormat::Bgr0`] and
//! [`Stream::write_video_u32`] (no `unsafe`, no `bytemuck`).
//!
//! # wgpu (and engines built on it)
//!
//! Render to (or copy the surface to) a texture with `COPY_SRC` at the
//! stream size (downscale in a pass: cheaper than encoding a 4K frame),
//! copy it into one of two or three `MAP_READ` staging buffers, and hand
//! tvpipe the mapped buffer from two frames ago, padded rows and all:
//!
//! ```ignore
//! const W: u32 = 1280;
//! const H: u32 = 720;
//! // Rows of a texture copy are padded to 256 bytes.
//! let padded = (W * 4).div_ceil(wgpu::COPY_BYTES_PER_ROW_ALIGNMENT)
//! * wgpu::COPY_BYTES_PER_ROW_ALIGNMENT;
//! let staging: Vec<wgpu::Buffer> = (0..3)
//! .map(|_| device.create_buffer(&wgpu::BufferDescriptor {
//! label: Some("tvpipe readback"),
//! size: (padded * H) as u64,
//! usage: wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::MAP_READ,
//! mapped_at_creation: false,
//! }))
//! .collect();
//!
//! // Every frame, after rendering into `target` (Rgba8Unorm, COPY_SRC):
//! if stream.wants_frame() {
//! let buf = &staging[frame % 3];
//! encoder.copy_texture_to_buffer(
//! target.as_image_copy(),
//! wgpu::TexelCopyBufferInfo {
//! buffer: buf,
//! layout: wgpu::TexelCopyBufferLayout {
//! offset: 0,
//! bytes_per_row: Some(padded),
//! rows_per_image: Some(H),
//! },
//! },
//! wgpu::Extent3d { width: W, height: H, depth_or_array_layers: 1 },
//! );
//! buf.slice(..).map_async(wgpu::MapMode::Read, |_| {});
//! pending.push_back((frame, stream.elapsed()));
//! }
//! queue.submit([encoder.finish()]);
//! device.poll(wgpu::PollType::Poll)?;
//! // Two frames later the mapping is done: no stall on the GPU.
//! if let Some(&(old, pts)) = pending.front().filter(|(f, _)| frame >= f + 2) {
//! let buf = &staging[old % 3];
//! {
//! let data = buf.slice(..).get_mapped_range();
//! let f = tvpipe::Frame::new(&data, padded as usize);
//! let _ = stream.write_video_frame(f, pts)?;
//! }
//! buf.unmap();
//! pending.pop_front();
//! }
//! ```
//!
//! Use [`PixelFormat::Bgra`] for a `Bgra8Unorm` surface. Checking
//! [`Stream::wants_frame`] first skips the copy for frames the encoder
//! would drop. An RGB→NV12 compute pass that writes a 1.5-byte-per-pixel
//! buffer cuts the readback by 2.7× and the conversion on the CPU:
//! [`PixelFormat::Nv12`] with [`Frame::planes`].
//!
//! # Bevy and macroquad
//!
//! - **Bevy**: a camera rendering to an `Image` with `COPY_SRC`, a render
//! graph node copying it to a staging buffer and sending the mapped
//! bytes over a channel to the main world (the shape of Bevy's
//! `headless_renderer` example), then as above. The screenshot API is
//! too slow per frame.
//! - **macroquad / miniquad** (OpenGL): render to a `RenderTarget`, read
//! it with `get_texture_data()`; GL rows are bottom-up:
//! `Frame::new(&bytes, w * 4).bottom_up(true)`.
//!
//! # Audio from a sound card callback (cpal)
//!
//! ```ignore
//! let audio = stream.audio_writer(); // Send + Clone
//! device.build_output_stream(&config, move |out: &mut [f32], _| {
//! mixer.fill(out);
//! audio.write_f32(out); // never blocks for long
//! }, |e| eprintln!("{e}"), None)?;
//! ```
//!
//! Use the device's sample rate in `Options::audio`. The TV plays about
//! 0.1–0.3 s after the local speakers; games usually mute one.
//!
//! # A hardware encoder
//!
//! With NVENC, VideoToolbox, Media Foundation or VA-API through the
//! program's own bindings: `Options::h264(w, h, fps)`, no B-frames, a
//! low-latency preset, an IDR when [`Stream::take_keyframe_request`] says
//! so (a long GOP is fine), then [`Stream::write_h264`].
//!
//! # FairPlay and crash isolation: the `tvpipe` command
//!
//! A program that wants FairPlay without linking LGPL code, or wants a
//! crash in tvpipe not to take it down, runs `tvpipe --machine` as a child
//! (like the Node SDK): SLRW records on its stdin ([`slrw`](crate::slrw)),
//! one JSON event per line on its stdout ([`Event::from_json`]); see
//! docs/machine.md. With `default-features = false` the library is then
//! only those two formats.
//!
//! # Shipping
//!
//! - **macOS**: the program makes the network connections, so macOS's
//! Local Network prompt names it; its `Info.plist` needs
//! `NSLocalNetworkUsageDescription`.
//! - **Windows**: the browser player listens on 127.0.0.1 only (no
//! firewall prompt).
//! - **Debug builds**: the built-in H.264 encoder is too slow unoptimized;
//! add `[profile.dev.package.tvpipe] opt-level = 3` (and the same for
//! `ring`).
use crate::;