From 7c6434f6ff9fab3b146caa7c7bea0f638c612ef7 Mon Sep 17 00:00:00 2001 From: Tove Petersson Date: Thu, 9 Nov 2023 10:55:14 +0100 Subject: [PATCH] Added DisplaySurfaceChangeCallback (fix #255) --- index.html | 228 +++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 211 insertions(+), 17 deletions(-) diff --git a/index.html b/index.html index 618a7db..8a84d2c 100644 --- a/index.html +++ b/index.html @@ -409,25 +409,37 @@

MediaDevices Additions

  • [=Prompt the user to choose=] a display device, for a - {{PermissionDescriptor}} with its - {{PermissionDescriptor/name}} set to "display-capture", - resulting in a set of provided media.

    + {{PermissionDescriptor}} with its + {{PermissionDescriptor/name}} set to "display-capture", + resulting in a capture-source-set, + sources, that meets the following + requirements:

    -

    The provided media MUST include precisely one video - track.

    +
      +
    1. +

      The [=capture-source-set=] MUST include precisely one + video track.

      +
      2. -

      The provided media MUST include at most one audio track. - This audio track MUST NOT be included if audio was not - specified in requestedMediaTypes, or if it was - specified as false.

      +
    2. +

      The [=capture-source-set=] MUST include at most one + audio track. This audio track MUST NOT be included if + audio was not specified in + requestedMediaTypes, or if it was specified + as false.

      +
      3. -

      The devices chosen MUST be the ones determined by the - user. Once selected, the source of a {{MediaStreamTrack}} - MUST NOT change, unless the user permits it through their - interaction with the user agent.

      +
    3. +

      The sources in the [=capture-source-set=] MUST + represent the devices determined by the user. Once + selected, the source of a {{MediaStreamTrack}} MUST NOT + change, unless the user permits it through their + interaction with the user agent.

      +
      4. +

    User agents are encouraged to warn users against sharing @@ -439,9 +451,9 @@

    MediaDevices Additions

    If the result of the request is - {{PermissionState/"granted"}}, then for each device that is - sourcing the provided media, using a stable and private id - for the device, deviceId, set + {{PermissionState/"granted"}}, then for each device with a + source in [=capture-source-set=], using a stable and private + id for the device, deviceId, set [[\devicesLiveMap]][deviceId] to true, if it isn’t already true, and set the [[\devicesAccessibleMap]][deviceId] to @@ -512,7 +524,8 @@

    MediaDevices Additions

  • This invocation of {{MediaDevices/getDisplayMedia()}} is now considered to have produced a new - capture-session.

    + capture-session, with the associated + [=capture-source-set=], sources.

    • @@ -668,6 +681,110 @@

    Unconstrained Display Surface Selection

    +
    +

    Changing Display Surfaces

    + + +

    + The user agent MUST NOT change the [=display surface=] + associated with a [=capture-session=] unless the user has + explicitly indicated that they want this change to be + performed by interacting with user agent or operating system. + + If the user indicates a change of [=display surface=], the + user agent MUST run the following steps: +

    + + +
      +
    1. +

      If the [=capture-session=] does not have an associated + {{CaptureController}}, controller, abort these steps.

      +
      2. + + +
    2. +

      If controller.{{CaptureController/[[DisplaySurfaceChangeCallback]]}} + is null, abort these steps.

      +
      3. + + +
    3. +

      Stop delivering frames from all sources in the + [=capture-source-set=] associated with the [=capture-session=]. +

      +
      4. + + +
    4. +

      Let newSources be the set of sources selected by the + user when the user chose a new [=display surface=].

      + + +

      + newSources MUST fulfill the same requirements as the + [=capture-source-set=] formed when {{MediaDevices/getDisplayMedia}} + is called.

      +
      5. + + +
    5. +

      Queue a task to:

      +
        +
      1. +

        + Set the [=capture-source-set=] + associated with the [=capture-session=] to newSources. +

        +
        2. + + +
      2. +

        Let stream be a new {{MediaStream}} with a new + {{MediaStreamTrack}} for each source in newSources. +

        3. + + +
      3. +

        Run the [=ApplyConstraints algorithm=] on all tracks in + stream with the appropriate constraints. Should + this fail, abort these steps.

        +
        4. + + +
      4. +

        Set + controller.{{CaptureController/[[Source]]}} to + the stream's video track's + [[\Source]].

        +
        5. + + +
      5. +

        Set + controller.{{CaptureController/[[DisplaySurfaceType]]}} + to the stream's video track's + {{DisplayCaptureSurfaceType}}.

        +
        6. + + +
      6. +

        Invoke + controller.{{CaptureController/[[DisplaySurfaceChangeCallback]]}} + with stream as the argument.

        +
        7. +
      +
      6. + +
    6. +

      Queue tasks to end all tracks connected to sources in the + [=capture-source-set=] associated with the [=capture-session=]. +

      +
      7. +
    +
    + +

    Constrainable Properties for Captured Display Surfaces

    @@ -1099,6 +1216,30 @@

    CaptureStartFocusBehavior

    +
    +

    DisplaySurfaceChangeCallback

    +

    + Used to receive a new {{MediaStream}} if the [=display surface=] + associated with a [=capture-session=] changes. +

    +
    + 
    callback DisplaySurfaceChangeCallback = undefined
+               (MediaStream stream);
    +
    +

    Callback DisplaySurfaceChangeCallback + Parameters

    +
    +
    stream of type {{MediaStream}}
    +
    + A new {{MediaStream}} with a new {{MediaStreamTrack}} for each + source in the [=capture-source-set=] associated with the + [=display surface=] that the user has selected. +
    +
    +
    +
    +

    CaptureController @@ -1124,6 +1265,7 @@

    CaptureController interface CaptureController : EventTarget { constructor(); undefined setFocusBehavior(CaptureStartFocusBehavior focusBehavior); + undefined setDisplaySurfaceChangeCallback(DisplaySurfaceChangeCallback callback); }; @@ -1226,6 +1368,19 @@

    CaptureController The focus behavior desired by the application. + + + + [[\DisplaySurfaceChangeCallback]] + + + null + + + A callback called when the [=display surface=] of the + associated [=capture-session=] changes. + + @@ -1294,6 +1449,45 @@

    CaptureController + + +
    setDisplaySurfaceChangeCallback +
    + + +
    +

    Run the following steps:

    + + +
      +
    1. +

      Let callback be the method's first argument.

      +
      2. + + +
    2. +

      If [=this=].{{CaptureController/[[IsBound]]}} is + true, + [=exception/throw=] an "{{InvalidStateError}}" + {{DOMException}}.

      +
      3. + + +
    3. +

      If + [=this=].{{CaptureController/[[DisplaySurfaceChangeCallback]]}} + is not null, [=exception/throw=] an + "{{InvalidStateError}}" {{DOMException}}.

      +
      4. + + +
    4. +

      Set + [=this=].{{CaptureController/[[DisplaySurfaceChangeCallback]]}} + to callback.

      +
      5. +
    +