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

Effect: Add some FrameProcessor javadoc.

Browse Source 
In particular, make it a bit more clear that "rendering" and "releasing" frames are
related concepts, and how they differ from one another in conjunction with frame
dropping.

PiperOrigin-RevId: 471037733
This commit is contained in:
huangdarwin 2022-08-30 18:01:11 +00:00 committed by Marc Baechinger
parent a8e814abbd
commit e6a1936ba9
1 changed files with 14 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
library/common/src/main/java/androidx/media3/common/FrameProcessor.java
View File

@ -23,10 +23,10 @@ import java.util.List;
/** /**
* Interface for a frame processor that applies changes to individual video frames. * Interface for a frame processor that applies changes to individual video frames.
* *
* <p>The changes are specified by {@link Effect} instances passed to the {@link Factory}. * <p>The changes are specified by {@link Effect} instances passed to {@link Factory#create}.
* *
* <p>The frame processor manages its input {@link Surface} which can be accessed via {@link * <p>Manages its input {@link Surface}, which can be accessed via {@link #getInputSurface()}. The
* #getInputSurface()}. The output {@link Surface} must be set by the caller using {@link * output {@link Surface} must be set by the caller using {@link
* #setOutputSurfaceInfo(SurfaceInfo)}. * #setOutputSurfaceInfo(SurfaceInfo)}.
* *
* <p>The caller must {@linkplain #registerInputFrame() register} input frames before rendering them * <p>The caller must {@linkplain #registerInputFrame() register} input frames before rendering them
@ -45,10 +45,11 @@ public interface FrameProcessor {
* @param effects The {@link Effect} instances to apply to each frame. * @param effects The {@link Effect} instances to apply to each frame.
* @param debugViewProvider A {@link DebugViewProvider}. * @param debugViewProvider A {@link DebugViewProvider}.
* @param colorInfo The {@link ColorInfo} for input and output frames. * @param colorInfo The {@link ColorInfo} for input and output frames.
* @param releaseFramesAutomatically If {@code true}, the {@link FrameProcessor} will release * @param releaseFramesAutomatically If {@code true}, the {@link FrameProcessor} will render
* output frames to the {@linkplain #setOutputSurfaceInfo(SurfaceInfo) output surface} * output frames to the {@linkplain #setOutputSurfaceInfo(SurfaceInfo) output surface}
* automatically as they become available. If {@code false}, the {@link FrameProcessor} will * automatically as {@link FrameProcessor} is done processing them. If {@code false}, the
* wait to release each frame until {@link #releaseOutputFrame(long)} is called. * {@link FrameProcessor} will block until {@link #releaseOutputFrame(long)} is called, to
* render or drop the frame.
* @return A new instance. * @return A new instance.
* @throws FrameProcessingException If a problem occurs while creating the {@link * @throws FrameProcessingException If a problem occurs while creating the {@link
* FrameProcessor}. * FrameProcessor}.
@ -97,7 +98,7 @@ public interface FrameProcessor {
void onFrameProcessingEnded(); void onFrameProcessingEnded();
} }
/** Returns the input {@link Surface}. */ /** Returns the input {@link Surface}, where {@link FrameProcessor} consumes input frames from. */
Surface getInputSurface(); Surface getInputSurface();
/** /**
@ -131,11 +132,12 @@ public interface FrameProcessor {
int getPendingInputFrameCount(); int getPendingInputFrameCount();
/** /**
* Sets the output surface and supporting information. * Sets the output surface and supporting information. When output frames are released and not
* dropped, they will be rendered to this output {@link SurfaceInfo}.
* *
* <p>The new output {@link SurfaceInfo} is applied from the next output frame rendered onwards. * <p>The new output {@link SurfaceInfo} is applied from the next output frame rendered onwards.
* If the output {@link SurfaceInfo} is {@code null}, the {@code FrameProcessor} will stop * If the output {@link SurfaceInfo} is {@code null}, the {@code FrameProcessor} will stop
* rendering and resume rendering pending frames once a non-null {@link SurfaceInfo} is set. * rendering pending frames and resume rendering once a non-null {@link SurfaceInfo} is set.
* *
* <p>If the dimensions given in {@link SurfaceInfo} do not match the {@linkplain * <p>If the dimensions given in {@link SurfaceInfo} do not match the {@linkplain
* Listener#onOutputSizeChanged(int,int) output size after applying the final effect} the frames * Listener#onOutputSizeChanged(int,int) output size after applying the final effect} the frames
@ -151,6 +153,9 @@ public interface FrameProcessor {
* Releases the oldest unreleased output frame that has become {@linkplain * Releases the oldest unreleased output frame that has become {@linkplain
* Listener#onOutputFrameAvailable(long) available} at the given {@code releaseTimeNs}. * Listener#onOutputFrameAvailable(long) available} at the given {@code releaseTimeNs}.
* *
* <p>This will either render the output frame to the {@linkplain #setOutputSurfaceInfo output
* surface}, or drop the frame, per {@code releaseTimeNs}.
*
* <p>This method must only be called if {@code releaseFramesAutomatically} was set to {@code * <p>This method must only be called if {@code releaseFramesAutomatically} was set to {@code
* false} using the {@link Factory} and should be called exactly once for each frame that becomes * false} using the {@link Factory} and should be called exactly once for each frame that becomes
* {@linkplain Listener#onOutputFrameAvailable(long) available}. * {@linkplain Listener#onOutputFrameAvailable(long) available}.