PPAPI: Fix interface functions that take PP_CompletionCallbacks, but don't

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"
@@ skipping 34 matching lines @@
 // stream marker in the stream. Calls from left to right are functions that are
 // in PPB_VideoDecoder_Dev and calls from right to left are functions that are
 // in PPP_VideoDecoder_Dev interface.
 //
 //        Plugin                   VideoDecoder
 //          |###########################|
 //          |       Configuration       |
 //          |###########################|
 //          | GetConfigs                |
 //          |-------------------------->|
-//          | Create                    |
+//          | Create + Init             |
 //          |-------------------------->|  Decoder will ask for certain number
 //          | (Decode)                  |  of PictureBuffers. This may happen
 //          |- - - - - - - - - - - - - >|  either directly after constructor or
 //          |     ProvidePictureBuffers |  after Decode has decoded some of the
 //          |<--------------------------|  bitstream. Once resources have been
 //          | AssignPictureBuffer       |  acquired decoder calls
 //          |-------------------------->|  NotifyResourcesAcquired.
 //          |   NotifyResourcesAcquired |
 //          |<--------------------------|
 //          |                           |
@@ skipping 48 matching lines @@
   // 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,
                         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|.
+  // Creates a video decoder. Init() must be called afterwards to
+  // set its configuration.
+  //
+  // Parameters:
+  //   |instance| pointer to the plugin instance.
+  //
+  // The created decoder is returned as PP_Resource. 0 means failure.
+  PP_Resource (*Create)(PP_Instance instance);
+
+  // Initializes the video decoder with requested configuration.
   // |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.
-  //   |callback| called after initialize is complete.
+  //   |video_decoder| is the previously created handle to the decoder resource.
+  //   |decoder_config| the configuration to use to initialize the decoder.
+  //   |callback| called after initialization is complete.
   //
-  // The created decoder is returned as PP_Resource. NULL means failure.
-  PP_Resource (*Create)(PP_Instance instance,
-                        PP_VideoConfigElement* dec_config,
-                        struct PP_CompletionCallback callback);
+  // Returns an error code from pp_errors.h.
+  int32_t (*Init)(PP_Resource video_decoder,

[darin (slow to review), 2011/06/03 17:54:58]

nit: elsewhere we spell out Initialize.  I think we should be consistent and do
so here too.  Use words not abbreviations :)

[polina, 2011/06/03 19:35:04]

Done.

+                  PP_VideoConfigElement* decoder_config,
+                  struct PP_CompletionCallback callback);
 
   // 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.
+  //   |video_decoder| is the previously created handle to the decoder resource.
   //   |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,
+  // Returns an error code from pp_errors.h.
+  int32_t (*Decode)(PP_Resource video_decoder,
                     struct PP_VideoBitstreamBuffer_Dev* bitstream_buffer,
                     struct PP_CompletionCallback callback);
 
   // Provides the decoder with picture buffers for video decoding.
   // AssignGLESBuffers provides texture-backed buffers, whereas
   // AssignSysmemBuffers provides system memory-backed buffers.
   //
   // This function should be called when decoder has issued the
   // ProvidePictureBuffers callback to the plugin with buffer requirements.
   //
   // 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.
   //
   // 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.
   //
   // 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... in which case the output buffers should be
   // callback parameters to ProvidePictureBuffers instead of being part of the
   // PPB API.
   //
   // Parameters:
-  //   |video_decoder| is the previously created handle to the decoder instance.
+  //   |video_decoder| is the previously created handle to the decoder resource.
   //   |no_of_buffers| how many buffers are behind picture buffer pointer.
   //   |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);
   void (*AssignSysmemBuffers)(PP_Resource video_decoder,
                               uint32_t no_of_buffers,
                               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.
+  //   |video_decoder| is the previously created handle to the decoder resource.
   //   |picture_buffer_id| contains the id of the picture buffer that was
   //   processed.
   void (*ReusePictureBuffer)(PP_Resource video_decoder,
                              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.
+  //   |video_decoder| is the previously created handle to the decoder resource.
   //   |callback| is one-time callback that will be called once the flushing
   //   request has been completed.
   //
-  // Returns PP_TRUE on acceptance of flush request and PP_FALSE if request to
-  // flush is rejected by the decoder.
-  PP_Bool (*Flush)(PP_Resource video_decoder,
+  // Returns an error code from pp_errors.h.
+  int32_t (*Flush)(PP_Resource video_decoder,
                    struct PP_CompletionCallback callback);
 
   // Dispatches abortion request to the decoder to abort decoding as soon as
   // possible and will not output anything or generate new callbacks. |callback|
   // will be called as soon as abortion has been finished. After abortion all
   // buffers can be considered dismissed even when there has not been callbacks
   // to dismiss them.
   //
   // Parameters:
-  //   |video_decoder| is the previously created handle to the decoder instance.
+  //   |video_decoder| is the previously created handle to the decoder resource.
   //   |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,
+  // Returns an error code from pp_errors.h.
+  int32_t (*Abort)(PP_Resource video_decoder,
                    struct PP_CompletionCallback callback);
 };
 
 #endif  /* PPAPI_C_DEV_PPB_VIDEO_DECODER_DEV_H_ */