Pepper_31_C_interfaces
ppb_graphics_2d.h
Go to the documentation of this file.
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  */
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  */
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  */
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 
282 
285  const struct PP_Size* size,
286  PP_Bool is_always_opaque);
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 
PP_Resource(* Create)(PP_Instance instance, const struct PP_Size *size, PP_Bool is_always_opaque)
int32_t(* Flush)(PP_Resource graphics_2d, struct PP_CompletionCallback callback)
PP_Bool(* Describe)(PP_Resource graphics_2d, struct PP_Size *size, PP_Bool *is_always_opaque)
void(* Scroll)(PP_Resource graphics_2d, const struct PP_Rect *clip_rect, const struct PP_Point *amount)
PP_Bool(* Describe)(PP_Resource graphics_2d, struct PP_Size *size, PP_Bool *is_always_opaque)
void(* PaintImageData)(PP_Resource graphics_2d, PP_Resource image_data, const struct PP_Point *top_left, const struct PP_Rect *src_rect)
int32_t PP_Resource
Definition: pp_resource.h:40
PP_Resource(* Create)(PP_Instance instance, const struct PP_Size *size, PP_Bool is_always_opaque)
void(* ReplaceContents)(PP_Resource graphics_2d, PP_Resource image_data)
void(* ReplaceContents)(PP_Resource graphics_2d, PP_Resource image_data)
void(* Scroll)(PP_Resource graphics_2d, const struct PP_Rect *clip_rect, const struct PP_Point *amount)
PP_Bool(* IsGraphics2D)(PP_Resource resource)
float(* GetScale)(PP_Resource resource)
PP_Bool(* SetScale)(PP_Resource resource, float scale)
void(* PaintImageData)(PP_Resource graphics_2d, PP_Resource image_data, const struct PP_Point *top_left, const struct PP_Rect *src_rect)
int32_t PP_Instance
Definition: pp_instance.h:34
int32_t(* Flush)(PP_Resource graphics_2d, struct PP_CompletionCallback callback)
PP_Bool
Definition: pp_bool.h:30
PP_Bool(* IsGraphics2D)(PP_Resource resource)