/*
 * Copyright (C) 2016 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.
 */
package androidx.media3.exoplayer;

import static java.lang.annotation.ElementType.TYPE_USE;

import android.annotation.SuppressLint;
import androidx.annotation.IntDef;
import androidx.media3.common.C;
import androidx.media3.common.Format;
import androidx.media3.common.util.UnstableApi;
import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/** Defines the capabilities of a {@link Renderer}. */
@UnstableApi
public interface RendererCapabilities {

  /** Listener for renderer capabilities events. */
  interface Listener {

    /**
     * Called when the renderer capabilities are changed.
     *
     * <p>This method will be called on the playback thread.
     *
     * @param renderer The renderer that has its capabilities changed.
     */
    void onRendererCapabilitiesChanged(Renderer renderer);
  }

  /** A mask to apply to {@link Capabilities} to obtain the {@link C.FormatSupport} only. */
  int FORMAT_SUPPORT_MASK = 0b111;

  /**
   * Level of renderer support for adaptive format switches. One of {@link #ADAPTIVE_SEAMLESS},
   * {@link #ADAPTIVE_NOT_SEAMLESS} or {@link #ADAPTIVE_NOT_SUPPORTED}.
   */
  @Documented
  @Retention(RetentionPolicy.SOURCE)
  @Target(TYPE_USE)
  @IntDef({ADAPTIVE_SEAMLESS, ADAPTIVE_NOT_SEAMLESS, ADAPTIVE_NOT_SUPPORTED})
  @interface AdaptiveSupport {}

  /** A mask to apply to {@link Capabilities} to obtain the {@link AdaptiveSupport} only. */
  int ADAPTIVE_SUPPORT_MASK = 0b11 << 3;

  /** The {@link Renderer} can seamlessly adapt between formats. */
  int ADAPTIVE_SEAMLESS = 0b10 << 3;

  /**
   * The {@link Renderer} can adapt between formats, but may suffer a brief discontinuity
   * (~50-100ms) when adaptation occurs.
   */
  int ADAPTIVE_NOT_SEAMLESS = 0b01 << 3;

  /** The {@link Renderer} does not support adaptation between formats. */
  int ADAPTIVE_NOT_SUPPORTED = 0;

  /**
   * Level of renderer support for tunneling. One of {@link #TUNNELING_SUPPORTED} or {@link
   * #TUNNELING_NOT_SUPPORTED}.
   */
  @Documented
  @Retention(RetentionPolicy.SOURCE)
  @Target(TYPE_USE)
  @IntDef({TUNNELING_SUPPORTED, TUNNELING_NOT_SUPPORTED})
  @interface TunnelingSupport {}

  /** A mask to apply to {@link Capabilities} to obtain {@link TunnelingSupport} only. */
  int TUNNELING_SUPPORT_MASK = 0b1 << 5;

  /** The {@link Renderer} supports tunneled output. */
  int TUNNELING_SUPPORTED = 0b1 << 5;

  /** The {@link Renderer} does not support tunneled output. */
  int TUNNELING_NOT_SUPPORTED = 0;

  /**
   * Level of renderer support for hardware acceleration. One of {@link
   * #HARDWARE_ACCELERATION_SUPPORTED} and {@link #HARDWARE_ACCELERATION_NOT_SUPPORTED}.
   *
   * <p>For video renderers, the level of support is indicated for non-tunneled output.
   */
  @Documented
  @Retention(RetentionPolicy.SOURCE)
  @Target(TYPE_USE)
  @IntDef({
    HARDWARE_ACCELERATION_SUPPORTED,
    HARDWARE_ACCELERATION_NOT_SUPPORTED,
  })
  @interface HardwareAccelerationSupport {}

  /** A mask to apply to {@link Capabilities} to obtain {@link HardwareAccelerationSupport} only. */
  int HARDWARE_ACCELERATION_SUPPORT_MASK = 0b1 << 6;

