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 */
64typedef enum {
65  PP_IMAGEDATAFORMAT_BGRA_PREMUL,
66  PP_IMAGEDATAFORMAT_RGBA_PREMUL
67} PP_ImageDataFormat;
68PP_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 */
81struct 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};
95PP_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 */
108struct 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
202typedef struct PPB_ImageData_1_0 PPB_ImageData;
203/**
204 * @}
205 */
206
207#endif  /* PPAPI_C_PPB_IMAGE_DATA_H_ */
208
209