include/media/hardware/VideoAPI.h

/*
 * Copyright (C) 2016 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef VIDEO_API_H_

#define VIDEO_API_H_

namespace android {

/**
 * Structure describing a media image (frame)
 * Currently only supporting YUV
 * @deprecated. Use MediaImage2 instead
 */
struct MediaImage {
    enum Type {
        MEDIA_IMAGE_TYPE_UNKNOWN = 0,
        MEDIA_IMAGE_TYPE_YUV,
    };

    enum PlaneIndex {
        Y = 0,
        U,
        V,
        MAX_NUM_PLANES
    };

    Type mType;
    uint32_t mNumPlanes;              // number of planes
    uint32_t mWidth;                  // width of largest plane (unpadded, as in nFrameWidth)
    uint32_t mHeight;                 // height of largest plane (unpadded, as in nFrameHeight)
    uint32_t mBitDepth;               // useable bit depth
    struct PlaneInfo {
        uint32_t mOffset;             // offset of first pixel of the plane in bytes
                                      // from buffer offset
        uint32_t mColInc;             // column increment in bytes
        uint32_t mRowInc;             // row increment in bytes
        uint32_t mHorizSubsampling;   // subsampling compared to the largest plane
        uint32_t mVertSubsampling;    // subsampling compared to the largest plane
    };
    PlaneInfo mPlane[MAX_NUM_PLANES];
};

/**
 * Structure describing a media image (frame)
 */
struct __attribute__ ((__packed__)) MediaImage2 {
    enum Type : uint32_t {
        MEDIA_IMAGE_TYPE_UNKNOWN = 0,
        MEDIA_IMAGE_TYPE_YUV,
        MEDIA_IMAGE_TYPE_YUVA,
        MEDIA_IMAGE_TYPE_RGB,
        MEDIA_IMAGE_TYPE_RGBA,
        MEDIA_IMAGE_TYPE_Y,
    };

    enum PlaneIndex : uint32_t {
        Y = 0,
        U = 1,
        V = 2,
        R = 0,
        G = 1,
        B = 2,
        A = 3,
        MAX_NUM_PLANES = 4,
    };

    Type mType;
    uint32_t mNumPlanes;              // number of planes
    uint32_t mWidth;                  // width of largest plane (unpadded, as in nFrameWidth)
    uint32_t mHeight;                 // height of largest plane (unpadded, as in nFrameHeight)
    uint32_t mBitDepth;               // useable bit depth (always MSB)
    uint32_t mBitDepthAllocated;      // bits per component (must be 8 or 16)

    struct __attribute__ ((__packed__)) PlaneInfo {
        uint32_t mOffset;             // offset of first pixel of the plane in bytes
                                      // from buffer offset
        int32_t mColInc;              // column increment in bytes
        int32_t mRowInc;              // row increment in bytes
        uint32_t mHorizSubsampling;   // subsampling compared to the largest plane
        uint32_t mVertSubsampling;    // subsampling compared to the largest plane
    };
    PlaneInfo mPlane[MAX_NUM_PLANES];

    void initFromV1(const MediaImage&); // for internal use only
};

static_assert(sizeof(MediaImage2::PlaneInfo) == 20, "wrong struct size");
static_assert(sizeof(MediaImage2) == 104, "wrong struct size");

/**
 * Aspects of color.
 */

// NOTE: this structure is expected to grow in the future if new color aspects are
// added to codec bitstreams. OMX component should not require a specific nSize
// though could verify that nSize is at least the size of the structure at the
// time of implementation. All new fields will be added at the end of the structure
// ensuring backward compatibility.
struct __attribute__ ((__packed__)) ColorAspects {
    // this is in sync with the range values in graphics.h
    enum Range : uint32_t {
        RangeUnspecified,
        RangeFull,
        RangeLimited,
        RangeOther = 0xff,
    };

    enum Primaries : uint32_t {
        PrimariesUnspecified,
        PrimariesBT709_5,       // Rec.ITU-R BT.709-5 or equivalent
        PrimariesBT470_6M,      // Rec.ITU-R BT.470-6 System M or equivalent
        PrimariesBT601_6_625,   // Rec.ITU-R BT.601-6 625 or equivalent
        PrimariesBT601_6_525,   // Rec.ITU-R BT.601-6 525 or equivalent
        PrimariesGenericFilm,   // Generic Film
        PrimariesBT2020,        // Rec.ITU-R BT.2020 or equivalent
        PrimariesOther = 0xff,
    };

