Proposed changes to Pepper 3D API.

ppapi/c/dev/ppb_context_3d_dev.h

+// Copyright (c) 2010 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_CONTEXT_3D_DEV_H_
+#define PPAPI_C_DEV_PPB_CONTEXT_3D_DEV_H_
+
+#include "ppapi/c/pp_bool.h"
+#include "ppapi/c/pp_module.h"
+#include "ppapi/c/pp_resource.h"
+
+#define PPB_CONTEXT_3D_DEV_INTERFACE "PPB_Context3D(Dev);0.1"
+
+// TODO(alokp): Should this rather be named Graphics3DContext
+// to indicate that it is part of the Graphics3D package?
+struct PPB_Context3D_Dev {
+  // Creates and initializes a rendering context and returns a handle to it.
+  // The context can be used to render to any compatible PPB_Surface3D_Dev.
+  //
+  // 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. The only attribute that can be
+  // specified in attrib list is PP_GRAPHICS3DATTRIB_CONTEXT_CLIENT_VERSION,
+  // and this attribute may only be specified when creating a OpenGL ES context.
+  // attrib list may be NULL or empty (first attribute is EGL_NONE), in which
+  // case attributes assume their default values as described below.
+  // PP_GRAPHICS3DATTRIB_CONTEXT_CLIENT_VERSION determines which version of an
+  // OpenGL ES context to create. An attribute value of 1 specifies creation
+  // of an OpenGL ES 1.x context. An attribute value of 2 specifies creation
+  // of an OpenGL ES 2.x context. The default value for
+  // PP_GRAPHICS3DATTRIB_CONTEXT_CLIENT_VERSION is 1.
+  //
+  // If config is not a valid PP_Graphics3DConfig_Dev, or does not support
+  // the requested client API, then an PP_GRAPHICS3DERROR_BAD_CONFIG error is
+  // generated (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_Module module,
+                        PP_Graphics3DConfig_Dev config,
+                        PP_Resource share_context,
+                        const int32_t* attrib_list);
+
+  // Returns PP_TRUE if the given resource is a valid PPB_Context3D_Dev,
+  // PP_FALSE if it is an invalid resource or is a resource of another type.
+  PP_Bool (*IsContext3D)(PP_Resource resource);
+
+  // Returns in value the value of attribute for context.
+  // Attributes that can be queried for include:
+  // - PP_GRAPHICS3DATTRIB_CONFIG_ID: returns the ID of the
+  //   PP_Graphics3DConfig_Dev with respect to which the context was created.
+  // - PP_GRAPHICS3DATTRIB_CONTEXT_CLIENT_TYPE: returns the type of client API

[brettw, 2010/12/10 00:32:27]

The documentation here is great. I think it would be better to add the
documentation where the enum is defined rather than on these functions. Then on
the functions, specify which subset of attributes it can take. This will also
save you from describing them twice (set and get attrib on surface 3D have some
duplicated descriptions).

[alokp, 2010/12/10 13:20:33]

Done.

+  //   this context supports.
+  // - PP_GRAPHICS3DATTRIB_CONTEXT_CLIENT_VERSION: returns the version of the
+  //   client API this context supports, as specified at context creation time.
+  //   The resulting value is only meaningful for an OpenGL ES context.
+  // - PP_GRAPHICS3DATTRIB_RENDER_BUFFER: returns the buffer which client API
+  //   rendering via this context will use. The value returned depends on
+  //   properties of both the context, and the surface to which the context
+  //   is bound:
+  //   - If the context is bound to a surface, then either
+  //     PP_GRAPHICS3DATTRIBVALUE_BACK_BUFFER or
+  //     PP_GRAPHICS3DATTRIBVALUE_SINGLE_BUFFER may be returned. The value
+  //     returned depends on the buffer requested by the setting of the
+  //     PP_GRAPHICS3DATTRIB_RENDER_BUFFER property of the surface.
+  //   - If the context is not bound to a surface, then
+  //     PP_GRAPHICS3DATTRIBVALUE_NONE will be returned.
+  //
+  // On failure the following error codes may be returned:
+  // - PP_GRAPHICS3DERROR_BAD_ATTRIBUTE if attribute is not a valid attribute
+  // - PP_GRAPHICS3DERROR_BAD_CONTEXT if context is invalid.
+  int32_t (*GetAttrib)(PP_Resource context,
+                       int32_t attribute,
+                       int32_t* value);
+
+  // Binds context to the draw and read surfaces.
+  // For an OpenGL or OpenGL ES context, draw is used for all operations except
+  // for any pixel data read back or copied, which is taken from the frame
+  // buffer values of read. Note that the same PPB_Surface3D_Dev may be
+  // specified for both draw and read.
+  //
+  // On failure the following error codes may be returned:
+  // - PP_GRAPHICS3DERROR_BAD_MATCH: if draw or read surfaces are not
+  //   compatible with context.
+  // - PP_GRAPHICS3DERROR_BAD_ACCESS: if either draw or read is bound to any
+  //   other context.
+  // - PP_GRAPHICS3DERROR_BAD_CONTEXT: if context is not a valid context.
+  // - PP_GRAPHICS3DERROR_BAD_SURFACE: if either draw or read are not valid
+  //   surfaces.
+  // - PP_GRAPHICS3DERROR_BAD_MATCH:fIf draw and read cannot fit into
+  //   graphics memory simultaneously.
+  // - PP_ERROR_NOMEMORY: if the ancillary buffers for draw and read cannot
+  //   be allocated.
+  // - PP_GRAPHICS3DERROR_CONTEXT_LOST: if a power management event has
+  //   occurred.
+  //
+  // If draw is destroyed after BindSurfaces is called, then subsequent
+  // rendering commands will be processed and the context state will be updated,
+  // but the surface contents become undefined. If read is destroyed after
+  // BindSurfaces then pixel values read from the framebuffer (e.g., as result
+  // of calling glReadPixels) are undefined.
+  //
+  // To unbind surfaces set draw and read to NULL.
+  int32_t (*BindSurfaces)(PP_Resource context,
+                          PP_Resource draw,
+                          PP_Resource read);
+
+  // Returns the surfaces bound to the context for drawing and reading in
+  // draw and read respectively.
+  //
+  // On failure, the following error codes can be returned:
+  // - PP_GRAPHICS3DERROR_BAD_CONTEXT: if context is not a valid context.
+  // - PP_ERROR_BADARGUMENT: if either draw or read is NULL.
+  int32_t (*GetBoundSurfaces)(PP_Resource context,
+                              PP_Resource* draw,
+                              PP_Resource* read);
+};
+
+#endif  // PPAPI_C_DEV_PPB_CONTEXT_3D_DEV_H_