public interface Renderer extends ExoPlayer.ExoPlayerComponent
SampleStream
.
Internally, a renderer's lifecycle is managed by the owning ExoPlayer
. The renderer is
transitioned through various states as the overall playback state changes. The valid state
transitions are shown below, annotated with the methods that are called during each transition.
Modifier and Type | Field and Description |
---|---|
static int |
STATE_DISABLED
The renderer is disabled.
|
static int |
STATE_ENABLED
The renderer is enabled but not started.
|
static int |
STATE_STARTED
The renderer is started.
|
Modifier and Type | Method and Description |
---|---|
void |
disable()
Disable the renderer, transitioning it to the
STATE_DISABLED state. |
void |
enable(Format[] formats,
SampleStream stream,
long positionUs,
boolean joining,
long offsetUs)
Enables the renderer to consume from the specified
SampleStream . |
RendererCapabilities |
getCapabilities()
Returns the capabilities of the renderer.
|
MediaClock |
getMediaClock()
If the renderer advances its own playback position then this method returns a corresponding
MediaClock . |
int |
getState()
Returns the current state of the renderer.
|
SampleStream |
getStream()
Returns the
SampleStream being consumed, or null if the renderer is disabled. |
int |
getTrackType()
Returns the track type that the
Renderer handles. |
boolean |
hasReadStreamToEnd()
Returns whether the renderer has read the current
SampleStream to the end. |
boolean |
isEnded()
Whether the renderer is ready for the
ExoPlayer instance to transition to
ExoPlayer.STATE_ENDED . |
boolean |
isReady()
Whether the renderer is able to immediately render media from the current position.
|
void |
maybeThrowStreamError()
Throws an error that's preventing the renderer from reading from its
SampleStream . |
void |
render(long positionUs,
long elapsedRealtimeUs)
Incrementally renders the
SampleStream . |
void |
replaceStream(Format[] formats,
SampleStream stream,
long offsetUs)
Replaces the
SampleStream from which samples will be consumed. |
void |
resetPosition(long positionUs)
Signals to the renderer that a position discontinuity has occurred.
|
void |
setCurrentStreamIsFinal()
Signals to the renderer that the current
SampleStream will be the final one supplied
before it is next disabled or reset. |
void |
setIndex(int index)
Sets the index of this renderer within the player.
|
void |
start()
Starts the renderer, meaning that calls to
render(long, long) will cause media to be
rendered. |
void |
stop()
Stops the renderer, transitioning it to the
STATE_ENABLED state. |
handleMessage
static final int STATE_DISABLED
static final int STATE_ENABLED
static final int STATE_STARTED
render(long, long)
will cause media to be rendered.int getTrackType()
Renderer
handles. For example, a video renderer will
return C.TRACK_TYPE_VIDEO
, an audio renderer will return C.TRACK_TYPE_AUDIO
, a
text renderer will return C.TRACK_TYPE_TEXT
, and so on.TRACK_TYPE_*
constants defined in C
.RendererCapabilities getCapabilities()
void setIndex(int index)
index
- The renderer index.MediaClock getMediaClock()
MediaClock
. If provided, the player will use the returned MediaClock
as its
source of time during playback. A player may have at most one renderer that returns a
MediaClock
from this method.MediaClock
tracking the playback position of the renderer, or null.int getState()
STATE_*
constants).void enable(Format[] formats, SampleStream stream, long positionUs, boolean joining, long offsetUs) throws ExoPlaybackException
SampleStream
.
This method may be called when the renderer is in the following states:
STATE_DISABLED
.
formats
- The enabled formats.stream
- The SampleStream
from which the renderer should consume.positionUs
- The player's current position.joining
- Whether this renderer is being enabled to join an ongoing playback.offsetUs
- The offset to be added to timestamps of buffers read from stream
before they are rendered.ExoPlaybackException
- If an error occurs.void start() throws ExoPlaybackException
render(long, long)
will cause media to be
rendered.
This method may be called when the renderer is in the following states:
STATE_ENABLED
.
ExoPlaybackException
- If an error occurs.void replaceStream(Format[] formats, SampleStream stream, long offsetUs) throws ExoPlaybackException
SampleStream
from which samples will be consumed.
This method may be called when the renderer is in the following states:
STATE_ENABLED
, STATE_STARTED
.
formats
- The enabled formats.stream
- The SampleStream
from which the renderer should consume.offsetUs
- The offset to be added to timestamps of buffers read from stream
before
they are rendered.ExoPlaybackException
- If an error occurs.SampleStream getStream()
SampleStream
being consumed, or null if the renderer is disabled.boolean hasReadStreamToEnd()
SampleStream
to the end.
This method may be called when the renderer is in the following states:
STATE_ENABLED
, STATE_STARTED
.
void setCurrentStreamIsFinal()
SampleStream
will be the final one supplied
before it is next disabled or reset.
This method may be called when the renderer is in the following states:
STATE_ENABLED
, STATE_STARTED
.
void maybeThrowStreamError() throws IOException
SampleStream
. Does
nothing if no such error exists.
This method may be called when the renderer is in the following states:
STATE_ENABLED
, STATE_STARTED
.
IOException
- An error that's preventing the renderer from making progress or buffering
more data.void resetPosition(long positionUs) throws ExoPlaybackException
After a position discontinuity, the renderer's SampleStream
is guaranteed to provide
samples starting from a key frame.
This method may be called when the renderer is in the following states:
STATE_ENABLED
, STATE_STARTED
.
positionUs
- The new playback position in microseconds.ExoPlaybackException
- If an error occurs handling the reset.void render(long positionUs, long elapsedRealtimeUs) throws ExoPlaybackException
SampleStream
.
If the renderer is in the STATE_ENABLED
state then each call to this method will do
work toward being ready to render the 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 STATE_STARTED
state then calls to this method will render the
SampleStream
in sync with the specified media positions.
This method should return quickly, and should not block if the renderer is unable to make useful progress.
This method may be called when the renderer is in the following states:
STATE_ENABLED
, STATE_STARTED
.
positionUs
- The current media time in microseconds, measured at the start of the
current iteration of the rendering loop.elapsedRealtimeUs
- SystemClock.elapsedRealtime()
in microseconds,
measured at the start of the current iteration of the rendering loop.ExoPlaybackException
- If an error occurs.boolean isReady()
If the renderer is in the STATE_STARTED
state then returning true indicates that the
renderer has everything that it needs to continue playback. Returning false indicates that
the player should pause until the renderer is ready.
If the renderer is in the STATE_ENABLED
state then returning true indicates that the
renderer is ready for playback to be started. Returning false indicates that it is not.
This method may be called when the renderer is in the following states:
STATE_ENABLED
, STATE_STARTED
.
boolean isEnded()
ExoPlayer
instance to transition to
ExoPlayer.STATE_ENDED
. The player will make this transition as soon as true
is
returned by all of its Renderer
s.
This method may be called when the renderer is in the following states:
STATE_ENABLED
, STATE_STARTED
.
void stop() throws ExoPlaybackException
STATE_ENABLED
state.
This method may be called when the renderer is in the following states:
STATE_STARTED
.
ExoPlaybackException
- If an error occurs.void disable()
STATE_DISABLED
state.
This method may be called when the renderer is in the following states:
STATE_ENABLED
.