src/ppapi/api/ppb_image_data.idl

   1 /* Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2  * Use of this source code is governed by a BSD-style license that can be
   3  * found in the LICENSE file.
   4  */
   5
   6 /**
   7  * This file defines the <code>PPB_ImageData</code> struct for determining how
   8  * a browser handles image data.
   9  */
  10
  11 [generate_thunk]
  12
  13 label Chrome {
  14   M14 = 1.0
  15 };
  16
  17 /**
  18  * <code>PP_ImageDataFormat</code> is an enumeration of the different types of
  19  * image data formats.
  20  *
  21  * The third part of each enumeration value describes the memory layout from
  22  * the lowest address to the highest. For example, BGRA means the B component
  23  * is stored in the lowest address, no matter what endianness the platform is
  24  * using.
  25  *
  26  * The PREMUL suffix implies pre-multiplied alpha is used. In this mode, the
  27  * red, green and blue color components of the pixel data supplied to an image
  28  * data should be pre-multiplied by their alpha value. For example: starting
  29  * with floating point color components, here is how to convert them to 8-bit
  30  * premultiplied components for image data:
  31  *
  32  * ...components of a pixel, floats ranging from 0 to 1...
  33  * <code>float red = 1.0f;</code>
  34  * <code>float green = 0.50f;</code>
  35  * <code>float blue = 0.0f;</code>
  36  * <code>float alpha = 0.75f;</code>
  37  * ...components for image data are 8-bit values ranging from 0 to 255...
  38  * <code>uint8_t image_data_red_premul = (uint8_t)(red * alpha * 255.0f);
  39  * </code>
  40  * <code>uint8_t image_data_green_premul = (uint8_t)(green * alpha * 255.0f);
  41  * </code>
  42  * <code>uint8_t image_data_blue_premul = (uint8_t)(blue * alpha * 255.0f);
  43  * </code>
  44  * <code>uint8_t image_data_alpha_premul = (uint8_t)(alpha * 255.0f);</code>
  45  *
  46  * <strong>Note:</strong> The resulting pre-multiplied red, green and blue
  47  * components should not be greater than the alpha value.
  48  */
  49 [assert_size(4)]
  50 enum PP_ImageDataFormat {
  51   PP_IMAGEDATAFORMAT_BGRA_PREMUL,
  52   PP_IMAGEDATAFORMAT_RGBA_PREMUL
  53 };
  54
  55 /**
  56  * The <code>PP_ImageDataDesc</code> structure represents a description of
  57  * image data.
  58  */
  59 [assert_size(16)]
  60 struct PP_ImageDataDesc {
  61   /**
  62    * This value represents one of the image data types in the
  63    * <code>PP_ImageDataFormat</code> enum.
  64    */
  65   PP_ImageDataFormat format;
  66
  67   /** This value represents the size of the bitmap in pixels. */
  68   PP_Size size;
  69
  70   /**
  71    * This value represents the row width in bytes. This may be different than
  72    * width * 4 since there may be padding at the end of the lines.
  73    */
  74   int32_t stride;
  75 };
  76
  77 /**
  78  * The <code>PPB_ImageData</code> interface contains pointers to several
  79  * functions for determining the browser's treatment of image data.
  80  */
  81 interface PPB_ImageData {
  82   /**
  83    * GetNativeImageDataFormat() returns the browser's preferred format for
  84    * image data. The browser uses this format internally for painting. Other
  85    * formats may require internal conversions to paint or may have additional
  86    * restrictions depending on the function.
  87    *
  88    * @return A <code>PP_ImageDataFormat</code> containing the preferred format.
  89    */
  90   PP_ImageDataFormat GetNativeImageDataFormat();
  91
  92   /**
  93    * IsImageDataFormatSupported() determines if the given image data format is
  94    * supported by the browser. Note: <code>PP_IMAGEDATAFORMAT_BGRA_PREMUL</code>
  95    * and <code>PP_IMAGEDATAFORMAT_RGBA_PREMUL</code> formats are always
  96    * supported. Other image formats do not make this guarantee, and should be
  97    * checked first with IsImageDataFormatSupported() before using.
  98    *
  99    * @param[in] format The image data format.
 100    *
 101    * @return A <code>PP_Bool</code> with <code>PP_TRUE</code> if the given
 102    * image data format is supported by the browser.
 103    */
 104   PP_Bool IsImageDataFormatSupported(
 105       [in] PP_ImageDataFormat format);
 106
 107   /**
 108    * Create() allocates an image data resource with the given format and size.
 109    *
 110    * For security reasons, if uninitialized, the bitmap will not contain random
 111    * memory, but may contain data from a previous image produced by the same
 112    * module if the bitmap was cached and re-used.
 113    *
 114    * @param[in] instance A <code>PP_Instance</code> identifying one instance
 115    * of a module.
 116    * @param[in] format The desired image data format.
 117    * @param[in] size A pointer to a <code>PP_Size</code> containing the image
 118    * size.
 119    * @param[in] init_to_zero A <code>PP_Bool</code> to determine transparency
 120    * at creation.
 121    * Set the <code>init_to_zero</code> flag if you want the bitmap initialized
 122    * to transparent during the creation process. If this flag is not set, the
 123    * current contents of the bitmap will be undefined, and the module should
 124    * be sure to set all the pixels.
 125    *
 126    * @return A <code>PP_Resource</code> with a nonzero ID on success or zero on
 127    * failure. Failure means the instance, image size, or format was invalid.
 128    */
 129   PP_Resource Create(
 130       [in] PP_Instance instance,
 131       [in] PP_ImageDataFormat format,
 132       [in] PP_Size size,
 133       [in] PP_Bool init_to_zero);
 134
 135   /**
 136    * IsImageData() determines if a given resource is image data.
 137    *
 138    * @param[in] image_data A <code>PP_Resource</code> corresponding to image
 139    * data.
 140    *
 141    * @return A <code>PP_Bool</code> with <code>PP_TRUE</code> if the given
 142    * resource is an image data or <code>PP_FALSE</code> if the resource is
 143    * invalid or some type other than image data.
 144    */
 145   PP_Bool IsImageData(
 146       [in] PP_Resource image_data);
 147
 148   /**
 149    * Describe() computes the description of the
 150    * image data.
 151    *
 152    * @param[in] image_data A <code>PP_Resource</code> corresponding to image
 153    * data.
 154    * @param[in,out] desc A pointer to a <code>PP_ImageDataDesc</code>
 155    * containing the description.
 156    *
 157    * @return A <code>PP_Bool</code> with <code>PP_TRUE</code> on success or
 158    * <code>PP_FALSE</code> if the resource is not an image data. On
 159    * <code>PP_FALSE</code>, the <code>desc</code> structure will be filled
 160    * with 0.
 161    */
 162   [always_set_output_parameters]
 163   PP_Bool Describe(
 164       [in] PP_Resource image_data,
 165       [out] PP_ImageDataDesc desc);
 166
 167   /**
 168    * Map() maps an image data into the module address space.
 169    *
 170    * @param[in] image_data A <code>PP_Resource</code> corresponding to image
 171    * data.
 172    *
 173    * @return A pointer to the beginning of the data.
 174    */
 175   mem_t Map(
 176       [in] PP_Resource image_data);
 177
 178   /**
 179    * Unmap is a pointer to a function that unmaps an image data from the module
 180    * address space.
 181    *
 182    * @param[in] image_data A <code>PP_Resource</code> corresponding to image
 183    * data.
 184    */
 185   void Unmap(
 186       [in] PP_Resource image_data);
 187 };
 188