BaseGlShaderProgram

Kotlin |Java

@UnstableApi
public abstract class BaseGlShaderProgram implements GlShaderProgram

A base implementation of GlShaderProgram.

BaseGlShaderProgram manages an output texture pool, whose size is configurable on construction. An implementation should manage a GLSL shader program for processing frames. Override drawFrame to customize drawing. Implementations generally copy input pixels into an output frame, with changes to pixels specific to the implementation.

BaseShaderProgram implementations can produce any number of output frames per input frame with the same presentation timestamp.

All methods in this class must be called on the thread that owns the OpenGL context.

Summary

Protected fields
`GlShaderProgram.InputListener`	`inputListener`
`GlShaderProgram.OutputListener`	`outputListener`
`final TexturePool`	`outputTexturePool`

Public constructors
`BaseGlShaderProgram( boolean useHighPrecisionColorComponents, int texturePoolCapacity )` Creates a `BaseGlShaderProgram` instance.

Public methods
`abstract Size`	`configure(int inputWidth, int inputHeight)` Configures the instance based on the input dimensions.
`abstract void`	`drawFrame(int inputTexId, long presentationTimeUs)` Draws one frame.
`void`	`@CallSuper flush()` Flushes the `GlShaderProgram`.
`void`	`queueInputFrame( GlObjectsProvider glObjectsProvider, GlTextureInfo inputTexture, long presentationTimeUs )` Processes an input frame if possible.
`void`	`@CallSuper release()` Releases all resources.
`void`	`releaseOutputFrame(GlTextureInfo outputTexture)` Notifies the `GlShaderProgram` that the frame on the given output texture is no longer used and can be overwritten.
`void`	`setErrorListener( Executor errorListenerExecutor, GlShaderProgram.ErrorListener errorListener )` Sets the `ErrorListener`.
`void`	`setInputListener(GlShaderProgram.InputListener inputListener)` Sets the `InputListener`.
`void`	`setOutputListener(GlShaderProgram.OutputListener outputListener)` Sets the `OutputListener`.
`boolean`	`shouldClearTextureBuffer()` Returns `true` if the texture buffer should be cleared before calling `drawFrame` or `false` if it should retain the content of the last drawn frame.
`void`	`signalEndOfCurrentInputStream()` Notifies the `GlShaderProgram` that no further input frames belonging to the current input stream will be queued.

Protected methods
`final GlShaderProgram.InputListener`	`getInputListener()`
`final GlShaderProgram.OutputListener`	`getOutputListener()`
`final void`	`onError(Exception e)`

Protected fields

inputListener

protected GlShaderProgram.InputListener inputListener

outputListener

protected GlShaderProgram.OutputListener outputListener

outputTexturePool

protected final TexturePool outputTexturePool

Public constructors

BaseGlShaderProgram

public BaseGlShaderProgram(
    boolean useHighPrecisionColorComponents,
    int texturePoolCapacity
)

Creates a BaseGlShaderProgram instance.

Parameters
`boolean useHighPrecisionColorComponents`	If `false`, uses colors with 8-bit unsigned bytes. If `true`, use 16-bit (half-precision) floating-point.
`int texturePoolCapacity`	The capacity of the texture pool. For example, if implementing a texture cache, the size should be the number of textures to cache.

Public methods

configure

public abstract Size configure(int inputWidth, int inputHeight)

Configures the instance based on the input dimensions.

This method must be called before drawing the first frame and before drawing subsequent frames with different input dimensions.

Parameters
`int inputWidth`	The input width, in pixels.
`int inputHeight`	The input height, in pixels.

Returns
`Size`	The output width and height of frames processed through `drawFrame`.

Throws
`androidx.media3.common.VideoFrameProcessingException`	If an error occurs while configuring.

drawFrame

public abstract void drawFrame(int inputTexId, long presentationTimeUs)

Draws one frame.

This method may only be called after the shader program has been configured. The caller is responsible for focussing the correct render target before calling this method.

A minimal implementation should tell OpenGL to use its shader program, bind the shader program's vertex attributes and uniforms, and issue a drawing command.

Parameters
`int inputTexId`	Identifier of a 2D OpenGL texture containing the input frame.
`long presentationTimeUs`	The presentation timestamp of the current frame, in microseconds.

Throws
`androidx.media3.common.VideoFrameProcessingException`	If an error occurs while processing or drawing the frame.

flush

@CallSuper
public void flush()

Flushes the GlShaderProgram.

The GlShaderProgram should reclaim the ownership of its allocated textures, notify its InputListener about the flush event, and report its availability if necessary.

The implementation must not output frames until after this method returns.

queueInputFrame

public void queueInputFrame(
    GlObjectsProvider glObjectsProvider,
    GlTextureInfo inputTexture,
    long presentationTimeUs
)

Processes an input frame if possible.

The GlShaderProgram owns the accepted frame until it calls onInputFrameProcessed. The caller should not overwrite or release the texture before the GlShaderProgram has finished processing it.

This method must only be called when the GlShaderProgram can accept an input frame.

Parameters
`GlObjectsProvider glObjectsProvider`	The `GlObjectsProvider` for using EGL and GLES.
`GlTextureInfo inputTexture`	A `GlTextureInfo` describing the texture containing the input frame.
`long presentationTimeUs`	The presentation timestamp of the input frame, in microseconds.

release

@CallSuper
public void release()

Releases all resources.

Throws
`androidx.media3.common.VideoFrameProcessingException`	If an error occurs while releasing resources.

releaseOutputFrame

public void releaseOutputFrame(GlTextureInfo outputTexture)

Notifies the GlShaderProgram that the frame on the given output texture is no longer used and can be overwritten.

setErrorListener

public void setErrorListener(
    Executor errorListenerExecutor,
    GlShaderProgram.ErrorListener errorListener
)

Sets the ErrorListener.

The ErrorListener is invoked on the provided Executor.

setInputListener

public void setInputListener(GlShaderProgram.InputListener inputListener)

Sets the InputListener.

The InputListener should be invoked on the thread that owns the parent OpenGL context. For example, DefaultVideoFrameProcessor invokes the InputListener methods on its internal thread.

setOutputListener

public void setOutputListener(GlShaderProgram.OutputListener outputListener)

Sets the OutputListener.

The OutputListener should be invoked on the thread that owns the parent OpenGL context. For example, DefaultVideoFrameProcessor invokes the OutputListener methods on its internal thread.

shouldClearTextureBuffer

public boolean shouldClearTextureBuffer()

Returns true if the texture buffer should be cleared before calling drawFrame or false if it should retain the content of the last drawn frame.

When returning false, the shader program must clear the texture before first drawing to it, because textures are not zero-initialized when created. This can be done by calling clearFocusedBuffers.

signalEndOfCurrentInputStream

public void signalEndOfCurrentInputStream()

Notifies the GlShaderProgram that no further input frames belonging to the current input stream will be queued.

Input frames that are queued after this method is called belong to a different input stream.

Protected methods

getInputListener

protected final GlShaderProgram.InputListener getInputListener()

getOutputListener

protected final GlShaderProgram.OutputListener getOutputListener()

onError

protected final void onError(Exception e)