Added PPB_Graphics3D_Dev::Resize to let plugins resize the backing surface.

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 13 matching lines @@
 // context = g3d->Create(instance, config, attribs, &context);
 // inst->BindGraphics(instance, context);
 //
 // // Present one frame.
 // gles2->Clear(context, GL_COLOR_BUFFER);
 // g3d->SwapBuffers(context);
 //
 // // Shutdown.
 // core->ReleaseResource(context);
 
 #define PPB_GRAPHICS_3D_DEV_INTERFACE_0_5 "PPB_Graphics3D(Dev);0.5"

[piman, 2011/07/28 23:35:06]

You need to rev the interface.

[alokp, 2011/07/29 16:13:12]

Done.

 #define PPB_GRAPHICS_3D_DEV_INTERFACE PPB_GRAPHICS_3D_DEV_INTERFACE_0_5
 
 struct PPB_Graphics3D_Dev {
   // TODO(alokp): Do these functions need module argument?
 
   // Retrieves the list of all available PP_Config3D_Devs.
   // configs is a pointer to a buffer containing config_size elements.
   // On success, PP_OK is returned. The number of configurations is returned
   // in num_config, and elements 0 through num_config - 1 of configs are filled
   // in with valid PP_Config3D_Devs. No more than config_size
@@ skipping 144 matching lines @@
   //   not contain PP_GRAPHICS3DATTRIBVALUE_MULTISAMPLE_RESOLVE_BOX_BIT, a
   //   PP_GRAPHICS3DERROR_BAD_MATCH error is returned.
   // - PP_GRAPHICS3DATTRIB_SWAP_BEHAVIOR: If value is
   //   PP_GRAPHICS3DATTRIBVALUE_BUFFER_PRESERVED, and the
   //   PP_GRAPHICS3DATTRIB_SURFACE_TYPE attribute used to create surface
   //   does not contain PP_GRAPHICS3DATTRIBVALUE_SWAP_BEHAVIOR_PRESERVED_BIT,
   //   a PP_GRAPHICS3DERROR_BAD_MATCH error is returned.
   int32_t (*SetAttribs)(PP_Resource context,
                         int32_t* attrib_list);
 
+  // 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.
+  // - PP_ERROR_NOMEMORY if the surface could not be resized due to
+  //   insufficient resources.

[piman, 2011/07/28 23:35:06]

You won't know about this case without doing a sync round-trip to the gpu
process. I think it would be better in general to treat this as a GL command
(after all it's just glResizeCHROMIUM), returning no error here, but setting the
GL error. If the plugin cares, it can call glGetError which will do the round
trip.

[alokp, 2011/07/29 16:13:12]

Yes I was worried about the round-trip, hence the TODO. There are a couple of
options to avoid the round trip:

1. Expose this as a GL function as you suggest. It is certainly practical but
not very clean API. We create and swap buffers in this interface. But having to
jump over to a the GL interface to resize it is confusing. Another problem with
this approach is that we will have to expose this as a GL extension, which by
definition is optional. But this is not optional. It will be impossible to use
Pepper 3D without this extension.

2. Add documentation that while you could issue a resize command here, you need
to call glGetError to catch out-of-memory condition. Again confusing.

3. Make it asynchronous like swap-buffers. One more callback to track may be too
complicated.

4. Make the callback for SwapBuffers accept an error code. This will also get
rid of the PPP_Graphics3D_Dev::Graphics3DContextLost(). After every frame we
could return one of the following errors generated by this interface:
- PP_GRAPHICS3D_ERROR_CONTEXT_LOST
- PP_ERROR_NO_MEMORY

I like the last option the best. It makes the API much simpler.

+  int32_t (*Resize)(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_GRAPHICS3DATTRIBVALUE_BUFFER_PRESERVED.
   //
   // SwapBuffers performs an implicit flush operation on context.
   //
   // This functions can run in two modes:
@@ skipping 10 matching lines @@
   // 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.
   int32_t (*SwapBuffers)(PP_Resource context,
                          struct PP_CompletionCallback callback);
 };
 
 #endif  /* PPAPI_C_DEV_PPB_GRAPHICS_3D_DEV_H_ */