1 /*
2  * Copyright 2014, 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 MEDIA_CODEC_INFO_H_
18 
19 #define MEDIA_CODEC_INFO_H_
20 
21 #include <android-base/macros.h>
22 #include <binder/Parcel.h>
23 #include <media/stagefright/foundation/ABase.h>
24 #include <media/stagefright/foundation/AString.h>
25 
26 #include <sys/types.h>
27 #include <utils/Errors.h>
28 #include <utils/KeyedVector.h>
29 #include <utils/RefBase.h>
30 #include <utils/Vector.h>
31 #include <utils/StrongPointer.h>
32 
33 #include <type_traits>
34 
35 namespace android {
36 
37 struct AMessage;
38 class Parcel;
39 
40 typedef KeyedVector<AString, AString> CodecSettings;
41 
42 struct MediaCodecInfoWriter;
43 struct MediaCodecListWriter;
44 
45 struct MediaCodecInfo : public RefBase {
46     struct ProfileLevel {
47         uint32_t mProfile;
48         uint32_t mLevel;
49         bool operator <(const ProfileLevel &o) const {
50             return mProfile < o.mProfile || (mProfile == o.mProfile && mLevel < o.mLevel);
51         }
52     };
53 
54     struct CapabilitiesWriter;
55 
56     enum Attributes : int32_t {
57         // attribute flags
58         kFlagIsEncoder = 1 << 0,
59         kFlagIsVendor = 1 << 1,
60         kFlagIsSoftwareOnly = 1 << 2,
61         kFlagIsHardwareAccelerated = 1 << 3,
62     };
63 
64     struct Capabilities : public RefBase {
65         constexpr static char FEATURE_ADAPTIVE_PLAYBACK[] = "feature-adaptive-playback";
66         constexpr static char FEATURE_DYNAMIC_TIMESTAMP[] = "feature-dynamic-timestamp";
67         constexpr static char FEATURE_FRAME_PARSING[] = "feature-frame-parsing";
68         constexpr static char FEATURE_INTRA_REFRESH[] = "feature-frame-parsing";
69         constexpr static char FEATURE_MULTIPLE_FRAMES[] = "feature-multiple-frames";
70         constexpr static char FEATURE_SECURE_PLAYBACK[] = "feature-secure-playback";
71         constexpr static char FEATURE_TUNNELED_PLAYBACK[] = "feature-tunneled-playback";
72 
73         /**
74          * Returns the supported levels for each supported profile in a target array.
75          *
76          * @param profileLevels target array for the profile levels.
77          */
78         void getSupportedProfileLevels(Vector<ProfileLevel> *profileLevels) const;
79 
80         /**
81          * Returns the supported color formats in a target array. Only used for video/image
82          * components.
83          *
84          * @param colorFormats target array for the color formats.
85          */
86         void getSupportedColorFormats(Vector<uint32_t> *colorFormats) const;
87 
88         /**
89          * Returns metadata associated with this codec capability.
90          *
91          * This contains:
92          * - features,
93          * - performance data.
94          *
95          * TODO: expose this as separate API-s and wrap here.
96          */
97         const sp<AMessage> getDetails() const;
98 
99     protected:
100         Vector<ProfileLevel> mProfileLevels;
101         SortedVector<ProfileLevel> mProfileLevelsSorted;
102         Vector<uint32_t> mColorFormats;
103         SortedVector<uint32_t> mColorFormatsSorted;
104         sp<AMessage> mDetails;
105 
106         Capabilities();
107 
108     private:
109         // read object from parcel even if object creation fails
110         static sp<Capabilities> FromParcel(const Parcel &parcel);
111         status_t writeToParcel(Parcel *parcel) const;
112 
113         DISALLOW_COPY_AND_ASSIGN(Capabilities);
114 
115         friend struct MediaCodecInfo;
116         friend struct MediaCodecInfoWriter;
117         friend struct CapabilitiesWriter;
118     };
119 
120     /**
121      * This class is used for modifying information inside a `Capabilities`
122      * object. An object of type `CapabilitiesWriter` can be obtained by calling
123      * `MediaCodecInfoWriter::addMediaType()`.
124      */
125     struct CapabilitiesWriter {
126         /**
127          * Add a key-value pair to the list of details. If the key already
128          * exists, the old value will be replaced.
129          *
130          * A pair added by this function will be accessible by
131          * `Capabilities::getDetails()`. Call `AMessage::getString()` with the
132          * same key to retrieve the value.
133          *
134          * @param key The key.
135          * @param value The string value.
136          */
137         void addDetail(const char* key, const char* value);
138         /**
139          * Add a key-value pair to the list of details. If the key already
140          * exists, the old value will be replaced.
141          *
142          * A pair added by this function will be accessible by
143          * `Capabilities::getDetails()`. Call `AMessage::getInt32()` with the
144          * same key to retrieve the value.
145          *
146          * @param key The key.
147          * @param value The `int32_t` value.
148          */
149         void addDetail(const char* key, int32_t value);
150         /**
151          * Removes a key-value pair from the list of details. If the key is not
152          * present, this call does nothing.
153          *
154          * @param key The key.
155          */
156         void removeDetail(const char* key);
157         /**
158          * Add a profile-level pair. If this profile-level pair already exists,
159          * it will be ignored.
160          *
161          * @param profile The "profile" component.
162          * @param level The "level" component.
163          */
164         void addProfileLevel(uint32_t profile, uint32_t level);
165         /**
166          * Add a color format. If this color format already exists, it will be
167          * ignored.
168          *
169          * @param format The color format.
170          */
171         void addColorFormat(uint32_t format);
172 
173     private:
174         /**
175          * The associated `Capabilities` object.
176          */
177         Capabilities* mCap;
178         /**
179          * Construct a writer for the given `Capabilities` object.
180          *
181          * @param cap The `Capabilities` object to be written to.
182          */
183         CapabilitiesWriter(Capabilities* cap);
184 
185         friend MediaCodecInfoWriter;
186     };
187 
isEncoderMediaCodecInfo188     inline bool isEncoder() const {
189         return getAttributes() & kFlagIsEncoder;
190     }
191 
192     Attributes getAttributes() const;
193     void getSupportedMediaTypes(Vector<AString> *mediaTypes) const;
194     const sp<Capabilities> getCapabilitiesFor(const char *mediaType) const;
195     const char *getCodecName() const;
196 
197     /**
198      * Returns a vector containing alternate names for the codec.
199      *
200      * \param aliases the destination array for the aliases. This is cleared.
201      *
202      * Multiple codecs may share alternate names as long as their supported media types are
203      * distinct; however, these will result in different aliases for the MediaCodec user as
204      * the canonical codec has to be resolved without knowing the media type in
205      * MediaCodec::CreateByComponentName.
206      */
207     void getAliases(Vector<AString> *aliases) const;
208 
209     /**
210      * Return the name of the service that hosts the codec. This value is not
211      * visible at the Java level.
212      *
213      * Currently, this is the "instance name" of the IOmx service.
214      */
215     const char *getOwnerName() const;
216 
217     /**
218      * Returns the rank of the component.
219      *
220      * Technically this is defined to be per media type, but that makes ordering the MediaCodecList
221      * impossible as MediaCodecList is ordered by codec name.
222      */
223     uint32_t getRank() const;
224 
225     /**
226      * Serialization over Binder
227      */
228     static sp<MediaCodecInfo> FromParcel(const Parcel &parcel);
229     status_t writeToParcel(Parcel *parcel) const;
230 
231 private:
232     AString mName;
233     AString mOwner;
234     Attributes mAttributes;
235     KeyedVector<AString, sp<Capabilities> > mCaps;
236     Vector<AString> mAliases;
237     uint32_t mRank;
238 
239     ssize_t getCapabilityIndex(const char *mediaType) const;
240 
241     /**
242      * Construct an `MediaCodecInfo` object. After the construction, its
243      * information can be set via an `MediaCodecInfoWriter` object obtained from
244      * `MediaCodecListWriter::addMediaCodecInfo()`.
245      */
246     MediaCodecInfo();
247 
248     DISALLOW_COPY_AND_ASSIGN(MediaCodecInfo);
249 
250     friend class MediaCodecListOverridesTest;
251     friend struct MediaCodecInfoWriter;
252     friend struct MediaCodecListWriter;
253 };
254 
255 /**
256  * This class is to be used by a `MediaCodecListBuilderBase` instance to
257  * populate information inside the associated `MediaCodecInfo` object.
258  *
259  * The only place where an instance of `MediaCodecInfoWriter` can be constructed
260  * is `MediaCodecListWriter::addMediaCodecInfo()`. A `MediaCodecListBuilderBase`
261  * instance should call `MediaCodecListWriter::addMediaCodecInfo()` on the given
262  * `MediaCodecListWriter` object given as an input to
263  * `MediaCodecListBuilderBase::buildMediaCodecList()`.
264  */
265 struct MediaCodecInfoWriter {
266     /**
267      * Set the name of the codec.
268      *
269      * @param name The new name.
270      */
271     void setName(const char* name);
272     /**
273      * Adds an alias (alternate name) for the codec. Multiple codecs can share an alternate name
274      * as long as their supported media types are distinct.
275      *
276      * @param name an alternate name.
277      */
278     void addAlias(const char* name);
279     /**
280      * Set the owner name of the codec.
281      *
282      * This "owner name" is the name of the `IOmx` instance that supports this
283      * codec.
284      *
285      * @param owner The new owner name.
286      */
287     void setOwner(const char* owner);
288     /**
289      * Sets codec attributes.
290      *
291      * @param attributes Codec attributes.
292      */
293     void setAttributes(typename std::underlying_type<MediaCodecInfo::Attributes>::type attributes);
294     /**
295      * Add a media type to an indexed list and return a `CapabilitiesWriter` object
296      * that can be used for modifying the associated `Capabilities`.
297      *
298      * If the media type already exists, this function will return the
299      * `CapabilitiesWriter` associated with the media type.
300      *
301      * @param[in] mediaType The name of a new media type to add.
302      * @return writer The `CapabilitiesWriter` object for modifying the
303      * `Capabilities` associated with the media type. `writer` will be valid
304      * regardless of whether `mediaType` already exists or not.
305      */
306     std::unique_ptr<MediaCodecInfo::CapabilitiesWriter> addMediaType(
307             const char* mediaType);
308     /**
309      * Remove a media type.
310      *
311      * @param mediaType The name of the media type to remove.
312      * @return `true` if `mediaType` is removed; `false` if `mediaType` is not found.
313      */
314     bool removeMediaType(const char* mediaType);
315     /**
316      * Set rank of the codec. MediaCodecList will stable-sort the list according
317      * to rank in non-descending order.
318      *
319      * @param rank The rank of the component.
320      */
321     void setRank(uint32_t rank);
322 private:
323     /**
324      * The associated `MediaCodecInfo`.
325      */
326     MediaCodecInfo* mInfo;
327     /**
328      * Construct the `MediaCodecInfoWriter` object associated with the given
329      * `MediaCodecInfo` object.
330      *
331      * @param info The underlying `MediaCodecInfo` object.
332      */
333     MediaCodecInfoWriter(MediaCodecInfo* info);
334 
335     DISALLOW_COPY_AND_ASSIGN(MediaCodecInfoWriter);
336 
337     friend struct MediaCodecListWriter;
338 };
339 
340 }  // namespace android
341 
342 #endif  // MEDIA_CODEC_INFO_H_
343 
344 
345