Proposed changes to Pepper 3D API.

ppapi/c/dev/ppb_surface_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_SURFACE_3D_DEV_H_
+#define PPAPI_C_DEV_PPB_SURFACE_3D_DEV_H_
+
+#include "ppapi/c/pp_bool.h"
+#include "ppapi/c/pp_module.h"
+#include "ppapi/c/pp_resource.h"
+
+#define PPB_SURFACE_3D_DEV_INTERFACE "PPB_Surface3D(Dev);0.1"
+
+// TODO(alokp): Should this rather be named Graphics3DSurface
+// to indicate that it is part of the Graphics3D package?
+struct PPB_Surface3D_Dev {
+  // Creates a render surface and returns a handle to it.
+  // Any PPB_Context3D_Dev created with a compatible PP_Graphics3DConfig_Dev
+  // can be used to render into this surface. The returned surface is
+  // off-screen to start with. It must be attached to a plugin instance
+  // using PPB_Instance::BindGraphics to draw on the web page.
+  // attrib_list specifies a list of attributes for the surface. The list has
+  // the same structure as described for PPB_Graphics3D_Dev::GetConfigAttribs.
+  // Attributes that can be specified in attrib_list include:
+  // PP_GRAPHICS3DATTRIB_WIDTH: width of surface in pixels
+  // PP_GRAPHICS3DATTRIB_HEIGHT: height of surface in pixels
+  // 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_Surface3D_Dev::GetAttrib
+  //   can be used to retrieve surface dimensions.
+  // PP_GRAPHICS3DATTRIB_RENDER_BUFFER: specifies which buffer should be used
+  //   for client API rendering to the surface. If its value is
+  //   PP_GRAPHICS3DATTRIBVALUE_SINGLE_BUFFER, the surface contains a single
+  //   color buffer to which the client APIs render to. If its value is
+  //   PP_GRAPHICS3DATTRIBVALUE_BACK_BUFFER, then the surface contains two
+  //   color buffers and all client APIs render into the back buffer. The
+  //   default value of PP_GRAPHICS3DATTRIB_RENDER_BUFFER is
+  //   PP_GRAPHICS3DATTRIBVALUE_BACK_BUFFER.
+  //
+  // TODO(alokp): Need a way to return specific error codes. Would a fourth
+  // int32_t* argument be fine. It will certainly be inconsistent with othe
+  // functions that return error code.
+  PP_Resource (*Create)(PP_Module module,
+                        PP_Graphics3DConfig_Dev config,
+                        const int32_t* attrib_list);
+
+  // Returns PP_TRUE if the given resource is a valid Surface3D, PP_FALSE if it
+  // is an invalid resource or is a resource of another type.
+  PP_Bool (*IsSurface3D)(PP_Resource resource);
+
+  // Sets an attribute for PPB_Surface3D_Dev. The specified attribute of
+  // surface is set to value. Attributes that can be specified are:
+  // PP_GRAPHICS3DATTRIB_MULTISAMPLE_RESOLVE: specifies the filter to use when
+  //   resolving the multisample buffer. A value of
+  //   PP_GRAPHICS3DATTRIBVALUE_MULTISAMPLE_RESOLVE_DEFAULT chooses the default
+  //   implementation-defined filtering method, while
+  //   PP_GRAPHICS3DATTRIBVALUE_MULTISAMPLE_RESOLVE_BOX chooses a one-pixel wide
+  //   box filter placing equal weighting on all multisample values. 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. The initial value of
+  //   PP_GRAPHICS3DATTRIB_MULTISAMPLE_RESOLVE is
+  //   PP_GRAPHICS3DATTRIBVALUE_MULTISAMPLE_RESOLVE_DEFAULT.
+  // PP_GRAPHICS3DATTRIB_SWAP_BEHAVIOR: specifies the effect on the color
+  //   buffer of posting a surface with SwapBuffers. A value of
+  //   PP_GRAPHICS3DATTRIBVALUE_BUFFER_PRESERVED indicates that color buffer
+  //   contents are unaffected, while PP_GRAPHICS3DATTRIBVALUE_BUFFER_DESTROYED
+  //   indicates that color buffer contents may be destroyed or changed by the
+  //   operation. 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. The initial value of
+  //   PP_GRAPHICS3DATTRIB_SWAP_BEHAVIOR is chosen by the implementation.
+  int32_t (*SetAttrib)(PP_Resource surface,
+                       int32_t attribute,
+                       int32_t value);
+
+  // Retrieves the value of attribute for surface. Attributes that can be
+  // queried for are:
+  // PP_GRAPHICS3DATTRIB_CONFIG_ID: returns the ID of the
+  //   PP_Graphics3DConfig_Dev with respect to which the surface was created.
+  // PP_GRAPHICS3DATTRIB_LARGEST_SURFACE: returns the same attribute value
+  //   specified when the surface was created with PPB_Surface3D_Dev::Create.
+  // EGL_WIDTH and EGL_HEIGHT: returns respectively the width and height,
+  //   in pixels, of the surface (which may be less than the requested size if
+  //   PP_GRAPHICS3DATTRIB_LARGEST_SURFACE is PP_TRUE).
+  // PP_GRAPHICS3DATTRIB_RENDER_BUFFER: returns the buffer which client API
+  //   rendering is requested to use.
+  // PP_GRAPHICS3DATTRIB_MULTISAMPLE_RESOLVE: returns the filtering method used
+  //   when performing multi-sample buffer resolution. The filter may be either
+  //   PP_GRAPHICS3DATTRIBVALUE_MULTISAMPLE_RESOLVE_DEFAULT or
+  //   PP_GRAPHICS3DATTRIBVALUE_MULTISAMPLE_RESOLVE_BOX.
+  // PP_GRAPHICS3DATTRIB_SWAP_BEHAVIOR: describes the effect on the color
+  //   buffer when posting a surface with PPB_Surface3D_Dev::SwapBuffers.
+  //   Swap behavior may be either PP_GRAPHICS3DATTRIBVALUE_BUFFER_PRESERVED
+  //   or PP_GRAPHICS3DATTRIBVALUE_BUFFER_DESTROYED.
+  //
+  // If attribute is not a valid PPB_Surface3D_Dev surface attribute,
+  // then an PP_GRAPHICS3DERROR_BAD_ATTRIBUTE error is generated. If surface
+  // is not a valid PPB_Surface3D_Dev then an PP_GRAPHICS3DERROR_BAD_SURFACE
+  // error is generated.
+  int32_t (*GetAttrib)(PP_Resource surface,
+                       int32_t attribute,
+                       int32_t* value);
+
+  // 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 surface is not PP_GRAPHICS3DATTRIBVALUE_BUFFER_PRESERVED.
+  //
+  // If surface is bound as the draw surface of a context then SwapBuffers
+  // performs an implicit flush operation on the 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 surface,
+                         struct PP_CompletionCallback callback);
+};
+
+#endif  // PPAPI_C_DEV_PPB_SURFACE_3D_DEV_H_