    // this partially in sync with the transfer values in graphics.h prior to the transfers
    // unlikely to be required by Android section
    enum Transfer : uint32_t {
        TransferUnspecified,
        TransferLinear,         // Linear transfer characteristics
        TransferSRGB,           // sRGB or equivalent
        TransferSMPTE170M,      // SMPTE 170M or equivalent (e.g. BT.601/709/2020)
        TransferGamma22,        // Assumed display gamma 2.2
        TransferGamma28,        // Assumed display gamma 2.8
        TransferST2084,         // SMPTE ST 2084 for 10/12/14/16 bit systems
        TransferHLG,            // ARIB STD-B67 hybrid-log-gamma

        // transfers unlikely to be required by Android
        TransferSMPTE240M = 0x40, // SMPTE 240M
        TransferXvYCC,          // IEC 61966-2-4
        TransferBT1361,         // Rec.ITU-R BT.1361 extended gamut
        TransferST428,          // SMPTE ST 428-1
        TransferOther = 0xff,
    };

    enum MatrixCoeffs : uint32_t {
        MatrixUnspecified,
        MatrixBT709_5,          // Rec.ITU-R BT.709-5 or equivalent
        MatrixBT470_6M,         // KR=0.30, KB=0.11 or equivalent
        MatrixBT601_6,          // Rec.ITU-R BT.601-6 625 or equivalent
        MatrixSMPTE240M,        // SMPTE 240M or equivalent
        MatrixBT2020,           // Rec.ITU-R BT.2020 non-constant luminance
        MatrixBT2020Constant,   // Rec.ITU-R BT.2020 constant luminance
        MatrixOther = 0xff,
    };

    // this is in sync with the standard values in graphics.h
    enum Standard : uint32_t {
        StandardUnspecified,
        StandardBT709,                  // PrimariesBT709_5 and MatrixBT709_5
        StandardBT601_625,              // PrimariesBT601_6_625 and MatrixBT601_6
        StandardBT601_625_Unadjusted,   // PrimariesBT601_6_625 and KR=0.222, KB=0.071
        StandardBT601_525,              // PrimariesBT601_6_525 and MatrixBT601_6
        StandardBT601_525_Unadjusted,   // PrimariesBT601_6_525 and MatrixSMPTE240M
        StandardBT2020,                 // PrimariesBT2020 and MatrixBT2020
        StandardBT2020Constant,         // PrimariesBT2020 and MatrixBT2020Constant
        StandardBT470M,                 // PrimariesBT470_6M and MatrixBT470_6M
        StandardFilm,                   // PrimariesGenericFilm and KR=0.253, KB=0.068
        StandardOther = 0xff,
    };

    Range mRange;                // IN/OUT
    Primaries mPrimaries;        // IN/OUT
    Transfer mTransfer;          // IN/OUT
    MatrixCoeffs mMatrixCoeffs;  // IN/OUT
};

static_assert(sizeof(ColorAspects) == 16, "wrong struct size");

/**
 * HDR Metadata.
 */

// HDR Static Metadata Descriptor as defined by CTA-861-3.
struct __attribute__ ((__packed__)) HDRStaticInfo {
    // Static_Metadata_Descriptor_ID
    enum ID : uint8_t {
        kType1 = 0, // Static Metadata Type 1
    } mID;

    struct __attribute__ ((__packed__)) Primaries1 {
        // values are in units of 0.00002
        uint16_t x;
        uint16_t y;
    };

    // Static Metadata Descriptor Type 1
    struct __attribute__ ((__packed__)) Type1 {
        Primaries1 mR; // display primary 0
        Primaries1 mG; // display primary 1
        Primaries1 mB; // display primary 2
        Primaries1 mW; // white point
        uint16_t mMaxDisplayLuminance; // in cd/m^2
        uint16_t mMinDisplayLuminance; // in 0.0001 cd/m^2
        uint16_t mMaxContentLightLevel; // in cd/m^2
        uint16_t mMaxFrameAverageLightLevel; // in cd/m^2
    };

    union {
         Type1 sType1;
    };
};

static_assert(sizeof(HDRStaticInfo::Primaries1) == 4, "wrong struct size");
static_assert(sizeof(HDRStaticInfo::Type1) == 24, "wrong struct size");
static_assert(sizeof(HDRStaticInfo) == 25, "wrong struct size");

#ifdef STRINGIFY_ENUMS

inline static const char *asString(MediaImage::Type i, const char *def = "??") {
    switch (i) {
        case MediaImage::MEDIA_IMAGE_TYPE_UNKNOWN: return "Unknown";
        case MediaImage::MEDIA_IMAGE_TYPE_YUV:     return "YUV";
        default:                                   return def;
    }
}

inline static const char *asString(MediaImage::PlaneIndex i, const char *def = "??") {
    switch (i) {
        case MediaImage::Y: return "Y";
        case MediaImage::U: return "U";
        case MediaImage::V: return "V";
        default:            return def;
    }
}

