// Copyright 2023 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.display.types;

/// Specifies how individual pixels are arranged in an image buffer.
///
/// The tiling format influences other image parameters, such as dimensions
/// and pixel format, that are supported by the display engines. Display engine
/// drivers currently express this knowledge by setting buffer constraints in
/// sysmem, and by rejecting invalid combinations.
///
/// Values other than [`IMAGE_TILING_TYPE_LINEAR`] and
/// [`IMAGE_TILING_TYPE_CAPTURE`] are an escape hatch. The driver and image
/// producer are responsible for agreeing on the meaning of the value, through
/// some mechanism outside the scope of this API.
alias ImageTilingTypeIdValue = uint32;

/// Equivalent to Vulkan's linear tiling.
///
/// Pixels are arranged in the image buffer in row-major order. Each row may
/// have some padding bytes.
///
/// Default for [`ImageTilingTypeIdValue`].
const IMAGE_TILING_TYPE_LINEAR ImageTilingTypeIdValue = 0;

// The gap between IMAGE_TILING_TYPE_LINEAR and IMAGE_TILING_TYPE_CAPTURE can be
// used for platform-specific / driver-specific formats. Eventually, this magic
// will be replaced by better primitives for discovering and negotiating image
// contracts.

/// The tiling used by the display engine's capture feature.
///
/// This value is used as a signal that the image buffer will used by the
/// display engine to store displayed contents, and therefore is a slight abuse
/// of the "tiling" semantics.
///
/// Like every other tiling value, this introduces constraints on image
/// parameters such as dimensions and pixel format.
const IMAGE_TILING_TYPE_CAPTURE ImageTilingTypeIdValue = 10;

// The signal provided by IMAGE_TILING_TYPE_CAPTURE will be moved elsewhere in a
// future revision of this API.

/// The intended usage for a sysmem BufferCollection holding image buffers.
///
/// Each buffer in the collection will store a single image, which is intended
/// to be used as described below.
type ImageBufferUsage = struct {
    /// Specifies how individual pixels are arranged in an image buffer.
    ///
    /// See [`fuchsia.hardware.display.types/ImageTilingTypeIdValue`].
    tiling_type uint32;
};

/// Describes how an image is stored in a buffer of a sysmem BufferCollection.
///
/// The buffer is dedicated to storing a single image. The properties below are
/// needed for decoding the image from the buffer.
// TODO(https://fxbug.dev/329163718): sysmem already has some of the information
// here. Prune this structure, replacing members with querying properties on the
// associated sysmem BufferCollection.
type ImageMetadata = struct {
    /// The width and height of the image in pixels.
    width uint32;
    height uint32;

    /// Specifies how individual pixels are arranged in an image buffer.
    ///
    /// See [`fuchsia.hardware.display.types/ImageTilingTypeIdValue`].
    tiling_type uint32;
};