  /** The renderer is able to use hardware acceleration. */
  int HARDWARE_ACCELERATION_SUPPORTED = 0b1 << 6;

  /** The renderer is not able to use hardware acceleration. */
  int HARDWARE_ACCELERATION_NOT_SUPPORTED = 0;

  /**
   * Level of decoder support. One of {@link #DECODER_SUPPORT_PRIMARY}, {@link
   * #DECODER_SUPPORT_FALLBACK}, and {@link #DECODER_SUPPORT_FALLBACK_MIMETYPE}}.
   *
   * <p>For video renderers, the level of support is indicated for non-tunneled output.
   */
  @Documented
  @Retention(RetentionPolicy.SOURCE)
  @Target(TYPE_USE)
  @IntDef({DECODER_SUPPORT_FALLBACK_MIMETYPE, DECODER_SUPPORT_PRIMARY, DECODER_SUPPORT_FALLBACK})
  @interface DecoderSupport {}

  /** A mask to apply to {@link Capabilities} to obtain {@link DecoderSupport} only. */
  int DECODER_SUPPORT_MASK = 0b11 << 7;

  /**
   * The format's MIME type is unsupported and the renderer may use a decoder for a fallback MIME
   * type.
   */
  int DECODER_SUPPORT_FALLBACK_MIMETYPE = 0b10 << 7;

  /** The renderer is able to use the primary decoder for the format's MIME type. */
  int DECODER_SUPPORT_PRIMARY = 0b1 << 7;

  /** The format exceeds the primary decoder's capabilities but is supported by fallback decoder */
  int DECODER_SUPPORT_FALLBACK = 0;

  /**
   * Level of renderer support for audio offload.
   *
   * <p>Speed change and gapless transition support with audio offload is represented by the bit
   * mask flags {@link #AUDIO_OFFLOAD_SPEED_CHANGE_SUPPORTED} and {@link
   * #AUDIO_OFFLOAD_GAPLESS_SUPPORTED} respectively. If neither feature is supported then the value
   * will be either {@link #AUDIO_OFFLOAD_SUPPORTED} or {@link #AUDIO_OFFLOAD_NOT_SUPPORTED}.
   *
   * <p>For non-audio renderers, the level of support is always {@link
   * #AUDIO_OFFLOAD_NOT_SUPPORTED}.
   */
  @Documented
  @Retention(RetentionPolicy.SOURCE)
  @Target(TYPE_USE)
  @IntDef({
    AUDIO_OFFLOAD_SPEED_CHANGE_SUPPORTED,
    AUDIO_OFFLOAD_GAPLESS_SUPPORTED,
    AUDIO_OFFLOAD_SUPPORTED,
    AUDIO_OFFLOAD_NOT_SUPPORTED
  })
  @interface AudioOffloadSupport {}

  /** A mask to apply to {@link Capabilities} to obtain {@link AudioOffloadSupport} only. */
  int AUDIO_OFFLOAD_SUPPORT_MASK = 0b111 << 9;

  /** The renderer supports audio offload and speed changes with this format. */
  int AUDIO_OFFLOAD_SPEED_CHANGE_SUPPORTED = 0b100 << 9;

  /** The renderer supports audio offload and gapless transitions with this format. */
  int AUDIO_OFFLOAD_GAPLESS_SUPPORTED = 0b10 << 9;

  /** The renderer supports audio offload with this format. */
  int AUDIO_OFFLOAD_SUPPORTED = 0b1 << 9;

  /** Audio offload is not supported with this format. */
  int AUDIO_OFFLOAD_NOT_SUPPORTED = 0;

