Skip to content

SDK / exoplayer

Go to a project
Commit e7d95aff by olly Committed by Oliver Woodman
Options

Update Renderer documentation 

- Cleaned up documentation
- Removed getIndex from Renderer interface
- Renamed reset to be positionReset

-------------
Created by MOE: https://github.com/google/moe
MOE_MIGRATED_REVID=127731006
parent ff914afd
Inline Side-by-side
Showing with 193 additions and 164 deletions
extensions/vp9/src/main/java/com/google/android/exoplayer2/ext/vp9/LibvpxVideoRenderer.java
......@@ -106,6 +106,7 @@ public final class LibvpxVideoRenderer extends BaseRenderer {
public LibvpxVideoRenderer(boolean scaleToFit, long allowedJoiningTimeMs,
Handler eventHandler, VideoRendererEventListener eventListener,
int maxDroppedFrameCountToNotify) {
super(C.TRACK_TYPE_VIDEO);
this.scaleToFit = scaleToFit;
this.allowedJoiningTimeMs = allowedJoiningTimeMs;
this.maxDroppedFrameCountToNotify = maxDroppedFrameCountToNotify;
......@@ -139,11 +140,6 @@ public final class LibvpxVideoRenderer extends BaseRenderer {
}
@Override
public int getTrackType() {
return C.TRACK_TYPE_VIDEO;
}
@Override
public int supportsFormat(Format format) {
return isLibvpxAvailable() && MimeTypes.VIDEO_VP9.equalsIgnoreCase(format.sampleMimeType)
? (FORMAT_HANDLED | ADAPTIVE_SEAMLESS) : FORMAT_UNSUPPORTED_TYPE;
......@@ -359,7 +355,7 @@ public final class LibvpxVideoRenderer extends BaseRenderer {
}
@Override
protected void onReset(long positionUs, boolean joining) {
protected void onPositionReset(long positionUs, boolean joining) {
inputStreamEnded = false;
outputStreamEnded = false;
renderedFirstFrame = false;
......
library/src/main/java/com/google/android/exoplayer2/BaseRenderer.java
......@@ -27,6 +27,8 @@ import java.io.IOException;
*/
public abstract class BaseRenderer implements Renderer, RendererCapabilities {
private final int trackType;
private int index;
private int state;
private SampleStream stream;
......@@ -34,11 +36,21 @@ public abstract class BaseRenderer implements Renderer, RendererCapabilities {
private boolean readEndOfStream;
private boolean streamIsFinal;
public BaseRenderer() {
/**
* @param trackType The track type that the renderer handles. One of the {@link C}
* {@code TRACK_TYPE_*} constants.
*/
public BaseRenderer(int trackType) {
this.trackType = trackType;
readEndOfStream = true;
}
@Override
public final int getTrackType() {
return trackType;
}
@Override
public final RendererCapabilities getCapabilities() {
return this;
}
......@@ -49,11 +61,6 @@ public abstract class BaseRenderer implements Renderer, RendererCapabilities {
}
@Override
public final int getIndex() {
return index;
}
@Override
public MediaClock getMediaClock() {
return null;
}
......@@ -70,19 +77,14 @@ public abstract class BaseRenderer implements Renderer, RendererCapabilities {
state = STATE_ENABLED;
onEnabled(joining);
replaceStream(formats, stream, offsetUs);
onReset(positionUs, joining);
onPositionReset(positionUs, joining);
}
/**
* Called when the renderer is enabled.
* <p>
* The default implementation is a no-op.
*
* @param joining Whether this renderer is being enabled to join an ongoing playback.
* @throws ExoPlaybackException If an error occurs.
*/
protected void onEnabled(boolean joining) throws ExoPlaybackException {
// Do nothing.
@Override
public final void start() throws ExoPlaybackException {
Assertions.checkState(state == STATE_ENABLED);
state = STATE_STARTED;
onStarted();
}
@Override
......@@ -95,53 +97,102 @@ public abstract class BaseRenderer implements Renderer, RendererCapabilities {
onStreamChanged(formats);
}
/**
* Called when the renderer's stream has changed.
* <p>
* The default implementation is a no-op.
*
* @param formats The enabled formats.
* @throws ExoPlaybackException Thrown if an error occurs.
*/
protected void onStreamChanged(Format[] formats) throws ExoPlaybackException {
// Do nothing.
@Override
public final boolean hasReadStreamToEnd() {
return readEndOfStream;
}
@Override
public final void setCurrentStreamIsFinal() {
streamIsFinal = true;
}
@Override
public final void maybeThrowStreamError() throws IOException {
stream.maybeThrowError();
}
@Override
public final void resetPosition(long positionUs) throws ExoPlaybackException {
streamIsFinal = false;
onPositionReset(positionUs, false);
}
@Override
public final void stop() throws ExoPlaybackException {
Assertions.checkState(state == STATE_STARTED);
state = STATE_ENABLED;
onStopped();
}
@Override
public final void reset(long positionUs) throws ExoPlaybackException {
public final void disable() {
Assertions.checkState(state == STATE_ENABLED);
state = STATE_DISABLED;
onDisabled();
stream = null;
streamIsFinal = false;
onReset(positionUs, false);
}
// RendererCapabilities implementation.
@Override
public int supportsMixedMimeTypeAdaptation() throws ExoPlaybackException {
return ADAPTIVE_NOT_SUPPORTED;
}
// ExoPlayerComponent implementation.
@Override
public void handleMessage(int what, Object object) throws ExoPlaybackException {
// Do nothing.
}
// Methods to be overridden by subclasses.
/**
* Invoked when a reset is encountered, and also when the renderer is enabled.
* Called when the renderer is enabled.
* <p>
* This method may be called when the renderer is in the following states:
* {@link #STATE_ENABLED}, {@link #STATE_STARTED}.
* The default implementation is a no-op.
*
* @param positionUs The playback position in microseconds.
* @param joining Whether this renderer is being enabled to join an ongoing playback.
* @throws ExoPlaybackException If an error occurs handling the reset.
* @throws ExoPlaybackException If an error occurs.
*/
protected void onReset(long positionUs, boolean joining) throws ExoPlaybackException {
protected void onEnabled(boolean joining) throws ExoPlaybackException {
// Do nothing.
}
@Override
public final boolean hasReadStreamToEnd() {
return readEndOfStream;
}
@Override
public final void setCurrentStreamIsFinal() {
streamIsFinal = true;
/**
* Called when the renderer's stream has changed. This occurs when the renderer is enabled after
* {@link #onEnabled(boolean)} has been called, and also when the stream has been replaced whilst
* the renderer is enabled or started.
* <p>
* The default implementation is a no-op.
*
* @param formats The enabled formats.
* @throws ExoPlaybackException If an error occurs.
*/
protected void onStreamChanged(Format[] formats) throws ExoPlaybackException {
// Do nothing.
}
@Override
public final void start() throws ExoPlaybackException {
Assertions.checkState(state == STATE_ENABLED);
state = STATE_STARTED;
onStarted();
/**
* Invoked when the position is reset. This occurs when the renderer is enabled after
* {@link #onStreamChanged(Format[])} has been called, and also when a position discontinuity
* is encountered.
* <p>
* After a position reset, the renderer's {@link SampleStream} is guaranteed to provide samples
* starting from a key frame.
* <p>
* The default implementation is a no-op.
*
* @param positionUs The new playback position in microseconds.
* @param joining Whether this renderer is being enabled to join an ongoing playback.
* @throws ExoPlaybackException If an error occurs.
*/
protected void onPositionReset(long positionUs, boolean joining)
throws ExoPlaybackException {
// Do nothing.
}
/**
......@@ -155,13 +206,6 @@ public abstract class BaseRenderer implements Renderer, RendererCapabilities {
// Do nothing.
}
@Override
public final void stop() throws ExoPlaybackException {
Assertions.checkState(state == STATE_STARTED);
state = STATE_ENABLED;
onStopped();
}
/**
* Called when the renderer is stopped.
* <p>
......@@ -173,15 +217,6 @@ public abstract class BaseRenderer implements Renderer, RendererCapabilities {
// Do nothing.
}
@Override
public final void disable() {
Assertions.checkState(state == STATE_ENABLED);
state = STATE_DISABLED;
onDisabled();
stream = null;
streamIsFinal = false;
}
/**
* Called when the renderer is disabled.
* <p>
......@@ -191,27 +226,17 @@ public abstract class BaseRenderer implements Renderer, RendererCapabilities {
// Do nothing.
}
@Override
public final void maybeThrowStreamError() throws IOException {
stream.maybeThrowError();
}
// RendererCapabilities implementation.
@Override
public int supportsMixedMimeTypeAdaptation() throws ExoPlaybackException {
return ADAPTIVE_NOT_SUPPORTED;
}
// ExoPlayerComponent implementation.
// Methods to be called by subclasses.
@Override
public void handleMessage(int what, Object object) throws ExoPlaybackException {
// Do nothing.
/**
* Returns the index of the renderer within the player.
*
* @return The index of the renderer within the player.
*/
protected final int getIndex() {
return index;
}
// Methods to be called by subclasses.
/**
* Reads from the enabled upstream source.
*
......
library/src/main/java/com/google/android/exoplayer2/ExoPlayerImplInternal.java
......@@ -500,7 +500,7 @@ import java.util.ArrayList;
internalPositionUs = sourceOffsetUs + periodPositionUs;
standaloneMediaClock.setPositionUs(internalPositionUs);
for (Renderer renderer : enabledRenderers) {
renderer.reset(internalPositionUs);
renderer.resetPosition(internalPositionUs);
}
}
......
library/src/main/java/com/google/android/exoplayer2/Renderer.java
......@@ -72,13 +72,6 @@ public interface Renderer extends ExoPlayerComponent {
void setIndex(int index);
/**
* Returns the index of the renderer within the player.
*
* @return The index of the renderer within the player.
*/
int getIndex();
/**
* If the renderer advances its own playback position then this method returns a corresponding
* {@link MediaClock}. If provided, the player will use the returned {@link MediaClock} as its
* source of time during playback. A player may have at most one renderer that returns a
......@@ -97,6 +90,9 @@ public interface Renderer extends ExoPlayerComponent {
/**
* Enable the renderer to consume from the specified {@link SampleStream}.
* <p>
* This method may be called when the renderer is in the following states:
* {@link #STATE_DISABLED}.
*
* @param formats The enabled formats.
* @param stream The {@link SampleStream} from which the renderer should consume.
......@@ -110,7 +106,21 @@ public interface Renderer extends ExoPlayerComponent {
long offsetUs) throws ExoPlaybackException;
/**
* Sets the {@link SampleStream} from which samples will be consumed.
* Starts the renderer, meaning that calls to {@link #render(long, long)} will cause media to be
* rendered.
* <p>
* This method may be called when the renderer is in the following states:
* {@link #STATE_ENABLED}.
*
* @throws ExoPlaybackException If an error occurs.
*/
void start() throws ExoPlaybackException;
/**
* Replaces the {@link SampleStream} from which samples will be consumed.
* <p>
* This method may be called when the renderer is in the following states:
* {@link #STATE_ENABLED}, {@link #STATE_STARTED}.
*
* @param formats The enabled formats.
* @param stream The {@link SampleStream} from which the renderer should consume.
......@@ -122,50 +132,28 @@ public interface Renderer extends ExoPlayerComponent {
throws ExoPlaybackException;
/**
* Called when a reset is encountered.
*
* @param positionUs The playback position in microseconds.
* @throws ExoPlaybackException If an error occurs handling the reset.
*/
void reset(long positionUs) throws ExoPlaybackException;
/**
* Returns whether the renderer has read the current {@link SampleStream} to the end.
* <p>
* This method may be called when the renderer is in the following states:
* {@link #STATE_ENABLED}, {@link #STATE_STARTED}.
*/
boolean hasReadStreamToEnd();
/**
* Signals to the renderer that the current {@link SampleStream} will be the final one supplied
* before it is next disabled or reset.
* <p>
* This method may be called when the renderer is in the following states:
* {@link #STATE_ENABLED}, {@link #STATE_STARTED}.
*/
void setCurrentStreamIsFinal();
/**
* Starts the renderer, meaning that calls to {@link #render(long, long)} will cause media to be
* rendered.
*
* @throws ExoPlaybackException If an error occurs.
*/
void start() throws ExoPlaybackException;
/**
* Stops the renderer.
*
* @throws ExoPlaybackException If an error occurs.
*/
void stop() throws ExoPlaybackException;
/**
* Disable the renderer.
*/
void disable();
/**
* Throws an error that's preventing the renderer from reading from its {@link SampleStream}. Does
* nothing if no such error exists.
* <p>
* This method may be called when the renderer is in the following states:
* {@link #STATE_ENABLED}.
* {@link #STATE_ENABLED}, {@link #STATE_STARTED}.
*
* @throws IOException An error that's preventing the renderer from making progress or buffering
* more data.
......@@ -173,8 +161,28 @@ public interface Renderer extends ExoPlayerComponent {
void maybeThrowStreamError() throws IOException;
/**
* Called when a position discontinuity is encountered.
* <p>
* After a position discontinuity, the renderer's {@link SampleStream} is guaranteed to provide
* samples starting from a key frame.
* <p>
* This method may be called when the renderer is in the following states:
* {@link #STATE_ENABLED}, {@link #STATE_STARTED}.
*
* @param positionUs The new playback position in microseconds.
* @throws ExoPlaybackException If an error occurs handling the reset.
*/
void resetPosition(long positionUs) throws ExoPlaybackException;
/**
* Incrementally renders the {@link SampleStream}.
* <p>
* If the renderer is in the {@link #STATE_ENABLED} state then each call to this method will do
* work toward being ready to render the {@link SampleStream} when the renderer is started. It may
* also render the very start of the media, for example the first frame of a video stream. If the
* renderer is in the {@link #STATE_STARTED} state then calls to this method will render the
* {@link SampleStream} in sync with the specified media positions.
* <p>
* This method should return quickly, and should not block if the renderer is unable to make
* useful progress.
* <p>
......@@ -218,4 +226,22 @@ public interface Renderer extends ExoPlayerComponent {
*/
boolean isEnded();
/**
* Stops the renderer.
* <p>
* This method may be called when the renderer is in the following states:
* {@link #STATE_STARTED}.
*
* @throws ExoPlaybackException If an error occurs.
*/
void stop() throws ExoPlaybackException;
/**
* Disable the renderer.
* <p>
* This method may be called when the renderer is in the following states:
* {@link #STATE_ENABLED}.
*/
void disable();
}
library/src/main/java/com/google/android/exoplayer2/audio/MediaCodecAudioRenderer.java
......@@ -132,18 +132,13 @@ public class MediaCodecAudioRenderer extends MediaCodecRenderer implements Media
DrmSessionManager drmSessionManager, boolean playClearSamplesWithoutKeys,
Handler eventHandler, AudioRendererEventListener eventListener,
AudioCapabilities audioCapabilities, int streamType) {
super(mediaCodecSelector, drmSessionManager, playClearSamplesWithoutKeys);
super(C.TRACK_TYPE_AUDIO, mediaCodecSelector, drmSessionManager, playClearSamplesWithoutKeys);
audioSessionId = AudioTrack.SESSION_ID_NOT_SET;
audioTrack = new AudioTrack(audioCapabilities, streamType);
eventDispatcher = new EventDispatcher(eventHandler, eventListener);
}
@Override
public int getTrackType() {
return C.TRACK_TYPE_AUDIO;
}
@Override
protected int supportsFormat(MediaCodecSelector mediaCodecSelector, Format format)
throws DecoderQueryException {
String mimeType = format.sampleMimeType;
......@@ -264,8 +259,8 @@ public class MediaCodecAudioRenderer extends MediaCodecRenderer implements Media
}
@Override
protected void onReset(long positionUs, boolean joining) throws ExoPlaybackException {
super.onReset(positionUs, joining);
protected void onPositionReset(long positionUs, boolean joining) throws ExoPlaybackException {
super.onPositionReset(positionUs, joining);
audioTrack.reset();
currentPositionUs = positionUs;
allowPositionDiscontinuity = true;
......
library/src/main/java/com/google/android/exoplayer2/audio/SimpleDecoderAudioRenderer.java
......@@ -85,6 +85,7 @@ public abstract class SimpleDecoderAudioRenderer extends BaseRenderer implements
public SimpleDecoderAudioRenderer(Handler eventHandler,
AudioRendererEventListener eventListener, AudioCapabilities audioCapabilities,
int streamType) {
super(C.TRACK_TYPE_AUDIO);
eventDispatcher = new EventDispatcher(eventHandler, eventListener);
audioSessionId = AudioTrack.SESSION_ID_NOT_SET;
audioTrack = new AudioTrack(audioCapabilities, streamType);
......@@ -137,11 +138,6 @@ public abstract class SimpleDecoderAudioRenderer extends BaseRenderer implements
decoderCounters.ensureUpdated();
}
@Override
public int getTrackType() {
return C.TRACK_TYPE_AUDIO;
}
protected abstract SimpleDecoder<DecoderInputBuffer, ? extends SimpleOutputBuffer,
? extends AudioDecoderException> createDecoder(Format format) throws AudioDecoderException;
......@@ -311,7 +307,7 @@ public abstract class SimpleDecoderAudioRenderer extends BaseRenderer implements
}
@Override
protected void onReset(long positionUs, boolean joining) {
protected void onPositionReset(long positionUs, boolean joining) {
audioTrack.reset();
currentPositionUs = positionUs;
allowPositionDiscontinuity = true;
......
library/src/main/java/com/google/android/exoplayer2/mediacodec/MediaCodecRenderer.java
......@@ -205,6 +205,8 @@ public abstract class MediaCodecRenderer extends BaseRenderer {
protected DecoderCounters decoderCounters;
/**
* @param trackType The track type that the renderer handles. One of the {@code C.TRACK_TYPE_*}
* constants defined in {@link C}.
* @param mediaCodecSelector A decoder selector.
* @param drmSessionManager For use with encrypted media. May be null if support for encrypted
* media is not required.
......@@ -214,8 +216,9 @@ public abstract class MediaCodecRenderer extends BaseRenderer {
* permitted to play clear regions of encrypted media files before {@code drmSessionManager}
* has obtained the keys necessary to decrypt encrypted regions of the media.
*/
public MediaCodecRenderer(MediaCodecSelector mediaCodecSelector,
public MediaCodecRenderer(int trackType, MediaCodecSelector mediaCodecSelector,
DrmSessionManager drmSessionManager, boolean playClearSamplesWithoutKeys) {
super(trackType);
Assertions.checkState(Util.SDK_INT >= 16);
this.mediaCodecSelector = Assertions.checkNotNull(mediaCodecSelector);
this.drmSessionManager = drmSessionManager;
......@@ -383,7 +386,7 @@ public abstract class MediaCodecRenderer extends BaseRenderer {
}
@Override
protected void onReset(long positionUs, boolean joining) throws ExoPlaybackException {
protected void onPositionReset(long positionUs, boolean joining) throws ExoPlaybackException {
inputStreamEnded = false;
outputStreamEnded = false;
if (codec != null) {
......@@ -899,8 +902,9 @@ public abstract class MediaCodecRenderer extends BaseRenderer {
* modified between successive calls. Hence an implementation can, for example, modify the
* buffer's position to keep track of how much of the data it has processed.
* <p>
* Note that the first call to this method following a call to {@link #onReset(long, boolean)}
* will always receive a new {@link ByteBuffer} to be processed.
* Note that the first call to this method following a call to
* {@link #onPositionReset(long, boolean)} will always receive a new {@link ByteBuffer} to be
* processed.
*
* @param positionUs The current media time in microseconds, measured at the start of the
* current iteration of the rendering loop.
......
library/src/main/java/com/google/android/exoplayer2/metadata/MetadataRenderer.java
......@@ -77,6 +77,7 @@ public final class MetadataRenderer<T> extends BaseRenderer implements Callback
*/
public MetadataRenderer(Output<T> output, Looper outputLooper,
MetadataDecoder<T> metadataDecoder) {
super(C.TRACK_TYPE_METADATA);
this.output = Assertions.checkNotNull(output);
this.outputHandler = outputLooper == null ? null : new Handler(outputLooper, this);
this.metadataDecoder = Assertions.checkNotNull(metadataDecoder);
......@@ -85,18 +86,13 @@ public final class MetadataRenderer<T> extends BaseRenderer implements Callback
}
@Override
public int getTrackType() {
return C.TRACK_TYPE_METADATA;
}
@Override
public int supportsFormat(Format format) {
return metadataDecoder.canDecode(format.sampleMimeType) ? FORMAT_HANDLED
: FORMAT_UNSUPPORTED_TYPE;
}
@Override
protected void onReset(long positionUs, boolean joining) {
protected void onPositionReset(long positionUs, boolean joining) {
pendingMetadata = null;
inputStreamEnded = false;
}
......
library/src/main/java/com/google/android/exoplayer2/text/TextRenderer.java
......@@ -93,6 +93,7 @@ public final class TextRenderer extends BaseRenderer implements Callback {
* @param decoderFactory A factory from which to obtain {@link SubtitleDecoder} instances.
*/
public TextRenderer(Output output, Looper outputLooper, SubtitleDecoderFactory decoderFactory) {
super(C.TRACK_TYPE_TEXT);
this.output = Assertions.checkNotNull(output);
this.outputHandler = outputLooper == null ? null : new Handler(outputLooper, this);
this.decoderFactory = decoderFactory;
......@@ -100,11 +101,6 @@ public final class TextRenderer extends BaseRenderer implements Callback {
}
@Override
public int getTrackType() {
return C.TRACK_TYPE_TEXT;
}
@Override
public int supportsFormat(Format format) {
return decoderFactory.supportsFormat(format) ? FORMAT_HANDLED
: (MimeTypes.isText(format.sampleMimeType) ? FORMAT_UNSUPPORTED_SUBTYPE
......@@ -120,7 +116,7 @@ public final class TextRenderer extends BaseRenderer implements Callback {
}
@Override
protected void onReset(long positionUs, boolean joining) {
protected void onPositionReset(long positionUs, boolean joining) {
inputStreamEnded = false;
outputStreamEnded = false;
if (subtitle != null) {
......
library/src/main/java/com/google/android/exoplayer2/video/MediaCodecVideoRenderer.java
......@@ -151,7 +151,7 @@ public class MediaCodecVideoRenderer extends MediaCodecRenderer {
int videoScalingMode, long allowedJoiningTimeMs, DrmSessionManager drmSessionManager,
boolean playClearSamplesWithoutKeys, Handler eventHandler,
VideoRendererEventListener eventListener, int maxDroppedFrameCountToNotify) {
super(mediaCodecSelector, drmSessionManager, playClearSamplesWithoutKeys);
super(C.TRACK_TYPE_VIDEO, mediaCodecSelector, drmSessionManager, playClearSamplesWithoutKeys);
this.videoScalingMode = videoScalingMode;
this.allowedJoiningTimeMs = allowedJoiningTimeMs;
this.maxDroppedFrameCountToNotify = maxDroppedFrameCountToNotify;
......@@ -169,11 +169,6 @@ public class MediaCodecVideoRenderer extends MediaCodecRenderer {
}
@Override
public int getTrackType() {
return C.TRACK_TYPE_VIDEO;
}
@Override
protected int supportsFormat(MediaCodecSelector mediaCodecSelector, Format format)
throws DecoderQueryException {
String mimeType = format.sampleMimeType;
......@@ -235,8 +230,8 @@ public class MediaCodecVideoRenderer extends MediaCodecRenderer {
}
@Override
protected void onReset(long positionUs, boolean joining) throws ExoPlaybackException {
super.onReset(positionUs, joining);
protected void onPositionReset(long positionUs, boolean joining) throws ExoPlaybackException {
super.onPositionReset(positionUs, joining);
renderedFirstFrame = false;
consecutiveDroppedFrameCount = 0;
joiningDeadlineMs = joining && allowedJoiningTimeMs > 0
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or sign in to comment