From a0bc8d95c2352a79df66121259b25f04f43e07b1 Mon Sep 17 00:00:00 2001 From: andrewlewis Date: Fri, 7 Jul 2023 17:32:56 +0100 Subject: [PATCH] Improve texture asset loader documentation Add documentation for threading requirements at the class level (in addition to existing documentation on the methods) to improve discoverablility. Also fix a couple of nits in the javadoc (US English spelling, avoid passive voice) and in `OnInputFrameProcessedListener`. PiperOrigin-RevId: 546303732 --- .../common/OnInputFrameProcessedListener.java | 8 +++++--- .../media3/transformer/TextureAssetLoader.java | 13 ++++++++++--- 2 files changed, 15 insertions(+), 6 deletions(-) diff --git a/libraries/common/src/main/java/androidx/media3/common/OnInputFrameProcessedListener.java b/libraries/common/src/main/java/androidx/media3/common/OnInputFrameProcessedListener.java index 7e82f58174..fbdf7c675c 100644 --- a/libraries/common/src/main/java/androidx/media3/common/OnInputFrameProcessedListener.java +++ b/libraries/common/src/main/java/androidx/media3/common/OnInputFrameProcessedListener.java @@ -25,10 +25,12 @@ public interface OnInputFrameProcessedListener { * Called when the given input frame has been processed. * * @param textureId The identifier of the processed texture. - * @param syncObject A GL sync object that has been inserted into the GL command stream after the - * last write of texture. Value is 0 if and only if the {@code GLES30#glFenceSync} failed or - * the EGL context version is less than openGL 3.0. The sync object must be {@link + * @param syncObject A GL sync object (see https://www.khronos.org/opengl/wiki/Sync_Object) that + * has been inserted into the GL command stream after the last use of the texture. Value is 0 + * if and only if the {@code GLES30#glFenceSync} failed or the EGL context version is less + * than OpenGL 3.0. The sync object must be {@link * androidx.media3.common.util.GlUtil#deleteSyncObject deleted} after use. + * @throws VideoFrameProcessingException Thrown if an error was encountered handling the event. */ void onInputFrameProcessed(int textureId, long syncObject) throws VideoFrameProcessingException; } diff --git a/libraries/transformer/src/main/java/androidx/media3/transformer/TextureAssetLoader.java b/libraries/transformer/src/main/java/androidx/media3/transformer/TextureAssetLoader.java index d97caba878..f7917926ce 100644 --- a/libraries/transformer/src/main/java/androidx/media3/transformer/TextureAssetLoader.java +++ b/libraries/transformer/src/main/java/androidx/media3/transformer/TextureAssetLoader.java @@ -36,9 +36,9 @@ import org.checkerframework.checker.nullness.qual.MonotonicNonNull; * android.opengl.GLES10#GL_TEXTURE_2D traditional GLES texture} instances. * *

Typically instantiated in a custom {@link AssetLoader.Factory} saving a reference to the - * created {@link TextureAssetLoader}. Input is provided calling {@link #queueInputTexture} to - * provide all the video frames, then {@link #signalEndOfVideoInput() signalling the end of input} - * when finished. + * created {@link TextureAssetLoader}. Provide video frames as input by calling {@link + * #queueInputTexture}, then {@link #signalEndOfVideoInput() signal the end of input} when finished. + * Those methods must be called from the same thread, which can be any thread. */ @UnstableApi public final class TextureAssetLoader implements AssetLoader { @@ -59,6 +59,13 @@ public final class TextureAssetLoader implements AssetLoader { * *

The {@link EditedMediaItem#durationUs}, {@link Format#width} and {@link Format#height} must * be set. + * + * @param editedMediaItem Information about the media item for which frames are provided. + * @param assetLoaderListener Listener for asset loading events. + * @param format Information about the format of video frames. + * @param frameProcessedListener Listener for the event when a frame has been processed. The + * listener receives a GL sync object (if supported) to allow reusing the texture after it's + * no longer in use. */ public TextureAssetLoader( EditedMediaItem editedMediaItem,