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