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