User:Shellylin/InputPort: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
(→‎Contributors: Add contributirs)
 
(11 intermediate revisions by the same user not shown)
Line 3: Line 3:


== Contributors ==
== Contributors ==
Shih-Chiang Chien, Shelly Lin, James Cheng


== Status ==
== Status ==
Line 8: Line 9:


== Features ==
== Features ==
* Enumerate available input ports on the current device. Supported types of input ports include A/V, VGA and HDMI.
* Enumerate available input ports on the current device. Supported types of input ports include A/V, DisplayPort and HDMI.
* Retrieve media content from an input port, provided by its source provider. Presented as a MediaStream object.
* Retrieve media content from an input port, provided by its source provider. Presented as a MediaStream object.
* Read and write the attributes of a selected input port.
* Support hot-plug detection on each input port.
** Examples of input port attributes: frame rate, color system, aspect ratio...etc.
* Support hotplug detection on each input port.


== Proposed API ==
== Proposed API ==
=== Basic Port Interface ===
=== Basic Port Interface ===
   enum InputPortType { "av", "displayport", "hdmi", "pc" };
   enum InputPortType { "av", "displayport", "hdmi" };


   interface InputPort {
   interface InputPort : EventTarget {
    readonly attribute DOMString name;
     readonly attribute DOMString id;
     readonly attribute DOMString id;
     readonly attribute InputPortType type;
     readonly attribute InputPortType type;
     readonly attribute MediaStream stream;
     readonly attribute MediaStream stream;
    readonly attribute boolean connected;
             attribute EventHandler onconnect;
             attribute EventHandler onconnect;
             attribute EventHandler ondisconnect;
             attribute EventHandler ondisconnect;
   };
   };
<u>'''Attributes'''</u><br />
'''name''' of type DOMString, readonly<br />
The name of this input port, e.g. "HDMI1", "HDMI2".


'''id''' of type DOMString, readonly<br />
'''id''' of type DOMString, readonly<br />
When an InputPort object is created, the user agent MUST generate an identifier string, and MUST initialize the object's id attribute to that string. A good practice is to use an UUID, which is 36 characters long in its canonical form.
The unique id for the represented input port.<br />
 
Input port identifier MUST be unique to the application, and persistent between application sessions.
The id attribute MUST return the value to which it was initialized when the object was created.


