Pepper3D API change - merging PPB_Surface3D and PPB_Context3D into PPB_Graphics3D.

The original API was designed to be similar to EGL a couple of reasons:
- EGL is a standard API that developers are familiar with and serves their purpose
- It would be relatively easy to write an EGL implementation on top of Pepper3D implementation to facilitate porting of existing EGL apps

However the restrictions in Pepper API do not allow certain use cases. The separation of context and surface allows using a single context to render to multiple instance or offscreen surfaces. But since each context is implicitly tied to a particular instance it is infeasible or confusing to draw to other instace surfaces. The offscreen use-case can be easily handled using Framebuffer objects (FBO). Writing an EGL wrapper for the new API should not be too difficult either.

Combining context and surface has advantages:
- Less complex API and implementation
- Convinient versioning

Please note that this is not ready to submit. I am only sending the proposed API. Once approved I will delete PPB_Surface3D and PPB_Context3D, and make other necessary changes to make sure everything compiles and works.
Review URL: http://codereview.chromium.org/6745010

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

2 files changed, 137 insertions, 22 deletions

diff --git a/ppapi/c/dev/pp_graphics_3d_dev.h b/ppapi/c/dev/pp_graphics_3d_dev.h
index 6ea2506..49f47c7 100644
--- a/ppapi/c/dev/pp_graphics_3d_dev.h
+++ b/ppapi/c/dev/pp_graphics_3d_dev.h
@@ -1,4 +1,4 @@
-/* Copyright (c) 2010 The Chromium Authors. All rights reserved.
+/* 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.
  */
@@ -8,22 +8,11 @@
 
 #include "ppapi/c/pp_stdint.h"
 
-// TODO(alokp): Using PP_Graphics3D prefix is making these enum names rather
-// long. Can we just use PP_GL? It will be a nice short replacement of EGL.
-// In which case we should rename associated classes as - PP_GL, PP_GLContext,
-// PP_GLContext, PP_GLSurface, PP_GLConfig, and PP_OpenGLES2.
-//
-// Another option is to rename Surface3D and Context3D to Graphics3DSurface
-// and Graphics3DContext respectively But this does not make the names
-// any shorter.
-
 enum PP_Graphics3DError_Dev {
   PP_GRAPHICS3DERROR_BAD_ACCESS = 0x3002,
   PP_GRAPHICS3DERROR_BAD_ATTRIBUTE = 0x3004,
   PP_GRAPHICS3DERROR_BAD_CONFIG = 0x3005,
-  PP_GRAPHICS3DERROR_BAD_CONTEXT = 0x3006,
   PP_GRAPHICS3DERROR_BAD_MATCH = 0x3009,
-  PP_GRAPHICS3DERROR_BAD_SURFACE = 0x300D,
   PP_GRAPHICS3DERROR_CONTEXT_LOST = 0x300E
 };
 
diff --git a/ppapi/c/dev/ppb_graphics_3d_dev.h b/ppapi/c/dev/ppb_graphics_3d_dev.h
index a5cfc6a..79bf80d 100644
--- a/ppapi/c/dev/ppb_graphics_3d_dev.h
+++ b/ppapi/c/dev/ppb_graphics_3d_dev.h
@@ -1,4 +1,4 @@
-/* Copyright (c) 2010 The Chromium Authors. All rights reserved.
+/* 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.
  */
@@ -7,32 +7,33 @@
 
 #include "ppapi/c/dev/pp_graphics_3d_dev.h"
 
+#include "ppapi/c/pp_bool.h"
+#include "ppapi/c/pp_instance.h"
+#include "ppapi/c/pp_resource.h"
+
 // Example usage from plugin code:
 //
 // // Setup.
-// PP_Resource context, surface;
+// PP_Resource context;
 // int32_t config, num_config;
 // g3d->GetConfigs(&config, 1, &num_config);
 // int32_t attribs[] = {PP_GRAPHICS_3D_SURFACE_WIDTH, 800,
 //                      PP_GRAPHICS_3D_SURFACE_HEIGHT, 800,
 //                      PP_GRAPHICS_3D_ATTRIB_NONE};
-// c3d->Create(instance, config, NULL, NULL, &context);
-// s3d->Create(instance, config, attribs, &surface);
-// c3d->BindSurfaces(context, surface, surface);
-// inst->BindGraphics(instance, surface);
+// context = g3d->Create(instance, config, attribs, &context);
+// inst->BindGraphics(instance, context);
 //
 // // Present one frame.
 // gles2->Clear(context, GL_COLOR_BUFFER);
-// c3d->SwapBuffers(context);
+// g3d->SwapBuffers(context);
 //
 // // Shutdown.
 // core->ReleaseResource(context);
-// core->ReleaseResource(surface);
 