  /**
   * Combined renderer capabilities.
   *
   * <p>This is a bitwise OR of {@link C.FormatSupport}, {@link AdaptiveSupport}, {@link
   * TunnelingSupport}, {@link HardwareAccelerationSupport}, {@link DecoderSupport} and {@link
   * AudioOffloadSupport}. Use {@link #getFormatSupport}, {@link #getAdaptiveSupport}, {@link
   * #getTunnelingSupport}, {@link #getHardwareAccelerationSupport}, {@link #getDecoderSupport} and
   * {@link AudioOffloadSupport} to obtain individual components. Use {@link #create(int)}, {@link
   * #create(int, int, int)}, {@link #create(int, int, int, int)}, or {@link #create(int, int, int,
   * int, int, int)} to create combined capabilities from individual components.
   *
   * <p>Possible values:
   *
   * <ul>
   *   <li>{@link C.FormatSupport}: The level of support for the format itself. One of {@link
   *       C#FORMAT_HANDLED}, {@link C#FORMAT_EXCEEDS_CAPABILITIES}, {@link
   *       C#FORMAT_UNSUPPORTED_DRM}, {@link C#FORMAT_UNSUPPORTED_SUBTYPE} and {@link
   *       C#FORMAT_UNSUPPORTED_TYPE}.
   *   <li>{@link AdaptiveSupport}: The level of support for adapting from the format to another
   *       format of the same MIME type. One of {@link #ADAPTIVE_SEAMLESS}, {@link
   *       #ADAPTIVE_NOT_SEAMLESS} and {@link #ADAPTIVE_NOT_SUPPORTED}. Only set if the level of
   *       support for the format itself is {@link C#FORMAT_HANDLED} or {@link
   *       C#FORMAT_EXCEEDS_CAPABILITIES}.
   *   <li>{@link TunnelingSupport}: The level of support for tunneling. One of {@link
   *       #TUNNELING_SUPPORTED} and {@link #TUNNELING_NOT_SUPPORTED}. Only set if the level of
   *       support for the format itself is {@link C#FORMAT_HANDLED} or {@link
   *       C#FORMAT_EXCEEDS_CAPABILITIES}.
   *   <li>{@link HardwareAccelerationSupport}: The level of support for hardware acceleration. One
   *       of {@link #HARDWARE_ACCELERATION_SUPPORTED} and {@link
   *       #HARDWARE_ACCELERATION_NOT_SUPPORTED}.
   *   <li>{@link DecoderSupport}: The level of decoder support. One of {@link
   *       #DECODER_SUPPORT_PRIMARY}, {@link #DECODER_SUPPORT_FALLBACK}, or {@link
   *       #DECODER_SUPPORT_FALLBACK_MIMETYPE}.
   *   <li>{@link AudioOffloadSupport}: The level of offload support. Value will have the flag
   *       {@link #AUDIO_OFFLOAD_SUPPORTED} or be {@link #AUDIO_OFFLOAD_NOT_SUPPORTED}. In addition,
   *       if it is {@link #AUDIO_OFFLOAD_SUPPORTED}, then one can check for {@link
   *       #AUDIO_OFFLOAD_SPEED_CHANGE_SUPPORTED} and {@link #AUDIO_OFFLOAD_GAPLESS_SUPPORTED}.
   *       These represent speed change and gapless transition support with audio offload
   *       respectively.
   * </ul>
   */
  @Documented
  @Retention(RetentionPolicy.SOURCE)
  // Intentionally empty to prevent assignment or comparison with individual flags without masking.
  @Target(TYPE_USE)
  @IntDef({})
  @interface Capabilities {}

