ppapi/c/ppb_view.h

   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 Sep  5 11:32:22 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"
  22 #define PPB_VIEW_INTERFACE PPB_VIEW_INTERFACE_1_2
  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 {
  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 typedef struct PPB_View_1_2 PPB_View;
 218
 219 struct PPB_View_1_0 {
 220   PP_Bool (*IsView)(PP_Resource resource);
 221   PP_Bool (*GetRect)(PP_Resource resource, struct PP_Rect* rect);
 222   PP_Bool (*IsFullscreen)(PP_Resource resource);
 223   PP_Bool (*IsVisible)(PP_Resource resource);
 224   PP_Bool (*IsPageVisible)(PP_Resource resource);
 225   PP_Bool (*GetClipRect)(PP_Resource resource, struct PP_Rect* clip);
 226 };
 227
 228 struct PPB_View_1_1 {
 229   PP_Bool (*IsView)(PP_Resource resource);
 230   PP_Bool (*GetRect)(PP_Resource resource, struct PP_Rect* rect);
 231   PP_Bool (*IsFullscreen)(PP_Resource resource);
 232   PP_Bool (*IsVisible)(PP_Resource resource);
 233   PP_Bool (*IsPageVisible)(PP_Resource resource);
 234   PP_Bool (*GetClipRect)(PP_Resource resource, struct PP_Rect* clip);
 235   float (*GetDeviceScale)(PP_Resource resource);
 236   float (*GetCSSScale)(PP_Resource resource);
 237 };
 238 /**
 239  * @}
 240  */
 241
 242 #endif  /* PPAPI_C_PPB_VIEW_H_ */
 243