/* 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.
 */

/* Defines the image data API. */

/* Bitmap formats. */
enum PP_ImageDataFormat {
  /* 32 bits, BGRA byte order, premultiplied alpha */
  PP_IMAGEDATAFORMAT_BGRA_PREMUL = 0,
  /* 32 bits, RGBA byte order, premultiplied alpha */
  PP_IMAGEDATAFORMAT_RGBA_PREMUL = 1
};

/* Description of a bitmap. */
struct PP_ImageDataDesc {
  /* Byte format. */
  PP_ImageDataFormat format;

  /* Size of the bitmap in pixels. */
  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.
   */
  int32_t stride;
};

/* Interface for manipulating 2D bitmaps. */
interface PPB_ImageData_0_3 {
  /* 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.
   */
  PP_ImageDataFormat GetNativeImageDataFormat();

  /* Returns PP_TRUE if the given image data format is supported by the browser.
   */
  PP_Bool IsImageDataFormatSupported(
      [in] 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.
   *
   * 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.
   */
  PP_Resource Create(
      [in] PP_Instance instance,
      [in] PP_ImageDataFormat format,
      [in] PP_Size size,
      [in] 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.
   */
  PP_Bool IsImageData(
      [in] 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|
   * structure will be filled with 0.
   */
  PP_Bool Describe(
      [in] PP_Resource image_data,
      [out] PP_ImageDataDesc desc);

  /* Maps this bitmap into the plugin address space and returns a pointer to the
   * beginning of the data.
   */
  mem_t Map(
      [in] PP_Resource image_data);

  /* Unmaps this bitmaps from the plugin address space */
  void Unmap(
      [in] PP_Resource image_data);
};