ppapi/c/ppb_graphics_3d.h

   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