sdk/fidl/fuchsia.ui.composition/screenshot.fidl

// 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.composition;

using fuchsia.io;
using fuchsia.math;
using zx;

/// The different formats of Screenshot that can be requested.
@available(added=12)
type ScreenshotFormat = flexible enum : uint8 {
    /// The default format, requesting a tightly packed pixel data with 32 bit BGRA pixels.
    BGRA_RAW = 0;

    /// Requests tightly packed pixel data which is compressed into PNG format.
    @available(added=HEAD)
    PNG = 1;
};

/// Collects the current graphical content of a display.
@available(added=12)
@discoverable
closed protocol Screenshot {
    /// Collects the current graphical content of a display in a specified buffer `format` in the
    /// sRGB color space. Note that the sRGB color space is non-linear, meaning that unit tests
    /// doing pixel equality checks making use of non-fully saturated colors should convert to a
    /// linear color space.
    ///
    /// See https://fuchsia.dev/fuchsia-src/concepts/ui/scenic/color_spaces for more information.
    ///
    /// Screenshot is taken immediately, populated with the display's content from the most recent
    /// VSYNC.
    ///
    /// If the client calls [`Take`] a second time before a first [`Take`] call returns, the server
    /// will close the Screenshot connection with a ZX_ERR_SHOULD_WAIT epitaph.
    ///
    /// If capture fails due to an internal error, the server will close the Screenshot connection
    /// with a ZX_ERR_INTERNAL epitaph.
    strict Take(resource table {
        /// Format of the requested screenshot.
        1: format ScreenshotFormat;
    }) -> (resource table {
        /// CPU mappable read-only VMO that contains screenshot data. The server owns the VMO and
        /// may reuse for the next [`Take`]. The VMO is guaranteed to be accessible after mapping.
        /// In some allocations, VMO::read() might not be available, i.e. on emulator.
        ///
        /// Basic usage: After the client receives a VMO handle, to ensure data stability, it should
        /// finish reading the VMO before calling [`Take`] again. When finished reading, the client
        /// should drop the VMO handle.
        ///
        /// Advanced usage: To edit the data, or to persist it beyond the next [`Take`] call, the
        /// client should copy the data to a private VMO.
        1: vmo zx.Handle:VMO;
        /// Size of the screenshot in pixels.
        2: size fuchsia.math.SizeU;
    });

    /// Collects the current graphical content of a display in a specified buffer `format` in the
    /// sRGB color space. Note that the sRGB color space is non-linear, meaning that unit tests
    /// doing pixel equality checks making use of non-fully saturated colors should convert to a
    /// linear color space.
    ///
    /// TODO(https://fxbug.dev/42065844): Link to fuchsia.dev documentation when it's up.
    ///
    /// Screenshot is taken immediately, populated with the display's content from the most recent
    /// VSYNC.
    ///
    /// If the client calls [`TakeFile`] a second time before a first [`TakeFile`] call returns,
    /// the server will close the Screenshot connection with a ZX_ERR_SHOULD_WAIT epitaph.
    ///
    /// If capture fails due to an internal error, the server will close the Screenshot connection
    /// with a ZX_ERR_INTERNAL epitaph.
    ///
    /// This call should be used if the client is on the host and does not support VMOs,
    /// as is the case for ffx tools.
    strict TakeFile(resource table {
        /// Format of the requested screenshot.
        1: format ScreenshotFormat;
    }) -> (resource table {
        /// |fuchsia.io.File| channel used to read the generated screenshot file data.
        /// The server side of the channel is stored on the device until ZX_CHANNEL_PEER_CLOSED
        /// is detected.
        ///
        /// Basic usage: After the client recieves the client end of the file channel,
        /// to avoid memory pile-ups, it should finish reading the data
        /// before calling [`TakeFile`] again. When finished reading,
        /// the client should call [`Close`] on the |fuchsia.io.File| channel, this will release
        /// the memory allocated on the server side.
        1: file client_end:fuchsia.io.File;
        /// Size of the screenshot in pixels.
        2: size fuchsia.math.SizeU;
    });
};