ppapi/api/ppb_graphics_2d.idl

   1 /* Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2  * Use of this source code is governed by a BSD-style license that can be
   3  * found in the LICENSE file.
   4  */
   5
   6 /**
   7  * Defines the <code>PPB_Graphics2D</code> struct representing a 2D graphics
   8  * context within the browser.
   9  */
  10
  11 label Chrome {
  12   M14 = 1.0,
  13   M27 = 1.1
  14 };
  15
  16 /**
  17  * <code>PPB_Graphics2D</code> defines the interface for a 2D graphics context.
  18  */
  19 [macro="PPB_GRAPHICS_2D_INTERFACE"]
  20 interface PPB_Graphics2D {
  21   /**
  22    * Create() creates a 2D graphics context. The returned graphics context will
  23    * not be bound to the module instance on creation (call BindGraphics() on
  24    * the module instance to bind the returned graphics context to the module
  25    * instance).
  26    *
  27    * @param[in] instance The module instance.
  28    * @param[in] size The size of the graphic context.
  29    * @param[in] is_always_opaque Set the <code>is_always_opaque</code> flag to
  30    * <code>PP_TRUE</code> if you know that you will be painting only opaque
  31    * data to this context. This option will disable blending when compositing
  32    * the module with the web page, which might give higher performance on some
  33    * computers.
  34    *
  35    * If you set <code>is_always_opaque</code>, your alpha channel should always
  36    * be set to 0xFF or there may be painting artifacts. The alpha values
  37    * overwrite the destination alpha values without blending when
  38    * <code>is_always_opaque</code> is true.
  39    *
  40    * @return A <code>PP_Resource</code> containing the 2D graphics context if
  41    * successful or 0 if unsuccessful.
  42    */
  43   PP_Resource Create(
  44       [in] PP_Instance instance,
  45       [in] PP_Size size,
  46       [in] PP_Bool is_always_opaque);
  47
  48   /**
  49    * IsGraphics2D() determines if the given resource is a valid
  50    * <code>Graphics2D</code>.
  51    *
  52    * @param[in] resource A <code>Graphics2D</code> context resource.
  53    *
  54    * @return PP_TRUE if the given resource is a valid <code>Graphics2D</code>,
  55    * <code>PP_FALSE</code> if it is an invalid resource or is a resource of
  56    * another type.
  57    */
  58   PP_Bool IsGraphics2D(
  59       [in] PP_Resource resource);
  60
  61   /**
  62    * Describe() retrieves the configuration for the given graphics context,
  63    * filling the given values (which must not be <code>NULL</code>).
  64    *
  65    * @param[in] resource The 2D Graphics resource.
  66    * @param[in,out] size The size of the 2D graphics context in the browser.
  67    * @param[in,out] is_always_opaque Identifies whether only opaque data
  68    * will be painted.
  69    *
  70    * @return Returns <code>PP_TRUE</code> on success or <code>PP_FALSE</code> if
  71    * the resource is invalid. The output parameters will be set to 0 on a
  72    * <code>PP_FALSE</code>.
  73    */
  74   PP_Bool Describe(
  75       [in] PP_Resource graphics_2d,
  76       [out] PP_Size size,
  77       [out] PP_Bool is_always_opqaue);
  78
  79   /**
  80    * PaintImageData() enqueues a paint of the given image into the context.
  81    * This function has no effect until you call Flush() As a result, what
  82    * counts is the contents of the bitmap when you call Flush(), not when
  83    * you call this function.
  84    *
  85    * The provided image will be placed at <code>top_left</code> from the top
  86    *  left of the context's internal backing store. Then the pixels contained
  87    * in <code>src_rect</code> will be copied into the backing store. This
  88    * means that the rectangle being painted will be at <code>src_rect</code>
  89    * offset by <code>top_left</code>.
  90    *
  91    * The <code>src_rect</code> is specified in the coordinate system of the
  92    * image being painted, not the context. For the common case of copying the
  93    * entire image, you may specify an empty <code>src_rect</code>.
  94    *
  95    * The painted area of the source bitmap must fall entirely within the
  96    * context. Attempting to paint outside of the context will result in an
  97    * error. However, the source bitmap may fall outside the context, as long
  98    * as the <code>src_rect</code> subset of it falls entirely within the
  99    * context.
 100    *
 101    * There are two methods most modules will use for painting. The first
 102    * method is to generate a new <code>ImageData</code> and then paint it. In
 103    * this case, you'll set the location of your painting to
 104    * <code>top_left</code> and set <code>src_rect</code> to <code>NULL</code>.
 105    * The second is that you're generating small invalid regions out of a larger
 106    * bitmap representing your entire instance. In this case, you would set the
 107    * location of your image to (0,0) and then set <code>src_rect</code> to the
 108    * pixels you changed.
 109    *
 110    * @param[in] resource The 2D Graphics resource.
 111    * @param[in] image The <code>ImageData</code> to be painted.
 112    * @param[in] top_left A <code>Point</code> representing the
 113    * <code>top_left</code> location where the <code>ImageData</code> will be
 114    * painted.
 115    * @param[in] src_rect The rectangular area where the <code>ImageData</code>
 116    * will be painted.
 117    */
 118   void PaintImageData(
 119       [in] PP_Resource graphics_2d,
 120       [in] PP_Resource image_data,
 121       [in] PP_Point top_left,
 122       [in] PP_Rect src_rect);
 123
 124   /**
 125    * Scroll() enqueues a scroll of the context's backing store. This
 126    * function has no effect until you call Flush(). The data within the
 127    * provided clipping rectangle will be shifted by (dx, dy) pixels.
 128    *
 129    * This function will result in some exposed region which will have undefined
 130    * contents. The module should call PaintImageData() on these exposed regions
 131    * to give the correct contents.
 132    *
 133    * The scroll can be larger than the area of the clipping rectangle, which
 134    * means the current image will be scrolled out of the rectangle. This
 135    * scenario is not an error but will result in a no-op.
 136    *
 137    * @param[in] graphics_2d The 2D Graphics resource.
 138    * @param[in] clip The clipping rectangle.
 139    * @param[in] amount The amount the area in the clipping rectangle will
 140    * shifted.
 141    */
 142   void Scroll(
 143       [in] PP_Resource graphics_2d,
 144       [in] PP_Rect clip_rect,
 145       [in] PP_Point amount);
 146
 147   /**
 148    * ReplaceContents() provides a slightly more efficient way to paint the
 149    * entire module's image. Normally, calling PaintImageData() requires that
 150    * the browser copy the pixels out of the image and into the graphics
 151    * context's backing store. This function replaces the graphics context's
 152    * backing store with the given image, avoiding the copy.
 153    *
 154    * The new image must be the exact same size as this graphics context. If the
 155    * new image uses a different image format than the browser's native bitmap
 156    * format (use <code>PPB_ImageData.GetNativeImageDataFormat()</code> to
 157    * retrieve the format), then a conversion will be done inside the browser
 158    * which may slow the performance a little bit.
 159    *
 160    * <strong>Note:</strong> The new image will not be painted until you call
 161    * Flush().
 162    *
 163    * After this call, you should take care to release your references to the
 164    * image. If you paint to the image after ReplaceContents(), there is the
 165    * possibility of significant painting artifacts because the page might use
 166    * partially-rendered data when copying out of the backing store.
 167    *
 168    * In the case of an animation, you will want to allocate a new image for the
 169    * next frame. It is best if you wait until the flush callback has executed
 170    * before allocating this bitmap. This gives the browser the option of
 171    * caching the previous backing store and handing it back to you (assuming
 172    * the sizes match). In the optimal case, this means no bitmaps are allocated
 173    * during the animation, and the backing store and "front buffer" (which the
 174    * plugin is painting into) are just being swapped back and forth.
 175    *
 176    * @param[in] graphics_2d The 2D Graphics resource.
 177    * @param[in] image The <code>ImageData</code> to be painted.
 178    */
 179   void ReplaceContents(
 180       [in] PP_Resource graphics_2d,
 181       [in] PP_Resource image_data);
 182
 183   /**
 184    * Flush() flushes any enqueued paint, scroll, and replace commands to the
 185    * backing store. This function actually executes the updates, and causes a
 186    * repaint of the webpage, assuming this graphics context is bound to a module
 187    * instance.
 188    *
 189    * Flush() runs in asynchronous mode. Specify a callback function and the
 190    * argument for that callback function. The callback function will be
 191    * executed on the calling thread when the image has been painted to the
 192    * screen. While you are waiting for a flush callback, additional calls to
 193    * Flush() will fail.
 194    *
 195    * Because the callback is executed (or thread unblocked) only when the
 196    * instance's image is actually on the screen, this function provides
 197    * a way to rate limit animations. By waiting until the image is on the
 198    * screen before painting the next frame, you can ensure you're not
 199    * flushing 2D graphics faster than the screen can be updated.
 200    *
 201    * <strong>Unbound contexts</strong>
 202    * If the context is not bound to a module instance, you will
 203    * still get a callback. The callback will execute after Flush() returns
 204    * to avoid reentrancy. The callback will not wait until anything is
 205    * painted to the screen because there will be nothing on the screen. The
 206    * timing of this callback is not guaranteed and may be deprioritized by
 207    * the browser because it is not affecting the user experience.
 208    *
 209    * <strong>Off-screen instances</strong>
 210    * If the context is bound to an instance that is currently not visible (for
 211    * example, scrolled out of view) it will behave like the "unbound context"
 212    * case.
 213    *
 214    * <strong>Detaching a context</strong>
 215    * If you detach a context from a module instance, any pending flush
 216    * callbacks will be converted into the "unbound context" case.
 217    *
 218    * <strong>Released contexts</strong>
 219    * A callback may or may not get called even if you have released all
 220    * of your references to the context. This scenario can occur if there are
 221    * internal references to the context suggesting it has not been internally
 222    * destroyed (for example, if it is still bound to an instance) or due to
 223    * other implementation details. As a result, you should be careful to
 224    * check that flush callbacks are for the context you expect and that
 225    * you're capable of handling callbacks for unreferenced contexts.
 226    *
 227    * <strong>Shutdown</strong>
 228    * If a module instance is removed when a flush is pending, the
 229    * callback will not be executed.
 230    *
 231    * @param[in] graphics_2d The 2D Graphics resource.
 232    * @param[in] callback A <code>CompletionCallback</code> to be called when
 233    * the image has been painted on the screen.
 234    *
 235    * @return Returns <code>PP_OK</code> on success or
 236    * <code>PP_ERROR_BADRESOURCE</code> if the graphics context is invalid,
 237    * <code>PP_ERROR_BADARGUMENT</code> if the callback is null and flush is
 238    * being called from the main thread of the module, or
 239    * <code>PP_ERROR_INPROGRESS</code> if a flush is already pending that has
 240    * not issued its callback yet.  In the failure case, nothing will be updated
 241    * and no callback will be scheduled.
 242    */
 243   int32_t Flush(
 244       [in] PP_Resource graphics_2d,
 245       [in] PP_CompletionCallback callback);
 246
 247   /**
 248    * SetScale() sets the scale factor that will be applied when painting the
 249    * graphics context onto the output device. Typically, if rendering at device
 250    * resolution is desired, the context would be created with the width and
 251    * height scaled up by the view's GetDeviceScale and SetScale called with a
 252    * scale of 1.0 / GetDeviceScale(). For example, if the view resource passed
 253    * to DidChangeView has a rectangle of (w=200, h=100) and a device scale of
 254    * 2.0, one would call Create with a size of (w=400, h=200) and then call
 255    * SetScale with 0.5. One would then treat each pixel in the context as a
 256    * single device pixel.
 257    *
 258    * @param[in] resource A <code>Graphics2D</code> context resource.
 259    * @param[in] scale The scale to apply when painting.
 260    *
 261    * @return Returns <code>PP_TRUE</code> on success or <code>PP_FALSE</code> if
 262    * the resource is invalid or the scale factor is 0 or less.
 263    */
 264   [version=1.1]
 265   PP_Bool SetScale(
 266       [in] PP_Resource resource,
 267       [in] float_t scale);
 268
 269   /***
 270    * GetScale() gets the scale factor that will be applied when painting the
 271    * graphics context onto the output device.
 272    *
 273    * @param[in] resource A <code>Graphics2D</code> context resource.
 274    *
 275    * @return Returns the scale factor for the graphics context. If the resource
 276    * is not a valid <code>Graphics2D</code> context, this will return 0.0.
 277    */
 278   [version=1.1]
 279   float_t GetScale(
 280       [in] PP_Resource resource);
 281
 282 };
 283