Pepper 3D API changes:

ppapi/c/dev/ppb_graphics_3d_dev.h

Index: ppapi/c/dev/ppb_graphics_3d_dev.h
===================================================================
--- ppapi/c/dev/ppb_graphics_3d_dev.h	(revision 99369)
+++ ppapi/c/dev/ppb_graphics_3d_dev.h	(working copy)
@@ -28,10 +28,32 @@
 // // 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
+#define PPB_GRAPHICS_3D_DEV_INTERFACE_0_9 "PPB_Graphics3D(Dev);0.9"
+#define PPB_GRAPHICS_3D_DEV_INTERFACE PPB_GRAPHICS_3D_DEV_INTERFACE_0_9
 
 struct PPB_Graphics3D_Dev {
+  // Retrieves the maximum supported value for the given attribute.
+  //
+  // This function may be used to check if a particular attribute value is
+  // supported before attempting to create a context.
+  // Attributes that can be queried for 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 attribute is invalid or value is NULL
+  int32_t (*GetAttribMaxValue)(PP_Resource instance,
+                               int32_t attribute, int32_t* value);
+
   // 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.
@@ -81,15 +103,15 @@
   // 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:
@@ -108,8 +130,26 @@
   //
   // Attributes that can be specified are:
   // - 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

[brettw, 2011/09/02 20:21:45]

It's not clear to me when I'm supposed to call this function.

[alokp, 2011/09/02 21:41:02]

The context may get lost anytime. It may go out of memory when attempting to
resize the backing surface. An application may call this function after resize.
Although not recommended, but an application may even call it at the beginning
of a frame to make sure it can be rendered to.

If your question is "why is it part of the API when the error code is already
returned by SwapBuffers?", then please see the discussion here -
http://codereview.chromium.org/7530010. Antoine wanted to support one particular
use case - "In the case that it's CPU-costly to draw a frame, the user may want
to check for the result of resize before starting a draw cycle, paying for the
round trip".

I think that most applications will not call this function ever. They will just
check the error code in SwapBuffers callback.

[brettw, 2011/09/02 22:14:24]

Then I'd like to add to the comment that this returns the same error code
provided by the SwapBuffers callback. If this function can return some data
before the callback occurs, can we mention this?

My problem is that as somebody thinking about using this API, it's not clear if
I should be calling this function, and when I should be calling it. I might be
tempted to call it all the time to make sure there's no error, which would be
incorrect. We at least need to have enough info here so that the people who
don't need this function know they don't need it.

[alokp, 2011/09/02 23:45:07]

I already have this in the comment - "Note that the same error code is also
returned in the swap buffers callback". Is that what you were looking for?
 
I agree it is confusing and could lead to many applications calling a
synchronous function unnecessarily. I have tried to make it clearer by adding
more documentation to GetError and SwapBuffers, but still think we should remove
this from V1. SwapBuffers callback covers most use cases.

+  // buffers callback.
+  //
+  // The following error codes may be returned:
+  // - PP_ERROR_NOMEMORY
+  // - PP_ERROR_CONTEXT_LOST
+  int32_t (*GetError)(PP_Resource context);
+
   // Resizes the backing surface for context.
   //
   // On failure the following error codes may be returned:
@@ -129,24 +169,26 @@
   // 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.
+  // 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 SwapBuffers callback,
+  // additional calls to SwapBuffers will fail.
   //
-  // 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.
-  //
   // 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);
 };