Update VideoDecode PPAPI structs to be consistent with media structures, part 1

ppapi/c/dev/ppb_video_decoder_dev.h

 /* Copyright (c) 2011 The Chromium Authors. All rights reserved.
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
 #ifndef PPAPI_C_DEV_PPB_VIDEO_DECODER_DEV_H_
 #define PPAPI_C_DEV_PPB_VIDEO_DECODER_DEV_H_
 
 #include "ppapi/c/dev/pp_video_dev.h"
 #include "ppapi/c/pp_completion_callback.h"
 #include "ppapi/c/pp_var.h"
 
-#define PPB_VIDEODECODER_DEV_INTERFACE_0_5 "PPB_VideoDecoder(Dev);0.5"
-#define PPB_VIDEODECODER_DEV_INTERFACE PPB_VIDEODECODER_DEV_INTERFACE_0_5
+#define PPB_VIDEODECODER_DEV_INTERFACE_0_6 "PPB_VideoDecoder(Dev);0.6"
+#define PPB_VIDEODECODER_DEV_INTERFACE PPB_VIDEODECODER_DEV_INTERFACE_0_6
 
 // Video decoder interface.
 //
 // Basic usage:
 //   1. Use GetConfigs() to query potential configurations. Configuration
 //   information includes:
 //     a. Bitstream format.
 //     b. Output picture format.
 //     c. Output picture buffer storage type.
 //   2. Select configuration that suits you and Create() the decoder with the
@@ skipping 39 matching lines @@
   // with valid elements to the buffer pointed by |matching_configs|. No more
   // than |config_size| PP_VideoConfig_Devs will be returned even if more would
   // be available for the decoder device.
   //
   // When this function is called with |matching_configs| = NULL, then no
   // configurations are returned, but the total number of PP_VideoConfig_Devs
   // available will be returned in |num_of_matching_configs|.
   //
   // Returns PP_TRUE on success, PP_FALSE otherwise.
   PP_Bool (*GetConfigs)(PP_Instance instance,
-                        struct PP_VideoDecoderConfig_Dev* proto_config,
-                        struct PP_VideoDecoderConfig_Dev* matching_configs,
-                        int32_t matching_configs_size,
-                        int32_t* num_of_matching_configs);
+                        PP_VideoConfigElement* proto_config,
+                        PP_VideoConfigElement* matching_configs,
+                        uint32_t matching_configs_size,
+                        uint32_t* num_of_matching_configs);
 
   // Creates a video decoder with requested |decoder_config|.
   // |input_format| in |decoder_config| specifies the format of input access
   // unit, with PP_VIDEOKEY_CODECID and PP_VIDEOKEY_PAYLOADFORMAT required.
   // Plugin has the option to specify codec profile/level and other
   // information such as PP_VIDEOKEY_ACCELERATION, to let browser choose
   // the most appropriate decoder.
   //
   // Parameters:
   //   |instance| pointer to the plugin instance.
   //   |dec_config| the configuration which to use to initialize the decoder.
   //
   // The created decoder is returned as PP_Resource. NULL means failure.
   PP_Resource (*Create)(PP_Instance instance,
-                        struct PP_VideoDecoderConfig_Dev* dec_config);
+                        PP_VideoConfigElement* dec_config);
 
   // Tests whether |resource| is a video decoder created through Create
   // function of this interface.
   //
   // Parameters:
   //   |resource| is handle to resource to test.
   //
   // Returns true if is a video decoder, false otherwise.
   PP_Bool (*IsVideoDecoder)(PP_Resource resource);
 
   // Dispatches bitstream buffer to the decoder. This is asynchronous and
   // non-blocking function.
   //
   // Parameters:
   //   |video_decoder| is the previously created handle to the decoder instance.
   //   |bitstream_buffer| is the bitstream buffer that contains the input data.
   //   |callback| will be called when |bitstream_buffer| has been processed by
   //   the decoder.
   //
   // Returns PP_TRUE on decoder successfully accepting buffer, PP_FALSE
   // otherwise.
   PP_Bool (*Decode)(PP_Resource video_decoder,
                     struct PP_VideoBitstreamBuffer_Dev* bitstream_buffer,
                     struct PP_CompletionCallback callback);
 
-  // Provides the decoder with picture buffers for video decoding. This
-  // function should be called when decoder has issued ProvidePictureBuffers
-  // callback to the plugin with buffer requirements.
+  // Provides the decoder with texture-backed picture buffers for video
+  // decoding.
   //
-  // If the plugin is can determine how many and what kind of buffers are
-  // needed by the decoder it can provide them in advance. For this purpose
-  // the configuration map can provide how many extra buffers the decoder
-  // implementation requires for seamless operation.
+  // This function should be called when decoder has issued the
+  // ProvidePictureBuffers callback to the plugin with buffer requirements.
   //
-  // The decoder will pause if AssignPictureBuffer hasn't been called with
-  // sufficient buffers.
+  // It can also be called in advance or outside of ProvidePictureBuffers calls
+  // to provide the decoder with additional buffers. Additional buffers will be
+  // added to the decoder's buffer pool.
   //
-  // If the decoder rejects the buffers it will return the buffers and issue
+  // The decoder will pause in decoding if it has not received enough buffers.
+  //
+  // If the buffer is invalid, the decoder will return the buffer and will issue
   // ProvidePictureBuffers again.
   //
-  // If AssignPictureBuffer is called multiple times the decoder will add them
-  // to its pool of output pictures.
-  //
-  // TODO(vmr): this API feels too flexible... should we make it more strict
-  // where the decoder errors on bad buffers/duplicate buffers? Perhaps
-  // AssignPictureBuffer should only get called in response to
-  // ProvidePictureBuffer?
+  // TODO(vmr/vrk): Decide if the API is too flexible, i.e. stricter rules on
+  // errors/duplicates or requiring Assign*Buffers to only be called in response
+  // to ProvidePictureBuffers.

[Ami GONE FROM CHROMIUM, 2011/05/03 23:34:47]

...in which case they should just be callback parameters to
ProvidePictureBuffers instead of being part of the PPB API.

[vrk (LEFT CHROMIUM), 2011/05/05 05:57:12]

Good point. Added this almost verbatim to the comment! :)

   //
   // Parameters:
   //   |video_decoder| is the previously created handle to the decoder instance.
   //   |no_of_buffers| how many buffers are behind picture buffer pointer.
-  //   |picture_buffer| contains the reference to the picture buffer that was
-  //   processed.
-  void (*AssignPictureBuffer)(PP_Resource video_decoder,
+  //   |buffers| contains the reference to the picture buffer that was
+  //   allocated.
+  void (*AssignGLESBuffers)(PP_Resource video_decoder,
+                            uint32_t no_of_buffers,
+                            struct PP_GLESBuffer_Dev* buffers);
+
+  // Provides the decoder with system memory-backed picture buffers for video

[Ami GONE FROM CHROMIUM, 2011/05/03 23:34:47]

I think this comment & the newline preceding it can be elided, and the comment
on the previous function modified slightly to cover both.

[vrk (LEFT CHROMIUM), 2011/05/05 05:57:12]

Done. I did a similar thing with the comments for the respective methods in
video_decode_accelerator.h.

+  // decoding.
+  //
+  // Please see comment in AssignGLESBuffers for usage; it is the same as
+  // AssignGLES except it is for buffers in system memory, not GPU.
+  //
+  // Parameters:
+  //   |video_decoder| is the previously created handle to the decoder instance.
+  //   |no_of_buffers| how many buffers are behind picture buffer pointer.
+  //   |buffers| contains the reference to the picture buffer that was
+  //   allocated.
+  void (*AssignSysmemBuffers)(PP_Resource video_decoder,
                               uint32_t no_of_buffers,
-                              union PP_PictureData_Dev* picture_buffer);
+                              struct PP_SysmemBuffer_Dev* buffers);
 
   // Tells the decoder to reuse given picture buffer. Typical use of this
   // function is to call from PictureReady callback to recycle picture buffer
   // back to the decoder after blitting the image so that decoder can use the
   // image for output again.
   //
   // The decoder will ignore any picture buffer not previously provided via
   // AssignPictureBuffer.
   //
   // TODO(vmr): figure out how the sync will be handled with command buffer as
   //            there will be possibly lag due to command buffer implementation
   //            to actual GL swap. At that moment decoder may have already taken
   //            the GL textures for writing output again.
   //
   // Parameters:
   //   |video_decoder| is the previously created handle to the decoder instance.
   //   |picture_buffer| contains the reference to the picture buffer that was
   //   processed.
   void (*ReusePictureBuffer)(PP_Resource video_decoder,
-                             union PP_PictureData_Dev* picture_buffer);
+                             int32_t picture_buffer_id);
 
   // Dispatches flushing request to the decoder to flush both input and output
   // buffers. Successful flushing will result in output of the pictures and
   // buffers held inside the decoder and returning of bitstream buffers using
   // the callbacks implemented by the plug-in. Once done with flushing, the
   // decode will call the |callback|.
   //
   // Parameters:
   //   |video_decoder| is the previously created handle to the decoder instance.
   //   |callback| is one-time callback that will be called once the flushing
@@ skipping 15 matching lines @@
   //   |callback| is one-time callback that will be called once the abortion
   //   request has been completed.
   //
   // Returns PP_TRUE on acceptance of abort request and PP_FALSE if request to
   // abort is rejected by the decoder.
   PP_Bool (*Abort)(PP_Resource video_decoder,
                    struct PP_CompletionCallback callback);
 };
 
 #endif  /* PPAPI_C_DEV_PPB_VIDEO_DECODER_DEV_H_ */