ppapi/cpp/graphics_3d.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef PPAPI_CPP_GRAPHICS_3D_H_
   6 #define PPAPI_CPP_GRAPHICS_3D_H_
   7
   8 #include "ppapi/c/ppb_graphics_3d.h"
   9 #include "ppapi/cpp/resource.h"
  10
  11 /// @file
  12 /// This file defines the API to create a 3D rendering context in the browser.
  13 namespace pp {
  14
  15 class CompletionCallback;
  16 class InstanceHandle;
  17
  18 /// This class represents a 3D rendering context in the browser.
  19 class Graphics3D : public Resource {
  20  public:
  21   /// Default constructor for creating an is_null() Graphics3D object.
  22   Graphics3D();
  23
  24   /// A constructor for creating and initializing a 3D rendering context.
  25   /// The returned context is created off-screen and must be attached
  26   /// to a module instance using <code>Instance::BindGraphics</code> to draw on
  27   /// the web page.
  28   ///
  29   /// @param[in] instance The instance with which this resource will be
  30   /// associated.
  31   ///
  32   /// @param[in] attrib_list The list of attributes (name=value pairs) for the
  33   /// context. The list is terminated with
  34   /// <code>PP_GRAPHICS3DATTRIB_NONE</code>. The <code>attrib_list</code> may
  35   /// be <code>NULL</code> or empty (first attribute is
  36   /// <code>PP_GRAPHICS3DATTRIB_NONE</code>). If an attribute is not specified
  37   /// in <code>attrib_list</code>, then the default value is used.
  38   ///
  39   /// Attributes are classified into two categories:
  40   ///
  41   /// 1. AtLeast: The attribute value in the returned context will meet or
  42   ///            exceed the value requested when creating the object.
  43   /// 2. Exact: The attribute value in the returned context is equal to
  44   ///          the value requested when creating the object.
  45   ///
  46   /// AtLeast attributes are (all have default values of 0):
  47   ///
  48   /// <code>PP_GRAPHICS3DATTRIB_ALPHA_SIZE</code>
  49   /// <code>PP_GRAPHICS3DATTRIB_BLUE_SIZE</code>
  50   /// <code>PP_GRAPHICS3DATTRIB_GREEN_SIZE</code>
  51   /// <code>PP_GRAPHICS3DATTRIB_RED_SIZE</code>
  52   /// <code>PP_GRAPHICS3DATTRIB_DEPTH_SIZE</code>
  53   /// <code>PP_GRAPHICS3DATTRIB_STENCIL_SIZE</code>
  54   /// <code>PP_GRAPHICS3DATTRIB_SAMPLES</code>
  55   /// <code>PP_GRAPHICS3DATTRIB_SAMPLE_BUFFERS</code>
  56   ///
  57   /// Exact attributes are:
  58   ///
  59   /// <code>PP_GRAPHICS3DATTRIB_WIDTH</code> Default 0
  60   /// <code>PP_GRAPHICS3DATTRIB_HEIGHT</code> Default 0
  61   /// <code>PP_GRAPHICS3DATTRIB_SWAP_BEHAVIOR</code>
  62   /// Default: Implementation defined.
  63   ///
  64   /// On failure, the object will be is_null().
  65   Graphics3D(const InstanceHandle& instance,
  66              const int32_t attrib_list[]);
  67
  68   /// A constructor for creating and initializing a 3D rendering context. The
  69   /// returned context is created off-screen. It must be attached to a
  70   /// module instance using <code>Instance::BindGraphics</code> to draw on the
  71   /// web page.
  72   ///
  73   /// This constructor is identical to the 2-argument version except that this
  74   /// version allows sharing of resources with another context.
  75   ///
  76   /// @param[in] instance The instance that will own the new Graphics3D.
  77   ///
  78   /// @param[in] share_context Specifies the context with which all
  79   /// shareable data will be shared. The shareable data is defined by the
  80   /// client API (note that for OpenGL and OpenGL ES, shareable data excludes
  81   /// texture objects named 0). An arbitrary number of Graphics3D resources
  82   /// can share data in this fashion.
  83   //
  84   /// @param[in] attrib_list The list of attributes for the context. See the
  85   /// 2-argument version of this constructor for more information.
  86   ///
  87   /// On failure, the object will be is_null().
  88   Graphics3D(const InstanceHandle& instance,
  89              const Graphics3D& share_context,
  90              const int32_t attrib_list[]);
  91
  92   /// Destructor.
  93   ~Graphics3D();
  94
  95   /// GetAttribs() retrieves the value for each attribute in
  96   /// <code>attrib_list</code>. The list has the same structure as described
  97   /// for the constructor. All attribute values specified in
  98   /// <code>pp_graphics_3d.h</code> can be retrieved.
  99   ///
 100   /// @param[in,out] attrib_list The list of attributes (name=value pairs) for
 101   /// the context. The list is terminated with
 102   /// <code>PP_GRAPHICS3DATTRIB_NONE</code>.
 103   ///
 104   /// The following error codes may be returned on failure:
 105   ///
 106   /// PP_ERROR_BADRESOURCE if context is invalid.
 107   /// PP_ERROR_BADARGUMENT if <code>attrib_list</code> is NULL or any attribute
 108   /// in the <code>attrib_list</code> is not a valid attribute.
 109   ///
 110   /// <strong>Example:</strong>
 111   ///
 112   /// @code
 113   /// int attrib_list[] = {PP_GRAPHICS3DATTRIB_RED_SIZE, 0,
 114   ///                      PP_GRAPHICS3DATTRIB_GREEN_SIZE, 0,
 115   ///                      PP_GRAPHICS3DATTRIB_BLUE_SIZE, 0,
 116   ///                      PP_GRAPHICS3DATTRIB_NONE};
 117   /// GetAttribs(context, attrib_list);
 118   /// int red_bits = attrib_list[1];
 119   /// int green_bits = attrib_list[3];
 120   /// int blue_bits = attrib_list[5];
 121   /// @endcode
 122   ///
 123   /// This example retrieves the values for rgb bits in the color buffer.
 124   int32_t GetAttribs(int32_t attrib_list[]) const;
 125
 126   /// SetAttribs() sets the values for each attribute in
 127   /// <code>attrib_list</code>. The list has the same structure as the list
 128   /// used in the constructors.
 129   ///
 130   /// Attributes that can be specified are:
 131   /// - PP_GRAPHICS3DATTRIB_SWAP_BEHAVIOR
 132   ///
 133   /// On failure the following error codes may be returned:
 134   /// - PP_ERROR_BADRESOURCE if context is invalid.
 135   /// - PP_ERROR_BADARGUMENT if attrib_list is NULL or any attribute in the
 136   ///   attrib_list is not a valid attribute.
 137   int32_t SetAttribs(const int32_t attrib_list[]);
 138
 139   /// ResizeBuffers() resizes the backing surface for the context.
 140   ///
 141   /// @param[in] width The width of the backing surface.
 142   /// @param[in] height The height of the backing surface.
 143   ///
 144   /// @return An int32_t containing <code>PP_ERROR_BADRESOURCE</code> if
 145   /// context is invalid or <code>PP_ERROR_BADARGUMENT</code> if the value
 146   /// specified for width or height is less than zero.
 147   /// <code>PP_ERROR_NOMEMORY</code> might be returned on the next
 148   /// SwapBuffers() callback if the surface could not be resized due to
 149   /// insufficient resources.
 150   int32_t ResizeBuffers(int32_t width, int32_t height);
 151
 152   /// SwapBuffers() makes the contents of the color buffer available for
 153   /// compositing. This function has no effect on off-screen surfaces: surfaces
 154   /// not bound to any module instance. The contents of ancillary buffers are
 155   /// always undefined after calling SwapBuffers(). The contents of the color
 156   /// buffer are undefined if the value of the
 157   /// <code>PP_GRAPHICS3DATTRIB_SWAP_BEHAVIOR</code> attribute of context is
 158   /// not <code>PP_GRAPHICS3DATTRIB_BUFFER_PRESERVED</code>.
 159   ///
 160   /// SwapBuffers() runs in asynchronous mode. Specify a callback function and
 161   /// the argument for that callback function. The callback function will be
 162   /// executed on the calling thread after the color buffer has been composited
 163   /// with rest of the html page. While you are waiting for a SwapBuffers()
 164   /// callback, additional calls to SwapBuffers() will fail.
 165   ///
 166   /// Because the callback is executed (or thread unblocked) only when the
 167   /// instance's current state is actually on the screen, this function
 168   /// provides a way to rate limit animations. By waiting until the image is on
 169   /// the screen before painting the next frame, you can ensure you're not
 170   /// generating updates faster than the screen can be updated.
 171   ///
 172   /// SwapBuffers() performs an implicit flush operation on context.
 173   /// If the context gets into an unrecoverable error condition while
 174   /// processing a command, the error code will be returned as the argument
 175   /// for the callback. The callback may return the following error codes:
 176   ///
 177   /// <code>PP_ERROR_NOMEMORY</code>
 178   /// <code>PP_ERROR_CONTEXT_LOST</code>
 179   ///
 180   /// Note that the same error code may also be obtained by calling GetError().
 181   ///
 182   /// param[in] cc A <code>CompletionCallback</code> to be called upon
 183   /// completion of SwapBuffers().
 184   ///
 185   /// @return An int32_t containing <code>PP_ERROR_BADRESOURCE</code> if
 186   /// context is invalid or <code>PP_ERROR_BADARGUMENT</code> if callback is
 187   /// invalid.
 188   int32_t SwapBuffers(const CompletionCallback& cc);
 189 };
 190
 191 }  // namespace pp
 192
 193 #endif  // PPAPI_CPP_GRAPHICS_3D_H_