Willy

I have to switch DragonRuby Game Toolkit over from Oculus's VrApi to OpenXR. This is a good change, as it is going to get us off deprecated libraries and closer to supporting more than just the Oculus Quest.

But I'm looking into how to use OpenXR, and good lord, that shit is daunting.

I mean, look at the Hello World example for crying out loud!

I haven't opened any of these files, they might be three lines of code each, but already my first take is "this is WAY too complex." It's a textbook "you ever see sample code so heavy you had to take a nap?" moment.

Don't write samples like this!

Write samples like this instead!

void start_this_shit_up(void) {
    // here's all the stuff you have to do BEFORE ANYTHING ELSE.
    // there are 12 parameters, we will walk through them.
    // come in here prepared with a HWND/argc+argv/good vibes
    MyLib_Init(&params);
    // this can fail, but we SKIPPED ERROR HANDLING so you
    // can see how this API works. Because that's the important part.
}

void use_this_shit(void) {
     // there a million Doohickeys in the world from different vendors, 
     // and eventually you will need to handle their special attributes in
     // an abstract way, but for now, this will make the Doohickey you
     // probably have on your desk go brrrr
     MyLib_DoAThing(1, false, "whatever.xml");
     // (xml is terrible. So is json. Don't force them on C programmers.)
}

void shut_this_shit_down(void) {
     // If your API can fail during deinit, you fucked up. But it's too
     // late now. Make a note of it, DON'T HANDLE IT IN THE
     // SAMPLE CODE, and be done.
    MyLib_Deinit();
}

int main(int argc, char **argv) {
    start_this_shit_up();
    use_this_shit();
    shut_this_shit_down();
    return 0;  // I literally do not care.
}

Notice how the functions are listed in this example in the order you will use them. Like, you know, how a brain thinks about a task.

Oh wait, you have platform-specific stuff that needs to be handled? Okay! DO NOT PUT IT IN A SEPARATE FILE.

void start_this_shit_up(void) {
    #ifdef __WINDOWS__
    MyLib_WindowsMagic(myHwnd);
    #elif defined(__LINUX__)
    MyLib_LinuxMagic(whatever);
    #else
    #error Uhoh, check back as we add new platforms!
    #endif
    MyLib_Init(&params);
}

Did this need helloworld_windows.c and helloworld_linux.c? No it did not.

Do you find yourself making subfolders? STOP IT.

Do you find yourself building a GUI for your sample app? DELETE IT.

This just helps obfuscate the thing you actually want people to know about, the API. If I have to dig through some GUI toolkit code to find where you actually use the API, it's just adding complexity, which adds confusion, which adds uncertainty, which all adds up to WASTED TIME.

It is okay to have different ways to build the sample code, in case people want to run it, or experiment with it, or you just want to make sure it actually compiles, but please hide that stuff somewhere so I don't have to care about the marathon that Gradle made you run or whatever. Ideally, you should be able to just drop your ONE .c FILE into anything that looks like a compiler and it'll (mostly) work. Maybe leave a comment at the top about libraries it might need to link to. But if half of what I see when I hit your github is a million project files, I'm already getting distracted from the actual goal.

Which is to understand how to use the API.

Flipping Finches was a game I made for Ludum Dare 53 back at the start of May.

The theme was Delivery, and I got 9th in Theme! It's a difficult-ish flying platformer where the bird will do a flip every time you turn around.

You can play here https://aeveis.itch.io/flipping-finches.

I'm trying to be a more positive person these days. Less criticizing, more creating. Gratitude. Humility. All that kind of shit.

but there are fucking limits

aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

EDIT: updated with clarifying details

fascinating new discovery: softmodems introduced an equivalent to AUI/MII. let me explain

ethernet is one of the only communications protocols i'm aware of that was designed with extreme modularity and flexibility from the get-go. for some reason, its designers understood that someday, the first idea they had for the physical layer on which ethernet would travel would get replaced with a new idea, and that at that point they would not want to have to redesign all their hardware from the ground up

so the first 15-20 years of ethernet cards did not actually have a "native medium." you couldn't buy a "thicknet card" or "thinnet card" - all Ethernet ports were AUI, or Attachment Unit Interface connectors. that was a DA15 plug, like on a PC joystick, and it spoke a completely universal, all-digital Ethernet protocol.

instead of plugging the actual "ethernet cable" into the AUI port, you connected an MAU (Medium Attachment Unit.) That contained electronics to convert from the simple TTL-digital protocol into whatever weird horseshit was being used on the actual wire.

if you were using thicknet or thinnet, the digital signals were turned into RF warblings that would survive travel down a coax cable; once twisted-pair Ethernet became a thing, your MAU produced differential digital signals. i don't know what other MAUs were ever sold, but in theory you could have one that produced open-air radio signals, or transmitted over a pair of IR LEDs. the important thing is that the card didn't know shit about any of this.

the electronics on the card were called the MAC (yes, as in "MAC address.") the MAC only understood packets, and only spoke AUI. it didn't know about analog voltages or coax or any of the stuff going on outside the PC; all that stuff is part of what Ethernet called the PHY, or physical layer interface.

everything was very cleanly segmented, so you could design a single MAC (probably where 90% of the design cost went anyway) without needing to be married to a specific medium - the end user provided an appropriate MAU, and if they ever changed media, they could simply swap that out to change PHYs.

it was honestly brilliant, and the concept persists to the present day. the later 100mbps standard is actually a completely distinct protocol called Fast Ethernet, which diverges so greatly that it replaced AUI with a new interface called MII, and in turn MII developed into eight or ten newer, faster interfaces, but they all do the same basic thing: isolate MAC from PHY.

critically however, the external transceiver basically disappeared; MII exists on all Ethernet devices, but almost invariably as an internal board-level connection between two chips, not an exposed plug that an end user interacts with. it now largely exists to make life easier for manufacturers, since end users virtually never change media.

for that reason, 99% of computer users have never seen an MAU these days, and the term is technically not applied to anything from Fast Ethernet onwards - but the concept absolutely still exists!

for one thing: SFPs, as used in enterprise networking, are functionally MAUs: they separate the MAC from the medium (or "PHY"), they just use MII instead of AUI under the hood.

if you have a 48-port 10-gig switch, there's a good chance that the entire thing is SFP ports. that means you can still do what we were doing in 1990: when you need to change media, you just switch out a transceiver - an SFP module - and the rest of the switch is none the wiser. the MAC only cares about medium present or medium not present, and the transceiver worries about all that.

so if your switch is all fiber, but you need a copper port in an emergency - just swap a module. done, medium changed. if you need to connect two switches together - just use a direct attach cable. that's literally ethernet with no MAU. direct PHY-to-PHY communication over the MII protocol. incredible!

in addition, early Fast Ethernet cards actually had exposed MII ports and supported external transceivers, exactly as Ethernet did with AUI. see followup post for image. these are stupid rare!

so this is all very cool - and apparently modems did the same thing. this makes sense! late-era dialup modems, even if they're softmodems, had to have a DSP somewhere. DSPs, AFAIK, do not output analog signals directly, you still need a DAC for that. well, the people who design DSPs are not necessarily the people who know best how to make DACs; you're going to end up buying them from two different companies, but since modem signals conform very reliably to known specs, why use different interfaces?

who wants to reprogram their DSP for every DAC they choose on a given day? and who wants to buy a generic DAC, then still have to build the rest of the "front end" - the circuitry that handles ring detection, onhook-offhook, tone decoding, etc.? so, they apparently came up with "MII for modems." cool!

early Fast Ethernet cards had MII ports just like how Ethernet had AUI