// Copyright 2023 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library fuchsia.hardware.display;

using fuchsia.images2;
using fuchsia.hardware.display.types;

/// Describes an operational mode for a display device attached to the system.
///
/// The operational parameters that make up a mode description must be updated
/// atomically, using a resource-intensive "mode setting" operation. Parameters
/// that can be changed quickly, such as brightness and contrast, do not belong
/// in a mode description.
type Mode = struct {
    /// Number of pixels on a horizontal line of the displayed image.
    ///
    /// This describes the image data sent to the display, which is also called
    /// the "active area" or "active pixels" in raster scan terminology. Despite
    /// the name, some of the "active pixels" may not actually be shown to the
    /// user, for example due to corners or notches.
    horizontal_resolution uint32;

    /// Number of horizontal lines that make up a displayed image.
    ///
    /// This describes the image data sent to the display, which is also called
    /// the "active area" or "active pixels" in raster scan terminology. Despite
    /// the name, some of the "active pixels" may not actually be shown to the
    /// user, for example due to corners or notches.
    vertical_resolution uint32;

    /// Number of images transmitted to the display in 100 seconds.
    ///
    /// This is the display's vertical refresh rate, in centihertz (0.01 Hz).
    refresh_rate_e2 uint32;

    /// Bit field of mode attributes.
    ///
    /// This field is currently unused. It will be used for binary attributes,
    /// such as whether a display mode is interlaced.
    flags uint32;
};

/// Description for a display device attached to the system.
///
/// Display devices include external monitors and internal panels.
type Info = struct {
    /// Uniquely identifies the display in a Controller connection.
    ///
    /// See [`fuchsia.hardware.display.types/DisplayId`].
    id fuchsia.hardware.display.types.DisplayId;

    /// Operational modes supported by the described display device.
    ///
    /// The first entry is the device's preferred mode.
    modes vector<Mode>:MAX;

    /// Pixel formats that can be directly displayed on the attached display.
    ///
    /// This field will be revised to better reflect the subtleties around
    /// modern display hardware, such as multiple layer types, and around
    /// pixel format modifiers, such as tiling and framebuffer compression
    /// formats. See https://fxbug.dev/42072347 and https://fxbug.dev/42076907.
    ///
    /// The formats listed here reflect support from both the display engine
    /// hardware and the display device. This means some of the formats may be
    /// subject to conversion inside the display engine hardware.
    ///
    /// The first entry in the list is the display's preferred format. This
    /// format is likely to be supported for transferring data between the
    /// display engine and the display hardware, and not require any conversion
    /// inside the display engine.
    ///
    /// Format conversion inside the display engine is likely to be
    /// significantly more power-efficient than a GPU render stage or software
    /// conversion. So, using any format in this list is better than using the
    /// GPU to convert to the preferred format.
    pixel_format vector<fuchsia.images2.PixelFormat>:MAX;

    /// Part of a display device identifier that persists across boot cycles.
    ///
    /// If the `manufacturer_name`, `monitor_name` and `monitor_serial` fields
    /// are all non-empty, they  make up an identifier that is likely to be
    /// unique to the attached device, and is highly unlikely to change across
    /// boot cycles. Software that needs to identify displays (for example, to
    /// honor display-specific preferences) should use this triplet.
    manufacturer_name string:IDENTIFIER_MAX_LEN;

    /// Part of a display device identifier that persists across boot cycles.
    ///
    /// See `manufacturer_name` for details.
    monitor_name string:IDENTIFIER_MAX_LEN;

    /// Part of a display device identifier that persists across boot cycles.
    ///
    /// See `manufacturer_name` for details.
    monitor_serial string:IDENTIFIER_MAX_LEN;

    /// Physical horizontal size of the displayed image area, in millimeters.
    ///
    /// If `using_fallback_size` is true, the value is a best guess from the
    /// driver. Otherwise, the value here is reported by the display device.
    horizontal_size_mm uint32;

    /// Physical vertical size of the displayed image area, in millimeters.
    ///
    /// See `horizontal_size_mm` for more details.
    vertical_size_mm uint32;

    /// True if the driver does not have the display's physical sizing info.
    using_fallback_size bool;
};

const IDENTIFIER_MAX_LEN uint32 = 128;