New documentation for ppb_graphics_2d.h, graphics_2d.h, and image_data.h

Review URL: http://codereview.chromium.org/7054083

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@90276 0039d316-1c4b-4281-b951-d872f2087c98

2 files changed, 299 insertions, 34 deletions

diff --git a/ppapi/cpp/graphics_2d.h b/ppapi/cpp/graphics_2d.h
index 9d498e1..e14dcd2 100644
--- a/ppapi/cpp/graphics_2d.h
+++ b/ppapi/cpp/graphics_2d.h
@@ -1,4 +1,4 @@
-// Copyright (c) 2010 The Chromium Authors. All rights reserved.
+// 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.
 
@@ -9,6 +9,9 @@
 #include "ppapi/cpp/resource.h"
 #include "ppapi/cpp/size.h"
 
+
+/// @file
+/// This file defines the API to create a 2D graphics context in the browser.
 namespace pp {
 
 class CompletionCallback;
@@ -19,51 +22,229 @@ class Rect;
 
 class Graphics2D : public Resource {
  public:
-  // Creates an is_null() ImageData object.
+  /// Default constructor for creating an is_null() Graphics2D object.
   Graphics2D();
 
-  // The copied context will refer to the original (since this is just a wrapper
-  // around a refcounted resource).
+  /// A constructor accepting a reference to a Graphics2D graphics context
+  /// and converting it to a reference counted Graphics2D context. The
+  /// underlying 2D context is not copied; this constructor creates another
+  /// reference to the original 2D context.
+  ///
+  /// @param[in] other A pointer to a Graphics2D context.
   Graphics2D(const Graphics2D& other);
 
-  // Allocates a new 2D graphics context with the given size in the browser,
-  // resulting object will be is_null() if the allocation failed.
+  /// A constructor allocating a new 2D graphics context with the given size
+  /// in the browser, resulting object will be is_null() if the allocation
+  /// failed.
+  ///
+  /// @param[in] instance The module instance.
+  /// @param[in] size The size of the 2D graphics context in the browser,
+  /// measured in device pixels.
+  /// @param[in] is_always_opaque Set the is_always_opaque flag if you know
+  /// that you will be painting only opaque data to this context. This will
+  /// disable blending when compositing the plugin with the web page, which
+  /// might give higher performance on some computers.
+  /// If you set is_always_opaque, your alpha channel should always be set to
+  /// 0xFF or there may be painting artifacts. The alpha values overwrite
+  /// the destination alpha values without blending when
+  /// <code>is_always_opaque</code> is true.
   Graphics2D(Instance* instance, const Size& size, bool is_always_opaque);
 
+  /// A destructor that decrements the reference count of a Graphics2D object
+  /// made using the previous copy constructor. It is possible that the
+  /// destructor does not toally destroy the underlying 2D context if there
+  /// are outstanding references to it.
   virtual ~Graphics2D();
 
+
+  /// Assigns one 2D graphics context to this 2D graphics context. This
+  /// function increases the reference count of the 2D resource of
+  /// the other 2D graphics context while decrementing the reference counter
+  /// of this 2D graphics context.
+  ///
+  /// @param[in] other An other 2D graphics context.
+  /// @return A new Graphics2D context.
   Graphics2D& operator=(const Graphics2D& other);
 
+  /// Getter function for returning size of the 2D graphics context.
+  ///
+  /// @return The size of the 2D graphics context measured in device pixels.
   const Size& size() const { return size_; }
 
-  // Enqueues paint or scroll commands. THIS COMMAND HAS NO EFFECT UNTIL YOU
-  // CALL Flush().
-  //
-  // If you call the version with no source rect, the entire image will be
-  // painted.
-  //
-  // Please see PPB_Graphics2D.PaintImageData / .Scroll for more details.
+  /// This function enqueues a paint command of the given image into
+  /// the context. This command 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 provided image will be placed at <code>top_left</code> from the top
+  /// left of the context's internal backing store. This version of
+  /// PaintImageData paints the entire image. Refer to the other version of
+  /// this function to paint only part of the area.
+  ///
+  /// 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.
+  ///
+  /// There are two methods most modules will use for painting. The first
+  /// method is to generate a new ImageData and then paint it. In this case,
+  /// you'll set the location of your painting to <code>top_left</code> and
+  /// set <code>src_rect</code> to NULL. The second is that you're generating
+  /// small invalid regions out of a larger bitmap representing your entire
+  /// module's image.
+  ///
+  /// @param[in] image The ImageData to be painted.
+  /// @param[in] top_left A Point representing the top_left location where the
+  /// ImageData will be painted.
   void PaintImageData(const ImageData& image,
                       const Point& top_left);
+
+  /// This function enqueues a paint command of the given image into
+  /// the context. This command 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 provided image will be placed at <code>top_left</code> from the top
+  /// left of the context's internal backing store. Then the pixels contained
+  /// in <code>src_rect</code> will be copied into the backing store. This
+  /// means that the rectangle being painted will be at <code>src_rect</code>
+  /// offset by <code>top_left/code>.
+  ///
+  /// The <code>src_rect/code> 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 an empty <code>src_rect</code>.
+  ///
+  /// 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 methods most modules will use for painting. The first
+  /// method is to generate a new ImageData 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 module's image. The
+  /// second is that you're generating small invalid regions out of a larger
+  /// bitmap representing your entire module. In this case, you would set the
+  /// location of your image to (0,0) and then set <code>src_rect</code> to the
+  /// pixels you changed.
+  ///
+  /// @param[in] image The ImageData to be painted.
+  /// @param[in] top_left A Point representing the <code>top_left</code>
+  /// location where the ImageData will be painted.
+  /// @param[in] src_rect The rectangular area where the ImageData will
+  /// be painted.
   void PaintImageData(const ImageData& image,
                       const Point& top_left,
                       const Rect& src_rect);
+
+  /// This function enqueues a scroll of the context's backing store. This
+  /// function has no effect until you call Flush(). The data within the
+  /// provided clipping rectangle will be shifted by (dx, dy) pixels.
+  ///
+  /// This function will result in some exposed region which will have
+  /// undefined contents. The module should call PaintImageData() on
+  /// these exposed regions to give the correct contents.
+  ///
+  /// The scroll can be larger than the area of the clipping rectangle, which
+  /// means the current image will be scrolled out of the rectangle. This
+  /// scenario is not an error but will result in a no-op.
+  ///
+  /// @param[in] clip The clipping rectangle.
+  /// @param[in] amount The amount the area in the clipping rectangle will
+  /// shifted.
   void Scroll(const Rect& clip, const Point& amount);
 
-  // The browser will take ownership of the given image data. The object
-  // pointed to by the parameter will be cleared. To avoid horrible artifacts,
-  // you should also not use any other ImageData objects referring to the same
-  // resource will no longer be usable. THIS COMMAND HAS NO EFFECT UNTIL YOU
-  // CALL Flush().
-  //
-  // Please see PPB_Graphics2D.ReplaceContents for more details.
+  /// This function provides a slightly more efficient way to paint the entire
+  /// module's image. Normally, calling PaintImageData() requires that the
+  /// browser copy the pixels out of the image and into the graphics context's
+  /// backing store. This function replaces the graphics context's backing
+  /// store with the given image, avoiding the copy.
+  ///
+  /// The new image must be the exact same size as this graphics context. If
+  /// the new image uses a different image format than the browser's native
+  /// bitmap format (use ImageData::GetNativeImageDataFormat() to retrieve the
+  /// format), then a conversion will be done inside the browser which may slow
+  /// the performance a little bit.
+  ///
+  /// The new image will not be painted until you call Flush().
+  ///
+  /// Release your references to the image after a call to this function.
+  /// If you paint to the image after ReplaceContents(), there is the
+  /// possibility of significant painting artifacts because the page might use
+  /// partially-rendered data when copying out of the backing store.
+  ///
+  /// In the case of an animation, you will want to allocate a new image for
+  /// the next frame. It is best if you wait until the flush callback has
+  /// executed before allocating this bitmap. This gives the browser the option
+  /// of caching the previous backing store and handing it back to you
+  /// (assuming the sizes match). In the optimal case, this means no bitmaps are
+  /// allocated during the animation, and the backing store and "front buffer"
+  /// (which the module is painting into) are just being swapped back and forth.
+  ///
+  /// @param[in] image The ImageData to be painted.
   void ReplaceContents(ImageData* image);
 
-  // Flushes all the currently enqueued Paint, Scroll, and Replace commands.
-  // Can be used in synchronous mode (NULL callback pointer) from background
-  // threads.
-  //
-  // Please see PPB_Graphics2D.Flush for more details.
+
+  /// This function flushes any enqueued paint, scroll, and replace commands
+  /// for the backing store. This actually executes the updates, and causes a
+  /// repaint of the webpage, assuming this graphics context is bound to a
+  /// module instance.
+  ///
+  /// Flush() 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 when the image has been painted to the
+  /// screen. While you are waiting for a Flush callback, additional calls to
+  /// Flush() will fail.
+  ///
+  /// Because the callback is executed (or thread unblocked) only when the
+  /// module's image 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
+  /// flushing 2D graphics faster than the screen can be updated.
+  ///
+  /// <strong>Unbound contexts</strong>
+  /// If the context is not bound to a module instance, you will
+  /// still get a callback. The callback will execute after Flush() returns
+  /// to avoid reentrancy. The callback will not wait until anything is
+  /// painted to the screen because there will be nothing on the screen. The
+  /// timing of this callback is not guaranteed and may be deprioritized by
+  /// the browser because it is not affecting the user experience.
+  ///
+  /// <strong>Off-screen instances</strong>
+  /// If the context is bound to an instance that is
+  /// currently not visible (for example, scrolled out of view) it will
+  /// behave like the "unbound context" case.
+  ///
+  /// <strong>Detaching a context</strong>
+  /// If you detach a context from a module instance, any
+  /// pending flush callbacks will be converted into the "unbound context"
+  /// case.
+  ///
+  /// <strong>Released contexts</strong>
+  /// A callback may or may not still get called even if you have released all
+  /// of your references to the context. This can occur if there are internal
+  /// references to the context that means it has not been internally
+  /// destroyed (for example, if it is still bound to an instance) or due to
+  /// other implementation details. As a result, you should be careful to
+  /// check that flush callbacks are for the context you expect and that
+  /// you're capable of handling callbacks for context that you may have
+  /// released your reference to.
+  ///
+  /// <strong>Shutdown</strong>
+  /// If a plugin instance is removed when a Flush is pending, the
+  /// callback will not be executed.
+  ///
+  /// @param[in] cc A CompletionCallback to be called when the image has
+  /// been painted on the screen.
+  /// @return Returns PP_OK on succes or PP_Error_BadResource the graphics
+  /// context is invalid, PP_Error_BadArgument if the callback is null and
+  /// flush is being called from the main thread of the module, or
+  /// PP_Error_InProgress if a flush is already pending that has not issued
+  /// its callback yet.  In the failure case, nothing will be updated and
+  /// no callback will be scheduled.
+
+  /// TODO(darin): We should ensure that the completion callback always runs, so
+  /// that it is easier for consumers to manage memory referenced by a callback.
   int32_t Flush(const CompletionCallback& cc);
 
  private:
diff --git a/ppapi/cpp/image_data.h b/ppapi/cpp/image_data.h
index 673bcfc..682174d 100644
--- a/ppapi/cpp/image_data.h
+++ b/ppapi/cpp/image_data.h
@@ -10,6 +10,10 @@
 #include "ppapi/cpp/size.h"
 #include "ppapi/cpp/resource.h"
 
+
+/// @file
+/// This file defines the APIs for determining how a browser
+/// handles image data.
 namespace pp {
 
 class Instance;
@@ -17,39 +21,119 @@ class Plugin;
 
 class ImageData : public Resource {
  public:
-  // Creates an is_null() ImageData object.
+  /// Default constructor for creating an is_null() ImageData object.
   ImageData();
 
-  // This magic constructor is used when we've gotten a PP_Resource as a return
-  // value that has already been addref'ed for us.
+  /// A special structure used by the constructor that does not increment the
+  /// reference count of the underlying Image resource.
   struct PassRef {};
+
+  /// A constructor used when you have received a PP_Resource as a return
+  /// value that has already been reference counted.
+  ///
+  /// @param[in] resource A PP_Resource corresponding to image data.
   ImageData(PassRef, PP_Resource resource);
 
+  /// A constructor accepting a reference to an ImageData to increment the
+  /// reference count of the underlying Image resource. This constructor
+  /// produces an ImageData object that shares the underlying Image resource
+  /// with <code>other</code>.
+  ///
+  /// @param[in] other A pointer to an image data.
   ImageData(const ImageData& other);
 
-  // Allocates a new ImageData in the browser with the given parameters. The
-  // resulting object will be is_null() if the allocation failed.
+  /// A constructor that allocates a new ImageData in the browser with the
+  /// provided parameters.
+  /// The resulting object will be is_null() if the allocation failed.
+  ///
+  /// @param[in] instance A PP_Instance indentifying one instance of a module.
+  /// @param[in] format The desired image format.
+  /// PP_ImageDataFormat is an enumeration of the different types of
+  /// image data formats.
+  ///
+  /// The third part of each enumeration value describes the memory layout from
+  /// the lowest address to the highest. For example, BGRA means the B component
+  /// is stored in the lowest address, no matter what endianness the platform is
+  /// using.
+  ///
+  /// The PREMUL suffix implies pre-multiplied alpha is used. In this mode, the
+  /// red, green and blue color components of the pixel data supplied to an
+  /// image data should be pre-multiplied by their alpha value. For example:
+  /// starting with floating point color components, here is how to convert
+  /// them to 8-bit premultiplied components for image data:
+  ///    ...components of a pixel, floats ranging from 0 to 1...
+  ///    float red = 1.0f;
+  ///    float green = 0.50f;
+  ///    float blue = 0.0f;
+  ///    float alpha = 0.75f;
+  ///    ...components for image data are 8-bit values ranging from 0 to 255...
+  ///    uint8_t image_data_red_premul = (uint8_t)(red * alpha * 255.0f);
+  ///    uint8_t image_data_green_premul = (uint8_t)(green * alpha * 255.0f);
+  ///    uint8_t image_data_blue_premul = (uint8_t)(blue * alpha * 255.0f);
+  ///    uint8_t image_data_alpha_premul = (uint8_t)(alpha * 255.0f);
+  /// Note the resulting pre-multiplied red, green and blue components should
+  /// not be greater than the alpha value.
+  /// @param[in] size A pointer to a PP_Size containing the image size.
+  /// @param[in] init_to_zero A PP_Bool to determine transparency at creation.
+  /// Set the init_to_zero flag if you want the bitmap initialized to
+  /// transparent during the creation process. If this flag is not set, the
+  /// current contents of the bitmap will be undefined, and the plugin should
+  /// be sure to set all the pixels.
   ImageData(Instance* instance,
             PP_ImageDataFormat format,
             const Size& size,
             bool init_to_zero);
 
+  /// This function decrements the reference count of this ImageData and
+  /// increments the reference count of the <code>other</code> ImageData.
+  /// This ImageData shares the underlying image resource with
+  /// <code>other</code>.
+  ///
+  /// @param[in] other An other image data.
+  /// @return A new image data context.
   ImageData& operator=(const ImageData& other);
 
-  // Returns the browser's preferred format for images. Using this format
-  // guarantees no extra conversions will occur when painting.
+  /// This function determines the browser's preferred format for images.
+  /// Using this format guarantees no extra conversions will occur when
+  /// painting.
+  ///
+  /// @return PP_ImageDataFormat containing the preferred format.
   static PP_ImageDataFormat GetNativeImageDataFormat();
 
+  /// A getter function for returning the current format for images.
+  ///
+  /// @return PP_ImageDataFormat containing the preferred format.
   PP_ImageDataFormat format() const { return desc_.format; }
 
+  /// A getter function for returning the image size.
+  ///
+  /// @return The image size in pixels.
   pp::Size size() const { return desc_.size; }
+
+  /// A getter function for returning the row width in bytes.
+  ///
+  /// @return The row width in bytes.
   int32_t stride() const { return desc_.stride; }
 
+  /// A getter function for returning a raw pointer to the image pixels.
+  ///
+  /// @return A raw pointer to the image pixels.
   void* data() const { return data_; }
 
-  // Helper function to retrieve the address of the given pixel for 32-bit
-  // pixel formats.
+  /// This function is used retrieve the address of the given pixel for 32-bit
+  /// pixel formats.
+  ///
+  /// @param[in] coord A Point representing the x and y coordinates for a
+  /// specific pixel.
+  /// @return The address for the pixel.
   const uint32_t* GetAddr32(const Point& coord) const;
+
+  /// This function is used retrieve the address of the given pixel for 32-bit
+  /// pixel formats.
+  ///
+  /// @param[in] coord A Point representing the x and y coordinates for a
+  /// specific pixel.
+  /// @return The address for the pixel.
   uint32_t* GetAddr32(const Point& coord);
 
  private: