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