Proposed changes for Pepper 3D API.

ppapi/c/dev/ppb_graphics_3d_dev.h

 /* Copyright (c) 2011 The Chromium Authors. All rights reserved.
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
 #ifndef PPAPI_C_DEV_PPB_GRAPHICS_3D_DEV_H_
 #define PPAPI_C_DEV_PPB_GRAPHICS_3D_DEV_H_
 
 #include "ppapi/c/dev/pp_graphics_3d_dev.h"
 
 #include "ppapi/c/pp_bool.h"
@@ skipping 14 matching lines @@
 // gles2->Clear(context, GL_COLOR_BUFFER);
 // g3d->SwapBuffers(context);
 //
 // // Shutdown.
 // core->ReleaseResource(context);
 
 #define PPB_GRAPHICS_3D_DEV_INTERFACE_0_8 "PPB_Graphics3D(Dev);0.8"
 #define PPB_GRAPHICS_3D_DEV_INTERFACE PPB_GRAPHICS_3D_DEV_INTERFACE_0_8
 
 struct PPB_Graphics3D_Dev {
+  // Retrieves the maximum supported value for each attribute in attrib_list.
+  // The list has the same structure as described for
+  // PPB_Graphics3D_Dev::GetAttribs.
+  //
+  // This function may be used before attempting to create a context to check
+  // if a particular attribute value is supported.
+  // Attributes that can be specified in attrib_list include:
+  // - PP_GRAPHICS3DATTRIB_ALPHA_SIZE
+  // - PP_GRAPHICS3DATTRIB_BLUE_SIZE
+  // - PP_GRAPHICS3DATTRIB_GREEN_SIZE
+  // - PP_GRAPHICS3DATTRIB_RED_SIZE
+  // - PP_GRAPHICS3DATTRIB_DEPTH_SIZE
+  // - PP_GRAPHICS3DATTRIB_STENCIL_SIZE
+  // - PP_GRAPHICS3DATTRIB_SAMPLES
+  // - PP_GRAPHICS3DATTRIB_SAMPLE_BUFFERS
+  // - PP_GRAPHICS3DATTRIB_WIDTH
+  // - PP_GRAPHICS3DATTRIB_HEIGHT
+  //
+  // On failure the following error codes may be returned:
+  // - PP_ERROR_BADRESOURCE if instance is invalid.
+  // - PP_ERROR_BADARGUMENT if attrib_list is NULL or any attribute in the
+  //   attrib_list is not a valid attribute
+  int32_t (*GetAttribsMaxValue)(PP_Resource instance, int32_t* attrib_list);
+
   // Creates and initializes a rendering context and returns a handle to it.
   // The returned context is off-screen to start with. It must be attached to
   // a plugin instance using PPB_Instance::BindGraphics to draw on the web page.
   //
   // If share_context is not NULL, then all shareable data, as defined
   // by the client API (note that for OpenGL and OpenGL ES, shareable data
   // excludes texture objects named 0) will be shared by share_context, all
   // other contexts share_context already shares with, and the newly created
   // context. An arbitrary number of PPB_Graphics3D_Dev can share data in
   // this fashion.
@@ skipping 15 matching lines @@
   //
   // Attributes that can be specified in attrib_list include:
   // - PP_GRAPHICS3DATTRIB_ALPHA_SIZE: Category: AtLeast Default: 0.
   // - PP_GRAPHICS3DATTRIB_BLUE_SIZE: Category: AtLeast Default: 0.
   // - PP_GRAPHICS3DATTRIB_GREEN_SIZE: Category: AtLeast Default: 0.
   // - PP_GRAPHICS3DATTRIB_RED_SIZE: Category: AtLeast Default: 0.
   // - PP_GRAPHICS3DATTRIB_DEPTH_SIZE: Category: AtLeast Default: 0.
   // - PP_GRAPHICS3DATTRIB_STENCIL_SIZE: Category: AtLeast Default: 0.
   // - PP_GRAPHICS3DATTRIB_SAMPLES: Category: AtLeast Default: 0.
   // - PP_GRAPHICS3DATTRIB_SAMPLE_BUFFERS: Category: AtLeast Default: 0.
+  // - PP_GRAPHICS3DATTRIB_BIND_RGB: Category: Exact Default: PP_FALSE.
   // - PP_GRAPHICS3DATTRIB_WIDTH: Category: Exact Default: 0.
   // - PP_GRAPHICS3DATTRIB_HEIGHT: Category: Exact Default: 0.
   // - PP_GRAPHICS3DATTRIB_SWAP_BEHAVIOR:
   //   Category: Exact Default: Implementation defined.
   //
   // On failure NULL resource is returned.
   PP_Resource (*Create)(PP_Instance instance,
                         PP_Resource share_context,
                         const int32_t* attrib_list);
 
   // Returns PP_TRUE if the given resource is a valid PPB_Graphics3D_Dev,
   // PP_FALSE if it is an invalid resource or is a resource of another type.
   PP_Bool (*IsGraphics3D)(PP_Resource resource);
 
-  // Retrieves the values for each attribute in attrib_list. The list
+  // Retrieves the value for each attribute in attrib_list. The list
   // has the same structure as described for PPB_Graphics3D_Dev::Create.
   // It is both input and output structure for this function.
   //
   // All attributes specified in PPB_Graphics3D_Dev::Create can be queried for.
   // On failure the following error codes may be returned:
   // - PP_ERROR_BADRESOURCE if context is invalid.
-  // - PP_GRAPHICS3DERROR_BAD_ATTRIBUTE if any attribute in the attrib_list
-  //   is not a valid attribute
+  // - PP_ERROR_BADARGUMENT if attrib_list is NULL or any attribute in the
+  //   attrib_list is not a valid attribute.
   //
   // Example usage: To get the values for rgb bits in the color buffer,
   // this function must be called as following:
   // int attrib_list[] = {PP_GRAPHICS3DATTRIB_RED_SIZE, 0,
   //                      PP_GRAPHICS3DATTRIB_GREEN_SIZE, 0,
   //                      PP_GRAPHICS3DATTRIB_BLUE_SIZE, 0,
   //                      PP_GRAPHICS3DATTRIB_NONE};
   // GetAttribs(context, attrib_list);
   // int red_bits = attrib_list[1];
   // int green_bits = attrib_list[3];
   // int blue_bits = attrib_list[5];
   int32_t (*GetAttribs)(PP_Resource context, int32_t* attrib_list);
 
   // Sets the values for each attribute in attrib_list. The list
   // has the same structure as described for PPB_Graphics3D_Dev::Create.
   //
   // Attributes that can be specified are:
+  // - PP_GRAPHICS3DATTRIB_BIND_RGB
   // - PP_GRAPHICS3DATTRIB_SWAP_BEHAVIOR
+  //
+  // On failure the following error codes may be returned:
+  // - PP_ERROR_BADRESOURCE if context is invalid.
+  // - PP_ERROR_BADARGUMENT if attrib_list is NULL or any attribute in the
+  //   attrib_list is not a valid attribute.
   int32_t (*SetAttribs)(PP_Resource context, int32_t* attrib_list);
 
+  // The recoverable error conditions that have no side effect are
+  // detected and returned immediately by all functions in this interface.
+  // In addition the implementation may get into a fatal state while
+  // processing a command. In this case the application must detroy the
+  // context and reinitialize client API state and objects to continue
+  // rendering. Note that the same error code is also returned in the swap
+  // buffers callback.
+  // 
+  // The following error codes may be returned:
+  // - PP_ERROR_NOMEMORY
+  // - PP_GRAPHICS3DERROR_CONTEXT_LOST

[brettw, 2011/08/25 19:25:31]

I'm OK just calling this PP_ERROR_CONTEXT_LOST. We've had some discussions about
wanting the 2D graphics backing store to be able to be thrown away, so could
re-use this error there as well.

[alokp, 2011/09/01 20:22:36]

Done.

+  int32_t (*GetError)(PP_Resource context);
+
   // Resizes the backing surface for context.
   //
   // On failure the following error codes may be returned:
   // - PP_ERROR_BADRESOURCE if context is invalid.
   // - PP_ERROR_BADARGUMENT if the value specified for width or height
   //   is less than zero.
   //
   // If the surface could not be resized due to insufficient resources,
   // PP_ERROR_NOMEMORY error is returned on the next SwapBuffers callback.
   int32_t (*ResizeBuffers)(PP_Resource context,
                            int32_t width, int32_t height);
 
   // Makes the contents of the color buffer available for compositing.
   // This function has no effect on off-screen surfaces - ones not bound
   // to any plugin instance. The contents of ancillary buffers are always
   // undefined after calling SwapBuffers. The contents of the color buffer are
   // undefined if the value of the PP_GRAPHICS3DATTRIB_SWAP_BEHAVIOR attribute
   // of context is not PP_GRAPHICS3DATTRIB_BUFFER_PRESERVED.
   //
-  // SwapBuffers performs an implicit flush operation on context.
-  //
-  // This functions can run in two modes:
-  // - In synchronous mode, you specify NULL for the callback and the callback
-  //   data. This function will block the calling thread until the image has
-  //   been painted to the screen. It is not legal to block the main thread of
-  //   the plugin, you can use synchronous mode only from background threads.
-  // - In asynchronous mode, you specify a callback function and the argument
-  //   for that callback function. The callback function will be executed on
-  //   the calling thread when the image has been painted to the screen. While
-  //   you are waiting for a Flush callback, additional calls to Flush will
-  //   fail.
+  // SwapBuffers runs in asynchronous mode. Specify a callback function and the
+  // argument for that callback function. The callback function will be executed
+  // on the calling thread after the color buffer has been composited with
+  // rest of the html page. While you are waiting for a Flush callback,
+  // additional calls to Flush will fail.
   //
   // Because the callback is executed (or thread unblocked) only when the
   // plugin's current state is actually on the screen, this function provides a
   // way to rate limit animations. By waiting until the image is on the screen
   // before painting the next frame, you can ensure you're not generating
   // updates faster than the screen can be updated.
+  //
+  // SwapBuffers performs an implicit flush operation on context.
+  // If the context gets into an unrecoverable error condition while
+  // processing a command, the error code will be returned as the argument
+  // for the callback.
+  //
+  // On failure the following error codes may be returned:
+  // - PP_ERROR_BADRESOURCE if context is invalid.
+  // - PP_ERROR_BADARGUMENT if callback is invalid.
   int32_t (*SwapBuffers)(PP_Resource context,
                          struct PP_CompletionCallback callback);
 };
 
 #endif  /* PPAPI_C_DEV_PPB_GRAPHICS_3D_DEV_H_ */