Proposed changes to Pepper 3D API.

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 68085)
+++ ppapi/c/dev/ppb_graphics_3d_dev.h	(working copy)
@@ -6,99 +6,100 @@
 #define PPAPI_C_DEV_PPB_GRAPHICS_3D_DEV_H_
 
 #include "ppapi/c/pp_bool.h"
-#include "ppapi/c/pp_instance.h"
 #include "ppapi/c/pp_module.h"
 #include "ppapi/c/pp_resource.h"
 #include "ppapi/c/pp_stdint.h"
 
+#include "ppapi/c/dev/pp_graphics_3d_dev.h"
+
 // Example usage from plugin code:
 //
-// PP_Resource context = device->Create(module, config, contextAttribList);
-// CHECK(context);
+// // Setup.
+// PP_Resource context, surface;
+// 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(module, config, NULL, NULL, &context);
+// s3d->Create(module, config, attribs, &surface);
+// c3d->BindSurfaces(context, surface, surface);
+// inst->BindGraphics(instance, surface);
 //
 // // Present one frame.
-// CHECK(device->MakeCurrent(context));
-// glClear(GL_COLOR_BUFFER);
-// CHECK(device->MakeCurrent(NULL));
-// CHECK(device->SwapBuffers(context));
+// gles2->Clear(context, GL_COLOR_BUFFER);
+// c3d->SwapBuffers(context);
 //
 // // Shutdown.
 // core->ReleaseResource(context);
+// core->ReleaseResource(surface);
 
 #define PPB_GRAPHICS_3D_DEV_INTERFACE "PPB_Graphics3D(Dev);0.2"
 
