Positional Arguments

After I read [ RaabSPD5 ] I thought to have a look at methods with positional arguments sooner or later. Now I found some time during the holidays to have a closer look at the subject and you might enjoy reading about it. On the one hand it might be helpful for squeak programmers who are maintaining an API for an external library in squeak or planing to write one. On the other hand it describes a possible way to learn OpenGL within squeak using examples presented in standard text books.

One bridge for programmers to the "outer world" in squeak is the foreign function interface FFI. It can be used to call functions in external shared libraries from squeak methods. The FFI takes care of parameter type conversion, the right order and size of parameters on the stack and converting results back into squeak objects. Before one can call a specific external function, a corresponding method has to be written in squeak.

	strlen: aString
		<apicall: long 'strlen' (char *) module: 'c'>
		^self externalCallFailed
      

module names

At least on Unix the FFI system tries to be clever in guessing where to find shared libraries. In the above example squeak looks for a library named c, c.so, c.dylib, libc, libc.so or libc.dylib in the current directory. If this fails it starts the same search in other "well known" directories like /lib or /usr/lib using compiled in defaults and the environment variables SQUEAK_PLUGIN_PATH and LD_LIBRARY_PATH. If the library you want to use can't be found by that procedure or follows an unusual naming scheme, you have to tell FFI the exact name and/or location of the library. For the above to work on my system I had to specify the exact name libc.so.6 instead of just c.

In Example 1 you can see a method that defines a callout to the function strlen in the standard C library. The function strlen expects a pointer to a null terminated C string and returns the length of the string as an integer. The FFI takes care of converting the string object aString into a C string before the function strlen gets called. The result of the function will be converted back into an integer object, which will be the return value of the method strlen:. The code below the <apicall:module:> declaration only gets executed in case of an error (e.g library not found) and serves as a fallback. In the example an appropriate error will be raised.

Now the selector strlen: could be used in a message to the class CApi in the usual way. Example 2 shows some code fragment assuming the method strlen: had been implemented as a class side method of the class CApi.

	| size string |
	string ← 'SqueakString'.
	size ← CApi strlen: string.
	Transcript show: size printString; cr.
      

Now it seems easy enough to write the corresponding API methods for several library functions and just use them in squeak^[1]. But there is the question how the API method names should be chosen. The main aim should be that the names should match the ones of the C API as far as possible. So programmer who are familiar with a C API should be able to use the same API from within squeak without too many surprises. This also makes it more likely, that a squeak programmer could benefit from consulting the documentation, tutorials, HOWTOs and examples that exists for the C API.

Some good guidelines for naming API methods could be:

Methods with positonal arguments are currently only available in the latest version of croquet, but can be also used in the current development branch^[3] of squeak after filein of [ PosArgsCS ]. In Example 3 there is the same method once defined with the common keyword method pattern and once with positionl arguments. Below in Example 4 is some sample code to illustrate the difference in message sending.

	  apiRoundRect: aHDC with: left with: top with: right with: bottom with: width with: height
	  	<apicall: bool 'RoundRect' (Win32HDC long long long long long long) module: 'gdi32.dll'>
	  	^ self externalCallFailed
	

	  apiRoundRect(aHDC, left, top, right, bottom, width, height)
	  	<apicall: bool 'RoundRect' (Win32HDC long long long long long long) module: 'gdi32.dll'>
	  	^ self externalCallFailed
	

	  roundRectangle: aRect width: width height: height 
	  	^self
	  		apiRoundRect: self
			with: aRect left
			with: aRect top
			with: aRect right
			with: aRect bottom
			with: width
			with: height
	

	  roundRectangle: aRect width: width height: height 
	  	^self
	  		apiRoundRect(self, aRect left, aRect top, aRect right, aRect bottom, width, height)
	

So what are the benefits of using positional arguments? In the use case of API methods I think they are the best way to achieve the aim from above. That was the easy usage of an API in squeak that conforms to what is described in existing documentation.

Now let's see how it feels to use one particular API from within squeak. To be able to use OpenGL we need the corresponding API methods. One can find the C prototypes of the OpenGL API functions in [OGL] for example and it is easy enough to write the API methods in squeak for a few functions. But there are about 150 distinct functions in OpenGL not counting their variations. Luckily somebody already has done the work for us^[4]. The OpenGL API is part of the latest version of croquet, but can be used with the current development branch^[3] of squeak too, after the filein of [ GLXCS ]^[5]. Now we just need a little playground where we can experiment with OpenGL. A modified version of the OpenGLMorph from croquet available at [ OGLMorphCS ] is all that we need.

Now let's have a look at the first OpenGL example in [OGL], which can be seen in Example 5. After we filed in all the changesets mentioned above, we have all "whateverWeNeed". The method were we place our OpenGL code resides in the OpenGLMorph and is surely not named main but glRenderOn:. Instead of a window we have an OpenGLMorph that also takes care of all initialization and updating. Now we can write the actual OpenGL code into the method. Example 6 shows how the method looks like.

	#include <whateverYouNeed.h>
	
	main() {
	
		InitializeAWindowPlease();

		glClearColor (0.0, 0.0, 0.0, 0.0);
		glClear (GL_COLOR_BUFFER_BIT);
		glColor3f (1.0, 1.0, 1.0);
		glOrtho (0.0, 1.0, 0.0, 1.0, -1.0, 1.0);
		glBegin (GL_POLYGON);
			glVertex3f (0.25, 0.25, 0.0);
			glVertex3f (0.75, 0.25, 0.0);
			glVertex3f (0.75, 0.75, 0.0);
			glVertex3f (0.25, 0.75, 0.0);
		glEnd();
		glFlush();

		UpdateTheWindowAndCheckForEvents();
	}
      

	glRenderOn: aRenderer
		aRenderer
			glClearColor(0.0, 0.0, 0.0, 0.0);
			glClear(GLColorBufferBit);
			glColor3f(1.0, 1.0, 1.0);
			glOrtho(0.0, 1.0, 0.0, 1.0, -1.0, 1.0);
			glBegin(GLPolygon);
				glVertex3f(0.25, 0.25, 0.0);
				glVertex3f(0.75, 0.25, 0.0);
				glVertex3f(0.75, 0.75, 0.0);
				glVertex3f(0.25, 0.75, 0.0);
			glEnd();
			glFlush()
      

If you evaluate OpenGLMorph new openInWorld you should see a white rectangle on black background^[6].