Clarify the behavior of PaintImageData.

ppapi/c/ppb_graphics_2d.h

 /* Copyright (c) 2010 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_C_PPB_GRAPHICS_2D_H_
 #define PPAPI_C_PPB_GRAPHICS_2D_H_
 
 #include "ppapi/c/pp_bool.h"
 #include "ppapi/c/pp_instance.h"
 #include "ppapi/c/pp_module.h"
@@ skipping 53 matching lines @@
                       struct PP_Size* size,
                       PP_Bool* is_always_opqaue);
 
   /**
    * Enqueues a paint of the given image into the context. THIS HAS NO EFFECT
    * UNTIL YOU CALL Flush(). As a result, what counts is the contents of the
    * bitmap when you call Flush, not when you call this function.
    *
    * The given image will be placed at |top_left| from the top left of the
    * context's internal backing store. Then the src_rect will be copied into the
-   * backing store. This parameter may not be NULL.
+   * backing store. This parameter may not be NULL. This means that the
+   * rectangle being painted will be at src_rect offset by top_left.
    *
    * The src_rect is specified in the coordinate system of the image being
    * painted, not the context. For the common case of copying the entire image,
    * you may specify a NULL |src_rect| pointer. If you are frequently updating
    * the entire image, consider using ReplaceContents which will give slightly
    * higher performance.
    *
    * The painted area of the source bitmap must fall entirely within the
    * context. Attempting to paint outside of the context will result in an
    * error. However, the source bitmap may fall outside the context, as long
    * as the src_rect subset of it falls entirely within the context.
+   *
+   * There are two modes most plugins may use for painting. The first is
+   * that you will generate a new ImageData (possibly representing a subset of
+   * your plugin) and then paint it. In this case, you'll set the location of
+   * your painting to top_left and set src_rect to NULL. The second is that
+   * you're generating small invalid regions out of a larger bitmap
+   * representing your entire plugin. In this case, you would set the location
+   * of your image to (0,0) and then set src_rect to the pixels you changed.
    */
   void (*PaintImageData)(PP_Resource graphics_2d,
                          PP_Resource image_data,
                          const struct PP_Point* top_left,
                          const struct PP_Rect* src_rect);
 
   /**
    * Enqueues a scroll of the context's backing store. THIS HAS NO EFFECT UNTIL
    * YOU CALL Flush(). The data within the given clip rect (you may specify
    * NULL to scroll the entire region) will be shifted by (dx, dy) pixels.
@@ skipping 119 matching lines @@
   int32_t (*Flush)(PP_Resource graphics_2d,
                    struct PP_CompletionCallback callback);
 
 };
 
 /**
  * @}
  */
 #endif  /* PPAPI_C_PPB_GRAPHICS_2D_H_ */