Skip to main content

whisker_engine/
recording.rs

1//! Rust-only renderer used by engine and protocol tests.
2
3use whisker_protocol::{
4    ApplyResult, FramePacket, RenderCapabilities, SceneProjection, SurfaceId, ValidationError,
5};
6
7/// Semantic frame receiver used by a [`Scene`](crate::Scene).
8///
9/// Platform renderer modules will implement the same information flow through
10/// generated bindings. This small Rust trait exists for engine tests and does
11/// not define the final cross-language ABI.
12pub trait FrameSink {
13    /// Receiver-specific presentation failure.
14    type Error;
15
16    /// Declares optional semantic protocol groups before a surface presents them.
17    fn capabilities(&self) -> RenderCapabilities;
18
19    /// Validates and presents one complete frame transaction.
20    fn present(&mut self, packet: &FramePacket) -> Result<ApplyResult, Self::Error>;
21}
22
23/// One attempted presentation and its recorded result.
24#[derive(Clone, Debug, PartialEq)]
25pub struct RecordedFrame {
26    /// Packet submitted to the renderer.
27    pub packet: FramePacket,
28    /// Reference validation outcome.
29    pub result: Result<ApplyResult, ValidationError>,
30}
31
32/// Rust-only frame receiver backed by [`SceneProjection`].
33///
34/// Every attempted packet is retained, including malformed packets. Tests can
35/// therefore assert both the producer output and the receiver state after
36/// acceptance, recovery requests, or validation failures.
37#[derive(Debug)]
38pub struct RecordingRenderer {
39    projection: SceneProjection,
40    frames: Vec<RecordedFrame>,
41}
42
43impl RecordingRenderer {
44    /// Creates an empty receiver for one surface.
45    pub fn new(surface: SurfaceId) -> Self {
46        Self {
47            projection: SceneProjection::new(surface),
48            frames: Vec::new(),
49        }
50    }
51
52    /// Returns the accepted reference projection.
53    pub const fn projection(&self) -> &SceneProjection {
54        &self.projection
55    }
56
57    /// Returns every attempted frame in submission order.
58    pub fn frames(&self) -> &[RecordedFrame] {
59        &self.frames
60    }
61}
62
63impl FrameSink for RecordingRenderer {
64    type Error = ValidationError;
65
66    fn capabilities(&self) -> RenderCapabilities {
67        RenderCapabilities::all_frame_native()
68    }
69
70    fn present(&mut self, packet: &FramePacket) -> Result<ApplyResult, Self::Error> {
71        let result = self.projection.apply(packet);
72        self.frames.push(RecordedFrame {
73            packet: packet.clone(),
74            result: result.clone(),
75        });
76        result
77    }
78}
79
80#[cfg(test)]
81mod tests {
82    use super::*;
83    use whisker_protocol::{FrameHeader, FrameMode, ProtocolVersion, SurfaceId, ValidationError};
84
85    fn surface(value: u64) -> SurfaceId {
86        SurfaceId::new(value).expect("test surface")
87    }
88
89    #[test]
90    fn records_accepted_and_rejected_packets() {
91        let mut renderer = RecordingRenderer::new(surface(1));
92        assert_eq!(
93            renderer.capabilities(),
94            RenderCapabilities::all_frame_native()
95        );
96        let packet = FramePacket {
97            header: FrameHeader {
98                version: ProtocolVersion::CURRENT,
99                surface: surface(1),
100                scene_epoch: 1,
101                frame_id: 1,
102                base_revision: 0,
103                target_revision: 1,
104                viewport_epoch: 1,
105                mode: FrameMode::Snapshot,
106            },
107            operations: Vec::new(),
108        };
109        assert_eq!(
110            renderer.present(&packet),
111            Ok(ApplyResult::Accepted { revision: 1 })
112        );
113
114        let mut malformed = packet;
115        malformed.header.scene_epoch = 2;
116        malformed.header.surface = surface(2);
117        assert_eq!(
118            renderer.present(&malformed),
119            Err(ValidationError::SurfaceMismatch {
120                expected: surface(1),
121                received: surface(2),
122            })
123        );
124
125        assert_eq!(renderer.projection().revision(), 1);
126        assert_eq!(renderer.frames().len(), 2);
127        assert_eq!(
128            renderer.frames()[0].result,
129            Ok(ApplyResult::Accepted { revision: 1 })
130        );
131        assert!(renderer.frames()[1].result.is_err());
132    }
133}