Use Instance* in the Graphics3D constructor rather than Instance&, for

consistency.

I also created a new 2-arg constructor since the share_context will normally
be empty, and it's less clear what to use there if you don't have a shared
context.

I copied comments from the C interface to the C++ one, and converted the
comments in the C header file to C-style comments from C++ ones. The
documentation still needs some Doxygen love, but we can worry about that
later.
Review URL: http://codereview.chromium.org/7867048

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

6 files changed, 325 insertions, 170 deletions

diff --git a/gpu/demos/framework/pepper.cc b/gpu/demos/framework/pepper.cc
index 3a2e180b..831e094 100644
--- a/gpu/demos/framework/pepper.cc
+++ b/gpu/demos/framework/pepper.cc
@@ -88,7 +88,7 @@ class PluginInstance : public pp::Instance {
         PP_GRAPHICS3DATTRIB_HEIGHT, size_.height(),
         PP_GRAPHICS3DATTRIB_NONE
     };
-    context_ = pp::Graphics3D(*this, pp::Graphics3D(), attribs);
+    context_ = pp::Graphics3D(this, attribs);
     if (context_.is_null())
       return;
 
diff --git a/ppapi/c/ppb_graphics_3d.h b/ppapi/c/ppb_graphics_3d.h
index ef93402..6415318 100644
--- a/ppapi/c/ppb_graphics_3d.h
+++ b/ppapi/c/ppb_graphics_3d.h
@@ -11,192 +11,209 @@
 #include "ppapi/c/pp_instance.h"
 #include "ppapi/c/pp_resource.h"
 
