@UnstableApi
class Presentation : MatrixTransformation

Controls how a frame is presented with options to set the output resolution and choose how to map the input pixels onto the output frame geometry (for example, by stretching the input frame to match the specified output frame, or fitting the input frame using letterboxing).

The background color of the output frame will be black, with alpha = 0 if applicable.

Summary

Nested types
@Documented
@Retention(value = SOURCE)
@Target(value = TYPE_USE)
@IntDef(value = )
annotation Presentation.Layout

Strategies controlling the layout of input pixels in the output frame.

Constants
const Int

Empty pixels added above and below the input frame (for letterboxing), or to the left and right of the input frame (for pillarboxing), until the desired aspect ratio is achieved.
const Int

Pixels cropped from the input frame, until the desired aspect ratio is achieved.
const Int

Frame stretched larger on the x or y axes to fit the desired aspect ratio.

Public functions
Size!
configure(inputWidth: Int, inputHeight: Int)

Configures the input and output dimensions.
java-static Presentation!
createForAspectRatio(
    aspectRatio: @FloatRange(from = 0, fromInclusive = false) Float,
    @Presentation.Layout layout: Int
)

Creates a new Presentation instance.
java-static Presentation!

Creates a new Presentation instance.
java-static Presentation!
createForWidthAndHeight(
    width: Int,
    height: Int,
    @Presentation.Layout layout: Int
)

Creates a new Presentation instance.
Matrix!
getMatrix(presentationTimeUs: Long)

Returns the 3x3 transformation Matrix to apply to the frame with the given timestamp.
Boolean
isNoOp(inputWidth: Int, inputHeight: Int)

Returns whether a GlEffect applies no change at every timestamp.

Inherited functions
From androidx.media3.effect.GlEffect
abstract GlShaderProgram!
toGlShaderProgram(context: Context!, useHdr: Boolean)

Returns a GlShaderProgram that applies the effect.
From androidx.media3.effect.GlMatrixTransformation
BaseGlShaderProgram!
toGlShaderProgram(context: Context!, useHdr: Boolean)

Returns a GlShaderProgram that applies the effect.
From androidx.media3.effect.MatrixTransformation
FloatArray<Float>!
getGlMatrixArray(presentationTimeUs: Long)

Returns the 4x4 transformation Matrix to apply to the frame with the given timestamp.

Constants

LAYOUT_SCALE_TO_FIT

const val LAYOUT_SCALE_TO_FIT = 0: Int

Empty pixels added above and below the input frame (for letterboxing), or to the left and right of the input frame (for pillarboxing), until the desired aspect ratio is achieved. All input frame pixels will be within the output frame.

When applying:

  • letterboxing, the output width will default to the input width, and the output height will be scaled appropriately.
  • pillarboxing, the output height will default to the input height, and the output width will be scaled appropriately.

LAYOUT_SCALE_TO_FIT_WITH_CROP

const val LAYOUT_SCALE_TO_FIT_WITH_CROP = 1: Int

Pixels cropped from the input frame, until the desired aspect ratio is achieved. Pixels may be cropped either from the bottom and top, or from the left and right sides, of the input frame.

When cropping from the:

  • bottom and top, the output width will default to the input width, and the output height will be scaled appropriately.
  • left and right, the output height will default to the input height, and the output width will be scaled appropriately.

LAYOUT_STRETCH_TO_FIT

const val LAYOUT_STRETCH_TO_FIT = 2: Int

Frame stretched larger on the x or y axes to fit the desired aspect ratio.

When stretching to a:

  • taller aspect ratio, the output width will default to the input width, and the output height will be scaled appropriately.
  • narrower aspect ratio, the output height will default to the input height, and the output width will be scaled appropriately.

Public functions

configure

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

Configures the input and output dimensions.

Must be called before getGlMatrixArray.

Parameters
inputWidth: Int

The input frame width, in pixels.
inputHeight: Int

The input frame height, in pixels.
Returns
Size!

The output frame width and height, in pixels.

createForAspectRatio

java-static fun createForAspectRatio(
    aspectRatio: @FloatRange(from = 0, fromInclusive = false) Float,
    @Presentation.Layout layout: Int
): Presentation!

Creates a new Presentation instance.

The output frame will have the given aspect ratio (width/height ratio). Width or height will be resized to conform to this aspectRatio, given a Layout.

Parameters
aspectRatio: @FloatRange(from = 0, fromInclusive = false) Float

The aspect ratio (width/height ratio) of the output frame. Must be positive.
@Presentation.Layout layout: Int

The layout of the output frame.

createForHeight

java-static fun createForHeight(height: Int): Presentation!

Creates a new Presentation instance.

The output frame will have the given height. Width will scale to preserve the input aspect ratio. For example, a 1920x1440 video can be scaled to 640x480 by passing a height of 480.

Parameters
height: Int

The height of the output frame, in pixels.

createForWidthAndHeight

java-static fun createForWidthAndHeight(
    width: Int,
    height: Int,
    @Presentation.Layout layout: Int
): Presentation!

Creates a new Presentation instance.

The output frame will have the given width and height, given a Layout.

Width and height must be positive integers representing the output frame's width and height.

Parameters
width: Int

The width of the output frame, in pixels.
height: Int

The height of the output frame, in pixels.
@Presentation.Layout layout: Int

The layout of the output frame.

getMatrix

fun getMatrix(presentationTimeUs: Long): Matrix!

Returns the 3x3 transformation Matrix to apply to the frame with the given timestamp.

isNoOp

fun isNoOp(inputWidth: Int, inputHeight: Int): Boolean

Returns whether a GlEffect applies no change at every timestamp.

This can be used as a hint to skip this instance.

Parameters
inputWidth: Int

The input frame width, in pixels.
inputHeight: Int

The input frame height, in pixels.