ppapi/api/ppb_graphics_3d.idl

   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