Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 | |
Torne (Richard Coles) | c2e0dbd | 2013-05-09 18:35:53 +0100 | [diff] [blame] | 24 | /// A constructor for creating and initializing a 3D rendering context. |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 | /// |
Torne (Richard Coles) | c2e0dbd | 2013-05-09 18:35:53 +0100 | [diff] [blame] | 112 | /// @code |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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]; |
Torne (Richard Coles) | c2e0dbd | 2013-05-09 18:35:53 +0100 | [diff] [blame] | 121 | /// @endcode |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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_ |