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