3D Graphics

Vetting the driver in JavaScript

At startup, the application should perform a few additional tests that can be implemented in JavaScript on its hosting web page. The script that performs these tests should be included before the module’s embed tag, and ideally the embed tag should appear on the hosting page only if these tests succeed.

The first thing to check is whether you can create a graphics context. If you can, use the context to confirm the existence of any required OpenGL ES 2.0 extensions. You may want to refer to the extension registry and include vendor prefixes when checking for extensions.

Vetting the driver in Native Client

Vetting the driver in the Chrome Web Store

If you choose to place your application in the Chrome Web Store, its Web Store manifest file can include the webgl feature in the requirements parameter. It looks like this:

"requirements": {
  "3D": {
    "features": ["webgl"]
  }
}

While WebGL is technically a JavaScript API, specifying the webgl feature also works for OpenGL ES 2.0 because both interfaces use the same driver.

This manifest item is not required, but if you include it, the Chrome Web Store will prevent a user from installing the application if the browser is running on a machine that does not support OpenGL ES 2.0 or that is using a known blacklisted GPU driver that could invite an attack.

If the Web Store determines that the user’s driver is deficient, the app won’t appear on the store’s tile display. However, it will appear in store search results or if the user links to it directly, in which case the user could still download it. But the manifest requirements will be checked when the user reaches the install page, and if there is a problem, the browser will display the message “This application is not supported on this computer. Installation has been disabled.”

The manifest-based check applies only to downloads directly from the Chrome Web Store. It is not performed when an application is loaded via inline installation.

What to do when there are problems

Using the vetting procedure described above, you should be able to detect the most common problems before your application runs. If there are problems, your code should describe the issue as clearly as possible. That’s easy if there is a missing feature. Failure to create a graphics context is tougher to diagnose. At the very least, you can suggest that the user try to update the driver. You might want to linke to the Chrome page that describes how to do updates.

If a user can’t update the driver, or their problem persists, be sure to gather information about their graphics environment. Ask for the contents of the Chrome about:gpu page.

Document unreliable drivers

It can be helpful to include information about known dubious drivers in your user documentation. This might help identify if a rogue driver is the cause of a problem. There are many sources of GPU driver blacklists. Two such lists can be found at the Chromium project and Khronos. You can use these lists to include information in your documentation that warns users about dangerous drivers.

Test your defenses

You can test your driver validation code by running Chrome with the following flags (all at once) and watching how your application responds:

• --disable-webgl
• --disable-pepper-3d
• --disable-gl-multisampling
• --disable-accelerated-compositing
• --disable-accelerated-2d-canvas

Use “pure” OpenGL ES 2.0 function calls

You can make OpenGL ES 2.0 calls through a Pepper extension library. The SDK example examples/api/graphics_3d works this way. In the file graphics_3d.cc, the key initialization steps are as follows:

• Add these includes at the top of the file:

  #include <GLES2/gl2.h>
  #include "ppapi/lib/gl/gles2/gl2ext_ppapi.h"
  

• Define the function InitGL. The exact specification of attrib_list will be application specific.

  bool InitGL(int32_t new_width, int32_t new_height) {
    if (!glInitializePPAPI(pp::Module::Get()->get_browser_interface())) {
      fprintf(stderr, "Unable to initialize GL PPAPI!\n");
      return false;
    }
  
    const int32_t attrib_list[] = {
      PP_GRAPHICS3DATTRIB_ALPHA_SIZE, 8,
      PP_GRAPHICS3DATTRIB_DEPTH_SIZE, 24,
      PP_GRAPHICS3DATTRIB_WIDTH, new_width,
      PP_GRAPHICS3DATTRIB_HEIGHT, new_height,
      PP_GRAPHICS3DATTRIB_NONE
    };
  
    context_ = pp::Graphics3D(this, attrib_list);
    if (!BindGraphics(context_)) {
      fprintf(stderr, "Unable to bind 3d context!\n");
      context_ = pp::Graphics3D();
      glSetCurrentContextPPAPI(0);
      return false;
    }
  
    glSetCurrentContextPPAPI(context_.pp_resource());
    return true;
  }
  

