// Copyright 2022 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.ui.display.color;
using zx;

/// The properties required to apply color conversion to the display.
/// The conversion is applied to each pixel of the display according to the formula:
///
/// [coefficients * (pixel + preoffsets) + postoffsets].
///
/// where pixel is a column vector consisting of the pixel's 3 RGB components.
type ConversionProperties = table {
    /// The |coefficients| param represents a 3x3 matrix, where the values are given in
    /// row-major order:
    ///
    /// | 0  1  2 |
    /// | 3  4  5 |
    /// | 6  7  8 |
    1: coefficients array<float32, 9>;
    /// Preoffsets and postoffsets represent a [3x1] vector each of RGB values.
    2: preoffsets array<float32, 3>;
    3: postoffsets array<float32, 3>;
};

@discoverable
closed protocol Converter {

    /// Modifies the color of final display output of rendered content. The sole parameter is a
    /// table of |ConversionProperties|, which contains the parameters required to apply the
    /// color conversion formula to the display. Please see |ConversionProperties| defined
    /// above for more information.
    ///
    /// All parameters in the properties table must be normal 32-bit floating point values.
    /// If any of the values do not meet this specification, the new color conversion values
    /// will not be applied and a value of ZX_ERR_INVALID_ARGS will be returned. Otherwise,
    /// the return value will be ZX_OK: https://en.wikipedia.org/wiki/Normal_number_%28computing%29.
    /// Once a value of ZX_OK has been returned to the client, the color conversion values are ready
    /// to be used in future render calls, including screenshots.
    ///
    /// Values in |ConversionProperties| may also be left blank. The default values for each member,
    /// if left blank, are as follows:
    ///     coefficients =
    ///             [1, 0, 0,
    ///              0, 1, 0,
    ///              0, 0, 1]  (i.e. the identity matrix)
    ///     preoffsets = [0,0,0]
    ///     postoffsets = [0,0,0]
    /// Thus, ColorConversion can be reset by passing in an empty table to this function.
    ///
    /// Hardware that support color conversion generally accept a limited range of coefficient
    /// values. Coefficients in the range of [-2, 2] inclusive will be accepted by most
    /// hardware. The hardware driver will clamp values that are outside its acceptable range.
    ///
    /// `preoffsets`, `postoffsets`: Clients are encouraged to produce color conversion values that
    /// do not depend on pre and post offsets since some hardware do not have support for that.
    /// For cases where pre and post offset values need to be used, the range should be limited to
    /// (-1, 1).
    strict SetValues(resource struct {
        properties ConversionProperties;
    }) -> (struct {
        res zx.Status;
    });

    /// Submits a minimum value that all channels of all pixels rendered to the display
    /// are clamped to. This can be used to mitigate the apparent effects of backlight
    /// bleeding on certain devices in low-light environments.
    ///
    /// The valid range for a minimum value is [0, 255] (inclusive).  For a new
    /// minimum value M, each color channel's range will be limited to [M, 255].
    ///
    /// Callers should wait for the acknowledgement to return before submitting another
    /// call to this function. The minimum_rgb clamping can be removed simply by submitting
    /// a value of 0.
    ///
    /// Not all hardware supports this feature. So this function returns |true|
    /// if successfully applied and |false| if unsupported.
    strict SetMinimumRgb(struct {
        minimum_rgb uint8;
    }) -> (struct {
        supported bool;
    });
};