Pin Chrome's shortcut to the Win10 Start menu on install and OS upgrade.
[chromium-blink-merge.git] / ppapi / cpp / graphics_3d.h
blob31af6877829a49f7021d0b230c17be83865f0e33
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.
5 #ifndef PPAPI_CPP_GRAPHICS_3D_H_
6 #define PPAPI_CPP_GRAPHICS_3D_H_
8 #include "ppapi/c/ppb_graphics_3d.h"
9 #include "ppapi/cpp/resource.h"
11 /// @file
12 /// This file defines the API to create a 3D rendering context in the browser.
13 namespace pp {
15 class CompletionCallback;
16 class InstanceHandle;
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();
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[]);
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.
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[]);
92 /// Destructor.
93 ~Graphics3D();
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>.
104 /// The following error codes may be returned on failure:
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.
110 /// <strong>Example:</strong>
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
123 /// This example retrieves the values for rgb bits in the color buffer.
124 int32_t GetAttribs(int32_t attrib_list[]) const;
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.
130 /// Attributes that can be specified are:
131 /// - PP_GRAPHICS3DATTRIB_SWAP_BEHAVIOR
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[]);
139 /// ResizeBuffers() resizes the backing surface for the context.
141 /// @param[in] width The width of the backing surface.
142 /// @param[in] height The height of the backing surface.
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);
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>.
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.
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.
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:
177 /// <code>PP_ERROR_NOMEMORY</code>
178 /// <code>PP_ERROR_CONTEXT_LOST</code>
180 /// Note that the same error code may also be obtained by calling GetError().
182 /// param[in] cc A <code>CompletionCallback</code> to be called upon
183 /// completion of SwapBuffers().
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);
191 } // namespace pp
193 #endif // PPAPI_CPP_GRAPHICS_3D_H_