Listen to menuListValueChanged events to support <select>
[chromium-blink-merge.git] / ppapi / api / ppb_image_data.idl
blob8e1d09dc2634a4036255cfc86d5361b743fa0c75
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 */
6 /**
7 * This file defines the <code>PPB_ImageData</code> struct for determining how
8 * a browser handles image data.
9 */
11 [generate_thunk]
13 label Chrome {
14 M14 = 1.0
17 /**
18 * <code>PP_ImageDataFormat</code> is an enumeration of the different types of
19 * image data formats.
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.
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:
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>
46 * <strong>Note:</strong> The resulting pre-multiplied red, green and blue
47 * components should not be greater than the alpha value.
49 [assert_size(4)]
50 enum PP_ImageDataFormat {
51 PP_IMAGEDATAFORMAT_BGRA_PREMUL,
52 PP_IMAGEDATAFORMAT_RGBA_PREMUL
55 /**
56 * The <code>PP_ImageDataDesc</code> structure represents a description of
57 * image data.
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.
65 PP_ImageDataFormat format;
67 /** This value represents the size of the bitmap in pixels. */
68 PP_Size size;
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.
74 int32_t stride;
77 /**
78 * The <code>PPB_ImageData</code> interface contains pointers to several
79 * functions for determining the browser's treatment of image data.
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.
88 * @return A <code>PP_ImageDataFormat</code> containing the preferred format.
90 PP_ImageDataFormat GetNativeImageDataFormat();
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.
99 * @param[in] format The image data format.
101 * @return A <code>PP_Bool</code> with <code>PP_TRUE</code> if the given
102 * image data format is supported by the browser.
104 PP_Bool IsImageDataFormatSupported(
105 [in] PP_ImageDataFormat format);
108 * Create() allocates an image data resource with the given format and size.
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.
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.
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.
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);
136 * IsImageData() determines if a given resource is image data.
138 * @param[in] image_data A <code>PP_Resource</code> corresponding to image
139 * data.
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.
145 PP_Bool IsImageData(
146 [in] PP_Resource image_data);
149 * Describe() computes the description of the
150 * image data.
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.
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.
162 [always_set_output_parameters]
163 PP_Bool Describe(
164 [in] PP_Resource image_data,
165 [out] PP_ImageDataDesc desc);
168 * Map() maps an image data into the module address space.
170 * @param[in] image_data A <code>PP_Resource</code> corresponding to image
171 * data.
173 * @return A pointer to the beginning of the data.
175 mem_t Map(
176 [in] PP_Resource image_data);
179 * Unmap is a pointer to a function that unmaps an image data from the module
180 * address space.
182 * @param[in] image_data A <code>PP_Resource</code> corresponding to image
183 * data.
185 void Unmap(
186 [in] PP_Resource image_data);