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 */ 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 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); 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
