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