Update the IDL

Final update of the IDL so that we can switch to using
generated code for ppapi/c/ and ppapi/c/trusted.


BUG= http://code.google.com/p/chromium/issues/detail?id=74634
TEST= tryserver
TBR= dmichael@chromium.org
Review URL: http://codereview.chromium.org/7390023

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@92805 0039d316-1c4b-4281-b951-d872f2087c98

1 files changed, 133 insertions, 35 deletions

diff --git a/ppapi/api/ppb_image_data.idl b/ppapi/api/ppb_image_data.idl
index aa3cbd0..f7fc63d 100644
--- a/ppapi/api/ppb_image_data.idl
+++ b/ppapi/api/ppb_image_data.idl
@@ -3,56 +3,125 @@
  * found in the LICENSE file.
  */
 
-/* Defines the image data API. */
+/**
+ * This file defines the <code>PPB_ImageData</code> struct for determining how
+ * a browser handles image data.
+ */
+
+ label Chrome {
+   M13 = 0.3,
+   M14 = 1.0
+ };
 
-/* Bitmap formats. */
+/**
+ * <code>PP_ImageDataFormat</code> is an enumeration of the different types of
+ * image data formats.
+ *
+ * The third part of each enumeration value describes the memory layout from
+ * the lowest address to the highest. For example, BGRA means the B component
+ * is stored in the lowest address, no matter what endianness the platform is
+ * using.
+ *
+ * The PREMUL suffix implies pre-multiplied alpha is used. In this mode, the
+ * red, green and blue color components of the pixel data supplied to an image
+ * data should be pre-multiplied by their alpha value. For example: starting
+ * with floating point color components, here is how to convert them to 8-bit
+ * premultiplied components for image data:
+ *
+ * ...components of a pixel, floats ranging from 0 to 1...
+ * <code>float red = 1.0f;</code>
+ * <code><code>float green = 0.50f;</code>
+ * <code>float blue = 0.0f;</code>
+ * <code>float alpha = 0.75f;</code>
+ * ...components for image data are 8-bit values ranging from 0 to 255...
+ * <code>uint8_t image_data_red_premul = (uint8_t)(red * alpha * 255.0f);
+ * </code>
+ * <code>uint8_t image_data_green_premul = (uint8_t)(green * alpha * 255.0f);
+ * </code>
+ * <code>uint8_t image_data_blue_premul = (uint8_t)(blue * alpha * 255.0f);
+ * </code>
+ * <code>uint8_t image_data_alpha_premul = (uint8_t)(alpha * 255.0f);</code>
+ *
+ * <strong>Note:</strong> The resulting pre-multiplied red, green and blue
+ * components should not be greater than the alpha value.
+ */
+[assert_size(4)]
 enum PP_ImageDataFormat {
-  /* 32 bits, BGRA byte order, premultiplied alpha */
-  PP_IMAGEDATAFORMAT_BGRA_PREMUL = 0,
-  /* 32 bits, RGBA byte order, premultiplied alpha */
-  PP_IMAGEDATAFORMAT_RGBA_PREMUL = 1
+  PP_IMAGEDATAFORMAT_BGRA_PREMUL,
+  PP_IMAGEDATAFORMAT_RGBA_PREMUL
 };
 
-/* Description of a bitmap. */
+/**
+ * The <code>PP_ImageDataDesc</code> structure represents a description of
+ * image data.
+ */
+[assert_size(16)]
 struct PP_ImageDataDesc {
-  /* Byte format. */
+  /**
+   * This value represents one of the image data types in the
+   * <code>PP_ImageDataFormat</code> enum.
+   */
   PP_ImageDataFormat format;
 
-  /* Size of the bitmap in pixels. */
+  /** This value represents the size of the bitmap in pixels. */
   PP_Size size;
 
-  /* The row width in bytes. This may be different than width * 4 since there
-   * may be padding at the end of the lines.
+  /**
+   * This value represents the row width in bytes. This may be different than
+   * width * 4 since there may be padding at the end of the lines.
    */
   int32_t stride;
 };
 
