Need your opinion: What is most appealing form for GL function bindings?

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|

Need your opinion: What is most appealing form for GL function bindings?

Igor Stasenko
There are multiple GL bindings exists by now
- one that used by Croquet (FFI)
- another one that using Alien

and i doing one more, which using NativeBoost for callouts.

And the question, what form of selectors you like most,
pros/cons .. i need to know, because i can pick any of them,
but i hope, that i will not be only one who using this stuff, so i
need your opinion.

Lets take a usual OpenGL function:

void glVertex3f(GLfloat x, GLfloat y, GLfloat z)

A Croquet/FFI bindings translates it to a following selector:

1. glVertex3f: x with: y with: z

An Alien bindings using following form:

2. glVertex3fX: x y: y z: z

Since my bindings will definitely use underscores, its not a problem
to use a following one:

3. glVertex3f_x: x y: y z: z

Currently i using this one:

4. glVertex3f: x y: y z: z

In private mail with Andreas, he proposed a following:
---
The one thing I'd consider is to use #comma: as the 'standard' keyword
instead of #with: for example:

5. glVertex3f: x comma: y comma: z

The reason should be obvious; you're replacing the comma so it should
be a little more clear than using #with:.
---

6. this option actually not about positional arguments, but about
omitting the 'gl' prefix for each function name.
It is because, you already typing gl at each invocation:

gl glVertex3f: x with: y with: z

so, maybe it worth to omit gl prefix, so, a code will look like:

gl Vertex3f: x with: y with: z

(sure thing, one may use different name for api interface object, not
'gl'.. but i think that in 99.9%
cases, 'gl' is a natural choice).

---

My own choice is [3].
As to me, it helps greatly when you coding,
so, once you autocomplete the selector, you know what parameter you
need at each position,
unlike anonymous keywords, like with: or comma: , which don't telling
you anything about arguments you end up browsing docs each time.
Oh, and btw, each time you need to change something, you again may
need to refer to docs,
since it still may be not clear, what argument types a function
expects even if you look at already working code.

The pro for picking [1] is mainly be compatible with lots of Croquet
code which using GL.
Except that, in NB bindings, i taking a constant names as is , i.e.
GL_LINES, while croquet
uses GLLines. So, its still will require porting.


P.S. i'm already having some stuff working (see attachment).. But i
little bit hesistant to do more, because then , if i reconsider
about selector names, it will require a lot of fixes all around places.
It generating all these methods automatically, so i can change a form
at any moment.
NBOpenGL methodDict size 2063
NBWgl methodDict size  132
NBGlx methodDict size 121

--
Best regards,
Igor Stasenko AKA sig.

_______________________________________________
Pharo-project mailing list
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project

GL viewport.png (46K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Need your opinion: What is most appealing form for GL function bindings?

Schwab,Wilhelm K
Sig,

Since you are focusing on the name of the selector, can I conclude that you are using the selector name to make the call?  I am not sure I like that (strongly suspect I do not).  Dolphin and FFI use a pragma(-ish??) syntax with the return type, function name and argument types explicitly listed.  I very much would like to see you handle the details of getting things on and off of the stack, but I would like to control the selector name and the types.

As an example, calling something

  waveletTransformForward:comma:comma:

is not nearly as helpful to me as

  waveletTransformForward:size:flag:

The selector can be even more informative than that, but hopefully it starts to make the case for the independent selector.

Bill


-----Original Message-----
From: [hidden email] [mailto:[hidden email]] On Behalf Of Igor Stasenko
Sent: Thursday, May 20, 2010 10:48 AM
To: The general-purpose Squeak developers list; Pharo Development
Subject: [Pharo-project] Need your opinion: What is most appealing form for GL function bindings?

There are multiple GL bindings exists by now
- one that used by Croquet (FFI)
- another one that using Alien

and i doing one more, which using NativeBoost for callouts.

And the question, what form of selectors you like most, pros/cons .. i need to know, because i can pick any of them, but i hope, that i will not be only one who using this stuff, so i need your opinion.

Lets take a usual OpenGL function:

void glVertex3f(GLfloat x, GLfloat y, GLfloat z)

A Croquet/FFI bindings translates it to a following selector:

1. glVertex3f: x with: y with: z

An Alien bindings using following form:

2. glVertex3fX: x y: y z: z

Since my bindings will definitely use underscores, its not a problem to use a following one:

3. glVertex3f_x: x y: y z: z

Currently i using this one:

4. glVertex3f: x y: y z: z

In private mail with Andreas, he proposed a following:
---
The one thing I'd consider is to use #comma: as the 'standard' keyword instead of #with: for example:

5. glVertex3f: x comma: y comma: z

The reason should be obvious; you're replacing the comma so it should be a little more clear than using #with:.
---

6. this option actually not about positional arguments, but about omitting the 'gl' prefix for each function name.
It is because, you already typing gl at each invocation:

gl glVertex3f: x with: y with: z

so, maybe it worth to omit gl prefix, so, a code will look like:

gl Vertex3f: x with: y with: z

(sure thing, one may use different name for api interface object, not 'gl'.. but i think that in 99.9% cases, 'gl' is a natural choice).

---

My own choice is [3].
As to me, it helps greatly when you coding, so, once you autocomplete the selector, you know what parameter you need at each position, unlike anonymous keywords, like with: or comma: , which don't telling you anything about arguments you end up browsing docs each time.
Oh, and btw, each time you need to change something, you again may need to refer to docs, since it still may be not clear, what argument types a function expects even if you look at already working code.

The pro for picking [1] is mainly be compatible with lots of Croquet code which using GL.
Except that, in NB bindings, i taking a constant names as is , i.e.
GL_LINES, while croquet
uses GLLines. So, its still will require porting.


P.S. i'm already having some stuff working (see attachment).. But i little bit hesistant to do more, because then , if i reconsider about selector names, it will require a lot of fixes all around places.
It generating all these methods automatically, so i can change a form at any moment.
NBOpenGL methodDict size 2063
NBWgl methodDict size  132
NBGlx methodDict size 121

--
Best regards,
Igor Stasenko AKA sig.

_______________________________________________
Pharo-project mailing list
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
Reply | Threaded
Open this post in threaded view
|

Re: Need your opinion: What is most appealing form for GL function bindings?

Henrik Sperre Johansen
  On 20.05.2010 19:42, Schwab,Wilhelm K wrote:

> Sig,
>
> Since you are focusing on the name of the selector, can I conclude that you are using the selector name to make the call?  I am not sure I like that (strongly suspect I do not).  Dolphin and FFI use a pragma(-ish??) syntax with the return type, function name and argument types explicitly listed.  I very much would like to see you handle the details of getting things on and off of the stack, but I would like to control the selector name and the types.
>
> As an example, calling something
>
>    waveletTransformForward:comma:comma:
>
> is not nearly as helpful to me as
>
>    waveletTransformForward:size:flag:
>
> The selector can be even more informative than that, but hopefully it starts to make the case for the independent selector.
>
> Bill
No, but he is automatically generating the interface from a spec file,
thus some standard for how to convert it to a selector is needed.

If he's using the NB FFI convention we discussed some time ago, the only
"magic" is that the arg names are used in the apiCall specification.
Example copy-pasted from the announcement of that functionality:

primGetModuleFileName: hModule with: lpFileName with: nSize
        <primitive: #primitiveNativeCall module: #NativeBoostPlugin>

        ^ NBFFICallout
                apiCall: #(
                        DWORD GetModuleFileName (
                                HMODULE hModule,
                                LPTSTR lpFilename,
                                DWORD nSize))
                module: #Kernel32
                options: #( - coerceNilToNull )

Cheers,
Henry



_______________________________________________
Pharo-project mailing list
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
Reply | Threaded
Open this post in threaded view
|

Re: Need your opinion: What is most appealing form for GL function bindings?

Henrik Sperre Johansen
In reply to this post by Igor Stasenko
  On 20.05.2010 17:47, Igor Stasenko wrote:

> There are multiple GL bindings exists by now
> - one that used by Croquet (FFI)
> - another one that using Alien
>
> and i doing one more, which using NativeBoost for callouts.
>
> And the question, what form of selectors you like most,
> pros/cons .. i need to know, because i can pick any of them,
> but i hope, that i will not be only one who using this stuff, so i
> need your opinion.
>
> Lets take a usual OpenGL function:
>
> void glVertex3f(GLfloat x, GLfloat y, GLfloat z)
>
For me, 3 + 6 seems the nicest, for the reasons you mentioned.
(method names starting in lower case though, so gl vertex3f_x: x y: y z: z).

Cheers,
Henry

PS. That particular method was deprecated in 3.0 and removed in 3.1
though, right? ;)

_______________________________________________
Pharo-project mailing list
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
Reply | Threaded
Open this post in threaded view
|

Re: Need your opinion: What is most appealing form for GL function bindings?

Igor Stasenko
In reply to this post by Henrik Sperre Johansen
On 20 May 2010 21:50, Henrik Sperre Johansen
<[hidden email]> wrote:

>  On 20.05.2010 19:42, Schwab,Wilhelm K wrote:
>>
>> Sig,
>>
>> Since you are focusing on the name of the selector, can I conclude that
>> you are using the selector name to make the call?  I am not sure I like that
>> (strongly suspect I do not).  Dolphin and FFI use a pragma(-ish??) syntax
>> with the return type, function name and argument types explicitly listed.  I
>> very much would like to see you handle the details of getting things on and
>> off of the stack, but I would like to control the selector name and the
>> types.
>>
>> As an example, calling something
>>
>>   waveletTransformForward:comma:comma:
>>
>> is not nearly as helpful to me as
>>
>>   waveletTransformForward:size:flag:
>>
>> The selector can be even more informative than that, but hopefully it
>> starts to make the case for the independent selector.
>>
>> Bill
>
> No, but he is automatically generating the interface from a spec file, thus
> some standard for how to convert it to a selector is needed.
>
> If he's using the NB FFI convention we discussed some time ago, the only
> "magic" is that the arg names are used in the apiCall specification.
> Example copy-pasted from the announcement of that functionality:
>
> primGetModuleFileName: hModule with: lpFileName with: nSize
>        <primitive: #primitiveNativeCall module: #NativeBoostPlugin>
>
>        ^ NBFFICallout
>                apiCall: #(
>                        DWORD GetModuleFileName (
>                                HMODULE hModule,
>                                LPTSTR lpFilename,
>                                DWORD nSize))
>                module: #Kernel32
>                options: #( - coerceNilToNull )
>

Right, you are free to change it to anything you like. But it would be
unwise to poke manually with more
than 2500 functions (i listed the numbers earlier), so there is an
automated process which generating code for them.

Here is how generated method looks like:

glDrawArraysInstancedARB: mode first: first count: count primcount: primcount
        "This method was automatically generated from OpenGL specs"
        "See http://squeaksource.com/OpenGLSpecs for details"
        <primitive: #primitiveNativeCall module: #NativeBoostPlugin>

        ^ self
                glApiCall: #( void glDrawArraysInstancedARB ( GLenum mode , long
first , GLsizei count , GLsizei primcount ) )
                attributes: #(
                        #alias 'DrawArraysInstanced'
                        #category #'ARB_draw_instanced'
                        #version #'2.0'
                )

As you may see, in addition to function prototype 'void
glTbufferMask3DFX ( GLuint mask )'
it contains an additional meta-information, which could be userful to
diagnose problem, if call fails.

And as an example, how you can change it, here it is:

choosePixelFormat

        <primitive: #primitiveNativeCall module: #NativeBoostPlugin>
       
        ^ NBFFICallout
                stdcall: #( int ChoosePixelFormat (
                        HDC  dc ,
                        GLPixelFormatDescriptor pixelFormat
                )) module: #gdi32
               
as you can see, this method doesn't taking any arguments, while
function expects 2.
Still its a working implementation.
A dc and pixelFormat is an instance variables of method's receiver,
and NBFFICallout knows
how to deal with it.


> Cheers,
> Henry
>
>
>
> _______________________________________________
> Pharo-project mailing list
> [hidden email]
> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
>



--
Best regards,
Igor Stasenko AKA sig.

_______________________________________________
Pharo-project mailing list
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
Reply | Threaded
Open this post in threaded view
|

Re: Need your opinion: What is most appealing form for GL function bindings?

Igor Stasenko
In reply to this post by Henrik Sperre Johansen
On 20 May 2010 21:51, Henrik Sperre Johansen
<[hidden email]> wrote:

>  On 20.05.2010 17:47, Igor Stasenko wrote:
>>
>> There are multiple GL bindings exists by now
>> - one that used by Croquet (FFI)
>> - another one that using Alien
>>
>> and i doing one more, which using NativeBoost for callouts.
>>
>> And the question, what form of selectors you like most,
>> pros/cons .. i need to know, because i can pick any of them,
>> but i hope, that i will not be only one who using this stuff, so i
>> need your opinion.
>>
>> Lets take a usual OpenGL function:
>>
>> void glVertex3f(GLfloat x, GLfloat y, GLfloat z)
>>
> For me, 3 + 6 seems the nicest, for the reasons you mentioned.
> (method names starting in lower case though, so gl vertex3f_x: x y: y z: z).
>
Ok,
with one exception, i think.

For funtions which taking just a single argument, like:

void glMatrixMode ( GLenum mode )

i think it would be better to not append an argument name i.e.

gl matrixMode: foo

instead of

gl matrixMode_mode: foo

Because in most cases, there is enough information about it from a
function name itself,
and argument name in selector just adds a noise:

void glColor3fv ( GLfloat* v )

gl color3fv: foo

instead of

gl color3fv_v: foo



> Cheers,
> Henry
>
> PS. That particular method was deprecated in 3.0 and removed in 3.1 though,
> right? ;)
>
> _______________________________________________
> Pharo-project mailing list
> [hidden email]
> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
>



--
Best regards,
Igor Stasenko AKA sig.

_______________________________________________
Pharo-project mailing list
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
Reply | Threaded
Open this post in threaded view
|

Re: [squeak-dev] Need your opinion: What is most appealing form for GL function bindings?

Lukas Renggli
In reply to this post by Igor Stasenko
     7. gl glVertex3f(x, y, z)
     http://scg.unibe.ch/research/helvetia/examples#155976728

Ok, that requires quite some support code and doesn't work in the
latest Pharo yet, but is also something to consider :-)

Lukas

On 20 May 2010 17:47, Igor Stasenko <[hidden email]> wrote:

> There are multiple GL bindings exists by now
> - one that used by Croquet (FFI)
> - another one that using Alien
>
> and i doing one more, which using NativeBoost for callouts.
>
> And the question, what form of selectors you like most,
> pros/cons .. i need to know, because i can pick any of them,
> but i hope, that i will not be only one who using this stuff, so i
> need your opinion.
>
> Lets take a usual OpenGL function:
>
> void glVertex3f(GLfloat x, GLfloat y, GLfloat z)
>
> A Croquet/FFI bindings translates it to a following selector:
>
> 1. glVertex3f: x with: y with: z
>
> An Alien bindings using following form:
>
> 2. glVertex3fX: x y: y z: z
>
> Since my bindings will definitely use underscores, its not a problem
> to use a following one:
>
> 3. glVertex3f_x: x y: y z: z
>
> Currently i using this one:
>
> 4. glVertex3f: x y: y z: z
>
> In private mail with Andreas, he proposed a following:
> ---
> The one thing I'd consider is to use #comma: as the 'standard' keyword
> instead of #with: for example:
>
> 5. glVertex3f: x comma: y comma: z
>
> The reason should be obvious; you're replacing the comma so it should
> be a little more clear than using #with:.
> ---
>
> 6. this option actually not about positional arguments, but about
> omitting the 'gl' prefix for each function name.
> It is because, you already typing gl at each invocation:
>
> gl glVertex3f: x with: y with: z
>
> so, maybe it worth to omit gl prefix, so, a code will look like:
>
> gl Vertex3f: x with: y with: z
>
> (sure thing, one may use different name for api interface object, not
> 'gl'.. but i think that in 99.9%
> cases, 'gl' is a natural choice).
>
> ---
>
> My own choice is [3].
> As to me, it helps greatly when you coding,
> so, once you autocomplete the selector, you know what parameter you
> need at each position,
> unlike anonymous keywords, like with: or comma: , which don't telling
> you anything about arguments you end up browsing docs each time.
> Oh, and btw, each time you need to change something, you again may
> need to refer to docs,
> since it still may be not clear, what argument types a function
> expects even if you look at already working code.
>
> The pro for picking [1] is mainly be compatible with lots of Croquet
> code which using GL.
> Except that, in NB bindings, i taking a constant names as is , i.e.
> GL_LINES, while croquet
> uses GLLines. So, its still will require porting.
>
>
> P.S. i'm already having some stuff working (see attachment).. But i
> little bit hesistant to do more, because then , if i reconsider
> about selector names, it will require a lot of fixes all around places.
> It generating all these methods automatically, so i can change a form
> at any moment.
> NBOpenGL methodDict size 2063
> NBWgl methodDict size  132
> NBGlx methodDict size 121
>
> --
> Best regards,
> Igor Stasenko AKA sig.
>
>
>
>



--
Lukas Renggli
www.lukas-renggli.ch

_______________________________________________
Pharo-project mailing list
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
Reply | Threaded
Open this post in threaded view
|

Re: [squeak-dev] Need your opinion: What is most appealing form for GL function bindings?

Igor Stasenko
Hello , all
i made a decision

I'd like to thank you for your help.

Please, forgive me, if its not your favorite choice.
It is hard to make everyone happy.

So, here the winner:

readPixels_x: "in" x y: "in" y width: "in" width height: "in" height
format: "in" format type: "in" type pixels: "out" pixels
        "This method was automatically generated from OpenGL specs"
        "See http://squeaksource.com/OpenGLSpecs for details"
        <primitive: #primitiveNativeCall module: #NativeBoostPlugin>

        ^ self
                glApiCall: #( void glReadPixels ( GLint x , GLint y , GLsizei width
, GLsizei height , GLenum format , GLenum type , GLvoid* pixels ) )
                index: 1334
                attributes: #(
                        #category #'VERSION_1_0'
                        #version #'1.0'
                )


For 1-arg:

arrayElement: "in" i
        "This method was automatically generated from OpenGL specs"
        "See http://squeaksource.com/OpenGLSpecs for details"
        <primitive: #primitiveNativeCall module: #NativeBoostPlugin>

        ^ self
                glApiCall: #( void glArrayElement ( long i ) )
                index: 15
                attributes: #(
                        #category #'VERSION_1_1_DEPRECATED'
                        #deprecated #'3.1'
                        #version #'1.1'
                )



--
Best regards,
Igor Stasenko AKA sig.

_______________________________________________
Pharo-project mailing list
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project