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 189