-/* Interface for manipulating 2D bitmaps. */
-interface PPB_ImageData_0_3 {
-  /* Returns the browser's preferred format for image data. This format will be
-   * the format is uses internally for painting. Other formats may require
-   * internal conversions to paint or may have additional restrictions depending
-   * on the function.
+/**
+ * The <code>PPB_ImageData</code> interface contains pointers to several
+ * functions for determining the browser's treatment of image data.
+ */
+[version=0.3]
+interface PPB_ImageData {
+  /**
+   * GetNativeImageDataFormat() returns the browser's preferred format for
+   * image data. The browser uses this format internally for painting. Other
+   * formats may require internal conversions to paint or may have additional
+   * restrictions depending on the function.
+   *
+   * @return A <code>PP_ImageDataFormat</code> containing the preferred format.
    */
   PP_ImageDataFormat GetNativeImageDataFormat();
 
-  /* Returns PP_TRUE if the given image data format is supported by the browser.
+  /**
+   * IsImageDataFormatSupported() determines if the given image data format is
+   * supported by the browser.
+   *
+   * @param[in] format The image data format.
+   *
+   * @return A <code>PP_Bool</code> with <code>PP_TRUE</code> if the given
+   * image data format is supported by the browser.
    */
   PP_Bool IsImageDataFormatSupported(
       [in] PP_ImageDataFormat format);
 
-  /* Allocates an image data resource with the given format and size. The
-   * return value will have a nonzero ID on success, or zero on failure.
-   * Failure means the instance, image size, or format was invalid.
-   *
-   * Set the init_to_zero flag if you want the bitmap initialized to
-   * transparent during the creation process. If this flag is not set, the
-   * current contents of the bitmap will be undefined, and the plugin should
-   * be sure to set all the pixels.
+  /**
+   * Create() allocates an image data resource with the given format and size.
    *
    * For security reasons, if uninitialized, the bitmap will not contain random
    * memory, but may contain data from a previous image produced by the same
-   * plugin if the bitmap was cached and re-used.
+   * module if the bitmap was cached and re-used.
+   *
+   * @param[in] instance A <code>PP_Instance</code> indentifying one instance
+   * of a module.
+   * @param[in] format The desired image data format.
+   * @param[in] size A pointer to a <code>PP_Size</code> containing the image
+   * size.
+   * @param[in] init_to_zero A <code>PP_Bool</code> to determine transparency
+   * at creation.
+   * Set the <code>init_to_zero</code> flag if you want the bitmap initialized
+   * to transparent during the creation process. If this flag is not set, the
+   * current contents of the bitmap will be undefined, and the module should
+   * be sure to set all the pixels.
+   *
+   * @return A <code>PP_Resource</code> with a nonzero ID on succes or zero on
+   * failure. Failure means the instance, image size, or format was invalid.
    */
   PP_Resource Create(
       [in] PP_Instance instance,
@@ -60,27 +129,56 @@ interface PPB_ImageData_0_3 {
       [in] PP_Size size,
       [in] PP_Bool init_to_zero);
 
-  /* Returns PP_TRUE if the given resource is an image data. Returns PP_FALSE if
-   * the resource is invalid or some type other than an image data.
+  /**
+   * IsImageData() determiens if a given resource is image data.
+   *
+   * @param[in] image_data A <code>PP_Resource</code> corresponding to image
+   * data.
+   *
+   * @return A <code>PP_Bool</code> with <code>PP_TRUE</code> if the given
+   * resrouce is an image data or <code>PP_FALSE</code> if the resource is
+   * invalid or some type other than image data.
    */
   PP_Bool IsImageData(
       [in] PP_Resource image_data);
 
-  /* Computes the description of the image data. Returns PP_TRUE on success,
-   * PP_FALSE if the resource is not an image data. On PP_FALSE, the |desc|
-   * structure will be filled with 0.
+  /**
+   * Describe() computes the description of the
+   * image data.
+   *
+   * @param[in] image_data A <code>PP_Resource</code> corresponding to image
+   * data.
+   * @param[in,out] desc A pointer to a <code>PP_ImageDataDesc</code>
+   * containing the description.
+   *
+   * @return A <code>PP_Bool</code> with <code>PP_TRUE</code> on success or
+   * <code>PP_FALSE</code> if the resource is not an image data. On
+   * <code>PP_FALSE</code>, the <code>desc</code> structure will be filled
+   * with 0.
    */
   PP_Bool Describe(
       [in] PP_Resource image_data,
       [out] PP_ImageDataDesc desc);
 
-  /* Maps this bitmap into the plugin address space and returns a pointer to the
-   * beginning of the data.
+  /**
+   * Map() maps an image data into the module address space.
+   *
+   * @param[in] image_data A <code>PP_Resource</code> corresponding to image
+   * data.
+   *
+   * @return A pointer to the beginning of the data.
    */
   mem_t Map(
       [in] PP_Resource image_data);
 
-  /* Unmaps this bitmaps from the plugin address space */
+  /**
+   * Unmap is a pointer to a function that unmaps an image data from the module
+   * address space.
+   *
+   * @param[in] image_data A <code>PP_Resource</code> corresponding to image
+   * data.
+   */
   void Unmap(
       [in] PP_Resource image_data);
 };
+