cc: Added inline to Tile::IsReadyToDraw
[chromium-blink-merge.git] / ppapi / c / ppb_graphics_3d.h
blobc9ed91cba21d5fc4788b6e82e28d298fe6e3f8d2
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 /* From ppb_graphics_3d.idl modified Fri Aug 30 08:36:16 2013. */
8 #ifndef PPAPI_C_PPB_GRAPHICS_3D_H_
9 #define PPAPI_C_PPB_GRAPHICS_3D_H_
11 #include "ppapi/c/pp_bool.h"
12 #include "ppapi/c/pp_completion_callback.h"
13 #include "ppapi/c/pp_instance.h"
14 #include "ppapi/c/pp_macros.h"
15 #include "ppapi/c/pp_resource.h"
16 #include "ppapi/c/pp_stdint.h"
18 #define PPB_GRAPHICS_3D_INTERFACE_1_0 "PPB_Graphics3D;1.0"
19 #define PPB_GRAPHICS_3D_INTERFACE PPB_GRAPHICS_3D_INTERFACE_1_0
21 /**
22 * @file
23 * Defines the <code>PPB_Graphics3D</code> struct representing a 3D graphics
24 * context within the browser.
28 /* Add 3D graphics enums */
29 #include "ppapi/c/pp_graphics_3d.h"
31 /**
32 * @addtogroup Interfaces
33 * @{
35 /**
36 * <code>PPB_Graphics3D</code> defines the interface for a 3D graphics context.
37 * <strong>Example usage from plugin code:</strong>
39 * <strong>Setup:</strong>
40 * @code
41 * PP_Resource context;
42 * int32_t attribs[] = {PP_GRAPHICS3DATTRIB_WIDTH, 800,
43 * PP_GRAPHICS3DATTRIB_HEIGHT, 800,
44 * PP_GRAPHICS3DATTRIB_NONE};
45 * context = g3d->Create(instance, 0, attribs);
46 * inst->BindGraphics(instance, context);
47 * @endcode
49 * <strong>Present one frame:</strong>
50 * @code
51 * PP_CompletionCallback callback = {
52 * DidFinishSwappingBuffers, 0, PP_COMPLETIONCALLBACK_FLAG_NONE,
53 * };
54 * gles2->Clear(context, GL_COLOR_BUFFER_BIT);
55 * g3d->SwapBuffers(context, callback);
56 * @endcode
58 * <strong>Shutdown:</strong>
59 * @code
60 * core->ReleaseResource(context);
61 * @endcode
63 struct PPB_Graphics3D_1_0 {
64 /**
65 * GetAttribMaxValue() retrieves the maximum supported value for the
66 * given attribute. This function may be used to check if a particular
67 * attribute value is supported before attempting to create a context.
69 * @param[in] instance The module instance.
70 * @param[in] attribute The attribute for which maximum value is queried.
71 * Attributes that can be queried for include:
72 * - <code>PP_GRAPHICS3DATTRIB_ALPHA_SIZE</code>
73 * - <code>PP_GRAPHICS3DATTRIB_BLUE_SIZE</code>
74 * - <code>PP_GRAPHICS3DATTRIB_GREEN_SIZE</code>
75 * - <code>PP_GRAPHICS3DATTRIB_RED_SIZE</code>
76 * - <code>PP_GRAPHICS3DATTRIB_DEPTH_SIZE</code>
77 * - <code>PP_GRAPHICS3DATTRIB_STENCIL_SIZE</code>
78 * - <code>PP_GRAPHICS3DATTRIB_SAMPLES</code>
79 * - <code>PP_GRAPHICS3DATTRIB_SAMPLE_BUFFERS</code>
80 * - <code>PP_GRAPHICS3DATTRIB_WIDTH</code>
81 * - <code>PP_GRAPHICS3DATTRIB_HEIGHT</code>
82 * @param[out] value The maximum supported value for <code>attribute</code>
84 * @return Returns <code>PP_TRUE</code> on success or the following on error:
85 * - <code>PP_ERROR_BADRESOURCE</code> if <code>instance</code> is invalid
86 * - <code>PP_ERROR_BADARGUMENT</code> if <code>attribute</code> is invalid
87 * or <code>value</code> is 0
89 int32_t (*GetAttribMaxValue)(PP_Resource instance,
90 int32_t attribute,
91 int32_t* value);
92 /**
93 * Create() creates and initializes a 3D rendering context.
94 * The returned context is off-screen to start with. It must be attached to
95 * a plugin instance using <code>PPB_Instance::BindGraphics</code> to draw
96 * on the web page.
98 * @param[in] instance The module instance.
100 * @param[in] share_context The 3D context with which the created context
101 * would share resources. If <code>share_context</code> is not 0, then all
102 * shareable data, as defined by the client API (note that for OpenGL and
103 * OpenGL ES, shareable data excludes texture objects named 0) will be shared
104 * by <code>share_context<code>, all other contexts <code>share_context</code>
105 * already shares with, and the newly created context. An arbitrary number of
106 * <code>PPB_Graphics3D</code> can share data in this fashion.
108 * @param[in] attrib_list specifies a list of attributes for the context.
109 * It is a list of attribute name-value pairs in which each attribute is
110 * immediately followed by the corresponding desired value. The list is
111 * terminated with <code>PP_GRAPHICS3DATTRIB_NONE</code>.
112 * The <code>attrib_list<code> may be 0 or empty (first attribute is
113 * <code>PP_GRAPHICS3DATTRIB_NONE</code>). If an attribute is not
114 * specified in <code>attrib_list</code>, then the default value is used
115 * (it is said to be specified implicitly).
116 * Attributes for the context are chosen according to an attribute-specific
117 * criteria. Attributes can be classified into two categories:
118 * - AtLeast: The attribute value in the returned context meets or exceeds
119 * the value specified in <code>attrib_list</code>.
120 * - Exact: The attribute value in the returned context is equal to
121 * the value specified in <code>attrib_list</code>.
123 * Attributes that can be specified in <code>attrib_list</code> include:
124 * - <code>PP_GRAPHICS3DATTRIB_ALPHA_SIZE</code>:
125 * Category: AtLeast Default: 0.
126 * - <code>PP_GRAPHICS3DATTRIB_BLUE_SIZE</code>:
127 * Category: AtLeast Default: 0.
128 * - <code>PP_GRAPHICS3DATTRIB_GREEN_SIZE</code>:
129 * Category: AtLeast Default: 0.
130 * - <code>PP_GRAPHICS3DATTRIB_RED_SIZE</code>:
131 * Category: AtLeast Default: 0.
132 * - <code>PP_GRAPHICS3DATTRIB_DEPTH_SIZE</code>:
133 * Category: AtLeast Default: 0.
134 * - <code>PP_GRAPHICS3DATTRIB_STENCIL_SIZE</code>:
135 * Category: AtLeast Default: 0.
136 * - <code>PP_GRAPHICS3DATTRIB_SAMPLES</code>:
137 * Category: AtLeast Default: 0.
138 * - <code>PP_GRAPHICS3DATTRIB_SAMPLE_BUFFERS</code>:
139 * Category: AtLeast Default: 0.
140 * - <code>PP_GRAPHICS3DATTRIB_WIDTH</code>:
141 * Category: Exact Default: 0.
142 * - <code>PP_GRAPHICS3DATTRIB_HEIGHT</code>:
143 * Category: Exact Default: 0.
144 * - <code>PP_GRAPHICS3DATTRIB_SWAP_BEHAVIOR</code>:
145 * Category: Exact Default: Implementation defined.
147 * @return A <code>PP_Resource</code> containing the 3D graphics context if
148 * successful or 0 if unsuccessful.
150 PP_Resource (*Create)(PP_Instance instance,
151 PP_Resource share_context,
152 const int32_t attrib_list[]);
154 * IsGraphics3D() determines if the given resource is a valid
155 * <code>Graphics3D</code> context.
157 * @param[in] resource A <code>Graphics3D</code> context resource.
159 * @return PP_TRUE if the given resource is a valid <code>Graphics3D</code>,
160 * <code>PP_FALSE</code> if it is an invalid resource or is a resource of
161 * another type.
163 PP_Bool (*IsGraphics3D)(PP_Resource resource);
165 * GetAttribs() retrieves the value for each attribute in
166 * <code>attrib_list</code>.
168 * @param[in] context The 3D graphics context.
169 * @param[in,out] attrib_list The list of attributes that are queried.
170 * <code>attrib_list</code> has the same structure as described for
171 * <code>PPB_Graphics3D::Create</code>. It is both input and output
172 * structure for this function. All attributes specified in
173 * <code>PPB_Graphics3D::Create</code> can be queried for.
175 * @return Returns <code>PP_OK</code> on success or:
176 * - <code>PP_ERROR_BADRESOURCE</code> if context is invalid
177 * - <code>PP_ERROR_BADARGUMENT</code> if attrib_list is 0 or any attribute
178 * in the <code>attrib_list</code> is not a valid attribute.
180 * <strong>Example usage:</strong> To get the values for rgb bits in the
181 * color buffer, this function must be called as following:
182 * @code
183 * int attrib_list[] = {PP_GRAPHICS3DATTRIB_RED_SIZE, 0,
184 * PP_GRAPHICS3DATTRIB_GREEN_SIZE, 0,
185 * PP_GRAPHICS3DATTRIB_BLUE_SIZE, 0,
186 * PP_GRAPHICS3DATTRIB_NONE};
187 * GetAttribs(context, attrib_list);
188 * int red_bits = attrib_list[1];
189 * int green_bits = attrib_list[3];
190 * int blue_bits = attrib_list[5];
191 * @endcode
193 int32_t (*GetAttribs)(PP_Resource context, int32_t attrib_list[]);
195 * SetAttribs() sets the values for each attribute in
196 * <code>attrib_list</code>.
198 * @param[in] context The 3D graphics context.
199 * @param[in] attrib_list The list of attributes whose values need to be set.
200 * <code>attrib_list</code> has the same structure as described for
201 * <code>PPB_Graphics3D::Create</code>.
202 * Attributes that can be specified are:
203 * - <code>PP_GRAPHICS3DATTRIB_SWAP_BEHAVIOR</code>
205 * @return Returns <code>PP_OK</code> on success or:
206 * - <code>PP_ERROR_BADRESOURCE</code> if <code>context</code> is invalid.
207 * - <code>PP_ERROR_BADARGUMENT</code> if <code>attrib_list</code> is 0 or
208 * any attribute in the <code>attrib_list</code> is not a valid attribute.
210 int32_t (*SetAttribs)(PP_Resource context, const int32_t attrib_list[]);
212 * GetError() returns the current state of the given 3D context.
214 * The recoverable error conditions that have no side effect are
215 * detected and returned immediately by all functions in this interface.
216 * In addition the implementation may get into a fatal state while
217 * processing a command. In this case the application must destroy the
218 * context and reinitialize client API state and objects to continue
219 * rendering.
221 * Note that the same error code is also returned in the SwapBuffers callback.
222 * It is recommended to handle error in the SwapBuffers callback because
223 * GetError is synchronous. This function may be useful in rare cases where
224 * drawing a frame is expensive and you want to verify the result of
225 * ResizeBuffers before attempting to draw a frame.
227 * @param[in] The 3D graphics context.
228 * @return Returns:
229 * - <code>PP_OK</code> if no error
230 * - <code>PP_ERROR_NOMEMORY</code>
231 * - <code>PP_ERROR_CONTEXT_LOST</code>
233 int32_t (*GetError)(PP_Resource context);
235 * ResizeBuffers() resizes the backing surface for context.
237 * If the surface could not be resized due to insufficient resources,
238 * <code>PP_ERROR_NOMEMORY</code> error is returned on the next
239 * <code>SwapBuffers</code> callback.
241 * @param[in] context The 3D graphics context.
242 * @param[in] width The width of the backing surface.
243 * @param[in] height The height of the backing surface.
244 * @return Returns <code>PP_OK</code> on success or:
245 * - <code>PP_ERROR_BADRESOURCE</code> if context is invalid.
246 * - <code>PP_ERROR_BADARGUMENT</code> if the value specified for
247 * <code>width</code> or <code>height</code> is less than zero.
249 int32_t (*ResizeBuffers)(PP_Resource context, int32_t width, int32_t height);
251 * SwapBuffers() makes the contents of the color buffer available for
252 * compositing. This function has no effect on off-screen surfaces - ones not
253 * bound to any plugin instance. The contents of ancillary buffers are always
254 * undefined after calling <code>SwapBuffers</code>. The contents of the color
255 * buffer are undefined if the value of the
256 * <code>PP_GRAPHICS3DATTRIB_SWAP_BEHAVIOR</code> attribute of context is not
257 * <code>PP_GRAPHICS3DATTRIB_BUFFER_PRESERVED</code>.
259 * <code>SwapBuffers</code> runs in asynchronous mode. Specify a callback
260 * function and the argument for that callback function. The callback function
261 * will be executed on the calling thread after the color buffer has been
262 * composited with rest of the html page. While you are waiting for a
263 * SwapBuffers callback, additional calls to SwapBuffers will fail.
265 * Because the callback is executed (or thread unblocked) only when the
266 * plugin's current state is actually on the screen, this function provides a
267 * way to rate limit animations. By waiting until the image is on the screen
268 * before painting the next frame, you can ensure you're not generating
269 * updates faster than the screen can be updated.
271 * SwapBuffers performs an implicit flush operation on context.
272 * If the context gets into an unrecoverable error condition while
273 * processing a command, the error code will be returned as the argument
274 * for the callback. The callback may return the following error codes:
275 * - <code>PP_ERROR_NOMEMORY</code>
276 * - <code>PP_ERROR_CONTEXT_LOST</code>
277 * Note that the same error code may also be obtained by calling GetError.
279 * @param[in] context The 3D graphics context.
280 * @param[in] callback The callback that will executed when
281 * <code>SwapBuffers</code> completes.
283 * @return Returns PP_OK on success or:
284 * - <code>PP_ERROR_BADRESOURCE</code> if context is invalid.
285 * - <code>PP_ERROR_BADARGUMENT</code> if callback is invalid.
288 int32_t (*SwapBuffers)(PP_Resource context,
289 struct PP_CompletionCallback callback);
292 typedef struct PPB_Graphics3D_1_0 PPB_Graphics3D;
294 * @}
297 #endif /* PPAPI_C_PPB_GRAPHICS_3D_H_ */