Improve documentation of StreamStream/SampleQueue read methods

PiperOrigin-RevId: 357734165

library/core/src/main/java/com/google/android/exoplayer2/BaseRenderer.java

@@ -19,6 +19,7 @@ import static java.lang.Math.max;
 
 import androidx.annotation.Nullable;
 import com.google.android.exoplayer2.decoder.DecoderInputBuffer;
+import com.google.android.exoplayer2.decoder.DecoderInputBuffer.InsufficientCapacityException;
 import com.google.android.exoplayer2.source.SampleStream;
 import com.google.android.exoplayer2.util.Assertions;
 import com.google.android.exoplayer2.util.MediaClock;
@@ -386,6 +387,10 @@ public abstract class BaseRenderer implements Renderer, RendererCapabilities {
    *     it's not changing. A sample will never be read if set to true, however it is still possible
    *     for the end of stream or nothing to be read.
    * @return The status of read, one of {@link SampleStream.ReadDataResult}.
+   * @throws InsufficientCapacityException If the {@code buffer} is not a {@link
+   *     DecoderInputBuffer#isFlagsOnly() flags-only} buffer and has insufficient capacity to hold
+   *     the data of a sample being read. The buffer {@link DecoderInputBuffer#timeUs timestamp} and
+   *     flags are populated if this exception is thrown, but the read position is not advanced.
    */
   @SampleStream.ReadDataResult
   protected final int readSource(

library/core/src/main/java/com/google/android/exoplayer2/source/SampleDataQueue.java

@@ -21,6 +21,7 @@ import androidx.annotation.Nullable;
 import com.google.android.exoplayer2.C;
 import com.google.android.exoplayer2.decoder.CryptoInfo;
 import com.google.android.exoplayer2.decoder.DecoderInputBuffer;
+import com.google.android.exoplayer2.decoder.DecoderInputBuffer.InsufficientCapacityException;
 import com.google.android.exoplayer2.extractor.TrackOutput.CryptoData;
 import com.google.android.exoplayer2.source.SampleQueue.SampleExtrasHolder;
 import com.google.android.exoplayer2.upstream.Allocation;
@@ -120,6 +121,8 @@ import java.util.Arrays;
    *
    * @param buffer The buffer to populate.
    * @param extrasHolder The extras holder whose offset should be read and subsequently adjusted.
+   * @throws InsufficientCapacityException If the {@code buffer} has insufficient capacity to hold
+   *     the data being read.
    */
   public void readToBuffer(DecoderInputBuffer buffer, SampleExtrasHolder extrasHolder) {
     readAllocationNode = readSampleData(readAllocationNode, buffer, extrasHolder, scratch);
@@ -131,6 +134,8 @@ import java.util.Arrays;
    *
    * @param buffer The buffer to populate.
    * @param extrasHolder The extras holder whose offset should be read and subsequently adjusted.
+   * @throws InsufficientCapacityException If the {@code buffer} has insufficient capacity to hold
+   *     the data being peeked.
    */
   public void peekToBuffer(DecoderInputBuffer buffer, SampleExtrasHolder extrasHolder) {
     readSampleData(readAllocationNode, buffer, extrasHolder, scratch);
@@ -259,6 +264,8 @@ import java.util.Arrays;
    * @param scratch A scratch {@link ParsableByteArray}.
    * @return The first {@link AllocationNode} that contains unread bytes after the last byte that
    *     the invocation read.
+   * @throws InsufficientCapacityException If the {@code buffer} has insufficient capacity to hold
+   *     the sample data.
    */
   private static AllocationNode readSampleData(
       AllocationNode allocationNode,

library/core/src/main/java/com/google/android/exoplayer2/source/SampleQueue.java

@@ -27,6 +27,7 @@ import com.google.android.exoplayer2.C;
 import com.google.android.exoplayer2.Format;
 import com.google.android.exoplayer2.FormatHolder;
 import com.google.android.exoplayer2.decoder.DecoderInputBuffer;
+import com.google.android.exoplayer2.decoder.DecoderInputBuffer.InsufficientCapacityException;
 import com.google.android.exoplayer2.drm.DrmInitData;
 import com.google.android.exoplayer2.drm.DrmSession;
 import com.google.android.exoplayer2.drm.DrmSessionEventListener;
@@ -401,14 +402,19 @@ public class SampleQueue implements TrackOutput {
    * @param buffer A {@link DecoderInputBuffer} to populate in the case of reading a sample or the
    *     end of the stream. If the end of the stream has been reached, the {@link
    *     C#BUFFER_FLAG_END_OF_STREAM} flag will be set on the buffer. If a {@link
-   *     DecoderInputBuffer#isFlagsOnly() flags-only} buffer is passed, only the buffer flags may be
-   *     populated by this method and the read position of the queue will not change.
+   *     DecoderInputBuffer#isFlagsOnly() flags-only} buffer is passed and a sample is read, then
+   *     only the buffer {@link DecoderInputBuffer#timeUs timestamp} and flags will be populated,
+   *     and the read position will not be advanced.
    * @param formatRequired Whether the caller requires that the format of the stream be read even if
    *     it's not changing. A sample will never be read if set to true, however it is still possible
    *     for the end of stream or nothing to be read.
    * @param loadingFinished True if an empty queue should be considered the end of the stream.
    * @return The result, which can be {@link C#RESULT_NOTHING_READ}, {@link C#RESULT_FORMAT_READ} or
    *     {@link C#RESULT_BUFFER_READ}.
+   * @throws InsufficientCapacityException If the {@code buffer} is not a {@link
+   *     DecoderInputBuffer#isFlagsOnly() flags-only} buffer and has insufficient capacity to hold
+   *     the data of a sample being read. The buffer {@link DecoderInputBuffer#timeUs timestamp} and
+   *     flags are populated if this exception is thrown, but the read position is not advanced.
    */
   @CallSuper
   public int read(

library/core/src/main/java/com/google/android/exoplayer2/source/SampleStream.java

@@ -19,6 +19,7 @@ import androidx.annotation.IntDef;
 import com.google.android.exoplayer2.C;
 import com.google.android.exoplayer2.FormatHolder;
 import com.google.android.exoplayer2.decoder.DecoderInputBuffer;
+import com.google.android.exoplayer2.decoder.DecoderInputBuffer.InsufficientCapacityException;
 import java.io.IOException;
 import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
@@ -66,13 +67,17 @@ public interface SampleStream {
    * @param buffer A {@link DecoderInputBuffer} to populate in the case of reading a sample or the
    *     end of the stream. If the end of the stream has been reached, the {@link
    *     C#BUFFER_FLAG_END_OF_STREAM} flag will be set on the buffer. If a {@link
-   *     DecoderInputBuffer#isFlagsOnly() flags-only} buffer is passed, then no {@link
-   *     DecoderInputBuffer#data} will be read and the read position of the stream will not change,
-   *     but the flags of the buffer will be populated.
+   *     DecoderInputBuffer#isFlagsOnly() flags-only} buffer is passed and a sample is read, then
+   *     only the buffer {@link DecoderInputBuffer#timeUs timestamp} and flags will be populated,
+   *     and the read position will not be advanced.
    * @param formatRequired Whether the caller requires that the format of the stream be read even if
    *     it's not changing. A sample will never be read if set to true, however it is still possible
    *     for the end of stream or nothing to be read.
    * @return The status of read, one of {@link ReadDataResult}.
+   * @throws InsufficientCapacityException If the {@code buffer} is not a {@link
+   *     DecoderInputBuffer#isFlagsOnly() flags-only} buffer and has insufficient capacity to hold
+   *     the data of a sample being read. The buffer {@link DecoderInputBuffer#timeUs timestamp} and
+   *     flags are populated if this exception is thrown, but the read position is not advanced.
    */
   @ReadDataResult
   int readData(FormatHolder formatHolder, DecoderInputBuffer buffer, boolean formatRequired);