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 * Defines the <code>PPB_Graphics3D</code> struct representing a 3D graphics 8 * context within the browser. 9 */ 10 11 [generate_thunk] 12 13 label Chrome { 14 M15 = 1.0 15 }; 16 17 #inline c 18 /* Add 3D graphics enums */ 19 #include "ppapi/c/pp_graphics_3d.h" 20 #endinl 21 22 /** 23 * <code>PPB_Graphics3D</code> defines the interface for a 3D graphics context. 24 * <strong>Example usage from plugin code:</strong> 25 * 26 * <strong>Setup:</strong> 27 * @code 28 * PP_Resource context; 29 * int32_t attribs[] = {PP_GRAPHICS3DATTRIB_WIDTH, 800, 30 * PP_GRAPHICS3DATTRIB_HEIGHT, 800, 31 * PP_GRAPHICS3DATTRIB_NONE}; 32 * context = g3d->Create(instance, 0, attribs); 33 * inst->BindGraphics(instance, context); 34 * @endcode 35 * 36 * <strong>Present one frame:</strong> 37 * @code 38 * PP_CompletionCallback callback = { 39 * DidFinishSwappingBuffers, 0, PP_COMPLETIONCALLBACK_FLAG_NONE, 40 * }; 41 * gles2->Clear(context, GL_COLOR_BUFFER_BIT); 42 * g3d->SwapBuffers(context, callback); 43 * @endcode 44 * 45 * <strong>Shutdown:</strong> 46 * @code 47 * core->ReleaseResource(context); 48 * @endcode 49 */ 50 [macro="PPB_GRAPHICS_3D_INTERFACE"] 51 interface PPB_Graphics3D { 52 /** 53 * GetAttribMaxValue() retrieves the maximum supported value for the 54 * given attribute. This function may be used to check if a particular 55 * attribute value is supported before attempting to create a context. 56 * 57 * @param[in] instance The module instance. 58 * @param[in] attribute The attribute for which maximum value is queried. 59 * Attributes that can be queried for include: 60 * - <code>PP_GRAPHICS3DATTRIB_ALPHA_SIZE</code> 61 * - <code>PP_GRAPHICS3DATTRIB_BLUE_SIZE</code> 62 * - <code>PP_GRAPHICS3DATTRIB_GREEN_SIZE</code> 63 * - <code>PP_GRAPHICS3DATTRIB_RED_SIZE</code> 64 * - <code>PP_GRAPHICS3DATTRIB_DEPTH_SIZE</code> 65 * - <code>PP_GRAPHICS3DATTRIB_STENCIL_SIZE</code> 66 * - <code>PP_GRAPHICS3DATTRIB_SAMPLES</code> 67 * - <code>PP_GRAPHICS3DATTRIB_SAMPLE_BUFFERS</code> 68 * - <code>PP_GRAPHICS3DATTRIB_WIDTH</code> 69 * - <code>PP_GRAPHICS3DATTRIB_HEIGHT</code> 70 * @param[out] value The maximum supported value for <code>attribute</code> 71 * 72 * @return Returns <code>PP_TRUE</code> on success or the following on error: 73 * - <code>PP_ERROR_BADRESOURCE</code> if <code>instance</code> is invalid 74 * - <code>PP_ERROR_BADARGUMENT</code> if <code>attribute</code> is invalid 75 * or <code>value</code> is 0 76 */ 77 int32_t GetAttribMaxValue( 78 [in] PP_Resource instance, 79 [in] int32_t attribute, 80 [out] int32_t value); 81 82 /** 83 * Create() creates and initializes a 3D rendering context. 84 * The returned context is off-screen to start with. It must be attached to 85 * a plugin instance using <code>PPB_Instance::BindGraphics</code> to draw 86 * on the web page. 87 * 88 * @param[in] instance The module instance. 89 * 90 * @param[in] share_context The 3D context with which the created context 91 * would share resources. If <code>share_context</code> is not 0, then all 92 * shareable data, as defined by the client API (note that for OpenGL and 93 * OpenGL ES, shareable data excludes texture objects named 0) will be shared 94 * by <code>share_context<code>, all other contexts <code>share_context</code> 95 * already shares with, and the newly created context. An arbitrary number of 96 * <code>PPB_Graphics3D</code> can share data in this fashion. 97 * 98 * @param[in] attrib_list specifies a list of attributes for the context. 99 * It is a list of attribute name-value pairs in which each attribute is 100 * immediately followed by the corresponding desired value. The list is 101 * terminated with <code>PP_GRAPHICS3DATTRIB_NONE</code>. 102 * The <code>attrib_list<code> may be 0 or empty (first attribute is 103 * <code>PP_GRAPHICS3DATTRIB_NONE</code>). If an attribute is not 104 * specified in <code>attrib_list</code>, then the default value is used 105 * (it is said to be specified implicitly). 106 * Attributes for the context are chosen according to an attribute-specific 107 * criteria. Attributes can be classified into two categories: 108 * - AtLeast: The attribute value in the returned context meets or exceeds 109 * the value specified in <code>attrib_list</code>. 110 * - Exact: The attribute value in the returned context is equal to 111 * the value specified in <code>attrib_list</code>. 112 * 113 * Attributes that can be specified in <code>attrib_list</code> include: 114 * - <code>PP_GRAPHICS3DATTRIB_ALPHA_SIZE</code>: 115 * Category: AtLeast Default: 0. 116 * - <code>PP_GRAPHICS3DATTRIB_BLUE_SIZE</code>: 117 * Category: AtLeast Default: 0. 118 * - <code>PP_GRAPHICS3DATTRIB_GREEN_SIZE</code>: 119 * Category: AtLeast Default: 0. 120 * - <code>PP_GRAPHICS3DATTRIB_RED_SIZE</code>: 121 * Category: AtLeast Default: 0. 122 * - <code>PP_GRAPHICS3DATTRIB_DEPTH_SIZE</code>: 123 * Category: AtLeast Default: 0. 124 * - <code>PP_GRAPHICS3DATTRIB_STENCIL_SIZE</code>: 125 * Category: AtLeast Default: 0. 126 * - <code>PP_GRAPHICS3DATTRIB_SAMPLES</code>: 127 * Category: AtLeast Default: 0. 128 * - <code>PP_GRAPHICS3DATTRIB_SAMPLE_BUFFERS</code>: 129 * Category: AtLeast Default: 0. 130 * - <code>PP_GRAPHICS3DATTRIB_WIDTH</code>: 131 * Category: Exact Default: 0. 132 * - <code>PP_GRAPHICS3DATTRIB_HEIGHT</code>: 133 * Category: Exact Default: 0. 134 * - <code>PP_GRAPHICS3DATTRIB_SWAP_BEHAVIOR</code>: 135 * Category: Exact Default: Implementation defined. 136 * 137 * @return A <code>PP_Resource</code> containing the 3D graphics context if 138 * successful or 0 if unsuccessful. 139 */ 140 PP_Resource Create( 141 [in] PP_Instance instance, 142 [in] PP_Resource share_context, 143 [in] int32_t[] attrib_list); 144 145 /** 146 * IsGraphics3D() determines if the given resource is a valid 147 * <code>Graphics3D</code> context. 148 * 149 * @param[in] resource A <code>Graphics3D</code> context resource. 150 * 151 * @return PP_TRUE if the given resource is a valid <code>Graphics3D</code>, 152 * <code>PP_FALSE</code> if it is an invalid resource or is a resource of 153 * another type. 154 */ 155 PP_Bool IsGraphics3D( 156 [in] PP_Resource resource); 157 158 /** 159 * GetAttribs() retrieves the value for each attribute in 160 * <code>attrib_list</code>. 161 * 162 * @param[in] context The 3D graphics context. 163 * @param[in,out] attrib_list The list of attributes that are queried. 164 * <code>attrib_list</code> has the same structure as described for 165 * <code>PPB_Graphics3D::Create</code>. It is both input and output 166 * structure for this function. All attributes specified in 167 * <code>PPB_Graphics3D::Create</code> can be queried for. 168 * 169 * @return Returns <code>PP_OK</code> on success or: 170 * - <code>PP_ERROR_BADRESOURCE</code> if context is invalid 171 * - <code>PP_ERROR_BADARGUMENT</code> if attrib_list is 0 or any attribute 172 * in the <code>attrib_list</code> is not a valid attribute. 173 * 174 * <strong>Example usage:</strong> To get the values for rgb bits in the 175 * color buffer, this function must be called as following: 176 * @code 177 * int attrib_list[] = {PP_GRAPHICS3DATTRIB_RED_SIZE, 0, 178 * PP_GRAPHICS3DATTRIB_GREEN_SIZE, 0, 179 * PP_GRAPHICS3DATTRIB_BLUE_SIZE, 0, 180 * PP_GRAPHICS3DATTRIB_NONE}; 181 * GetAttribs(context, attrib_list); 182 * int red_bits = attrib_list[1]; 183 * int green_bits = attrib_list[3]; 184 * int blue_bits = attrib_list[5]; 185 * @endcode 186 */ 187 int32_t GetAttribs( 188 [in] PP_Resource context, 189 [inout] int32_t[] attrib_list); 190 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( 208 [in] PP_Resource context, 209 [in] int32_t[] attrib_list); 210 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( 234 [in] PP_Resource context); 235 236 /** 237 * ResizeBuffers() resizes the backing surface for context. 238 * 239 * If the surface could not be resized due to insufficient resources, 240 * <code>PP_ERROR_NOMEMORY</code> error is returned on the next 241 * <code>SwapBuffers</code> callback. 242 * 243 * @param[in] context The 3D graphics context. 244 * @param[in] width The width of the backing surface. 245 * @param[in] height The height of the backing surface. 246 * @return Returns <code>PP_OK</code> on success or: 247 * - <code>PP_ERROR_BADRESOURCE</code> if context is invalid. 248 * - <code>PP_ERROR_BADARGUMENT</code> if the value specified for 249 * <code>width</code> or <code>height</code> is less than zero. 250 */ 251 int32_t ResizeBuffers( 252 [in] PP_Resource context, 253 [in] int32_t width, 254 [in] int32_t height); 255 256 /** 257 * SwapBuffers() makes the contents of the color buffer available for 258 * compositing. This function has no effect on off-screen surfaces - ones not 259 * bound to any plugin instance. The contents of ancillary buffers are always 260 * undefined after calling <code>SwapBuffers</code>. The contents of the color 261 * buffer are undefined if the value of the 262 * <code>PP_GRAPHICS3DATTRIB_SWAP_BEHAVIOR</code> attribute of context is not 263 * <code>PP_GRAPHICS3DATTRIB_BUFFER_PRESERVED</code>. 264 * 265 * <code>SwapBuffers</code> runs in asynchronous mode. Specify a callback 266 * function and the argument for that callback function. The callback function 267 * will be executed on the calling thread after the color buffer has been 268 * composited with rest of the html page. While you are waiting for a 269 * SwapBuffers callback, additional calls to SwapBuffers will fail. 270 * 271 * Because the callback is executed (or thread unblocked) only when the 272 * plugin's current state is actually on the screen, this function provides a 273 * way to rate limit animations. By waiting until the image is on the screen 274 * before painting the next frame, you can ensure you're not generating 275 * updates faster than the screen can be updated. 276 * 277 * SwapBuffers performs an implicit flush operation on context. 278 * If the context gets into an unrecoverable error condition while 279 * processing a command, the error code will be returned as the argument 280 * for the callback. The callback may return the following error codes: 281 * - <code>PP_ERROR_NOMEMORY</code> 282 * - <code>PP_ERROR_CONTEXT_LOST</code> 283 * Note that the same error code may also be obtained by calling GetError. 284 * 285 * @param[in] context The 3D graphics context. 286 * @param[in] callback The callback that will executed when 287 * <code>SwapBuffers</code> completes. 288 * 289 * @return Returns PP_OK on success or: 290 * - <code>PP_ERROR_BADRESOURCE</code> if context is invalid. 291 * - <code>PP_ERROR_BADARGUMENT</code> if callback is invalid. 292 * 293 */ 294 int32_t SwapBuffers( 295 [in] PP_Resource context, 296 [in] PP_CompletionCallback callback); 297 }; 298 299
