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__, aligned(alignof(uint32_t)))) 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 PrimariesRP431, // SMPTE RP 431-2 (DCI P3) 131 PrimariesEG432, // SMPTE EG 432-1 (Display P3) 132 PrimariesOther = 0xff, 133 }; 134 135 // this partially in sync with the transfer values in graphics.h prior to the transfers 136 // unlikely to be required by Android section 137 enum Transfer : uint32_t { 138 TransferUnspecified, 139 TransferLinear, // Linear transfer characteristics 140 TransferSRGB, // sRGB or equivalent 141 TransferSMPTE170M, // SMPTE 170M or equivalent (e.g. BT.601/709/2020) 142 TransferGamma22, // Assumed display gamma 2.2 143 TransferGamma28, // Assumed display gamma 2.8 144 TransferST2084, // SMPTE ST 2084 for 10/12/14/16 bit systems 145 TransferHLG, // ARIB STD-B67 hybrid-log-gamma 146 147 // transfers unlikely to be required by Android 148 TransferSMPTE240M = 0x40, // SMPTE 240M 149 TransferXvYCC, // IEC 61966-2-4 150 TransferBT1361, // Rec.ITU-R BT.1361 extended gamut 151 TransferST428, // SMPTE ST 428-1 152 TransferOther = 0xff, 153 }; 154 155 enum MatrixCoeffs : uint32_t { 156 MatrixUnspecified, 157 MatrixBT709_5, // Rec.ITU-R BT.709-5 or equivalent 158 MatrixBT470_6M, // KR=0.30, KB=0.11 or equivalent 159 MatrixBT601_6, // Rec.ITU-R BT.601-6 625 or equivalent 160 MatrixSMPTE240M, // SMPTE 240M or equivalent 161 MatrixBT2020, // Rec.ITU-R BT.2020 non-constant luminance 162 MatrixBT2020Constant, // Rec.ITU-R BT.2020 constant luminance 163 MatrixOther = 0xff, 164 }; 165 166 // this is in sync with the standard values in graphics.h 167 enum Standard : uint32_t { 168 StandardUnspecified, 169 StandardBT709, // PrimariesBT709_5 and MatrixBT709_5 170 StandardBT601_625, // PrimariesBT601_6_625 and MatrixBT601_6 171 StandardBT601_625_Unadjusted, // PrimariesBT601_6_625 and KR=0.222, KB=0.071 172 StandardBT601_525, // PrimariesBT601_6_525 and MatrixBT601_6 173 StandardBT601_525_Unadjusted, // PrimariesBT601_6_525 and MatrixSMPTE240M 174 StandardBT2020, // PrimariesBT2020 and MatrixBT2020 175 StandardBT2020Constant, // PrimariesBT2020 and MatrixBT2020Constant 176 StandardBT470M, // PrimariesBT470_6M and MatrixBT470_6M 177 StandardFilm, // PrimariesGenericFilm and KR=0.253, KB=0.068 178 StandardDisplayP3, // PrimariesEG432 and MatrixBT601_6 179 // StandardAdobeRGB, // for placeholder only (not used by media) 180 StandardOther = 0xff, 181 }; 182 183 Range mRange; // IN/OUT 184 Primaries mPrimaries; // IN/OUT 185 Transfer mTransfer; // IN/OUT 186 MatrixCoeffs mMatrixCoeffs; // IN/OUT 187 }; 188 189 static_assert(sizeof(ColorAspects) == 16, "wrong struct size"); 190 191 /** 192 * HDR Metadata. 193 */ 194 195 // HDR Static Metadata Descriptor as defined by CTA-861-3. 196 struct __attribute__ ((__packed__)) HDRStaticInfo { 197 // Static_Metadata_Descriptor_ID 198 enum ID : uint8_t { 199 kType1 = 0, // Static Metadata Type 1 200 } mID; 201 202 struct __attribute__ ((__packed__)) Primaries1 { 203 // values are in units of 0.00002 204 uint16_t x; 205 uint16_t y; 206 }; 207 208 // Static Metadata Descriptor Type 1 209 struct __attribute__ ((__packed__)) Type1 { 210 Primaries1 mR; // display primary 0 211 Primaries1 mG; // display primary 1 212 Primaries1 mB; // display primary 2 213 Primaries1 mW; // white point 214 uint16_t mMaxDisplayLuminance; // in cd/m^2 215 uint16_t mMinDisplayLuminance; // in 0.0001 cd/m^2 216 uint16_t mMaxContentLightLevel; // in cd/m^2 217 uint16_t mMaxFrameAverageLightLevel; // in cd/m^2 218 }; 219 220 union { 221 Type1 sType1; 222 }; 223 }; 224 225 static_assert(sizeof(HDRStaticInfo::Primaries1) == 4, "wrong struct size"); 226 static_assert(sizeof(HDRStaticInfo::Type1) == 24, "wrong struct size"); 227 static_assert(sizeof(HDRStaticInfo) == 25, "wrong struct size"); 228 229 #ifdef STRINGIFY_ENUMS 230 231 inline static const char *asString(MediaImage::Type i, const char *def = "??") { 232 switch (i) { 233 case MediaImage::MEDIA_IMAGE_TYPE_UNKNOWN: return "Unknown"; 234 case MediaImage::MEDIA_IMAGE_TYPE_YUV: return "YUV"; 235 default: return def; 236 } 237 } 238 239 inline static const char *asString(MediaImage::PlaneIndex i, const char *def = "??") { 240 switch (i) { 241 case MediaImage::Y: return "Y"; 242 case MediaImage::U: return "U"; 243 case MediaImage::V: return "V"; 244 default: return def; 245 } 246 } 247 248 inline static const char *asString(MediaImage2::Type i, const char *def = "??") { 249 switch (i) { 250 case MediaImage2::MEDIA_IMAGE_TYPE_UNKNOWN: return "Unknown"; 251 case MediaImage2::MEDIA_IMAGE_TYPE_YUV: return "YUV"; 252 case MediaImage2::MEDIA_IMAGE_TYPE_YUVA: return "YUVA"; 253 case MediaImage2::MEDIA_IMAGE_TYPE_RGB: return "RGB"; 254 case MediaImage2::MEDIA_IMAGE_TYPE_RGBA: return "RGBA"; 255 case MediaImage2::MEDIA_IMAGE_TYPE_Y: return "Y"; 256 default: return def; 257 } 258 } 259 260 inline static char asChar2( 261 MediaImage2::PlaneIndex i, MediaImage2::Type j, char def = '?') { 262 const char *planes = asString(j, NULL); 263 // handle unknown values 264 if (j == MediaImage2::MEDIA_IMAGE_TYPE_UNKNOWN || planes == NULL || i >= strlen(planes)) { 265 return def; 266 } 267 return planes[i]; 268 } 269 270 inline static const char *asString(ColorAspects::Range i, const char *def = "??") { 271 switch (i) { 272 case ColorAspects::RangeUnspecified: return "Unspecified"; 273 case ColorAspects::RangeFull: return "Full"; 274 case ColorAspects::RangeLimited: return "Limited"; 275 case ColorAspects::RangeOther: return "Other"; 276 default: return def; 277 } 278 } 279 280 inline static const char *asString(ColorAspects::Primaries i, const char *def = "??") { 281 switch (i) { 282 case ColorAspects::PrimariesUnspecified: return "Unspecified"; 283 case ColorAspects::PrimariesBT709_5: return "BT709_5"; 284 case ColorAspects::PrimariesBT470_6M: return "BT470_6M"; 285 case ColorAspects::PrimariesBT601_6_625: return "BT601_6_625"; 286 case ColorAspects::PrimariesBT601_6_525: return "BT601_6_525"; 287 case ColorAspects::PrimariesGenericFilm: return "GenericFilm"; 288 case ColorAspects::PrimariesBT2020: return "BT2020"; 289 case ColorAspects::PrimariesRP431: return "RP431"; 290 case ColorAspects::PrimariesEG432: return "EG432"; 291 case ColorAspects::PrimariesOther: return "Other"; 292 default: return def; 293 } 294 } 295 296 inline static const char *asString(ColorAspects::Transfer i, const char *def = "??") { 297 switch (i) { 298 case ColorAspects::TransferUnspecified: return "Unspecified"; 299 case ColorAspects::TransferLinear: return "Linear"; 300 case ColorAspects::TransferSRGB: return "SRGB"; 301 case ColorAspects::TransferSMPTE170M: return "SMPTE170M"; 302 case ColorAspects::TransferGamma22: return "Gamma22"; 303 case ColorAspects::TransferGamma28: return "Gamma28"; 304 case ColorAspects::TransferST2084: return "ST2084"; 305 case ColorAspects::TransferHLG: return "HLG"; 306 case ColorAspects::TransferSMPTE240M: return "SMPTE240M"; 307 case ColorAspects::TransferXvYCC: return "XvYCC"; 308 case ColorAspects::TransferBT1361: return "BT1361"; 309 case ColorAspects::TransferST428: return "ST428"; 310 case ColorAspects::TransferOther: return "Other"; 311 default: return def; 312 } 313 } 314 315 inline static const char *asString(ColorAspects::MatrixCoeffs i, const char *def = "??") { 316 switch (i) { 317 case ColorAspects::MatrixUnspecified: return "Unspecified"; 318 case ColorAspects::MatrixBT709_5: return "BT709_5"; 319 case ColorAspects::MatrixBT470_6M: return "BT470_6M"; 320 case ColorAspects::MatrixBT601_6: return "BT601_6"; 321 case ColorAspects::MatrixSMPTE240M: return "SMPTE240M"; 322 case ColorAspects::MatrixBT2020: return "BT2020"; 323 case ColorAspects::MatrixBT2020Constant: return "BT2020Constant"; 324 case ColorAspects::MatrixOther: return "Other"; 325 default: return def; 326 } 327 } 328 329 inline static const char *asString(ColorAspects::Standard i, const char *def = "??") { 330 switch (i) { 331 case ColorAspects::StandardUnspecified: return "Unspecified"; 332 case ColorAspects::StandardBT709: return "BT709"; 333 case ColorAspects::StandardBT601_625: return "BT601_625"; 334 case ColorAspects::StandardBT601_625_Unadjusted: return "BT601_625_Unadjusted"; 335 case ColorAspects::StandardBT601_525: return "BT601_525"; 336 case ColorAspects::StandardBT601_525_Unadjusted: return "BT601_525_Unadjusted"; 337 case ColorAspects::StandardBT2020: return "BT2020"; 338 case ColorAspects::StandardBT2020Constant: return "BT2020Constant"; 339 case ColorAspects::StandardBT470M: return "BT470M"; 340 case ColorAspects::StandardFilm: return "Film"; 341 case ColorAspects::StandardDisplayP3: return "DisplayP3"; 342 // case ColorAspects::StandardAdobeRGB: return "AdobeRGB"; 343 case ColorAspects::StandardOther: return "Other"; 344 default: return def; 345 } 346 } 347 348 #endif 349 350 } // namespace android 351 352 #endif // VIDEO_API_H_ 353