loliball/media
1
0
Fork 0
mirror of https://github.com/androidx/media.git synced 2025-05-05 06:30:24 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Improve DefaultTrackSelector documentation

Browse Source 
It's quite hard to find the defaults currently. Placing them
on each variable makes them easier to find.

-------------
Created by MOE: https://github.com/google/moe
MOE_MIGRATED_REVID=202495929
This commit is contained in:
olly 2018-06-28 09:54:09 -07:00 committed by Oliver Woodman
parent 186711287b
commit 6cdaf593e0
1 changed files with 94 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

167
library/core/src/main/java/com/google/android/exoplayer2/trackselection/DefaultTrackSelector.java
View File

@ -153,7 +153,8 @@ import java.util.concurrent.atomic.AtomicReference;
public class DefaultTrackSelector extends MappingTrackSelector { public class DefaultTrackSelector extends MappingTrackSelector {
/** /**
* A builder for {@link Parameters}. * A builder for {@link Parameters}. See the {@link Parameters} documentation for explanations of
* the parameters that can be configured using this builder.
*/ */
public static final class ParametersBuilder { public static final class ParametersBuilder {
@ -177,9 +178,7 @@ public class DefaultTrackSelector extends MappingTrackSelector {
private boolean viewportOrientationMayChange; private boolean viewportOrientationMayChange;
private int tunnelingAudioSessionId; private int tunnelingAudioSessionId;
/** /** Creates a builder with default initial values. */
* Creates a builder obtaining the initial values from {@link Parameters#DEFAULT}.
*/
public ParametersBuilder() { public ParametersBuilder() {
this(Parameters.DEFAULT); this(Parameters.DEFAULT);
} }
@ -343,15 +342,15 @@ public class DefaultTrackSelector extends MappingTrackSelector {
} }
/** /**
* Equivalent to invoking {@link #setViewportSize} with the viewport size obtained from * Equivalent to calling {@link #setViewportSize(int, int, boolean)} with the viewport size
* {@link Util#getPhysicalDisplaySize(Context)}. * obtained from {@link Util#getPhysicalDisplaySize(Context)}.
* *
* @param context The context to obtain the viewport size from. * @param context Any context.
* @param viewportOrientationMayChange See {@link #viewportOrientationMayChange}. * @param viewportOrientationMayChange See {@link Parameters#viewportOrientationMayChange}.
* @return This builder. * @return This builder.
*/ */
public ParametersBuilder setViewportSizeToPhysicalDisplaySize(Context context, public ParametersBuilder setViewportSizeToPhysicalDisplaySize(
boolean viewportOrientationMayChange) { Context context, boolean viewportOrientationMayChange) {
// Assume the viewport is fullscreen. // Assume the viewport is fullscreen.
Point viewportSize = Util.getPhysicalDisplaySize(context); Point viewportSize = Util.getPhysicalDisplaySize(context);
return setViewportSize(viewportSize.x, viewportSize.y, viewportOrientationMayChange); return setViewportSize(viewportSize.x, viewportSize.y, viewportOrientationMayChange);
@ -368,13 +367,16 @@ public class DefaultTrackSelector extends MappingTrackSelector {
} }
/** /**
* See {@link Parameters#viewportWidth}, {@link Parameters#maxVideoHeight} and * See {@link Parameters#viewportWidth}, {@link Parameters#maxVideoHeight} and {@link
* {@link Parameters#viewportOrientationMayChange}. * Parameters#viewportOrientationMayChange}.
* *
* @param viewportWidth See {@link Parameters#viewportWidth}.
* @param viewportHeight See {@link Parameters#viewportHeight}.
* @param viewportOrientationMayChange See {@link Parameters#viewportOrientationMayChange}.
* @return This builder. * @return This builder.
*/ */
public ParametersBuilder setViewportSize(int viewportWidth, int viewportHeight, public ParametersBuilder setViewportSize(
boolean viewportOrientationMayChange) { int viewportWidth, int viewportHeight, boolean viewportOrientationMayChange) {
this.viewportWidth = viewportWidth; this.viewportWidth = viewportWidth;
this.viewportHeight = viewportHeight; this.viewportHeight = viewportHeight;
this.viewportOrientationMayChange = viewportOrientationMayChange; this.viewportOrientationMayChange = viewportOrientationMayChange;
@ -485,8 +487,10 @@ public class DefaultTrackSelector extends MappingTrackSelector {
} }
/** /**
* Enables or disables tunneling. To enable tunneling, pass an audio session id to use when in * See {@link Parameters#tunnelingAudioSessionId}.
* tunneling mode. Session ids can be generated using {@link *
* <p>Enables or disables tunneling. To enable tunneling, pass an audio session id to use when
* in tunneling mode. Session ids can be generated using {@link
* C#generateAudioSessionIdV21(Context)}. To disable tunneling pass {@link * C#generateAudioSessionIdV21(Context)}. To disable tunneling pass {@link
* C#AUDIO_SESSION_ID_UNSET}. Tunneling will only be activated if it's both enabled and * C#AUDIO_SESSION_ID_UNSET}. Tunneling will only be activated if it's both enabled and
* supported by the audio and video renderers for the selected tracks. * supported by the audio and video renderers for the selected tracks.
@ -540,25 +544,7 @@ public class DefaultTrackSelector extends MappingTrackSelector {
/** Constraint parameters for {@link DefaultTrackSelector}. */ /** Constraint parameters for {@link DefaultTrackSelector}. */
public static final class Parameters implements Parcelable { public static final class Parameters implements Parcelable {
/** /** An instance with default values. */
* An instance with default values:
*
* <ul>
* <li>No preferred audio language.
* <li>No preferred text language.
* <li>Text tracks with undetermined language are not selected if no track with {@link
* #preferredTextLanguage} is available.
* <li>All selection flags are considered for text track selections.
* <li>Lowest bitrate track selections are not forced.
* <li>Adaptation between different mime types is not allowed.
* <li>Non seamless adaptation is allowed.
* <li>No max limit for video width/height.
* <li>No max video bitrate.
* <li>Video constraints are exceeded if no supported selection can be made otherwise.
* <li>Renderer capabilities are exceeded if no supported selection can be made.
* <li>No viewport constraints.
* </ul>
*/
public static final Parameters DEFAULT = new Parameters(); public static final Parameters DEFAULT = new Parameters();
// Per renderer overrides. // Per renderer overrides.
@ -568,105 +554,140 @@ public class DefaultTrackSelector extends MappingTrackSelector {
// Audio // Audio
/** /**
* The preferred language for audio, as well as for forced text tracks, as an ISO 639-2/T tag. * The preferred language for audio and forced text tracks, as an ISO 639-2/T tag. {@code null}
* {@code null} selects the default track, or the first track if there's no default. * selects the default track, or the first track if there's no default. The default value is
* {@code null}.
*/ */
public final @Nullable String preferredAudioLanguage; public final @Nullable String preferredAudioLanguage;
// Text // Text
/** /**
* The preferred language for text tracks as an ISO 639-2/T tag. {@code null} selects the * The preferred language for text tracks as an ISO 639-2/T tag. {@code null} selects the
* default track if there is one, or no track otherwise. * default track if there is one, or no track otherwise. The default value is {@code null}.
*/ */
public final @Nullable String preferredTextLanguage; public final @Nullable String preferredTextLanguage;
/** /**
* Whether a text track with undetermined language should be selected if no track with * Whether a text track with undetermined language should be selected if no track with {@link
* {@link #preferredTextLanguage} is available, or if {@link #preferredTextLanguage} is unset. * #preferredTextLanguage} is available, or if {@link #preferredTextLanguage} is unset. The
* default value is {@code false}.
*/ */
public final boolean selectUndeterminedTextLanguage; public final boolean selectUndeterminedTextLanguage;
/** /**
* Bitmask of selection flags that are disabled for text track selections. See {@link * Bitmask of selection flags that are disabled for text track selections. See {@link
* C.SelectionFlags}. * C.SelectionFlags}. The default value is {@code 0} (i.e. no flags).
*/ */
public final int disabledTextTrackSelectionFlags; public final int disabledTextTrackSelectionFlags;
// Video // Video
/** /**
* Maximum allowed video width. * Maximum allowed video width. The default value is {@link Integer#MAX_VALUE} (i.e. no
* constraint).
*
* <p>Note: To restrict adaptive video track selections to be suitable for a given viewport (the
* region of the display within which video will be played), it's preferable to use viewport
* constraints ({@link #viewportWidth}, {@link #viewportHeight} and
* {@link #viewportOrientationMayChange}) rather than video size constraints
* ({@link #maxVideoWidth and {@link #maxVideoHeight}). This is because selecting video tracks
* for a given viewport is normally more nuanced than imposing fixed limits on resolution (e.g.
* it's normally preferable to select one format that exceeds the size of the viewport, and to
* take into account the possibility that the orientation of the viewport may change).
*/ */
public final int maxVideoWidth; public final int maxVideoWidth;
/** /**
* Maximum allowed video height. * Maximum allowed video height. The default value is {@link Integer#MAX_VALUE} (i.e. no
* constraint).
*
* <p>Note: To restrict adaptive video track selections to be suitable for a given viewport (the
* region of the display within which video will be played), it's preferable to use viewport
* constraints ({@link #viewportWidth}, {@link #viewportHeight} and
* {@link #viewportOrientationMayChange}) rather than video size constraints
* ({@link #maxVideoWidth and {@link #maxVideoHeight}). This is because selecting video tracks
* for a given viewport is normally more nuanced than imposing fixed limits on resolution (e.g.
* it's normally preferable to select one format that exceeds the size of the viewport, and to
* take into account the possibility that the orientation of the viewport may change).
*/ */
public final int maxVideoHeight; public final int maxVideoHeight;
/** /**
* Maximum video bitrate. * Maximum video bitrate. The default value is {@link Integer#MAX_VALUE} (i.e. no constraint).
*/ */
public final int maxVideoBitrate; public final int maxVideoBitrate;
/** /**
* Whether to exceed video constraints when no selection can be made otherwise. * Whether to exceed the {@link #maxVideoWidth}, {@link #maxVideoHeight} and {@link
* #maxVideoBitrate} constraints when no selection can be made otherwise. The default value is
* {@code true}.
*/ */
public final boolean exceedVideoConstraintsIfNecessary; public final boolean exceedVideoConstraintsIfNecessary;
/** /**
* Viewport width in pixels. Constrains video tracks selections for adaptive playbacks so that * Viewport width in pixels. Constrains video track selections for adaptive playbacks so that
* only tracks suitable for the viewport are selected. * only tracks suitable for the viewport are selected. The default value is {@link
* Integer#MAX_VALUE} (i.e. no constraint).
*/ */
public final int viewportWidth; public final int viewportWidth;
/** /**
* Viewport height in pixels. Constrains video tracks selections for adaptive playbacks so that * Viewport height in pixels. Constrains video track selections for adaptive playbacks so that
* only tracks suitable for the viewport are selected. * only tracks suitable for the viewport are selected. The default value is {@link
* Integer#MAX_VALUE} (i.e. no constraint).
*/ */
public final int viewportHeight; public final int viewportHeight;
/** /**
* Whether the viewport orientation may change during playback. Constrains video tracks * Whether the viewport orientation may change during playback. Constrains video track
* selections for adaptive playbacks so that only tracks suitable for the viewport are selected. * selections for adaptive playbacks so that only tracks suitable for the viewport are selected.
* The default value is {@code true}.
*/ */
public final boolean viewportOrientationMayChange; public final boolean viewportOrientationMayChange;
// General // General
/** /**
* Whether to force selection of the single lowest bitrate audio and video tracks that comply * Whether to force selection of the single lowest bitrate audio and video tracks that comply
* with all other constraints. * with all other constraints. The default value is {@code false}.
*/ */
public final boolean forceLowestBitrate; public final boolean forceLowestBitrate;
/** /**
* Whether to allow adaptive selections containing mixed mime types. * Whether to allow adaptive selections containing mixed mime types. The default value is {@code
* false}.
*/ */
public final boolean allowMixedMimeAdaptiveness; public final boolean allowMixedMimeAdaptiveness;
/** /**
* Whether to allow adaptive selections where adaptation may not be completely seamless. * Whether to allow adaptive selections where adaptation may not be completely seamless. The
* default value is {@code true}.
*/ */
public final boolean allowNonSeamlessAdaptiveness; public final boolean allowNonSeamlessAdaptiveness;
/** /**
* Whether to exceed renderer capabilities when no selection can be made otherwise. * Whether to exceed renderer capabilities when no selection can be made otherwise. This
* parameter applies when all of the tracks available for a renderer exceed the renderer's
* reported capabilities. If the parameter is {@code true} then the lowest quality track will
* still be selected. Playback may succeed if the renderer has under-reported its true
* capabilities. If {@code false} then no track will be selected. The default value is {@code
* true}.
*/ */
public final boolean exceedRendererCapabilitiesIfNecessary; public final boolean exceedRendererCapabilitiesIfNecessary;
/** /**
* The audio session id to use when tunneling, or {@link C#AUDIO_SESSION_ID_UNSET} if tunneling * The audio session id to use when tunneling, or {@link C#AUDIO_SESSION_ID_UNSET} if tunneling
* is not to be enabled. * is disabled. The default value is {@link C#AUDIO_SESSION_ID_UNSET} (i.e. tunneling is
* disabled).
*/ */
public final int tunnelingAudioSessionId; public final int tunnelingAudioSessionId;
private Parameters() { private Parameters() {
this( this(
new SparseArray<Map<TrackGroupArray, SelectionOverride>>(), /* selectionOverrides= */ new SparseArray<>(),
new SparseBooleanArray(), /* rendererDisabledFlags= */ new SparseBooleanArray(),
null, /* preferredAudioLanguage= */ null,
null, /* preferredTextLanguage= */ null,
false, /* selectUndeterminedTextLanguage= */ false,
0, /* disabledTextTrackSelectionFlags= */ 0,
false, /* forceLowestBitrate= */ false,
false, /* allowMixedMimeAdaptiveness= */ false,
true, /* allowNonSeamlessAdaptiveness= */ true,
Integer.MAX_VALUE, /* maxVideoWidth= */ Integer.MAX_VALUE,
Integer.MAX_VALUE, /* maxVideoHeight= */ Integer.MAX_VALUE,
Integer.MAX_VALUE, /* maxVideoBitrate= */ Integer.MAX_VALUE,
true, /* exceedVideoConstraintsIfNecessary= */ true,
true, /* exceedRendererCapabilitiesIfNecessary= */ true,
Integer.MAX_VALUE, /* viewportWidth= */ Integer.MAX_VALUE,
Integer.MAX_VALUE, /* viewportHeight= */ Integer.MAX_VALUE,
true, /* viewportOrientationMayChange= */ true,
C.AUDIO_SESSION_ID_UNSET); /* tunnelingAudioSessionId= */ C.AUDIO_SESSION_ID_UNSET);
} }
/* package */ Parameters( /* package */ Parameters(