Pepper 3D API changes:

1. Added GetAttribMaxValue() and GetError()
2. Fixed the documentation for SwapBuffers()
3. Replaced PP_GRAPHICS3DERROR_CONTEXT_LOST with PP_ERROR_CONTEXT_LOST

Review URL: http://codereview.chromium.org/7824040

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@99532 0039d316-1c4b-4281-b951-d872f2087c98

8 files changed, 111 insertions, 25 deletions

diff --git a/ppapi/c/dev/pp_graphics_3d_dev.h b/ppapi/c/dev/pp_graphics_3d_dev.h
index 34544ee..300f110 100644
--- a/ppapi/c/dev/pp_graphics_3d_dev.h
+++ b/ppapi/c/dev/pp_graphics_3d_dev.h
@@ -8,11 +8,6 @@
 
 #include "ppapi/c/pp_stdint.h"
 
-enum PP_Graphics3DError_Dev {
-  PP_GRAPHICS3DERROR_BAD_ATTRIBUTE = 0x3004,
-  PP_GRAPHICS3DERROR_CONTEXT_LOST = 0x300E
-};
-
 enum PP_Graphics3DAttrib_Dev {
   // Bits of Alpha in the color buffer.
   PP_GRAPHICS3DATTRIB_ALPHA_SIZE = 0x3021,
@@ -32,8 +27,6 @@ enum PP_Graphics3DAttrib_Dev {
   PP_GRAPHICS3DATTRIB_SAMPLE_BUFFERS = 0x3032,
   // Attrib list terminator.
   PP_GRAPHICS3DATTRIB_NONE = 0x3038,
-
-  // Surface-specific attributes.
   // Height of surface in pixels.
   PP_GRAPHICS3DATTRIB_HEIGHT = 0x3056,
   // Width of surface in pixels.
diff --git a/ppapi/c/dev/ppb_graphics_3d_dev.h b/ppapi/c/dev/ppb_graphics_3d_dev.h
index aa93c1a..28c759c 100644
--- a/ppapi/c/dev/ppb_graphics_3d_dev.h
+++ b/ppapi/c/dev/ppb_graphics_3d_dev.h
@@ -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 @@ struct 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:
@@ -108,8 +130,31 @@ struct PPB_Graphics3D_Dev {
   //
   // 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 SwapBuffers callback.
+  // It is recommended to handle error in the SwapBuffers callback because
+  // GetError is synchronous. This function may be useful in rare cases where
+  // drawing a frame is expensive and you want to verify the result of
+  // ResizeBuffers before attemptimg to draw a frame.
+  //
+  // 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 +174,29 @@ struct PPB_Graphics3D_Dev {
   // 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 SwapBuffers callback,
+  // additional calls to SwapBuffers 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. The callback may return the following error codes:
+  // - PP_ERROR_NOMEMORY
+  // - PP_ERROR_CONTEXT_LOST
+  // Note that the same error code may also be obtained by calling GetError.
+  //
+  // On failure SwapBuffers may return the following error codes:
+  // - PP_ERROR_BADRESOURCE if context is invalid.
+  // - PP_ERROR_BADARGUMENT if callback is invalid.
   int32_t (*SwapBuffers)(PP_Resource context,
                          struct PP_CompletionCallback callback);
 };
diff --git a/ppapi/c/pp_errors.h b/ppapi/c/pp_errors.h
index 13ed316..1394aa7 100644
--- a/ppapi/c/pp_errors.h
+++ b/ppapi/c/pp_errors.h
@@ -85,7 +85,12 @@ enum {
    * This value indicates that the user cancelled rather than providing
    * expected input.
    */
-  PP_ERROR_USERCANCEL = -40
+  PP_ERROR_USERCANCEL = -40,
+  /**
+   * This value indicates that the graphics context was lost due to a
+   * power management event.
+   */
+  PP_ERROR_CONTEXT_LOST = -50
 };
 /**
  * @}
diff --git a/ppapi/native_client/src/shared/ppapi_proxy/plugin_ppb_graphics_3d.cc b/ppapi/native_client/src/shared/ppapi_proxy/plugin_ppb_graphics_3d.cc
index 3d7f0ab..d6b15d9 100644
--- a/ppapi/native_client/src/shared/ppapi_proxy/plugin_ppb_graphics_3d.cc
+++ b/ppapi/native_client/src/shared/ppapi_proxy/plugin_ppb_graphics_3d.cc
@@ -41,6 +41,13 @@ int32_t GetNumAttribs(const int32_t* attrib_list) {
   return num;
 }
 
+int32_t GetAttribMaxValue(PP_Resource instance,
+                          int32_t attribute,
+                          int32_t* value) {
+  // TODO(nfullagar): Implement me.
+  return PP_ERROR_FAILED;
+}
+
 PP_Resource Create(PP_Instance instance,
                    PP_Resource share_context,
                    const int32_t* attrib_list) {
@@ -105,6 +112,11 @@ int32_t SetAttribs(PP_Resource graphics3d_id,
   return pp_error;
 }
 
+int32_t GetError(PP_Resource graphics_3d) {
+  // TODO(nfullagar): Implement me.
+  return PP_ERROR_FAILED;
+}
+
 int32_t ResizeBuffers(PP_Resource graphics3d_id,
                       int32_t width,
                       int32_t height) {
@@ -225,10 +237,12 @@ int32_t PluginGraphics3D::SwapBuffers(PP_Resource graphics3d_id,
 // static
 const PPB_Graphics3D_Dev* PluginGraphics3D::GetInterface() {
   static const PPB_Graphics3D_Dev intf = {
+    &GetAttribMaxValue,
     &Create,
     &IsGraphics3D,
     &GetAttribs,
     &SetAttribs,
+    &GetError,
     &ResizeBuffers,
     &SwapBuffs,
   };
diff --git a/ppapi/shared_impl/graphics_3d_impl.cc b/ppapi/shared_impl/graphics_3d_impl.cc
index cb21e77..00555de 100644
--- a/ppapi/shared_impl/graphics_3d_impl.cc
+++ b/ppapi/shared_impl/graphics_3d_impl.cc
@@ -33,6 +33,11 @@ int32_t Graphics3DImpl::SetAttribs(int32_t* attrib_list) {
   return PP_ERROR_FAILED;
 }
 
+int32_t Graphics3DImpl::GetError() {
+  // TODO(alokp): Implement me.
+  return PP_ERROR_FAILED;
+}
+
 int32_t Graphics3DImpl::ResizeBuffers(int32_t width, int32_t height) {
   if ((width < 0) || (height < 0))
     return PP_ERROR_BADARGUMENT;
diff --git a/ppapi/shared_impl/graphics_3d_impl.h b/ppapi/shared_impl/graphics_3d_impl.h
index a22cdee..07fe967 100644
--- a/ppapi/shared_impl/graphics_3d_impl.h
+++ b/ppapi/shared_impl/graphics_3d_impl.h
@@ -26,6 +26,7 @@ class PPAPI_SHARED_EXPORT Graphics3DImpl : public thunk::PPB_Graphics3D_API {
   // PPB_Graphics3D_API implementation.
   virtual int32_t GetAttribs(int32_t* attrib_list) OVERRIDE;
   virtual int32_t SetAttribs(int32_t* attrib_list) OVERRIDE;
+  virtual int32_t GetError() OVERRIDE;
   virtual int32_t ResizeBuffers(int32_t width, int32_t height) OVERRIDE;
   virtual int32_t SwapBuffers(PP_CompletionCallback callback) OVERRIDE;
   virtual void* MapTexSubImage2DCHROMIUM(GLenum target,
diff --git a/ppapi/thunk/ppb_graphics_3d_api.h b/ppapi/thunk/ppb_graphics_3d_api.h
index c9af8e4..7b782254 100644
--- a/ppapi/thunk/ppb_graphics_3d_api.h
+++ b/ppapi/thunk/ppb_graphics_3d_api.h
@@ -20,6 +20,7 @@ class PPAPI_THUNK_EXPORT PPB_Graphics3D_API {
   // Graphics3D API.
   virtual int32_t GetAttribs(int32_t* attrib_list) = 0;
   virtual int32_t SetAttribs(int32_t* attrib_list) = 0;
+  virtual int32_t GetError() = 0;
   virtual int32_t ResizeBuffers(int32_t width, int32_t height) = 0;
   virtual int32_t SwapBuffers(PP_CompletionCallback callback) = 0;
 
diff --git a/ppapi/thunk/ppb_graphics_3d_thunk.cc b/ppapi/thunk/ppb_graphics_3d_thunk.cc
index 50c31fc..c706d33 100644
--- a/ppapi/thunk/ppb_graphics_3d_thunk.cc
+++ b/ppapi/thunk/ppb_graphics_3d_thunk.cc
@@ -17,6 +17,13 @@ namespace {
 
 typedef EnterResource<PPB_Graphics3D_API> EnterGraphics3D;
 
+int32_t GetAttribMaxValue(PP_Resource instance,
+                          int32_t attribute,
+                          int32_t* value) {
+  // TODO(alokp): Implement me.
+  return PP_ERROR_FAILED;
+}
+
 PP_Resource Create(PP_Instance instance,
                    PP_Resource share_context,
                    const int32_t* attrib_list) {
@@ -46,6 +53,14 @@ int32_t SetAttribs(PP_Resource graphics_3d, int32_t* attrib_list) {
   return enter.object()->SetAttribs(attrib_list);
 }
 
+int32_t GetError(PP_Resource graphics_3d) {
+  EnterGraphics3D enter(graphics_3d, true);
+  if (enter.failed())
+    return PP_ERROR_BADRESOURCE;
+
+  return enter.object()->GetError();
+}
+
 int32_t ResizeBuffers(PP_Resource graphics_3d, int32_t width, int32_t height) {
   EnterGraphics3D enter(graphics_3d, true);
   if (enter.failed())
@@ -62,10 +77,12 @@ int32_t SwapBuffers(PP_Resource graphics_3d, PP_CompletionCallback callback) {
 }
 
 const PPB_Graphics3D_Dev g_ppb_graphics_3d_thunk = {
+  &GetAttribMaxValue,
   &Create,
   &IsGraphics3D,
   &GetAttribs,
   &SetAttribs,
+  &GetError,
   &ResizeBuffers,
   &SwapBuffers
 };