concordance 0.1.0

A library for negotiating HDMI 2.1 modes.
Documentation 
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

//! Negotiation policy type and named presets.

/// Controls how the ranker orders validated configurations.
///
/// `NegotiationPolicy` is a const-constructible struct. Named presets are provided
/// for common cases; custom implementations can encode platform-specific priorities.
///
/// # Policy matrix
///
/// The two flags [`prefer_color_fidelity`] and [`prefer_high_refresh`] are independent
/// and together select one of four ranking modes for the quality/performance dimension:
///
/// | `prefer_color_fidelity` | `prefer_high_refresh` | Ranking mode |
/// |:-----------------------:|:---------------------:|--------------|
/// | `true`                  | `false`               | **Color fidelity** — bit depth → color format → refresh rate (descending) |
/// | `false`                 | `true`                | **High refresh** — refresh rate → bit depth → color format (descending) |
/// | `true`                  | `true`                | **Color fidelity** — same as color-fidelity mode; fidelity takes precedence |
/// | `false`                 | `false`               | **Power saving** — all three criteria reversed (ascending), minimising bandwidth |
///
/// [`prefer_color_fidelity`]: NegotiationPolicy::prefer_color_fidelity
/// [`prefer_high_refresh`]: NegotiationPolicy::prefer_high_refresh
#[non_exhaustive]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct NegotiationPolicy {
    /// Prefer native resolution over non-native resolutions.
    pub prefer_native_resolution: bool,

    /// Prefer higher color fidelity (bit depth, color encoding) over higher refresh rate.
    pub prefer_color_fidelity: bool,

    /// Prefer higher refresh rate over other factors after color fidelity.
    ///
    /// When both `prefer_color_fidelity` and `prefer_high_refresh` are `true`, color
    /// fidelity takes precedence. When both are `false`, the ranker enters power-saving
    /// mode and reverses all three criteria to minimise bandwidth.
    pub prefer_high_refresh: bool,

    /// Penalize configurations that require DSC.
    pub penalize_dsc: bool,
}

impl NegotiationPolicy {
    /// Prefer maximum quality: native resolution, max color fidelity, then refresh rate.
    pub const BEST_QUALITY: Self = Self {
        prefer_native_resolution: true,
        prefer_color_fidelity: true,
        prefer_high_refresh: false,
        penalize_dsc: true,
    };

    /// Prefer maximum performance: native resolution, max refresh rate, then color fidelity.
    pub const BEST_PERFORMANCE: Self = Self {
        prefer_native_resolution: true,
        prefer_color_fidelity: false,
        prefer_high_refresh: true,
        penalize_dsc: false,
    };

    /// Prefer power saving: lower refresh rates and simpler configurations are ranked higher.
    ///
    /// Native resolution is still preferred even in power-saving mode. Running at a
    /// non-native resolution forces the display scaler on, which consumes additional
    /// power and introduces scaling artifacts — both outcomes that undermine the goal.
    /// Power savings come from reduced refresh rate and color depth, not reduced resolution.
    pub const POWER_SAVING: Self = Self {
        prefer_native_resolution: true,
        prefer_color_fidelity: false,
        prefer_high_refresh: false,
        penalize_dsc: true,
    };
}

impl Default for NegotiationPolicy {
    fn default() -> Self {
        Self::BEST_QUALITY
    }
}