Package com.google.android.exoplayer2.video

## Class DecoderVideoRenderer

- java.lang.Object
- - com.google.android.exoplayer2.BaseRenderer
  - - com.google.android.exoplayer2.video.DecoderVideoRenderer

- All Implemented Interfaces:
    `PlayerMessage.Target`, `Renderer`, `RendererCapabilities`
  Direct Known Subclasses:
    `Libgav1VideoRenderer`, `LibvpxVideoRenderer`

      public abstract class DecoderVideoRenderer
      extends BaseRenderer

  Decodes and renders video using a `Decoder`.

  This renderer accepts the following messages sent via `ExoPlayer.createMessage(PlayerMessage.Target)` on the playback thread:

  - Message with type `Renderer.MSG_SET_VIDEO_OUTPUT` to set the output surface. The message payload should be the target `Surface` or `VideoDecoderOutputBufferRenderer`, or null. Other non-null payloads have the effect of clearing the output.
  - Message with type `Renderer.MSG_SET_VIDEO_FRAME_METADATA_LISTENER` to set a listener for metadata associated with frames being rendered. The message payload should be the `VideoFrameMetadataListener`, or null.

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from interface com.google.android.exoplayer2.Renderer

      `Renderer.MessageType, Renderer.State, Renderer.WakeupListener`

    - ### Nested classes/interfaces inherited from interface com.google.android.exoplayer2.RendererCapabilities

      `RendererCapabilities.AdaptiveSupport, RendererCapabilities.Capabilities, RendererCapabilities.DecoderSupport, RendererCapabilities.FormatSupport, RendererCapabilities.HardwareAccelerationSupport, RendererCapabilities.TunnelingSupport`

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected DecoderCounters` | `decoderCounters` | Decoder event counters used for debugging purposes.

    - ### Fields inherited from interface com.google.android.exoplayer2.Renderer

      `MSG_CUSTOM_BASE, MSG_SET_AUDIO_ATTRIBUTES, MSG_SET_AUDIO_SESSION_ID, MSG_SET_AUX_EFFECT_INFO, MSG_SET_CAMERA_MOTION_LISTENER, MSG_SET_CHANGE_FRAME_RATE_STRATEGY, MSG_SET_PREFERRED_AUDIO_DEVICE, MSG_SET_SCALING_MODE, MSG_SET_SKIP_SILENCE_ENABLED, MSG_SET_VIDEO_FRAME_METADATA_LISTENER, MSG_SET_VIDEO_OUTPUT, MSG_SET_VOLUME, MSG_SET_WAKEUP_LISTENER, STATE_DISABLED, STATE_ENABLED, STATE_STARTED`

    - ### Fields inherited from interface com.google.android.exoplayer2.RendererCapabilities

      `ADAPTIVE_NOT_SEAMLESS, ADAPTIVE_NOT_SUPPORTED, ADAPTIVE_SEAMLESS, ADAPTIVE_SUPPORT_MASK, DECODER_SUPPORT_FALLBACK, DECODER_SUPPORT_FALLBACK_MIMETYPE, DECODER_SUPPORT_PRIMARY, FORMAT_EXCEEDS_CAPABILITIES, FORMAT_HANDLED, FORMAT_SUPPORT_MASK, FORMAT_UNSUPPORTED_DRM, FORMAT_UNSUPPORTED_SUBTYPE, FORMAT_UNSUPPORTED_TYPE, HARDWARE_ACCELERATION_NOT_SUPPORTED, HARDWARE_ACCELERATION_SUPPORT_MASK, HARDWARE_ACCELERATION_SUPPORTED, MODE_SUPPORT_MASK, TUNNELING_NOT_SUPPORTED, TUNNELING_SUPPORT_MASK, TUNNELING_SUPPORTED`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `DecoderVideoRenderer​(long allowedJoiningTimeMs, Handler eventHandler, VideoRendererEventListener eventListener, int maxDroppedFramesToNotify)` |

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected DecoderReuseEvaluation` | `canReuseDecoder​(String decoderName, Format oldFormat, Format newFormat)` | Evaluates whether the existing decoder can be reused for a new `Format`.
    `protected abstract Decoder<DecoderInputBuffer,​? extends VideoDecoderOutputBuffer,​? extends DecoderException>` | `createDecoder​(Format format, CryptoConfig cryptoConfig)` | Creates a decoder for the given format.
    `protected void` | `dropOutputBuffer​(VideoDecoderOutputBuffer outputBuffer)` | Drops the specified output buffer and releases it.
    `protected void` | `flushDecoder()` | Flushes the decoder.
    `void` | `handleMessage​(@com.google.android.exoplayer2.Renderer.MessageType int messageType, Object message)` | Handles a message delivered to the target.
    `boolean` | `isEnded()` | Whether the renderer is ready for the `ExoPlayer` instance to transition to `Player.STATE_ENDED`.
    `boolean` | `isReady()` | Whether the renderer is able to immediately render media from the current position.
    `protected boolean` | `maybeDropBuffersToKeyframe​(long positionUs)` | Drops frames from the current output buffer to the next keyframe at or before the playback position.
    `protected void` | `onDisabled()` | Called when the renderer is disabled.
    `protected void` | `onEnabled​(boolean joining, boolean mayRenderStartOfStream)` | Called when the renderer is enabled.
    `protected void` | `onInputFormatChanged​(FormatHolder formatHolder)` | Called when a new format is read from the upstream source.
    `protected void` | `onPositionReset​(long positionUs, boolean joining)` | Called when the position is reset.
    `protected void` | `onProcessedOutputBuffer​(long presentationTimeUs)` | Called when an output buffer is successfully processed.
    `protected void` | `onQueueInputBuffer​(DecoderInputBuffer buffer)` | Called immediately before an input buffer is queued into the decoder.
    `protected void` | `onStarted()` | Called when the renderer is started.
    `protected void` | `onStopped()` | Called when the renderer is stopped.
    `protected void` | `onStreamChanged​(Format[] formats, long startPositionUs, long offsetUs)` | Called when the renderer's stream has changed.
    `protected void` | `releaseDecoder()` | Releases the decoder.
    `void` | `render​(long positionUs, long elapsedRealtimeUs)` | Incrementally renders the `SampleStream`.
    `protected void` | `renderOutputBuffer​(VideoDecoderOutputBuffer outputBuffer, long presentationTimeUs, Format outputFormat)` | Renders the specified output buffer.
    `protected abstract void` | `renderOutputBufferToSurface​(VideoDecoderOutputBuffer outputBuffer, Surface surface)` | Renders the specified output buffer to the passed surface.
    `protected abstract void` | `setDecoderOutputMode​(@com.google.android.exoplayer2.C.VideoOutputMode int outputMode)` | Sets output mode of the decoder.
    `protected void` | `setOutput​(Object output)` | Sets the video output.
    `protected boolean` | `shouldDropBuffersToKeyframe​(long earlyUs, long elapsedRealtimeUs)` | Returns whether to drop all buffers from the buffer being processed to the keyframe at or after the current playback position, if possible.
    `protected boolean` | `shouldDropOutputBuffer​(long earlyUs, long elapsedRealtimeUs)` | Returns whether the buffer being processed should be dropped.
    `protected boolean` | `shouldForceRenderOutputBuffer​(long earlyUs, long elapsedSinceLastRenderUs)` | Returns whether to force rendering an output buffer.
    `protected void` | `skipOutputBuffer​(VideoDecoderOutputBuffer outputBuffer)` | Skips the specified output buffer and releases it.
    `protected void` | `updateDroppedBufferCounters​(int droppedInputBufferCount, int droppedDecoderBufferCount)` | Updates local counters and `decoderCounters` to reflect that buffers were dropped.

    - ### Methods inherited from class com.google.android.exoplayer2.BaseRenderer

      `createRendererException, createRendererException, disable, enable, getCapabilities, getConfiguration, getFormatHolder, getIndex, getLastResetPositionUs, getMediaClock, getPlayerId, getReadingPositionUs, getState, getStream, getStreamFormats, getTrackType, hasReadStreamToEnd, init, isCurrentStreamFinal, isSourceReady, maybeThrowStreamError, onReset, readSource, replaceStream, reset, resetPosition, setCurrentStreamFinal, skipSource, start, stop, supportsMixedMimeTypeAdaptation`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface com.google.android.exoplayer2.Renderer

      `getName, setPlaybackSpeed`

    - ### Methods inherited from interface com.google.android.exoplayer2.RendererCapabilities

      `getName, supportsFormat`

