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
13label 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)]
50enum 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)]
60struct 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 */
81interface 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