Skip to content

Commit

Permalink
Remove limitation to self-capture
Browse files Browse the repository at this point in the history
  • Loading branch information
@eladalon1983
eladalon1983 committed Oct 14, 2022
1 parent 6c41d38 commit 279c49d
Showing 1 changed file with 14 additions and 48 deletions.
62 changes: 14 additions & 48 deletions index.html
View file
Expand Up @@ -27,13 +27,6 @@ <h2>Definitions</h2>
This document uses the definition of the following concepts from [[SCREEN-CAPTURE]]:
<dfn>display-surface</dfn> and <dfn>browser</dfn> [=display-surface=].
</p>
<p>
This specification defines <dfn>self-capture</dfn> as the capture of a [=browser=]
[=display-surface=] that is the rendered form of the [=top-level browsing context=] of the
[=associated Document=] of the {{MediaDevices}} object from which the application initiated
the capture session. A <dfn>self-capture video track</dfn> is a {{MediaStreamTrack}} sourced
by <a>self-capture</a>.
</p>
</section>
<section class="informative" id="use-cases">
<h2>Use Cases</h2>
Expand Down Expand Up @@ -78,28 +71,8 @@ <h3>Practical Use-Case</h3>
applications will likely use a combination of {{MediaDevices/getDisplayMedia()}} and
Region Capture for some time to come.
</p>
<p>
The combination of {{MediaDevices/getDisplayMedia()}} and Region Capture is also useful
for applications that allow the users to choose whichever [=display-surface=] they wish,
but offer distinct functionality depending on whether users choose to [=self-capture=] or,
conversely, choose to capture a window or monitor. Such applications would only succeed in
using Region Capture if the user chose to [=self-capture=]; otherwise, the attempt to
apply cropping would be a no-op.
</p>
</section>
</section>
<section id="scope">
<h2>Scope</h2>
<p>
As presently defined, {{BrowserCaptureMediaStreamTrack/cropTo}}(<var>cropTarget</var>)
returns a [=rejected=] {{Promise}} if the <var>cropTarget</var> is not associated with an
{{Element}} within either the current [=top-level browsing context=] or any of its
<a data-cite="HTML#list-of-the-descendant-browsing-contexts">descendant browsing contexts</a
>. That means that all of the mechanisms introduced by this document are only relevant for
[=self-capture=]. An immediate corollary is that navigation of the (shared) [=top-level
browsing context=] breaks off the capture, and therefore also the cropping session.
</p>
</section>
<section id="solution-overview">
<h2>Solution Overview</h2>
<p>The region-capture mechanism comprises two parts:</p>
Expand All @@ -117,7 +90,7 @@ <h2>Solution Overview</h2>
<p>
We define two <dfn>crop-states</dfn> for video tracks - <dfn>cropped</dfn> and
<dfn>uncropped</dfn>. Tracks start out [=uncropped=], and may turn to [=cropped=] when
{{BrowserCaptureMediaStreamTrack/cropTo}} is successfully called on them.
{{BrowserCaptureMediaStreamTrack/cropTo()}} is successfully called on them.
</p>
</section>
<section id="produce-crop-target">
Expand All @@ -126,7 +99,7 @@ <h2><dfn>CropTarget Production</dfn></h2>
<h3>CropTarget Motivation</h3>
<p>
The [=cropping mechanism=] presented in this document
({{BrowserCaptureMediaStreamTrack/cropTo}}) relies on [=Crop-session Target=] rather than
({{BrowserCaptureMediaStreamTrack/cropTo()}}) relies on [=Crop-session Target=] rather than
on direct node references. This serves a dual purpose.
</p>
<ul>
Expand All @@ -146,7 +119,7 @@ <h3>CropTarget Motivation</h3>
<h3><dfn>CropTarget</dfn> Definition</h3>
<p>
CropTarget is an intentionally empty, opaque identifier. Its purpose is to be handed to
{{BrowserCaptureMediaStreamTrack/cropTo}} as input.
{{BrowserCaptureMediaStreamTrack/cropTo()}} as input.
</p>
<pre class="idl">
[Exposed=(Window,Worker), Serializable]
Expand Down Expand Up @@ -174,13 +147,10 @@ <h3><dfn>CropTarget</dfn> Definition</h3>
<p>
Calling {{CropTarget/fromElement}} with an {{Element}} of a supported type associates
that {{Element}} with a {{CropTarget}}. This {{CropTarget}} may be used as input to
{{BrowserCaptureMediaStreamTrack/cropTo}}. We define a
<dfn>valid CropTarget</dfn> as one returned by a previous call to
{{CropTarget.fromElement()}} in the current [=top-level browsing context=] or any of
its
<a data-cite="HTML#list-of-the-descendant-browsing-contexts"
>descendant browsing contexts</a
>.
{{BrowserCaptureMediaStreamTrack/cropTo()}}. We define a
<dfn>valid CropTarget</dfn> as one returned by a call to {{CropTarget.fromElement()}}
in a <a data-cite="!HTML#document">document</a> that is still
<a data-cite="!HTML#active-document">active</a>.
</p>
<p>
When {{CropTarget/fromElement}} is called with a given <var>element</var>, the user
Expand All @@ -189,7 +159,7 @@ <h3><dfn>CropTarget</dfn> Definition</h3>
<var>p</var> only after it has finished all the necessary internal propagation of
state associated with the new {{CropTarget}}, at which point the user agent MUST be
ready to receive the new {{CropTarget}} as a valid parameter to
{{BrowserCaptureMediaStreamTrack/cropTo}}.
{{BrowserCaptureMediaStreamTrack/cropTo()}}.
</p>
<p>
When cloning an {{Element}} on which {{CropTarget/fromElement}} was previously called,
Expand Down Expand Up @@ -268,7 +238,7 @@ <h3>BrowserCaptureMediaStreamTrack</h3>
<p>
We specify that if the user chooses to capture a [=browser=] [=display-surface=], the user
agent MUST instantiate the video track as either {{MediaStreamTrack}}, or as some
sub-class of {{MediaStreamTrack}}, and that {{BrowserCaptureMediaStreamTrack/cropTo}} MUST
sub-class of {{MediaStreamTrack}}, and that {{BrowserCaptureMediaStreamTrack/cropTo()}} MUST
be exposed on this track. For simplicity's sake, this document assumes that a subclass
called {{BrowserCaptureMediaStreamTrack}} is used by the user agent.
</p>
Expand All @@ -289,22 +259,18 @@ <h3>BrowserCaptureMediaStreamTrack</h3>
</dt>
<dd>
<p>
Calls to this method instruct the user agent to start/stop cropping a [=self-capture
video track=] to the
Calls to this method instruct the user agent to start/stop cropping a
video track to the
<a href="https://drafts.csswg.org/cssom-view/#dom-element-getboundingclientrect">
bounding client rectangle</a
>
of <var>cropTarget</var>.[[\Element]]. Since the track is restricted to the visible
viewport of the [=display-surface=], the captured area will be the intersection of the
visible viewport and the element bounding client rectangle. Whenever
{{BrowserCaptureMediaStreamTrack/cropTo}} is invoked, the user agent MUST execute the
{{BrowserCaptureMediaStreamTrack/cropTo()}} is invoked, the user agent MUST execute the
following algorithm:
</p>
<ol>
<li>
If [=this=] is not a [=self-capture video track=], the user agent MUST return a new
{{Promise}}, [=rejected=] with an {{NotSupportedError}}.
</li>
<li>
<p>
If <var>cropTarget</var> is neither a [=valid CropTarget=] nor <code>null</code>, the
Expand Down Expand Up @@ -389,7 +355,7 @@ <h4>Crop-Session Definitions</h4>
</p>
<p>
We define a [=potential crop-target=] which is targeted by a successful call to
{{BrowserCaptureMediaStreamTrack/cropTo}} as the <dfn>crop-session target</dfn>.
{{BrowserCaptureMediaStreamTrack/cropTo()}} as the <dfn>crop-session target</dfn>.
</p>
<p>
Consider a frame produced on a [=cropped=] video track. The user agent calculates the
Expand Down Expand Up @@ -445,7 +411,7 @@ <h5>Disconnected Crop-Session Target</h5>
>, in which case it would not produce any new frames. Nevertheless, the user agent
MUST treat a [=disconnected crop-session target=] the same way it treats an [=empty
crop-session target=]. The application may call
{{BrowserCaptureMediaStreamTrack/cropTo}} on the track with either {{undefined}} or a
{{BrowserCaptureMediaStreamTrack/cropTo()}} on the track with either {{undefined}} or a
new {{CropTarget}}, thereby allowing the production of frames on the track to be
resumed.
</p>
Expand Down

0 comments on commit 279c49d

Please sign in to comment.