W3C home > Mailing lists > Public > public-media-capture@w3.org > November 2013

Constraint webidl comments

From: Jan-Ivar Bruaroey <jib@mozilla.com>
Date: Wed, 13 Nov 2013 17:23:45 -0500
Message-ID: <5283FBF1.9030103@mozilla.com>
To: "public-media-capture@w3.org" <public-media-capture@w3.org>
I've been meaning to comment on the webidl for the Constrainable 
interface, as well as for constraints in general.

First, an minor one.

>From 
http://dev.w3.org/2011/webrtc/editor/getusermedia.html#interface-definition-1 
:

> [NoInterfaceObject]
> interface Constrainable {
>      readonly    attribute Capabilities capabilities();
>      readonly    attribute Constraints  constraints;
>      readonly    attribute Settings     settings;


http://www.w3.org/TR/WebIDL/#idl-dictionaries states "Dictionaries MUST 
NOT be used as the type of an attribute, constant or exception field", 
so this has to be:

      Capabilities getCapabilities();
      Constraints  getConstraints();
      Settings     getSettings();

My next point regards the same three lines shown here, but runs deeper.

http://dev.w3.org/2011/webrtc/editor/getusermedia.html#capabilities-constraints-and-settings

I'm troubled by the fact that none of the definitions, Capabilities, 
Constraints (really Constraint, ConstraintSet), or Settings, have webidl 
definitions. I understand why, because they can't, because that would 
depend on context, and webidl does not support templates AFAIK (nor do I 
think it should).

I think the desire to make Constrainable into an abstraction is hurting 
clarity here. I think we're better off promoting Constrainable as a 
/pattern/, and root its description, in this document, in its actual use 
in this document.

This should:

  *   be a lot easier to read,
  *   let us include actual rather than pseudo-webidl, and
  *   avoid confusion about whether constraints from one domain are
    applicable in another (they're not).


http://dev.w3.org/2011/webrtc/editor/getusermedia.html#propertyvaluerange

This abstraction is inefficient in webidl, and should be discouraged:
> dictionaryPropertyValueRange  {
>      any max;
>      any  min;
> };

There are costs and security implications with using 'any' and 'object' 
for any implementation that relies on generated webidl bindings. 
Basically, the generator passes on the cost and risks of parsing the JS 
object to the c++ implementation in these cases, hence this should be 
avoided when possible (it is possible here).

And finally, another minor one:
> dictionaryConstraints  {
>      ConstraintSet?  mandatory  <http://dev.w3.org/2011/webrtc/editor/getusermedia.html#widl-Constraints-mandatory>;
>      Constraint[]    optional  <http://dev.w3.org/2011/webrtc/editor/getusermedia.html#widl-Constraints-optional>;
> };
We should use sequence<> for optional here to pass by value rather than 
by reference.

Also, 'optional' needs to be '_optional' since the former is a reserved 
keyword in webidl. No worries, as the '_' disappears in the generated 
bindings, so this is a detail.

With these changes, we can describe our constraints using webidl:


dictionaryUnsignedLongRange  {
     unsigned long  max;
     unsignedlong  min;
};

dictionary FloatRange  {
     float  max;
     float  min;
};

dictionary MediaTrackConstraintSet {
     (float or FloatRange) frameRate;
     (float or FloatRange) aspectRatio;
     (unsigned long or UnsignedLongRange) width;
     (unsigned long or UnsignedLongRange) height;
     (VideoFacingModeEnum or sequence<VideoFacingModeEnum>) facingMode;
};

typedef MediaTrackConstraintSet MediaTrackConstraint;

dictionary MediaTrackConstraints {
     MediaTrackConstraintSet mandatory;
     sequence<MediaTrackConstraint> _optional;
};

[NoInterfaceObject]
interface MediaTrackConstrainable {
     MediaTrackConstraintSet  getCapabilities();
     MediaTrackConstraints getConstraints();
     MediaTrackConstraintSet  getSettings();
     attribute EventHandler onoverconstrained;
     void applyConstraints (MediaTrackConstraints constraints,
                            VoidFunction successCallback,
                            ConstraintErrorCallback errorCallback);
};

Which I think adds value.

.: Jan-Ivar :.
Received on Wednesday, 13 November 2013 22:24:19 UTC

This archive was generated by hypermail 2.3.1 : Tuesday, 6 January 2015 21:24:43 UTC