BaseGlShaderProgram

Kotlin |Java

@UnstableApi
abstract class BaseGlShaderProgram : GlShaderProgram

Known direct subclasses

SingleFrameGlShaderProgram

SingleFrameGlShaderProgram

This class is deprecated.

Use BaseGlShaderProgram instead.

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

Public constructors
`BaseGlShaderProgram( useHighPrecisionColorComponents: Boolean, texturePoolCapacity: Int )` Creates a `BaseGlShaderProgram` instance.

Public functions
`abstract Size!`	`configure(inputWidth: Int, inputHeight: Int)` Configures the instance based on the input dimensions.
`abstract Unit`	`drawFrame(inputTexId: Int, presentationTimeUs: Long)` Draws one frame.
`Unit`	`@CallSuper flush()` Flushes the `GlShaderProgram`.
`Unit`	`queueInputFrame( glObjectsProvider: GlObjectsProvider!, inputTexture: GlTextureInfo!, presentationTimeUs: Long )` Processes an input frame if possible.
`Unit`	`@CallSuper release()` Releases all resources.
`Unit`	`releaseOutputFrame(outputTexture: GlTextureInfo!)` Notifies the `GlShaderProgram` that the frame on the given output texture is no longer used and can be overwritten.
`Unit`	`setErrorListener( errorListenerExecutor: Executor!, errorListener: GlShaderProgram.ErrorListener! )` Sets the `ErrorListener`.
`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.
`Unit`	`signalEndOfCurrentInputStream()` Notifies the `GlShaderProgram` that no further input frames belonging to the current input stream will be queued.

Protected functions
`Unit`	`onError(e: Exception!)`

Protected properties
`GlShaderProgram.InputListener!`	`inputListener`
`GlShaderProgram.OutputListener!`	`outputListener`
`TexturePool!`	`outputTexturePool`

Public constructors

BaseGlShaderProgram

BaseGlShaderProgram(
    useHighPrecisionColorComponents: Boolean,
    texturePoolCapacity: Int
)

Creates a BaseGlShaderProgram instance.

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

Public functions

configure

abstract fun configure(inputWidth: Int, inputHeight: Int): Size!

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
`inputWidth: Int`	The input width, in pixels.
`inputHeight: Int`	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

abstract fun drawFrame(inputTexId: Int, presentationTimeUs: Long): Unit

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
`inputTexId: Int`	Identifier of a 2D OpenGL texture containing the input frame.
`presentationTimeUs: Long`	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
fun flush(): Unit

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

fun queueInputFrame(
    glObjectsProvider: GlObjectsProvider!,
    inputTexture: GlTextureInfo!,
    presentationTimeUs: Long
): Unit

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.
`inputTexture: GlTextureInfo!`	A `GlTextureInfo` describing the texture containing the input frame.
`presentationTimeUs: Long`	The presentation timestamp of the input frame, in microseconds.

release

@CallSuper
fun release(): Unit

Releases all resources.

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

releaseOutputFrame

fun releaseOutputFrame(outputTexture: GlTextureInfo!): Unit

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

setErrorListener

fun setErrorListener(
    errorListenerExecutor: Executor!,
    errorListener: GlShaderProgram.ErrorListener!
): Unit

Sets the ErrorListener.

The ErrorListener is invoked on the provided Executor.

shouldClearTextureBuffer

fun shouldClearTextureBuffer(): Boolean

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

fun signalEndOfCurrentInputStream(): Unit

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 functions

onError

protected fun onError(e: Exception!): Unit

Protected properties

inputListener

protected var inputListener: GlShaderProgram.InputListener!

outputListener

protected var outputListener: GlShaderProgram.OutputListener!

outputTexturePool

protected val outputTexturePool: TexturePool!