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 13label 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"] 22interface 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 287