Add video decoding support in the CDM interface.

webkit/media/crypto/ppapi/content_decryption_module.h

Index: webkit/media/crypto/ppapi/content_decryption_module.h
diff --git a/webkit/media/crypto/ppapi/content_decryption_module.h b/webkit/media/crypto/ppapi/content_decryption_module.h
index cb21258a6fb24feb19ab45813e34f3c15fb1082d..87f791a51c9e5033bf1d21faab4d065eaa29024e 100644
--- a/webkit/media/crypto/ppapi/content_decryption_module.h
+++ b/webkit/media/crypto/ppapi/content_decryption_module.h
@@ -29,10 +29,13 @@ namespace cdm {
 
 enum Status {
   kSuccess = 0,
-  kErrorUnknown,
-  kErrorNoKey
+  kNeedMoreData,  // Decoder needs more data to produce a decoded frame/sample.
+  kNoKey,  // The required decryption key is not available.
+  kError
 };
 
+// Represents a key message sent by the CDM. It does not own any pointers in
+// this struct.
 // TODO(xhwang): Use int32_t instead of uint32_t for sizes here and below and
 // update checks to include <0.
 struct KeyMessage {
@@ -82,6 +85,8 @@ struct SubsampleEntry {
   uint32_t cipher_bytes;
 };
 
+// Represents an input buffer to be decrypted (and possibly decoded). It does
+// own any pointers in this struct.
 struct InputBuffer {
   InputBuffer()
       : data(NULL),
@@ -117,6 +122,7 @@ struct InputBuffer {
   int64_t timestamp;  // Presentation timestamp in microseconds.
 };
 
+// Represents an output decrypted buffer. It does not own |data|.
 struct OutputBuffer {
   OutputBuffer()
       : data(NULL),
@@ -129,6 +135,77 @@ struct OutputBuffer {
   int64_t timestamp;  // Presentation timestamp in microseconds.
 };
 
+// Surface formats based on FOURCC labels, see:
+// http://www.fourcc.org/yuv.php
+enum VideoFormat {
+  kUnknownVideoFormat = 0,  // Unknown format value.  Used for error reporting.
+  kEmptyVideoFrame,  // An empty frame.
+  kYv12,  // 12bpp YVU planar 1x1 Y, 2x2 VU samples.
+  kI420  // 12bpp YVU planar 1x1 Y, 2x2 UV samples.
+};
+
+struct VideoSize {

[scherkus (not reviewing), 2012/09/05 16:43:43]

this looks like a general purpose size struct to me

considering it's namespaced lets go w/ Size

[xhwang, 2012/09/05 17:13:30]

Done.

+  VideoSize() : width(0), height(0) {}
+  VideoSize(int32_t width, int32_t height) : width(width), height(height) {}
+
+  int32_t width;
+  int32_t height;
+};
+
+struct VideoFrame {
+  static const int32_t kMaxPlanes = 3;
+
+  VideoFrame()
+      : timestamp(0) {
+    for (int i = 0; i < kMaxPlanes; ++i) {
+      strides[i] = 0;
+      data[i] = NULL;
+    }
+  }
+
+  // Array of strides for each plane, typically greater or equal to the width
+  // of the surface divided by the horizontal sampling period.  Note that
+  // strides can be negative.
+  int32_t strides[kMaxPlanes];
+
+  // Array of data pointers to each plane.
+  uint8_t* data[kMaxPlanes];
+
+  int64_t timestamp;  // Presentation timestamp in microseconds.
+};
+
+struct VideoDecoderConfig {
+  enum VideoCodec {
+    kUnknownVideoCodec = 0,
+    kCodecVP8
+  };
+
+  enum VideoCodecProfile {
+    kUnknownVideoCodecProfile = 0,
+    kVp8ProfileMain
+  };
+
+  VideoDecoderConfig()
+      : codec(kUnknownVideoCodec),
+        profile(kUnknownVideoCodecProfile),
+        format(kUnknownVideoFormat),
+        extra_data(NULL),
+        extra_data_size() {}
+
+  VideoCodec codec;
+  VideoCodecProfile profile;
+  VideoFormat format;
+
+  // Width and height of video frame immediately post-decode. Not all pixels
+  // in this region are valid.
+  VideoSize coded_size;
+
+  // Optional byte data required to initialize video decoders, such as H.264
+  // AAVC data.
+  uint8_t* extra_data;
+  int32_t extra_data_size;
+};
+
 class ContentDecryptionModule {
  public:
   // Generates a |key_request| given the |init_data|.

[scherkus (not reviewing), 2012/09/05 16:43:43]

add blank line below to separate function summary from return statements

[xhwang, 2012/09/05 17:13:30]

Done.

@@ -136,7 +213,7 @@ class ContentDecryptionModule {
   // in which case the callee should have allocated memory for the output
   // parameters (e.g |session_id| in |key_request|) and passed the ownership
   // to the caller.
-  // Returns kErrorUnknown otherwise, in which case the output parameters should
+  // Returns kError otherwise, in which case the output parameters should
   // not be used by the caller.
   //
   // TODO(xhwang): It's not safe to pass the ownership of the dynamically
@@ -148,7 +225,7 @@ class ContentDecryptionModule {
 
   // Adds the |key| to the CDM to be associated with |key_id|.

[scherkus (not reviewing), 2012/09/05 16:43:43]

add blank line below to separate function summary from return statements

[xhwang, 2012/09/05 17:13:30]

Done.

   // Returns kSuccess if the key was successfully added.
-  // Returns kErrorUnknown otherwise.
+  // Returns kError otherwise.

[scherkus (not reviewing), 2012/09/05 16:43:43]

this isn't a sentence -- I'd rewrite this as:

Returns kSuccess if the key was successfully added, kError otherwise.

[xhwang, 2012/09/05 17:13:30]

Done.

   virtual Status AddKey(const char* session_id,
                         int session_id_size,
                         const uint8_t* key,
@@ -159,7 +236,7 @@ class ContentDecryptionModule {
   // Cancels any pending key request made to the CDM for |session_id|.

[scherkus (not reviewing), 2012/09/05 16:43:43]

add blank line below to separate function summary from return statements

[xhwang, 2012/09/05 17:13:30]

Done.

   // Returns kSuccess if all pending key requests for |session_id| were
   // successfully canceled or there was no key request to be canceled.
-  // Returns kErrorUnknown otherwise.
+  // Returns kError otherwise.

[scherkus (not reviewing), 2012/09/05 16:43:43]

ditto

[xhwang, 2012/09/05 17:13:30]

Done.

   virtual Status CancelKeyRequest(const char* session_id,
                                   int session_id_size) = 0;
 
@@ -167,10 +244,11 @@ class ContentDecryptionModule {
   // Returns kSuccess if decryption succeeded, in which case the callee
   // should have filled the |decrypted_buffer| and passed the ownership of
   // |data| in |decrypted_buffer| to the caller.
-  // Returns kErrorNoKey if the CDM did not have the necessary decryption key
+  // Returns kNoKey if the CDM did not have the necessary decryption key
   // to decrypt.
-  // Returns kErrorUnknown if any other error happened.
-  // In these two cases, |decrypted_buffer| should not be used by the caller.
+  // Returns kError if any other error happened.

[scherkus (not reviewing), 2012/09/05 16:43:43]

Returns kSuccess if the key was successfully added, kError otherwise.

[xhwang, 2012/09/05 17:13:30]

This doesn't apply directly. I'll keep it as is.

+  // If the return value is not kSuccess, |decrypted_buffer| should be ignored
+  // by the caller.
   //
   // TODO(xhwang): It's not safe to pass the ownership of the dynamically
   // allocated memory over library boundaries. Fix it after related PPAPI change
@@ -178,6 +256,48 @@ class ContentDecryptionModule {
   virtual Status Decrypt(const InputBuffer& encrypted_buffer,
                          OutputBuffer* decrypted_buffer) = 0;
 
+  // Initializes the CDM video decoder with |video_decoder_config|. This
+  // function must be called before DecryptAndDecodeVideo() is called.

[scherkus (not reviewing), 2012/09/05 16:43:43]

add blank line below to separate function summary from return statements

[xhwang, 2012/09/05 17:13:30]

Done.

+  // Returns kSuccess if the |video_decoder_config| is supported and the CDM
+  // video decoder is successfully initialized.
+  // Returns kError if |video_decoder_config| is not supported. The CDM may
+  // still be able to do Decrypt().
+  //
+  // TODO(xhwang): Add stream ID here and in the following video decoder
+  // functions when we need to support multiple video streams in one CDM.
+  virtual Status InitializeVideoDecoder(
+      const VideoDecoderConfig& video_decoder_config) = 0;
+
+  // Decrypts the |encrypted_buffer| and decodes the decrypted buffer into a
+  // |video_frame|. Upon end-of-stream, the caller should call this function
+  // repeatedly with empty |encrypted_buffer| (|data| == NULL) until only empty
+  // |video_frame| (|format| == kEmptyVideoFrame) is produced.

[scherkus (not reviewing), 2012/09/05 16:43:43]

add blank line below to separate function summary from return statements

[xhwang, 2012/09/05 17:13:30]

Done.

+  // Returns kSuccess if decryption and decoding both succeeded, in which case

[scherkus (not reviewing), 2012/09/05 16:43:43]

ditto for vertical whitespacing

[xhwang, 2012/09/05 17:13:30]

?

+  // the callee should have filled the |video_frame| and passed the ownership of
+  // |data| in |video_frame| to the caller.
+  // Returns kNoKey if the CDM did not have the necessary decryption key
+  // to decrypt.
+  // Returns kNeedMoreData if more data was needed by the decoder to generate
+  // a decoded frame (e.g. during initialization).
+  // Returns kError if any other (decryption or decoding) error happened.
+  // If the return value is not kSuccess, |video_frame| should be ignored by
+  // the caller.
+  //
+  // TODO(xhwang): It's not safe to pass the ownership of the dynamically
+  // allocated memory over library boundaries. Fix it after related PPAPI change
+  // and sample CDM are landed.
+  virtual Status DecryptAndDecodeVideo(const InputBuffer& encrypted_buffer,
+                                       VideoFrame* video_frame) = 0;
+
+  // Resets the CDM video decoder to an initialized clean state. All internally

[ddorwin, 2012/09/05 14:52:29]

s/internally/internal/

[xhwang, 2012/09/05 17:13:30]

Done.

+  // buffers will be flushed.
+  virtual void ResetVideoDecoder() = 0;
+
+  // Stops the CDM video decoder and sets it to an uninitialized state. The
+  // caller can call InitializeVideoDecoder() again after this call to

[scherkus (not reviewing), 2012/09/05 16:43:43]

do you have a use case for this?

if not I'd recommend simply deleting the object to signal stop

[xhwang, 2012/09/05 17:13:30]

This will be used for config change, in which case we want to do Stop then
Initialize with new config.

+  // re-initialize the video decoder.
+  virtual void StopVideoDecoder() = 0;
+
   virtual ~ContentDecryptionModule() {}
 };