15821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* Copyright (c) 2012 The Chromium Authors. All rights reserved. 25821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Use of this source code is governed by a BSD-style license that can be 35821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * found in the LICENSE file. 45821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 55821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 65821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/** 75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Defines the <code>PPB_Graphics2D</code> struct representing a 2D graphics 85821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * context within the browser. 95821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 11c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)[generate_thunk] 12c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)label Chrome { 14c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) M14 = 1.0, 15c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) M27 = 1.1 165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)}; 175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/** 195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <code>PPB_Graphics2D</code> defines the interface for a 2D graphics context. 205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)[macro="PPB_GRAPHICS_2D_INTERFACE"] 225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)interface PPB_Graphics2D { 235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /** 245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Create() creates a 2D graphics context. The returned graphics context will 255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * not be bound to the module instance on creation (call BindGraphics() on 265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * the module instance to bind the returned graphics context to the module 275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * instance). 285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param[in] instance The module instance. 305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param[in] size The size of the graphic context. 315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param[in] is_always_opaque Set the <code>is_always_opaque</code> flag to 325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <code>PP_TRUE</code> if you know that you will be painting only opaque 335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * data to this context. This option will disable blending when compositing 345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * the module with the web page, which might give higher performance on some 355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * computers. 365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * If you set <code>is_always_opaque</code>, your alpha channel should always 385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * be set to 0xFF or there may be painting artifacts. The alpha values 395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * overwrite the destination alpha values without blending when 405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <code>is_always_opaque</code> is true. 415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @return A <code>PP_Resource</code> containing the 2D graphics context if 435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * successful or 0 if unsuccessful. 445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PP_Resource Create( 465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) [in] PP_Instance instance, 475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) [in] PP_Size size, 485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) [in] PP_Bool is_always_opaque); 495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /** 515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * IsGraphics2D() determines if the given resource is a valid 525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <code>Graphics2D</code>. 535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param[in] resource A <code>Graphics2D</code> context resource. 555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @return PP_TRUE if the given resource is a valid <code>Graphics2D</code>, 575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <code>PP_FALSE</code> if it is an invalid resource or is a resource of 585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * another type. 595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PP_Bool IsGraphics2D( 615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) [in] PP_Resource resource); 625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /** 645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Describe() retrieves the configuration for the given graphics context, 655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * filling the given values (which must not be <code>NULL</code>). 665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param[in] resource The 2D Graphics resource. 685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param[in,out] size The size of the 2D graphics context in the browser. 695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param[in,out] is_always_opaque Identifies whether only opaque data 705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * will be painted. 715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 72c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) * @return Returns <code>PP_TRUE</code> on success or <code>PP_FALSE</code> if 735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * the resource is invalid. The output parameters will be set to 0 on a 745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <code>PP_FALSE</code>. 755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 76c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) [always_set_output_parameters] 775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PP_Bool Describe( 785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) [in] PP_Resource graphics_2d, 795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) [out] PP_Size size, 80c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) [out] PP_Bool is_always_opaque); 815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /** 835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * PaintImageData() enqueues a paint of the given image into the context. 845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * This function has no effect until you call Flush() As a result, what 855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * counts is the contents of the bitmap when you call Flush(), not when 865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * you call this function. 875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * The provided image will be placed at <code>top_left</code> from the top 895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * left of the context's internal backing store. Then the pixels contained 905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * in <code>src_rect</code> will be copied into the backing store. This 915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * means that the rectangle being painted will be at <code>src_rect</code> 925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * offset by <code>top_left</code>. 935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * The <code>src_rect</code> is specified in the coordinate system of the 955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * image being painted, not the context. For the common case of copying the 965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * entire image, you may specify an empty <code>src_rect</code>. 975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * The painted area of the source bitmap must fall entirely within the 995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * context. Attempting to paint outside of the context will result in an 1005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * error. However, the source bitmap may fall outside the context, as long 1015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * as the <code>src_rect</code> subset of it falls entirely within the 1025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * context. 1035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 1045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * There are two methods most modules will use for painting. The first 1055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * method is to generate a new <code>ImageData</code> and then paint it. In 1065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * this case, you'll set the location of your painting to 1075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <code>top_left</code> and set <code>src_rect</code> to <code>NULL</code>. 1085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * The second is that you're generating small invalid regions out of a larger 1095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * bitmap representing your entire instance. In this case, you would set the 1105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * location of your image to (0,0) and then set <code>src_rect</code> to the 1115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * pixels you changed. 1125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 1135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param[in] resource The 2D Graphics resource. 1145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param[in] image The <code>ImageData</code> to be painted. 1155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param[in] top_left A <code>Point</code> representing the 1165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <code>top_left</code> location where the <code>ImageData</code> will be 1175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * painted. 1185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param[in] src_rect The rectangular area where the <code>ImageData</code> 1195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * will be painted. 1205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 1215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void PaintImageData( 1225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) [in] PP_Resource graphics_2d, 1235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) [in] PP_Resource image_data, 1245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) [in] PP_Point top_left, 1255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) [in] PP_Rect src_rect); 1265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /** 1285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Scroll() enqueues a scroll of the context's backing store. This 1295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * function has no effect until you call Flush(). The data within the 1305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * provided clipping rectangle will be shifted by (dx, dy) pixels. 1315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 1325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * This function will result in some exposed region which will have undefined 1335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * contents. The module should call PaintImageData() on these exposed regions 1345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * to give the correct contents. 1355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 1365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * The scroll can be larger than the area of the clipping rectangle, which 1375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * means the current image will be scrolled out of the rectangle. This 1385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * scenario is not an error but will result in a no-op. 1395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 1405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param[in] graphics_2d The 2D Graphics resource. 1415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param[in] clip The clipping rectangle. 1425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param[in] amount The amount the area in the clipping rectangle will 1435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * shifted. 1445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 1455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void Scroll( 1465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) [in] PP_Resource graphics_2d, 1475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) [in] PP_Rect clip_rect, 1485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) [in] PP_Point amount); 1495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /** 1515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * ReplaceContents() provides a slightly more efficient way to paint the 1525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * entire module's image. Normally, calling PaintImageData() requires that 1535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * the browser copy the pixels out of the image and into the graphics 1545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * context's backing store. This function replaces the graphics context's 1555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * backing store with the given image, avoiding the copy. 1565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 1575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * The new image must be the exact same size as this graphics context. If the 1585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * new image uses a different image format than the browser's native bitmap 1595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * format (use <code>PPB_ImageData.GetNativeImageDataFormat()</code> to 1605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * retrieve the format), then a conversion will be done inside the browser 1615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * which may slow the performance a little bit. 1625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 1635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <strong>Note:</strong> The new image will not be painted until you call 1645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Flush(). 1655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 1665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * After this call, you should take care to release your references to the 1675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * image. If you paint to the image after ReplaceContents(), there is the 1685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * possibility of significant painting artifacts because the page might use 1695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * partially-rendered data when copying out of the backing store. 1705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 1715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * In the case of an animation, you will want to allocate a new image for the 1725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * next frame. It is best if you wait until the flush callback has executed 1735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * before allocating this bitmap. This gives the browser the option of 1745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * caching the previous backing store and handing it back to you (assuming 1755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * the sizes match). In the optimal case, this means no bitmaps are allocated 1765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * during the animation, and the backing store and "front buffer" (which the 1775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * plugin is painting into) are just being swapped back and forth. 1785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 1795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param[in] graphics_2d The 2D Graphics resource. 1805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param[in] image The <code>ImageData</code> to be painted. 1815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 1825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void ReplaceContents( 1835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) [in] PP_Resource graphics_2d, 1845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) [in] PP_Resource image_data); 1855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /** 1875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Flush() flushes any enqueued paint, scroll, and replace commands to the 1885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * backing store. This function actually executes the updates, and causes a 1895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * repaint of the webpage, assuming this graphics context is bound to a module 1905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * instance. 1915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 1925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Flush() runs in asynchronous mode. Specify a callback function and the 1935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * argument for that callback function. The callback function will be 1945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * executed on the calling thread when the image has been painted to the 1955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * screen. While you are waiting for a flush callback, additional calls to 1965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Flush() will fail. 1975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 1985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Because the callback is executed (or thread unblocked) only when the 1995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * instance's image is actually on the screen, this function provides 2005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * a way to rate limit animations. By waiting until the image is on the 2015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * screen before painting the next frame, you can ensure you're not 2025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * flushing 2D graphics faster than the screen can be updated. 2035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 2045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <strong>Unbound contexts</strong> 2055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * If the context is not bound to a module instance, you will 2065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * still get a callback. The callback will execute after Flush() returns 2075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * to avoid reentrancy. The callback will not wait until anything is 2085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * painted to the screen because there will be nothing on the screen. The 2095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * timing of this callback is not guaranteed and may be deprioritized by 2105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * the browser because it is not affecting the user experience. 2115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 2125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <strong>Off-screen instances</strong> 2135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * If the context is bound to an instance that is currently not visible (for 2145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * example, scrolled out of view) it will behave like the "unbound context" 2155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * case. 2165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 2175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <strong>Detaching a context</strong> 2185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * If you detach a context from a module instance, any pending flush 2195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * callbacks will be converted into the "unbound context" case. 2205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 2215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <strong>Released contexts</strong> 2225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * A callback may or may not get called even if you have released all 2235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * of your references to the context. This scenario can occur if there are 2245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * internal references to the context suggesting it has not been internally 2255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * destroyed (for example, if it is still bound to an instance) or due to 2265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * other implementation details. As a result, you should be careful to 2275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * check that flush callbacks are for the context you expect and that 2285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * you're capable of handling callbacks for unreferenced contexts. 2295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 2305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <strong>Shutdown</strong> 2315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * If a module instance is removed when a flush is pending, the 2325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * callback will not be executed. 2335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 2345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param[in] graphics_2d The 2D Graphics resource. 2355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param[in] callback A <code>CompletionCallback</code> to be called when 2365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * the image has been painted on the screen. 2375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 2385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @return Returns <code>PP_OK</code> on success or 2395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <code>PP_ERROR_BADRESOURCE</code> if the graphics context is invalid, 2405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <code>PP_ERROR_BADARGUMENT</code> if the callback is null and flush is 2415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * being called from the main thread of the module, or 2425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <code>PP_ERROR_INPROGRESS</code> if a flush is already pending that has 2435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * not issued its callback yet. In the failure case, nothing will be updated 2445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * and no callback will be scheduled. 2455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 2465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int32_t Flush( 2475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) [in] PP_Resource graphics_2d, 2485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) [in] PP_CompletionCallback callback); 249c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 250c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /** 251c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) * SetScale() sets the scale factor that will be applied when painting the 252c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) * graphics context onto the output device. Typically, if rendering at device 253c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) * resolution is desired, the context would be created with the width and 254c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) * height scaled up by the view's GetDeviceScale and SetScale called with a 255c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) * scale of 1.0 / GetDeviceScale(). For example, if the view resource passed 256c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) * to DidChangeView has a rectangle of (w=200, h=100) and a device scale of 257c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) * 2.0, one would call Create with a size of (w=400, h=200) and then call 258c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) * SetScale with 0.5. One would then treat each pixel in the context as a 259c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) * single device pixel. 260c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) * 261c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) * @param[in] resource A <code>Graphics2D</code> context resource. 262c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) * @param[in] scale The scale to apply when painting. 263c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) * 264c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) * @return Returns <code>PP_TRUE</code> on success or <code>PP_FALSE</code> if 265c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) * the resource is invalid or the scale factor is 0 or less. 266c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) */ 267c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) [version=1.1] 268c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) PP_Bool SetScale( 269c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) [in] PP_Resource resource, 270c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) [in] float_t scale); 271c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 272c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /*** 273c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) * GetScale() gets the scale factor that will be applied when painting the 274c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) * graphics context onto the output device. 275c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) * 276c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) * @param[in] resource A <code>Graphics2D</code> context resource. 277c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) * 278c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) * @return Returns the scale factor for the graphics context. If the resource 279c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) * is not a valid <code>Graphics2D</code> context, this will return 0.0. 280c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) */ 281c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) [version=1.1] 282c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) float_t GetScale( 283c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) [in] PP_Resource resource); 284c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 2855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)}; 2865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 287