Skip to main content

edid_seria/
builder.rs

1//! Builder for valid EDID base blocks.
2
3use crate::edid::EdidBlock;
4use crate::error::{DescriptorError, DtdError, EdidError, MetadataError, MetadataWriteError};
5use crate::metadata::{
6    BaseMetadata, ChromaticityCoordinates, EstablishedTimings, MonitorDescriptor,
7    StandardTimingEntry,
8};
9use crate::timing::DetailedTiming;
10
11/// Explicit placement policy used by [`BaseBlockBuilder`].
12#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
13pub enum TimingPlacement {
14    /// Reuse existing timing slots first, then dummy/free slots; never overwrite descriptors.
15    #[default]
16    ReuseTimingsThenFreePreserveDescriptors,
17}
18
19/// Errors produced while constructing a base block.
20#[derive(Clone, Debug, PartialEq, Eq)]
21#[non_exhaustive]
22pub enum BaseBlockError {
23    /// Identity metadata is not representable.
24    Metadata(MetadataError),
25    /// Chromaticity or standard timings are not representable.
26    MetadataWrite(MetadataWriteError),
27    /// A monitor descriptor is invalid.
28    Descriptor(DescriptorError),
29    /// A detailed timing cannot be represented or no slot is available.
30    Dtd(DtdError),
31    /// An existing block is not a valid EDID base block.
32    InvalidExistingBlock {
33        /// Validation failure from the supplied block.
34        source: EdidError,
35    },
36}
37impl From<MetadataError> for BaseBlockError {
38    fn from(e: MetadataError) -> Self {
39        Self::Metadata(e)
40    }
41}
42impl From<MetadataWriteError> for BaseBlockError {
43    fn from(e: MetadataWriteError) -> Self {
44        Self::MetadataWrite(e)
45    }
46}
47impl From<DescriptorError> for BaseBlockError {
48    fn from(e: DescriptorError) -> Self {
49        Self::Descriptor(e)
50    }
51}
52impl From<DtdError> for BaseBlockError {
53    fn from(e: DtdError) -> Self {
54        Self::Dtd(e)
55    }
56}
57impl core::fmt::Display for BaseBlockError {
58    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
59        match self {
60            Self::Metadata(e) => write!(f, "base metadata: {e}"),
61            Self::MetadataWrite(e) => write!(f, "base metadata encoding: {e}"),
62            Self::Descriptor(e) => write!(f, "monitor descriptor: {e}"),
63            Self::Dtd(e) => write!(f, "detailed timing: {e}"),
64            Self::InvalidExistingBlock { source } => {
65                write!(f, "existing base block is invalid: {source}")
66            }
67        }
68    }
69}
70impl std::error::Error for BaseBlockError {
71    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
72        match self {
73            Self::Metadata(source) => Some(source),
74            Self::MetadataWrite(source) => Some(source),
75            Self::Descriptor(source) => Some(source),
76            Self::Dtd(source) => Some(source),
77            Self::InvalidExistingBlock { source } => Some(source),
78        }
79    }
80}
81
82/// Incrementally constructs a valid EDID base block.
83#[derive(Clone, Debug)]
84pub struct BaseBlockBuilder {
85    base: EdidBlock,
86    metadata: Option<BaseMetadata>,
87    chromaticity: Option<ChromaticityCoordinates>,
88    established: Option<EstablishedTimings>,
89    standard: Option<[StandardTimingEntry; 8]>,
90    descriptors: [Option<MonitorDescriptor>; 4],
91    timings: Option<Vec<DetailedTiming>>,
92    placement: TimingPlacement,
93    pending_error: Option<BaseBlockError>,
94}
95impl BaseBlockBuilder {
96    /// Create a builder using the library's minimal EDID defaults.
97    #[must_use]
98    pub fn new() -> Self {
99        Self::default()
100    }
101
102    /// Start from a validated base block, preserving fields that are not replaced.
103    pub fn from_block(block: &EdidBlock) -> Result<Self, BaseBlockError> {
104        block
105            .validate_base()
106            .map_err(|source| BaseBlockError::InvalidExistingBlock { source })?;
107        Ok(Self::stage(block.clone()))
108    }
109    fn stage(base: EdidBlock) -> Self {
110        Self {
111            base,
112            metadata: None,
113            chromaticity: None,
114            established: None,
115            standard: None,
116            descriptors: core::array::from_fn(|_| None),
117            timings: None,
118            placement: TimingPlacement::default(),
119            pending_error: None,
120        }
121    }
122
123    /// Set identity and capability metadata.
124    #[must_use]
125    pub fn metadata(mut self, value: BaseMetadata) -> Self {
126        self.metadata = Some(value);
127        self
128    }
129    /// Set the four chromaticity points.
130    #[must_use]
131    pub fn chromaticity(mut self, value: ChromaticityCoordinates) -> Self {
132        self.chromaticity = Some(value);
133        self
134    }
135    /// Set established timing bitfields.
136    #[must_use]
137    pub fn established_timings(mut self, value: EstablishedTimings) -> Self {
138        self.established = Some(value);
139        self
140    }
141    /// Set all eight standard timing slots.
142    #[must_use]
143    pub fn standard_timings(mut self, value: [StandardTimingEntry; 8]) -> Self {
144        self.standard = Some(value);
145        self
146    }
147    /// Set one monitor descriptor slot (zero-based).
148    ///
149    /// An out-of-range slot is recorded and returned by [`Self::build`]; it is
150    /// never silently ignored.
151    #[must_use]
152    pub fn monitor_descriptor(mut self, slot: usize, value: MonitorDescriptor) -> Self {
153        if let Some(target) = self.descriptors.get_mut(slot) {
154            *target = Some(value);
155        } else {
156            self.pending_error = Some(BaseBlockError::Descriptor(
157                DescriptorError::SlotOutOfRange { slot, slots: 4 },
158            ));
159        }
160        self
161    }
162    /// Select the explicit detailed-timing placement policy.
163    #[must_use]
164    pub fn timing_placement(mut self, placement: TimingPlacement) -> Self {
165        self.placement = placement;
166        self
167    }
168    /// Set the detailed timings, which are placed into reusable slots.
169    #[must_use]
170    pub fn detailed_timings(mut self, value: Vec<DetailedTiming>) -> Self {
171        self.timings = Some(value);
172        self
173    }
174    /// Build the block atomically; failures return no partially written block.
175    ///
176    /// When detailed timings are set, existing timing slots are replaced
177    /// before free slots, monitor descriptors are preserved, and unused former
178    /// timing slots are cleared. Without an explicit timing set, staged slots remain unchanged.
179    pub fn build(self) -> Result<EdidBlock, BaseBlockError> {
180        if let Some(error) = self.pending_error {
181            return Err(error);
182        }
183        let mut block = self.base;
184        if let Some(value) = self.metadata {
185            block.set_metadata(&value)?;
186        }
187        if let Some(value) = self.chromaticity {
188            block.set_chromaticity(&value)?;
189        }
190        if let Some(value) = self.established {
191            block.set_established_timings(&value)?;
192        }
193        if let Some(value) = self.standard {
194            block.set_standard_timings(&value)?;
195        }
196        for (slot, value) in self.descriptors.into_iter().enumerate() {
197            if let Some(value) = value {
198                block.set_monitor_descriptor(slot, &value)?;
199            }
200        }
201        if let Some(timings) = self.timings {
202            match self.placement {
203                TimingPlacement::ReuseTimingsThenFreePreserveDescriptors => {
204                    block.write_resolutions_checked(&timings)?;
205                }
206            }
207        }
208        block.update_checksum();
209        Ok(block)
210    }
211}
212
213impl Default for BaseBlockBuilder {
214    fn default() -> Self {
215        let metadata = BaseMetadata {
216            manufacturer_id: "AAA".into(),
217            product_code: 0,
218            serial_number: 0,
219            manufacture_week: 0,
220            manufacture_year: 1990,
221            input: 0x80,
222            horizontal_size_cm: 0,
223            vertical_size_cm: 0,
224            gamma: None,
225            feature_flags: 0,
226        };
227        Self::stage(
228            EdidBlock::from_metadata(&metadata).expect("the builder default metadata is valid"),
229        )
230    }
231}
232
233#[cfg(test)]
234mod tests {
235    use super::*;
236    use crate::{
237        ChromaticityPoint, DtdError, EdidError, MetadataError, StandardTiming,
238        StandardTimingAspectRatio, all_presets,
239    };
240
241    fn valid_metadata() -> BaseMetadata {
242        BaseMetadata {
243            manufacturer_id: "ABC".into(),
244            product_code: 0x1234,
245            serial_number: 0x5678_9ABC,
246            manufacture_week: 25,
247            manufacture_year: 2024,
248            input: 0x80,
249            horizontal_size_cm: 60,
250            vertical_size_cm: 34,
251            gamma: Some(220),
252            feature_flags: 0x0A,
253        }
254    }
255    #[test]
256    fn default_builder_returns_valid_minimal_base() {
257        let block = BaseBlockBuilder::new().build().unwrap();
258        assert_eq!(block.validate(), Ok(()));
259        assert_eq!(block.raw[126], 0);
260        assert_eq!(
261            block
262                .raw
263                .iter()
264                .fold(0u8, |sum, byte| sum.wrapping_add(*byte)),
265            0
266        );
267        assert_eq!(block.metadata().unwrap().manufacturer_id, "AAA");
268    }
269
270    #[test]
271    fn metadata_and_capability_fields_roundtrip_through_builder() {
272        let metadata = valid_metadata();
273        let chromaticity = ChromaticityCoordinates {
274            red: ChromaticityPoint { x: 650, y: 340 },
275            green: ChromaticityPoint { x: 300, y: 600 },
276            blue: ChromaticityPoint { x: 150, y: 60 },
277            white: ChromaticityPoint { x: 313, y: 329 },
278        };
279        let established = EstablishedTimings::from_raw([0x20, 0x08, 0x15]);
280        let mut standard = [StandardTimingEntry::Unused; 8];
281        standard[0] = StandardTimingEntry::Timing(StandardTiming {
282            horizontal_pixels: 1920,
283            aspect_ratio: StandardTimingAspectRatio::SixteenByNine,
284            refresh_rate_hz: 60,
285        });
286
287        let block = BaseBlockBuilder::new()
288            .metadata(metadata.clone())
289            .chromaticity(chromaticity)
290            .established_timings(established)
291            .standard_timings(standard)
292            .build()
293            .unwrap();
294
295        assert_eq!(block.metadata().unwrap(), metadata);
296        assert_eq!(block.chromaticity().unwrap(), chromaticity);
297        assert_eq!(block.established_timings().unwrap(), established);
298        assert_eq!(block.standard_timings().unwrap(), standard);
299    }
300    #[test]
301    fn invalid_metadata_is_reported_without_partial_result() {
302        let metadata = BaseMetadata {
303            manufacturer_id: "abC".into(),
304            product_code: 0,
305            serial_number: 0,
306            manufacture_week: 0,
307            manufacture_year: 2024,
308            input: 0x80,
309            horizontal_size_cm: 0,
310            vertical_size_cm: 0,
311            gamma: None,
312            feature_flags: 0,
313        };
314        assert_eq!(
315            BaseBlockBuilder::new().metadata(metadata).build(),
316            Err(BaseBlockError::Metadata(
317                MetadataError::InvalidManufacturerCharacter {
318                    index: 0,
319                    character: 'a'
320                }
321            ))
322        );
323    }
324
325    #[test]
326    fn descriptors_are_preserved_when_timings_are_added() {
327        let block = BaseBlockBuilder::new()
328            .monitor_descriptor(0, MonitorDescriptor::ProductName("panel".into()))
329            .detailed_timings(vec![all_presets()[0].clone()])
330            .build()
331            .unwrap();
332        assert_eq!(
333            block.monitor_descriptor(0).unwrap(),
334            Some(MonitorDescriptor::ProductName("panel".into()))
335        );
336    }
337
338    #[test]
339    fn from_block_reuses_timings_then_free_slots_and_preserves_descriptors() {
340        let mut existing = EdidBlock::from_metadata(&valid_metadata()).unwrap();
341        let old_timing = all_presets()[0].clone();
342        existing.write_detailed_checked(2, &old_timing).unwrap();
343        let descriptor = MonitorDescriptor::ProductName("panel".into());
344        existing.set_monitor_descriptor(1, &descriptor).unwrap();
345        assert_eq!(
346            BaseBlockBuilder::from_block(&existing)
347                .unwrap()
348                .build()
349                .unwrap(),
350            existing
351        );
352        let descriptor_bytes = existing.raw[54 + 18..54 + 2 * 18].to_owned();
353        let replacement = all_presets()[6].clone();
354        let added = all_presets()[7].clone();
355        let block = BaseBlockBuilder::from_block(&existing)
356            .unwrap()
357            .detailed_timings(vec![replacement.clone(), added.clone()])
358            .build()
359            .unwrap();
360
361        assert_eq!(
362            block.read_detailed(2).unwrap().h_active,
363            replacement.h_active
364        );
365        assert_eq!(block.read_detailed(0).unwrap().h_active, added.h_active);
366        assert_eq!(
367            &block.raw[54 + 18..54 + 2 * 18],
368            descriptor_bytes.as_slice()
369        );
370        assert!(block.read_detailed(3).is_none());
371    }
372    #[test]
373    fn too_many_timings_returns_structured_slot_error() {
374        let timings = all_presets()[..].iter().take(5).cloned().collect();
375        assert!(matches!(
376            BaseBlockBuilder::new().detailed_timings(timings).build(),
377            Err(BaseBlockError::Dtd(DtdError::NoAvailableSlot {
378                requested: 5,
379                available: 4
380            }))
381        ));
382    }
383
384    #[test]
385    fn from_block_rejects_invalid_input_and_keeps_source_unchanged_on_slot_error() {
386        let mut invalid = EdidBlock::new_default();
387        invalid.raw[10] ^= 1;
388        assert!(matches!(
389            BaseBlockBuilder::from_block(&invalid),
390            Err(BaseBlockError::InvalidExistingBlock {
391                source: EdidError::InvalidChecksum { .. }
392            })
393        ));
394
395        let mut existing = EdidBlock::from_metadata(&valid_metadata()).unwrap();
396        for slot in 0..4 {
397            existing
398                .set_monitor_descriptor(slot, &MonitorDescriptor::ProductName(format!("D{slot}")))
399                .unwrap();
400        }
401        let before = existing.raw;
402        let result = BaseBlockBuilder::from_block(&existing)
403            .unwrap()
404            .detailed_timings(vec![all_presets()[0].clone()])
405            .build();
406        assert_eq!(
407            result,
408            Err(BaseBlockError::Dtd(DtdError::NoAvailableSlot {
409                requested: 1,
410                available: 0
411            }))
412        );
413        assert_eq!(existing.raw, before);
414    }
415}
416
417#[cfg(test)]
418mod boundary_tests {
419    use super::*;
420    use crate::{ChromaticityCoordinates, ChromaticityPoint, all_presets};
421    #[test]
422    fn descriptor_slot_four_is_structured_error() {
423        assert!(matches!(
424            BaseBlockBuilder::new()
425                .monitor_descriptor(4, MonitorDescriptor::Dummy)
426                .build(),
427            Err(BaseBlockError::Descriptor(
428                DescriptorError::SlotOutOfRange { slot: 4, slots: 4 }
429            ))
430        ));
431    }
432    #[test]
433    fn invalid_chromaticity_is_rejected() {
434        let point = ChromaticityPoint { x: 1024, y: 0 };
435        let c = ChromaticityCoordinates {
436            red: point,
437            green: point,
438            blue: point,
439            white: point,
440        };
441        assert!(matches!(
442            BaseBlockBuilder::new().chromaticity(c).build(),
443            Err(BaseBlockError::MetadataWrite(
444                MetadataWriteError::InvalidChromaticityValue { value: 1024 }
445            ))
446        ));
447    }
448    #[test]
449    fn invalid_timing_returns_error() {
450        let mut timing = all_presets()[0].clone();
451        timing.h_active = 0;
452        assert!(matches!(
453            BaseBlockBuilder::new()
454                .detailed_timings(vec![timing])
455                .build(),
456            Err(BaseBlockError::Dtd(_))
457        ));
458    }
459}