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 209