Clarify the byte ordering and premultiplied-ness of the Pepper 2D data....

third_party/npapi/bindings/npapi_extensions.h

 /* Copyright (c) 2006-2009 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 _NP_EXTENSIONS_H_
 #define _NP_EXTENSIONS_H_
 
 #include "third_party/npapi/bindings/npapi.h"
 
@@ skipping 213 matching lines @@
 
 /* 2D -----------------------------------------------------------------------*/
 
 #define NPPepper2DDevice 1
 
 typedef struct _NPDeviceContext2DConfig {
 } NPDeviceContext2DConfig;
 
 typedef struct _NPDeviceContext2D
 {
+  /* Internal value used by the browser to identify this device.
+   */
   void* reserved;
+
+  /* A pointer to the pixel data. This data is 8-bit values in BGRA order in
+   * memory. Each row will start |stride| bytes after the previous one.
+   *
+   * THIS DATA USES PREMULTIPLIED ALPHA. This means that each color channel has
+   * been multiplied with the corresponding alpha, which makes compositing
+   * easier. If any color channels have a value greater than the alpha value,
+   * you'll likely get crazy colors and weird artifacts.
+   */
   void* region;
+
+  /* Length of each row of pixels in bytes. This may be larger than width * 4
+   * if there is padding at the end of each row to help with alignment.
+   */
   int32 stride;
 
   /* The dirty region that the plugin has painted into the buffer. This
    * will be initialized to the size of the plugin image in
    * initializeContextPtr. The plugin can change the values to only
    * update portions of the image.
    */
   struct {
     int32 left;
     int32 top;
@@ skipping 33 matching lines @@
   int32 commandBufferEntries;
 
   // Offset in command buffer reader has reached. Synchronized on flush.
   int32 getOffset;
 
   // Offset in command buffer writer has reached. Synchronized on flush.
   int32 putOffset;
 } NPDeviceContext3D;
 
 #endif  /* _NP_EXTENSIONS_H_ */