1 /* 2 * Copyright 2024, 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 CODEC_CAPABILITIES_H_ 18 19 #define CODEC_CAPABILITIES_H_ 20 21 #include <media/AudioCapabilities.h> 22 #include <media/CodecCapabilitiesUtils.h> 23 #include <media/EncoderCapabilities.h> 24 #include <media/VideoCapabilities.h> 25 #include <media/stagefright/foundation/ABase.h> 26 #include <media/stagefright/foundation/AMessage.h> 27 #include <media/stagefright/foundation/AString.h> 28 #include <media/stagefright/MediaCodecConstants.h> 29 30 #include <utils/Errors.h> 31 #include <utils/RefBase.h> 32 #include <utils/Vector.h> 33 #include <utils/StrongPointer.h> 34 35 namespace android { 36 37 struct CodecCapabilities { 38 39 static bool SupportsBitrate(Range<int32_t> bitrateRange, 40 const sp<AMessage> &format); 41 42 /** 43 * Retrieve the codec capabilities for a certain {@code mime type}, {@code 44 * profile} and {@code level}. If the type, or profile-level combination 45 * is not understood by the framework, it returns null. 46 * <p class=note> In {@link android.os.Build.VERSION_CODES#M}, calling this 47 * method without calling any method of the {@link MediaCodecList} class beforehand 48 * results in a {@link NullPointerException}.</p> 49 */ 50 static std::shared_ptr<CodecCapabilities> CreateFromProfileLevel(std::string mediaType, 51 int32_t profile, int32_t level, int32_t maxConcurrentInstances = -1); 52 CodecCapabilitiesCodecCapabilities53 CodecCapabilities() {}; 54 55 /** 56 * Init CodecCapabilities with settings. 57 */ 58 void init(std::vector<ProfileLevel> profLevs, std::vector<uint32_t> colFmts, bool encoder, 59 sp<AMessage> &defaultFormat, sp<AMessage> &capabilitiesInfo, 60 int32_t maxConcurrentInstances = 0); 61 62 /** 63 * Returns the media type for which this codec-capability object was created. 64 */ 65 const std::string& getMediaType(); 66 67 /** 68 * Returns the supported profile levels. 69 */ 70 const std::vector<ProfileLevel>& getProfileLevels(); 71 72 /** 73 * Returns the supported color formats. 74 */ 75 std::vector<uint32_t> getColorFormats() const; 76 77 /** 78 * Returns a media format with default values for configurations that have defaults. 79 */ 80 sp<AMessage> getDefaultFormat() const; 81 82 /** 83 * Returns the max number of the supported concurrent codec instances. 84 * <p> 85 * This is a hint for an upper bound. Applications should not expect to successfully 86 * operate more instances than the returned value, but the actual number of 87 * concurrently operable instances may be less as it depends on the available 88 * resources at time of use. 89 */ 90 int32_t getMaxSupportedInstances() const; 91 92 /** 93 * Returns the audio capabilities or {@code null} if this is not an audio codec. 94 */ 95 std::shared_ptr<AudioCapabilities> getAudioCapabilities() const; 96 97 /** 98 * Returns the video capabilities or {@code null} if this is not a video codec. 99 */ 100 std::shared_ptr<VideoCapabilities> getVideoCapabilities() const; 101 102 /** 103 * Returns the encoding capabilities or {@code null} if this is not an encoder. 104 */ 105 std::shared_ptr<EncoderCapabilities> getEncoderCapabilities() const; 106 107 std::vector<std::string> validFeatures() const; 108 109 /** 110 * Query codec feature capabilities. 111 * <p> 112 * These features are supported to be used by the codec. These 113 * include optional features that can be turned on, as well as 114 * features that are always on. 115 */ 116 bool isFeatureSupported(const std::string &name) const; 117 118 /** 119 * Query codec feature requirements. 120 * <p> 121 * These features are required to be used by the codec, and as such, 122 * they are always turned on. 123 */ 124 bool isFeatureRequired(const std::string &name) const; 125 126 bool isRegular() const; 127 128 /** 129 * Query whether codec supports a given {@link MediaFormat}. 130 * 131 * <p class=note> 132 * <strong>Note:</strong> On {@link android.os.Build.VERSION_CODES#LOLLIPOP}, 133 * {@code format} must not contain a {@linkplain MediaFormat#KEY_FRAME_RATE 134 * frame rate}. Use 135 * <code class=prettyprint>format.setString(MediaFormat.KEY_FRAME_RATE, null)</code> 136 * to clear any existing frame rate setting in the format. 137 * <p> 138 * 139 * The following table summarizes the format keys considered by this method. 140 * This is especially important to consider when targeting a higher SDK version than the 141 * minimum SDK version, as this method will disregard some keys on devices below the target 142 * SDK version. 143 * 144 * <table style="width: 0%"> 145 * <thead> 146 * <tr> 147 * <th rowspan=3>OS Version(s)</th> 148 * <td colspan=3>{@code MediaFormat} keys considered for</th> 149 * </tr><tr> 150 * <th>Audio Codecs</th> 151 * <th>Video Codecs</th> 152 * <th>Encoders</th> 153 * </tr> 154 * </thead> 155 * <tbody> 156 * <tr> 157 * <td>{@link android.os.Build.VERSION_CODES#LOLLIPOP}</td> 158 * <td rowspan=3>{@link MediaFormat#KEY_MIME}<sup>*</sup>,<br> 159 * {@link MediaFormat#KEY_SAMPLE_RATE},<br> 160 * {@link MediaFormat#KEY_CHANNEL_COUNT},</td> 161 * <td>{@link MediaFormat#KEY_MIME}<sup>*</sup>,<br> 162 * {@link CodecCapabilities#FEATURE_AdaptivePlayback}<sup>D</sup>,<br> 163 * {@link CodecCapabilities#FEATURE_SecurePlayback}<sup>D</sup>,<br> 164 * {@link CodecCapabilities#FEATURE_TunneledPlayback}<sup>D</sup>,<br> 165 * {@link MediaFormat#KEY_WIDTH},<br> 166 * {@link MediaFormat#KEY_HEIGHT},<br> 167 * <strong>no</strong> {@code KEY_FRAME_RATE}</td> 168 * <td rowspan=10>as to the left, plus<br> 169 * {@link MediaFormat#KEY_BITRATE_MODE},<br> 170 * {@link MediaFormat#KEY_PROFILE} 171 * (and/or {@link MediaFormat#KEY_AAC_PROFILE}<sup>~</sup>),<br> 172 * <!-- {link MediaFormat#KEY_QUALITY},<br> --> 173 * {@link MediaFormat#KEY_COMPLEXITY} 174 * (and/or {@link MediaFormat#KEY_FLAC_COMPRESSION_LEVEL}<sup>~</sup>)</td> 175 * </tr><tr> 176 * <td>{@link android.os.Build.VERSION_CODES#LOLLIPOP_MR1}</td> 177 * <td rowspan=2>as above, plus<br> 178 * {@link MediaFormat#KEY_FRAME_RATE}</td> 179 * </tr><tr> 180 * <td>{@link android.os.Build.VERSION_CODES#M}</td> 181 * </tr><tr> 182 * <td>{@link android.os.Build.VERSION_CODES#N}</td> 183 * <td rowspan=2>as above, plus<br> 184 * {@link MediaFormat#KEY_PROFILE},<br> 185 * <!-- {link MediaFormat#KEY_MAX_BIT_RATE},<br> --> 186 * {@link MediaFormat#KEY_BIT_RATE}</td> 187 * <td rowspan=2>as above, plus<br> 188 * {@link MediaFormat#KEY_PROFILE},<br> 189 * {@link MediaFormat#KEY_LEVEL}<sup>+</sup>,<br> 190 * <!-- {link MediaFormat#KEY_MAX_BIT_RATE},<br> --> 191 * {@link MediaFormat#KEY_BIT_RATE},<br> 192 * {@link CodecCapabilities#FEATURE_IntraRefresh}<sup>E</sup></td> 193 * </tr><tr> 194 * <td>{@link android.os.Build.VERSION_CODES#N_MR1}</td> 195 * </tr><tr> 196 * <td>{@link android.os.Build.VERSION_CODES#O}</td> 197 * <td rowspan=3 colspan=2>as above, plus<br> 198 * {@link CodecCapabilities#FEATURE_PartialFrame}<sup>D</sup></td> 199 * </tr><tr> 200 * <td>{@link android.os.Build.VERSION_CODES#O_MR1}</td> 201 * </tr><tr> 202 * <td>{@link android.os.Build.VERSION_CODES#P}</td> 203 * </tr><tr> 204 * <td>{@link android.os.Build.VERSION_CODES#Q}</td> 205 * <td colspan=2>as above, plus<br> 206 * {@link CodecCapabilities#FEATURE_FrameParsing}<sup>D</sup>,<br> 207 * {@link CodecCapabilities#FEATURE_MultipleFrames},<br> 208 * {@link CodecCapabilities#FEATURE_DynamicTimestamp}</td> 209 * </tr><tr> 210 * <td>{@link android.os.Build.VERSION_CODES#R}</td> 211 * <td colspan=2>as above, plus<br> 212 * {@link CodecCapabilities#FEATURE_LowLatency}<sup>D</sup></td> 213 * </tr> 214 * <tr> 215 * <td colspan=4> 216 * <p class=note><strong>Notes:</strong><br> 217 * *: must be specified; otherwise, method returns {@code false}.<br> 218 * +: method does not verify that the format parameters are supported 219 * by the specified level.<br> 220 * D: decoders only<br> 221 * E: encoders only<br> 222 * ~: if both keys are provided values must match 223 * </td> 224 * </tr> 225 * </tbody> 226 * </table> 227 * 228 * @param format media format with optional feature directives. 229 * @return whether the codec capabilities support the given format 230 * and feature requests. 231 */ 232 bool isFormatSupported(const sp<AMessage> &format) const; 233 234 /** 235 * If the CodecCapabilities contains an AudioCapabilities. 236 * 237 * Not a public API to users. 238 */ 239 bool isAudio() const; 240 241 /** 242 * If the CodecCapabilities contains a VideoCapabilities. 243 * 244 * Not a public API to users. 245 */ 246 bool isVideo() const; 247 248 /** 249 * If the CodecCapabilities contains an EncoderCapabilities. 250 * 251 * Not a public API to users. 252 */ 253 bool isEncoder() const; 254 255 private: 256 std::string mMediaType; 257 std::vector<ProfileLevel> mProfileLevels; 258 std::vector<uint32_t> mColorFormats; 259 int32_t mMaxSupportedInstances; 260 261 sp<AMessage> mDefaultFormat; 262 sp<AMessage> mCapabilitiesInfo; 263 264 // Features 265 std::set<std::string> mFeaturesSupported; 266 std::set<std::string> mFeaturesRequired; 267 268 std::shared_ptr<AudioCapabilities> mAudioCaps; 269 std::shared_ptr<VideoCapabilities> mVideoCaps; 270 std::shared_ptr<EncoderCapabilities> mEncoderCaps; 271 272 bool supportsProfileLevel(int32_t profile, int32_t level) const; 273 std::vector<Feature> getValidFeatures() const; 274 int32_t getErrors() const; 275 }; 276 277 } // namespace android 278 279 #endif // CODEC_CAPABILITIES_H_