[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Public WebGL] Adding types to signatures in detail boxes



On Apr 27, 2010, at 7:10 PM, Kenneth Russell wrote:

> On Tue, Apr 27, 2010 at 12:10 PM, Chris Marrin <cmarrin@apple.com> wrote:
>> 
>> On Apr 26, 2010, at 6:18 PM, Kenneth Russell wrote:
>> 
>>> On Fri, Mar 5, 2010 at 3:42 PM, Chris Marrin <cmarrin@apple.com> wrote:
>>>> 
>>>> On Mar 2, 2010, at 3:21 PM, Kenneth Russell wrote:
>>>> 
>>>>> Currently the method signatures in the (green) detail boxes throughout
>>>>> the spec omit the types which are in the IDL snippets in the gray
>>>>> boxes.
>>>>> 
>>>>> This seems to have been done to follow the pattern in the Canvas spec,
>>>>> but I find it annoying. In particular, it makes it very difficult to
>>>>> document overloaded methods.
>>>>> 
>>>>> I would like to make a pass through the spec and add the types (and
>>>>> overloadings) from the gray boxes into the method signatures in the
>>>>> green boxes. Are there any objections to my doing this?
>>>> 
>>>> 
>>>> It annoys me, too. But yes it was done to match the Canvas spec (and many other W3C spec styles). If it can be done without adding too much noise, I would be all for adding types.
>>> 
>>> Apologies for the long delay; I've finally made this edit. It included
>>> removing the "in" keyword for all function arguments, as it is
>>> implicit in the Web IDL spec, and adding a new .idl-code CSS style to
>>> handle indentation of the second and subsequent lines if the function
>>> signature wraps. Layout should work properly for the overloaded method
>>> descriptions.
>>> 
>>> What do you all think? In general I think this is an improvement.
>>> There is a proliferation of uniform* and vertexAttrib* entry points,
>>> but perhaps we could abbreviate those. For example:
>>> 
>>>    void uniform1f(WebGLUniformLocation location, GLfloat x)
>>>    void uniform1i(WebGLUniformLocation location, GLint x)
>>>    void uniform2f(WebGLUniformLocation location, GLfloat x, GLfloat y)
>>>    void uniform2i(WebGLUniformLocation location, GLint x, GLint y)
>>>    void uniform3f(WebGLUniformLocation location, GLfloat x, GLfloat
>>> y, GLfloat z)
>>>    void uniform3i(WebGLUniformLocation location, GLint x, GLint y, GLint z)
>>>    void uniform4f(WebGLUniformLocation location, GLfloat x, GLfloat
>>> y, GLfloat z, GLfloat w)
>>>    void uniform4i(WebGLUniformLocation location, GLint x, GLint y,
>>> GLint z, GLint w)
>>>    void uniform[1234]fv(WebGLUniformLocation location, WebGLFloatArray v)
>>>    void uniform[1234]fv(WebGLUniformLocation location, sequence<float> v)
>>>    void uniform[1234]iv(WebGLUniformLocation location, WebGLIntArray v)
>>>    void uniform[1234]iv(WebGLUniformLocation location, sequence<long> v)
>> 
>> 
>> This is a big improvement. Thanks, Ken.
> 
> You're welcome. What do you think about using the above shorthand for
> the uniform and other entry points?

I'm not sure how I feel about it. The fact that you can't shorten the non-vector forms (because of differing types) makes it inconsistent, which could lead to confusion. What about:

	void uniform[1234][fi](WebGLUniformLocation location, ...)
	void uniform[1234][fi]v(WebGLUniformLocation location, ...)

Leaving off the additional parameters in this case is not that bad. But maybe it is. I guess I think we should try to collapse everything or nothing.

-----
~Chris
cmarrin@apple.com




-----------------------------------------------------------
You are currently subscribe to public_webgl@khronos.org.
To unsubscribe, send an email to majordomo@khronos.org with
the following command in the body of your email: