ppapi/c/ppb_image_data.h

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