OverlaySettings.java
package androidx.media3.effect;
/*
* Copyright 2022 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import static androidx.media3.common.util.Assertions.checkArgument;
import android.util.Pair;
import androidx.annotation.FloatRange;
import androidx.media3.common.util.GlUtil;
import androidx.media3.common.util.UnstableApi;
import com.google.errorprone.annotations.CanIgnoreReturnValue;
/** Contains information to control how an {@link TextureOverlay} is displayed on the screen. */
@UnstableApi
public final class OverlaySettings {
public final boolean useHdr;
public final float alpha;
public final float[] matrix;
public final Pair<Float, Float> anchor;
private OverlaySettings(boolean useHdr, float alpha, float[] matrix, Pair<Float, Float> anchor) {
this.useHdr = useHdr;
this.alpha = alpha;
this.matrix = matrix;
this.anchor = anchor;
}
/** A builder for {@link OverlaySettings} instances. */
public static final class Builder {
private boolean useHdr;
private float alpha;
private float[] matrix;
private Pair<Float, Float> anchor;
/** Creates a new {@link Builder}. */
public Builder() {
alpha = 1f;
matrix = GlUtil.create4x4IdentityMatrix();
anchor = Pair.create(0f, 0f);
}
/**
* Sets whether input overlay comes from an HDR source. If {@code true}, colors will be in
* linear RGB BT.2020. If {@code false}, colors will be in linear RGB BT.709.
*
* <p>Set to {@code false} by default.
*/
@CanIgnoreReturnValue
public Builder setUsesHdr(boolean useHdr) {
this.useHdr = useHdr;
return this;
}
/**
* Sets the {@link android.opengl.Matrix} used to transform the overlay before applying it to a
* frame.
*
* <p>Set to always return the identity matrix by default.
*/
@CanIgnoreReturnValue
public Builder setMatrix(float[] matrix) {
this.matrix = matrix;
return this;
}
/**
* Sets the alpha value of the overlay, altering its transparency.
*
* <p>Alpha values range from 0 (all transparent) to 1 (completely opaque).
*
* <p>Set to always return {@code 1} by default.
*/
@CanIgnoreReturnValue
public Builder setAlpha(@FloatRange(from = 0, to = 1) float alpha) {
checkArgument(0 <= alpha && alpha <= 1, "Alpha needs to be in the interval [0, 1].");
this.alpha = alpha;
return this;
}
/**
* Sets the coordinates for the anchor point of the overlay.
*
* <p>The anchor point is the point inside the overlay that the overlay is positioned from.
*
* <p>The coordinates are specified in Normalised Device Coordinates (NDCs). Set to always
* return {@code (0,0)} (the center) by default.
*
* @param x The NDC x-coordinate in the range [-1, 1].
* @param y The NDC y-coordinate in the range [-1, 1].
*/
@CanIgnoreReturnValue
public Builder setAnchor(
@FloatRange(from = -1, to = 1) float x, @FloatRange(from = -1, to = 1) float y) {
checkArgument(-1 <= x && x <= 1);
checkArgument(-1 <= y && y <= 1);
this.anchor = Pair.create(x, y);
return this;
}
/** Creates an instance of {@link OverlaySettings}, using defaults if values are unset. */
public OverlaySettings build() {
return new OverlaySettings(useHdr, alpha, matrix, anchor);
}
}
}