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

// TODO(https://fxbug.dev/42107169): change struct to table
/// Describes how the pixels within an image are represented.
/// Simple formats need only a type.
/// Parametric pixel formats may require additional properties.
type PixelFormat = struct {
    type PixelFormatType;
    /// This bool effectively makes format_modifier optional, to satisfy
    /// 'ForDeprecatedCBindings', to satisfy "FIDL Simple C Bindings".
    has_format_modifier bool;
    format_modifier FormatModifier;
};

// TODO(https://fxbug.dev/42107179): add more formats.
/// The ordering of the channels in the format name reflects how
/// the actual layout of the channel.
///
/// Each of these values is opinionated re. the color spaces that can be
/// contained within (in contrast with Vulkan).
///
/// This should be kept in sync with fuchsia.sysmem2.PixelFormatType.
//
// TODO(dustingreen): Add more comment text re. pixel data layout for each of
// these.
type PixelFormatType = strict enum {
    INVALID = 0;

    /// RGB only, 8 bits per each of R/G/B/A sample
    /// Compatible with VK_FORMAT_R8G8B8A8_UNORM.
    R8G8B8A8 = 1;

    /// 32bpp BGRA, 1 plane.  RGB only, 8 bits per each of B/G/R/A sample.
    /// Compatible with VK_FORMAT_B8G8R8A8_UNORM.
    BGRA32 = 101; // For UVC compliance.

    /// YUV only, 8 bits per Y sample
    /// Compatible with VK_FORMAT_G8_B8_R8_3PLANE_420_UNORM.
    I420 = 102; // For UVC compliance.

    /// YUV only, 8 bits per Y sample
    /// Not compatible with any vulkan format.
    M420 = 103; // For UVC compliance.

    /// YUV only, 8 bits per Y sample
    /// Compatible with VK_FORMAT_G8_B8R8_2PLANE_420_UNORM.
    NV12 = 104; // For UVC compliance.

    /// YUV only, 8 bits per Y sample
    /// Compatible with VK_FORMAT_G8B8G8R8_422_UNORM.
    YUY2 = 105; // For UVC compliance.

    // TODO(garratt): Please elaborate in a comment here re. what/where the spec
    // for this is (including any variants that are specified / permitted /
    // indicated in-band / prohibited).
    MJPEG = 106; // For UVC compliance.

    /// YUV only, 8 bits per Y sample
    /// Compatible with VK_FORMAT_G8_B8_R8_3PLANE_420_UNORM with B and R swizzled.
    YV12 = 107;

    /// 24bpp BGR, 1 plane. RGB only, 8 bits per each of B/G/R sample
    /// Compatible with VK_FORMAT_B8G8R8_UNORM.
    BGR24 = 108;

    /// 16bpp RGB, 1 plane. 5 bits R, 6 bits G, 5 bits B
    /// Compatible with VK_FORMAT_R5G6B5_UNORM_PACK16.
    RGB565 = 109;

    /// 8bpp RGB, 1 plane. 3 bits R, 3 bits G, 2 bits B
    /// Not compatible with any vulkan format.
    RGB332 = 110;

    /// 8bpp RGB, 1 plane. 2 bits R, 2 bits G, 2 bits B
    /// Not compatible with any vulkan format.
    RGB2220 = 111;

    /// 8bpp, Luminance-only (red, green and blue have identical values.)
    /// Compatible with VK_FORMAT_R8_UNORM.
    L8 = 112;

    /// 8bpp, Red-only (Green and Blue are to be interpreted as 0).
    /// Compatible with VK_FORMAT_R8_UNORM.
    R8 = 113;

    /// 16bpp RG, 1 plane. 8 bits R, 8 bits G.
    /// Compatible with VK_FORMAT_R8G8_UNORM.
    R8G8 = 114;

    /// 32bpp RGBA, 1 plane. 2 bits A, 10 bits R/G/B.
    /// Compatible with VK_FORMAT_A2R10G10B10_UNORM_PACK32.
    A2R10G10B10 = 115;

    /// 32bpp BGRA, 1 plane. 2 bits A, 10 bits R/G/B.
    /// Compatible with VK_FORMAT_A2B10G10R10_UNORM_PACK32.
    A2B10G10R10 = 116;

    /// The sysmem client is explicitly indicating that the sysmem client does
    /// not care which pixel format is chosen / used.  When setting this value,
    /// the sysmem client must not set format_modifier_value.
    @available(added=10)
    DO_NOT_CARE = 0xFFFFFFFE;
};

// TODO(https://fxbug.dev/42107169): change struct to table
/// Describes how the pixels within an image are meant to be presented.
/// Simple color spaces need only a type.
/// Parametric color spaces may require additional properties.
type ColorSpace = struct {
    type ColorSpaceType;
};

/// This list has a separate entry for each variant of a color space standard.
///
/// For this reason, should we ever add support for the RGB variant of 709, for
/// example, we'd add a separate entry to this list for that variant.  Similarly
/// for the RGB variants of 2020 or 2100.  Similarly for the YcCbcCrc variant of
/// 2020.  Similarly for the ICtCp variant of 2100.
///
/// A given ColorSpaceType may permit usage with a PixelFormatType(s) that
/// provides a bits-per-sample that's compatible with the ColorSpaceType's
/// official spec.  Not all spec-valid combinations are necessarily supported.
/// See ImageFormatIsSupportedColorSpaceForPixelFormat() for the best-case degree
/// of support, but a "true" from that function doesn't guarantee that any given
/// combination of participants will all support the desired combination of
/// ColorSpaceType and PixelFormatType.
///
/// The sysmem service helps find a mutually supported combination and allocate
/// suitable buffers.
///
/// A ColorSpaceType's spec is not implicitly extended to support
/// outside-the-standard bits-per-sample (R, G, B, or Y sample).  For example,
/// for 2020 and 2100, 8 bits-per-Y-sample is not supported (by sysmem), because
/// 8 bits-per-Y-sample is not in the spec for 2020 or 2100.  A sysmem
/// participant that attempts to advertise support for a PixelFormat + ColorSpace
/// that's non-standard will cause sysmem to reject the combo and fail to
/// allocate (intentionally, to strongly discourage specifying
/// insufficiently-defined combos).
type ColorSpaceType = strict enum {
    /// Not a valid color space type.
    INVALID = 0;
    /// sRGB
    SRGB = 1;
    /// 601 NTSC ("525 line") YCbCr primaries, narrow
    REC601_NTSC = 2;
    /// 601 NTSC ("525 line") YCbCr primaries, wide
    REC601_NTSC_FULL_RANGE = 3;
    /// 601 PAL ("625 line") YCbCr primaries, narrow
    REC601_PAL = 4;
    /// 601 PAL ("625 line") YCbCr primaries, wide
    REC601_PAL_FULL_RANGE = 5;
    /// 709 YCbCr (not RGB)
    REC709 = 6;
    /// 2020 YCbCr (not RGB, not YcCbcCrc)
    REC2020 = 7;
    /// 2100 YCbCr (not RGB, not ICtCp)
    REC2100 = 8;

    /// Either the pixel format doesn't represent a color, or it's in an
    /// application-specific colorspace that isn't describable by another entry
    /// in this enum.
    PASS_THROUGH = 9;

    /// The sysmem client is explicitly indicating that the sysmem client does
    /// not care which color space is chosen / used.
    @available(added=10)
    DO_NOT_CARE = 0xFFFFFFFE;
};