W3C home > Mailing lists > Public > public-audio@w3.org > April to June 2012

Re: [Bug 17334] (setTargetValueAtTime): AudioParam.setTargetValueAtTime is misleading and underdefined

From: Marcus Geelnard <mage@opera.com>
Date: Fri, 29 Jun 2012 10:20:09 +0200
To: "olivier Thereaux" <olivier.thereaux@bbc.co.uk>, "Chris Rogers" <crogers@google.com>
Cc: "Ray Bellis" <ray@bellis.me.uk>, public-audio@w3.org
Message-ID: <op.wgnn3vz1m77heq@mage-desktop>
Den 2012-06-28 20:26:05 skrev Chris Rogers <crogers@google.com>:

> On Thu, Jun 28, 2012 at 9:16 AM, olivier Thereaux <
> olivier.thereaux@bbc.co.uk> wrote:
>> hi Ray,
>> On 28 Jun 2012, at 16:48, Ray Bellis wrote:
>> > On 28/06/2012 15:23, olivier Thereaux wrote:
>> >
>> >> However… I may be misunderstanding the essence of this method, but
>> >> aren't we talking about a value to be reached at a certain time (or,
>> >> in other words, a value pre-set for a given time)?
>> >
>> > I think you must made my point for me ;-)
>> Always happy to helps ;)
>> > Chris Rogers described it thus:
>> >
>> > "It's a *target* value which we start approaching at precisely the  
>> time
>> > given."
>> >
>> > which I read to mean that the time given is the _start_ of the curve,
>> > not the end of it.
>> I hadn't read it that way, but now that you mention it, yes, it makes  
>> more
>> sense.
>> Chris, any thought? I wouldn't want to impose the change of name if it  
>> is
>> typical in most software APIs, but I am sensitive to the points made by  
>> Ray
>> and Philip.
> This is one method in a family of methods which include "AtTime" in their
> name:
> setValueAtTime()
> linearRampToValueAtTime()
> exponentialRampToValueAtTime()
> setTargetValueAtTime()
> setValueCurveAtTime()
> So I think it's important to maintain consistency here.  Also, I believe
> the name describes precisely what it does.  In other words, the "target
> value" is set at the time given (which for all the methods is the time of
> the event in the time-ordered event list):
> https://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html#methodsandparams-AudioParam

Once you understand what the function does, the name makes sense. However,  
the name alone does not make it easy to understand what it does.

I think that the confusion (at least for me) is that "setTargetValue" is  
very similar to "setValue", and I fear that many will have them mixed up.  
Generally speaking, the "set" term indicates a zero-duration operation.  
I'd much rather see that methods that cause gradual changes use a  
consistent naming convention, excluding the term "set".

I think that a more appropriate name could be "approachValueAtTime" or  

Similarly the name "setValueCurveAtTime" would do better without "set".  
Any suggestions? (I'm out of ideas right now)


Marcus Geelnard
Core Graphics Developer
Opera Software ASA
Received on Friday, 29 June 2012 08:20:51 UTC

This archive was generated by hypermail 2.3.1 : Tuesday, 6 January 2015 21:49:59 UTC