inline static const char *asString(MediaImage2::Type i, const char *def = "??") {
    switch (i) {
        case MediaImage2::MEDIA_IMAGE_TYPE_UNKNOWN: return "Unknown";
        case MediaImage2::MEDIA_IMAGE_TYPE_YUV:     return "YUV";
        case MediaImage2::MEDIA_IMAGE_TYPE_YUVA:    return "YUVA";
        case MediaImage2::MEDIA_IMAGE_TYPE_RGB:     return "RGB";
        case MediaImage2::MEDIA_IMAGE_TYPE_RGBA:    return "RGBA";
        case MediaImage2::MEDIA_IMAGE_TYPE_Y:       return "Y";
        default:                                    return def;
    }
}

inline static char asChar2(
        MediaImage2::PlaneIndex i, MediaImage2::Type j, char def = '?') {
    const char *planes = asString(j, NULL);
    // handle unknown values
    if (j == MediaImage2::MEDIA_IMAGE_TYPE_UNKNOWN || planes == NULL || i >= strlen(planes)) {
        return def;
    }
    return planes[i];
}

inline static const char *asString(ColorAspects::Range i, const char *def = "??") {
    switch (i) {
        case ColorAspects::RangeUnspecified: return "Unspecified";
        case ColorAspects::RangeFull:        return "Full";
        case ColorAspects::RangeLimited:     return "Limited";
        case ColorAspects::RangeOther:       return "Other";
        default:                             return def;
    }
}

inline static const char *asString(ColorAspects::Primaries i, const char *def = "??") {
    switch (i) {
        case ColorAspects::PrimariesUnspecified: return "Unspecified";
        case ColorAspects::PrimariesBT709_5:     return "BT709_5";
        case ColorAspects::PrimariesBT470_6M:    return "BT470_6M";
        case ColorAspects::PrimariesBT601_6_625: return "BT601_6_625";
        case ColorAspects::PrimariesBT601_6_525: return "BT601_6_525";
        case ColorAspects::PrimariesGenericFilm: return "GenericFilm";
        case ColorAspects::PrimariesBT2020:      return "BT2020";
        case ColorAspects::PrimariesOther:       return "Other";
        default:                                 return def;
    }
}

inline static const char *asString(ColorAspects::Transfer i, const char *def = "??") {
    switch (i) {
        case ColorAspects::TransferUnspecified: return "Unspecified";
        case ColorAspects::TransferLinear:      return "Linear";
        case ColorAspects::TransferSRGB:        return "SRGB";
        case ColorAspects::TransferSMPTE170M:   return "SMPTE170M";
        case ColorAspects::TransferGamma22:     return "Gamma22";
        case ColorAspects::TransferGamma28:     return "Gamma28";
        case ColorAspects::TransferST2084:      return "ST2084";
        case ColorAspects::TransferHLG:         return "HLG";
        case ColorAspects::TransferSMPTE240M:   return "SMPTE240M";
        case ColorAspects::TransferXvYCC:       return "XvYCC";
        case ColorAspects::TransferBT1361:      return "BT1361";
        case ColorAspects::TransferST428:       return "ST428";
        case ColorAspects::TransferOther:       return "Other";
        default:                                return def;
    }
}

inline static const char *asString(ColorAspects::MatrixCoeffs i, const char *def = "??") {
    switch (i) {
        case ColorAspects::MatrixUnspecified:    return "Unspecified";
        case ColorAspects::MatrixBT709_5:        return "BT709_5";
        case ColorAspects::MatrixBT470_6M:       return "BT470_6M";
        case ColorAspects::MatrixBT601_6:        return "BT601_6";
        case ColorAspects::MatrixSMPTE240M:      return "SMPTE240M";
        case ColorAspects::MatrixBT2020:         return "BT2020";
        case ColorAspects::MatrixBT2020Constant: return "BT2020Constant";
        case ColorAspects::MatrixOther:          return "Other";
        default:                                 return def;
    }
}

inline static const char *asString(ColorAspects::Standard i, const char *def = "??") {
    switch (i) {
        case ColorAspects::StandardUnspecified:          return "Unspecified";
        case ColorAspects::StandardBT709:                return "BT709";
        case ColorAspects::StandardBT601_625:            return "BT601_625";
        case ColorAspects::StandardBT601_625_Unadjusted: return "BT601_625_Unadjusted";
        case ColorAspects::StandardBT601_525:            return "BT601_525";
        case ColorAspects::StandardBT601_525_Unadjusted: return "BT601_525_Unadjusted";
        case ColorAspects::StandardBT2020:               return "BT2020";
        case ColorAspects::StandardBT2020Constant:       return "BT2020Constant";
        case ColorAspects::StandardBT470M:               return "BT470M";
        case ColorAspects::StandardFilm:                 return "Film";
        case ColorAspects::StandardOther:                return "Other";
        default:                                         return def;
    }
}

#endif

}  // namespace android

#endif  // VIDEO_API_H_