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 package com.google.android.exoplayer2; 17 18 import android.annotation.SuppressLint; 19 import androidx.annotation.IntDef; 20 import com.google.android.exoplayer2.util.MimeTypes; 21 import java.lang.annotation.Documented; 22 import java.lang.annotation.Retention; 23 import java.lang.annotation.RetentionPolicy; 24 25 /** 26 * Defines the capabilities of a {@link Renderer}. 27 */ 28 public interface RendererCapabilities { 29 30 /** 31 * Level of renderer support for a format. One of {@link #FORMAT_HANDLED}, {@link 32 * #FORMAT_EXCEEDS_CAPABILITIES}, {@link #FORMAT_UNSUPPORTED_DRM}, {@link 33 * #FORMAT_UNSUPPORTED_SUBTYPE} or {@link #FORMAT_UNSUPPORTED_TYPE}. 34 */ 35 @Documented 36 @Retention(RetentionPolicy.SOURCE) 37 @IntDef({ 38 FORMAT_HANDLED, 39 FORMAT_EXCEEDS_CAPABILITIES, 40 FORMAT_UNSUPPORTED_DRM, 41 FORMAT_UNSUPPORTED_SUBTYPE, 42 FORMAT_UNSUPPORTED_TYPE 43 }) 44 @interface FormatSupport {} 45 46 /** A mask to apply to {@link Capabilities} to obtain the {@link FormatSupport} only. */ 47 int FORMAT_SUPPORT_MASK = 0b111; 48 /** 49 * The {@link Renderer} is capable of rendering the format. 50 */ 51 int FORMAT_HANDLED = 0b100; 52 /** 53 * The {@link Renderer} is capable of rendering formats with the same mime type, but the 54 * properties of the format exceed the renderer's capabilities. There is a chance the renderer 55 * will be able to play the format in practice because some renderers report their capabilities 56 * conservatively, but the expected outcome is that playback will fail. 57 * <p> 58 * Example: The {@link Renderer} is capable of rendering H264 and the format's mime type is 59 * {@link MimeTypes#VIDEO_H264}, but the format's resolution exceeds the maximum limit supported 60 * by the underlying H264 decoder. 61 */ 62 int FORMAT_EXCEEDS_CAPABILITIES = 0b011; 63 /** 64 * The {@link Renderer} is capable of rendering formats with the same mime type, but is not 65 * capable of rendering the format because the format's drm protection is not supported. 66 * <p> 67 * Example: The {@link Renderer} is capable of rendering H264 and the format's mime type is 68 * {@link MimeTypes#VIDEO_H264}, but the format indicates PlayReady drm protection where-as the 69 * renderer only supports Widevine. 70 */ 71 int FORMAT_UNSUPPORTED_DRM = 0b010; 72 /** 73 * The {@link Renderer} is a general purpose renderer for formats of the same top-level type, 74 * but is not capable of rendering the format or any other format with the same mime type because 75 * the sub-type is not supported. 76 * <p> 77 * Example: The {@link Renderer} is a general purpose audio renderer and the format's 78 * mime type matches audio/[subtype], but there does not exist a suitable decoder for [subtype]. 79 */ 80 int FORMAT_UNSUPPORTED_SUBTYPE = 0b001; 81 /** 82 * The {@link Renderer} is not capable of rendering the format, either because it does not 83 * support the format's top-level type, or because it's a specialized renderer for a different 84 * mime type. 85 * <p> 86 * Example: The {@link Renderer} is a general purpose video renderer, but the format has an 87 * audio mime type. 88 */ 89 int FORMAT_UNSUPPORTED_TYPE = 0b000; 90 91 /** 92 * Level of renderer support for adaptive format switches. One of {@link #ADAPTIVE_SEAMLESS}, 93 * {@link #ADAPTIVE_NOT_SEAMLESS} or {@link #ADAPTIVE_NOT_SUPPORTED}. 94 */ 95 @Documented 96 @Retention(RetentionPolicy.SOURCE) 97 @IntDef({ADAPTIVE_SEAMLESS, ADAPTIVE_NOT_SEAMLESS, ADAPTIVE_NOT_SUPPORTED}) 98 @interface AdaptiveSupport {} 99 100 /** A mask to apply to {@link Capabilities} to obtain the {@link AdaptiveSupport} only. */ 101 int ADAPTIVE_SUPPORT_MASK = 0b11000; 102 /** 103 * The {@link Renderer} can seamlessly adapt between formats. 104 */ 105 int ADAPTIVE_SEAMLESS = 0b10000; 106 /** 107 * The {@link Renderer} can adapt between formats, but may suffer a brief discontinuity 108 * (~50-100ms) when adaptation occurs. 109 */ 110 int ADAPTIVE_NOT_SEAMLESS = 0b01000; 111 /** 112 * The {@link Renderer} does not support adaptation between formats. 113 */ 114 int ADAPTIVE_NOT_SUPPORTED = 0b00000; 115 116 /** 117 * Level of renderer support for tunneling. One of {@link #TUNNELING_SUPPORTED} or {@link 118 * #TUNNELING_NOT_SUPPORTED}. 119 */ 120 @Documented 121 @Retention(RetentionPolicy.SOURCE) 122 @IntDef({TUNNELING_SUPPORTED, TUNNELING_NOT_SUPPORTED}) 123 @interface TunnelingSupport {} 124 125 /** A mask to apply to {@link Capabilities} to obtain the {@link TunnelingSupport} only. */ 126 int TUNNELING_SUPPORT_MASK = 0b100000; 127 /** 128 * The {@link Renderer} supports tunneled output. 129 */ 130 int TUNNELING_SUPPORTED = 0b100000; 131 /** 132 * The {@link Renderer} does not support tunneled output. 133 */ 134 int TUNNELING_NOT_SUPPORTED = 0b000000; 135 136 /** 137 * Combined renderer capabilities. 138 * 139 * <p>This is a bitwise OR of {@link FormatSupport}, {@link AdaptiveSupport} and {@link 140 * TunnelingSupport}. Use {@link #getFormatSupport(int)}, {@link #getAdaptiveSupport(int)} or 141 * {@link #getTunnelingSupport(int)} to obtain the individual flags. And use {@link #create(int)} 142 * or {@link #create(int, int, int)} to create the combined capabilities. 143 * 144 * <p>Possible values: 145 * 146 * <ul> 147 * <li>{@link FormatSupport}: The level of support for the format itself. One of {@link 148 * #FORMAT_HANDLED}, {@link #FORMAT_EXCEEDS_CAPABILITIES}, {@link #FORMAT_UNSUPPORTED_DRM}, 149 * {@link #FORMAT_UNSUPPORTED_SUBTYPE} and {@link #FORMAT_UNSUPPORTED_TYPE}. 150 * <li>{@link AdaptiveSupport}: The level of support for adapting from the format to another 151 * format of the same mime type. One of {@link #ADAPTIVE_SEAMLESS}, {@link 152 * #ADAPTIVE_NOT_SEAMLESS} and {@link #ADAPTIVE_NOT_SUPPORTED}. Only set if the level of 153 * support for the format itself is {@link #FORMAT_HANDLED} or {@link 154 * #FORMAT_EXCEEDS_CAPABILITIES}. 155 * <li>{@link TunnelingSupport}: The level of support for tunneling. One of {@link 156 * #TUNNELING_SUPPORTED} and {@link #TUNNELING_NOT_SUPPORTED}. Only set if the level of 157 * support for the format itself is {@link #FORMAT_HANDLED} or {@link 158 * #FORMAT_EXCEEDS_CAPABILITIES}. 159 * </ul> 160 */ 161 @Documented 162 @Retention(RetentionPolicy.SOURCE) 163 // Intentionally empty to prevent assignment or comparison with individual flags without masking. 164 @IntDef({}) 165 @interface Capabilities {} 166 167 /** 168 * Returns {@link Capabilities} for the given {@link FormatSupport}. 169 * 170 * <p>The {@link AdaptiveSupport} is set to {@link #ADAPTIVE_NOT_SUPPORTED} and {{@link 171 * TunnelingSupport} is set to {@link #TUNNELING_NOT_SUPPORTED}. 172 * 173 * @param formatSupport The {@link FormatSupport}. 174 * @return The combined {@link Capabilities} of the given {@link FormatSupport}, {@link 175 * #ADAPTIVE_NOT_SUPPORTED} and {@link #TUNNELING_NOT_SUPPORTED}. 176 */ 177 @Capabilities create(@ormatSupport int formatSupport)178 static int create(@FormatSupport int formatSupport) { 179 return create(formatSupport, ADAPTIVE_NOT_SUPPORTED, TUNNELING_NOT_SUPPORTED); 180 } 181 182 /** 183 * Returns {@link Capabilities} combining the given {@link FormatSupport}, {@link AdaptiveSupport} 184 * and {@link TunnelingSupport}. 185 * 186 * @param formatSupport The {@link FormatSupport}. 187 * @param adaptiveSupport The {@link AdaptiveSupport}. 188 * @param tunnelingSupport The {@link TunnelingSupport}. 189 * @return The combined {@link Capabilities}. 190 */ 191 // Suppression needed for IntDef casting. 192 @SuppressLint("WrongConstant") 193 @Capabilities create( @ormatSupport int formatSupport, @AdaptiveSupport int adaptiveSupport, @TunnelingSupport int tunnelingSupport)194 static int create( 195 @FormatSupport int formatSupport, 196 @AdaptiveSupport int adaptiveSupport, 197 @TunnelingSupport int tunnelingSupport) { 198 return formatSupport | adaptiveSupport | tunnelingSupport; 199 } 200 201 /** 202 * Returns the {@link FormatSupport} from the combined {@link Capabilities}. 203 * 204 * @param supportFlags The combined {@link Capabilities}. 205 * @return The {@link FormatSupport} only. 206 */ 207 // Suppression needed for IntDef casting. 208 @SuppressLint("WrongConstant") 209 @FormatSupport getFormatSupport(@apabilities int supportFlags)210 static int getFormatSupport(@Capabilities int supportFlags) { 211 return supportFlags & FORMAT_SUPPORT_MASK; 212 } 213 214 /** 215 * Returns the {@link AdaptiveSupport} from the combined {@link Capabilities}. 216 * 217 * @param supportFlags The combined {@link Capabilities}. 218 * @return The {@link AdaptiveSupport} only. 219 */ 220 // Suppression needed for IntDef casting. 221 @SuppressLint("WrongConstant") 222 @AdaptiveSupport getAdaptiveSupport(@apabilities int supportFlags)223 static int getAdaptiveSupport(@Capabilities int supportFlags) { 224 return supportFlags & ADAPTIVE_SUPPORT_MASK; 225 } 226 227 /** 228 * Returns the {@link TunnelingSupport} from the combined {@link Capabilities}. 229 * 230 * @param supportFlags The combined {@link Capabilities}. 231 * @return The {@link TunnelingSupport} only. 232 */ 233 // Suppression needed for IntDef casting. 234 @SuppressLint("WrongConstant") 235 @TunnelingSupport getTunnelingSupport(@apabilities int supportFlags)236 static int getTunnelingSupport(@Capabilities int supportFlags) { 237 return supportFlags & TUNNELING_SUPPORT_MASK; 238 } 239 240 /** 241 * Returns string representation of a {@link FormatSupport} flag. 242 * 243 * @param formatSupport A {@link FormatSupport} flag. 244 * @return A string representation of the flag. 245 */ getFormatSupportString(@ormatSupport int formatSupport)246 static String getFormatSupportString(@FormatSupport int formatSupport) { 247 switch (formatSupport) { 248 case RendererCapabilities.FORMAT_HANDLED: 249 return "YES"; 250 case RendererCapabilities.FORMAT_EXCEEDS_CAPABILITIES: 251 return "NO_EXCEEDS_CAPABILITIES"; 252 case RendererCapabilities.FORMAT_UNSUPPORTED_DRM: 253 return "NO_UNSUPPORTED_DRM"; 254 case RendererCapabilities.FORMAT_UNSUPPORTED_SUBTYPE: 255 return "NO_UNSUPPORTED_TYPE"; 256 case RendererCapabilities.FORMAT_UNSUPPORTED_TYPE: 257 return "NO"; 258 default: 259 throw new IllegalStateException(); 260 } 261 } 262 263 /** Returns the name of the {@link Renderer}. */ getName()264 String getName(); 265 266 /** 267 * Returns the track type that the {@link Renderer} handles. For example, a video renderer will 268 * return {@link C#TRACK_TYPE_VIDEO}, an audio renderer will return {@link C#TRACK_TYPE_AUDIO}, a 269 * text renderer will return {@link C#TRACK_TYPE_TEXT}, and so on. 270 * 271 * @see Renderer#getTrackType() 272 * @return One of the {@code TRACK_TYPE_*} constants defined in {@link C}. 273 */ getTrackType()274 int getTrackType(); 275 276 /** 277 * Returns the extent to which the {@link Renderer} supports a given format. 278 * 279 * @param format The format. 280 * @return The {@link Capabilities} for this format. 281 * @throws ExoPlaybackException If an error occurs. 282 */ 283 @Capabilities supportsFormat(Format format)284 int supportsFormat(Format format) throws ExoPlaybackException; 285 286 /** 287 * Returns the extent to which the {@link Renderer} supports adapting between supported formats 288 * that have different MIME types. 289 * 290 * @return The {@link AdaptiveSupport} for adapting between supported formats that have different 291 * MIME types. 292 * @throws ExoPlaybackException If an error occurs. 293 */ 294 @AdaptiveSupport supportsMixedMimeTypeAdaptation()295 int supportsMixedMimeTypeAdaptation() throws ExoPlaybackException; 296 } 297