p.s. The idea behind InputPort's id is identical to the id of MediaStream, we want to differentiate InputPort instances created by different UA, so the above statement is copied from the definition of MediaStream's id.
''This idea is referenced from the attribute [http://w3c.github.io/mediacapture-main/getusermedia.html#dictionary-mediadeviceinfo-members deviceId] of MediaDevice.''


'''type''' of type InputPortType, readonly<br />
'''type''' of type InputPortType, readonly<br />
Line 42: Line 36:


'''stream''' of type MediaStream, readonly<br />
'''stream''' of type MediaStream, readonly<br />
The stream represents the media content provided by this input port.
The media content of this input port, represented as a MediaStream object.<br />
The reference of this object remains unchanged during the life time of its belonging InputPort; Dispatch of connect or disconnect event responses to the state of hardware connection, isolating to the fact of whether the media content is playable or not; Behaviour of stream with non-playable content should be the same as behavior of muted media tracks, described in section "[http://w3c.github.io/mediacapture-main/getusermedia.html#life-cycle-and-media-flow Life-cycle and Media Flow]".
 
'''connected''' of type boolean, readonly<br />
True if this input port is connected to a source provider, and vice versa.
 
'''onconnect''' of type EventHandler,<br />
'''ondisconnect''' of type EventHandler,<br />
Whenever the hardware detects a connection/disconnection of this input port, UA must queue a task to fire a simple event name connect/disconnect at its InputPort object.


=== Specific Port Interfaces ===
=== Specific Port Interfaces ===
==== A/V ====
==== A/V ====
  enum AVInputPortType { "scart", "rca" };
  enum AVInputPortVideoFormat { "component", "composite", "rgb" };
  interface AVInputPort : InputPort {
    sequence<AVInputPortVideoFormat> getSupportedVideoFormats ();
    readonly attribute AVInputPortType type;
  }


==== PC ====
''In reality, a specific input port has its specific attributes and methods, our goal is to collect those "common" cases as much as possible. However, with limit information, we will not focus on implementing hardware dependent attributes and methods in this draft.''
  enum PCInputPortType { "audio", "dvi" };


   interface PCInputPort : InputPort {
   interface AVInputPort : InputPort {
     readonly attribute PCInputPortType type;
     // Possible hardware-dependent attributes.
   }
   };


==== HDMI/DisplayPort ====
==== HDMI/DisplayPort ====
  enum HDMIInputPortAudioFormat { "LPCM", "Dolby Digital" };
   interface HDMIInputPort : InputPort {
   interface HDMIInputPort : InputPort {
     sequence<HDMIInputPortAudioFormat> getSupportedAudioFormats ();
     // Possible hardware-dependent attributes.
   }
   };
 
  enum DisplayPortInputPortAudioFormat { "LPCM" };


   interface DisplayPortInputPort : InputPort {
   interface DisplayPortInputPort : InputPort {
     sequence<DisplayPortInputPortAudioFormat> getSupportedAudioFormats ();
     // Possible hardware-dependent attributes.
   }
   };
 
p.s. Supposely the enum of HDMIInputPortAudioFormat and DisplayPortInputPortAudioFormat depended on its manufacturer, we will not define those attributes in the InputPort API.


=== InputPortManager ===
=== InputPortManager ===
Line 80: Line 68:
This will be an object in <code>window.navigator</code> named <code>InputPortManager</code> with the following interface:
This will be an object in <code>window.navigator</code> named <code>InputPortManager</code> with the following interface:


  [AvailableIn=CertifiedApps]
   partial interface Navigator {
   partial interface Navigator {
     readonly attribute InputPortManager inputPortManager;
     readonly attribute InputPortManager inputPortManager;
Line 85: Line 74:


   interface InputPortManager {
   interface InputPortManager {
     sequence<InputPort> getInputPorts ();
     Promise<sequence<InputPort>> getInputPorts ();
   };
   };
'''getInputPorts'''<br />
This method makes a request to retrieve all the available input ports on a device. It returns a new Promise that will be used to notify the caller about the result of the operation, which is an array of InputPort elements belong to the InputPortManager.


== Examples ==
== Examples ==

Latest revision as of 03:05, 13 April 2015

Goals

Provide DOM API access to the input ports of devices. With InputPort API, application developers are able to browse available input ports of the current device, retrieve media content provided by a particular port, detect whether an input port has connected to a source provider.

Contributors

Shih-Chiang Chien, Shelly Lin, James Cheng

Status

Features

  • Enumerate available input ports on the current device. Supported types of input ports include A/V, DisplayPort and HDMI.
  • Retrieve media content from an input port, provided by its source provider. Presented as a MediaStream object.
  • Support hot-plug detection on each input port.

Proposed API

Basic Port Interface

 enum InputPortType { "av", "displayport", "hdmi" };

 interface InputPort : EventTarget {
   readonly attribute DOMString id;
   readonly attribute InputPortType type;
   readonly attribute MediaStream stream;
   readonly attribute boolean connected;
            attribute EventHandler onconnect;
            attribute EventHandler ondisconnect;
 };

id of type DOMString, readonly
The unique id for the represented input port.
Input port identifier MUST be unique to the application, and persistent between application sessions.

This idea is referenced from the attribute deviceId of MediaDevice.

type of type InputPortType, readonly
The type of this input port, value must be defined in the enum of InputPortType, e.g. "av", "displayport".

stream of type MediaStream, readonly
The media content of this input port, represented as a MediaStream object.
The reference of this object remains unchanged during the life time of its belonging InputPort; Dispatch of connect or disconnect event responses to the state of hardware connection, isolating to the fact of whether the media content is playable or not; Behaviour of stream with non-playable content should be the same as behavior of muted media tracks, described in section "Life-cycle and Media Flow".

connected of type boolean, readonly
True if this input port is connected to a source provider, and vice versa.

onconnect of type EventHandler,
ondisconnect of type EventHandler,
Whenever the hardware detects a connection/disconnection of this input port, UA must queue a task to fire a simple event name connect/disconnect at its InputPort object.

Specific Port Interfaces

A/V

In reality, a specific input port has its specific attributes and methods, our goal is to collect those "common" cases as much as possible. However, with limit information, we will not focus on implementing hardware dependent attributes and methods in this draft. 

 interface AVInputPort : InputPort {
   // Possible hardware-dependent attributes.
 };

HDMI/DisplayPort

 interface HDMIInputPort : InputPort {
   // Possible hardware-dependent attributes.
 };

 interface DisplayPortInputPort : InputPort {
   // Possible hardware-dependent attributes.
 };

InputPortManager

This will be an object in window.navigator named InputPortManager with the following interface: 

 [AvailableIn=CertifiedApps]
 partial interface Navigator {
   readonly attribute InputPortManager inputPortManager;
 };

 interface InputPortManager {
   Promise<sequence<InputPort>> getInputPorts ();
 };

getInputPorts
This method makes a request to retrieve all the available input ports on a device. It returns a new Promise that will be used to notify the caller about the result of the operation, which is an array of InputPort elements belong to the InputPortManager.

Examples

Retrieved from "https://wiki.allizom.org/index.php?title=User:Shellylin/InputPort&oldid=1067749"