sdk/fidl/fuchsia.ui.display.singleton/power.fidl

// Copyright 2024 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.singleton;

using zx;

/// The power mode of the display hardware.
@available(added=HEAD)
type PowerMode = flexible enum : uint32 {
    /// The display is powered off. The hardware will not apply new display
    /// configs nor generate new VSync events.
    ///
    /// All display devices must support this power mode.
    OFF = 0;

    /// The display is fully powered on.
    ///
    /// All display devices must support this power mode.
    ON = 1;

    /// The display is powered on and configured in a low power state that
    /// is suitable for presenting ambient information to the user,
    /// possibly with lower fidelity than ON, but with greater efficiency.
    ///
    /// A display device must support both `DOZE` and `DOZE_SUSPEND` power
    /// modes, or neither.
    DOZE = 2;

    /// The display is configured as the same state in DOZE but may stop
    /// applying display updates from the client.
    ///
    /// This is effectively a hint to the device that drawing to the display
    /// has been suspended and that the device must remain in a low power state
    /// and continue displaying its current contents indefinitely until the
    /// power mode changes.
    ///
    /// A display device must support both `DOZE` and `DOZE_SUSPEND` power
    /// modes, or neither. When both modes are supported, the display device
    /// is allowed to not use the hint above, in which case `DOZE_SUSPEND`
    /// is identical to `DOZE`.
    DOZE_SUSPEND = 3;
};

/// Controls the power state of the default display device.
@available(added=HEAD)
@discoverable
open protocol DisplayPower {
    /// Set the power state of the default connected display device to `power_mode`.
    ///
    /// Errors:
    ///  - `ZX_ERR_NOT_FOUND`: There is no connected display.
    ///  - `ZX_ERR_NOT_SUPPORTED`: The default connected display driver or hardware
    ///    does not support the requested power mode.
    ///  - `ZX_ERR_INTERNAL`: Operation failed for another reason.
    flexible SetPowerMode(struct {
        /// The display's new power mode.
        ///
        /// Displays have `ON` power mode when they are connected to the system.
        power_mode PowerMode;
    }) -> () error zx.Status;
};