• Include logic in Instance::DidChangeView to call InitGL whenever necessary: upon application launch (when the graphics context is NULL) and whenever the module’s View changes size.

Use Regal

If you are porting an OpenGL ES 2.0 application, or are comfortable writing in OpenGL ES 2.0, you should stick with the Pepper APIs or pure OpenGL ES 2.0 calls described above. If you are porting an application that uses features not in OpenGL ES 2.0, consider using Regal. Regal is an open source library that supports many versions of OpenGL. Regal recently added support for Native Client. Regal forwards most OpenGL calls directly to the underlying graphics library, but it can also emulate other calls that are not included (when hardware support exists). See libregal for more info.

Use the Pepper API

Your code can call the Pepper PPB_OpenGLES2 API directly, as with any Pepper interface. When you write in this way, each invocation of an OpenGL ES 2.0 function must begin with a reference to the Pepper interface, and the first argument is the graphics context. To invoke the function glCompileShader, your code might look like:

ppb_g3d_interface->CompileShader(graphicsContext, shader);

This approach specifically targets the Pepper APIs. Each call corresponds to a OpenGL ES 2.0 function, but the syntax is unique to Native Client, so the source file is not portable.

The Chrome and Native Client processes

Chrome is a multi-process browser. Each Chrome tab is a separate process that is running an application with its own main thread (we’ll call it the Chrome main thread). When an application launches a Native Client module, the module runs in a new, separate sandboxed process. The module’s process has its own main thread (the Native Client thread). The Chrome and Native Client processes communicate with each other using Pepper API calls on their main threads.

When the Chrome main thread calls the Native Client thread (keyboard and mouse callbacks, for example), the Chrome main thread will block. This means that lengthy operations on the Native Client thread can steal cycles from Chrome, and performing blocking operations on the Native Client thread can bring your app to a standstill.

Native Client uses callback functions to synchronize the main threads of the two processes. Only certain Pepper functions use callbacks; SwapBuffers is one.

SwapBuffers and its callback function

SwapBuffers is non-blocking; it is called from the Native Client thread and returns immediately. When SwapBuffers is called, it runs asynchronously on the Chrome main thread. It switches the graphics data buffers, handles any needed compositing operations, and redraws the screen. When the screen update is complete, the callback function that was included as one of SwapBuffer‘s arguments will be called from the Chrome thread and executed on the Native Client thread.

To create a rendering loop, your Native Client module should include a function that does the rendering work and then executes SwapBuffers, passing itself as the SwapBuffer callback. If your rendering code is efficient and runs quickly, this scheme will achieve the highest frame rate possible. The documentation for SwapBuffers explains why this is optimal: because the callback is executed only when the plugin’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.

The following diagram illustrates the interaction between the Chrome and Native Client processes. The application-specific rendering code runs in the function called Draw on the Native Client thread. Blue down-arrows are blocking calls from the main thread to Native Client, green up-arrows are non-blocking SwapBuffers calls from Native Client to the main thread. All OpenGL ES 2.0 calls are made from Draw in the Native Client thread.

SDK example graphics_3d

The SDK example graphics_3d uses the function MainLoop (in hello_world.cc) to create a rendering loop as described above. MainLoop calls Render to do the rendering work, and then invokes SwapBuffers, passing itself as the callback.

void MainLoop(void* foo, int bar) {
  if (g_LoadCnt == 3) {
    InitProgram();
    g_LoadCnt++;
  }
  if (g_LoadCnt > 3) {
    Render();
    PP_CompletionCallback cc = PP_MakeCompletionCallback(MainLoop, 0);
    ppb_g3d_interface->SwapBuffers(g_context, cc);
  } else {
    PP_CompletionCallback cc = PP_MakeCompletionCallback(MainLoop, 0);
    ppb_core_interface->CallOnMainThread(0, cc, 0);
  }
}

