Pepper: add PPB_VideoEncoder interface

ppapi/api/ppb_video_encoder.idl

+/* Copyright (c) 2014 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.
+ */
+
+/**
+ * This file defines the <code>PPB_VideoEncoder</code> interface.
+ */
+[generate_thunk]
+
+label Chrome {
+  [channel=dev] M37 = 0.1
+};
+
+/**
+ * This typedef defines the signature that you implement to receive the
+ * encoder's initialization result.
+ *
+ * @param[in] encoder The encoder being initialized.
+ * @param[in] result If result is 0 (PP_OK), the operation succeeded.  Negative
+ * values (other than -1 or PP_OK_COMPLETE) indicate error and are specified
+ * in pp_errors.h.
+ * @param[in] input_frames_count A number of video frames the caller needs to
+ * allocate in order to make sure it's always capable of feeding the encoder.
+ * @param[in] input_coded_size The size of the video frames the caller should
+ * allocate to match the hardware constrains.
+ * @param[inout] user_data An opaque pointer that was passed into
+ * <code>PPB_VideoEncoder.Initialize()</code>.
+ */
+typedef void PPB_VideoEncoder_Ready_Func([in] PP_Resource encoder,
+                                         [in] int32_t result,
+                                         [in] uint32_t input_frames_count,
+                                         [in] PP_Size input_coded_size,
+                                         [inout] mem_t user_data);
+
+
+/**
+ * The <code>PPB_VideoEncoderParams</code> struct contains the parameters
+ * given to the video encoder to initialize itself.
+ */
+struct PP_VideoEncoderParams {
+  /**
+   * A <code>PP_Size</code> specifying the size of the frames to encode.
+   */
+  PP_Size input_size;
+
+  /**
+   * A <code>PP_VideoProfile</code> specifying the video codec profile.
+   */
+  PP_VideoProfile profile;
+
+  /**
+   * The bitrate of the video encoding.
+   */
+  uint32_t bitrate;
+
+  /**
+   * A <code>PP_Bool</code> specifying whether the encoder can fall back to
+   * software encoding if a suitable hardware encoder isn't available.
+   */
+  PP_Bool allow_software_fallback;
+};
+
+/**
+ * Struct describing a video picture to encode.
+ */
+struct PP_VideoEncoderPicture {
+  /**
+   * Texture ID of the picture to encode in the plugin's GL context.
+   */
+  uint32_t texture_id;
+
+  /**
+   * The GL texture target for the picture to encode.
+   * Possible values are:
+   *   GL_TEXTURE_2D                 (normalized texture coordinates)
+   *   GL_TEXTURE_RECTANGLE_ARB      (dimension dependent texture coordinates)
+   *
+   * The pixel format of the texture is GL_RGBA.
+   */
+  uint32_t texture_target;
+
+  /**
+   * Dimensions of the texture holding the picture to encode.
+   */
+  PP_Size texture_size;
+};
+
+/**
+ * Video encoder interface.
+ *
+ * Typical usage:
+ * - Call Create() to create a new video encoder resource.
+ * - Call Initialize() to initialize it with a 3d graphics context and the
+ *   desired codec profile.
+ * - Call Encode() continuously (waiting for each previous call to complete) to
+ *   push video frames to the encoder.
+ * - Call Reset() to quickly stop the encoder (e.g. to implement Seek) and wait
+ *   for the callback before restarting decoding at another point.
+ * - To destroy the encoder, the plugin should release all of its references to
+ *   it. Any pending callbacks will abort before the encoder is destroyed.
+ *
+ * Available video codecs vary by platform.
+ * All: vp8, vp9.
+ */
+interface PPB_VideoEncoder {
+  /**
+   * Creates a new video encoder resource.
+   *
+   * @param[in] instance A <code>PP_Instance</code> identifying the instance
+   * with the video encoder.
+   *
+   * @return A <code>PP_Resource</code> corresponding to a video encoder if
+   * successful or 0 otherwise.
+   */
+  PP_Resource Create(
+      [in] PP_Instance instance);
+
+  /**
+   * Determines if the given resource is a video encoder.
+   *
+   * @param[in] resource A <code>PP_Resource</code> identifying a resource.
+   *
+   * @return <code>PP_TRUE</code> if the resource is a
+   * <code>PPB_VideoEncoder</code>, <code>PP_FALSE</code> if the resource is
+   * invalid or some other type.
+   */
+  PP_Bool IsVideoEncoder(
+      [in] PP_Resource resource);
+
+  /**
+   * Initializes a video encoder resource. This should be called after
+   * Create() and before any other functions.
+   *
+   * @param[in] video_encoder A <code>PP_Resource</code> identifying the video
+   * encoder.
+   * @param[in] params A <code>PP_VideoEncoderParams</code> specifying the
+   * parameters to initialize the video encoder.
+   * @param[inout] user_data An opaque pointer that will be passed into
+   * <code>callback</code>.
+   * @param[in] callback A <code>PPB_VideoEncoder_Ready_Func</code> to be
+   * called upon completion.
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
+   * Returns PP_ERROR_FAILED if the video encoder has already been initialized
+   * or the submitted 3d context is invalid.
+   * Returns PP_ERROR_NOTSUPPORTED if video encoding is not available, or the
+   * requested profile is not supported. In this case, the client may call
+   * Initialize() again with different parameters to find a good configuration.
+   */
+  int32_t Initialize(
+      [in] PP_Resource video_encoder,
+      [in] PP_Resource graphics3d_context,
+      [in] PP_VideoEncoderParams params,
+      [inout] mem_t user_data,
+      [in] PPB_VideoEncoder_Ready_Func callback);
+
+  /**
+   * Encodes a video frame. The plugin should wait until the encoder signals
+   * completion by returning PP_OK or by running |callback| before calling
+   * Encode() again. The plugin will be notified by the
+   * <code>PPP_VideoEncoder</code> interface when video bitstream buffer are
+   * ready.
+   *
+   * @param[in] video_encoder A <code>PP_Resource</code> identifying the video
+   * encoder.
+   * @param[in] picture A <code>PP_VideoEncoderPicture</code> picture.
+   * @param[in] force_keyframe Forces the encoding of a keyframe for this
+   * picture.
+   * @param[in] callback A <code>PP_CompletionCallback_Dev</code> to be called on
+   * completion.
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
+   * Returns PP_ERROR_BADARGUMENT if the |picture| argument is invalid.
+   * Returns PP_ERROR_FAILED if the encoder isn't initialized or the picture
+   * buffer submitted is already used by the encoder.
+   * Returns PP_ERROR_INPROGRESS if this function has already been called and is
+   * already for an encoding operation to complete.
+   */
+  int32_t Encode(
+      [in] PP_Resource video_encoder,
+      [in] uint32_t encode_id,
+      [in] PP_VideoEncoderPicture picture,
+      [in] PP_Bool force_keyframe,
+      [in] PP_CompletionCallback callback);
+
+  /**
+   * Resets the encoder as quickly as possible. The plugin can call Reset() to
+   * skip to another position in the video stream. After Reset() returns, any
+   * pending calls to Encode() abort, causing their callbacks to run with
+   * PP_ERROR_ABORTED. The plugin should not make further calls to the encoder
+   * until the encoder signals completion by running |callback|.
+   *
+   * @param[in] video_encoder A <code>PP_Resource</code> identifying the video
+   * encoder.
+   * @param[in] callback A <code>PP_CompletionCallback</code> to be called on
+   * completion.
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
+   * Returns PP_ERROR_FAILED if the encoder isn't initialized.
+   */
+  int32_t Reset(
+      [in] PP_Resource video_encoder,
+      [in] PP_CompletionCallback callback);
+};