Home | History | Annotate | Download | only in hardware
      1 /*
      2  * Copyright (C) 2016 The Android Open Source Project
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 #ifndef VIDEO_API_H_
     18 
     19 #define VIDEO_API_H_
     20 
     21 namespace android {
     22 
     23 /**
     24  * Structure describing a media image (frame)
     25  * Currently only supporting YUV
     26  * @deprecated. Use MediaImage2 instead
     27  */
     28 struct MediaImage {
     29     enum Type {
     30         MEDIA_IMAGE_TYPE_UNKNOWN = 0,
     31         MEDIA_IMAGE_TYPE_YUV,
     32     };
     33 
     34     enum PlaneIndex {
     35         Y = 0,
     36         U,
     37         V,
     38         MAX_NUM_PLANES
     39     };
     40 
     41     Type mType;
     42     uint32_t mNumPlanes;              // number of planes
     43     uint32_t mWidth;                  // width of largest plane (unpadded, as in nFrameWidth)
     44     uint32_t mHeight;                 // height of largest plane (unpadded, as in nFrameHeight)
     45     uint32_t mBitDepth;               // useable bit depth
     46     struct PlaneInfo {
     47         uint32_t mOffset;             // offset of first pixel of the plane in bytes
     48                                       // from buffer offset
     49         uint32_t mColInc;             // column increment in bytes
     50         uint32_t mRowInc;             // row increment in bytes
     51         uint32_t mHorizSubsampling;   // subsampling compared to the largest plane
     52         uint32_t mVertSubsampling;    // subsampling compared to the largest plane
     53     };
     54     PlaneInfo mPlane[MAX_NUM_PLANES];
     55 };
     56 
     57 /**
     58  * Structure describing a media image (frame)
     59  */
     60 struct __attribute__ ((__packed__)) MediaImage2 {
     61     enum Type : uint32_t {
     62         MEDIA_IMAGE_TYPE_UNKNOWN = 0,
     63         MEDIA_IMAGE_TYPE_YUV,
     64         MEDIA_IMAGE_TYPE_YUVA,
     65         MEDIA_IMAGE_TYPE_RGB,
     66         MEDIA_IMAGE_TYPE_RGBA,
     67         MEDIA_IMAGE_TYPE_Y,
     68     };
     69 
     70     enum PlaneIndex : uint32_t {
     71         Y = 0,
     72         U = 1,
     73         V = 2,
     74         R = 0,
     75         G = 1,
     76         B = 2,
     77         A = 3,
     78         MAX_NUM_PLANES = 4,
     79     };
     80 
     81     Type mType;
     82     uint32_t mNumPlanes;              // number of planes
     83     uint32_t mWidth;                  // width of largest plane (unpadded, as in nFrameWidth)
     84     uint32_t mHeight;                 // height of largest plane (unpadded, as in nFrameHeight)
     85     uint32_t mBitDepth;               // useable bit depth (always MSB)
     86     uint32_t mBitDepthAllocated;      // bits per component (must be 8 or 16)
     87 
     88     struct __attribute__ ((__packed__)) PlaneInfo {
     89         uint32_t mOffset;             // offset of first pixel of the plane in bytes
     90                                       // from buffer offset
     91         int32_t mColInc;              // column increment in bytes
     92         int32_t mRowInc;              // row increment in bytes
     93         uint32_t mHorizSubsampling;   // subsampling compared to the largest plane
     94         uint32_t mVertSubsampling;    // subsampling compared to the largest plane
     95     };
     96     PlaneInfo mPlane[MAX_NUM_PLANES];
     97 
     98     void initFromV1(const MediaImage&); // for internal use only
     99 };
    100 
    101 static_assert(sizeof(MediaImage2::PlaneInfo) == 20, "wrong struct size");
    102 static_assert(sizeof(MediaImage2) == 104, "wrong struct size");
    103 
    104 /**
    105  * Aspects of color.
    106  */
    107 
    108 // NOTE: this structure is expected to grow in the future if new color aspects are
    109 // added to codec bitstreams. OMX component should not require a specific nSize
    110 // though could verify that nSize is at least the size of the structure at the
    111 // time of implementation. All new fields will be added at the end of the structure
    112 // ensuring backward compatibility.
    113 struct __attribute__ ((__packed__)) ColorAspects {
    114     // this is in sync with the range values in graphics.h
    115     enum Range : uint32_t {
    116         RangeUnspecified,
    117         RangeFull,
    118         RangeLimited,
    119         RangeOther = 0xff,
    120     };
    121 
    122     enum Primaries : uint32_t {
    123         PrimariesUnspecified,
    124         PrimariesBT709_5,       // Rec.ITU-R BT.709-5 or equivalent
    125         PrimariesBT470_6M,      // Rec.ITU-R BT.470-6 System M or equivalent
    126         PrimariesBT601_6_625,   // Rec.ITU-R BT.601-6 625 or equivalent
    127         PrimariesBT601_6_525,   // Rec.ITU-R BT.601-6 525 or equivalent
    128         PrimariesGenericFilm,   // Generic Film
    129         PrimariesBT2020,        // Rec.ITU-R BT.2020 or equivalent
    130         PrimariesOther = 0xff,
    131     };
    132 
    133     // this partially in sync with the transfer values in graphics.h prior to the transfers
    134     // unlikely to be required by Android section
    135     enum Transfer : uint32_t {
    136         TransferUnspecified,
    137         TransferLinear,         // Linear transfer characteristics
    138         TransferSRGB,           // sRGB or equivalent
    139         TransferSMPTE170M,      // SMPTE 170M or equivalent (e.g. BT.601/709/2020)
    140         TransferGamma22,        // Assumed display gamma 2.2
    141         TransferGamma28,        // Assumed display gamma 2.8
    142         TransferST2084,         // SMPTE ST 2084 for 10/12/14/16 bit systems
    143         TransferHLG,            // ARIB STD-B67 hybrid-log-gamma
    144 
    145         // transfers unlikely to be required by Android
    146         TransferSMPTE240M = 0x40, // SMPTE 240M
    147         TransferXvYCC,          // IEC 61966-2-4
    148         TransferBT1361,         // Rec.ITU-R BT.1361 extended gamut
    149         TransferST428,          // SMPTE ST 428-1
    150         TransferOther = 0xff,
    151     };
    152 
    153     enum MatrixCoeffs : uint32_t {
    154         MatrixUnspecified,
    155         MatrixBT709_5,          // Rec.ITU-R BT.709-5 or equivalent
    156         MatrixBT470_6M,         // KR=0.30, KB=0.11 or equivalent
    157         MatrixBT601_6,          // Rec.ITU-R BT.601-6 625 or equivalent
    158         MatrixSMPTE240M,        // SMPTE 240M or equivalent
    159         MatrixBT2020,           // Rec.ITU-R BT.2020 non-constant luminance
    160         MatrixBT2020Constant,   // Rec.ITU-R BT.2020 constant luminance
    161         MatrixOther = 0xff,
    162     };
    163 
    164     // this is in sync with the standard values in graphics.h
    165     enum Standard : uint32_t {
    166         StandardUnspecified,
    167         StandardBT709,                  // PrimariesBT709_5 and MatrixBT709_5
    168         StandardBT601_625,              // PrimariesBT601_6_625 and MatrixBT601_6
    169         StandardBT601_625_Unadjusted,   // PrimariesBT601_6_625 and KR=0.222, KB=0.071
    170         StandardBT601_525,              // PrimariesBT601_6_525 and MatrixBT601_6
    171         StandardBT601_525_Unadjusted,   // PrimariesBT601_6_525 and MatrixSMPTE240M
    172         StandardBT2020,                 // PrimariesBT2020 and MatrixBT2020
    173         StandardBT2020Constant,         // PrimariesBT2020 and MatrixBT2020Constant
    174         StandardBT470M,                 // PrimariesBT470_6M and MatrixBT470_6M
    175         StandardFilm,                   // PrimariesGenericFilm and KR=0.253, KB=0.068
    176         StandardOther = 0xff,
    177     };
    178 
    179     Range mRange;                // IN/OUT
    180     Primaries mPrimaries;        // IN/OUT
    181     Transfer mTransfer;          // IN/OUT
    182     MatrixCoeffs mMatrixCoeffs;  // IN/OUT
    183 };
    184 
    185 static_assert(sizeof(ColorAspects) == 16, "wrong struct size");
    186 
    187 /**
    188  * HDR Metadata.
    189  */
    190 
    191 // HDR Static Metadata Descriptor as defined by CTA-861-3.
    192 struct __attribute__ ((__packed__)) HDRStaticInfo {
    193     // Static_Metadata_Descriptor_ID
    194     enum ID : uint8_t {
    195         kType1 = 0, // Static Metadata Type 1
    196     } mID;
    197 
    198     struct __attribute__ ((__packed__)) Primaries1 {
    199         // values are in units of 0.00002
    200         uint16_t x;
    201         uint16_t y;
    202     };
    203 
    204     // Static Metadata Descriptor Type 1
    205     struct __attribute__ ((__packed__)) Type1 {
    206         Primaries1 mR; // display primary 0
    207         Primaries1 mG; // display primary 1
    208         Primaries1 mB; // display primary 2
    209         Primaries1 mW; // white point
    210         uint16_t mMaxDisplayLuminance; // in cd/m^2
    211         uint16_t mMinDisplayLuminance; // in 0.0001 cd/m^2
    212         uint16_t mMaxContentLightLevel; // in cd/m^2
    213         uint16_t mMaxFrameAverageLightLevel; // in cd/m^2
    214     };
    215 
    216     union {
    217          Type1 sType1;
    218     };
    219 };
    220 
    221 static_assert(sizeof(HDRStaticInfo::Primaries1) == 4, "wrong struct size");
    222 static_assert(sizeof(HDRStaticInfo::Type1) == 24, "wrong struct size");
    223 static_assert(sizeof(HDRStaticInfo) == 25, "wrong struct size");
    224 
    225 #ifdef STRINGIFY_ENUMS
    226 
    227 inline static const char *asString(MediaImage::Type i, const char *def = "??") {
    228     switch (i) {
    229         case MediaImage::MEDIA_IMAGE_TYPE_UNKNOWN: return "Unknown";
    230         case MediaImage::MEDIA_IMAGE_TYPE_YUV:     return "YUV";
    231         default:                                   return def;
    232     }
    233 }
    234 
    235 inline static const char *asString(MediaImage::PlaneIndex i, const char *def = "??") {
    236     switch (i) {
    237         case MediaImage::Y: return "Y";
    238         case MediaImage::U: return "U";
    239         case MediaImage::V: return "V";
    240         default:            return def;
    241     }
    242 }
    243 
    244 inline static const char *asString(MediaImage2::Type i, const char *def = "??") {
    245     switch (i) {
    246         case MediaImage2::MEDIA_IMAGE_TYPE_UNKNOWN: return "Unknown";
    247         case MediaImage2::MEDIA_IMAGE_TYPE_YUV:     return "YUV";
    248         case MediaImage2::MEDIA_IMAGE_TYPE_YUVA:    return "YUVA";
    249         case MediaImage2::MEDIA_IMAGE_TYPE_RGB:     return "RGB";
    250         case MediaImage2::MEDIA_IMAGE_TYPE_RGBA:    return "RGBA";
    251         case MediaImage2::MEDIA_IMAGE_TYPE_Y:       return "Y";
    252         default:                                    return def;
    253     }
    254 }
    255 
    256 inline static char asChar2(
    257         MediaImage2::PlaneIndex i, MediaImage2::Type j, char def = '?') {
    258     const char *planes = asString(j, NULL);
    259     // handle unknown values
    260     if (j == MediaImage2::MEDIA_IMAGE_TYPE_UNKNOWN || planes == NULL || i >= strlen(planes)) {
    261         return def;
    262     }
    263     return planes[i];
    264 }
    265 
    266 inline static const char *asString(ColorAspects::Range i, const char *def = "??") {
    267     switch (i) {
    268         case ColorAspects::RangeUnspecified: return "Unspecified";
    269         case ColorAspects::RangeFull:        return "Full";
    270         case ColorAspects::RangeLimited:     return "Limited";
    271         case ColorAspects::RangeOther:       return "Other";
    272         default:                             return def;
    273     }
    274 }
    275 
    276 inline static const char *asString(ColorAspects::Primaries i, const char *def = "??") {
    277     switch (i) {
    278         case ColorAspects::PrimariesUnspecified: return "Unspecified";
    279         case ColorAspects::PrimariesBT709_5:     return "BT709_5";
    280         case ColorAspects::PrimariesBT470_6M:    return "BT470_6M";
    281         case ColorAspects::PrimariesBT601_6_625: return "BT601_6_625";
    282         case ColorAspects::PrimariesBT601_6_525: return "BT601_6_525";
    283         case ColorAspects::PrimariesGenericFilm: return "GenericFilm";
    284         case ColorAspects::PrimariesBT2020:      return "BT2020";
    285         case ColorAspects::PrimariesOther:       return "Other";
    286         default:                                 return def;
    287     }
    288 }
    289 
    290 inline static const char *asString(ColorAspects::Transfer i, const char *def = "??") {
    291     switch (i) {
    292         case ColorAspects::TransferUnspecified: return "Unspecified";
    293         case ColorAspects::TransferLinear:      return "Linear";
    294         case ColorAspects::TransferSRGB:        return "SRGB";
    295         case ColorAspects::TransferSMPTE170M:   return "SMPTE170M";
    296         case ColorAspects::TransferGamma22:     return "Gamma22";
    297         case ColorAspects::TransferGamma28:     return "Gamma28";
    298         case ColorAspects::TransferST2084:      return "ST2084";
    299         case ColorAspects::TransferHLG:         return "HLG";
    300         case ColorAspects::TransferSMPTE240M:   return "SMPTE240M";
    301         case ColorAspects::TransferXvYCC:       return "XvYCC";
    302         case ColorAspects::TransferBT1361:      return "BT1361";
    303         case ColorAspects::TransferST428:       return "ST428";
    304         case ColorAspects::TransferOther:       return "Other";
    305         default:                                return def;
    306     }
    307 }
    308 
    309 inline static const char *asString(ColorAspects::MatrixCoeffs i, const char *def = "??") {
    310     switch (i) {
    311         case ColorAspects::MatrixUnspecified:    return "Unspecified";
    312         case ColorAspects::MatrixBT709_5:        return "BT709_5";
    313         case ColorAspects::MatrixBT470_6M:       return "BT470_6M";
    314         case ColorAspects::MatrixBT601_6:        return "BT601_6";
    315         case ColorAspects::MatrixSMPTE240M:      return "SMPTE240M";
    316         case ColorAspects::MatrixBT2020:         return "BT2020";
    317         case ColorAspects::MatrixBT2020Constant: return "BT2020Constant";
    318         case ColorAspects::MatrixOther:          return "Other";
    319         default:                                 return def;
    320     }
    321 }
    322 
    323 inline static const char *asString(ColorAspects::Standard i, const char *def = "??") {
    324     switch (i) {
    325         case ColorAspects::StandardUnspecified:          return "Unspecified";
    326         case ColorAspects::StandardBT709:                return "BT709";
    327         case ColorAspects::StandardBT601_625:            return "BT601_625";
    328         case ColorAspects::StandardBT601_625_Unadjusted: return "BT601_625_Unadjusted";
    329         case ColorAspects::StandardBT601_525:            return "BT601_525";
    330         case ColorAspects::StandardBT601_525_Unadjusted: return "BT601_525_Unadjusted";
    331         case ColorAspects::StandardBT2020:               return "BT2020";
    332         case ColorAspects::StandardBT2020Constant:       return "BT2020Constant";
    333         case ColorAspects::StandardBT470M:               return "BT470M";
    334         case ColorAspects::StandardFilm:                 return "Film";
    335         case ColorAspects::StandardOther:                return "Other";
    336         default:                                         return def;
    337     }
    338 }
    339 
    340 #endif
    341 
    342 }  // namespace android
    343 
    344 #endif  // VIDEO_API_H_
    345