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 */
39struct 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
281typedef struct PPB_Graphics2D_1_1 PPB_Graphics2D;
282
283struct 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