loliball/media3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add additional documentation regarding resource acquisition.

Browse Source 
The main point of the IDLE state is that the player is not holding
resources. Clarify this in the documentation of STATE_IDLE, prepare and
stop.

PiperOrigin-RevId: 409950785
This commit is contained in:
tonihei 2021-11-15 13:16:47 +00:00 committed by Ian Baker
parent 471b27bf10
commit c0ffeb262c
1 changed files with 15 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
libraries/common/src/main/java/androidx/media3/common/Player.java
View File

@ -1091,7 +1091,10 @@ public interface Player {
@Target({FIELD, METHOD, PARAMETER, LOCAL_VARIABLE, TYPE_USE})
@IntDef({STATE_IDLE, STATE_BUFFERING, STATE_READY, STATE_ENDED})
@interface State {}
/** The player is idle, and must be {@link #prepare() prepared} before it will play the media. */
/**
* The player is idle, meaning it holds only limited resources. The player must be {@link
* #prepare() prepared} before it will play the media.
*/
int STATE_IDLE = 1;
/**
* The player is not able to immediately play the media, but is doing work toward being able to do
@ -1674,7 +1677,12 @@ public interface Player {
*/
Commands getAvailableCommands();
/** Prepares the player. */
/**
* Prepares the player.
*
* <p>This will move the player out of {@link #STATE_IDLE idle state} and the player will start
* loading media and acquire resources needed for playback.
*/
void prepare();
/**
@ -2014,12 +2022,13 @@ public interface Player {
PlaybackParameters getPlaybackParameters();
/**
* Stops playback without resetting the player. Use {@link #pause()} rather than this method if
* Stops playback without resetting the playlist. Use {@link #pause()} rather than this method if
* the intention is to pause playback.
*
* <p>Calling this method will cause the playback state to transition to {@link #STATE_IDLE}. The
* player instance can still be used, and {@link #release()} must still be called on the player if
* it's no longer required.
* <p>Calling this method will cause the playback state to transition to {@link #STATE_IDLE} and
* the player will release the loaded media and resources required for playback. The player
* instance can still be used by calling {@link #prepare()} again, and {@link #release()} must
* still be called on the player if it's no longer required.
*
* <p>Calling this method does not clear the playlist, reset the playback position or the playback
* error.