SpaceGirl | An Adventure into ObjC + Odin

While working on the game, I decided to partake in a side-quest of handrolling the graphics/os/input layer instead of relying on Raylib to do all the heavy lifting. While it's extraordinarily nice to bootstrap a project (as well as to make a full game with!), I feared that to do everything I wanted to with the game it would cause some friction later on that I don't want to deal with. So I thought it better to take the productivity hit early on (so that in the future) I can continue to make progress with minimal friction from a 3rd-party library (and also because I like having a full understanding of how everything works in my projects). But that's a post for the future. There is something else I want to write down here (mostly for my future self).

Working on macOS

With the switch to handrolling my own graphics layer, I don't want to be locked in to Windows (which is where I've been doing my development). So after getting the Windows+OpenGL layer in a state thats usable, I wanted to add macOS+Metal support before I made too many assumptions on how the API should be (which is an interesting topic itself). Working on macOS however is...interesting to say the least. If you're not working in Swift you inevitably will have to write some Objective-C code (whether you like it not). I had to do this when I tried my hand at making a similar graphics layer in pure C (here is the repo in case you're interested). Objective-C is fascinating because it harkens back to old OOP ideas in a (not quite) novel implementation.

Super Brief Obj-C Primer

I'm by no means an expert (or even a novice) at Obj-C. I only know what I need to know to get a basic application working on macOS, but the core idea and how it works is pretty simple. You have Objects/Classs (I'll use these two interchangeably) which can implement an Interface as well as contain Properties. That sounds all normal and familiar to people who know OOP (different names but same ideas). However, in order to call methods on an Object (or call a class method), you have to send it a message. And that is done with a very Lisp-ish syntax:

1

NSView *view = [[NSView alloc] init];

[NSView alloc] is the first method call that returns a new NSView object which then immediately gets init called on it (presumably this acts like a constructor of some sort).

And to pass parameters to these methods:

1
2
3
4
5
6
7

// a single parameter
NSRect rect = CGMakeRect(0, 0, 1280, 720);
NSView *view = [[NSView alloc] initWithFrame:rect];

// and a method `URLForResource` with a named parameter of `withExtension`
NSURL *libraryURL = [[NSBundle mainBundle] URLForResource:@"./shaders"
                                            withExtension:@"metallib"];

Alright that's about all you need to know about the syntax of Obj-C.

How does this relate to Odin?

Odin is (in my opinion) a fantasic language. It gets out of your way and supplies proper defaults for common scenarios. This is reflected in Odin's standard library as well as the syntax itself. I won't delve ¹ into too much detail, if you want a deeper dive into the general aspects of Odin, just look at their wonderful Overview page. But I will talk about their Obj-C integration.

Believe it or not you don't have to write a lick of real Obj-C code to interface with macOS. Take a look at this snippet:

1
2
3
4
5
6
7
8
9

import mtl "vendor:darwin/metal"
import qc  "vendor:darwin/quartzcore"

mtl_context := Metal_Content{...}

mtl_context.device = mtl.CreateSystemDefaultDevice()
mtl_context.layer = qc.MetalLayer.layer()
mtl_context.layer->setDevice(mtl_context.device)
mtl_context.layer->setPixelFormat(.RGBA8Unorm)

Neat right? No funky syntax, it just works thanks to Odin's support for some syntactic sugar to pass a variable's reference to itself as the first argument of a function in a vtable (thats what the -> does).

So this is great, we can just write (normal?) Odin and start creating a window and interfacing with Metal right? Well...you may be able to get a window on screen, but you wouldn't be able to do much with it. Remember when I said that you have to send a message to an Object to call a method on it? Well the windowing API on macOS requires you to create a custom Object that implements the NSView interface (think of this like the contents of the window), and from there you can override the -(void)updateLayer method that's responsible for rendering graphics (which is called automagically by the OS).

Okay, no big deal, let's do just that. Odin provides compiler intrinsics to create new Obj-C Objects. So let's create a new one that implements NSView.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

import ns "core:sys/darwin/foundation"

@(objc_class="Custom_View")
Custom_View :: struct {
    // this brings in `NSView`'s v-table (along with it's parents' v-tables)
    // which is equivalent to "implementing" an interface
    using _: ns.View
}

