media/base/android/media_codec_bridge.h

   1 // Copyright (c) 2013 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef MEDIA_BASE_ANDROID_MEDIA_CODEC_BRIDGE_H_
   6 #define MEDIA_BASE_ANDROID_MEDIA_CODEC_BRIDGE_H_
   7
   8 #include <jni.h>
   9 #include <string>
  10
  11 #include "base/android/scoped_java_ref.h"
  12 #include "base/time/time.h"
  13 #include "media/base/audio_decoder_config.h"
  14 #include "media/base/video_decoder_config.h"
  15 #include "ui/gfx/size.h"
  16
  17 namespace media {
  18
  19 struct SubsampleEntry;
  20
  21 // These must be in sync with MediaCodecBridge.MEDIA_CODEC_XXX constants in
  22 // MediaCodecBridge.java.
  23 enum MediaCodecStatus {
  24   MEDIA_CODEC_OK,
  25   MEDIA_CODEC_DEQUEUE_INPUT_AGAIN_LATER,
  26   MEDIA_CODEC_DEQUEUE_OUTPUT_AGAIN_LATER,
  27   MEDIA_CODEC_OUTPUT_BUFFERS_CHANGED,
  28   MEDIA_CODEC_OUTPUT_FORMAT_CHANGED,
  29   MEDIA_CODEC_INPUT_END_OF_STREAM,
  30   MEDIA_CODEC_OUTPUT_END_OF_STREAM,
  31   MEDIA_CODEC_NO_KEY,
  32   MEDIA_CODEC_STOPPED,
  33   MEDIA_CODEC_ERROR
  34 };
  35
  36 // Codec direction.  Keep this in sync with MediaCodecBridge.java.
  37 enum MediaCodecDirection {
  38   MEDIA_CODEC_DECODER,
  39   MEDIA_CODEC_ENCODER,
  40 };
  41
  42 // This class serves as a bridge for native code to call java functions inside
  43 // Android MediaCodec class. For more information on Android MediaCodec, check
  44 // http://developer.android.com/reference/android/media/MediaCodec.html
  45 // Note: MediaCodec is only available on JB and greater.
  46 // Use AudioCodecBridge or VideoCodecBridge to create an instance of this
  47 // object.
  48 //
  49 // TODO(fischman,xhwang): replace this (and the enums that go with it) with
  50 // chromium's JNI auto-generation hotness.
  51 class MEDIA_EXPORT MediaCodecBridge {
  52  public:
  53   // Returns true if MediaCodec is available on the device.
  54   // All other static methods check IsAvailable() internally. There's no need
  55   // to check IsAvailable() explicitly before calling them.
  56   static bool IsAvailable();
  57
  58   // Returns true if MediaCodec.setParameters() is available on the device.
  59   static bool SupportsSetParameters();
  60
  61   // Returns whether MediaCodecBridge has a decoder that |is_secure| and can
  62   // decode |codec| type.
  63   static bool CanDecode(const std::string& codec, bool is_secure);
  64
  65   // Represents supported codecs on android.
  66   // TODO(qinmin): Currently the codecs string only contains one codec. Do we
  67   // need to support codecs separated by comma. (e.g. "vp8" -> "vp8, vp8.0")?
  68   struct CodecsInfo {
  69     std::string codecs;  // E.g. "vp8" or "avc1".
  70     std::string name;    // E.g. "OMX.google.vp8.decoder".
  71     MediaCodecDirection direction;
  72   };
  73
  74   // Get a list of supported codecs.
  75   static std::vector<CodecsInfo> GetCodecsInfo();
  76
  77   virtual ~MediaCodecBridge();
  78
  79   // Resets both input and output, all indices previously returned in calls to
  80   // DequeueInputBuffer() and DequeueOutputBuffer() become invalid.
  81   // Please note that this clears all the inputs in the media codec. In other
  82   // words, there will be no outputs until new input is provided.
  83   // Returns MEDIA_CODEC_ERROR if an unexpected error happens, or Media_CODEC_OK
  84   // otherwise.
  85   MediaCodecStatus Reset();
  86
  87   // Finishes the decode/encode session. The instance remains active
  88   // and ready to be StartAudio/Video()ed again. HOWEVER, due to the buggy
  89   // vendor's implementation , b/8125974, Stop() -> StartAudio/Video() may not
  90   // work on some devices. For reliability, Stop() -> delete and recreate new
  91   // instance -> StartAudio/Video() is recommended.
  92   void Stop();
  93
  94   // Used for getting output format. This is valid after DequeueInputBuffer()
  95   // returns a format change by returning INFO_OUTPUT_FORMAT_CHANGED
  96   void GetOutputFormat(int* width, int* height);
  97
  98   // Returns the number of input buffers used by the codec.
  99   int GetInputBuffersCount();
 100
 101   // Submits a byte array to the given input buffer. Call this after getting an
 102   // available buffer from DequeueInputBuffer().  If |data| is NULL, assume the
 103   // input buffer has already been populated (but still obey |size|).
 104   // |data_size| must be less than kint32max (because Java).
 105   MediaCodecStatus QueueInputBuffer(int index,
 106                                     const uint8* data,
 107                                     size_t data_size,
 108                                     const base::TimeDelta& presentation_time);
 109
 110   // Similar to the above call, but submits a buffer that is encrypted.  Note:
 111   // NULL |subsamples| indicates the whole buffer is encrypted.  If |data| is
 112   // NULL, assume the input buffer has already been populated (but still obey
 113   // |data_size|).  |data_size| must be less than kint32max (because Java).
 114   MediaCodecStatus QueueSecureInputBuffer(
 115       int index,
 116       const uint8* data,
 117       size_t data_size,
 118       const uint8* key_id,
 119       int key_id_size,
 120       const uint8* iv,
 121       int iv_size,
 122       const SubsampleEntry* subsamples,
 123       int subsamples_size,
 124       const base::TimeDelta& presentation_time);
 125
 126   // Submits an empty buffer with a EOS (END OF STREAM) flag.
 127   void QueueEOS(int input_buffer_index);
 128
 129   // Returns:
 130   // MEDIA_CODEC_OK if an input buffer is ready to be filled with valid data,
 131   // MEDIA_CODEC_ENQUEUE_INPUT_AGAIN_LATER if no such buffer is available, or
 132   // MEDIA_CODEC_ERROR if unexpected error happens.
 133   // Note: Never use infinite timeout as this would block the decoder thread and
 134   // prevent the decoder job from being released.
 135   MediaCodecStatus DequeueInputBuffer(const base::TimeDelta& timeout,
 136                                       int* index);
 137
 138   // Dequeues an output buffer, block at most timeout_us microseconds.
 139   // Returns the status of this operation. If OK is returned, the output
 140   // parameters should be populated. Otherwise, the values of output parameters
 141   // should not be used.  Output parameters other than index/offset/size are
 142   // optional and only set if not NULL.
 143   // Note: Never use infinite timeout as this would block the decoder thread and
 144   // prevent the decoder job from being released.
 145   // TODO(xhwang): Can we drop |end_of_stream| and return
 146   // MEDIA_CODEC_OUTPUT_END_OF_STREAM?
 147   MediaCodecStatus DequeueOutputBuffer(const base::TimeDelta& timeout,
 148                                        int* index,
 149                                        size_t* offset,
 150                                        size_t* size,
 151                                        base::TimeDelta* presentation_time,
 152                                        bool* end_of_stream,
 153                                        bool* key_frame);
 154
 155   // Returns the buffer to the codec. If you previously specified a surface when
 156   // configuring this video decoder you can optionally render the buffer.
 157   void ReleaseOutputBuffer(int index, bool render);
 158
 159   // Returns the number of output buffers used by the codec.
 160   int GetOutputBuffersCount();
 161
 162   // Returns the capacity of each output buffer used by the codec.
 163   size_t GetOutputBuffersCapacity();
 164
 165   // Gets output buffers from media codec and keeps them inside the java class.
 166   // To access them, use DequeueOutputBuffer(). Returns whether output buffers
 167   // were successfully obtained.
 168   bool GetOutputBuffers() WARN_UNUSED_RESULT;
 169
 170   // Returns an input buffer's base pointer and capacity.
 171   void GetInputBuffer(int input_buffer_index, uint8** data, size_t* capacity);
 172
 173   // Copy |dst_size| bytes from output buffer |index|'s |offset| onwards into
 174   // |*dst|.
 175   bool CopyFromOutputBuffer(int index, size_t offset, void* dst, int dst_size);
 176
 177   static bool RegisterMediaCodecBridge(JNIEnv* env);
 178
 179  protected:
 180   // Returns true if |mime_type| is known to be unaccelerated (i.e. backed by a
 181   // software codec instead of a hardware one).
 182   static bool IsKnownUnaccelerated(const std::string& mime_type,
 183                                    MediaCodecDirection direction);
 184
 185   MediaCodecBridge(const std::string& mime,
 186                    bool is_secure,
 187                    MediaCodecDirection direction);
 188
 189   // Calls start() against the media codec instance. Used in StartXXX() after
 190   // configuring media codec. Returns whether media codec was successfully
 191   // started.
 192   bool StartInternal() WARN_UNUSED_RESULT;
 193
 194   jobject media_codec() { return j_media_codec_.obj(); }
 195   MediaCodecDirection direction_;
 196
 197  private:
 198   // Fills a particular input buffer; returns false if |data_size| exceeds the
 199   // input buffer's capacity (and doesn't touch the input buffer in that case).
 200   bool FillInputBuffer(int index,
 201                        const uint8* data,
 202                        size_t data_size) WARN_UNUSED_RESULT;
 203
 204   // Java MediaCodec instance.
 205   base::android::ScopedJavaGlobalRef<jobject> j_media_codec_;
 206
 207   DISALLOW_COPY_AND_ASSIGN(MediaCodecBridge);
 208 };
 209
 210 class AudioCodecBridge : public MediaCodecBridge {
 211  public:
 212   // Returns an AudioCodecBridge instance if |codec| is supported, or a NULL
 213   // pointer otherwise.
 214   static AudioCodecBridge* Create(const AudioCodec& codec);
 215
 216   // See MediaCodecBridge::IsKnownUnaccelerated().
 217   static bool IsKnownUnaccelerated(const AudioCodec& codec);
 218
 219   // Start the audio codec bridge.
 220   bool Start(const AudioCodec& codec, int sample_rate, int channel_count,
 221              const uint8* extra_data, size_t extra_data_size,
 222              bool play_audio, jobject media_crypto) WARN_UNUSED_RESULT;
 223
 224   // Play the output buffer. This call must be called after
 225   // DequeueOutputBuffer() and before ReleaseOutputBuffer. Returns the playback
 226   // head position expressed in frames.
 227   int64 PlayOutputBuffer(int index, size_t size);
 228
 229   // Set the volume of the audio output.
 230   void SetVolume(double volume);
 231
 232  private:
 233   explicit AudioCodecBridge(const std::string& mime);
 234
 235   // Configure the java MediaFormat object with the extra codec data passed in.
 236   bool ConfigureMediaFormat(jobject j_format, const AudioCodec& codec,
 237                             const uint8* extra_data, size_t extra_data_size);
 238 };
 239
 240 class MEDIA_EXPORT VideoCodecBridge : public MediaCodecBridge {
 241  public:
 242   // See MediaCodecBridge::IsKnownUnaccelerated().
 243   static bool IsKnownUnaccelerated(const VideoCodec& codec,
 244                                    MediaCodecDirection direction);
 245
 246   // Create, start, and return a VideoCodecBridge decoder or NULL on failure.
 247   static VideoCodecBridge* CreateDecoder(
 248       const VideoCodec& codec,  // e.g. media::kCodecVP8
 249       bool is_secure,
 250       const gfx::Size& size,  // Output frame size.
 251       jobject surface,        // Output surface, optional.
 252       jobject media_crypto);  // MediaCrypto object, optional.
 253
 254   // Create, start, and return a VideoCodecBridge encoder or NULL on failure.
 255   static VideoCodecBridge* CreateEncoder(
 256       const VideoCodec& codec,  // e.g. media::kCodecVP8
 257       const gfx::Size& size,    // input frame size
 258       int bit_rate,             // bits/second
 259       int frame_rate,           // frames/second
 260       int i_frame_interval,     // count
 261       int color_format);        // MediaCodecInfo.CodecCapabilities.
 262
 263   void SetVideoBitrate(int bps);
 264   void RequestKeyFrameSoon();
 265
 266  private:
 267   VideoCodecBridge(const std::string& mime,
 268                    bool is_secure,
 269                    MediaCodecDirection direction);
 270 };
 271
 272 }  // namespace media
 273
 274 #endif  // MEDIA_BASE_ANDROID_MEDIA_CODEC_BRIDGE_H_