This is part 2 of my tutorial on using the Racket FFI. If you haven’t read part 1 yet, you can find it here. Update: part 3 is also now available here.

Part 2 will continue with more Cairo examples. In this installment, I plan to go over some more advanced FFI hacking such as handling computed argument values, custom return arguments, and using C structs.

First, here’s the core code from part 1 condensed and re-arranged into an example that you can copy and paste into your definitions area:

Dashes and array arguments

To start off, let’s look at another C example from the Cairo samples page. This time we will look at the "dash" example, which has a use of an input array:

The most interesting function here is cairo_set_dash, which takes an array argument. The only other new functions are cairo_rel_line_to and cairo_curve_to which have very straightforward C types:

Meanwhile, the C type signature for cairo_set_dash from the Cairo docs looks like this:

Something to note about the arguments is that num_dashes encodes the length of the array dashes. This will come up later when we want to make the C type for this function more convenient.

On the Racket side, it’s natural to represent the array of dashes as either a list or vector of numbers. Given that, a fairly literal translation of the C type above might look like the following:

This type includes a type constructor we haven’t seen yet: _list. This is a so-called custom function type that has special meaning inside of a _fun type. It lets you convert between a Racket list and a C array. Since arrays are often used for both input and output of a C function, the constructor requires you to specify the mode in which you are using the array.

Since we only want to provide a list from the Racket side to C, we’ll use the i input mode. We can then call the function like this:

Note that because of how we defined the type of cairo-set-dash we had to provide the length of the input list as a separate argument! This seems pretty silly since it’s very easy to get the length of a Racket list and because this is a likely source of mistakes. It would be preferable to compute the length argument automatically.

Luckily, the _fun type constructor actually lets you do this with the (name : type) syntax for naming arguments in combination with the (type = expr) syntax for supplying computed arguments:

When a computed argument is specified with a =, it’s not necessary to provide the argument on the Racket side. So cairo-set-dash is now an arity 3 function that can be called like this:

This means we’ll never make a mistake in passing the length argument to Cairo. Just as an aside, it’s also possible to use Racket vectors instead of lists by using the _vector type constructor.

Putting it all together, we can reproduce the dashes example like this:

Result arguments and C structs

For some more advanced FFI hacking, let’s consider the problem of drawing some text into a predetermined space. In particular, we have our usual 256x256 bitmap that we want to draw some text into:

Our challenge is to make a Racket function that takes a string (let’s assume we can draw it in one line) and draws it into this bitmap. Since we are taking an arbitrary string, we will need to figure out how to scale the text to fit. To make it simple, let’s just scale the text to fit the width and assume the height will be okay.

To implement the key step of measuring the text size, we can use the cairo_text_extents function. Its type signature is as follows:

The interesting part of this signature is that cairo_text_extents_t is a struct type:

We haven’t yet seen how to handle C structs with the FFI, but it’s not too tricky. Support for C structs comes built-in and will look familiar if you’re used to Racket structs. We can directly translate the documented definition above into a define-cstruct declaration:

This declaration does a couple of things. First, it defines a bunch of handy C types related to the struct for us:

Along with functions that look like regular Racket struct operations:

With the struct type defined, it’s easy to come up with a rudimentary interface for cairo-text-extents:

In order to actually use this function, we need to create a text extents struct and provide it as a pointer. Conveniently, the FFI treats instances of C structs as pointers so this is pretty straightforward:

This style of programming feels awfully imperative though. Since we’re in a functional language, it would be nice to avoid the manual creation of the struct. We can define an alternate version of the cairo-text-extents FFI wrapper by combining named arguments, a new _ptr type constructor, and a neat feature of _fun that lets you customize the return result:

The _ptr constructor works like the _list constructor we saw earlier in this blog post but typically for a single object. Since we are passing in a value to use as an output, we specify the o mode to _ptr. In output mode, this type will automatically allocate a new instance of the type (using the malloc function) and arrange for it to be passed in as a pointer.

The strangest part of this example is that there are now two uses of the -> form! By providing a second arrow, we can customize what the FFI wrapper returns. The expression to the right of the second arrow is just Racket code that can reference previously named arguments. The result of evaluating this expression is used instead of the normal return result for calls to the wrapped function. In this case, we just return the struct that was allocated for us.

Using this new version of the wrapper is much simpler:

With that in hand, it’s pretty easy to write the function we set out to write:

And to conclude part 2 of this tutorial, here’s an example use of the new fit-text function: