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

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



On Wed, Apr 28, 2010 at 10:46 AM, Chris Marrin <cmarrin@apple.com> wrote:
>
> 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.

Upon further thought I agree with your suggestion and it does shorten
this portion of the spec significantly. As another data point Jacob
Seidelin coalesces these functions in the same way in his WebGL cheat
sheet at http://www.nihilogic.dk/labs/webgl_cheat_sheet/WebGL_Cheat_Sheet.htm
. I've checked in this change.

-Ken

-----------------------------------------------------------
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: