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 /* From ppb_graphics_2d.idl modified Fri Apr 26 08:49:08 2013. */ 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" 22 #define PPB_GRAPHICS_2D_INTERFACE_1_1 "PPB_Graphics2D;1.1" 23 #define PPB_GRAPHICS_2D_INTERFACE PPB_GRAPHICS_2D_INTERFACE_1_1 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 */ 39 struct PPB_Graphics2D_1_1 { 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 * 85 * @return Returns <code>PP_TRUE</code> on success or <code>PP_FALSE</code> if 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, 91 PP_Bool* is_always_opaque); 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); 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); 279 }; 280 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 }; 302 /** 303 * @} 304 */ 305 306 #endif /* PPAPI_C_PPB_GRAPHICS_2D_H_ */ 307 308