66. 3D – managing parameter lists

I find that 3D functions can have so many parameters that it gets difficult to get them right. This post provides a solution – named parameters – which I’ll use in future posts.

(If this isn’t exciting enough, tomorrow we create hills, and the next day, we make darkness).

The problem

I’ll use this function that we’ve used before, as an example. It isn’t the worst – I have one with twice as many parameters!

function AddFourWalls(x,y,z,w,h,d,img,s)

If I provide this function for you to use, with instructions on what everything is, it is still very easy to get things in the wrong place, or waste time going back to the instructions several times. And if you’re trying to find a small problem somewhere, it can be messy trying to figure out what all the numbers mean, in something like this:

AddFourWalls(200,0,300,300,19,50,i,.1)

Using named parameters

Suppose you are able to call the function like this, instead

AddFourWalls(x=200,y=0,z=300,width=300,height=19,depth=50,img=i,scaling=.1)

it is much easier to enter the values without mistakes, or figure out what is going on, later. So named parameters can make it easier to work with complex functions, and can reduce errors.

The other advantage is that you can name parameters in any order you like, and leave out any that you don’t want – whereas if you just provide a list of values, then you can’t leave any out, because if you do, the function will get them in the wrong order.

It isn’t hard to do this, because a table can hold named values, so all we have to do is make our named list into a table by adding {}, like so

AddFourWalls({x=200,y=0,z=300,width=300,height=19,depth=50,img=i,scaling=.1})

Then, in the AddFourWalls function, we can take each of the named values and put them into the variables we want to use, like this

function AddFourWalls(p)
x=p.x
y=p.y
….etc

Providing a choice

I’d like to go a bit further, and be able to provide either a list of values or a named list. You don’t have to read this if it doesn’t interest you, but it uses a nice Lua trick.

That trick is that if you write

function AddFourWalls(…)

then all your parameters will be contained in something called arg (short for arguments).

If you provide a list of items, then arg will be a table of those items, ie arg[1]=x, arg[2]=y, …..

If you provide a table of named parameters, that table will be in arg[1], so arg[1].x=x, arg[1].y=y, etc.

So I wrote a function called Params that takes arg, and a list of all the parameter names in the right order, and returns a list of parameter values no matter what you provide. They can then be assigned to the variables you want to use in your function.

For the AddFourWalls function, this is the result

function AddFourWalls(...)
    local x,y,z,w,h,d,img,s=Params(
        {'x','y','z','width','height','depth',
                 'img','scaling'},arg)

So now I can call this function in two ways

    AddFourWalls(200,0,300,300,19,50,i,.1)
    AddFourWalls({x=200,y=0,z=300,width=300,height=19,
                      depth=50,img=i,scaling=.1})

Here is my Params function, nothing too clever about it.

function Params(list,tbl) --tbl is params
    if type(tbl[1])=="table" then --was named table
        local t={} --match the named params with the list provided
        for n,v in pairs(tbl[1]) do
            for i=1,#list do
               if n==list[i] then t[i]=v break end
            end
        end
        return unpack(t)
    else --was an unnamed list, return it as is
       return unpack(tbl)
    end
end