// Copyright 2018 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.backlight;
using zx;

struct State {
    bool backlight_on;
    /// `brightness` can either be:
    /// 1. The unitless brightness value on a linear scale where 0.0 is the minimum
    ///    brightness and 1.0 is the maximum brightness - represents the current /
    ///    desired brightness as a percentage within the supported range. Used
    ///    by the `GetStateNormalized` / `SetStateNormalized` calls. The maximum
    ///    brightness that can be set using `SetStateNormalized` is
    ///    GetBrightnessScale() * GetMaxAbsoluteBrightness().
    /// 2. Absolute brightness in nits. Used by the `GetStateAbsolute` /
    ///    `SetStateAbsolute` calls.
    float64 brightness;
};

protocol Device {
    /// Gets the current backlight brightness as a percentage value between 0.0
    /// and 1.0
    GetStateNormalized() -> (State state) error zx.status;

    /// Sets the current backlight brightness as a percentage value between 0.0
    /// and 1.0
    SetStateNormalized(State state) -> () error zx.status;

    /// Gets the current backlight brightness in nits
    GetStateAbsolute() -> (State state) error zx.status;

    /// Sets the current backlight brightness in nits. Not affected by the scale
    /// set by SetNormalizedBrightnessScale.
    SetStateAbsolute(State state) -> () error zx.status;

    /// Gets the maximum supported backlight brightness in nits, if known.
    /// Otherwise returns error ZX_ERR_NOT_SUPPORTED.
    GetMaxAbsoluteBrightness() -> (float64 max_brightness) error zx.status;

    /// Scales the maximum normalized brightness by a percentage value in
    /// [0.0, 1.0], if supported. Otherwise returns error ZX_ERR_NOT_SUPPORTED.
    /// Values passed to SetStateNormalized will correspond to a maximum
    /// brightness of scale * GetMaxAbsoluteBrightness(). Calling this may
    /// change the current absolute brightness.
    SetNormalizedBrightnessScale(float64 scale) -> () error zx.status;

    /// Gets the current normalized brightness scale as a percentage value in
    /// [0.0, 1.0].
    GetNormalizedBrightnessScale() -> (float64 scale) error zx.status;
};