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 */
39struct 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   */
87  PP_Bool (*IsFullscreen)(PP_Resource resource);
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   */
107  PP_Bool (*IsVisible)(PP_Resource resource);
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   */
126  PP_Bool (*IsPageVisible)(PP_Resource resource);
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
202typedef struct PPB_View_1_1 PPB_View;
203
204struct PPB_View_1_0 {
205  PP_Bool (*IsView)(PP_Resource resource);
206  PP_Bool (*GetRect)(PP_Resource resource, struct PP_Rect* rect);
207  PP_Bool (*IsFullscreen)(PP_Resource resource);
208  PP_Bool (*IsVisible)(PP_Resource resource);
209  PP_Bool (*IsPageVisible)(PP_Resource resource);
210  PP_Bool (*GetClipRect)(PP_Resource resource, struct PP_Rect* clip);
211};
212/**
213 * @}
214 */
215
216#endif  /* PPAPI_C_PPB_VIEW_H_ */
217
218