Re: [w3ctag/spec-reviews] Ambient Light Sensor API (#115)

> * There's only a single example and no linked explainer document that would provide deeper understanding of how the various bits get used together. I think this would be clarifying both for the reader and the authors.

So I tried to provide some of this in the Generic Sensor API, notably in the [Background](https://w3c.github.io/sensors/#background) and [Concepts](https://w3c.github.io/sensors/#concepts) sections. Agree this still needs work.

> * The example (singular?) doesn't show how to use the Permission API in conjunction with the Ambient Light API, which seems pretty critical to actual use.

Yes. The Permission API is missing critical pieces for proper integration. @jyasskin is actively working on this as we speak. I'll revisit this and clean it up as soon as his changes have landed.

> Questions about the semantics (mostly out of ignorance, thanks for being patient with me):
> 
> * While I understand that the Generic Sensor API returns undefined for start() and stop(), it'd seem that individual sensors should probably return promises from these calls so that the start and stop operations can report errors

I'm waiting for cancelable promises for this (tracked here: https://github.com/w3c/sensors/issues/94).

> * There's no definition for what onstatechange would do. Does that report start/stop state? Are those inspectable in some other way?

Yeah, these are still [todos in the Generic Sensor API](https://w3c.github.io/sensors/#sensor-onstatechange) . Sensor objects have a `state` attribute which moves from `idle` -> `activating` -> `active` -> `idle`/`errored`. `statechange` events are fired on each transition from one of these states to another.

Maybe some sequence diagrams would help understand whats going on here. I'll give those a try.

> * The use of Constructors looks good!

Thanks.

> * What's the model for multiple clients of a sensor like this? I get that AmbientLightSensor likely doesn't have any difficulty multiplexing the data, there will be some sensors that may want to allow writing values and other sorts of configuration that can be considered "exclusive". How does the generic sensor API handle this?

It doesn't, because the underlying APIs won't let you do this. For example, on Android, if one app requires a sensor to be polled at 100Hz, all apps will get data at this frequency. When another app shows up and asks for a higher frequency, all apps will get the new one.

A similar model is used at the Web level in the Generic Sensor API. Basically, the UA compiles the needs of all Sensor objects and serves everyone of them with the most stringent requirements.

> And is "sensor state" meant to be mapped to the hardware sensor or specific to the software reflection that the object in question provides (which might be different than the hardware state)?

The latter. It's not possible to know from the underlying APIs whether a sensor is being used by another app or not (though it's certainly possible to infer this through timing attacks, etc.).

> For instance, [this](https://w3c.github.io/sensors/#sensor-reading) isn't particularly illuminating (pardon the pun).

This is in reference to the Sensor object's state (not the underlying HW). That said, when the state is "active," so is the underlying hardware, unless there's an error that hasn't been surfaced to the UA layer yet.

> * Requests for permissions aren't modeled in this API. Is the assumption that navigator.permissions.request() will be used here?

Yes. Through the Generic Sensor API, as soon as @jyasskin's changes have landed. 

> * Are these sensors available from within worker contexts? They don't appear to be from the IDL but maybe I'm missing some prose?

They're not.

> Shouldn't they be (modulo permissions request issues)?

That's a level 2 feature. Tracked here: https://github.com/w3c/sensors/issues/12

> * Glad to see these restricted to Secure Contexts. Nice work.

Copy/pasting boilerplate from @mikewest's spec made that dead easy. I can't claim any credit.

> Has there been any consideration of top-level browsing contexts vs. iframes? (cc: @mikewest)

Yes. [Here](https://w3c.github.io/sensors/#browsing-context) and [there](https://w3c.github.io/sensors/#sensor-task-source).

> * How does the sensor processing model get defined?

I guess the closest answer to this question is [here](https://w3c.github.io/sensors/#observe-a-sensor) which is currently curiously missing a step to tell the underlying sensor what to do in a UA-specific way. Need to fix this.

> If it's a frequency model, what happens when it's faster than the swap-buffer rate (e.g. requestAnimationFrame timing)?

That's a desired feature, actually, to lower latency (e.g. the Oculus Rift polls the gyroscope at 1KHz for this very reason). Frequency is capped at the HW limits of the sensor (First sub-step of the [Observe a Sensor abstract operation](https://w3c.github.io/sensors/#observe-a-sensor).

> * This is a bit first-pass, and would be happy to do a deeper review. Let me know if that'd be useful.

Thanks a bunch. What I'm getting out of this loud and clear is that the processing model needs to be explained much more clearly and upfront in the Generic Sensor spec. I'm happy for you to dig more deeply either right away or wait until I'm done with those edits.

---
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3ctag/spec-reviews/issues/115#issuecomment-204601582