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

/// Specifies how pixels are represented in the image buffer.
type PixelFormat = strict enum {
    /// BGRA_8
    ///
    /// A 32-bit four-component unsigned integer format.
    /// Byte order: B, G, R, A (little-endian ARGB packed 32-bit word).
    /// Equivalent to Skia `kBGRA_8888_SkColorType` color type.
    /// Equivalent to Zircon `ARGB_8888` pixel format on little-endian arch.
    BGRA_8 = 0;

    /// YUY2
    ///
    /// 4:2:2 (2x down-sampled UV horizontally; full res UV vertically)
    ///
    /// A 32-bit component that contains information for 2 pixels:
    /// Byte order: Y1, U, Y2, V
    /// Unpacks to 2 RGB pixels, where RGB1 = func(Y1, U, V)
    /// and RGB2 = func(Y2, U, V)
    /// Equivalent to YUV422
    YUY2 = 1;

    /// NV12
    ///
    /// 4:2:0 (2x down-sampled UV in both directions)
    ///
    /// Offset 0:
    /// 8 bit per pixel Y plane with bytes YYY.
    /// Offset height * stride:
    /// 8 bit UV data interleaved bytes as UVUVUV.
    ///
    /// Y plane has line stride >= width.
    ///
    /// In this context, both width and height are required to be even.
    ///
    /// The UV data is separated into "lines", with each "line" having same byte
    /// width as a line of Y data, and same "line" stride as Y data's line stride.
    /// The UV data has height / 2 "lines".
    ///
    /// In converting to RGB, the UV data gets up-scaled by 2x in both directions
    /// overall.  This comment is intentionally silent on exactly how UV up-scaling
    /// phase/filtering/signal processing works, as it's a complicated topic that
    /// can vary by implementation, typically trading off speed and quality of the
    /// up-scaling.  See comments in relevant conversion code for approach taken
    /// by any given convert path.  The precise relative phase of the UV data is
    /// not presently conveyed.
    NV12 = 2;

    /// YV12
    ///
    /// Like I420, except with V and U swapped.
    ///
    /// 4:2:0 (2x down-sampled UV in both directions)
    ///
    /// Offset 0:
    /// 8 bit per pixel Y plane with bytes YYY.
    /// Offset height * stride:
    /// 8 bit V data with uv_stride = stride / 2
    /// Offset height * stride + uv_stride * height / 2:
    /// 8 bit U data with uv_stride = stride / 2
    ///
    /// Y plane has line stride >= width.
    ///
    /// Both width and height are required to be even.
    YV12 = 3;

    /// R8G8B8A8
    ///
    /// A 32-bit four-component unsigned integer format.
    /// Byte order: R, G, B, A (little-endian ABGR packed 32-bit word).
    /// Equivalent to Skia `kRGBA_8888_SkColorType` color type.
    /// Equivalent to Zircon `ABGR_8888` pixel format on little-endian arch.
    ///
    /// This format can only be used with VK_DEVICE_MEMORY.
    R8G8B8A8 = 4;
};

/// Specifies how pixel color information should be interpreted.
type ColorSpace = strict enum {
    SRGB = 0;
};

/// Specifies how pixels are arranged in memory.
type Tiling = strict enum {
    /// Pixels are packed linearly.
    /// Equivalent to `VK_IMAGE_TILING_LINEAR`.
    LINEAR = 0;

    /// Pixels are packed in a GPU-dependent optimal format.
    /// Equivalent to `VK_IMAGE_TILING_OPTIMAL`.
    GPU_OPTIMAL = 1;
};

/// Specifies how alpha information should be interpreted.
type AlphaFormat = strict enum {
    /// Image is considered to be opaque.  Alpha channel is ignored.
    /// Blend function is: src.RGB
    OPAQUE = 0;
    /// Color channels have been premultiplied by alpha.
    /// Blend function is: src.RGB + (dest.RGB * (1 - src.A))
    PREMULTIPLIED = 1;
    /// Color channels have not been premultiplied by alpha.
    /// Blend function is: (src.RGB * src.A) + (dest.RGB * (1 - src.A))
    NON_PREMULTIPLIED = 2;
};

type Transform = strict enum {
    /// Pixels are displayed normally.
    NORMAL = 0;

    /// Pixels are mirrored left-right.
    FLIP_HORIZONTAL = 1;

    /// Pixels are flipped vertically.
    FLIP_VERTICAL = 2;

    /// Pixels are flipped vertically and mirrored left-right.
    FLIP_VERTICAL_AND_HORIZONTAL = 3;
};

/// Information about a graphical image (texture) including its format and size.
type ImageInfo = struct {
    /// Specifies if the image should be mirrored before displaying.
    @allow_deprecated_struct_defaults
    transform Transform = Transform.NORMAL;

    /// The width and height of the image in pixels.
    width uint32;
    height uint32;

    /// The number of bytes per row in the image buffer.
    stride uint32;

    /// The pixel format of the image.
    @allow_deprecated_struct_defaults
    pixel_format PixelFormat = PixelFormat.BGRA_8;

    /// The pixel color space.
    @allow_deprecated_struct_defaults
    color_space ColorSpace = ColorSpace.SRGB;

    /// The pixel arrangement in memory.
    @allow_deprecated_struct_defaults
    tiling Tiling = Tiling.LINEAR;

    /// Specifies the interpretion of the alpha channel, if one exists.
    @allow_deprecated_struct_defaults
    alpha_format AlphaFormat = AlphaFormat.OPAQUE;
};