  /**
   * Returns {@link Capabilities} for the given {@link C.FormatSupport}.
   *
   * <p>{@link AdaptiveSupport} is set to {@link #ADAPTIVE_NOT_SUPPORTED}, {@link TunnelingSupport}
   * is set to {@link #TUNNELING_NOT_SUPPORTED}, {@link HardwareAccelerationSupport} is set to
   * {@link #HARDWARE_ACCELERATION_NOT_SUPPORTED}, {@link DecoderSupport} is set to {@link
   * #DECODER_SUPPORT_PRIMARY} and {@link AudioOffloadSupport} is set to {@link
   * #AUDIO_OFFLOAD_NOT_SUPPORTED}.
   *
   * @param formatSupport The {@link C.FormatSupport}.
   * @return The combined {@link Capabilities} of the given {@link C.FormatSupport}, {@link
   *     #ADAPTIVE_NOT_SUPPORTED}, {@link #TUNNELING_NOT_SUPPORTED} and {@link
   *     #AUDIO_OFFLOAD_NOT_SUPPORTED}.
   */
  static @Capabilities int create(@C.FormatSupport int formatSupport) {
    return create(
        formatSupport,
        ADAPTIVE_NOT_SUPPORTED,
        TUNNELING_NOT_SUPPORTED,
        AUDIO_OFFLOAD_NOT_SUPPORTED);
  }

  /**
   * Returns {@link Capabilities} combining the given {@link C.FormatSupport}, {@link
   * AdaptiveSupport} and {@link TunnelingSupport}.
   *
   * <p>{@link HardwareAccelerationSupport} is set to {@link #HARDWARE_ACCELERATION_NOT_SUPPORTED},
   * {@link DecoderSupport} is set to {@link #DECODER_SUPPORT_PRIMARY}, and {@link
   * AudioOffloadSupport} is set to {@link #AUDIO_OFFLOAD_NOT_SUPPORTED}.
   *
   * @param formatSupport The {@link C.FormatSupport}.
   * @param adaptiveSupport The {@link AdaptiveSupport}.
   * @param tunnelingSupport The {@link TunnelingSupport}.
   * @return The combined {@link Capabilities}.
   */
  static @Capabilities int create(
      @C.FormatSupport int formatSupport,
      @AdaptiveSupport int adaptiveSupport,
      @TunnelingSupport int tunnelingSupport) {
    return create(
        formatSupport,
        adaptiveSupport,
        tunnelingSupport,
        HARDWARE_ACCELERATION_NOT_SUPPORTED,
        DECODER_SUPPORT_PRIMARY,
        AUDIO_OFFLOAD_NOT_SUPPORTED);
  }

  /**
   * Returns {@link Capabilities} combining the given {@link C.FormatSupport}, {@link
   * AdaptiveSupport}, {@link TunnelingSupport}, and {@link AudioOffloadSupport}.
   *
   * <p>{@link HardwareAccelerationSupport} is set to {@link #HARDWARE_ACCELERATION_NOT_SUPPORTED}
   * and {@link DecoderSupport} is set to {@link #DECODER_SUPPORT_PRIMARY}.
   *
   * @param formatSupport The {@link C.FormatSupport}.
   * @param adaptiveSupport The {@link AdaptiveSupport}.
   * @param tunnelingSupport The {@link TunnelingSupport}.
   * @param audioOffloadSupport The {@link AudioOffloadSupport}.
   * @return The combined {@link Capabilities}.
   */
  static @Capabilities int create(
      @C.FormatSupport int formatSupport,
      @AdaptiveSupport int adaptiveSupport,
      @TunnelingSupport int tunnelingSupport,
      @AudioOffloadSupport int audioOffloadSupport) {
    return create(
        formatSupport,
        adaptiveSupport,
        tunnelingSupport,
        HARDWARE_ACCELERATION_NOT_SUPPORTED,
        DECODER_SUPPORT_PRIMARY,
        audioOffloadSupport);
  }

