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