diff options
Diffstat (limited to 'ppapi')
| -rw-r--r-- | ppapi/cpp/graphics_2d.h | 231 | ||||
| -rw-r--r-- | ppapi/cpp/image_data.h | 102 |
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: |