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