@(objc_type=Custom_View, objc_name="updateLayer")
Custom_View_updateLayer :: proc "c" (self: ^Custom_View) {
    // do our fancy rendering
}

Not too compliated right?

• @(objc_class) just (as the attribute name suggests) registers a new class in the obj-c runtime.
• @(objc_type=Custom_View, objc_name="updateLayer") states that we want to define an instance method on the Custom_View class

Now there is some compiler magic that happens here behind the scenes, like automatically adding an updateLayer field to the Custom_View struct that contains the address of our Custom_View_updateLayer procedure. This would allow us to call the procedure just like we would with the official classes.

1
2

view := Custom_View.alloc()
view->updateLayer()

We wouldn't do this obviously since -(void)updateLayer is called automatically by the OS, but you get the idea.

Cool, so now we have a window on screen and can render graphics to it right? Well, what exactly are we rendering? And from where? Remember, -(void)updateLayer is called by the OS, and takes no arguments. So how exactly do we get our application state in there? We could just add a field to our custom class that contains our state.

1
2
3
4
5
6

@(objc_class="Custom_View")
Custom_View :: struct {
    metal_context: ^Metal_Context,

    using _: ns.View
}

Nice...wait, whats this?

$ ./build.sh
Error: @(objc_class) marked type must be of zero size
	Custom_View :: struct {
	^

Oh boy, we can't add custom state to our Object. We could solve this by having a global variable that contains our state, but I'd prefer to avoid that ².

The Rabbit Hole

Alright, so how do we go about getting state into our Object? Obviously its possible, because you can do this in Obj-C (and because a stateless computer is useless). They're called @propertys. And are defined like so:

1
2
3

@interface Custom_View : NSView
@property Metal_Context *metal_context;
@end

We just need to figure out how to add properties to a class via the Obj-C runtime. A quick google search later and you find this StackOverflow question from April of 2012.

How to write iOS app purely in C

I read here Learn C Before Objective-C?

Usually I then replace some Obj-C code with pure C code (after all you can mix them as much as you like, the content of an Obj-C method can be entirely, pure C code)

Is this true?

Is it possible to build an iPhone app purely in the C programming language?

Now I don't know about writing an entire iOS app in pure C. That just sounds like an exercise in masochism. But the selected answer given is a real treat. I won't transpose the entire thing here, but in short, the mad lad Richard J. Ross III gave a minimal example of rendering a single red box on an iPhone in pure C by using the Obj-C runtime (which of course is itself written in C). Even more importantly though he demonstrated how to create a class that contains properties (the comments are Ross's):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

// This is objc-runtime gibberish at best. We are creating a class with the
// name "AppDelegate" that is a subclass of "UIResponder". Note we do not need
// to register for the UIApplicationDelegate protocol, that really is simply for
// Xcode's autocomplete, we just need to implement the method and we are golden.
AppDelClass = objc_allocateClassPair(objc_getClass("UIResponder"), "AppDelegate", 0);

// Here, we tell the objc runtime that we have a variable named "window" of type 'id'
class_addIvar(AppDelClass, "window", sizeof(id), 0, "@");

// We tell the objc-runtime that we have an implementation for the method
// -application:didFinishLaunchingWithOptions:, and link that to our custom
// function defined above. Notice the final parameter. This tells the runtime
// the types of arguments received by the function.
class_addMethod(AppDelClass, sel_getUid("application:didFinishLaunchingWithOptions:"), (IMP) AppDel_didFinishLaunching, "i@:@@");

// Finally we tell the runtime that we have finished describing the class and
// we can let the rest of the application use it.
objc_registerClassPair(AppDelClass);

(if you're asking about the "i@:@@", according to Apple's Docs, it denotes the method signature)

Sweet, well all we gotta do is manually create our class, just using Odin's Obj-C bindings:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

import ns "core:sys/darwin/foundation"

custom_view_class := ns.objc_allocateClassPair(ns.objc_lookUpClass("NSView"), "Custom_View", 0)
ns.class_addIvar(custom_view_class, "metal_context", size_of(^Metal_Context), 0, "@")

// tell the runtime we are overriding the `-(void)updateLayer` method
update_layer_selector := intrinsics.objc_find_selector("updateLayer")
ns.class_addMethod(custom_view_class, update_layer_selector, auto_cast custom_view_updateLayer, "v@:")

ns.objc_registerClassPair(custom_view_class)

And of course the actual updateLayer procedure

1
2
3

custom_view_updateLayer :: proc "c" (view: ^intrinsics.objc_object, sel: intrinsics.objc_selector) {
    // do the rendering
}

And there we have it! Our custom clas that implements NSView with a property to hold our application state. Don't worry too much about the arguments to the procedure just yet, I'll get to those later. Now all that's left is to instantiate our class and assign it to our window...

Odin? You okay bud?

...but wait. How do we actually do that? We don't actually have a concrete Odin type that we can use, its only defined in the actual runtime itself. Maybe by taking a look at Odin's Obj-C binding source code for NSView itself, can give us a hint:

1
2
3
4

@(objc_type=View, objc_name="initWithFrame")
View_initWithFrame :: proc "c" (self: ^View, frame: Rect) -> ^View {
	return msgSend(^View, self, "initWithFrame:", frame)
}

Aha, a msgSend() procedure! This looks promising. Let's see what the signature of this procedure is:

1

@(private) msgSend :: intrinsics.objc_send

Looks to be an alias for the compiler intrinsic objc_send, looking into that we get...well a compiler intrinsic thats handled by the gb_internal lbValue lb_handle_objc_send(lbProcedure *p, Ast *expr). That function seems to generate a call to the odin objc_msgSend() procedure:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

#+private
package runtime

foreign import "system:Foundation.framework"

objc_id :: ^intrinsics.objc_object
objc_SEL :: ^intrinsics.objc_selector

/* other type definitions */

foreign Foundation {
    /* other procedures */

    objc_msgSend :: proc "c" (self: objc_id, op: objc_SEL, #c_vararg args: ..any) ---
}

There it is! Huh, that signature seems a little different than what View_initWithFrame was using.

1

msgSend(^View, self, "initWithFrame:", frame)

It must be the compiler doing some more magic behind the scenes. If you peruse a bit around View_initWithFrame, you'll notice that the first parameter to msgSend() is the return value of the method you're calling, and the rest of the parameters match with the objc_msgSend() procedure. This is probably just so you don't have to transmute(^Custom_View) every place you call a method. Although, if you notice, there isn't a way to define what class we're messaging. Remember, we created our class directly in the runtime, we don't have an Odin struct that's tagged with a class name. So we can't even use this procedure. Even if we wanted to be cheeky and give it a ^objc_object, it wouldn't be phased by our antics:

1
2
3

// this returns an `id` which is just an alias for `^intrinsics.objc_object`
our_object := ns.objc_getMetaClass("Custom_View")
view := intrinsics.objc_send(^intrinsics.objc_object, our_object, "alloc")

This gives an error:

Error: 'objc_send' expected a named type with the attribute @(obj_class=<string>) , got type objc_object
    ... w := intrinsics.objc_send(^intrinsics.objc_object, sel, "alloc")
                                                           ^~^

So it looks like this procedure assumes you'd never want to create a class that contains properties. Well now what?

Even More Antics

If the compiler is going to gatekeep us from sending messages to objects willy-nilly, we just have to get more crafty. All of these Obj-C runtime functions exist in Apple's Foundation framework (essentially just a really fancy dynamic library). So if we just link against the library manually, we should be able to skirt around Odin's compiler restrictions and get right to the source...code (i'm sorry).

Not so fast though, the Foundation framework is already linked against our binary when we import base:runtime, so we can't link it again. We could just not depend on base:runtime, however, I don't about you, but I like having my runtime features. So how can we access this elusive function?

By just grabbing the function pointer by force!

If we just dynamically load the Foundation framework at runtime, we can query for the objc_msgSend() function.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

id :: ^intrinsics.objc_object
SEL :: ^intrinsics.objc_selector
msgSend: proc "c" (self: id, cmd: SEL, #c_vararg args: ..any) -> id = nil

foundation_symbol_table := posix.dlopen("/System/Library/Frameworks/Foundation.framework/Versions/C/Foundation", {.LAZY})
if foundation_symbol_table == nil {
    fmt.eprintln("couldn't load foundation.framework")
    os.exit(1)
}
msgSend = auto_cast posix.dlsym(foundation_symbol_table, "objc_msgSend")

In practice, this shouldn't actually load anything from disk. It should just return the symbol table for the already loaded dylib. So let's see if it works, by allocating a new instance of our class:

1
2
3
4

// we could also do `ns.objc_lookUpClass("Custom_View")` instead of keeping `custom_view_class` around
view := msgSend(transmute(id)custom_view_class, intrinsics.objc_find_selector("alloc"))

fmt.eprintln(view)

$ game

0x12CF0CDF0

Hey, there we go, a pointer to our object, but we're not done yet. We still have to initialize our metal_context property on our object. We can do that by using the object_setInstanceVariable function which allows you to...set instance variables, at runtime without needing to have a concrete type that you can access. Then you can use object_getInstanceVariable to get the value within the methods. The way you do this is easy:

1
2

// metal_context: ^Metal_Context
ns.object_setInstanceVariable(view, "metal_context", metal_context)

And to access this variable in the methods its very similar:

1
2
3
4
5
6

custom_view_updateLayer :: proc "c" (self: id, sel: SEL) {
    metal_context: ^Metal_Context
    ns.object_getInstanceVariable(self, "metal_context", &metal_context)

    // do all the rendering with the metal_context
}

And we're done. However, while this works perfectly fine, manually loading the objc_msgSend function leaves a bad taste in my mouth. The only reason why we need it in the first place is to call alloc() on our custom class. But what if I told you there was another way using only the tools provided in the standard library. If you look around Apple's documentation on the Obj-C runtime you'll find a very useful objc_constructInstance method:

1

id objc_constructInstance(Class cls, void *bytes);

Using this we can essentially do what alloc() does, but without objc_msgSend:

1
2
3

size := ns.class_getInstanceSize(custom_view_class)
contents := raw_data(make([]u8, size))
view := ns.objc_constructInstance(class, contents)

But we still need to call initWithFrame:. How do we do that? Well, with a little bit of trickery, it can be done. Remember that everything is just a pointer to an object in memory and (through the wizardry of Obj-C) objc_msgSend will find the right function to call given a pointer to an object. So...what if we lie and say that our view is just an ^ns.View and call the appropriate methods:

1
2

view := transmute(^ns.View)ns.objc_constructInstance(class, contents)
view->initWithFrame(some_rect)

Look at that, no imported functions to be seen. This is also super handy if you need to "polyfill" some method that isn't yet reflected in the standard library. At the time of writing, Odin doesn't support the NSView:setNeedsDisplay: method. So to get around this, you can create a dummy class that implements that method and use the same casting trick:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

@(objc_class="DummyView")
DummyView :: struct {
   using _: ns.View
}

@(objc_type=DummyView, objc_name="setNeedsDisplay")
DummyView_setNeedsDisplay :: proc "c" (self: ^ns.View, needs_display: ns.BOOL) {
	intrinsics.objc_send(nil, self, "setNeedsDisplay:", needs_display)
}

(transmute(^DummView)view)->setNeedsDisplay(true)

And that is the final piece of the puzzle to write Obj-C without writing Obj-C. We now have all the tools necessary to write macOS applications in Odin (at least in this simple case, I wouldn't go writing an iOS app like this).

So much pain went into this post you wouldn't believe. This is my current chrome window as I'm writing this post:

It was a lot of staring at Odin source code, looking at documentation, and thanking my savior RJ Ross III. There was quite a bit of trial-and-error + hair pulling that I left out, but I think I properly articulated the journey I had through this whole adventure. I hope this can save you countless hours of of pain if you for some reason are trying to write a macOS app in Odin.

The next section is just about some interesting/funny stuff I found along the way in no particular order.

Interesting/Funny Stuff

• Apple's docs for objc_duplicateClass:

• Greg Parker's Hamster Emporium Archive

• bbum's comment on StackOverflow that gave me a chuckle and inspired a whole project on GitHub

• This poor soul that had the exact same problem I did when trying to create a window on macOS purely in Odin.