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_graphics_3d.idl modified Fri Aug 30 08:36:16 2013. */ 7 8 #ifndef PPAPI_C_PPB_GRAPHICS_3D_H_ 9 #define PPAPI_C_PPB_GRAPHICS_3D_H_ 10 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" 17 18 #define PPB_GRAPHICS_3D_INTERFACE_1_0 "PPB_Graphics3D;1.0" 19 #define PPB_GRAPHICS_3D_INTERFACE PPB_GRAPHICS_3D_INTERFACE_1_0 20 21 /** 22 * @file 23 * Defines the <code>PPB_Graphics3D</code> struct representing a 3D graphics 24 * context within the browser. 25 */ 26 27 28 /* Add 3D graphics enums */ 29 #include "ppapi/c/pp_graphics_3d.h" 30 31 /** 32 * @addtogroup Interfaces 33 * @{ 34 */ 35 /** 36 * <code>PPB_Graphics3D</code> defines the interface for a 3D graphics context. 37 * <strong>Example usage from plugin code:</strong> 38 * 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 48 * 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 57 * 58 * <strong>Shutdown:</strong> 59 * @code 60 * core->ReleaseResource(context); 61 * @endcode 62 */ 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. 68 * 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> 83 * 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 88 */ 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. 97 * 98 * @param[in] instance The module instance. 99 * 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. 107 * 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>. 122 * 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. 146 * 147 * @return A <code>PP_Resource</code> containing the 3D graphics context if 148 * successful or 0 if unsuccessful. 149 */ 150 PP_Resource (*Create)(PP_Instance instance, 151 PP_Resource share_context, 152 const int32_t attrib_list[]); 153 /** 154 * IsGraphics3D() determines if the given resource is a valid 155 * <code>Graphics3D</code> context. 156 * 157 * @param[in] resource A <code>Graphics3D</code> context resource. 158 * 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. 162 */ 163 PP_Bool (*IsGraphics3D)(PP_Resource resource); 164 /** 165 * GetAttribs() retrieves the value for each attribute in 166 * <code>attrib_list</code>. 167 * 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. 174 * 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. 179 * 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 192 */ 193 int32_t (*GetAttribs)(PP_Resource context, int32_t attrib_list[]); 194 /** 195 * SetAttribs() sets the values for each attribute in 196 * <code>attrib_list</code>. 197 * 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> 204 * 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. 209 */ 210 int32_t (*SetAttribs)(PP_Resource context, const int32_t attrib_list[]); 211 /** 212 * GetError() returns the current state of the given 3D context. 213 * 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. 220 * 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. 226 * 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> 232 */ 233 int32_t (*GetError)(PP_Resource context); 234 /** 235 * ResizeBuffers() resizes the backing surface for context. 236 * 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. 240 * 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. 248 */ 249 int32_t (*ResizeBuffers)(PP_Resource context, int32_t width, int32_t height); 250 /** 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>. 258 * 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. 264 * 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. 270 * 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. 278 * 279 * @param[in] context The 3D graphics context. 280 * @param[in] callback The callback that will executed when 281 * <code>SwapBuffers</code> completes. 282 * 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. 286 * 287 */ 288 int32_t (*SwapBuffers)(PP_Resource context, 289 struct PP_CompletionCallback callback); 290 }; 291 292 typedef struct PPB_Graphics3D_1_0 PPB_Graphics3D; 293 /** 294 * @} 295 */ 296 297 #endif /* PPAPI_C_PPB_GRAPHICS_3D_H_ */ 298 299