  /**
   * Returns {@link Capabilities} combining the given {@link C.FormatSupport}, {@link
   * AdaptiveSupport}, {@link TunnelingSupport}, {@link HardwareAccelerationSupport}, and {@link
   * DecoderSupport}.
   *
   * <p>{@link AudioOffloadSupport} is set to {@link #AUDIO_OFFLOAD_NOT_SUPPORTED}.
   *
   * @param formatSupport The {@link C.FormatSupport}.
   * @param adaptiveSupport The {@link AdaptiveSupport}.
   * @param tunnelingSupport The {@link TunnelingSupport}.
   * @param hardwareAccelerationSupport The {@link HardwareAccelerationSupport}.
   * @param decoderSupport The {@link DecoderSupport}.
   * @return The combined {@link Capabilities}.
   */
  static @Capabilities int create(
      @C.FormatSupport int formatSupport,
      @AdaptiveSupport int adaptiveSupport,
      @TunnelingSupport int tunnelingSupport,
      @HardwareAccelerationSupport int hardwareAccelerationSupport,
      @DecoderSupport int decoderSupport) {
    return create(
        formatSupport,
        adaptiveSupport,
        tunnelingSupport,
        hardwareAccelerationSupport,
        decoderSupport,
        AUDIO_OFFLOAD_NOT_SUPPORTED);
  }

  /**
   * Returns {@link Capabilities} combining the given {@link C.FormatSupport}, {@link
   * AdaptiveSupport}, {@link TunnelingSupport}, {@link HardwareAccelerationSupport}, {@link
   * DecoderSupport} and {@link AudioOffloadSupport}.
   *
   * @param formatSupport The {@link C.FormatSupport}.
   * @param adaptiveSupport The {@link AdaptiveSupport}.
   * @param tunnelingSupport The {@link TunnelingSupport}.
   * @param hardwareAccelerationSupport The {@link HardwareAccelerationSupport}.
   * @param decoderSupport The {@link DecoderSupport}.
   * @param audioOffloadSupport The {@link AudioOffloadSupport}
   * @return The combined {@link Capabilities}.
   */
  // Suppression needed for IntDef casting.
  @SuppressLint("WrongConstant")
  static @Capabilities int create(
      @C.FormatSupport int formatSupport,
      @AdaptiveSupport int adaptiveSupport,
      @TunnelingSupport int tunnelingSupport,
      @HardwareAccelerationSupport int hardwareAccelerationSupport,
      @DecoderSupport int decoderSupport,
      @AudioOffloadSupport int audioOffloadSupport) {
    return formatSupport
        | adaptiveSupport
        | tunnelingSupport
        | hardwareAccelerationSupport
        | decoderSupport
        | audioOffloadSupport;
  }

  /**
   * Returns the {@link C.FormatSupport} from the combined {@link Capabilities}.
   *
   * @param supportFlags The combined {@link Capabilities}.
   * @return The {@link C.FormatSupport} only.
   */
  // Suppression needed for IntDef casting.
  @SuppressLint("WrongConstant")
  static @C.FormatSupport int getFormatSupport(@Capabilities int supportFlags) {
    return supportFlags & FORMAT_SUPPORT_MASK;
  }

  /**
   * Returns whether the {@link C.FormatSupport} from the combined {@link Capabilities} indicates
   * the format is supported.
   *
   * <p>A format is considered supported if its {@link C.FormatSupport} value is {@link
   * C#FORMAT_HANDLED}, or optionally {@link C#FORMAT_EXCEEDS_CAPABILITIES} if enabled by {@code
   * allowExceedsCapabilities}.
   *
   * @param supportFlags The combined {@link Capabilities}.
   * @param allowExceedsCapabilities Whether {@link C#FORMAT_EXCEEDS_CAPABILITIES} should be
   *     considered as supported.
   * @return Whether the {@link Capabilities} indicate a format is supported.
   */
  static boolean isFormatSupported(
      @Capabilities int supportFlags, boolean allowExceedsCapabilities) {
    @C.FormatSupport int formatSupport = getFormatSupport(supportFlags);
    return formatSupport == C.FORMAT_HANDLED
        || (allowExceedsCapabilities && formatSupport == C.FORMAT_EXCEEDS_CAPABILITIES);
  }