-// These are the same error codes as used by EGL.
-enum {
-  PP_GRAPHICS_3D_ERROR_SUCCESS         = 0x3000,
-  PP_GRAPHICS_3D_ERROR_NOT_INITIALIZED = 0x3001,
-  PP_GRAOHICS_3D_ERROR_BAD_CONTEXT     = 0x3006,
-  PP_GRAPHICS_3D_ERROR_BAD_PARAMETER   = 0x300C,
-  PP_GRAPHICS_3D_ERROR_CONTEXT_LOST    = 0x300E
-};
-
-// QueryString targets, matching EGL ones.
-enum {
-  EGL_VENDOR      = 0x3053,
-  EGL_VERSION     = 0x3054,
-  EGL_EXTENSIONS  = 0x3055,
-  EGL_CLIENT_APIS = 0x308D
-};
-
 struct PPB_Graphics3D_Dev {
-  PP_Bool (*IsGraphics3D)(PP_Resource resource);
+  // TODO(alokp): Do these functions need module argument.
 
-  // EGL-like configuration ----------------------------------------------------
-  PP_Bool (*GetConfigs)(int32_t* configs,
+  // Retrieves the list of all available PP_Graphics3DConfig_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_Graphics3DConfig_Devs. No more than config_size
+  // PP_Graphics3DConfig_Devs will be returned even if more are available.
+  // However, if GetConfigs is called with configs = NULL, then no
+  // configurations are returned, but the total number of configurations
+  // available will be returned in num_config.
+  //
+  // On failure following error codes are returned:
+  // PP_ERROR_BADARGUMENT if num_config is NULL.
+  // PP_ERROR_FAILED for everything else.
+  int32_t (*GetConfigs)(PP_Graphics3DConfig_Dev* configs,
                         int32_t config_size,
                         int32_t* num_config);
 
-  PP_Bool (*ChooseConfig)(const int32_t* attrib_list,
-                          int32_t* configs,
-                          int32_t config_size,
-                          int32_t* num_config);
+  // Retrieves the values for each attribute in attrib_list.
+  // attrib_list is a list of attribute name-value pairs terminated with
+  // PP_GRAPHICS3DCONFIGATTRIB_NONE. It is both input and output structure
+  // for this function.
+  //
+  // On success PP_OK is returned and attrib_list is populated with
+  // values of the attributes specified in attrib_list.
+  // On failure following error codes are returned:
+  // PP_GRAPHICS3DERROR_BAD_CONFIG if config is not valid
+  // PP_ERROR_BADARGUMENT if attrib_list is NULL or malformed
+  // PP_GRAPHICS3DERROR_BAD_ATTRIBUTE if any of the attributes in the
+  //   attrib_list is not recognized.
+  //
+  // Example usage: To get the values for rgb bits in the color buffer,
+  // this function must be called as following:
+  // int attrib_list[] = {PP_GRAPHICS3DCONFIGATTRIB_RED_SIZE, 0,
+  //                      PP_GRAPHICS3DCONFIGATTRIB_GREEN_SIZE, 0,
+  //                      PP_GRAPHICS3DCONFIGATTRIB_BLUE_SIZE, 0,
+  //                      PP_GRAPHICS3DCONFIGATTRIB_NONE};
+  // GetConfigAttribs(config, attrib_list);
+  // int red_bits = attrib_list[1];
+  // int green_bits = attrib_list[3];
+  // int blue_bits = attrib_list[5];
+  int32_t (*GetConfigAttribs)(PP_Graphics3DConfig_Dev config,
+                              int32_t* attrib_list);
 
-  // TODO(apatrick): What to do if the browser window is moved to
-  // another display? Do the configs potentially change?
-  PP_Bool (*GetConfigAttrib)(int32_t config, int32_t attribute, int32_t* value);
-
-  const char* (*QueryString)(int32_t name);
-  // ---------------------------------------------------------------------------
-
-
-  // Create a reference counted 3D context. Releasing a context while it is
-  // current automatically sets the current context to NULL. This is only true
-  // for the releasing thread. Releasing a context while it is current on
-  // another thread leads to undefined behavior.
-  PP_Resource (*CreateContext)(PP_Instance instance,
-                               int32_t config,
-                               int32_t share_context,
-                               const int32_t* attrib_list);
-
-  // Get the address of any GL functions, whether core or part of an extension.
-  // Any thread.
-  void* (*GetProcAddress)(const char* name);
-
-  // Make a particular context current of the calling thread.  Returns PP_TRUE
-  // on success, PP_FALSE on failure.
-  PP_Bool (*MakeCurent)(PP_Resource context);
-
-  // Returns the calling thread's current context or NULL if no context is
-  // current.
-  PP_Resource (*GetCurrentContext)();
-
-  // Snapshots the rendered frame and makes it available for composition with
-  // the rest of the page. The alpha channel is used for translucency effects.
-  // One means fully opaque. Zero means fully transparent. Any thread.
-  // TODO(apatrick): premultiplied alpha or linear alpha? Premultiplied alpha is
-  // better for correct alpha blending effect. Most existing OpenGL code assumes
-  // linear. I could convert from linear to premultiplied during the copy from
-  // back-buffer to offscreen "front-buffer".
-  PP_Bool (*SwapBuffers)(PP_Resource context);
-
-  // Returns the current error for this thread. This is not associated with a
-  // particular context. It is distinct from the GL error returned by
-  // glGetError.
-  uint32_t (*GetError)();
+  // Returns a string describing some aspect of the Graphics3D implementation.
+  // name may be one of:
+  // - PP_GRAPHICS3DSTRING_CLIENT_APIS: describes which client rendering APIs are
+  //   supported. It is zero-terminated and contains a space-separated list of
+  //   API names, which must include at least one of "OpenGL" or "OpenGL_ES".
+  // - PP_GRAPHICS3DSTRING_EXTENSIONS: describes which extensions are supported
+  //   by the implementation. The string is zero-terminated and contains a
+  //   space-separated list of extension names; extension names themselves do
+  //   not contain spaces. If there are no extensions, then the empty string is
+  //   returned.
+  // - PP_GRAPHICS3DSTRING_VENDOR: Implementation dependent.
+  // - PP_GRAPHICS3DSTRING_VERSION: The format of the string is:
+  //   <major version.minor version><space><vendor specific info>
+  //   Both the major and minor portions of the version number are numeric.
+  //   The vendor-specific information is optional; if present, its format and
+  //   contents are implementation specific.
+  // On failure, PP_VARTYPE_UNDEFINED is returned.
+  struct PP_Var (*GetString)(int32_t name);
 };
 
 #endif  // PPAPI_C_DEV_PPB_GRAPHICS_3D_DEV_H_