sdk/fidl/fuchsia.hardware.backlight/backlight.fidl

// 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.
@available(added=HEAD)
library fuchsia.hardware.backlight;
using zx;

// TODO(https://fxbug.dev/419035481): Rework this struct to remove the design issues
// flagged below.
type State = struct {
    // TODO(https://fxbug.dev/419035481): The backlight_ prefix is redundant
    // here. The field appears to be redundant with specifying a `brightness`
    // value of 0.0.
    backlight_on bool;

    // TODO(https://fxbug.dev/419035481): The field's values have
    // context-dependent measurement units, which leads to error-prone code.
    /// `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.
    brightness float64;
};

// TODO(https://fxbug.dev/419035481): Describe the association between a
// backlight and a panel. Define the meaning of this interface for display
// technologies that do not have backlights, such as OLED. Specify the handling of
// invalid parameters in client requests.
closed protocol Device {
    /// Gets the current backlight brightness as a percentage value between 0.0
    /// and 1.0
    strict GetStateNormalized() -> (struct {
        state State;
    }) error zx.Status;

    /// Sets the current backlight brightness as a percentage value between 0.0
    /// and 1.0
    //
    // TODO(https://fxbug.dev/419035481): Specify the mapping of values to the
    // list of discrete levels supported by hardware.
    strict SetStateNormalized(struct {
        state State;
    }) -> () error zx.Status;

    /// Gets the current backlight brightness in nits
    strict GetStateAbsolute() -> (struct {
        state State;
    }) error zx.Status;

    /// Sets the current backlight brightness in nits.
    //
    // TODO(https://fxbug.dev/419035481): Specify the mapping of values to the
    // list of discrete levels supported by hardware.
    strict SetStateAbsolute(struct {
        state State;
    }) -> () error zx.Status;

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

// Added to allow service connection to replace devfs
service Service {
    backlight client_end:Device;
};