VideoAPI.h revision b4e0bce8404071958366573c2029a205336b6de2 
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
21namespace android {
22
23/**
24 * Structure describing a media image (frame)
25 * Currently only supporting YUV
26 * @deprecated. Use MediaImage2 instead
27 */
28struct 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 */
60struct __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
101static_assert(sizeof(MediaImage2::PlaneInfo) == 20, "wrong struct size");
102static_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.
113struct __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
185static_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.
192struct __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
221static_assert(sizeof(HDRStaticInfo::Primaries1) == 4, "wrong struct size");
222static_assert(sizeof(HDRStaticInfo::Type1) == 24, "wrong struct size");
223static_assert(sizeof(HDRStaticInfo) == 25, "wrong struct size");
224
225#ifdef STRINGIFY_ENUMS
226
227inline 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
235inline 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
244inline 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
256inline 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
266inline 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
276inline 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
290inline 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
309inline 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
323inline 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