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_ 194