-// Example usage from plugin code:
-//
-// // Setup.
-// PP_Resource context;
-// int32_t attribs[] = {PP_GRAPHICS3DATTRIB_WIDTH, 800,
-//                      PP_GRAPHICS3DATTRIB_HEIGHT, 800,
-//                      PP_GRAPHICS3DATTRIB_NONE};
-// context = g3d->Create(instance, attribs, &context);
-// inst->BindGraphics(instance, context);
-//
-// // Present one frame.
-// gles2->Clear(context, GL_COLOR_BUFFER);
-// g3d->SwapBuffers(context);
-//
-// // Shutdown.
-// core->ReleaseResource(context);
+/* Example usage from plugin code:
+ *
+ * // Setup.
+ * PP_Resource context;
+ * int32_t attribs[] = {PP_GRAPHICS3DATTRIB_WIDTH, 800,
+ *                      PP_GRAPHICS3DATTRIB_HEIGHT, 800,
+ *                      PP_GRAPHICS3DATTRIB_NONE};
+ * context = g3d->Create(instance, 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_INTERFACE_1_0 "PPB_Graphics3D;1.0"
 #define PPB_GRAPHICS_3D_INTERFACE PPB_GRAPHICS_3D_INTERFACE_1_0
 
 struct PPB_Graphics3D {
-  // 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
+  /**
+   * 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.
-  //
-  // 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_Graphics3D_Dev can share data in
-  // this fashion.
-  //
-  // attrib_list specifies a list of attributes for the context. It is a list
-  // of attribute name-value pairs in which each attribute is immediately
-  // followed by the corresponding desired value. The list is terminated with
-  // PP_GRAPHICS3DATTRIB_NONE. The attrib_list may be NULL or empty
-  // (first attribute is PP_GRAPHICS3DATTRIB_NONE). If an attribute is not
-  // specified in attrib_list, then the default value is used (it is said to
-  // be specified implicitly).
-  //
-  // Attributes for the context are chosen according to an attribute-specific
-  // criteria. Attributes can be classified into two categories:
-  // - AtLeast: The attribute value in the returned context meets or exceeds
-  //            the value specified in attrib_list.
-  // - Exact: The attribute value in the returned context is equal to
-  //          the value specified in attrib_list.
-  //
-  // Attributes that can be specified in attrib_list include:
-  // - PP_GRAPHICS3DATTRIB_ALPHA_SIZE: Category: AtLeast Default: 0.
-  // - PP_GRAPHICS3DATTRIB_BLUE_SIZE: Category: AtLeast Default: 0.
-  // - PP_GRAPHICS3DATTRIB_GREEN_SIZE: Category: AtLeast Default: 0.
-  // - PP_GRAPHICS3DATTRIB_RED_SIZE: Category: AtLeast Default: 0.
-  // - PP_GRAPHICS3DATTRIB_DEPTH_SIZE: Category: AtLeast Default: 0.
-  // - PP_GRAPHICS3DATTRIB_STENCIL_SIZE: Category: AtLeast Default: 0.
-  // - PP_GRAPHICS3DATTRIB_SAMPLES: Category: AtLeast Default: 0.
-  // - PP_GRAPHICS3DATTRIB_SAMPLE_BUFFERS: Category: AtLeast Default: 0.
-  // - PP_GRAPHICS3DATTRIB_WIDTH: Category: Exact Default: 0.
-  // - PP_GRAPHICS3DATTRIB_HEIGHT: Category: Exact Default: 0.
-  // - PP_GRAPHICS3DATTRIB_SWAP_BEHAVIOR:
-  //   Category: Exact Default: Implementation defined.
-  //
-  // On failure NULL resource is returned.
+  /**
+   * 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_Graphics3D can share data in
+   * this fashion.
+   *
+   * attrib_list specifies a list of attributes for the context. It is a list
+   * of attribute name-value pairs in which each attribute is immediately
+   * followed by the corresponding desired value. The list is terminated with
+   * PP_GRAPHICS3DATTRIB_NONE. The attrib_list may be NULL or empty
+   * (first attribute is PP_GRAPHICS3DATTRIB_NONE). If an attribute is not
+   * specified in attrib_list, then the default value is used (it is said to
+   * be specified implicitly).
+   *
+   * Attributes for the context are chosen according to an attribute-specific
+   * criteria. Attributes can be classified into two categories:
+   * - AtLeast: The attribute value in the returned context meets or exceeds
+   *            the value specified in attrib_list.
+   * - Exact: The attribute value in the returned context is equal to
+   *          the value specified in attrib_list.
+   *
+   * Attributes that can be specified in attrib_list include:
+   * - PP_GRAPHICS3DATTRIB_ALPHA_SIZE: Category: AtLeast Default: 0.
+   * - PP_GRAPHICS3DATTRIB_BLUE_SIZE: Category: AtLeast Default: 0.
+   * - PP_GRAPHICS3DATTRIB_GREEN_SIZE: Category: AtLeast Default: 0.
+   * - PP_GRAPHICS3DATTRIB_RED_SIZE: Category: AtLeast Default: 0.
+   * - PP_GRAPHICS3DATTRIB_DEPTH_SIZE: Category: AtLeast Default: 0.
+   * - PP_GRAPHICS3DATTRIB_STENCIL_SIZE: Category: AtLeast Default: 0.
+   * - PP_GRAPHICS3DATTRIB_SAMPLES: Category: AtLeast Default: 0.
+   * - PP_GRAPHICS3DATTRIB_SAMPLE_BUFFERS: Category: AtLeast Default: 0.
+   * - PP_GRAPHICS3DATTRIB_WIDTH: Category: Exact Default: 0.
+   * - PP_GRAPHICS3DATTRIB_HEIGHT: Category: Exact Default: 0.
+   * - PP_GRAPHICS3DATTRIB_SWAP_BEHAVIOR:
+   *   Category: Exact Default: Implementation defined.
+   *
+   * On failure NULL resource is returned.
+   */
   PP_Resource (*Create)(PP_Instance instance,
                         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.
+  /**
+   * Returns PP_TRUE if the given resource is a valid PPB_Graphics3D,
+   * PP_FALSE if it is an invalid resource or is a resource of another type.
+   */
   PP_Bool (*IsGraphics3D)(PP_Resource resource);
 
-  // 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_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:
-  // int attrib_list[] = {PP_GRAPHICS3DATTRIB_RED_SIZE, 0,
-  //                      PP_GRAPHICS3DATTRIB_GREEN_SIZE, 0,
-  //                      PP_GRAPHICS3DATTRIB_BLUE_SIZE, 0,
-  //                      PP_GRAPHICS3DATTRIB_NONE};
-  // GetAttribs(context, attrib_list);
-  // int red_bits = attrib_list[1];
-  // int green_bits = attrib_list[3];
-  // int blue_bits = attrib_list[5];
+  /**
+   * Retrieves the value for each attribute in attrib_list. The list
+   * has the same structure as described for PPB_Graphics3D::Create.
+   * It is both input and output structure for this function.
+   *
+   * All attributes specified in PPB_Graphics3D.Create can be queried for.
+   * 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.
+   *
+   * Example usage: To get the values for rgb bits in the color buffer,
+   * this function must be called as following:
+   * int attrib_list[] = {PP_GRAPHICS3DATTRIB_RED_SIZE, 0,
+   *                      PP_GRAPHICS3DATTRIB_GREEN_SIZE, 0,
+   *                      PP_GRAPHICS3DATTRIB_BLUE_SIZE, 0,
+   *                      PP_GRAPHICS3DATTRIB_NONE};
+   * GetAttribs(context, attrib_list);
+   * int red_bits = attrib_list[1];
+   * int green_bits = attrib_list[3];
+   * int blue_bits = attrib_list[5];
+   */
   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::Create.
-  //
-  // 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.
+  /**
+   * Sets the values for each attribute in attrib_list. The list
+   * has the same structure as described for PPB_Graphics3D.Create.
+   *
+   * 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
+  /**
+   * 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:
-  // - PP_ERROR_BADRESOURCE if context is invalid.
-  // - PP_ERROR_BADARGUMENT if the value specified for width or height
-  //   is less than zero.
-  //
-  // If the surface could not be resized due to insufficient resources,
-  // PP_ERROR_NOMEMORY error is returned on the next SwapBuffers callback.
+  /**
+   * 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.
+   *
+   * If the surface could not be resized due to insufficient resources,
+   * PP_ERROR_NOMEMORY error is returned on the next SwapBuffers callback.
+   */
   int32_t (*ResizeBuffers)(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_GRAPHICS3DATTRIB_BUFFER_PRESERVED.
-  //
-  // 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.
+  /**
+   * 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_GRAPHICS3DATTRIB_BUFFER_PRESERVED.
+   *
+   * 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/ppp_graphics_3d.h b/ppapi/c/ppp_graphics_3d.h
index 9916770..a40d94f 100644
--- a/ppapi/c/ppp_graphics_3d.h
+++ b/ppapi/c/ppp_graphics_3d.h
@@ -10,7 +10,9 @@
 #define PPP_GRAPHICS_3D_INTERFACE "PPP_Graphics_3D;1.0"
 
 struct PPP_Graphics3D {
-  // Called when the OpenGL ES window is invalidated and needs to be repainted.
+  /**
+   * Called when the OpenGL ES window is invalidated and needs to be repainted.
+   */
   void (*Graphics3DContextLost)(PP_Instance instance);
 };
 
diff --git a/ppapi/cpp/graphics_3d.cc b/ppapi/cpp/graphics_3d.cc
index 0cd8ba2..24ea8a42 100644
--- a/ppapi/cpp/graphics_3d.cc
+++ b/ppapi/cpp/graphics_3d.cc
@@ -23,12 +23,20 @@ template <> const char* interface_name<PPB_Graphics3D>() {
 Graphics3D::Graphics3D() {
 }
 
-Graphics3D::Graphics3D(const Instance& instance,
+Graphics3D::Graphics3D(const Instance* instance,
+                       const int32_t* attrib_list) {
+  if (has_interface<PPB_Graphics3D>()) {
+    PassRefFromConstructor(get_interface<PPB_Graphics3D>()->Create(
+        instance->pp_instance(), 0, attrib_list));
+  }
+}
+
+Graphics3D::Graphics3D(const Instance* instance,
                        const Graphics3D& share_context,
                        const int32_t* attrib_list) {
   if (has_interface<PPB_Graphics3D>()) {
     PassRefFromConstructor(get_interface<PPB_Graphics3D>()->Create(
-        instance.pp_instance(),
+        instance->pp_instance(),
         share_context.pp_resource(),
         attrib_list));
   }
diff --git a/ppapi/cpp/graphics_3d.h b/ppapi/cpp/graphics_3d.h
index aaa6d08..98e61a3 100644
--- a/ppapi/cpp/graphics_3d.h
+++ b/ppapi/cpp/graphics_3d.h
@@ -16,20 +16,148 @@ class Var;
 
 class Graphics3D : public Resource {
  public:
-  // Creates an is_null() Graphics3D_Dev object.
+  /// Creates an is_null() Graphics3D object.
   Graphics3D();
 
-  Graphics3D(const Instance& instance,
+  /// Creates and initializes a 3D rendering context. The returned context is
+  /// off-screen to start with. It must be attached to a plugin instance using
+  /// Instance::BindGraphics to draw on the web page.
+  ///
+  /// @param[in] instance The instance that will own the new Graphics3D.
+  ///
+  /// @param[in] attrib_list The list of attributes for the context. It is a
+  /// list of attribute name-value pairs in which each attribute is immediately
+  /// followed by the corresponding desired value. The list is terminated with
+  /// PP_GRAPHICS3DATTRIB_NONE. The attrib_list may be NULL or empty
+  /// (first attribute is PP_GRAPHICS3DATTRIB_NONE). If an attribute is not
+  /// specified in attrib_list, then the default value is used (it is said to
+  /// be specified implicitly).
+  ///
+  /// Attributes for the context are chosen according to an attribute-specific
+  /// criteria. Attributes can be classified into two categories:
+  /// - AtLeast: The attribute value in the returned context meets or exceeds
+  ///            the value specified in attrib_list.
+  /// - Exact: The attribute value in the returned context is equal to
+  ///          the value specified in attrib_list.
+  ///
+  /// Attributes that can be specified in attrib_list include:
+  /// - PP_GRAPHICS3DATTRIB_ALPHA_SIZE: Category: AtLeast Default: 0.
+  /// - PP_GRAPHICS3DATTRIB_BLUE_SIZE: Category: AtLeast Default: 0.
+  /// - PP_GRAPHICS3DATTRIB_GREEN_SIZE: Category: AtLeast Default: 0.
+  /// - PP_GRAPHICS3DATTRIB_RED_SIZE: Category: AtLeast Default: 0.
+  /// - PP_GRAPHICS3DATTRIB_DEPTH_SIZE: Category: AtLeast Default: 0.
+  /// - PP_GRAPHICS3DATTRIB_STENCIL_SIZE: Category: AtLeast Default: 0.
+  /// - PP_GRAPHICS3DATTRIB_SAMPLES: Category: AtLeast Default: 0.
+  /// - PP_GRAPHICS3DATTRIB_SAMPLE_BUFFERS: Category: AtLeast Default: 0.
+  /// - PP_GRAPHICS3DATTRIB_WIDTH: Category: Exact Default: 0.
+  /// - PP_GRAPHICS3DATTRIB_HEIGHT: Category: Exact Default: 0.
+  /// - PP_GRAPHICS3DATTRIB_SWAP_BEHAVIOR:
+  ///   Category: Exact Default: Implementation defined.
+  ///
+  /// On failure, the object will be is_null().
+  Graphics3D(const Instance* instance,
+             const int32_t* attrib_list);
+
+  /// Creates and initializes a 3D rendering context. The returned context is
+  /// off-screen to start with. It must be attached to a plugin instance using
+  /// Instance::BindGraphics to draw on the web page.
+  ///
+  /// This is identical to the 2-argument version except that this version
+  /// allows sharing of resources with another context.
+  ///
+  /// @param[in] instance The instance that will own the new Graphics3D.
+  ///
+  /// @param[in] share_context Specifies the context with which all
+  /// shareable data will be shared. The shareable data is defined by the
+  /// client API (note that for OpenGL and OpenGL ES, shareable data excludes
+  /// texture objects named 0). An arbitrary number of Graphics3D resources
+  /// can share data in this fashion.
+  //
+  /// @param[in] attrib_list The list of attributes for the context. See the
+  /// 2-argument version for more information.
+  ///
+  /// On failure, the object will be is_null().
+  Graphics3D(const Instance* instance,
              const Graphics3D& share_context,
              const int32_t* attrib_list);
 
   ~Graphics3D();
 
+  /// Retrieves the value for each attribute in attrib_list. The list
+  /// has the same structure as described for the constructor.
+  /// It is both input and output structure for this function.
+  ///
+  /// All attributes specified in PPB_Graphics3D.Create can be queried for.
+  /// 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.
+  ///
+  /// Example usage: To get the values for rgb bits in the color buffer,
+  /// this function must be called as following:
+  /// int attrib_list[] = {PP_GRAPHICS3DATTRIB_RED_SIZE, 0,
+  ///                      PP_GRAPHICS3DATTRIB_GREEN_SIZE, 0,
+  ///                      PP_GRAPHICS3DATTRIB_BLUE_SIZE, 0,
+  ///                      PP_GRAPHICS3DATTRIB_NONE};
+  /// GetAttribs(context, attrib_list);
+  /// int red_bits = attrib_list[1];
+  /// int green_bits = attrib_list[3];
+  /// int blue_bits = attrib_list[5];
   int32_t GetAttribs(int32_t* attrib_list) const;
+
+  /// Sets the values for each attribute in attrib_list. The list
+  /// has the same structure as described for PPB_Graphics3D.Create.
+  ///
+  /// 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(int32_t* attrib_list);
 
+  /// Resizes the backing surface for the 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.
+  ///
+  /// If the surface could not be resized due to insufficient resources,
+  /// PP_ERROR_NOMEMORY error is returned on the next SwapBuffers callback.
   int32_t ResizeBuffers(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_GRAPHICS3DATTRIB_BUFFER_PRESERVED.
+  ///
+  /// 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(const CompletionCallback& cc);
 };
 
diff --git a/ppapi/tests/test_graphics_3d.cc b/ppapi/tests/test_graphics_3d.cc
index 9f409e7..b54ce3d 100644
--- a/ppapi/tests/test_graphics_3d.cc
+++ b/ppapi/tests/test_graphics_3d.cc
@@ -33,7 +33,7 @@ std::string TestGraphics3D::TestFrame() {
       PP_GRAPHICS3DATTRIB_HEIGHT, height,
       PP_GRAPHICS3DATTRIB_NONE
   };
-  pp::Graphics3D context(*instance_, pp::Graphics3D(), attribs);
+  pp::Graphics3D context(instance_, attribs);
   ASSERT_FALSE(context.is_null());
 
   // Clear color buffer to opaque red.