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 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