Handling tab activation from the main thread

You can detect and respond to the activation or deactivation of a tab with JavaScript on your hosting page. Add an EventListener for visibilitychange that sends a message to the Native Client module, as in this example:

document.addEventListener('visibilitychange', function(){
  if (document.hidden) {
    // PostMessage to your Native Client module
    document.nacl_module.postMessage('INACTIVE');
  } else {
    // PostMessage to your Native Client module
    document.nacl_module.postMessage('ACTIVE');
  }

}, false);

Handling tab activation from the Native Client thread

You can also detect and respond to the activation or deactivation of a tab directly from your Native Client module by including code in the function pp::Instance::DidChangeView, which is called whenever a change in the module’s view occurs. The code can call ppb::View::IsPageVisible to determine if the page is visible or not. The most common cause of invisible pages is that the page is in a background tab.

Do’s

• Make sure to enable attrib 0. OpenGL requires that you enable attrib 0, but OpenGL ES 2.0 does not. For example, you can define a vertex shader with 2 attributes, numbered like this:

  glBindAttribLocation(program, "positions", 1);
  glBindAttribLocation(program, "normals", 2);
  

  In this case the shader is not using attrib 0 and Chrome may have to perform some additional work if it is emulating OpenGL ES 2.0 on top of OpenGL. It’s always more efficient to enable attrib 0, even if you do not use it.

• Check how shaders compile. Shaders can compile differently on different systems, which can result in glGetAttrib* functions returning different results. Be sure that the vertex attribute indices match the corresponding name each time you recompile a shader.
• Update indices sparingly. For security reasons, all indices must be validated. If you change indices, Native Client will validate them again. Structure your code so indices are not updated often.
• Use a smaller plugin and let CSS scale it. If you’re running into fillrate issues, it may be beneficial to perform scaling via CSS. The size your plugin renders is determined by the width and height attributes of the <embed> element for the module. The actual size displayed on the web page is controlled by the CSS styles applied to the element.
• Avoid matrix-to-matrix conversions. With some versions of Mac OS, there is a driver problem when compiling shaders. If you get compiler errors for matrix transforms, avoid matrix-to-matrix conversions. For instance, upres a vec3 to a vec4 before transforming it by a mat4, rather than converting the mat4 to a mat3.

Don’ts

• Don’t use client side buffers. OpenGL ES 2.0 can use client side data with glVertexAttribPointer and glDrawElements, but this is really slow. Try to avoid client side buffers. Use Vertex Buffer Objects (VBOs) instead.
• Don’t mix vertex data and index data. By default, Pepper 3D binds buffers to a single point. You could create a buffer and bind it to both GL_ARRAY_BUFFER and GL_ELEMENT_ARRAY_BUFFER, but that would be expensive overhead and it is not recommended.
• Don’t call ``glGet*`` or ``glCheck*`` during rendering. This is normal advice for OpenGL programs, but is particularly important for 3D on Chrome. Calls to any OpenGL ES 2.0 function whose name begins with these strings blocks the Native Client thread. This includes glGetError; avoid calling it in release builds.
• Don’t use fixed point (``GL_FIXED``) vertex attributes. Fixed point attributes are not supported in OpenGL ES 2.0, so emulating them in OpenGL ES 2.0 is slow. By default, GL_FIXED support is turned off in the Pepper 3D API.
• Don’t read data from the GPU. Don’t call glReadPixels, as it is slow.
• Don’t update a small portion of a large buffer. In the current OpenGL ES 2.0 implementation when you update a portion of a buffer (with glSubBufferData for example) the entire buffer must be reprocessed. To avoid this problem, keep static and dynamic data in different buffers.
• Don’t call ``glDisable(GL_TEXTURE_2D)``. This is an OpenGL ES 2.0 error. Each time it is called, an error messages will appear in Chrome’s about:gpu tab.