-#define PPB_GRAPHICS_3D_DEV_INTERFACE "PPB_Graphics3D(Dev);0.3"
+#define PPB_GRAPHICS_3D_DEV_INTERFACE "PPB_Graphics3D(Dev);0.4"
 
 struct PPB_Graphics3D_Dev {
-  // TODO(alokp): Do these functions need module argument.
+  // 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.
@@ -95,6 +96,131 @@ struct PPB_Graphics3D_Dev {
   //   contents are implementation specific.
   // On failure, PP_VARTYPE_UNDEFINED is returned.
   struct PP_Var (*GetString)(int32_t name);
+
+  // 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_Context3D_Dev can share data in
+  // this fashion.
+  //
+  // attrib_list specifies a list of attributes for the context. The list
+  // has the same structure as described for
+  // PPB_Graphics3D_Dev::GetConfigAttribs. attrib_list may be NULL or empty
+  // (first attribute is PP_GRAPHICS_3D_ATTRIB_NONE), in which case attributes
+  // assume their default values.
+  // Attributes that can be specified in attrib_list include:
+  // - PP_GRAPHICS3DATTRIB_CONTEXT_CLIENT_VERSION: may only be specified when
+  //   creating a OpenGL ES context.
+  // - PP_GRAPHICS3DATTRIB_WIDTH: The default value is zero.
+  // - PP_GRAPHICS3DATTRIB_HEIGHT: The default value is zero.
+  // - PP_GRAPHICS3DATTRIB_LARGEST_SURFACE: If true, creates the largest
+  //   possible surface when the allocation of the surface would otherwise fail.
+  //   The width and height of the allocated surface will never exceed the
+  //   values of PP_GRAPHICS3DATTRIB_WIDTH and PP_GRAPHICS3DATTRIB_HEIGHT,
+  //   respectively. If this option is used, PPB_Graphics3D_Dev::GetAttrib
+  //   can be used to retrieve surface dimensions.
+  // - PP_GRAPHICS3DATTRIB_RENDER_BUFFER
+  //
+  // It will fail to create a context if config is not a valid PP_Config3D_Dev,
+  // or does not support the requested client API (this includes requesting
+  // creation of an OpenGL ES 1.x context when the
+  // PP_GRAPHICS3DATTRIB_RENDERABLE_TYPE attribute of config does not
+  // contain PP_GRAPHICS3DATTRIBVALUE_OPENGL_ES_BIT, or creation of an
+  // OpenGL ES 2.x context when the attribute does not contain
+  // PP_GRAPHICS3DATTRIBVALUE_OPENGL_ES2_BIT).
+  //
+  // On failure Create returns NULL resource.
+  PP_Resource (*Create)(PP_Instance instance,
+                        PP_Config3D_Dev config,
+                        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
+  // has the same structure as described for
+  // PPB_Graphics3D_Dev::GetConfigAttribs.
+  //
+  // Attributes that can be queried for include:
+  // - PP_GRAPHICS3DATTRIB_CONFIG_ID: returns the ID of the
+  //   PP_Config3D_Dev with respect to which the context was created.
+  // - PP_GRAPHICS3DATTRIB_CONTEXT_CLIENT_TYPE: returns the type of client API
+  //   this context supports.
+  // - PP_GRAPHICS3DATTRIB_CONTEXT_CLIENT_VERSION: returns the version of the
+  //   client API this context supports, as specified at context creation time.
+  // - PP_GRAPHICS3DATTRIB_RENDER_BUFFER: returns the buffer which client API
+  //   rendering via this context will use. Either
+  //   PP_GRAPHICS3DATTRIBVALUE_BACK_BUFFER or
+  //   PP_GRAPHICS3DATTRIBVALUE_SINGLE_BUFFER may be returned depending on the
+  //   buffer requested by the setting of the PP_GRAPHICS3DATTRIB_RENDER_BUFFER
+  //   property of the context.
+  // - PP_GRAPHICS3DATTRIB_LARGEST_SURFACE: returns the same attribute value
+  //   specified when the context was created with PPB_Graphics3D_Dev::Create.
+  // - PP_GRAPHICS3DATTRIB_WIDTH and PP_GRAPHICS3DATTRIB_HEIGHT: The returned
+  //   size may be less than the requested size if
+  //   PP_GRAPHICS3DATTRIB_LARGEST_SURFACE is true.
+  // - PP_GRAPHICS3DATTRIB_MULTISAMPLE_RESOLVE
+  // - PP_GRAPHICS3DATTRIB_SWAP_BEHAVIOR
+  //
+  // 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
+  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::GetConfigAttribs.
+  //
+  // Attributes that can be specified are:
+  // - PP_GRAPHICS3DATTRIB_MULTISAMPLE_RESOLVE: If value
+  //   is PP_GRAPHICS3DATTRIBVALUE_MULTISAMPLE_RESOLVE_BOX, and the
+  //   PP_GRAPHICS3DATTRIB_SURFACE_TYPE attribute used to create surface does
+  //   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);
+
+  // 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:
+  // - 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.
+  int32_t (*SwapBuffers)(PP_Resource context,
+                         struct PP_CompletionCallback callback);
 };
 
 #endif  /* PPAPI_C_DEV_PPB_GRAPHICS_3D_DEV_H_ */