OLD | NEW |
1 .. _devguide-coding-3D-graphics: | 1 .. _devguide-coding-3D-graphics: |
2 | 2 |
3 ########### | 3 ########### |
4 3D Graphics | 4 3D Graphics |
5 ########### | 5 ########### |
6 | 6 |
7 Native Client applications use the `OpenGL ES 2.0 | 7 Native Client applications use the `OpenGL ES 2.0 |
8 <http://en.wikipedia.org/wiki/OpenGL_ES>`_ API for 3D rendering. This document | 8 <http://en.wikipedia.org/wiki/OpenGL_ES>`_ API for 3D rendering. This document |
9 describes how to call the OpenGL ES 2.0 interface in a Native Client module and | 9 describes how to call the OpenGL ES 2.0 interface in a Native Client module and |
10 how to build an efficient rendering loop. It also explains how to validate GPU | 10 how to build an efficient rendering loop. It also explains how to validate GPU |
(...skipping 101 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
112 ``glGetIntegerv(GL_MAX_VERTEX_TEXTURE_IMAGE_UNITS, ...)`` and | 112 ``glGetIntegerv(GL_MAX_VERTEX_TEXTURE_IMAGE_UNITS, ...)`` and |
113 ``glGetIntegerv(GL_MAX_TEXTURE_SIZE, ...)`` return values greater than 0. | 113 ``glGetIntegerv(GL_MAX_TEXTURE_SIZE, ...)`` return values greater than 0. |
114 | 114 |
115 * If you are using more than 8 textures in a single shader, make sure | 115 * If you are using more than 8 textures in a single shader, make sure |
116 ``glGetIntegerv(GL_MAX_TEXTURE_IMAGE_UNITS, ...)`` returns a value greater | 116 ``glGetIntegerv(GL_MAX_TEXTURE_IMAGE_UNITS, ...)`` returns a value greater |
117 than or equal to the number of simultaneous textures you need. | 117 than or equal to the number of simultaneous textures you need. |
118 | 118 |
119 Vetting the driver in the Chrome Web Store | 119 Vetting the driver in the Chrome Web Store |
120 ------------------------------------------ | 120 ------------------------------------------ |
121 | 121 |
122 If you choose to place your application in the `Chrome Web | 122 If you choose to place your application in the `Chrome Web Store </webstore>`_, |
123 Store <https://developers.google.com/chrome/web-store/docs/>`_, its Web Store | 123 its Web Store `manifest file </extensions/manifest>`_ can include the ``webgl`` |
124 `manifest file <http://code.google.com/chrome/extensions/manifest.html>`_ can | 124 feature in the requirements parameter. It looks like this: |
125 include the ``webgl`` feature in the requirements parameter. It looks like this: | |
126 | 125 |
127 .. naclcode:: | 126 .. naclcode:: |
128 | 127 |
129 "requirements": { | 128 "requirements": { |
130 "3D": { | 129 "3D": { |
131 "features": ["webgl"] | 130 "features": ["webgl"] |
132 } | 131 } |
133 } | 132 } |
134 | 133 |
135 While WebGL is technically a JavaScript API, specifying the ``webgl`` feature | 134 While WebGL is technically a JavaScript API, specifying the ``webgl`` feature |
136 also works for OpenGL ES 2.0 because both interfaces use the same driver. | 135 also works for OpenGL ES 2.0 because both interfaces use the same driver. |
137 | 136 |
138 This manifest item is not required, but if you include it, the Chrome Web Store | 137 This manifest item is not required, but if you include it, the Chrome Web Store |
139 will prevent a user from installing the application if the browser is running on | 138 will prevent a user from installing the application if the browser is running on |
140 a machine that does not support OpenGL ES 2.0 or that is using a known | 139 a machine that does not support OpenGL ES 2.0 or that is using a known |
141 blacklisted GPU driver that could invite an attack. | 140 blacklisted GPU driver that could invite an attack. |
142 | 141 |
143 If the Web Store determines that the user's driver is deficient, the app won't | 142 If the Web Store determines that the user's driver is deficient, the app won't |
144 appear on the store's tile display. However, it will appear in store search | 143 appear on the store's tile display. However, it will appear in store search |
145 results or if the user links to it directly, in which case the user could still | 144 results or if the user links to it directly, in which case the user could still |
146 download it. But the manifest requirements will be checked when the user reaches | 145 download it. But the manifest requirements will be checked when the user reaches |
147 the install page, and if there is a problem, the browser will display the | 146 the install page, and if there is a problem, the browser will display the |
148 message "This application is not supported on this computer. Installation has | 147 message "This application is not supported on this computer. Installation has |
149 been disabled." | 148 been disabled." |
150 | 149 |
151 The manifest-based check applies only to downloads directly from the Chrome Web | 150 The manifest-based check applies only to downloads directly from the Chrome Web |
152 Store. It is not performed when an application is loaded via `inline | 151 Store. It is not performed when an application is loaded via `inline |
153 installation | 152 installation </webstore/inline_installation>`_. |
154 <https://developers.google.com/chrome/web-store/docs/inline_installation>`_. | |
155 | 153 |
156 What to do when there are problems | 154 What to do when there are problems |
157 ---------------------------------- | 155 ---------------------------------- |
158 | 156 |
159 Using the vetting procedure described above, you should be able to detect the | 157 Using the vetting procedure described above, you should be able to detect the |
160 most common problems before your application runs. If there are problems, your | 158 most common problems before your application runs. If there are problems, your |
161 code should describe the issue as clearly as possible. That's easy if there is a | 159 code should describe the issue as clearly as possible. That's easy if there is a |
162 missing feature. Failure to create a graphics context is tougher to diagnose. At | 160 missing feature. Failure to create a graphics context is tougher to diagnose. At |
163 the very least, you can suggest that the user try to update the driver. You | 161 the very least, you can suggest that the user try to update the driver. You |
164 might want to linke to the Chrome page that describes `how to do updates | 162 might want to linke to the Chrome page that describes `how to do updates |
(...skipping 91 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
256 supports many versions of OpenGL. Regal recently added support for Native | 254 supports many versions of OpenGL. Regal recently added support for Native |
257 Client. Regal forwards most OpenGL calls directly to the underlying graphics | 255 Client. Regal forwards most OpenGL calls directly to the underlying graphics |
258 library, but it can also emulate other calls that are not included (when | 256 library, but it can also emulate other calls that are not included (when |
259 hardware support exists). See `libregal | 257 hardware support exists). See `libregal |
260 <http://www.altdevblogaday.com/2012/09/04/bringing-regal-opengl-to-native-client
/>`_ | 258 <http://www.altdevblogaday.com/2012/09/04/bringing-regal-opengl-to-native-client
/>`_ |
261 for more info. | 259 for more info. |
262 | 260 |
263 Use the Pepper API | 261 Use the Pepper API |
264 ------------------ | 262 ------------------ |
265 | 263 |
266 Your code can call the Pepper `PPB_OpenGLES2 | 264 Your code can call the Pepper PPB_OpenGLES2 API directly, as with any Pepper |
267 <https://developers.google.com/native-client/pepperc/struct_p_p_b___open_g_l_e_s
2>`_ | 265 interface. When you write in this way, each invocation of an OpenGL ES 2.0 |
268 API directly, as with any Pepper interface. When you write in this way, each | 266 function must begin with a reference to the Pepper interface, and the first |
269 invocation of an OpenGL ES 2.0 function must begin with a reference to the | 267 argument is the graphics context. To invoke the function ``glCompileShader``, |
270 Pepper interface, and the first argument is the graphics context. To invoke the | 268 your code might look like: |
271 function ``glCompileShader``, your code might look like: | |
272 | 269 |
273 .. naclcode:: | 270 .. naclcode:: |
274 | 271 |
275 ppb_g3d_interface->CompileShader(graphicsContext, shader); | 272 ppb_g3d_interface->CompileShader(graphicsContext, shader); |
276 | 273 |
277 This approach specifically targets the Pepper APIs. Each call corresponds to a | 274 This approach specifically targets the Pepper APIs. Each call corresponds to a |
278 OpenGL ES 2.0 function, but the syntax is unique to Native Client, so the source | 275 OpenGL ES 2.0 function, but the syntax is unique to Native Client, so the source |
279 file is not portable. | 276 file is not portable. |
280 | 277 |
281 Implementing a rendering loop | 278 Implementing a rendering loop |
(...skipping 13 matching lines...) Expand all Loading... |
295 a new, separate sandboxed process. The module's process has its own main thread | 292 a new, separate sandboxed process. The module's process has its own main thread |
296 (the Native Client thread). The Chrome and Native Client processes communicate | 293 (the Native Client thread). The Chrome and Native Client processes communicate |
297 with each other using Pepper API calls on their main threads. | 294 with each other using Pepper API calls on their main threads. |
298 | 295 |
299 When the Chrome main thread calls the Native Client thread (keyboard and mouse | 296 When the Chrome main thread calls the Native Client thread (keyboard and mouse |
300 callbacks, for example), the Chrome main thread will block. This means that | 297 callbacks, for example), the Chrome main thread will block. This means that |
301 lengthy operations on the Native Client thread can steal cycles from Chrome, and | 298 lengthy operations on the Native Client thread can steal cycles from Chrome, and |
302 performing blocking operations on the Native Client thread can bring your app to | 299 performing blocking operations on the Native Client thread can bring your app to |
303 a standstill. | 300 a standstill. |
304 | 301 |
305 Native Client uses callback functions to synchronize the main threads of the two | 302 Native Client uses callback functions to synchronize the main threads of the |
306 processes. Only certain Pepper functions use callbacks; `SwapBuffers | 303 two processes. Only certain Pepper functions use callbacks; `SwapBuffers |
307 <https://developers.google.com/native-client/pepperc/struct_p_p_b___graphics3_d_
_1__0#a293c6941c0da084267ffba3954793497>`_ | 304 </native-client/pepper_stable/c/struct_p_p_b___graphics3_d__1__0#a293c6941c0da08
4267ffba3954793497>`_ |
308 is one. | 305 is one. |
309 | 306 |
310 ``SwapBuffers`` and its callback function | 307 ``SwapBuffers`` and its callback function |
311 ----------------------------------------- | 308 ----------------------------------------- |
312 | 309 |
313 ``SwapBuffers`` is non-blocking; it is called from the Native Client thread and | 310 ``SwapBuffers`` is non-blocking; it is called from the Native Client thread and |
314 returns immediately. When ``SwapBuffers`` is called, it runs asynchronously on | 311 returns immediately. When ``SwapBuffers`` is called, it runs asynchronously on |
315 the Chrome main thread. It switches the graphics data buffers, handles any | 312 the Chrome main thread. It switches the graphics data buffers, handles any |
316 needed compositing operations, and redraws the screen. When the screen update is | 313 needed compositing operations, and redraws the screen. When the screen update is |
317 complete, the callback function that was included as one of ``SwapBuffer``'s | 314 complete, the callback function that was included as one of ``SwapBuffer``'s |
(...skipping 206 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
524 * **Don't read data from the GPU.** Don't call ``glReadPixels``, as it is slow. | 521 * **Don't read data from the GPU.** Don't call ``glReadPixels``, as it is slow. |
525 | 522 |
526 * **Don't update a small portion of a large buffer.** In the current OpenGL ES | 523 * **Don't update a small portion of a large buffer.** In the current OpenGL ES |
527 2.0 implementation when you update a portion of a buffer (with | 524 2.0 implementation when you update a portion of a buffer (with |
528 ``glSubBufferData`` for example) the entire buffer must be reprocessed. To | 525 ``glSubBufferData`` for example) the entire buffer must be reprocessed. To |
529 avoid this problem, keep static and dynamic data in different buffers. | 526 avoid this problem, keep static and dynamic data in different buffers. |
530 | 527 |
531 * **Don't call ``glDisable(GL_TEXTURE_2D)``.** This is an OpenGL ES 2.0 | 528 * **Don't call ``glDisable(GL_TEXTURE_2D)``.** This is an OpenGL ES 2.0 |
532 error. Each time it is called, an error messages will appear in Chrome's | 529 error. Each time it is called, an error messages will appear in Chrome's |
533 ``about:gpu`` tab. | 530 ``about:gpu`` tab. |
OLD | NEW |