New tabCapture.captureOffscreenTab API, initially for Presentation API 1UA mode

chrome/common/extensions/api/tab_capture.idl

Index: chrome/common/extensions/api/tab_capture.idl
diff --git a/chrome/common/extensions/api/tab_capture.idl b/chrome/common/extensions/api/tab_capture.idl
index c6489d6f6980c167c3b898864692979588bec2d5..f3d3dc25e4025050d780180e1e45088ad82550ff 100644
--- a/chrome/common/extensions/api/tab_capture.idl
+++ b/chrome/common/extensions/api/tab_capture.idl
@@ -66,6 +66,41 @@ namespace tabCapture {
     // to prevent redundant requests for the same tab).
     // |callback| : Callback invoked with CaptureInfo[] for captured tabs.
     static void getCapturedTabs(GetCapturedTabsCallback callback);
+
+    // Locates an off-screen presentation tab identified by a starting
+    // |presentationUrl| and |presentationId|.  If not found, one is
+    // automatically created and navigated to |presentationUrl|.  Then, capture
+    // is started.
+    //
+    // Off-screen presentation tabs are used to simulate the rendering of a web
+    // page on a remote device.  This is accomplished by rendering the page
+    // locally and capturing its audio and/or video output into a MediaStream.
+    // Users of this API can then remote the MediaStream (e.g., via WebRTC or
+    // Cast) to a remote playback device.
+    //
+    // Therefore, off-screen presentation tabs are isolated from the user's
+    // normal browser experience.  They do not show up in the browser window or
+    // tab strip, nor are they visible to extensions (e.g., via the
+    // chrome.tabs.* APIs).  For security reasons, they are isolated in their
+    // own non-shared incognito profile and cannot access any interactive
+    // resources such as keyboard/mouse input, media recording devices (e.g.,
+    // web cams), copy/paste to/from the system clipboard, etc.
+    //
+    // An off-screen presentation tab remains alive until one of three events
+    // occurs: 1. All MediaStreams providing its captured content are closed;
+    // 2. the page being rendered calls window.close(); 3. the extension that
+    // called capturePresentation() is unloaded.
+    //
+    // This is a new, experimental API and may change without notice.  In
+    // addition, it is only available when the browser is run with the
+    // --enable-capture-presentation-api switch.
+    //
+    // |options| : Configures the capture and returned MediaStream.
+    // |callback| : <code>null</code> on error.
+    static void capturePresentation(DOMString presentationUrl,
+                                    DOMString presentationId,
+                                    CaptureOptions options,
+                                    GetTabMediaCallback callback);
   };
 
   interface Events {