Add PPB_Fullscreen;0.5.

ppapi/api/dev/ppb_fullscreen_dev.idl

 /* Copyright (c) 2011 The Chromium Authors. All rights reserved.
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
 
 
 /**
- * This file defines the <code>PPB_Fullscreen</code> interface.
+ * This file defines the <code>PPB_Fullscreen_Dev</code> interface.
  */
 
 label Chrome {
-  M14 = 0.4
+  M16 = 0.5
 };
 
 interface PPB_Fullscreen_Dev {
   /**
    * Checks whether the plugin instance is currently in fullscreen mode.
    */
   PP_Bool IsFullscreen(
       [in] PP_Instance instance);
 
   /**
    * Switches the plugin instance to/from fullscreen mode. Returns PP_TRUE on
    * success, PP_FALSE on failure.
    *
-   * This unbinds the current Graphics2D or Surface3D. Pending flushes and
-   * swapbuffers will execute as if the resource was off-screen.  The transition
-   * is asynchronous. During the transition, IsFullscreen will return PP_False,
-   * and no Graphics2D or Surface3D can be bound. The transition ends at the
-   * next DidChangeView.
+   * This unbinds the current 2D or 3D devices. Pending flushes and swapbuffers
+   * will execute as if the resource was off-screen. The transition to and from
+   * fullscreen is asynchronous. During the transition, IsFullscreen will
+   * return the original value, and no 2D or 3D device can be bound.
+   * The transition ends at the next DidChangeView.
    *
-   * Note: when switching to and from fullscreen, Context3D and Surface3D
-   * resources need to be re-created. This is a current limitation that will be
-   * lifted in a later revision.
+   * The transition to fullscreen can only occur while the browser is
+   * processing a user gesture, even if PP_TRUE is returned. Note that two
+   * DidChangeView calls will happen when switching to fullscreen:
+   * one for moving the plugin to the middle of the window and one for
+   * stretching the window placing the plugin in the middle of the screen.
+   * Plugin size will not be affected.

[polina, 2011/09/26 22:12:36]

I am updating the header comments in a different patch set to draw your
attention to how different the new fullscreen implementation is from what was
expected based on the old one. The extensive changes I had to make to the test
also demonstrate that.

I propose that we consider suppressing the first DidChangeView for fullscreen
transitions. I think the 2-step nature of the transition is an implementation
detail that should be hidden from the developers.

I would also like to add a way to determine if SetFullscreen was called while
processing a user gesture, so we can return PP_FALSE otherwise. Currently
PP_TRUE is always returned by SetFullscreen. I have not yet figured out how to
check that. Please let me know if you know of a quick way to do so.

[polina, 2011/09/26 22:24:10]

Also, please not that the plugin is not resized to occupy the entire screen.
What approach do we recommend developers use to address that?

[piman, 2011/09/26 23:01:03]

I don't understand this... How can a plugin deal with full-screen if the
instance isn't at the size of the full screen?

[polina, 2011/09/27 00:49:08]

I was surprised by this behavior myself. In his JS demo here:
http://www.corp.google.com/~jeremya/fullscreen.html, Jeremy used
 
<style>
    <...>
    :-webkit-full-screen {
        width: 100%; height: 100%;
    }
</style>

I am not aware of a way to resize the plugin to larger dimensions from Pepper
C/C++. And I would prefer it if developers did not have to worry about this in
either JS or C/C++. I think we should do it for them. Jeremy can comment on why
he implemented things this way, and if he is planning on changing this behavior.
If not, we should consider addressing it in the Pepper layer although it is
undesirable for us not to match JS behavior.

    */
   PP_Bool SetFullscreen(
       [in] PP_Instance instance,
       [in] PP_Bool fullscreen);
 
   /**
-   * Gets the size of the screen. When going fullscreen, the instance will be
-   * resized to that size.
+   * Gets the size of the screen in pixels. When going fullscreen, the instance
+   * will be resized to that size.
    */
   PP_Bool GetScreenSize(
       [in] PP_Instance instance,
       [out] PP_Size size);
 };