  /**
   * Returns the {@link AdaptiveSupport} from the combined {@link Capabilities}.
   *
   * @param supportFlags The combined {@link Capabilities}.
   * @return The {@link AdaptiveSupport} only.
   */
  // Suppression needed for IntDef casting.
  @SuppressLint("WrongConstant")
  static @AdaptiveSupport int getAdaptiveSupport(@Capabilities int supportFlags) {
    return supportFlags & ADAPTIVE_SUPPORT_MASK;
  }

  /**
   * Returns the {@link TunnelingSupport} from the combined {@link Capabilities}.
   *
   * @param supportFlags The combined {@link Capabilities}.
   * @return The {@link TunnelingSupport} only.
   */
  // Suppression needed for IntDef casting.
  @SuppressLint("WrongConstant")
  static @TunnelingSupport int getTunnelingSupport(@Capabilities int supportFlags) {
    return supportFlags & TUNNELING_SUPPORT_MASK;
  }

  /**
   * Returns the {@link HardwareAccelerationSupport} from the combined {@link Capabilities}.
   *
   * @param supportFlags The combined {@link Capabilities}.
   * @return The {@link HardwareAccelerationSupport} only.
   */
  // Suppression needed for IntDef casting.
  @SuppressLint("WrongConstant")
  static @HardwareAccelerationSupport int getHardwareAccelerationSupport(
      @Capabilities int supportFlags) {
    return supportFlags & HARDWARE_ACCELERATION_SUPPORT_MASK;
  }

  /**
   * Returns the {@link DecoderSupport} from the combined {@link Capabilities}.
   *
   * @param supportFlags The combined {@link Capabilities}.
   * @return The {@link DecoderSupport} only.
   */
  // Suppression needed for IntDef casting.
  @SuppressLint("WrongConstant")
  static @DecoderSupport int getDecoderSupport(@Capabilities int supportFlags) {
    return supportFlags & DECODER_SUPPORT_MASK;
  }

  /**
   * Returns the {@link AudioOffloadSupport} from the combined {@link Capabilities}.
   *
   * @param supportFlags The combined {@link Capabilities}.
   * @return The {@link AudioOffloadSupport} only.
   */
  // Suppression needed for IntDef casting.
  @SuppressLint("WrongConstant")
  static @AudioOffloadSupport int getAudioOffloadSupport(@Capabilities int supportFlags) {
    return supportFlags & AUDIO_OFFLOAD_SUPPORT_MASK;
  }

  /** Returns the name of the {@link Renderer}. */
  String getName();

  /**
   * Returns the track type that the {@link Renderer} handles. For example, a video renderer will
   * return {@link C#TRACK_TYPE_VIDEO}, an audio renderer will return {@link C#TRACK_TYPE_AUDIO}, a
   * text renderer will return {@link C#TRACK_TYPE_TEXT}, and so on.
   *
   * @see Renderer#getTrackType()
   * @return The {@link C.TrackType track type}.
   */
  @C.TrackType
  int getTrackType();

  /**
   * Returns the extent to which the {@link Renderer} supports a given format.
   *
   * @param format The format.
   * @return The {@link Capabilities} for this format.
   * @throws ExoPlaybackException If an error occurs.
   */
  @Capabilities
  int supportsFormat(Format format) throws ExoPlaybackException;

  /**
   * Returns the extent to which the {@link Renderer} supports adapting between supported formats
   * that have different MIME types.
   *
   * @return The {@link AdaptiveSupport} for adapting between supported formats that have different
   *     MIME types.
   * @throws ExoPlaybackException If an error occurs.
   */
  @AdaptiveSupport
  int supportsMixedMimeTypeAdaptation() throws ExoPlaybackException;

  /**
   * Sets the {@link Listener}.
   *
   * @param listener The listener to be set.
   */
  default void setListener(Listener listener) {
    // Do nothing.
  }

  /** Clears the {@link Listener}. */
  default void clearListener() {
    // Do nothing.
  }
}