- - ### Field Detail

    - #### decoderCounters

          protected DecoderCounters decoderCounters

      Decoder event counters used for debugging purposes.

  - ### Constructor Detail

    - #### DecoderVideoRenderer

          protected DecoderVideoRenderer​(long allowedJoiningTimeMs,
                                         @Nullable
                                         Handler eventHandler,
                                         @Nullable
                                         VideoRendererEventListener eventListener,
                                         int maxDroppedFramesToNotify)

      Parameters:
        `allowedJoiningTimeMs` - The maximum duration in milliseconds for which this video renderer can attempt to seamlessly join an ongoing playback.
        `eventHandler` - A handler to use when delivering events to `eventListener`. May be null if delivery of events is not required.
        `eventListener` - A listener of events. May be null if delivery of events is not required.
        `maxDroppedFramesToNotify` - The maximum number of frames that can be dropped between invocations of `VideoRendererEventListener.onDroppedFrames(int, long)`.

  - ### Method Detail

    - #### render

          public void render​(long positionUs,
                             long elapsedRealtimeUs)
                      throws ExoPlaybackException

      Description copied from interface: `Renderer`
      Incrementally renders the `SampleStream`.

      If the renderer is in the `Renderer.STATE_ENABLED` state then each call to this method will do work toward being ready to render the `SampleStream` when the renderer is started. If the renderer is in the `Renderer.STATE_STARTED` state then calls to this method will render the `SampleStream` in sync with the specified media positions.

      The renderer may also render the very start of the media at the current position (e.g. the first frame of a video stream) while still in the `Renderer.STATE_ENABLED` state, unless it's the initial start of the media after calling `Renderer.enable(RendererConfiguration, Format[], SampleStream, long, boolean, boolean, long, long)` with `mayRenderStartOfStream` set to `false`.

      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: `Renderer.STATE_ENABLED`, `Renderer.STATE_STARTED`.

      Parameters:
        `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.
      Throws:
        `ExoPlaybackException` - If an error occurs.

    - #### isEnded

          public boolean isEnded()

      Description copied from interface: `Renderer`
      Whether the renderer is ready for the `ExoPlayer` instance to transition to `Player.STATE_ENDED`. The player will make this transition as soon as `true` is returned by all of its renderers.

      This method may be called when the renderer is in the following states: `Renderer.STATE_ENABLED`, `Renderer.STATE_STARTED`.

      Returns:
        Whether the renderer is ready for the player to transition to the ended state.

    - #### isReady

          public boolean isReady()

      Description copied from interface: `Renderer`
      Whether the renderer is able to immediately render media from the current position.

      If the renderer is in the `Renderer.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 `Renderer.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: `Renderer.STATE_ENABLED`, `Renderer.STATE_STARTED`.

      Returns:
        Whether the renderer is ready to render media.

    - #### handleMessage

          public void handleMessage​(@com.google.android.exoplayer2.Renderer.MessageType int messageType,
                                    @Nullable
                                    Object message)
                             throws ExoPlaybackException

      Description copied from interface: `PlayerMessage.Target`
      Handles a message delivered to the target.
      Specified by:
        `handleMessage` in interface `PlayerMessage.Target`
      Overrides:
        `handleMessage` in class `BaseRenderer`
      Parameters:
        `messageType` - The message type.
        `message` - The message payload.
      Throws:
        `ExoPlaybackException` - If an error occurred whilst handling the message. Should only be thrown by targets that handle messages on the playback thread.

    - #### onEnabled

          protected void onEnabled​(boolean joining,
                                   boolean mayRenderStartOfStream)
                            throws ExoPlaybackException

      Description copied from class: `BaseRenderer`
      Called when the renderer is enabled.

      The default implementation is a no-op.

      Overrides:
        `onEnabled` in class `BaseRenderer`
      Parameters:
        `joining` - Whether this renderer is being enabled to join an ongoing playback.
        `mayRenderStartOfStream` - Whether this renderer is allowed to render the start of the stream even if the state is not `Renderer.STATE_STARTED` yet.
      Throws:
        `ExoPlaybackException` - If an error occurs.

    - #### onPositionReset

          protected void onPositionReset​(long positionUs,
                                         boolean joining)
                                  throws ExoPlaybackException

      Description copied from class: `BaseRenderer`
      Called when the position is reset. This occurs when the renderer is enabled after `BaseRenderer.onStreamChanged(Format[], long, long)` has been called, and also when a position discontinuity is encountered.

      After a position reset, the renderer's `SampleStream` is guaranteed to provide samples starting from a key frame.

      The default implementation is a no-op.

      Overrides:
        `onPositionReset` in class `BaseRenderer`
      Parameters:
        `positionUs` - The new playback position in microseconds.
        `joining` - Whether this renderer is being enabled to join an ongoing playback.
      Throws:
        `ExoPlaybackException` - If an error occurs.

    - #### onStarted

          protected void onStarted()

      Description copied from class: `BaseRenderer`
      Called when the renderer is started.

      The default implementation is a no-op.

      Overrides:
        `onStarted` in class `BaseRenderer`

    - #### onStopped

          protected void onStopped()

      Description copied from class: `BaseRenderer`
      Called when the renderer is stopped.

      The default implementation is a no-op.

      Overrides:
        `onStopped` in class `BaseRenderer`

    - #### onDisabled

          protected void onDisabled()

      Description copied from class: `BaseRenderer`
      Called when the renderer is disabled.

      The default implementation is a no-op.

      Overrides:
        `onDisabled` in class `BaseRenderer`

    - #### onStreamChanged

          protected void onStreamChanged​(Format[] formats,
                                         long startPositionUs,
                                         long offsetUs)
                                  throws ExoPlaybackException

      Description copied from class: `BaseRenderer`
      Called when the renderer's stream has changed. This occurs when the renderer is enabled after `BaseRenderer.onEnabled(boolean, boolean)` has been called, and also when the stream has been replaced whilst the renderer is enabled or started.

      The default implementation is a no-op.

      Overrides:
        `onStreamChanged` in class `BaseRenderer`
      Parameters:
        `formats` - The enabled formats.
        `startPositionUs` - The start position of the new stream in renderer time (microseconds).
        `offsetUs` - The offset that will be added to the timestamps of buffers read via `BaseRenderer.readSource(com.google.android.exoplayer2.FormatHolder, com.google.android.exoplayer2.decoder.DecoderInputBuffer, @com.google.android.exoplayer2.source.SampleStream.ReadFlags int)` so that decoder input buffers have monotonically increasing timestamps.
      Throws:
        `ExoPlaybackException` - If an error occurs.

    - #### flushDecoder

          @CallSuper
          protected void flushDecoder()
                               throws ExoPlaybackException

      Flushes the decoder.
      Throws:
        `ExoPlaybackException` - If an error occurs reinitializing a decoder.

    - #### releaseDecoder

          @CallSuper
          protected void releaseDecoder()

      Releases the decoder.

    - #### onInputFormatChanged

          @CallSuper
          protected void onInputFormatChanged​(FormatHolder formatHolder)
                                       throws ExoPlaybackException

      Called when a new format is read from the upstream source.
      Parameters:
        `formatHolder` - A `FormatHolder` that holds the new `Format`.
      Throws:
        `ExoPlaybackException` - If an error occurs (re-)initializing the decoder.

    - #### onQueueInputBuffer

          protected void onQueueInputBuffer​(DecoderInputBuffer buffer)

      Called immediately before an input buffer is queued into the decoder.

      The default implementation is a no-op.

      Parameters:
        `buffer` - The buffer that will be queued.

    - #### onProcessedOutputBuffer

          @CallSuper
          protected void onProcessedOutputBuffer​(long presentationTimeUs)

      Called when an output buffer is successfully processed.
      Parameters:
        `presentationTimeUs` - The timestamp associated with the output buffer.

    - #### shouldDropOutputBuffer

          protected boolean shouldDropOutputBuffer​(long earlyUs,
                                                   long elapsedRealtimeUs)

      Returns whether the buffer being processed should be dropped.
      Parameters:
        `earlyUs` - The time until the buffer should be presented in microseconds. A negative value indicates that the buffer is late.
        `elapsedRealtimeUs` - `SystemClock.elapsedRealtime()` in microseconds, measured at the start of the current iteration of the rendering loop.

    - #### shouldDropBuffersToKeyframe

          protected boolean shouldDropBuffersToKeyframe​(long earlyUs,
                                                        long elapsedRealtimeUs)

      Returns whether to drop all buffers from the buffer being processed to the keyframe at or after the current playback position, if possible.
      Parameters:
        `earlyUs` - The time until the current buffer should be presented in microseconds. A negative value indicates that the buffer is late.
        `elapsedRealtimeUs` - `SystemClock.elapsedRealtime()` in microseconds, measured at the start of the current iteration of the rendering loop.

    - #### shouldForceRenderOutputBuffer

          protected boolean shouldForceRenderOutputBuffer​(long earlyUs,
                                                          long elapsedSinceLastRenderUs)

      Returns whether to force rendering an output buffer.
      Parameters:
        `earlyUs` - The time until the current buffer should be presented in microseconds. A negative value indicates that the buffer is late.
        `elapsedSinceLastRenderUs` - The elapsed time since the last output buffer was rendered, in microseconds.
      Returns:
        Returns whether to force rendering an output buffer.

    - #### skipOutputBuffer

          protected void skipOutputBuffer​(VideoDecoderOutputBuffer outputBuffer)

      Skips the specified output buffer and releases it.
      Parameters:
        `outputBuffer` - The output buffer to skip.

    - #### dropOutputBuffer

          protected void dropOutputBuffer​(VideoDecoderOutputBuffer outputBuffer)

      Drops the specified output buffer and releases it.
      Parameters:
        `outputBuffer` - The output buffer to drop.

    - #### maybeDropBuffersToKeyframe

          protected boolean maybeDropBuffersToKeyframe​(long positionUs)
                                                throws ExoPlaybackException

      Drops frames from the current output buffer to the next keyframe at or before the playback position. If no such keyframe exists, as the playback position is inside the same group of pictures as the buffer being processed, returns `false`. Returns `true` otherwise.
      Parameters:
        `positionUs` - The current playback position, in microseconds.
      Returns:
        Whether any buffers were dropped.
      Throws:
        `ExoPlaybackException` - If an error occurs flushing the decoder.

    - #### updateDroppedBufferCounters

          protected void updateDroppedBufferCounters​(int droppedInputBufferCount,
                                                     int droppedDecoderBufferCount)

      Updates local counters and `decoderCounters` to reflect that buffers were dropped.
      Parameters:
        `droppedInputBufferCount` - The number of buffers dropped from the source before being passed to the decoder.
        `droppedDecoderBufferCount` - The number of buffers dropped after being passed to the decoder.

    - #### createDecoder

          protected abstract Decoder<DecoderInputBuffer,​? extends VideoDecoderOutputBuffer,​? extends DecoderException> createDecoder​(Format format,
                                                                                                                                                 @Nullable
                                                                                                                                                 CryptoConfig cryptoConfig)
                                                                                                                                          throws DecoderException

      Creates a decoder for the given format.
      Parameters:
        `format` - The format for which a decoder is required.
        `cryptoConfig` - The `CryptoConfig` object required for decoding encrypted content. May be null and can be ignored if decoder does not handle encrypted content.
      Returns:
        The decoder.
      Throws:
        `DecoderException` - If an error occurred creating a suitable decoder.

    - #### renderOutputBuffer

          protected void renderOutputBuffer​(VideoDecoderOutputBuffer outputBuffer,
                                            long presentationTimeUs,
                                            Format outputFormat)
                                     throws DecoderException

      Renders the specified output buffer.

      The implementation of this method takes ownership of the output buffer and is responsible for calling `VideoDecoderOutputBuffer.release()` either immediately or in the future.

      Parameters:
        `outputBuffer` - `VideoDecoderOutputBuffer` to render.
        `presentationTimeUs` - Presentation time in microseconds.
        `outputFormat` - Output `Format`.
      Throws:
        `DecoderException` - If an error occurs when rendering the output buffer.

    - #### renderOutputBufferToSurface

          protected abstract void renderOutputBufferToSurface​(VideoDecoderOutputBuffer outputBuffer,
                                                              Surface surface)
                                                       throws DecoderException

      Renders the specified output buffer to the passed surface.

      The implementation of this method takes ownership of the output buffer and is responsible for calling `VideoDecoderOutputBuffer.release()` either immediately or in the future.

      Parameters:
        `outputBuffer` - `VideoDecoderOutputBuffer` to render.
        `surface` - Output `Surface`.
      Throws:
        `DecoderException` - If an error occurs when rendering the output buffer.

    - #### setOutput

          protected final void setOutput​(@Nullable
                                         Object output)

      Sets the video output.

    - #### setDecoderOutputMode

          protected abstract void setDecoderOutputMode​(@com.google.android.exoplayer2.C.VideoOutputMode int outputMode)

      Sets output mode of the decoder.
      Parameters:
        `outputMode` - Output mode.

    - #### canReuseDecoder

          protected DecoderReuseEvaluation canReuseDecoder​(String decoderName,
                                                           Format oldFormat,
                                                           Format newFormat)

      Evaluates whether the existing decoder can be reused for a new `Format`.

      The default implementation does not allow decoder reuse.

      Parameters:
        `oldFormat` - The previous format.
        `newFormat` - The new format.
      Returns:
        The result of the evaluation.