Pepper_31_C_interfaces
ppb_view.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_view.idl modified Fri Mar 29 11:55:32 2013. */
7 
8 #ifndef PPAPI_C_PPB_VIEW_H_
9 #define PPAPI_C_PPB_VIEW_H_
10 
11 #include "ppapi/c/pp_bool.h"
12 #include "ppapi/c/pp_macros.h"
13 #include "ppapi/c/pp_point.h"
14 #include "ppapi/c/pp_rect.h"
15 #include "ppapi/c/pp_resource.h"
16 #include "ppapi/c/pp_size.h"
17 #include "ppapi/c/pp_stdint.h"
18 
19 #define PPB_VIEW_INTERFACE_1_0 "PPB_View;1.0"
20 #define PPB_VIEW_INTERFACE_1_1 "PPB_View;1.1"
21 #define PPB_VIEW_INTERFACE PPB_VIEW_INTERFACE_1_1
22 
23 /**
24  * @file
25  * This file defines the <code>PPB_View</code> struct representing the state
26  * of the view of an instance.
27  */
28 
29 
30 /**
31  * @addtogroup Interfaces
32  * @{
33  */
34 /**
35  * <code>PPB_View</code> represents the state of the view of an instance.
36  * You will receive new view information using
37  * <code>PPP_Instance.DidChangeView</code>.
38  */
39 struct PPB_View_1_1 {
40  /**
41  * IsView() determines if the given resource is a valid
42  * <code>PPB_View</code> resource. Note that <code>PPB_ViewChanged</code>
43  * resources derive from <code>PPB_View</code> and will return true here
44  * as well.
45  *
46  * @param resource A <code>PP_Resource</code> corresponding to a
47  * <code>PPB_View</code> resource.
48  *
49  * @return <code>PP_TRUE</code> if the given resource supports
50  * <code>PPB_View</code> or <code>PP_FALSE</code> if it is an invalid
51  * resource or is a resource of another type.
52  */
53  PP_Bool (*IsView)(PP_Resource resource);
54  /**
55  * GetRect() retrieves the rectangle of the module instance associated
56  * with a view changed notification relative to the upper-left of the browser
57  * viewport. This position changes when the page is scrolled.
58  *
59  * The returned rectangle may not be inside the visible portion of the
60  * viewport if the module instance is scrolled off the page. Therefore, the
61  * position may be negative or larger than the size of the page. The size will
62  * always reflect the size of the module were it to be scrolled entirely into
63  * view.
64  *
65  * In general, most modules will not need to worry about the position of the
66  * module instance in the viewport, and only need to use the size.
67  *
68  * @param resource A <code>PP_Resource</code> corresponding to a
69  * <code>PPB_View</code> resource.
70  *
71  * @param rect A <code>PP_Rect</code> receiving the rectangle on success.
72  *
73  * @return Returns <code>PP_TRUE</code> if the resource was valid and the
74  * viewport rectangle was filled in, <code>PP_FALSE</code> if not.
75  */
76  PP_Bool (*GetRect)(PP_Resource resource, struct PP_Rect* rect);
77  /**
78  * IsFullscreen() returns whether the instance is currently
79  * displaying in fullscreen mode.
80  *
81  * @param resource A <code>PP_Resource</code> corresponding to a
82  * <code>PPB_View</code> resource.
83  *
84  * @return <code>PP_TRUE</code> if the instance is in full screen mode,
85  * or <code>PP_FALSE</code> if it's not or the resource is invalid.
86  */
88  /**
89  * IsVisible() determines whether the module instance might be visible to
90  * the user. For example, the Chrome window could be minimized or another
91  * window could be over it. In both of these cases, the module instance
92  * would not be visible to the user, but IsVisible() will return true.
93  *
94  * Use the result to speed up or stop updates for invisible module
95  * instances.
96  *
97  * This function performs the duties of GetRect() (determining whether the
98  * module instance is scrolled into view and the clip rectangle is nonempty)
99  * and IsPageVisible() (whether the page is visible to the user).
100  *
101  * @param resource A <code>PP_Resource</code> corresponding to a
102  * <code>PPB_View</code> resource.
103  *
104  * @return <code>PP_TRUE</code> if the instance might be visible to the
105  * user, <code>PP_FALSE</code> if it is definitely not visible.
106  */
108  /**
109  * IsPageVisible() determines if the page that contains the module instance
110  * is visible. The most common cause of invisible pages is that
111  * the page is in a background tab in the browser.
112  *
113  * Most applications should use IsVisible() instead of this function since
114  * the module instance could be scrolled off of a visible page, and this
115  * function will still return true. However, depending on how your module
116  * interacts with the page, there may be certain updates that you may want to
117  * perform when the page is visible even if your specific module instance is
118  * not visible.
119  *
120  * @param resource A <code>PP_Resource</code> corresponding to a
121  * <code>PPB_View</code> resource.
122  *
123  * @return <code>PP_TRUE</code> if the instance is plausibly visible to the
124  * user, <code>PP_FALSE</code> if it is definitely not visible.
125  */
127  /**
128  * GetClipRect() returns the clip rectangle relative to the upper-left corner
129  * of the module instance. This rectangle indicates the portions of the module
130  * instance that are scrolled into view.
131  *
132  * If the module instance is scrolled off the view, the return value will be
133  * (0, 0, 0, 0). This clip rectangle does <i>not</i> take into account page
134  * visibility. Therefore, if the module instance is scrolled into view, but
135  * the page itself is on a tab that is not visible, the return rectangle will
136  * contain the visible rectangle as though the page were visible. Refer to
137  * IsPageVisible() and IsVisible() if you want to account for page
138  * visibility.
139  *
140  * Most applications will not need to worry about the clip rectangle. The
141  * recommended behavior is to do full updates if the module instance is
142  * visible, as determined by IsVisible(), and do no updates if it is not
143  * visible.
144  *
145  * However, if the cost for computing pixels is very high for your
146  * application, or the pages you're targeting frequently have very large
147  * module instances with small visible portions, you may wish to optimize
148  * further. In this case, the clip rectangle will tell you which parts of
149  * the module to update.
150  *
151  * Note that painting of the page and sending of view changed updates
152  * happens asynchronously. This means when the user scrolls, for example,
153  * it is likely that the previous backing store of the module instance will
154  * be used for the first paint, and will be updated later when your
155  * application generates new content with the new clip. This may cause
156  * flickering at the boundaries when scrolling. If you do choose to do
157  * partial updates, you may want to think about what color the invisible
158  * portions of your backing store contain (be it transparent or some
159  * background color) or to paint a certain region outside the clip to reduce
160  * the visual distraction when this happens.
161  *
162  * @param resource A <code>PP_Resource</code> corresponding to a
163  * <code>PPB_View</code> resource.
164  *
165  * @param clip Output argument receiving the clip rect on success.
166  *
167  * @return Returns <code>PP_TRUE</code> if the resource was valid and the
168  * clip rect was filled in, <code>PP_FALSE</code> if not.
169  */
170  PP_Bool (*GetClipRect)(PP_Resource resource, struct PP_Rect* clip);
171  /**
172  * GetDeviceScale returns the scale factor between device pixels and Density
173  * Independent Pixels (DIPs, also known as logical pixels or UI pixels on
174  * some platforms). This allows the developer to render their contents at
175  * device resolution, even as coordinates / sizes are given in DIPs through
176  * the API.
177  *
178  * Note that the coordinate system for Pepper APIs is DIPs. Also note that
179  * one DIP might not equal one CSS pixel - when page scale/zoom is in effect.
180  *
181  * @param[in] resource A <code>PP_Resource</code> corresponding to a
182  * <code>PPB_View</code> resource.
183  *
184  * @return A <code>float</code> value representing the number of device pixels
185  * per DIP. If the resource is invalid, the value will be 0.0.
186  */
187  float (*GetDeviceScale)(PP_Resource resource);
188  /**
189  * GetCSSScale returns the scale factor between DIPs and CSS pixels. This
190  * allows proper scaling between DIPs - as sent via the Pepper API - and CSS
191  * pixel coordinates used for Web content.
192  *
193  * @param[in] resource A <code>PP_Resource</code> corresponding to a
194  * <code>PPB_View</code> resource.
195  *
196  * @return css_scale A <code>float</code> value representing the number of
197  * DIPs per CSS pixel. If the resource is invalid, the value will be 0.0.
198  */
199  float (*GetCSSScale)(PP_Resource resource);
200 };
201 
202 typedef struct PPB_View_1_1 PPB_View;
203 
204 struct PPB_View_1_0 {
205  PP_Bool (*IsView)(PP_Resource resource);
206  PP_Bool (*GetRect)(PP_Resource resource, struct PP_Rect* rect);
210  PP_Bool (*GetClipRect)(PP_Resource resource, struct PP_Rect* clip);
211 };
212 /**
213  * @}
214  */
215 
216 #endif /* PPAPI_C_PPB_VIEW_H_ */
217 
PP_Bool(* IsVisible)(PP_Resource resource)
Definition: ppb_view.h:107
PP_Bool(* IsView)(PP_Resource resource)
Definition: ppb_view.h:53
PP_Bool(* IsVisible)(PP_Resource resource)
Definition: ppb_view.h:208
PP_Bool(* IsPageVisible)(PP_Resource resource)
Definition: ppb_view.h:126
PP_Bool(* GetClipRect)(PP_Resource resource, struct PP_Rect *clip)
Definition: ppb_view.h:210
float(* GetCSSScale)(PP_Resource resource)
Definition: ppb_view.h:199
PP_Bool(* IsFullscreen)(PP_Resource resource)
Definition: ppb_view.h:87
int32_t PP_Resource
Definition: pp_resource.h:40
float(* GetDeviceScale)(PP_Resource resource)
Definition: ppb_view.h:187
PP_Bool(* IsFullscreen)(PP_Resource resource)
Definition: ppb_view.h:207
PP_Bool(* GetRect)(PP_Resource resource, struct PP_Rect *rect)
Definition: ppb_view.h:76
PP_Bool
Definition: pp_bool.h:30
PP_Bool(* GetRect)(PP_Resource resource, struct PP_Rect *rect)
Definition: ppb_view.h:206
PP_Bool(* IsView)(PP_Resource resource)
Definition: ppb_view.h:205
PP_Bool(* GetClipRect)(PP_Resource resource, struct PP_Rect *clip)
Definition: ppb_view.h:170
PP_Bool(* IsPageVisible)(PP_Resource resource)
Definition: ppb_view.h:209