diff options
Diffstat (limited to 'ppapi/c/ppb_image_data.h')
| -rw-r--r-- | ppapi/c/ppb_image_data.h | 94 |
1 files changed, 73 insertions, 21 deletions
diff --git a/ppapi/c/ppb_image_data.h b/ppapi/c/ppb_image_data.h index c9c6f99..bc014d4 100644 --- a/ppapi/c/ppb_image_data.h +++ b/ppapi/c/ppb_image_data.h @@ -15,7 +15,8 @@ /** * @file - * Defines the API ... + * This file defines the PPB_ImageData struct for determining how a browser + * handles image data. */ /** @@ -23,6 +24,10 @@ * @{ */ +/** + * PP_ImageDataFormat is an enumeration of the different types of + * image data formats. + */ typedef enum { PP_IMAGEDATAFORMAT_BGRA_PREMUL, PP_IMAGEDATAFORMAT_RGBA_PREMUL @@ -36,14 +41,24 @@ PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_ImageDataFormat, 4); * @addtogroup Structs * @{ */ + +/** + * The PP_ImageDataDesc structure represents a description of image data. + */ struct PP_ImageDataDesc { + + /** + * This value represents one of the image data types in the + * PP_ImageDataFormat enum. + */ PP_ImageDataFormat format; - /** Size of the bitmap in pixels. */ + /** This value represents the size of the bitmap in pixels. */ struct PP_Size size; - /** The row width in bytes. This may be different than width * 4 since there - * may be padding at the end of the lines. + /** + * This value represents the row width in bytes. This may be different than + * width * 4 since there may be padding at the end of the lines. */ int32_t stride; }; @@ -58,33 +73,51 @@ PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_ImageDataDesc, 16); * @addtogroup Interfaces * @{ */ + +/** + * The PPB_ImageData interface contains pointers to several functions for + * determining the browser's treatment of image data. + */ struct PPB_ImageData { /** - * Returns the browser's preferred format for image data. This format will be - * the format is uses internally for painting. Other formats may require - * internal conversions to paint or may have additional restrictions depending - * on the function. + * GetNativeImageDataFormat is a pointer to a function that returns the + * browser's preferred format for image data. The browser uses this format + * internally for painting. Other formats may require internal conversions + * to paint or may have additional restrictions depending on the function. + * + * @return PP_ImageDataFormat containing the preferred format. */ PP_ImageDataFormat (*GetNativeImageDataFormat)(); /** - * Returns PP_TRUE if the given image data format is supported by the browser. + * IsImageDataFormatSupported is a pointer to a function that determines if + * the given image data format is supported by the browser. + * + * @param[in] format The image data format. + * @return PP_Bool with PP_TRUE if the given image data format is supported + * by the browser. */ PP_Bool (*IsImageDataFormatSupported)(PP_ImageDataFormat format); /** - * Allocates an image data resource with the given format and size. The - * return value will have a nonzero ID on success, or zero on failure. - * Failure means the instance, image size, or format was invalid. + * Create is a pointer to a function that allocates an image data resource + * with the given format and size. * + * For security reasons, if uninitialized, the bitmap will not contain random + * memory, but may contain data from a previous image produced by the same + * plugin if the bitmap was cached and re-used. + * + * @param[in] instance A PP_Instance indentifying one instance of a module. + * @param[in] format The desired image data format. + * @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. * - * For security reasons, if uninitialized, the bitmap will not contain random - * memory, but may contain data from a previous image produced by the same - * plugin if the bitmap was cached and re-used. + * @return A PP_Resource with a nonzero ID on succes or zero on failure. + * Failure means the instance, image size, or format was invalid. */ PP_Resource (*Create)(PP_Instance instance, PP_ImageDataFormat format, @@ -92,25 +125,44 @@ struct PPB_ImageData { PP_Bool init_to_zero); /** - * Returns PP_TRUE if the given resource is an image data. Returns PP_FALSE if - * the resource is invalid or some type other than an image data. + * IsImageData is a pointer to a function that determiens if a given resource + * is image data. + * + * @param[in] image_data A PP_Resource corresponding to image data. + * @return A PP_Bool with PP_TRUE if the given resrouce is an image data + * or PP_FALSE if the resource is invalid or some type other than image data. */ PP_Bool (*IsImageData)(PP_Resource image_data); /** - * Computes the description of the image data. Returns PP_TRUE on success, - * PP_FALSE if the resource is not an image data. On PP_FALSE, the |desc| + * Describe is a pointer to a function that computes the description of the + * image data. + * + * @param[in] image_data A PP_Resource corresponding to image data. + * @param[in/out] desc A pointer to a PP_ImageDataDesc containing the + * description. + * @return A PP_Bool with PP_TRUE on success or PP_FALSE + * if the resource is not an image data. On PP_FALSE, the |desc| * structure will be filled with 0. */ PP_Bool (*Describe)(PP_Resource image_data, struct PP_ImageDataDesc* desc); /** - * Maps this bitmap into the plugin address space and returns a pointer to the - * beginning of the data. + * Map is a pointer to a function that maps an image data into the plugin + * address space. + * + * @param[in] image_data A PP_Resource corresponding to image data. + * @return A pointer to the beginning of the data. */ void* (*Map)(PP_Resource image_data); + /** + * Unmap is a pointer to a function that unmaps an image data from the plugin + * address space. + * + * @param[in] image_data A PP_Resource corresponding to image data. + */ void (*Unmap)(PP_Resource image_data); }; /** |