DEV Community: Colleague Riley

RGFW Under the Hood: Clipboard Copy/Paste

Colleague Riley — Mon, 09 Sep 2024 19:55:10 +0000

Introduction

Reading and writing to the clipboard using low-level APIs can be tricky. There are a bunch of steps required. This tutorial simplifies the process so you can easily read and write to the clipboard using the low-level APIs.

The tutorial is based on RGFW's source code and its usage of the low-level APIs.

Note: the cocoa code is written in Pure-C.

Overview

1) Clipboard Paste

X11 (init atoms, convert section, get data)
Win32 (open clipboard, get data, convert data, close clipboard)
Cocoa (set datatypes, get pasteboard, get data, convert data)

2) Clipboard Copy

X11 (init atoms, convert section, handle request, send data)
Win32 (setup global object, convert data, open clipboard, convert string, send data, close clipboard)
Cocoa (create datatype array, declare types, convert string, send data)

Clipboard Paste

X11

To handle the clipboard, you must create some Atoms via XInternAtom.
X Atoms are used to ask for or send specific data or properties through X11.

You'll need three atoms,

1) UTF8_STRING: Atom for a UTF-8 string.
2) CLIPBOARD: Atom for getting clipboard data.
3) XSEL_DATA: Atom to get selection data.

const Atom UTF8_STRING = XInternAtom(display, "UTF8_STRING", True);
const Atom CLIPBOARD = XInternAtom(display, "CLIPBOARD", 0);
const Atom XSEL_DATA = XInternAtom(display, "XSEL_DATA", 0);

Now, to get the clipboard data you have to request that the clipboard section be converted to UTF8 using XConvertSelection.

use XSync to send the request to the server.

XConvertSelection(display, CLIPBOARD, UTF8_STRING, XSEL_DATA, window, CurrentTime);
XSync(display, 0);

The selection will be converted and sent back to the client as a XSelectionNotify event. You can get the next event, which should be the SelectionNotify event with XNextEvent.

XEvent event;
XNextEvent(display, &event);

Check if the event is a SelectionNotify event and use .selection to ensure the type is a CLIPBOARD. Also make sure .property is not 0 and can be retrieved.

if (event.type == SelectionNotify && event.xselection.selection == CLIPBOARD && event.xselection.property != 0) {

You can get the converted data via XGetWindowProperty using the selection property.

    int format;
    unsigned long N, size;
    char* data, * s = NULL;
    Atom target;

    XGetWindowProperty(event.xselection.display, event.xselection.requestor,
        event.xselection.property, 0L, (~0L), 0, AnyPropertyType, &target,
        &format, &size, &N, (unsigned char**) &data);

Make sure the data is in the right format by checking target

    if (target == UTF8_STRING || target == XA_STRING) {

The data is stored in data, once you're done with it free it with XFree.

You can also delete the property via XDeleteProperty.

        XFree(data);
    }

    XDeleteProperty(event.xselection.display, event.xselection.requestor, event.xselection.property);
}

winapi

First, open the clipboard OpenClipboard.

if (OpenClipboard(NULL) == 0)
    return 0;

Get the clipboard data as a utf16 string via GetClipboardData

If the data is NULL, you should close the clipboard using CloseClipboard

HANDLE hData = GetClipboardData(CF_UNICODETEXT);
if (hData == NULL) {
    CloseClipboard();
    return 0;
}

Next, you need to convert the utf16 data back to utf8.

Start by locking memory for the utf8 data via GlobalLock.

wchar_t* wstr = (wchar_t*) GlobalLock(hData);

Use setlocale to ensure the data format is utf8.

Get the size of the UTF-8 version with wcstombs.

setlocale(LC_ALL, "en_US.UTF-8");

size_t textLen = wcstombs(NULL, wstr, 0);

If the size is valid, convert the data using wcstombs.

if (textLen) {
    char* text = (char*) malloc((textLen * sizeof(char)) + 1);

    wcstombs(text, wstr, (textLen) + 1);
    text[textLen] = '\0';

    free(text);
}

Make sure to free leftover global data using GlobalUnlock and close the clipboard with CloseClipboard.

GlobalUnlock(hData);
CloseClipboard();

cocoa

Cocoa uses NSPasteboardTypeString to ask for string data. You'll have to define this yourself if you're not using Objective-C.

NSPasteboardType const NSPasteboardTypeString = "public.utf8-plain-text";

Although the is a c-string and Cocoa uses NSStrings, you can convert the c-string to an NSString via stringWithUTF8String.

NSString* dataType = objc_msgSend_class_char(objc_getClass("NSString"), sel_registerName("stringWithUTF8String:"), (char*)NSPasteboardTypeString);

Now we'll use generalPasteboard to get the default pasteboard object.

NSPasteboard* pasteboard = objc_msgSend_id((id)objc_getClass("NSPasteboard"), sel_registerName("generalPasteboard"));

Then you can get the pasteboard's string data with the dataType using stringForType.

However, it will give you an NSString, which can be converted with UTF8String.

NSString* clip = ((id(*)(id, SEL, const char*))objc_msgSend)(pasteboard, sel_registerName("stringForType:"), dataType);
const char* str = ((const char* (*)(id, SEL)) objc_msgSend) (clip, sel_registerName("UTF8String"));

Clipboard Copy

X11

To copy to the clipboard you'll need a few more Atoms.

1) SAVE_TARGETS: To request a section to convert to (for copying).
2) TARGETS: To handle one requested target
3) MULTIPLE: When there are multiple request targets
4) ATOM_PAIR: To get the supported data types.
5) CLIPBOARD_MANAGER: To access data from the clipboard manager.

const Atom SAVE_TARGETS = XInternAtom((Display*) display, "SAVE_TARGETS", False);
const Atom TARGETS = XInternAtom((Display*) display, "TARGETS", False);
const Atom MULTIPLE = XInternAtom((Display*) display, "MULTIPLE", False);
const Atom ATOM_PAIR = XInternAtom((Display*) display, "ATOM_PAIR", False);
const Atom CLIPBOARD_MANAGER = XInternAtom((Display*) display, "CLIPBOARD_MANAGER", False);

We can request a clipboard section. First, set the owner of the section to be a client window via XSetSelectionOwner. Next request a converted section using XConvertSelection.

XSetSelectionOwner((Display*) display, CLIPBOARD, (Window) window, CurrentTime);

XConvertSelection((Display*) display, CLIPBOARD_MANAGER, SAVE_TARGETS, None, (Window) window, CurrentTime);

The rest of the code would exist in an event loop. You can create an external event loop from your main event loop if you wish or add this to your main event loop.

We'll be handling SelectionRequest in order to update the clipboard selection to the string data.

if (event.type == SelectionRequest) {
    const XSelectionRequestEvent* request = &event.xselectionrequest;

At the end of the SelectionNotify event, a response will be sent back to the requester. The structure should be created here and modified depending on the request data.

    XEvent reply = { SelectionNotify };
    reply.xselection.property = 0;

The first target we will handle is TARGETS when the requestor wants to know which targets are supported.

    if (request->target == TARGETS) {

I will create an array of supported targets

        const Atom targets[] = { TARGETS,
                                MULTIPLE,
                                UTF8_STRING,
                                XA_STRING };

This array can be passed using XChangeProperty.

I'll also change the selection property so the requestor knows what property we changed.

        XChangeProperty(display,
            request->requestor,
            request->property,
            4,
            32,
            PropModeReplace,
            (unsigned char*) targets,
            sizeof(targets) / sizeof(targets[0]));

        reply.xselection.property = request->property;
    }

Next, I will handle MULTIPLE targets.

    if (request->target == MULTIPLE) {

We'll start by getting the supported targets via XGetWindowProperty

        Atom* targets = NULL;

        Atom actualType = 0;
        int actualFormat = 0;
        unsigned long count = 0, bytesAfter = 0;

        XGetWindowProperty(display, request->requestor, request->property, 0, LONG_MAX, False, ATOM_PAIR, &actualType, &actualFormat, &count, &bytesAfter, (unsigned char **) &targets);

Now we'll loop through the supported targets. If the supported targets match one of our supported targets, we can pass the data with XChangeProperty.

If the target is not used, the second argument should be set to None, marking it as unused.

        unsigned long i;
        for (i = 0; i < count; i += 2) {
            if (targets[i] == UTF8_STRING || targets[i] == XA_STRING) {
                XChangeProperty((Display*) display,
                    request->requestor,
                    targets[i + 1],
                    targets[i],
                    8,
                    PropModeReplace,
                    (unsigned char*) text,
                    sizeof(text));
                XFlush(display);
            } else {
                targets[i + 1] = None;
            }
        }

You can pass the final array of supported targets to the requestor using XChangeProperty. This tells the requestor which targets to expect for the original list it sent.

The message will be sent out asap when XFlush is called.

You can free your copy of the target array with XFree.

        XChangeProperty((Display*) display,
            request->requestor,
            request->property,
            ATOM_PAIR,
            32,
            PropModeReplace,
            (unsigned char*) targets,
            count);

        XFlush(display);
        XFree(targets);

        reply.xselection.property = request->property;
    }

For the final step of the event, send the selection back to the requestor via XSendEvent.

Then flush the queue with XFlush.

    reply.xselection.display = request->display;
    reply.xselection.requestor = request->requestor;
    reply.xselection.selection = request->selection;
    reply.xselection.target = request->target;
    reply.xselection.time = request->time;

    XSendEvent((Display*) display, request->requestor, False, 0, &reply);
    XFlush(display);
}

winapi

First allocate global memory for your data and your utf-8 buffer with GlobalAlloc

HANDLE object = GlobalAlloc(GMEM_MOVEABLE, (1 + textLen) * sizeof(WCHAR));
WCHAR*  buffer = (WCHAR*) GlobalLock(object);

Next, you can use MultiByteToWideChar to convert your string to a wide string.

MultiByteToWideChar(CP_UTF8, 0, text, -1, buffer, textLen);

Now unlock the global object and open the clipboard

GlobalUnlock(object);
OpenClipboard(NULL);

To update the clipboard data, you start by clearing what's currently on the clipboard via EmptyClipboard you can use SetClipboardData to set the data to the utf8 object.

Finally, close the clipboard with CloseClipboard.

EmptyClipboard();
SetClipboardData(CF_UNICODETEXT, object);

CloseClipboard();

cocoa

Start by creating an array of the type of data you want to put on the clipboard and convert it to an NSArray using initWithObjects.

NSPasteboardType ntypes[] = { dataType };

NSArray* array = ((id (*)(id, SEL, void*, NSUInteger))objc_msgSend)
                    (NSAlloc(objc_getClass("NSArray")), sel_registerName("initWithObjects:count:"), ntypes, 1);

Use declareTypes to declare the array as the supported data types.

You can also free the NSArray with NSRelease.

((NSInteger(*)(id, SEL, id, void*))objc_msgSend) (pasteboard, sel_registerName("declareTypes:owner:"), array, NULL);
NSRelease(array);

You can convert the string to want to copy to an NSString via stringWithUTF8String and set the clipboard string to be that NSString using setString.

NSString* nsstr = objc_msgSend_class_char(objc_getClass("NSString"), sel_registerName("stringWithUTF8String:"), text);

((bool (*)(id, SEL, id, NSPasteboardType))objc_msgSend) (pasteboard, sel_registerName("setString:forType:"), nsstr, dataType);

Full examples

X11

// compile with:
// gcc x11.c -lX11

#include <X11/Xlib.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <limits.h>

#include <X11/Xatom.h>

int main(void) {
    Display* display = XOpenDisplay(NULL);

    Window window = XCreateSimpleWindow(display, RootWindow(display, DefaultScreen(display)), 10, 10, 200, 200, 1,
                                 BlackPixel(display, DefaultScreen(display)), WhitePixel(display, DefaultScreen(display)));

    XSelectInput(display, window, ExposureMask | KeyPressMask); 

    const Atom UTF8_STRING = XInternAtom(display, "UTF8_STRING", True);
    const Atom CLIPBOARD = XInternAtom(display, "CLIPBOARD", 0);
    const Atom XSEL_DATA = XInternAtom(display, "XSEL_DATA", 0);

    const Atom SAVE_TARGETS = XInternAtom((Display*) display, "SAVE_TARGETS", False);
    const Atom TARGETS = XInternAtom((Display*) display, "TARGETS", False);
    const Atom MULTIPLE = XInternAtom((Display*) display, "MULTIPLE", False);
    const Atom ATOM_PAIR = XInternAtom((Display*) display, "ATOM_PAIR", False);
    const Atom CLIPBOARD_MANAGER = XInternAtom((Display*) display, "CLIPBOARD_MANAGER", False);

    // input
    XConvertSelection(display, CLIPBOARD, UTF8_STRING, XSEL_DATA, window, CurrentTime);
    XSync(display, 0);

    XEvent event;
    XNextEvent(display, &event);

    if (event.type == SelectionNotify && event.xselection.selection == CLIPBOARD && event.xselection.property != 0) {

        int format;
        unsigned long N, size;
        char* data, * s = NULL;
        Atom target;

        XGetWindowProperty(event.xselection.display, event.xselection.requestor,
            event.xselection.property, 0L, (~0L), 0, AnyPropertyType, &target,
            &format, &size, &N, (unsigned char**) &data);

        if (target == UTF8_STRING || target == XA_STRING) {
            printf("paste: %s\n", data);
            XFree(data);
        }

        XDeleteProperty(event.xselection.display, event.xselection.requestor, event.xselection.property);
    }

    // output
    char text[] = "new string\0";

    XSetSelectionOwner((Display*) display, CLIPBOARD, (Window) window, CurrentTime);

    XConvertSelection((Display*) display, CLIPBOARD_MANAGER, SAVE_TARGETS, None, (Window) window, CurrentTime);

    Bool running = True;
    while (running) {
        XNextEvent(display, &event);
        if (event.type == SelectionRequest) {
            const XSelectionRequestEvent* request = &event.xselectionrequest;

            XEvent reply = { SelectionNotify };
            reply.xselection.property = 0;

            if (request->target == TARGETS) {
                const Atom targets[] = { TARGETS,
                                        MULTIPLE,
                                        UTF8_STRING,
                                        XA_STRING };

                XChangeProperty(display,
                    request->requestor,
                    request->property,
                    4,
                    32,
                    PropModeReplace,
                    (unsigned char*) targets,
                    sizeof(targets) / sizeof(targets[0]));

                reply.xselection.property = request->property;
            }

            if (request->target == MULTIPLE) {  
                Atom* targets = NULL;

                Atom actualType = 0;
                int actualFormat = 0;
                unsigned long count = 0, bytesAfter = 0;

                XGetWindowProperty(display, request->requestor, request->property, 0, LONG_MAX, False, ATOM_PAIR, &actualType, &actualFormat, &count, &bytesAfter, (unsigned char **) &targets);

                unsigned long i;
                for (i = 0; i < count; i += 2) {
                    Bool found = False; 

                    if (targets[i] == UTF8_STRING || targets[i] == XA_STRING) {
                        XChangeProperty((Display*) display,
                            request->requestor,
                            targets[i + 1],
                            targets[i],
                            8,
                            PropModeReplace,
                            (unsigned char*) text,
                            sizeof(text));
                        XFlush(display);
                        running = False;
                    } else {
                        targets[i + 1] = None;
                    }
                }

                XChangeProperty((Display*) display,
                    request->requestor,
                    request->property,
                    ATOM_PAIR,
                    32,
                    PropModeReplace,
                    (unsigned char*) targets,
                    count);

                XFlush(display);
                XFree(targets);

                reply.xselection.property = request->property;
            }

            reply.xselection.display = request->display;
            reply.xselection.requestor = request->requestor;
            reply.xselection.selection = request->selection;
            reply.xselection.target = request->target;
            reply.xselection.time = request->time;

            XSendEvent((Display*) display, request->requestor, False, 0, &reply);
            XFlush(display);
        }
    }

    XCloseDisplay(display);
 }

Winapi

// compile with:
// gcc win32.c

#include <windows.h>
#include <locale.h>

#include <stdio.h>

int main() {
    // output
    if (OpenClipboard(NULL) == 0)
        return 0;

    HANDLE hData = GetClipboardData(CF_UNICODETEXT);
    if (hData == NULL) {
        CloseClipboard();
        return 0;
    }

    wchar_t* wstr = (wchar_t*) GlobalLock(hData);

    setlocale(LC_ALL, "en_US.UTF-8");

    size_t textLen = wcstombs(NULL, wstr, 0);

    if (textLen) {
        char* text = (char*) malloc((textLen * sizeof(char)) + 1);

        wcstombs(text, wstr, (textLen) + 1);
        text[textLen] = '\0';

        printf("paste: %s\n", text);
        free(text);
    }

    GlobalUnlock(hData);
    CloseClipboard();


    // input

    char text[] = "new text\0";

    HANDLE object = GlobalAlloc(GMEM_MOVEABLE, (sizeof(text) / sizeof(char))  * sizeof(WCHAR));

    WCHAR* buffer = (WCHAR*) GlobalLock(object);
    if (!buffer) {
        GlobalFree(object);
        return 0;
    }

    MultiByteToWideChar(CP_UTF8, 0, text, -1, buffer, (sizeof(text) / sizeof(char)));

    GlobalUnlock(object);
    if (OpenClipboard(NULL) == 0) {
        GlobalFree(object);
        return 0;
    }

    EmptyClipboard();
    SetClipboardData(CF_UNICODETEXT, object);
    CloseClipboard();
}

Cocoa

// compile with:
// gcc cocoa.c -framework Foundation -framework AppKit  


#include <objc/runtime.h>
#include <objc/message.h>
#include <CoreVideo/CVDisplayLink.h>
#include <ApplicationServices/ApplicationServices.h>

#ifdef __arm64__
/* ARM just uses objc_msgSend */
#define abi_objc_msgSend_stret objc_msgSend
#define abi_objc_msgSend_fpret objc_msgSend
#else /* __i386__ */
/* x86 just uses abi_objc_msgSend_fpret and (NSColor *)objc_msgSend_id respectively */
#define abi_objc_msgSend_stret objc_msgSend_stret
#define abi_objc_msgSend_fpret objc_msgSend_fpret
#endif

typedef void NSPasteboard;
typedef void NSString;
typedef void NSArray;
typedef void NSApplication;

typedef const char* NSPasteboardType;

typedef unsigned long NSUInteger;
typedef long NSInteger;

#define NSAlloc(nsclass) objc_msgSend_id((id)nsclass, sel_registerName("alloc"))

#define objc_msgSend_bool           ((BOOL (*)(id, SEL))objc_msgSend)
#define objc_msgSend_void           ((void (*)(id, SEL))objc_msgSend)
#define objc_msgSend_void_id        ((void (*)(id, SEL, id))objc_msgSend)
#define objc_msgSend_uint           ((NSUInteger (*)(id, SEL))objc_msgSend)
#define objc_msgSend_void_bool      ((void (*)(id, SEL, BOOL))objc_msgSend)
#define objc_msgSend_void_int       ((void (*)(id, SEL, int))objc_msgSend)
#define objc_msgSend_bool_void      ((BOOL (*)(id, SEL))objc_msgSend)
#define objc_msgSend_void_SEL       ((void (*)(id, SEL, SEL))objc_msgSend)
#define objc_msgSend_id             ((id (*)(id, SEL))objc_msgSend)
#define objc_msgSend_id_id              ((id (*)(id, SEL, id))objc_msgSend)
#define objc_msgSend_id_bool            ((BOOL (*)(id, SEL, id))objc_msgSend)

#define objc_msgSend_class_char ((id (*)(Class, SEL, char*))objc_msgSend)

void NSRelease(id obj) {
    objc_msgSend_void(obj, sel_registerName("release"));
}

int main() {
    /* input */
    NSPasteboardType const NSPasteboardTypeString = "public.utf8-plain-text";

    NSString* dataType = objc_msgSend_class_char(objc_getClass("NSString"), sel_registerName("stringWithUTF8String:"), (char*)NSPasteboardTypeString);

    NSPasteboard* pasteboard = objc_msgSend_id((id)objc_getClass("NSPasteboard"), sel_registerName("generalPasteboard")); 

    NSString* clip = ((id(*)(id, SEL, const char*))objc_msgSend)(pasteboard, sel_registerName("stringForType:"), dataType);

    const char* str = ((const char* (*)(id, SEL)) objc_msgSend) (clip, sel_registerName("UTF8String"));

    printf("paste: %s\n", str);

    char text[] = "new string\0";

    NSPasteboardType ntypes[] = { dataType };

    NSArray* array = ((id (*)(id, SEL, void*, NSUInteger))objc_msgSend)
                        (NSAlloc(objc_getClass("NSArray")), sel_registerName("initWithObjects:count:"), ntypes, 1);

    ((NSInteger(*)(id, SEL, id, void*))objc_msgSend) (pasteboard, sel_registerName("declareTypes:owner:"), array, NULL);
    NSRelease(array);

    NSString* nsstr = objc_msgSend_class_char(objc_getClass("NSString"), sel_registerName("stringWithUTF8String:"), text);

    ((bool (*)(id, SEL, id, NSPasteboardType))objc_msgSend) (pasteboard, sel_registerName("setString:forType:"), nsstr, dataType);  
}

RGFW Under the Hood: X11 Drag 'n Drop

Colleague Riley — Mon, 02 Sep 2024 19:15:36 +0000

Introduction

To handle Drag 'n Drop events with X11, you must use the XDnD protocol. Although the XDnD protocol is significantly more complicated than other Drag 'n Drop APIs, it's still relatively simple in theory. However, implementing it is tedious because it requires properly communicating with the X11 server and the source window.

This tutorial explains how to handle the XDnD protocol and manage X11 Drag 'n Drop events. The code is based on RGFW's source code.

Overview

A detailed overview of the steps required:

First, X11 Atoms will be initialized. X11 Atoms are used to ask for or send specific data or properties through X11.
Then, the window's properties will be changed, allowing it to be aware of XDND (X Drag 'n Drop) events.
When a drag happens, the window will receive a ClientMessage Event which includes an XdndEnter message telling the target window that the drag has started.
While the drag is in progress, the source window sends updates about the drag to the target window via ClientMessage events. Each time the target window gets an update, it must confirm it received the update; otherwise, the interaction will end.
Once the drop happens, the source window will send an XdndDrop message. Then the target window will convert the drop selection via X11 and will receive an SelectionNotify event to get the converted data.
The target window will handle this event, convert the data to a readable string, and finally send a ClientMessage with the XdndFinished atom to tell the source window that the interaction is done.

A quick overview of the steps required:

1) Define X11 Atoms
2) Enable XDnD events for the window
3) Handle XDnD events via ClientMessage
4) Get the XDnD drop data via ClientMessage and end the interaction

Step 1 (Define X11 Atoms)

To handle XDnD events, XDnD atoms must be initialized via XInternAtom. Atoms are used when sending or requesting specific data or actions.

XdndTypeList is used when the target window wants to know the data types the source window supports.\
XdndSelection is used to examine the data selection after a drop and to retrieve the data after it is converted.

const Atom XdndTypeList = XInternAtom(display, "XdndTypeList", False);
const Atom XdndSelection = XInternAtom(display, "XdndSelection", False);

These generic Xdnd atoms are messages sent by the source window except for XdndStatus.

XdndEnter, is used when the drop has entered the target window.\
XdndPosition is used to update the target window on the position of the drop.\
XdndStatus is used to tell the source window that the target has received the message.\
XdndLeave is used when the drop has left the target window.\
XdndDrop is used when the drop has been dropped into the target window.\
XdndFinished is used when the drop has been finished.\

const Atom XdndEnter = XInternAtom(display, "XdndEnter", False);
const Atom XdndPosition = XInternAtom(display, "XdndPosition", False);
const Atom XdndStatus = XInternAtom(display, "XdndStatus", False);
const Atom XdndLeave = XInternAtom(display, "XdndLeave", False);    
const Atom XdndDrop = XInternAtom(display, "XdndDrop", False);  
const Atom XdndFinished = XInternAtom(display, "XdndFinished", False);

Xdnd Actions are actions the target window wants to make with the drag data.

XdndActionCopy is used when the target window wants to copy the drag data.

const Atom XdndActionCopy = XInternAtom(display, "XdndActionCopy", False);

The text/uri-list and text/plain atoms are needed to check the format of the drop data.

const Atom XtextUriList = XInternAtom((Display*) display, "text/uri-list", False); 
const Atom XtextPlain = XInternAtom((Display*) display, "text/plain", False);

Step 2 (Enable XDnD events for the window)

To receive XDnD events, the window must enable the XDndAware atom. This atom tells the window manager and the source window that the window wants to receive XDnD events.

This can be done by creating an XdndAware atom and using XChangeProperty to change the window's XdndAware property.

You also must set the XDnD version using a pointer, version 5 should be used as it is the newest version of the XDnD protocol.

const Atom XdndAware = XInternAtom(display, "XdndAware", False);
const char myversion = 5;

XChangeProperty(display, window, XdndAware, 4, 32, PropModeReplace, &myversion, 1);

Step 3 (Handle XDnD events via ClientMessage)

Before any events are handled, some variables must be defined.
These variables are given to us by the source window and are used across multiple instances.

These variables are the source window, the XDnD Protocall version used, and the format of the drop data.

int64_t source, version;
int32_t format;

Now the ClientMessage event can be handled.

case ClientMessage:

First, I will create a generic XEvent structure to reply to XDnD events. This is optional, but in using it we will have to do less work.

This will send the event to the source window and include our window (the target) in the data.

XEvent reply = { ClientMessage };
reply.xclient.window = source;
reply.xclient.format = 32;
reply.xclient.data.l[0] = (long) window;
reply.xclient.data.l[1] = 0;
reply.xclient.data.l[2] = None;

The ClientMessage event structure can be accessed via XEvent.xclient.

message_type is an attribute in the structure, it holds what the message type is. We will use it to check if the message type is an XDnD message.

There are 3 XDnD events we will handle, XdndEnter, XdndPosition, and XdndDrop.

Step 3.1 (XdndEnter)

XdndEnter is sent when the drop enters the target window.

if (E.xclient.message_type == XdndEnter) {

First, RGFW inits the required variables.

count: number of formats in the the format list,
formats: the list of supported formats and
real_formats: this is used here to avoid running malloc for each drop

    unsigned long count;
    Atom* formats;
    Atom real_formats[6];

We can also create a bool to check if the supported formats are a list or if there is only one format.

This can be done by using the xclient's data attribute. Data is a list of data about the event.

the first item is the source window.

The second item of the data includes two values, if the format is a list or not and the version of XDnD used.

To get the bool value, you can check the first bit, the version is stored 24 bits after (the final 40 bits).

The format should be set to None for now, also make sure the version is less than or equal to 5. Otherwise, there's probably an issue because 5 is the newest version.

    Bool list = E.xclient.data.l[1] & 1;

    source = E.xclient.data.l[0];
    version = E.xclient.data.l[1] >> 24;
    format = None;

    if (version > 5)
        break;

If the format is a list, we'll have to get the format list from the source window's XDndTypeList value using XGetWindowProperty

    if (list) {
        Atom actualType;
        int32_t actualFormat;
        unsigned long bytesAfter;

        XGetWindowProperty((Display*) display,
            source,
            XdndTypeList,
            0,
            LONG_MAX,
            False,
            4,
            &actualType,
            &actualFormat,
            &count,
            &bytesAfter,
            (unsigned char**) &formats);
    }

Otherwise, the format can be found using the leftover xclient values (2 - 4)

    else {
        count = 0;

        if (E.xclient.data.l[2] != None)
            real_formats[count++] = E.xclient.data.l[2];
        if (E.xclient.data.l[3] != None)
            real_formats[count++] = E.xclient.data.l[3];
        if (E.xclient.data.l[4] != None)
            real_formats[count++] = E.xclient.data.l[4];

        formats = real_formats;
    }

Now that we have the format array, we can check if the format matches any of the formats we're looking for.

The list should also be freed using XFree if it was received using XGetWindowProperty.

    unsigned long i;
    for (i = 0; i < count; i++) {
        if (formats[i] == XtextUriList || formats[i] == XtextPlain) {
            format = formats[i];
            break;
        }
    }

    if (list) {
        XFree(formats);
    }

    break;
}

Step 3.2 (XdndPosition)

XdndPosition is used when the drop position is updated.

Before we handle the event, make sure the version is correct.

if (E.xclient.message_type == XdndPosition && version <= 5)) {

The absolute X and Y can be found using the second item of the data list.

The X = the last 32 bits.
The Y = the first 32 bits.

    const int32_t xabs = (E.xclient.data.l[2] >> 16) & 0xffff;
    const int32_t yabs = (E.xclient.data.l[2]) & 0xffff;

The absolute X and Y can be translated to the actual X and Y coordinates of the drop position using XTranslateCoordinates.

    Window dummy;
    int32_t xpos, ypos;

    XTranslateCoordinates((Display*) display,
        XDefaultRootWindow((Display*) display),
        (Window) window,
        xabs, yabs,
        &xpos, &ypos,
        &dummy);

    printf("File drop starting at %i %i\n", xpos, ypos);

A response must be sent back to the source window. The response uses XdndStatus to tell the window it has received the message.

We should also tell the source the action accepted with the data. (XdndActionCopy)

The message can be sent out via XSendEvent make sure you also send out XFlush to make sure the event is pushed out.

    reply.xclient.message_type = XdndStatus;

    if (format) {
        reply.xclient.data.l[1] = 1;
        if (version >= 2)
            reply.xclient.data.l[4] = XdndActionCopy;
    }

    XSendEvent((Display*) display, source, False, NoEventMask, &reply);
    XFlush((Display*) display);
    break;
}

Step 3.3 (XdndDrop)

Before we handle the event, make sure the version is correct.

XdndDrop occurs when the item has been dropped.

if (E.xclient.message_type = XdndDrop && version <= 5) {

First, we should make sure we registered a valid format earlier.

    if (format) {

We can use XConvertSection to request that the selection be converted to the format.

We will get the result in an SelectionNotify event.

        // newer versions of xDnD require us to tell the source our time 
        Time time = CurrentTime;
        if (version >= 1)
            time = E.xclient.data.l[2];

        XConvertSelection((Display*) display,
            XdndSelection,
            format,
            XdndSelection,
            (Window) window,
            time);
    }

Otherwise, there is no drop data and the drop has ended. XDnD versions 2 and older require the target to tell the source when the drop has ended.

This can be done by sending out a ClientMessage event with the XdndFinished message type.

    else if (version >= 2) {
        reply.xclient.message_type = XdndFinished;

        XSendEvent((Display*) display, source,
            False, NoEventMask, &reply);
        XFlush((Display*) display);
    }
}

Step 4 (Get the XDnD drop data via ClientMessage and end the interaction)

Now we can receive the converted selection from the SlectionNotify event

case SelectionNotify: {

To do this, first, ensure the property is the XdndSelection.

/* this is only for checking for drops */

if (E.xselection.property != XdndSelection)
    break;

XGetWindowpropery can be used to get the selection data.

char* data;
unsigned long result;

Atom actualType;
int32_t actualFormat;
unsigned long bytesAfter;

XGetWindowProperty((Display*) display, E.xselection.requestor, E.xselection.property, \
                                    0, LONG_MAX, False, E.xselection.target, &actualType, 
                                    &actualFormat, &result, &bytesAfter, 
                                    (unsigned char**) &data);

if (result == 0)
    break;

printf("File dropped: %s\n", data);

This is the raw string data for the drop. If there are multiple drops, it will include the files separated by a '\n'. If you'd prefer an array of strings, you'd have to parse the data into an array.

The data should also be freed once you're done using it.

If you want to use the data after the event has been processed, you should allocate a separate buffer and copy the data over.

if (data)
    XFree(data);

the drop has ended and XDnD versions 2 and older require the target to tell the source when the drop has ended.
This can be done by sending out a ClientMessage event with the XdndFinished message type.

It will also include the action we did with the data and the result to tell the source wether or not we actually got the data.

if (version >= 2) {
    reply.xclient.message_type = XdndFinished;
    reply.xclient.data.l[1] = result;
    reply.xclient.data.l[2] = XdndActionCopy;

    XSendEvent((Display*) display, source, False, NoEventMask, &reply);
    XFlush((Display*) display);
}

Full code example

// This compiles with
// gcc example.c -lX11

#include <X11/Xlib.h>
#include <stdio.h>

#include <stdint.h>
#include <limits.h>

int main(void) {
    Display* display = XOpenDisplay(NULL);

    Window window = XCreateSimpleWindow(display, 
                                        RootWindow(display, DefaultScreen(display)), 
                                        10, 10, 200, 200, 1,
                                        BlackPixel(display, DefaultScreen(display)), WhitePixel(display, DefaultScreen(display)));

    XSelectInput(display, window, ExposureMask | KeyPressMask);

    const Atom wm_delete_window = XInternAtom((Display*) display, "WM_DELETE_WINDOW", False);

    /* Xdnd code */

    /* fetching data */
    const Atom XdndTypeList = XInternAtom(display, "XdndTypeList", False);
    const Atom XdndSelection = XInternAtom(display, "XdndSelection", False);

    /* client messages */
    const Atom XdndEnter = XInternAtom(display, "XdndEnter", False);
    const Atom XdndPosition = XInternAtom(display, "XdndPosition", False);
    const Atom XdndStatus = XInternAtom(display, "XdndStatus", False);
    const Atom XdndLeave = XInternAtom(display, "XdndLeave", False);    
    const Atom XdndDrop = XInternAtom(display, "XdndDrop", False);  
    const Atom XdndFinished = XInternAtom(display, "XdndFinished", False);

    /* actions */
    const Atom XdndActionCopy = XInternAtom(display, "XdndActionCopy", False);
    const Atom XdndActionMove = XInternAtom(display, "XdndActionMove", False);
    const Atom XdndActionLink = XInternAtom(display, "XdndActionLink", False);
    const Atom XdndActionAsk = XInternAtom(display, "XdndActionAsk", False);
    const Atom XdndActionPrivate = XInternAtom(display, "XdndActionPrivate", False);

    const Atom XtextUriList = XInternAtom((Display*) display, "text/uri-list", False); 
    const Atom XtextPlain = XInternAtom((Display*) display, "text/plain", False);

    const Atom XdndAware = XInternAtom(display, "XdndAware", False);
    const char myVersion = 5;
    XChangeProperty(display, window, XdndAware, 4, 32, PropModeReplace, &myVersion, 1);

    XMapWindow(display, window);

    XEvent E;
    Bool running = True;

    int64_t source, version;
    int32_t format;

    while (running) {
        XNextEvent(display, &E);

        switch (E.type) {
            case KeyPress: running = False; break;
            case ClientMessage:
                if (E.xclient.data.l[0] == (int64_t) wm_delete_window) {
                    running = False;
                    break;
                }

                XEvent reply = { ClientMessage };
                reply.xclient.window = source;
                reply.xclient.format = 32;
                reply.xclient.data.l[0] = (long) window;
                reply.xclient.data.l[2] = 0;
                reply.xclient.data.l[3] = 0;


                if (E.xclient.message_type == XdndEnter) {
                    unsigned long count;
                    Atom* formats;
                    Atom real_formats[6];

                    Bool list = E.xclient.data.l[1] & 1;

                    source = E.xclient.data.l[0];
                    version = E.xclient.data.l[1] >> 24;
                    format = None;

                    if (version > 5)
                        break;

                    if (list) {
                        Atom actualType;
                        int32_t actualFormat;
                        unsigned long bytesAfter;

                        XGetWindowProperty((Display*) display,
                            source,
                            XdndTypeList,
                            0,
                            LONG_MAX,
                            False,
                            4,
                            &actualType,
                            &actualFormat,
                            &count,
                            &bytesAfter,
                            (unsigned char**) &formats);
                    } else {
                        count = 0;

                        if (E.xclient.data.l[2] != None)
                            real_formats[count++] = E.xclient.data.l[2];
                        if (E.xclient.data.l[3] != None)
                            real_formats[count++] = E.xclient.data.l[3];
                        if (E.xclient.data.l[4] != None)
                            real_formats[count++] = E.xclient.data.l[4];

                        formats = real_formats;
                    }

                    unsigned long i;
                    for (i = 0; i < count; i++) {
                        if (formats[i] == XtextUriList || formats[i] == XtextPlain) {
                            format = formats[i];
                            break;
                        }
                    }

                    if (list) {
                        XFree(formats);
                    }

                    break;
                }
                if (E.xclient.message_type == XdndPosition) {
                    const int32_t xabs = (E.xclient.data.l[2] >> 16) & 0xffff;
                    const int32_t yabs = (E.xclient.data.l[2]) & 0xffff;
                    Window dummy;
                    int32_t xpos, ypos;

                    if (version > 5)
                        break;

                    XTranslateCoordinates((Display*) display,
                        XDefaultRootWindow((Display*) display),
                        (Window) window,
                        xabs, yabs,
                        &xpos, &ypos,
                        &dummy);

                    printf("File drop starting at %i %i\n", xpos, ypos);

                    reply.xclient.message_type = XdndStatus;

                    if (format) {
                        reply.xclient.data.l[1] = 1;
                        if (version >= 2)
                            reply.xclient.data.l[4] = XdndActionCopy;
                    }

                    XSendEvent((Display*) display, source, False, NoEventMask, &reply);
                    XFlush((Display*) display);
                    break;
                }

                if (E.xclient.message_type = XdndDrop && version <= 5) {
                    if (format) {
                        Time time = CurrentTime;

                        if (version >= 1)
                            time = E.xclient.data.l[2];

                        XConvertSelection((Display*) display,
                            XdndSelection,
                            format,
                            XdndSelection,
                            (Window) window,
                            time);
                    } else if (version >= 2) {
                        reply.xclient.message_type = XdndFinished;

                        XSendEvent((Display*) display, source,
                            False, NoEventMask, &reply);
                        XFlush((Display*) display);
                    }
                }
                break;
        case SelectionNotify: {
            /* this is only for checking for drops */
            if (E.xselection.property != XdndSelection)
                break;

            char* data;
            unsigned long result;

            Atom actualType;
            int32_t actualFormat;
            unsigned long bytesAfter;

            XGetWindowProperty((Display*) display, 
                                            E.xselection.requestor, E.xselection.property, 
                                            0, LONG_MAX, False, E.xselection.target, 
                                            &actualType, &actualFormat, &result, &bytesAfter, 
                                            (unsigned char**) &data);

            if (result == 0)
                break;

            printf("File(s) dropped: %s\n", data);

            if (data)
                XFree(data);

            if (version >= 2) {
                reply.xclient.message_type = XdndFinished;
                reply.xclient.data.l[1] = result;
                reply.xclient.data.l[2] = XdndActionCopy;

                XSendEvent((Display*) display, source, False, NoEventMask, &reply);
                XFlush((Display*) display);
            }

            break;
        }

            default: break;
        }
    }

    XCloseDisplay(display);
}

RGFW Under the Hood: Cocoa in Pure C

Colleague Riley — Mon, 26 Aug 2024 21:46:32 +0000

Introduction

To use Apple's Cocoa API, you must use Objective-C function calls. However, you do not have to write Objective-C code because Objective-C can be accessed via C functions such as objc_msgSend.

The main reason to use Pure-C over Objective-C is to be able to compile your project in C. This is helpful if you want to create a single-header file that does not require the user to compile using Objective-C.

Two examples of this are:

Silicon.h, a C-Wrapper for the Cocoa API that wraps around the Objective-C function calls so you can use the Cocoa API in normal-looking C code, and RGFW, a lightweight single-header windowing library.

Both projects can be used as a reference for using Cocoa in C.

Overview

A quick overview of the topics the article will cover

1) The Basics of Using Objective-C in Pure C
2) Defining Cocoa Types
3) Creating a Basic Cocoa Window

1. The Basics of using Objective-C in Pure C

Objective-C functions can be called using objc_msgsend.

Due to ABI differences, ARM uses objc_msgsend for all cases. However x86_64 CPUs require the use of specific functions for floating point and structure returns.
objc_msgsend_fpret for functions with floating point returns and
objc_msgsend_fstret for functions that return a structure.

RGFW handles this like this:

#include <objc/runtime.h>
#include <objc/message.h> 

#ifdef __arm64__
/* ARM just uses objc_msgSend */
#define abi_objc_msgSend_stret objc_msgSend
#define abi_objc_msgSend_fpret objc_msgSend
#else /* __i386__ */
/* x86 just uses abi_objc_msgSend_fpret and (NSColor *)objc_msgSend_id respectively */
#define abi_objc_msgSend_stret objc_msgSend_stret
#define abi_objc_msgSend_fpret objc_msgSend_fpret
#endif

objc_msgSend is a generic function, so its type must be cast based on the return and argument types you want.

For example: ((int (*)(id, SEL, int))objc_msgSend) for a function that takes an int argument and returns an int.

To avoid repeating commonly used type-casting, RGFW defines macros to handle common cases.

#define objc_msgSend_id             ((id (*)(id, SEL))objc_msgSend)
#define objc_msgSend_id_id          ((id (*)(id, SEL, id))objc_msgSend)
#define objc_msgSend_id_rect        ((id (*)(id, SEL, NSRect))objc_msgSend)
#define objc_msgSend_uint           ((NSUInteger (*)(id, SEL))objc_msgSend)
#define objc_msgSend_int            ((NSInteger (*)(id, SEL))objc_msgSend)
#define objc_msgSend_SEL            ((SEL (*)(id, SEL))objc_msgSend)
#define objc_msgSend_float          ((CGFloat (*)(id, SEL))abi_objc_msgSend_fpret)
#define objc_msgSend_bool           ((BOOL (*)(id, SEL))objc_msgSend)
#define objc_msgSend_void           ((void (*)(id, SEL))objc_msgSend)
#define objc_msgSend_double         ((double (*)(id, SEL))objc_msgSend)
#define objc_msgSend_void_id        ((void (*)(id, SEL, id))objc_msgSend)
#define objc_msgSend_void_uint      ((void (*)(id, SEL, NSUInteger))objc_msgSend)
#define objc_msgSend_void_int       ((void (*)(id, SEL, NSInteger))objc_msgSend)
#define objc_msgSend_void_bool      ((void (*)(id, SEL, BOOL))objc_msgSend)
#define objc_msgSend_void_float     ((void (*)(id, SEL, CGFloat))objc_msgSend)
#define objc_msgSend_void_double    ((void (*)(id, SEL, double))objc_msgSend)
#define objc_msgSend_void_SEL       ((void (*)(id, SEL, SEL))objc_msgSend)
#define objc_msgSend_id_char_const  ((id (*)(id, SEL, char const *))objc_msgSend)

You might notice two common arguments in these functions, id and SEL

The id argument refers to an ID of an Objective-C object or class.

SEL refers to the function's selector.

For example MyObject *bar = [MyObject objectWithString:@"RGFW"]; can be translated to id* bar = [id SEL:@"RGFW"];

To get the ID to an Objective-C class you must run objc_getClass

For example: objc_getClass("NSWindow");

To get the selector for an Objective-C function you must use sel_registerName

The syntax of Objective-C functions is like this <function-name>, then : is used as a placeholder for an argument.

A function with one argument would look like this:

sel_registerName("makeKeyAndOrderFront:");

However, a function with no arguments would look like this.

sel_registerName("isKeyWindow");

If the function has multiple arguments you will have to also add the argument names (not including the first argument)

sel_registerName("initWithContentRect:styleMask:backing:defer:");

To define a class method (eg. a callback function for the object) you must use class_addMethod this function takes the delegate class (class of the object that is calling's delegate
), selector of the function being called, the function you want to be called, and the arguments expected in string format.

But first, you must allocate the delegate class to access it.
You can do this using objc_allocateClassPair.

For example to allocate the delegate class for an NSWindow:

Class delegateClass = objc_allocateClassPair(objc_getClass("NSObject"), "WindowDelegate", 0);

To create a call back you have to use class_addMethod to set it as the callback for the class.

Creating a call back for NSWindow's windowWillResize would look like this:

class_addMethod(delegateClass, sel_registerName("windowWillResize:toSize:"), (IMP) windowResize, "{NSSize=ff}@:{NSSize=ff}");

You can also add custom user variables to the class, these can be used to attach user data to the class.

For example, RGFW attaches an RGFW_window to the NSWindow class to modify the RGFW_window* data. This can be done using class_addIvar

class_addIvar(
    delegateClass, "RGFW_window",
    sizeof(RGFW_window*), rint(log2(sizeof(RGFW_window*))),
    "L" 
);

To set the variable to use for your NSWindow instance, use

object_setInstanceVariable

To set the RGFW_window object to be the variable instance for its NSWindow object:

object_setInstanceVariable(delegate, "NSWindow", window);

You can get the instance variable of an object via object_getInstanceVariable

RGFW_window* win = NULL;

//The object variable would be called "self" in a callback
object_getInstanceVariable(self, "RGFW_window", (void*)&win);

Defining Cocoa Types

The Cocoa header files are written in Objective-C. This means we'll have to define the types and enums ourselves.

The shape types can be defined as the CG Shapes like this:

typedef CGRect NSRect;
typedef CGPoint NSPoint;
typedef CGSize NSSize;

Cocoa also uses custom integer-type names,
these can be defined to be their matching c datatype.

typedef unsigned long NSUInteger;
typedef long NSInteger;

You can also define Cocoa objects. I define them as void so I can use them as pointers.

// Note: void is being used here 
// type* can be used ( type* == void* == id ) 
typedef void NSEvent;
typedef void NSString;
typedef void NSWindow;  
typedef void NSApplication;

As for the enums, here are some of the enums I will be using in this tutorial.

Many of the other enums can be found in Cocoa's headers, documentation, RGFW.h, or Silicon. h.

/* this macro is used to give an enum a type */ 
#define NS_ENUM(type, name) type name; enum

typedef NS_ENUM(NSUInteger, NSWindowStyleMask) {
    NSWindowStyleMaskBorderless = 0,
    NSWindowStyleMaskTitled = 1 << 0,
    NSWindowStyleMaskClosable = 1 << 1,
    NSWindowStyleMaskMiniaturizable = 1 << 2,
    NSWindowStyleMaskResizable = 1 << 3,
    NSWindowStyleMaskTexturedBackground = 1 << 8, /* deprecated */
    NSWindowStyleMaskUnifiedTitleAndToolbar = 1 << 12,
    NSWindowStyleMaskFullScreen = 1 << 14,
    NSWindowStyleMaskFullSizeContentView = 1 << 15,
    NSWindowStyleMaskUtilityWindow = 1 << 4,
    NSWindowStyleMaskDocModalWindow = 1 << 6,
    NSWindowStyleMaskNonactivatingPanel = 1 << 7,
    NSWindowStyleMaskHUDWindow = 1 << 13
};

typedef NS_ENUM(NSUInteger, NSBackingStoreType) {
    NSBackingStoreRetained = 0,
    NSBackingStoreNonretained = 1,
    NSBackingStoreBuffered = 2
};

typedef NS_ENUM(NSUInteger, NSEventType) {        /* various types of events */
    NSEventTypeLeftMouseDown             = 1,
    NSEventTypeLeftMouseUp               = 2,
    NSEventTypeRightMouseDown            = 3,
    NSEventTypeRightMouseUp              = 4,
    NSEventTypeMouseMoved                = 5,
    NSEventTypeLeftMouseDragged          = 6,
    NSEventTypeRightMouseDragged         = 7,
    NSEventTypeMouseEntered              = 8,
    NSEventTypeMouseExited               = 9,
    NSEventTypeKeyDown                   = 10,
    NSEventTypeKeyUp                     = 11,
    NSEventTypeFlagsChanged              = 12,
    NSEventTypeAppKitDefined             = 13,
    NSEventTypeSystemDefined             = 14,
    NSEventTypeApplicationDefined        = 15,
    NSEventTypePeriodic                  = 16,
    NSEventTypeCursorUpdate              = 17,
    NSEventTypeScrollWheel               = 22,
    NSEventTypeTabletPoint               = 23,
    NSEventTypeTabletProximity           = 24,
    NSEventTypeOtherMouseDown            = 25,
    NSEventTypeOtherMouseUp              = 26,
    NSEventTypeOtherMouseDragged         = 27,
    /* The following event types are available on some hardware on 10.5.2 and later */
    NSEventTypeGesture API_AVAILABLE(macos(10.5))       = 29,
    NSEventTypeMagnify API_AVAILABLE(macos(10.5))       = 30,
    NSEventTypeSwipe   API_AVAILABLE(macos(10.5))       = 31,
    NSEventTypeRotate  API_AVAILABLE(macos(10.5))       = 18,
    NSEventTypeBeginGesture API_AVAILABLE(macos(10.5))  = 19,
    NSEventTypeEndGesture API_AVAILABLE(macos(10.5))    = 20,

    NSEventTypeSmartMagnify API_AVAILABLE(macos(10.8)) = 32,
    NSEventTypeQuickLook API_AVAILABLE(macos(10.8)) = 33,

    NSEventTypePressure API_AVAILABLE(macos(10.10.3)) = 34,
    NSEventTypeDirectTouch API_AVAILABLE(macos(10.10)) = 37,

    NSEventTypeChangeMode API_AVAILABLE(macos(10.15)) = 38,
};

typedef NS_ENUM(unsigned long long, NSEventMask) { /* masks for the types of events */
    NSEventMaskLeftMouseDown         = 1ULL << NSEventTypeLeftMouseDown,
    NSEventMaskLeftMouseUp           = 1ULL << NSEventTypeLeftMouseUp,
    NSEventMaskRightMouseDown        = 1ULL << NSEventTypeRightMouseDown,
    NSEventMaskRightMouseUp          = 1ULL << NSEventTypeRightMouseUp,
    NSEventMaskMouseMoved            = 1ULL << NSEventTypeMouseMoved,
    NSEventMaskLeftMouseDragged      = 1ULL << NSEventTypeLeftMouseDragged,
    NSEventMaskRightMouseDragged     = 1ULL << NSEventTypeRightMouseDragged,
    NSEventMaskMouseEntered          = 1ULL << NSEventTypeMouseEntered,
    NSEventMaskMouseExited           = 1ULL << NSEventTypeMouseExited,
    NSEventMaskKeyDown               = 1ULL << NSEventTypeKeyDown,
    NSEventMaskKeyUp                 = 1ULL << NSEventTypeKeyUp,
    NSEventMaskFlagsChanged          = 1ULL << NSEventTypeFlagsChanged,
    NSEventMaskAppKitDefined         = 1ULL << NSEventTypeAppKitDefined,
    NSEventMaskSystemDefined         = 1ULL << NSEventTypeSystemDefined,
    NSEventMaskApplicationDefined    = 1ULL << NSEventTypeApplicationDefined,
    NSEventMaskPeriodic              = 1ULL << NSEventTypePeriodic,
    NSEventMaskCursorUpdate          = 1ULL << NSEventTypeCursorUpdate,
    NSEventMaskScrollWheel           = 1ULL << NSEventTypeScrollWheel,
    NSEventMaskTabletPoint           = 1ULL << NSEventTypeTabletPoint,
    NSEventMaskTabletProximity       = 1ULL << NSEventTypeTabletProximity,
    NSEventMaskOtherMouseDown        = 1ULL << NSEventTypeOtherMouseDown,
    NSEventMaskOtherMouseUp          = 1ULL << NSEventTypeOtherMouseUp,
    NSEventMaskOtherMouseDragged     = 1ULL << NSEventTypeOtherMouseDragged,
};
/* The following event masks are available on some hardware on 10.5.2 and later */
#define NSEventMaskGesture API_AVAILABLE(macos(10.5))          (1ULL << NSEventTypeGesture)
#define NSEventMaskMagnify API_AVAILABLE(macos(10.5))          (1ULL << NSEventTypeMagnify)
#define NSEventMaskSwipe API_AVAILABLE(macos(10.5))            (1ULL << NSEventTypeSwipe)
#define NSEventMaskRotate API_AVAILABLE(macos(10.5))           (1ULL << NSEventTypeRotate)
#define NSEventMaskBeginGesture API_AVAILABLE(macos(10.5))     (1ULL << NSEventTypeBeginGesture)
#define NSEventMaskEndGesture API_AVAILABLE(macos(10.5))       (1ULL << NSEventTypeEndGesture)

/* Note: You can only use these event masks on 64 bit. In other words, you cannot setup a local, nor global, event monitor for these event types on 32 bit. Also, you cannot search the event queue for them (nextEventMatchingMask:...) on 32 bit. */
#define NSEventMaskSmartMagnify API_AVAILABLE(macos(10.8)) (1ULL << NSEventTypeSmartMagnify)
#define NSEventMaskPressure API_AVAILABLE(macos(10.10.3)) (1ULL << NSEventTypePressure)
#define NSEventMaskDirectTouch API_AVAILABLE(macos(10.12.2)) (1ULL << NSEventTypeDirectTouch)
#define NSEventMaskChangeMode API_AVAILABLE(macos(10.15)) (1ULL << NSEventTypeChangeMode)
#define NSEventMaskAny              NSUIntegerMax

typedef NS_ENUM(NSUInteger, NSEventModifierFlags) {
    NSEventModifierFlagCapsLock           = 1 << 16, // Set if Caps Lock key is pressed.
    NSEventModifierFlagShift              = 1 << 17, // Set if Shift key is pressed.
    NSEventModifierFlagControl            = 1 << 18, // Set if Control key is pressed.
    NSEventModifierFlagOption             = 1 << 19, // Set if Option or Alternate key is pressed.
    NSEventModifierFlagCommand            = 1 << 20, // Set if Command key is pressed.
    NSEventModifierFlagNumericPad         = 1 << 21, // Set if any key in the numeric keypad is pressed.
    NSEventModifierFlagHelp               = 1 << 22, // Set if the Help key is pressed.
    NSEventModifierFlagFunction           = 1 << 23, // Set if any function key is pressed.
};

RGFW also defines NSAlloc and NSRelease because they're basic functions that are used a lot.

#define NSAlloc(nsclass) objc_msgSend_id((id)nsclass, sel_registerName("alloc"))
#define NSRelease(nsclass) objc_msgSend_id((id)nsclass, sel_registerName("release"))

3. Creating a Basic Cocoa Window

Now that you understand the basics of calling Objective-C functions from C, and the setup required to use Cocoa, it's time to apply that for creating a basic window using Cocoa.

First, some library headers are required.

#include <CoreVideo/CVDisplayLink.h> // !
#include <ApplicationServices/ApplicationServices.h>

#include <string.h>

These functions will be used for printing information about the current event.

const char* NSEventTypeToChar(NSEventType eventType);
const char* NSEventModifierFlagsToChar(NSEventModifierFlags modifierFlags);

// These will be placed after the main function and will be defined like this:
const char* NSEventTypeToChar(NSEventType eventType) {
    switch (eventType) {
        case NSEventTypeLeftMouseDown: return "LeftMouseDown";
        case NSEventTypeLeftMouseUp: return "LeftMouseUp";
        case NSEventTypeRightMouseDown: return "RightMouseDown";
        case NSEventTypeRightMouseUp: return "RightMouseUp";
        case NSEventTypeMouseMoved: return "MouseMoved";
        case NSEventTypeLeftMouseDragged: return "LeftMouseDragged";
        case NSEventTypeRightMouseDragged: return "RightMouseDragged";
        case NSEventTypeMouseEntered: return "MouseEntered";
        case NSEventTypeMouseExited: return "MouseExited";
        case NSEventTypeKeyDown: return "KeyDown";
        case NSEventTypeKeyUp: return "KeyUp";
        case NSEventTypeFlagsChanged: return "FlagsChanged";
        case NSEventTypeAppKitDefined: return "AppKitDefined";
        case NSEventTypeSystemDefined: return "SystemDefined";
        case NSEventTypeApplicationDefined: return "ApplicationDefined";
        case NSEventTypePeriodic: return "Periodic";
        case NSEventTypeCursorUpdate: return "CursorUpdate";
        case NSEventTypeScrollWheel: return "ScrollWheel";
        case NSEventTypeTabletPoint: return "TabletPoint";
        case NSEventTypeTabletProximity: return "TabletProximity";
        case NSEventTypeOtherMouseDown: return "OtherMouseDown";
        case NSEventTypeOtherMouseUp: return "OtherMouseUp";
        case NSEventTypeOtherMouseDragged: return "OtherMouseDragged";
        default: return "N/A";
    }
}

char* ns_strcat(register char *s, register const char *append) {
    char *save = s;

    for (; *s; ++s);
    while ((*s++ = *append++));
    return save;
}

const char* NSEventModifierFlagsToChar(NSEventModifierFlags modifierFlags) {
    static char result[100];
    result[0] = '\0';

    if ((modifierFlags & NSEventModifierFlagCapsLock) == NSEventModifierFlagCapsLock) ns_strcat(result, "CapsLock, ");
    if ((modifierFlags & NSEventModifierFlagShift) == NSEventModifierFlagShift) ns_strcat(result, "NShift, ");
    if ((modifierFlags & NSEventModifierFlagControl) == NSEventModifierFlagControl) ns_strcat(result, "Control, ");
    if ((modifierFlags & NSEventModifierFlagOption) == NSEventModifierFlagOption) ns_strcat(result, "Option, ");
    if ((modifierFlags & NSEventModifierFlagCommand) == NSEventModifierFlagCommand) ns_strcat(result, "Command, ");
    if ((modifierFlags & NSEventModifierFlagNumericPad) == NSEventModifierFlagNumericPad) ns_strcat(result, "NumericPad, ");
    if ((modifierFlags & NSEventModifierFlagHelp) == NSEventModifierFlagHelp) ns_strcat(result, "Help, ");
    if ((modifierFlags & NSEventModifierFlagFunction) == NSEventModifierFlagFunction) ns_strcat(result, "Function, ");

    return result;
}

Cocoa does not handle certain events using the event loop.
Instead, they're fed to the NSWindow via callbacks.

Here's how these functions will be defined for this example:

bool running = true;

unsigned int onClose(void* self) {
    NSWindow* win = NULL;
    object_getInstanceVariable(self, "NSWindow", (void*)&win);
    if (win == NULL)
        return true;

    running = false;

    return true;
}

NSSize windowResize(void* self, SEL sel, NSSize frameSize) {
    NSWindow* win = NULL;
    object_getInstanceVariable(self, "NSWindow", (void*)&win);
    if (win == NULL)
        return frameSize;

    printf("window resized to %f %f\n", frameSize.width, frameSize.height);
    return frameSize;
}

The first thing that I will do in the main function is define the windowShouldClose callback.

This is so that way the program doesn't keep running after the window is closed.

class_addMethod(objc_getClass("NSObject"), sel_registerName("windowShouldClose:"), (IMP) onClose, 0);

Next, the NSApplication is set up.

This requires the use of sharedApplication and setActivationPolicy

NSApplication* NSApp = objc_msgSend_id((id)objc_getClass("NSApplication"), sel_registerName("sharedApplication"));
objc_msgSend_void_id(NSApp, sel_registerName("setActivationPolicy:"), NSApplicationActivationPolicyRegular);

Now you can create a NSWindow can be created, I broke the window creation process into three steps so it's more readable.

The window is created using initWithContentRect

NSBackingStoreType macArgs = NSWindowStyleMaskClosable | NSWindowStyleMaskMiniaturizable | NSBackingStoreBuffered | NSWindowStyleMaskTitled | NSWindowStyleMaskResizable;

SEL func = sel_registerName("initWithContentRect:styleMask:backing:defer:");

NSWindow* window = ((id (*)(id, SEL, NSRect, NSWindowStyleMask, NSBackingStoreType, bool))objc_msgSend)
            (NSAlloc(objc_getClass("NSWindow")), func, 
                        (NSRect){{200, 200}, {200, 200}}, 
                        macArgs, macArgs, false);

You can then set up the delegate class and window resize callback.

Class delegateClass = objc_allocateClassPair(objc_getClass("NSObject"), "WindowDelegate", 0);

class_addIvar(
        delegateClass, "NSWindow",
        sizeof(NSWindow*), rint(log2(sizeof(NSWindow*))),
        "L"
);

class_addMethod(delegateClass, sel_registerName("windowWillResize:toSize:"), (IMP) windowResize, "{NSSize=ff}@:{NSSize=ff}");

After that, the delegate must be initialized using init

Then I will set the delegate's variable data as our NSWindow and set the NSWindow's delegate to be the delegate we initialized using setDelegate

id delegate = objc_msgSend_id(NSAlloc(delegateClass), sel_registerName("init"));

object_setInstanceVariable(delegate, "NSWindow", window);

objc_msgSend_void_id(window, sel_registerName("setDelegate:"), delegate);

Then the window can be shown using setIsVisible and made key and front via makeKeyAndOrderFront, this puts it in focus.

activatIgnoredOtherApps is required to open the window

objc_msgSend_void_bool(NSApp, sel_registerName("activateIgnoringOtherApps:"), true);
((id(*)(id, SEL, SEL))objc_msgSend)(window, sel_registerName("makeKeyAndOrderFront:"), NULL);
objc_msgSend_void_bool(window, sel_registerName("setIsVisible:"), true);

objc_msgSend_void(NSApp, sel_registerName("finishLaunching"));

Now, in the draw loop, I'd start by creating a memory pool.

This is so that way all memory allocated by event checking can be freed at once, avoiding a memory leak.

This can be done using NSAutoreleasePool

id pool = objc_msgSend_id(NSAlloc(objc_getClass("NSAutoreleasePool")), sel_registerName("init"));

Now the current event can be checked using an NSEvent object and nextEventMatchingMask

The event type can be found using type
The event mouse point can be found using locationInWindow
The event modifier flags can be found using modifierFlags

NSEvent* e = (NSEvent*) ((id(*)(id, SEL, NSEventMask, void*, NSString*, bool))objc_msgSend) (NSApp, sel_registerName("nextEventMatchingMask:untilDate:inMode:dequeue:"), ULONG_MAX, NULL,                           ((id(*)(id, SEL, const char*))objc_msgSend) ((id)objc_getClass("NSString"), sel_registerName("stringWithUTF8String:"), "kCFRunLoopDefaultMode"), true);

unsigned int type = objc_msgSend_uint(e, sel_registerName("type"));  

NSPoint p = ((NSPoint(*)(id, SEL)) objc_msgSend)(e, sel_registerName("locationInWindow"));

Before I check the event, I make sure there is an event.

if (type == 0)
    printf("Event [type=%s location={%f, %f} modifierFlags={%s}]\n", 
                        NSEventTypeToChar(type), 
                        p.x, p.y, 
                        NSEventModifierFlagsToChar(objc_msgSend_uint(e, sel_registerName("modifierFlags"))));

The event can be pushed out using sendEvent and the window can be updated using updateWindows

objc_msgSend_void_id(NSApp, sel_registerName("sendEvent:"), e);
((void(*)(id, SEL))objc_msgSend)(NSApp, sel_registerName("updateWindows"));

At the end of the draw loop, the event pool should be freed.

NSRelease(pool);

Full code example

// compile with:
// gcc example.c -lm -framework Foundation -framework AppKit -framework CoreVideo

#include <objc/runtime.h>
#include <objc/message.h>
#include <CoreVideo/CVDisplayLink.h>
#include <ApplicationServices/ApplicationServices.h>

#ifdef __arm64__
/* ARM just uses objc_msgSend */
#define abi_objc_msgSend_stret objc_msgSend
#define abi_objc_msgSend_fpret objc_msgSend
#else /* __i386__ */
/* x86 just uses abi_objc_msgSend_fpret and (NSColor *)objc_msgSend_id respectively */
#define abi_objc_msgSend_stret objc_msgSend_stret
#define abi_objc_msgSend_fpret objc_msgSend_fpret
#endif

typedef CGRect NSRect;
typedef CGPoint NSPoint;
typedef CGSize NSSize;

typedef void NSEvent;
typedef void NSString;
typedef void NSWindow;  
typedef void NSApplication;

typedef unsigned long NSUInteger;
typedef long NSInteger;

#define NS_ENUM(type, name) type name; enum 

typedef NS_ENUM(NSUInteger, NSWindowStyleMask) {
    NSWindowStyleMaskBorderless = 0,
    NSWindowStyleMaskTitled = 1 << 0,
    NSWindowStyleMaskClosable = 1 << 1,
    NSWindowStyleMaskMiniaturizable = 1 << 2,
    NSWindowStyleMaskResizable = 1 << 3,
    NSWindowStyleMaskTexturedBackground = 1 << 8, /* deprecated */
    NSWindowStyleMaskUnifiedTitleAndToolbar = 1 << 12,
    NSWindowStyleMaskFullScreen = 1 << 14,
    NSWindowStyleMaskFullSizeContentView = 1 << 15,
    NSWindowStyleMaskUtilityWindow = 1 << 4,
    NSWindowStyleMaskDocModalWindow = 1 << 6,
    NSWindowStyleMaskNonactivatingPanel = 1 << 7,
    NSWindowStyleMaskHUDWindow = 1 << 13
};

typedef NS_ENUM(NSUInteger, NSBackingStoreType) {
    NSBackingStoreRetained = 0,
    NSBackingStoreNonretained = 1,
    NSBackingStoreBuffered = 2
};

typedef NS_ENUM(NSUInteger, NSEventType) {        /* various types of events */
    NSEventTypeLeftMouseDown             = 1,
    NSEventTypeLeftMouseUp               = 2,
    NSEventTypeRightMouseDown            = 3,
    NSEventTypeRightMouseUp              = 4,
    NSEventTypeMouseMoved                = 5,
    NSEventTypeLeftMouseDragged          = 6,
    NSEventTypeRightMouseDragged         = 7,
    NSEventTypeMouseEntered              = 8,
    NSEventTypeMouseExited               = 9,
    NSEventTypeKeyDown                   = 10,
    NSEventTypeKeyUp                     = 11,
    NSEventTypeFlagsChanged              = 12,
    NSEventTypeAppKitDefined             = 13,
    NSEventTypeSystemDefined             = 14,
    NSEventTypeApplicationDefined        = 15,
    NSEventTypePeriodic                  = 16,
    NSEventTypeCursorUpdate              = 17,
    NSEventTypeScrollWheel               = 22,
    NSEventTypeTabletPoint               = 23,
    NSEventTypeTabletProximity           = 24,
    NSEventTypeOtherMouseDown            = 25,
    NSEventTypeOtherMouseUp              = 26,
    NSEventTypeOtherMouseDragged         = 27,
    /* The following event types are available on some hardware on 10.5.2 and later */
    NSEventTypeGesture API_AVAILABLE(macos(10.5))       = 29,
    NSEventTypeMagnify API_AVAILABLE(macos(10.5))       = 30,
    NSEventTypeSwipe   API_AVAILABLE(macos(10.5))       = 31,
    NSEventTypeRotate  API_AVAILABLE(macos(10.5))       = 18,
    NSEventTypeBeginGesture API_AVAILABLE(macos(10.5))  = 19,
    NSEventTypeEndGesture API_AVAILABLE(macos(10.5))    = 20,

    NSEventTypeSmartMagnify API_AVAILABLE(macos(10.8)) = 32,
    NSEventTypeQuickLook API_AVAILABLE(macos(10.8)) = 33,

    NSEventTypePressure API_AVAILABLE(macos(10.10.3)) = 34,
    NSEventTypeDirectTouch API_AVAILABLE(macos(10.10)) = 37,

    NSEventTypeChangeMode API_AVAILABLE(macos(10.15)) = 38,
};

typedef NS_ENUM(unsigned long long, NSEventMask) { /* masks for the types of events */
    NSEventMaskLeftMouseDown         = 1ULL << NSEventTypeLeftMouseDown,
    NSEventMaskLeftMouseUp           = 1ULL << NSEventTypeLeftMouseUp,
    NSEventMaskRightMouseDown        = 1ULL << NSEventTypeRightMouseDown,
    NSEventMaskRightMouseUp          = 1ULL << NSEventTypeRightMouseUp,
    NSEventMaskMouseMoved            = 1ULL << NSEventTypeMouseMoved,
    NSEventMaskLeftMouseDragged      = 1ULL << NSEventTypeLeftMouseDragged,
    NSEventMaskRightMouseDragged     = 1ULL << NSEventTypeRightMouseDragged,
    NSEventMaskMouseEntered          = 1ULL << NSEventTypeMouseEntered,
    NSEventMaskMouseExited           = 1ULL << NSEventTypeMouseExited,
    NSEventMaskKeyDown               = 1ULL << NSEventTypeKeyDown,
    NSEventMaskKeyUp                 = 1ULL << NSEventTypeKeyUp,
    NSEventMaskFlagsChanged          = 1ULL << NSEventTypeFlagsChanged,
    NSEventMaskAppKitDefined         = 1ULL << NSEventTypeAppKitDefined,
    NSEventMaskSystemDefined         = 1ULL << NSEventTypeSystemDefined,
    NSEventMaskApplicationDefined    = 1ULL << NSEventTypeApplicationDefined,
    NSEventMaskPeriodic              = 1ULL << NSEventTypePeriodic,
    NSEventMaskCursorUpdate          = 1ULL << NSEventTypeCursorUpdate,
    NSEventMaskScrollWheel           = 1ULL << NSEventTypeScrollWheel,
    NSEventMaskTabletPoint           = 1ULL << NSEventTypeTabletPoint,
    NSEventMaskTabletProximity       = 1ULL << NSEventTypeTabletProximity,
    NSEventMaskOtherMouseDown        = 1ULL << NSEventTypeOtherMouseDown,
    NSEventMaskOtherMouseUp          = 1ULL << NSEventTypeOtherMouseUp,
    NSEventMaskOtherMouseDragged     = 1ULL << NSEventTypeOtherMouseDragged,
};
/* The following event masks are available on some hardware on 10.5.2 and later */
#define NSEventMaskGesture API_AVAILABLE(macos(10.5))          (1ULL << NSEventTypeGesture)
#define NSEventMaskMagnify API_AVAILABLE(macos(10.5))          (1ULL << NSEventTypeMagnify)
#define NSEventMaskSwipe API_AVAILABLE(macos(10.5))            (1ULL << NSEventTypeSwipe)
#define NSEventMaskRotate API_AVAILABLE(macos(10.5))           (1ULL << NSEventTypeRotate)
#define NSEventMaskBeginGesture API_AVAILABLE(macos(10.5))     (1ULL << NSEventTypeBeginGesture)
#define NSEventMaskEndGesture API_AVAILABLE(macos(10.5))       (1ULL << NSEventTypeEndGesture)

/* Note: You can only use these event masks on 64 bit. In other words, you cannot setup a local, nor global, event monitor for these event types on 32 bit. Also, you cannot search the event queue for them (nextEventMatchingMask:...) on 32 bit. */
#define NSEventMaskSmartMagnify API_AVAILABLE(macos(10.8)) (1ULL << NSEventTypeSmartMagnify)
#define NSEventMaskPressure API_AVAILABLE(macos(10.10.3)) (1ULL << NSEventTypePressure)
#define NSEventMaskDirectTouch API_AVAILABLE(macos(10.12.2)) (1ULL << NSEventTypeDirectTouch)
#define NSEventMaskChangeMode API_AVAILABLE(macos(10.15)) (1ULL << NSEventTypeChangeMode)
#define NSEventMaskAny              NSUIntegerMax

typedef NS_ENUM(NSUInteger, NSEventModifierFlags) {
    NSEventModifierFlagCapsLock           = 1 << 16, // Set if Caps Lock key is pressed.
    NSEventModifierFlagShift              = 1 << 17, // Set if Shift key is pressed.
    NSEventModifierFlagControl            = 1 << 18, // Set if Control key is pressed.
    NSEventModifierFlagOption             = 1 << 19, // Set if Option or Alternate key is pressed.
    NSEventModifierFlagCommand            = 1 << 20, // Set if Command key is pressed.
    NSEventModifierFlagNumericPad         = 1 << 21, // Set if any key in the numeric keypad is pressed.
    NSEventModifierFlagHelp               = 1 << 22, // Set if the Help key is pressed.
    NSEventModifierFlagFunction           = 1 << 23, // Set if any function key is pressed.
};

#define objc_msgSend_id             ((id (*)(id, SEL))objc_msgSend)
#define objc_msgSend_id_id          ((id (*)(id, SEL, id))objc_msgSend)
#define objc_msgSend_id_rect        ((id (*)(id, SEL, NSRect))objc_msgSend)
#define objc_msgSend_uint           ((NSUInteger (*)(id, SEL))objc_msgSend)
#define objc_msgSend_int            ((NSInteger (*)(id, SEL))objc_msgSend)
#define objc_msgSend_SEL            ((SEL (*)(id, SEL))objc_msgSend)
#define objc_msgSend_float          ((CGFloat (*)(id, SEL))abi_objc_msgSend_fpret)
#define objc_msgSend_bool           ((BOOL (*)(id, SEL))objc_msgSend)
#define objc_msgSend_void           ((void (*)(id, SEL))objc_msgSend)
#define objc_msgSend_double         ((double (*)(id, SEL))objc_msgSend)
#define objc_msgSend_void_id        ((void (*)(id, SEL, id))objc_msgSend)
#define objc_msgSend_void_uint      ((void (*)(id, SEL, NSUInteger))objc_msgSend)
#define objc_msgSend_void_int       ((void (*)(id, SEL, NSInteger))objc_msgSend)
#define objc_msgSend_void_bool      ((void (*)(id, SEL, BOOL))objc_msgSend)
#define objc_msgSend_void_float     ((void (*)(id, SEL, CGFloat))objc_msgSend)
#define objc_msgSend_void_double    ((void (*)(id, SEL, double))objc_msgSend)
#define objc_msgSend_void_SEL       ((void (*)(id, SEL, SEL))objc_msgSend)
#define objc_msgSend_id_char_const  ((id (*)(id, SEL, char const *))objc_msgSend)

typedef enum NSApplicationActivationPolicy {
    NSApplicationActivationPolicyRegular,
    NSApplicationActivationPolicyAccessory,
    NSApplicationActivationPolicyProhibited
} NSApplicationActivationPolicy;

#define NSAlloc(nsclass) objc_msgSend_id((id)nsclass, sel_registerName("alloc"))
#define NSRelease(nsclass) objc_msgSend_id((id)nsclass, sel_registerName("release"))

bool running = true;

unsigned int onClose(void* self) {
    NSWindow* win = NULL;
    object_getInstanceVariable(self, "NSWindow", (void*)&win);
    if (win == NULL)
        return true;

    running = false;

    return true;
}

NSSize windowResize(void* self, SEL sel, NSSize frameSize) {
    NSWindow* win = NULL;
    object_getInstanceVariable(self, "NSWindow", (void*)&win);
    if (win == NULL)
        return frameSize;

    printf("window resized to %f %f\n", frameSize.width, frameSize.height);
    return frameSize;
}



#include <string.h>

const char* NSEventTypeToChar(NSEventType eventType);
const char* NSEventModifierFlagsToChar(NSEventModifierFlags modifierFlags);

int main(int argc, char* argv[]) {
    class_addMethod(objc_getClass("NSObject"), sel_registerName("windowShouldClose:"), (IMP) onClose, 0);

    NSApplication* NSApp = objc_msgSend_id((id)objc_getClass("NSApplication"), sel_registerName("sharedApplication"));
    objc_msgSend_void_int(NSApp, sel_registerName("setActivationPolicy:"), NSApplicationActivationPolicyRegular);

    NSBackingStoreType macArgs = NSWindowStyleMaskClosable | NSWindowStyleMaskMiniaturizable | NSBackingStoreBuffered | NSWindowStyleMaskTitled | NSWindowStyleMaskResizable;

    SEL func = sel_registerName("initWithContentRect:styleMask:backing:defer:");

    NSWindow* window = ((id (*)(id, SEL, NSRect, NSWindowStyleMask, NSBackingStoreType, bool))objc_msgSend)
            (NSAlloc(objc_getClass("NSWindow")), func, 
                        (NSRect){{200, 200}, {200, 200}}, 
                        macArgs, macArgs, false);

    Class delegateClass = objc_allocateClassPair(objc_getClass("NSObject"), "WindowDelegate", 0);

    class_addIvar(
        delegateClass, "NSWindow",
        sizeof(NSWindow*), rint(log2(sizeof(NSWindow*))),
        "L"
    );

    class_addMethod(delegateClass, sel_registerName("windowWillResize:toSize:"), (IMP) windowResize, "{NSSize=ff}@:{NSSize=ff}");

    id delegate = objc_msgSend_id(NSAlloc(delegateClass), sel_registerName("init"));

    object_setInstanceVariable(delegate, "NSWindow", window);

    objc_msgSend_void_id(window, sel_registerName("setDelegate:"), delegate);

    objc_msgSend_void_bool(NSApp, sel_registerName("activateIgnoringOtherApps:"), true);
    ((id(*)(id, SEL, SEL))objc_msgSend)(window, sel_registerName("makeKeyAndOrderFront:"), NULL);
    objc_msgSend_void_bool(window, sel_registerName("setIsVisible:"), true);

    objc_msgSend_void(NSApp, sel_registerName("finishLaunching"));

    while (running) {
        id pool = objc_msgSend_id(NSAlloc(objc_getClass("NSAutoreleasePool")), sel_registerName("init"));

        NSEvent* e = (NSEvent*) ((id(*)(id, SEL, NSEventMask, void*, NSString*, bool))objc_msgSend) (NSApp, sel_registerName("nextEventMatchingMask:untilDate:inMode:dequeue:"), ULONG_MAX, NULL, ((id(*)(id, SEL, const char*))objc_msgSend) ((id)objc_getClass("NSString"), sel_registerName("stringWithUTF8String:"), "kCFRunLoopDefaultMode"), true);



        unsigned int type = objc_msgSend_uint(e, sel_registerName("type"));  

        NSPoint p = ((NSPoint(*)(id, SEL)) objc_msgSend)(e, sel_registerName("locationInWindow"));

        if (type != 0)  
            printf("Event [type=%s location={%f, %f} modifierFlags={%s}]\n", 
                                NSEventTypeToChar(type), 
                                p.x, p.y, 
                                NSEventModifierFlagsToChar(objc_msgSend_uint(e, sel_registerName("modifierFlags"))));

        objc_msgSend_void_id(NSApp, sel_registerName("sendEvent:"), e);
        ((void(*)(id, SEL))objc_msgSend)(NSApp, sel_registerName("updateWindows"));

        NSRelease(pool);
    }
}

const char* NSEventTypeToChar(NSEventType eventType) {
    switch (eventType) {
        case NSEventTypeLeftMouseDown: return "LeftMouseDown";
        case NSEventTypeLeftMouseUp: return "LeftMouseUp";
        case NSEventTypeRightMouseDown: return "RightMouseDown";
        case NSEventTypeRightMouseUp: return "RightMouseUp";
        case NSEventTypeMouseMoved: return "MouseMoved";
        case NSEventTypeLeftMouseDragged: return "LeftMouseDragged";
        case NSEventTypeRightMouseDragged: return "RightMouseDragged";
        case NSEventTypeMouseEntered: return "MouseEntered";
        case NSEventTypeMouseExited: return "MouseExited";
        case NSEventTypeKeyDown: return "KeyDown";
        case NSEventTypeKeyUp: return "KeyUp";
        case NSEventTypeFlagsChanged: return "FlagsChanged";
        case NSEventTypeAppKitDefined: return "AppKitDefined";
        case NSEventTypeSystemDefined: return "SystemDefined";
        case NSEventTypeApplicationDefined: return "ApplicationDefined";
        case NSEventTypePeriodic: return "Periodic";
        case NSEventTypeCursorUpdate: return "CursorUpdate";
        case NSEventTypeScrollWheel: return "ScrollWheel";
        case NSEventTypeTabletPoint: return "TabletPoint";
        case NSEventTypeTabletProximity: return "TabletProximity";
        case NSEventTypeOtherMouseDown: return "OtherMouseDown";
        case NSEventTypeOtherMouseUp: return "OtherMouseUp";
        case NSEventTypeOtherMouseDragged: return "OtherMouseDragged";
        default: return "N/A";
    }
}

char* ns_strcat(register char *s, register const char *append) {
    char *save = s;

    for (; *s; ++s);
    while ((*s++ = *append++));
    return save;
}

const char* NSEventModifierFlagsToChar(NSEventModifierFlags modifierFlags) {
    static char result[100];
    result[0] = '\0';

    if ((modifierFlags & NSEventModifierFlagCapsLock) == NSEventModifierFlagCapsLock) ns_strcat(result, "CapsLock, ");
    if ((modifierFlags & NSEventModifierFlagShift) == NSEventModifierFlagShift) ns_strcat(result, "NShift, ");
    if ((modifierFlags & NSEventModifierFlagControl) == NSEventModifierFlagControl) ns_strcat(result, "Control, ");
    if ((modifierFlags & NSEventModifierFlagOption) == NSEventModifierFlagOption) ns_strcat(result, "Option, ");
    if ((modifierFlags & NSEventModifierFlagCommand) == NSEventModifierFlagCommand) ns_strcat(result, "Command, ");
    if ((modifierFlags & NSEventModifierFlagNumericPad) == NSEventModifierFlagNumericPad) ns_strcat(result, "NumericPad, ");
    if ((modifierFlags & NSEventModifierFlagHelp) == NSEventModifierFlagHelp) ns_strcat(result, "Help, ");
    if ((modifierFlags & NSEventModifierFlagFunction) == NSEventModifierFlagFunction) ns_strcat(result, "Function, ");

    return result;
}

RGFW Under the Hood: Software Rendering

Colleague Riley — Mon, 19 Aug 2024 21:22:46 +0000

Introduction

RGFW is a lightweight single-header windowing library, its source code can be found here.
This tutorial is based on its source code.

The basic idea of software rendering is simple. It comes down to drawing to a buffer and blitting it to the screen.
However, software rendering is more complicated when working with low-level APIs because you must
properly initialize a rendering context, telling the API how to expect the data. Then to draw you have to use the API's functions to
blit to the screen, which can be complicated.

This tutorial explains how RGFW handles software rendering so you can understand how to implement it yourself.

NOTE: MacOS code will be written with a Cocoa C Wrapper in mind (see the RGFW.h or Silicon.h)

Overview

A quick overview of the steps required

Initialize buffer and rendering context
Draw to the buffer
Blit buffer to the screen
Free leftover data

Step 1 (Initialize buffer and rendering context)

NOTE: You may want the buffer's size to be bigger than the window so you can scale the buffer's size without reallocating it.

On X11 you start by creating a Visual (or pixel format) that tells the window how to handle the draw data.
Then create a bitmap for the buffer to render with, RGFW uses an XImage structure for the bitmap.
Next, you create a Graphics Context (GC) using the display and window data. The GC is used to tell X11 how to give
the window its draw data.

This is also where you can allocate the buffer. The buffer must be allocated for each platform except for Windows.

For this you need to use, XMatchVisualInfo, XCreateImage, and XCreateGC

XVisualInfo vi;
vi.visual = DefaultVisual(display, DefaultScreen(display));

XMatchVisualInfo(display, DefaultScreen(display), 32, TrueColor, &vi);

XImage* bitmap = XCreateImage(
            display, XDefaultVisual(display, vi.screen),
            vi.depth,
            ZPixmap, 0, NULL, RGFW_bufferSize.w, RGFW_bufferSize.h,
                32, 0
);

/* ..... */
/* Now this visual can be used to create a window and colormap */

XSetWindowAttributes swa;
Colormap cmap;

swa.colormap = cmap = XCreateColormap((Display*) display, DefaultRootWindow(display), vi.visual, AllocNone);

swa.background_pixmap = None;
swa.border_pixel = 0;
swa.event_mask = event_mask;

swa.background_pixel = 0;

Window window = XCreateWindow((Display*) display, DefaultRootWindow((Display*) display), x, y, w, h,
                0, vi.depth, InputOutput, vi.visual,
                CWColormap | CWBorderPixel | CWBackPixel | CWEventMask, &swa);
/* .... */

GC gc = XCreateGC(display, window, 0, NULL);

u8* buffer = (u8*)malloc(RGFW_bufferSize.w * RGFW_bufferSize.h * 4);

On Windows, you'll start by creating a bitmap header, which is used to create a bitmap with a specified format.
The format structure is used to tell the Windows API how to render the buffer to the screen.

Next, you create a Drawing Context Handle (HDC) allocated in memory, this is used for selecting the bitmap later.

NOTE: Windows does not need to allocate a buffer because Winapi handles that memory for us. You can also allocate the memory by hand.

Relevant Documentation: BITMAPV5HEADER, CreateDIBSection and CreateCompatibleDC

BITMAPV5HEADER bi;
ZeroMemory(&bi, sizeof(bi));
bi.bV5Size = sizeof(bi);
bi.bV5Width = RGFW_bufferSize.w;
bi.bV5Height = -((LONG) RGFW_bufferSize.h);
bi.bV5Planes = 1;
bi.bV5BitCount = 32;
bi.bV5Compression = BI_BITFIELDS;

// where it can expect to find the RGBA data
// (note: this might need to be changed according to the endianness) 
bi.bV5BlueMask = 0x00ff0000;
bi.bV5GreenMask = 0x0000ff00;
bi.bV5RedMask = 0x000000ff;
bi.bV5AlphaMask = 0xff000000;

u8* buffer;

HBITMAP bitmap = CreateDIBSection(hdc,
    (BITMAPINFO*) &bi,
    DIB_RGB_COLORS,
    (void**) &buffer,
    NULL,
    (DWORD) 0);

HDC hdcMem = CreateCompatibleDC(hdc);

On MacOS, there is not much setup, most of the work is done during rendering.

You only need to allocate the buffer data.

u8* buffer = malloc(RGFW_bufferSize.w * RGFW_bufferSize.h * 4);

Step 2 (Draw to the buffer)

For this tutorial, I will use Silk.h for drawing to the buffer. Silk.h is a single-header software rendering graphics library.

First, include silk,

#define SILK_PIXELBUFFER_WIDTH w
#define SILK_PIXELBUFFER_HEIGHT h
#define SILK_IMPLEMENTATION
#include "silk.h"

Now you can render using silk.

silkClearPixelBufferColor((pixel*)buffer, 0x11AA0033);

silkDrawCircle(
            (pixel*)buffer, 
            (vec2i) { SILK_PIXELBUFFER_WIDTH, SILK_PIXELBUFFER_HEIGHT },
            SILK_PIXELBUFFER_WIDTH,
            (vec2i) { SILK_PIXELBUFFER_CENTER_X, SILK_PIXELBUFFER_CENTER_Y - 60}, 
            60,
            0xff0000ff
);

Step 3 (Blit the buffer to the screen)

On X11, you first set the bitmap data to the buffer.
The bitmap data will be rendered using BGR, so you must

convert the data if you want to use RGB. Then you'll have to use XPutImage
to draw the XImage to the window using the GC.

Relevant documentation: XPutImage

bitmap->data = (char*) buffer;
#ifndef RGFW_X11_DONT_CONVERT_BGR
    u32 x, y;
    for (y = 0; y < (u32)window_height; y++) {
        for (x = 0; x < (u32)window_width; x++) {
            u32 index = (y * 4 * area.w) + x * 4;

            u8 red = bitmap->data[index];
            bitmap->data[index] = buffer[index + 2];
            bitmap->data[index + 2] = red;
        }
    }
#endif  
XPutImage(display, (Window)window, gc, bitmap, 0, 0, 0, 0, RGFW_bufferSize.w, RGFW_bufferSize.h);

On Windows, you must first select the bitmap and make sure that you save the last selected object so you can reselect it later.
Now you can blit the bitmap to the screen and reselect the old bitmap.

Relevant documentation: SelectObject and BitBlt

HGDIOBJ oldbmp = SelectObject(hdcMem, bitmap);
BitBlt(hdc, 0, 0, window_width, window_height, hdcMem, 0, 0, SRCCOPY);
SelectObject(hdcMem, oldbmp);

On MacOS, set the view's CALayer according to your window, this is used for rendering the image to the screen.
Next, create the image (bitmap) using the buffer.
Finally, you can add the image to the layer's graphics context, and draw and flush the layer to the screen.

Relevant documentation: CGColorSpaceCreateDeviceRGB, CGBitmapContextCreate, CGBitmapContextCreateImage, CGColorSpaceRelease, CGContextRelease,
CALayer, NSGraphicsContext, CGContextDrawImage, flushGraphics and, CGImageRelease

CGImageRef createImageFromBytes(unsigned char *buffer, int width, int height) {
    // Define color space
    CGColorSpaceRef colorSpace = CGColorSpaceCreateDeviceRGB();
    // Create bitmap context
    CGContextRef context = CGBitmapContextCreate(
            buffer, 
            width, height,
            8,
            RGFW_bufferSize.w * 4, 
            colorSpace,
            kCGImageAlphaPremultipliedLast);

    // Create image from bitmap context
    CGImageRef image = CGBitmapContextCreateImage(context);
    // Release the color space and context
    CGColorSpaceRelease(colorSpace);
    CGContextRelease(context);

    return image;
}

...
void* view = NSWindow_contentView(window);
void* layer = objc_msgSend_id(view, sel_registerName("layer"));

((void(*)(id, SEL, NSRect))objc_msgSend)(layer,
                sel_registerName("setFrame:"),
                (NSRect){{0, 0}, {window_width, window_height}});

CGImageRef image = createImageFromBytes(buffer, window_width, window_height);

// Get the current graphics context
id graphicsContext = objc_msgSend_class(objc_getClass("NSGraphicsContext"), sel_registerName("currentContext"));

// Get the CGContext from the current NSGraphicsContext
id cgContext = objc_msgSend_id(graphicsContext, sel_registerName("graphicsPort"));

// Draw the image in the context
NSRect bounds = (NSRect){{0,0}, {window_width, window_height}};
CGContextDrawImage((void*)cgContext, *(CGRect*)&bounds, image);

// Flush the graphics context to ensure the drawing is displayed
objc_msgSend_id(graphicsContext, sel_registerName("flushGraphics"));

objc_msgSend_void_id(layer, sel_registerName("setContents:"), (id)image);
objc_msgSend_id(layer, sel_registerName("setNeedsDisplay"));

CGImageRelease(image);

Step 4 (Free leftover data)

When you're done rendering, you should free the bitmap and image data using the respective API functions.

On X11 and MacOS, you also should free the buffer.

On X11 you must use XDestoryImage and XFreeGC.

XDestroyImage(bitmap);
XFreeGC(display, gc);
free(buffer);

On Windows, you must use DeleteDC and DeleteObject.

DeleteDC(hdcMem);
DeleteObject(bitmap);

On MacOS you must use release.

release(bitmap);
release(image);
free(buffer);

full examples

X11

// This can be compiled with 
// gcc x11.c -lX11 -lm

#include <X11/Xlib.h>
#include <X11/Xutil.h>

#include <stdio.h>
#include <stdlib.h>


#define SILK_PIXELBUFFER_WIDTH 500
#define SILK_PIXELBUFFER_HEIGHT 500
#define SILK_IMPLEMENTATION
#include "silk.h"

int main() {
    Display* display = XOpenDisplay(NULL);
    XVisualInfo vi;
    vi.visual = DefaultVisual(display, DefaultScreen(display));

    XMatchVisualInfo(display, DefaultScreen(display), 32, TrueColor, &vi);

    XImage* bitmap = XCreateImage(
            display, XDefaultVisual(display, vi.screen),
            vi.depth,
            ZPixmap, 0, NULL, 500, 500,
            32, 0
    );

    /* ..... */
    /* Now this visual can be used to create a window and colormap */

    XSetWindowAttributes swa;
    Colormap cmap;

    swa.colormap = cmap = XCreateColormap((Display*) display, DefaultRootWindow(display), vi.visual, AllocNone);

    swa.background_pixmap = None;
    swa.border_pixel = 0;
    swa.event_mask = CWColormap | CWBorderPixel | CWBackPixel | CWEventMask;

    swa.background_pixel = 0;

    Window window = XCreateWindow((Display*) display, DefaultRootWindow((Display*) display), 500, 500, 500, 500,
                    0, vi.depth, InputOutput, vi.visual,
                    CWColormap | CWBorderPixel | CWBackPixel | CWEventMask, &swa);
    /* .... */

    GC gc = XCreateGC(display, window, 0, NULL);

    u8* buffer = (u8*)malloc(500 * 500 * 4);

    XSelectInput(display, window, ExposureMask | KeyPressMask);
    XMapWindow(display, window);

    XEvent event;
    for (;;) {
        XNextEvent(display, &event);

        silkClearPixelBufferColor((pixel*)buffer, 0x11AA0033);

        silkDrawCircle(
                (pixel*)buffer, 
                (vec2i) { SILK_PIXELBUFFER_WIDTH, SILK_PIXELBUFFER_HEIGHT },
                SILK_PIXELBUFFER_WIDTH,
                (vec2i) { SILK_PIXELBUFFER_CENTER_X, SILK_PIXELBUFFER_CENTER_Y - 60}, 
                60,
                0xff0000ff
        );

        bitmap->data = (char*) buffer;
        #ifndef RGFW_X11_DONT_CONVERT_BGR
            u32 x, y;
            for (y = 0; y < (u32)500; y++) {
                for (x = 0; x < (u32)500; x++) {
                    u32 index = (y * 4 * 500) + x * 4;

                    u8 red = bitmap->data[index];
                    bitmap->data[index] = buffer[index + 2];
                    bitmap->data[index + 2] = red;
                }
            }
        #endif  
        XPutImage(display, (Window) window, gc, bitmap, 0, 0, 0, 0, 500, 500);
    }

    XDestroyImage(bitmap);
    XFreeGC(display, gc);
    free(buffer);
}

windows

// This can be compiled with
// gcc win32.c -lgdi32 -lm

#include <windows.h>

#include <stdio.h>
#include <stdint.h>
#include <assert.h>

#define SILK_PIXELBUFFER_WIDTH 500
#define SILK_PIXELBUFFER_HEIGHT 500
#define SILK_IMPLEMENTATION
#include "silk.h"

int main() {
    WNDCLASS wc = {0};
    wc.lpfnWndProc   = DefWindowProc; // Default window procedure
    wc.hInstance     = GetModuleHandle(NULL);
    wc.lpszClassName = "SampleWindowClass";

    RegisterClass(&wc);

    HWND hwnd = CreateWindowA(wc.lpszClassName, "Sample Window", 0,
            500, 500, 500, 500,
            NULL, NULL, wc.hInstance, NULL);


    BITMAPV5HEADER bi = { 0 };
    ZeroMemory(&bi, sizeof(bi));
    bi.bV5Size = sizeof(bi);
    bi.bV5Width = 500;
    bi.bV5Height = -((LONG) 500);
    bi.bV5Planes = 1;
    bi.bV5BitCount = 32;
    bi.bV5Compression = BI_BITFIELDS;

        // where it can expect to find the RGB data
    // (note: this might need to be changed according to the endianness) 
    bi.bV5BlueMask = 0x00ff0000;
    bi.bV5GreenMask = 0x0000ff00;
    bi.bV5RedMask = 0x000000ff;
    bi.bV5AlphaMask = 0xff000000;

    u8* buffer;

    HDC hdc = GetDC(hwnd); 
    HBITMAP bitmap = CreateDIBSection(hdc,
        (BITMAPINFO*) &bi,
        DIB_RGB_COLORS,
        (void**) &buffer,
        NULL,
        (DWORD) 0);

    HDC hdcMem = CreateCompatibleDC(hdc);   

    ShowWindow(hwnd, SW_SHOW);
    UpdateWindow(hwnd);

    MSG msg;

    BOOL running = TRUE;

    while (running) {
        if (PeekMessageA(&msg, hwnd, 0u, 0u, PM_REMOVE)) {
            TranslateMessage(&msg);
            DispatchMessage(&msg);
        }

        running = IsWindow(hwnd);

        silkClearPixelBufferColor((pixel*)buffer, 0x11AA0033);

        silkDrawCircle(
            (pixel*)buffer, 
            (vec2i) { SILK_PIXELBUFFER_WIDTH, SILK_PIXELBUFFER_HEIGHT },
            SILK_PIXELBUFFER_WIDTH,
            (vec2i) { SILK_PIXELBUFFER_CENTER_X, SILK_PIXELBUFFER_CENTER_Y - 60}, 
            60,
            0xff0000ff
        );

        HGDIOBJ oldbmp = SelectObject(hdcMem, bitmap);
        BitBlt(hdc, 0, 0, 500, 500, hdcMem, 0, 0, SRCCOPY);
        SelectObject(hdcMem, oldbmp);
    }

    DeleteDC(hdcMem);
    DeleteObject(bitmap);
    return 0;
}

RGFW Under the Hood: Raw Mouse Input and Mouse Locking

Colleague Riley — Tue, 13 Aug 2024 20:05:08 +0000

A tutorial that explains how to lock the cursor and enable raw mouse input for X11, WinAPI, Cocoa, and Emscripten.

Introduction

RGFW is a lightweight single-header windowing library, its source code can be found here.
This tutorial is based on its source code.

When you create an application that locks the cursor, such as a game with a first-person camera, it's important to be able to disable the cursor.
This means locking the cursor in the middle of the screen and getting raw input.

The only alternative to this method would be a hack that pulls the mouse back to the center of the window when it moves. However, this is a hack so it can be buggy
and does not work on all OSes. Therefore, it's important to properly lock the mouse by using raw input.

This tutorial explains how RGFW handles raw mouse input so you can understand how to implement it yourself.

Overview

A quick overview of the steps required

lock cursor
center the cursor
enable raw input
handle raw input
disable raw input
unlock cursor

When the user asks RGFW to hold the cursor, RGFW enables a bit flag that says the cursor is held.

win->_winArgs |= RGFW_HOLD_MOUSE;

Step 1 (Lock Cursor)

On X11 the cursor can be locked by grabbing it via XGrabPointer

XGrabPointer(display, window, True, PointerMotionMask, GrabModeAsync, GrabModeAsync, None, None, CurrentTime);

This gives the window full control of the pointer.

On Windows, ClipCursor locks the cursor to a specific rect on the screen.
This means we must find the window rectangle on the screen and then clip the mouse to that rectangle.

Also using: GetClientRect) and ClientToScreen

//First get the window size (the RGFW_window struct also includes this information, but using this ensures it's correct)
RECT clipRect;
GetClientRect(window, &clipRect);

// ClipCursor needs screen coordinates, not coordinates relative to the window
ClientToScreen(window, (POINT*) &clipRect.left);
ClientToScreen(window, (POINT*) &clipRect.right);

// Now we can lock the cursor
ClipCursor(&clipRect);

On MacOS and Emscripten the function to enable raw input also locks the cursor. So I'll get to its function in step 4.

Step 2 (center the cursor)

After the cursor is locked, it should be centered in the middle of the screen.
This ensures the cursor is locked in the right place and won't mess with anything else.

RGFW uses an RGFW function called RGFW_window_moveMouse to move the mouse in the middle of the window.

On X11, XWarpPointer can be used to move the cursor to the center of the window

XWarpPointer(display, None, window, 0, 0, 0, 0, window_width / 2, window_height / 2);

On Windows, SetCursorPos is used

SetCursorPos(window_x + (window_width / 2), window_y + (window_height / 2));

On MacOS, CGWarpMouseCursorPosition is used

CGWarpMouseCursorPosition(window_x + (window_width / 2), window_y + (window_height / 2));

On Emscripten, RGFW does not move the mouse.

Step 3 (enable raw input)

With X11, XI is used to enable raw input

// mask for XI and set mouse for raw mouse input ("RawMotion")
unsigned char mask[XIMaskLen(XI_RawMotion)] = { 0 };
XISetMask(mask, XI_RawMotion);

// set up X1 struct
XIEventMask em;
em.deviceid = XIAllMasterDevices;
em.mask_len = sizeof(mask);
em.mask = mask;

//Enable raw input using the structure
XISelectEvents(display, XDefaultRootWindow(display), &em, 1);

On Windows, you need to set up the RAWINPUTDEVICE structure and enable it with RegisterRawInputDevices

const RAWINPUTDEVICE id = { 0x01, 0x02, 0, window };
RegisterRawInputDevices(&id, 1, sizeof(id));

On MacOS you only need to run CGAssociateMouseAndMouseCursorPosition
This also locks the cursor by disassociating the mouse cursor and the mouse movement

CGAssociateMouseAndMouseCursorPosition(0);

On Emscripten you only need to request the user to lock the pointer

emscripten_request_pointerlock("#canvas", 1);

Step 4 (handle raw input events)

These all happen during event loops.

For X11, you must handle the normal MotionNotify, manually converting the input to raw input.
To check for raw mouse input events, you need to use GenericEvent.

switch (E.type) {
    (...)
    case MotionNotify:
        /* check if mouse hold is enabled */
        if ((win->_winArgs & RGFW_HOLD_MOUSE)) {
            /* convert E.xmotion to raw input by subtracting the previous point */
            win->event.point.x = win->_lastMousePoint.x - E.xmotion.x;
            win->event.point.y = win->_lastMousePoint.y - E.xmotion.y;
        }

        break;

    case GenericEvent: {
        /* MotionNotify is used for mouse events if the mouse isn't held */                
        if (!(win->_winArgs & RGFW_HOLD_MOUSE)) {
            XFreeEventData(display, &E.xcookie);
            break;
        }

        XGetEventData(display, &E.xcookie);
        if (E.xcookie.evtype == XI_RawMotion) {
            XIRawEvent *raw = (XIRawEvent *)E.xcookie.data;
            if (raw->valuators.mask_len == 0) {
                XFreeEventData(display, &E.xcookie);
                break;
            }

            double deltaX = 0.0f; 
            double deltaY = 0.0f;

            /* check if relative motion data exists where we think it does */
            if (XIMaskIsSet(raw->valuators.mask, 0) != 0)
                deltaX += raw->raw_values[0];
            if (XIMaskIsSet(raw->valuators.mask, 1) != 0)
                deltaY += raw->raw_values[1];

            //The mouse must be moved back to the center when it moves
            XWarpPointer(display, None, window, 0, 0, 0, 0, window_width / 2, window_height / 2);
            win->event.point = RGFW_POINT((i32)deltaX, (i32)deltaY);
        }

        XFreeEventData(display, &E.xcookie);
        break;
    }

On Windows, you only need to handle WM_INPUT events and check for raw motion input

switch (msg.message) {
    (...)
    case WM_INPUT: {
        /* check if the mouse is being held */
        if (!(win->_winArgs & RGFW_HOLD_MOUSE))
            break;

        /* get raw data as an array */
        unsigned size = sizeof(RAWINPUT);
        static RAWINPUT raw[sizeof(RAWINPUT)];
        GetRawInputData((HRAWINPUT)msg.lParam, RID_INPUT, raw, &size, sizeof(RAWINPUTHEADER));

        //Make sure raw data is valid 
        if (raw->header.dwType != RIM_TYPEMOUSE || (raw->data.mouse.lLastX == 0 && raw->data.mouse.lLastY == 0) )
            break;

        win->event.point.x = raw->data.mouse.lLastX;
        win->event.point.y = raw->data.mouse.lLastY;
        break;
    }

On macOS, you can check mouse input as normal while using deltaX and deltaY to fetch the mouse point

switch (objc_msgSend_uint(e, sel_registerName("type"))) {
    case NSEventTypeLeftMouseDragged:
    case NSEventTypeOtherMouseDragged:
    case NSEventTypeRightMouseDragged:
    case NSEventTypeMouseMoved:
        if ((win->_winArgs & RGFW_HOLD_MOUSE) == 0) // if the mouse is not held
                    break;

                NSPoint p;
        p.x = ((CGFloat(*)(id, SEL))abi_objc_msgSend_fpret)(e, sel_registerName("deltaX"));
        p.y = ((CGFloat(*)(id, SEL))abi_objc_msgSend_fpret)(e, sel_registerName("deltaY"));


        win->event.point = RGFW_POINT((i32)p.x, (i32) p.y));

On Emscripten the mouse events can be checked as they normally are, except we're going to use e->movementX/Y

EM_BOOL Emscripten_on_mousemove(int eventType, const EmscriptenMouseEvent* e, void* userData) {
    if ((RGFW_root->_winArgs & RGFW_HOLD_MOUSE) == 0) // if the mouse is not held
            return


        RGFW_point p = RGFW_POINT(e->movementX, e->movementY);
}

Step 5 (disable raw input)

Finally, RGFW allows disabling the raw input and unlocking the cursor to revert to normal mouse input.

First, RGFW disables the bit flag.

win->_winArgs ^= RGFW_HOLD_MOUSE;

In X11, first, you must create a structure with a blank mask.
This will disable raw input.

unsigned char mask[] = { 0 };
XIEventMask em;
em.deviceid = XIAllMasterDevices;

em.mask_len = sizeof(mask);
em.mask = mask;
XISelectEvents(display, XDefaultRootWindow(display), &em, 1);

For Windows, you pass a raw input device structure with RIDEV_REMOVE to disable the raw input.

const RAWINPUTDEVICE id = { 0x01, 0x02, RIDEV_REMOVE, NULL };
RegisterRawInputDevices(&id, 1, sizeof(id));

On MacOS and Emscripten, unlocking the cursor also disables raw input.

Step 6 (unlock cursor)

On X11, XUngrabPoint is used for unlocking the cursor.

XUngrabPointer(display, CurrentTime);

On Windows, pass a NULL rectangle pointer to ClipCursor inorder to the cursor.

ClipCursor(NULL);

On MacOS, associating the mouse cursor and the mouse movement will disable raw input and unlock the cursor

CGAssociateMouseAndMouseCursorPosition(1);

On Emscripten, exiting the pointer lock will unlock the cursor and disable raw input.

emscripten_exit_pointerlock();

Full code examples

X11

// This can be compiled with 
// gcc x11.c -lX11 -lXi

#include <X11/Xlib.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#include <X11/extensions/XInput2.h>

int main(void) {
    unsigned int window_width = 200;
    unsigned int window_height = 200;

    Display* display = XOpenDisplay(NULL);  
    Window window = XCreateSimpleWindow(display, RootWindow(display, DefaultScreen(display)), 400, 400, window_width, window_height, 1, BlackPixel(display, DefaultScreen(display)), WhitePixel(display, DefaultScreen(display)));

    XSelectInput(display, window, ExposureMask | KeyPressMask);
    XMapWindow(display, window);

    XGrabPointer(display, window, True, PointerMotionMask, GrabModeAsync, GrabModeAsync, None, None, CurrentTime);

    XWarpPointer(display, None, window, 0, 0, 0, 0, window_width / 2, window_height / 2);

    // mask for XI and set mouse for raw mouse input ("RawMotion")
    unsigned char mask[XIMaskLen(XI_RawMotion)] = { 0 };
    XISetMask(mask, XI_RawMotion);

    // set up X1 struct
    XIEventMask em;
    em.deviceid = XIAllMasterDevices;
    em.mask_len = sizeof(mask);
    em.mask = mask;

    // enable raw input using the structure
    XISelectEvents(display, XDefaultRootWindow(display), &em, 1);

    Bool rawInput = True;
    XPoint point;
    XPoint _lastMousePoint;

    XEvent event;

    for (;;) {
        XNextEvent(display, &event);
        switch (event.type) {
            case MotionNotify:
                /* check if mouse hold is enabled */
                if (rawInput) {
                    /* convert E.xmotion to rawinput by substracting the previous point */
                    point.x = _lastMousePoint.x - event.xmotion.x;
                    point.y = _lastMousePoint.y - event.xmotion.y;
                    printf("rawinput %i %i\n", point.x, point.y);
                }

                break;

            case GenericEvent: {
                /* MotionNotify is used for mouse events if the mouse isn't held */                
                if (rawInput == False) {
                    XFreeEventData(display, &event.xcookie);
                    break;
                }

                XGetEventData(display, &event.xcookie);
                if (event.xcookie.evtype == XI_RawMotion) {
                    XIRawEvent *raw = (XIRawEvent *)event.xcookie.data;
                    if (raw->valuators.mask_len == 0) {
                        XFreeEventData(display, &event.xcookie);
                        break;
                    }

                    double deltaX = 0.0f; 
                    double deltaY = 0.0f;

                    /* check if relative motion data exists where we think it does */
                    if (XIMaskIsSet(raw->valuators.mask, 0) != 0)
                        deltaX += raw->raw_values[0];
                    if (XIMaskIsSet(raw->valuators.mask, 1) != 0)
                        deltaY += raw->raw_values[1];

                    point = (XPoint){deltaX, deltaY};
                    XWarpPointer(display, None, window, 0, 0, 0, 0, window_width / 2, window_height / 2);

                    printf("rawinput %i %i\n", point.x, point.y);
                }   

                XFreeEventData(display, &event.xcookie);
                break;
            }
            case KeyPress:
                if (rawInput == False)
                    break;

                unsigned char mask[] = { 0 };
                XIEventMask em;
                em.deviceid = XIAllMasterDevices;

                em.mask_len = sizeof(mask);
                em.mask = mask;
                XISelectEvents(display, XDefaultRootWindow(display), &em, 1);
                XUngrabPointer(display, CurrentTime);

                printf("Raw input disabled\n");
                break;
            default: break;
        }
    }

    XCloseDisplay(display);
 }

Winapi

// compile with gcc winapi.c

#include <windows.h>

#include <stdio.h>
#include <stdint.h>
#include <assert.h>

int main() {
    WNDCLASS wc = {0};
    wc.lpfnWndProc   = DefWindowProc; // Default window procedure
    wc.hInstance     = GetModuleHandle(NULL);
    wc.lpszClassName = "SampleWindowClass";

    RegisterClass(&wc);

    int window_width = 300;
    int window_height = 300;
    int window_x = 400;
    int window_y = 400;

    HWND hwnd = CreateWindowA(wc.lpszClassName, "Sample Window", 0,
            window_x, window_y, window_width, window_height,
            NULL, NULL, wc.hInstance, NULL);

    ShowWindow(hwnd, SW_SHOW);
    UpdateWindow(hwnd);

    // first get the window size (the RGFW_window struct also includes this informaton, but using this ensures it's correct)
    RECT clipRect;
    GetClientRect(hwnd, &clipRect);

    // ClipCursor needs screen coords, not coords relative to the window
    ClientToScreen(hwnd, (POINT*) &clipRect.left);
    ClientToScreen(hwnd, (POINT*) &clipRect.right);

    // now we can lock the cursor
    ClipCursor(&clipRect);

    SetCursorPos(window_x + (window_width / 2), window_y + (window_height / 2));    
    const RAWINPUTDEVICE id = { 0x01, 0x02, 0, hwnd };
    RegisterRawInputDevices(&id, 1, sizeof(id));

    MSG msg;

    BOOL holdMouse = TRUE;

    BOOL running = TRUE;

    POINT point;

    while (running) {
        if (PeekMessageA(&msg, hwnd, 0u, 0u, PM_REMOVE)) {
            switch (msg.message) {
                case WM_CLOSE:
                case WM_QUIT:
                    running = FALSE;
                    break;
                case WM_INPUT: {
                    /* check if the mouse is being held */
                    if (holdMouse == FALSE)
                        break;

                    /* get raw data as an array */
                    unsigned size = sizeof(RAWINPUT);
                    static RAWINPUT raw[sizeof(RAWINPUT)];
                    GetRawInputData((HRAWINPUT)msg.lParam, RID_INPUT, raw, &size, sizeof(RAWINPUTHEADER));

                    // make sure raw data is valid 
                    if (raw->header.dwType != RIM_TYPEMOUSE || (raw->data.mouse.lLastX == 0 && raw->data.mouse.lLastY == 0) )
                        break;


                    point.x = raw->data.mouse.lLastX;
                    point.y = raw->data.mouse.lLastY;
                    printf("raw input: %i %i\n", point.x, point.y);
                    break;
                }
                case WM_KEYDOWN:
                    if (holdMouse == FALSE)
                        break;

                    const RAWINPUTDEVICE id = { 0x01, 0x02, RIDEV_REMOVE, NULL };
                    RegisterRawInputDevices(&id, 1, sizeof(id));
                    ClipCursor(NULL);

                    printf("rawinput disabled\n");
                    holdMouse = FALSE;
                    break;

                default: break;
            }
            TranslateMessage(&msg);
            DispatchMessage(&msg);
        }

        running = IsWindow(hwnd);
    }

    DestroyWindow(hwnd);
    return 0;
}

RGFW Under the Hood: OpenGL Context Creation

Colleague Riley — Fri, 09 Aug 2024 15:47:32 +0000

Tutorial for creating an accelerated opengl context for X11, Windows, and MacOS. Based on my project: RGFW.

Introduction

In my experience working on RGFW, one of the most annoying parts of working with low-level APIs is creating an OpenGL context.
This is not because it's hard, but because there are many not-so-obvious steps that you must do correctly to create your OpenGL context.
This tutorial explains how to create an OpenGL context for Windows, MacOS and Linux so that way others don't have to struggle with figuring it out.

NOTE: MacOS code will be written with a Cocoa C Wrapper in mind (see the RGFW.h or Silicon.h)

Overview

A quick overview of the steps required
1) Load OpenGL context creation functions (if you need to)
2) Create an OpenGL pixel format (or Visual on X11) using an attribute list
3) Create your OpenGL context using an attribute array to set the OpenGL version

4) Free the OpenGL context

On MacOS steps 2 and 3 are one step.
EGL will not be included in this article because the setup is far easier.

Step 1 (Load OpenGL context creation functions)

First RGFW needs to load these functions

//X11 (GLX):
    glXCreateContextAttribsARB
    glXSwapIntervalEXT //(optional)

//Windows (WGL):
    wglCreateContextAttribsARB
    wglChoosePixelFormatARB
    wglSwapIntervalEXT //(optional)

//Cocoa (NSOpenGL)
    (none)

It needs to load these functions because they're extension functions provided by the hardware vendor. By default, wglCreateContext or glXCreateContext will create an OpenGL ~1.0 context that probably uses software rendering.

To load the extension functions RGFW has to start by defining them.

//X11 (GLX):
    typedef GLXContext(*glXCreateContextAttribsARBProc)(Display*, GLXFBConfig, GLXContext, Bool, const int*);
    static glXCreateContextAttribsARBProc glXCreateContextAttribsARB = 0;

    //(optional)
    typedef void ( *PFNGLXSWAPINTERVALEXTPROC) (Display *dpy, GLXDrawable drawable, int interval);
    PFNGLXSWAPINTERVALEXTPROC glXSwapIntervalEXT = NULL;

//Windows (WGL):
    typedef HGLRC (WINAPI *PFNWGLCREATECONTEXTATTRIBSARBPROC)(HDC hdc, HGLRC hglrc, const int *attribList);
    PFNWGLCREATECONTEXTATTRIBSARBPROC wglCreateContextAttribsARB = NULL;

    typedef HRESULT (APIENTRY* PFNWGLCHOOSEPIXELFORMATARBPROC)(HDC hdc, const int* piAttribIList, const FLOAT* pfAttribFList, UINT nMaxFormats, int* piFormats, UINT* nNumFormats);
    static PFNWGLCHOOSEPIXELFORMATARBPROC wglChoosePixelFormatARB = NULL;

    //(optional)
    typedef BOOL(APIENTRY* PFNWGLSWAPINTERVALEXTPROC)(int interval);
    static PFNWGLSWAPINTERVALEXTPROC wglSwapIntervalEXT = NULL;

Once the functions are defined, RGFW loads the functions with these API calls:

/*X11 (GLX):*/ glXGetProcAddress aad glXGetProcAddressARB
/*Windows (WGL):*/ wglGetProcAddress

For example using GLX,

glXCreateContextAttribsARB = glXGetProcAddressARB((GLubyte*) "glXCreateContextAttribsARB");;

//(optional)
glXSwapIntervalEXT = (PFNGLXSWAPINTERVALEXTPROC) glXGetProcAddress((GLubyte*) "glXSwapIntervalEXT");

WGL is a little bit more complicated because it needs to start by creating a dummy context.
This dummy context is used by WGL to load the functions.

WGL dummy

First, RGFW has to create a dummy window and device context, RGFW also uses this dummy window to get the height offset for the title bar.

HWND dummyWin = CreateWindowA(Class.lpszClassName, name, window_style, x, y, w, h, 0, 0, inh, 0);

HDC dummy_dc = GetDC(dummyWin);

After that, RGFW creates a dummy pixel format for the dummy window and dummy OpenGL context.

u32 pfd_flags = PFD_DRAW_TO_WINDOW | PFD_SUPPORT_OPENGL | PFD_DOUBLEBUFFER;

PIXELFORMATDESCRIPTOR pfd = {
    sizeof(pfd),
    1, /* version */
    pfd_flags,
    PFD_TYPE_RGBA, /* ipixel type */
    24, /* color bits */
    0, 0, 0, 0, 0, 0,
    8, /* alpha bits */
    0, 0, 0, 0, 0, 0,
    32, /* depth bits */
    8, /* stencil bits */ 
    0,
    PFD_MAIN_PLANE, /* Layer type */
    0, 0, 0, 0
};

int pixel_format = ChoosePixelFormat(dummy_dc, &pfd);
SetPixelFormat(dummy_dc, pixel_format, &pfd);

Now RGFW can create a dummy context and set it to be the current context.

This context will be using the default OpenGL ~1.0 context, OpenGL.

HGLRC dummy_context = wglCreateContext(dummy_dc);
wglMakeCurrent(dummy_dc, dummy_context);

Now RGFW can load the functions and delete the dummy

wglCreateContextAttribsARB = (PFNWGLCREATECONTEXTATTRIBSARBPROC) (void*) wglGetProcAddress("wglCreateContextAttribsARB");
wglChoosePixelFormatARB = (PFNWGLCHOOSEPIXELFORMATARBPROC) (void*)wglGetProcAddress("wglChoosePixelFormatARB");

//(optional)
wglSwapIntervalEXT = (PFNWGLSWAPINTERVALEXTPROC) wglGetProcAddress("wglSwapIntervalEXT");

wglMakeCurrent(dummy_dc, 0);
wglDeleteContext(dummy_context);
ReleaseDC(dummyWin, dummy_dc);
DestroyWindow(dummyWin);

Step 2 (Create an OpenGL pixel format (or Visual on X11) using an attribute list)

RGFW needs to create a pixel format/visual so the window knows how to draw the data it gets and so OpenGL knows the draw format we want.

Step 2.1: creating the attribute list

To create an OpenGL pixel format using an attribute list, RGFW has a function that creates an attribute list, RGFW_initFormatAttribs for the pixel format.

This function uses macros based on the target OS's API, supporting all of the APIs with a single function.

For this tutorial, I'll be separating an array for each OS rather than using one big array.

//linux:
    static u32 attribs[] = {
                            GLX_X_VISUAL_TYPE,      GLX_TRUE_COLOR,
                            GLX_DEPTH_SIZE,         24,                            
                            GLX_X_RENDERABLE,       1,
                            GLX_RED_SIZE,           8,
                            GLX_GREEN_SIZE,         8,
                            GLX_BLUE_SIZE,          8,
                            GLX_ALPHA_SIZE,         8,
                            GLX_RENDER_TYPE,        GLX_RGBA_BIT,
                            GLX_DRAWABLE_TYPE,      GLX_WINDOW_BIT,

                            0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
    };

//windows:

    /// windows makes you define the macros yourself (or you can use wglext.h (which may or may not be installed on your system)
    // https://registry.khronos.org/OpenGL/api/GL/wglext.h
    // so I'll be using the hardcoded instead 
    static u32 attribs[] = {
                                    0x2003, // WGL_ACCELERATION_ARB
                                    0x2027, // WGL_FULL_ACCELERATION_ARB
                                    0x201b, 8, // WGL_ALPHA_BITS_ARB
                                    0x2022, 24, // WGL_DEPTH_BITS_ARB
                                    0x2001, 1, // WGL_DRAW_TO_WINDOW_ARB
                                    0x2015, 8, // WGL_RED_BITS_ARB
                                    0x2017, 8, // WGL_GREEN_BITS_ARB
                                    0x2019, 8, // WGL_BLUE_BITS_ARB
                                    0x2013, 0x202B, // WGL_PIXEL_TYPE_ARB,  WGL_TYPE_RGBA_ARB
                                    0x2010,     1, // WGL_SUPPORT_OPENGL_ARB
                                    0x2014,  32, // WGL_COLOR_BITS_ARB
                                    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
            };

//macos:
        static u32 attribs[] = {
                                11      , 8, // alpha size
                                24      , 24, // depth size
                                72, // NSOpenGLPFANoRecovery
                                8, 24, // NSOpenGLPFAColorSize
                                0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
        };

You may notice the extra 0s at the bottom of the array, that's for optional arguments.

To fill in the optional arguments, first RGFW sets the index to the first 0.

size_t index = (sizeof(attribs) / sizeof(attribs[0])) - 13;

RGFW uses a macro to fill in optional arguments

#define RGFW_GL_ADD_ATTRIB(attrib, attVal) \
        if (attVal) { \
            attribs[index] = attrib;\
            attribs[index + 1] = attVal;\
            index += 2;\
        }

RGFW defines variables that can be changed by the user to fill in these arguments.

i32 RGFW_STENCIL = 0, RGFW_SAMPLES = 0, RGFW_STEREO = GL_FALSE, RGFW_AUX_BUFFERS = 0, RGFW_DOUBLE_BUFFER = 1;

I'm going to split the arguments up between each platform.

linux:
    if (RGFW_DOUBLE_BUFFER)
        RGFW_GL_ADD_ATTRIB(GLX_DOUBLEBUFFER, 1);
    RGFW_GL_ADD_ATTRIB(GLX_STENCIL_SIZE, RGFW_STENCIL);
    RGFW_GL_ADD_ATTRIB(GLX_STEREO, RGFW_STEREO);
    RGFW_GL_ADD_ATTRIB(GLX_AUX_BUFFERS, RGFW_AUX_BUFFERS);
    // samples are handled by GLX later

windows:
    if (RGFW_DOUBLE_BUFFER)
        RGFW_GL_ADD_ATTRIB(0x2011, 1);  // double buffer
    RGFW_GL_ADD_ATTRIB(0x2023, RGFW_STENCIL);
    RGFW_GL_ADD_ATTRIB(0x2012, RGFW_STEREO);
    RGFW_GL_ADD_ATTRIB(0x2024, RGFW_AUX_BUFFERS);
    RGFW_GL_ADD_ATTRIB(0x2042, RGFW_SAMPLES);

macOS:
    if (RGFW_DOUBLE_BUFFER)
        RGFW_GL_ADD_ATTRIB(5, 1); // double buffer
    RGFW_GL_ADD_ATTRIB(13, RGFW_STENCIL);
    RGFW_GL_ADD_ATTRIB(6, RGFW_STEREO);
    RGFW_GL_ADD_ATTRIB(7, RGFW_AUX_BUFFERS);
    RGFW_GL_ADD_ATTRIB(55, RGFW_SAMPLES);

    /* this is here because macOS has a specific way to handle using software rendering */

    if (useSoftware) {
        RGFW_GL_ADD_ATTRIB(70, kCGLRendererGenericFloatID);
    } else {
        attribs[index] = 73;
        index += 1;
    }

On macOS RGFW also sets the version here.

attribs[index] = 99;
attribs[index + 1] = 0x1000;

if (RGFW_majorVersion >= 4 || RGFW_majorVersion >= 3) {
    attribs[index + 1] = (u32) ((RGFW_majorVersion >= 4) ? 0x4100 : 0x3200);
}

Make sure the final two arguments are set to 0, this is how OpenGL/WGL/GLX/NSOpenGL knows to stop reading.

RGFW_GL_ADD_ATTRIB(0, 0);

Step 2.2 creating the pixel format

Now that the list is created, it can be used to create the pixel format.

GLX

GLX Handles this by creating an array of GLXFBConfig based on the attributes.

i32 fbcount;
GLXFBConfig* fbc = glXChooseFBConfig((Display*) display, DefaultScreen(display), (i32*) attribs, &fbcount);

i32 best_fbc = -1;

if (fbcount == 0) {
    printf("Failed to find any valid GLX visual configs\n");
    return NULL;
}

Then it uses the generated array to find the closest matching FBConfig object. (This is where RGFW_SAMPLES comes in)

u32 i;
for (i = 0; i < (u32)fbcount; i++) {
    XVisualInfo* vi = glXGetVisualFromFBConfig((Display*) display, fbc[i]);
                if (vi == NULL)
        continue;

    XFree(vi);

    i32 samp_buf, samples;
    glXGetFBConfigAttrib((Display*) display, fbc[i], GLX_SAMPLE_BUFFERS, &samp_buf);
    glXGetFBConfigAttrib((Display*) display, fbc[i], GLX_SAMPLES, &samples);

    if ((best_fbc < 0 || samp_buf) && (samples == RGFW_SAMPLES || best_fbc == -1)) {
        best_fbc = i;
    }
}

if (best_fbc == -1) {
    printf("Failed to get a valid GLX visual\n");
    return NULL;
}

GLXFBConfig bestFbc = fbc[best_fbc];

Once it finds the closest matching object, it gets the X11 visual (or pixel format) from the array and frees the array.

/* Get a visual */
XVisualInfo* vi = glXGetVisualFromFBConfig((Display*) display, bestFbc);

XFree(fbc);

Now this Visual can be used to create a window and/or colormap.

XSetWindowAttributes swa;
Colormap cmap;

swa.colormap = cmap = XCreateColormap((Display*) display,
    DefaultRootWindow(display),
    vi->visual, AllocNone);

swa.background_pixmap = None;
swa.border_pixel = 0;
swa.event_mask = event_mask;

swa.background_pixel = 0;

Window window = XCreateWindow((Display*) display, DefaultRootWindow((Display*) display), x, y, w, h,
    0, vi->depth, InputOutput, vi->visual,
    CWColormap | CWBorderPixel | CWBackPixel | CWEventMask, &swa);

WGL

RGFW needs some WGL defines for creating the context:

#define WGL_CONTEXT_CORE_PROFILE_BIT_ARB 0x00000001
#define WGL_CONTEXT_COMPATIBILITY_PROFILE_BIT_ARB 0x00000002
#define WGL_CONTEXT_MAJOR_VERSION_ARB             0x2091
#define WGL_CONTEXT_MINOR_VERSION_ARB             0x2092
#define WGL_CONTEXT_PROFILE_MASK_ARB              0x9126

For WGL, RGFW has to first create a win32 pixel format.

PIXELFORMATDESCRIPTOR pfd2 = (PIXELFORMATDESCRIPTOR){ sizeof(pfd2), 1, pfd_flags, PFD_TYPE_RGBA, 32, 8, PFD_MAIN_PLANE, 24, 8, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0};

Then RGFW can create a WGL pixel format based on the attribs array.

int pixel_format2;
UINT num_formats;
wglChoosePixelFormatARB(hdc, attribs, 0, 1, &pixel_format2, &num_formats);
if (!num_formats) {
    printf("Failed to create a pixel format for WGL.\n");
}

Now RGFW can merge the two as one big format and set it as the format for your window.

DescribePixelFormat(hdc, pixel_format2, sizeof(pfd2), &pfd2);
if (!SetPixelFormat(hdc, pixel_format2, &pfd2)) {
    printf("Failed to set the WGL pixel format.\n");
}

NSOpenGL

For MacOS, RGFW just has to create the pixel format and then init a view based on the format for OpenGL.

void* format = NSOpenGLPixelFormat_initWithAttributes(attribs);

/* the pixel format can be passed directly to opengl context creation to create a context 
    this is because the format also includes information about the opengl version (which may be a bad thing) */
view = NSOpenGLView_initWithFrame((NSRect){{0, 0}, {w, h}}, format);
objc_msgSend_void(view, sel_registerName("prepareOpenGL"));
ctx = objc_msgSend_id(view, sel_registerName("openGLContext"))
objc_msgSend_void(ctx, sel_registerName("makeCurrentContext"));

If you're following along for MacOS, you can skip step 3.

Step 3 (Create your OpenGL context using an attribute array to set the OpenGL version)

NOTE: RGFW defines this enum and these variables so the user can control the OpenGL version:

typedef u8 RGFW_GL_profile; enum { RGFW_GL_CORE = 0,  RGFW_GL_COMPATIBILITY  };
i32 RGFW_majorVersion = 0, RGFW_minorVersion = 0;
b8 RGFW_profile = RGFW_GL_CORE;

glx

Now it's time to create the attribute array for the GL context creation and load the OpenGL version you want:

i32 context_attribs[7] = { 0, 0, 0, 0, 0, 0, 0 };
context_attribs[0] = GLX_CONTEXT_PROFILE_MASK_ARB;
if (RGFW_profile == RGFW_GL_CORE) 
    context_attribs[1] = GLX_CONTEXT_CORE_PROFILE_BIT_ARB;
else 
    context_attribs[1] = GLX_CONTEXT_COMPATIBILITY_PROFILE_BIT_ARB;

if (RGFW_majorVersion || RGFW_minorVersion) {
    context_attribs[2] = GLX_CONTEXT_MAJOR_VERSION_ARB;
    context_attribs[3] = RGFW_majorVersion;
    context_attribs[4] = GLX_CONTEXT_MINOR_VERSION_ARB;
    context_attribs[5] = RGFW_minorVersion;
}

Finally, the context can be created using the context_attribs array:

ctx = glXCreateContextAttribsARB((Display*) display, bestFbc, NULL, True, context_attribs);
glXMakeCurrent(display, window, ctx); // make the window the current so it can be rendered to in the same thread

WGL

First WGL needs to create an attribs array for setting the OpenGL Version

It also uses a helper macro called SET_ATTRIB

#define SET_ATTRIB(a, v) { \
    assert(((size_t) index + 1) < sizeof(context_attribs) / sizeof(context_attribs[0])); \
    context_attribs[index++] = a; \
    context_attribs[index++] = v; \
}

/* create opengl/WGL context for the specified version */ 
u32 index = 0;
i32 context_attribs[40];

if (RGFW_profile == RGFW_GL_CORE) {
    SET_ATTRIB(WGL_CONTEXT_PROFILE_MASK_ARB, WGL_CONTEXT_CORE_PROFILE_BIT_ARB);
}
else {
    SET_ATTRIB(WGL_CONTEXT_PROFILE_MASK_ARB, WGL_CONTEXT_COMPATIBILITY_PROFILE_BIT_ARB);
}

if (RGFW_majorVersion || RGFW_minorVersion) {
    SET_ATTRIB(WGL_CONTEXT_MAJOR_VERSION_ARB, RGFW_majorVersion);
    SET_ATTRIB(WGL_CONTEXT_MINOR_VERSION_ARB, RGFW_minorVersion);
}

SET_ATTRIB(0, 0);

Now the context can be created:

ctx = (HGLRC)wglCreateContextAttribsARB(hdc, NULL, context_attribs);
wglMakeCurrent(hdc, ctx); // make the window the current so it can be rendered to in the same thread

Step 4 (Free the OpenGL context)

Now that RGFW has created its OpenGL context, it has to free the context when it's done using it.

This is the easy part.

Linux (GLX):
    glXDestroyContext((Display*) display, ctx);

windows (WGL):
    wglDeleteContext((HGLRC) ctx);

macOS (NSOpenGL):
    // I think macOS NSOpenGL stuff is freed automatically when everything else is freed

Full code examples

X11

// compile with gcc x11.c -lX11 -lGL

#include <X11/Xlib.h>
#include <GL/glx.h>

#include <stdio.h>
#include <stdint.h>

typedef GLXContext(*glXCreateContextAttribsARBProc)(Display*, GLXFBConfig, GLXContext, Bool, const int*);
typedef void ( *PFNGLXSWAPINTERVALEXTPROC) (Display *dpy, GLXDrawable drawable, int interval);

#define GL_ADD_ATTRIB(attrib, attVal) \
        if (attVal) { \
            attribs[index] = attrib;\
            attribs[index + 1] = attVal;\
            index += 2;\
        }

typedef uint8_t GL_profile; enum  { GL_CORE = 0,  GL_COMPATIBILITY  };
int32_t majorVersion = 0, minorVersion = 0;
Bool profile = GL_CORE;

int32_t STENCIL = 0, SAMPLES = 0, STEREO = GL_FALSE, AUX_BUFFERS = 0, DOUBLE_BUFFER = 1;

int main(void) {
    typedef void ( *PFNGLXSWAPINTERVALEXTPROC) (Display *dpy, GLXDrawable drawable, int interval);
    PFNGLXSWAPINTERVALEXTPROC glXSwapIntervalEXT = NULL;

    glXCreateContextAttribsARBProc glXCreateContextAttribsARB = (glXCreateContextAttribsARBProc)glXGetProcAddressARB((GLubyte*) "glXCreateContextAttribsARB");
    glXSwapIntervalEXT = (PFNGLXSWAPINTERVALEXTPROC) glXGetProcAddress((GLubyte*) "glXSwapIntervalEXT");

    static uint32_t attribs[] = {
               GLX_X_VISUAL_TYPE,      GLX_TRUE_COLOR,
               GLX_DEPTH_SIZE,         24,                            
               GLX_X_RENDERABLE,       1,
               GLX_RED_SIZE,           8,
               GLX_GREEN_SIZE,         8,
               GLX_BLUE_SIZE,          8,
               GLX_ALPHA_SIZE,         8,
               GLX_RENDER_TYPE,        GLX_RGBA_BIT,
               GLX_DRAWABLE_TYPE,      GLX_WINDOW_BIT,
               0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
    };

    size_t index = (sizeof(attribs) / sizeof(attribs[0])) - 13;

    if (DOUBLE_BUFFER)
        GL_ADD_ATTRIB(GLX_DOUBLEBUFFER, 1);
    GL_ADD_ATTRIB(GLX_STENCIL_SIZE, STENCIL);
    GL_ADD_ATTRIB(GLX_STEREO, STEREO);
    GL_ADD_ATTRIB(GLX_AUX_BUFFERS, AUX_BUFFERS);

    Display *display;
    XEvent event;

    display = XOpenDisplay(NULL);
    if (display == NULL) {
        fprintf(stderr, "Cannot open display\n");
        return -1;
    }

    int s = DefaultScreen(display);

    int32_t fbcount;
    GLXFBConfig* fbc = glXChooseFBConfig((Display*) display, DefaultScreen(display), (int32_t*) attribs, &fbcount);

    int32_t best_fbc = -1;

    if (fbcount == 0) {
        printf("Failed to find any valid GLX visual configs\n");
        return -1;
    }

    uint32_t i;
    for (i = 0; i < (uint32_t)fbcount; i++) {
        XVisualInfo* vi = glXGetVisualFromFBConfig((Display*) display, fbc[i]);
        if (vi == NULL)
            continue;

        XFree(vi);

        int32_t samp_buf, samples;
        glXGetFBConfigAttrib((Display*) display, fbc[i], GLX_SAMPLE_BUFFERS, &samp_buf);
        glXGetFBConfigAttrib((Display*) display, fbc[i], GLX_SAMPLES, &samples);

        if ((best_fbc < 0 || samp_buf) && (samples == SAMPLES || best_fbc == -1)) {
            best_fbc = i;
        }
    }

    if (best_fbc == -1) {
        printf("Failed to get a valid GLX visual\n");
        return -1;
    }

    GLXFBConfig bestFbc = fbc[best_fbc];

    XVisualInfo* vi = glXGetVisualFromFBConfig((Display*) display, bestFbc);

    XFree(fbc);

    XSetWindowAttributes swa;
    Colormap cmap;

    swa.colormap = cmap = XCreateColormap((Display*) display, DefaultRootWindow(display), vi->visual, AllocNone);

    swa.background_pixmap = None;
    swa.border_pixel = 0;
    swa.event_mask = CWColormap | CWBorderPixel | CWBackPixel | CWEventMask;

    swa.background_pixel = 0;

    Window window = XCreateWindow((Display*) display, DefaultRootWindow((Display*) display), 400, 400, 200, 200, 0, vi->depth, InputOutput, vi->visual, CWColormap | CWBorderPixel | CWBackPixel | CWEventMask, &swa);

    XSelectInput(display, window, ExposureMask | KeyPressMask);

    int32_t context_attribs[7] = { 0, 0, 0, 0, 0, 0, 0 };
    context_attribs[0] = GLX_CONTEXT_PROFILE_MASK_ARB;
    if (profile == GL_CORE) 
        context_attribs[1] = GLX_CONTEXT_CORE_PROFILE_BIT_ARB;
    else 
        context_attribs[1] = GLX_CONTEXT_COMPATIBILITY_PROFILE_BIT_ARB;

    if (majorVersion || minorVersion) {
        context_attribs[2] = GLX_CONTEXT_MAJOR_VERSION_ARB;
        context_attribs[3] = majorVersion;
        context_attribs[4] = GLX_CONTEXT_MINOR_VERSION_ARB;
        context_attribs[5] = minorVersion;
    }

    GLXContext ctx = glXCreateContextAttribsARB((Display*) display, bestFbc, NULL, True, context_attribs);
    glXMakeCurrent(display, window, ctx);

    XMapWindow(display, window);

    for (;;) {
        XNextEvent(display, &event);

        glClearColor(0.2f, 0.3f, 0.3f, 1.0f);
        glClear(GL_COLOR_BUFFER_BIT);

        glXSwapBuffers(display, window);
    }

    glXDestroyContext((Display*) display, ctx);
    XCloseDisplay(display);

    return 0;
 }

Windows


// compile with gcc winapi.c -lopengl32 -lgdi32
#include <windows.h>
#include <GL/gl.h>

#include <stdio.h>
#include <stdint.h>
#include <assert.h>

typedef uint8_t     u8;
typedef int8_t      i8;
typedef uint16_t   u16;
typedef int16_t    i16;
typedef uint32_t   u32;
typedef int32_t    i32;
typedef uint64_t   u64;
typedef int64_t    i64;
typedef u8 b8;

#define WGL_CONTEXT_CORE_PROFILE_BIT_ARB 0x00000001
#define WGL_CONTEXT_COMPATIBILITY_PROFILE_BIT_ARB 0x00000002
#define WGL_CONTEXT_MAJOR_VERSION_ARB             0x2091
#define WGL_CONTEXT_MINOR_VERSION_ARB             0x2092
#define WGL_CONTEXT_PROFILE_MASK_ARB              0x9126

int main() {
    typedef HGLRC (WINAPI *PFNWGLCREATECONTEXTATTRIBSARBPROC)(HDC hdc, HGLRC hglrc, const int *attribList);
    PFNWGLCREATECONTEXTATTRIBSARBPROC wglCreateContextAttribsARB = NULL;

    typedef HRESULT (APIENTRY* PFNWGLCHOOSEPIXELFORMATARBPROC)(HDC hdc, const int* piAttribIList, const FLOAT* pfAttribFList, UINT nMaxFormats, int* piFormats, UINT* nNumFormats);
    static PFNWGLCHOOSEPIXELFORMATARBPROC wglChoosePixelFormatARB = NULL;

    typedef BOOL(APIENTRY* PFNWGLSWAPINTERVALEXTPROC)(int interval);
    static PFNWGLSWAPINTERVALEXTPROC wglSwapIntervalEXT = NULL;

    WNDCLASS wc = {0};
    wc.lpfnWndProc   = DefWindowProc; // Default window procedure
    wc.hInstance     = GetModuleHandle(NULL);
    wc.lpszClassName = "SampleWindowClass";

    RegisterClass(&wc);

    HWND dummyWin = CreateWindowA(wc.lpszClassName, "Sample Window", 0, 200, 200, 300, 300, 0, 0, wc.hInstance, 0);
    HDC dummy_dc = GetDC(dummyWin);

    u32 pfd_flags = PFD_DRAW_TO_WINDOW | PFD_SUPPORT_OPENGL | PFD_DOUBLEBUFFER;

    PIXELFORMATDESCRIPTOR pfd = {
        sizeof(pfd),
        1, /* version */
        pfd_flags,
        PFD_TYPE_RGBA, /* ipixel type */
        24, /* color bits */
        0, 0, 0, 0, 0, 0,
        8, /* alpha bits */
        0, 0, 0, 0, 0, 0,
        32, /* depth bits */
        8, /* stencil bits */ 
        0,
        PFD_MAIN_PLANE, /* Layer type */
        0, 0, 0, 0
    };

    int pixel_format = ChoosePixelFormat(dummy_dc, &pfd);
    SetPixelFormat(dummy_dc, pixel_format, &pfd);

    HGLRC dummy_context = wglCreateContext(dummy_dc);
    wglMakeCurrent(dummy_dc, dummy_context);

    wglCreateContextAttribsARB = (PFNWGLCREATECONTEXTATTRIBSARBPROC) (void*) wglGetProcAddress("wglCreateContextAttribsARB");
    wglChoosePixelFormatARB = (PFNWGLCHOOSEPIXELFORMATARBPROC) (void*)wglGetProcAddress("wglChoosePixelFormatARB");

    wglSwapIntervalEXT = (PFNWGLSWAPINTERVALEXTPROC) wglGetProcAddress("wglSwapIntervalEXT");

    wglMakeCurrent(dummy_dc, 0);
    wglDeleteContext(dummy_context);
    ReleaseDC(dummyWin, dummy_dc);
    DestroyWindow(dummyWin);

    static u32 attribs[] = {
              0x2003, // WGL_ACCELERATION_ARB
              0x2027, // WGL_FULL_ACCELERATION_ARB
              0x201b, 8, // WGL_ALPHA_BITS_ARB
              0x2022, 24, // WGL_DEPTH_BITS_ARB
              0x2001, 1, // WGL_DRAW_TO_WINDOW_ARB
              0x2015, 8, // WGL_RED_BITS_ARB
              0x2017, 8, // WGL_GREEN_BITS_ARB
              0x2019, 8, // WGL_BLUE_BITS_ARB
              0x2013, 0x202B, // WGL_PIXEL_TYPE_ARB, WGL_TYPE_RGBA_ARB
              0x2010, 1, // WGL_SUPPORT_OPENGL_ARB
              0x2014,    32, // WGL_COLOR_BITS_ARB
              0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
            };

    size_t index = (sizeof(attribs) / sizeof(attribs[0])) - 13;
    #define RGFW_GL_ADD_ATTRIB(attrib, attVal) \
        if (attVal) { \
            attribs[index] = attrib;\
            attribs[index + 1] = attVal;\
            index += 2;\
        }

    i32 RGFW_STENCIL = 0, RGFW_SAMPLES = 0, RGFW_STEREO = GL_FALSE, RGFW_AUX_BUFFERS = 0, RGFW_DOUBLE_BUFFER = 1;

    if (RGFW_DOUBLE_BUFFER)
        RGFW_GL_ADD_ATTRIB(0x2011, 1);  // double buffer
    RGFW_GL_ADD_ATTRIB(0x2023, RGFW_STENCIL);
    RGFW_GL_ADD_ATTRIB(0x2012, RGFW_STEREO);
    RGFW_GL_ADD_ATTRIB(0x2024, RGFW_AUX_BUFFERS);
    RGFW_GL_ADD_ATTRIB(0x2042, RGFW_SAMPLES);
    RGFW_GL_ADD_ATTRIB(0, 0);

    typedef u8 RGFW_GL_profile; enum { RGFW_GL_CORE = 0,  RGFW_GL_COMPATIBILITY  };
    i32 RGFW_majorVersion = 0, RGFW_minorVersion = 0;
    b8 RGFW_profile = RGFW_GL_CORE;

    HWND hwnd = CreateWindowA(wc.lpszClassName, "Sample Window",
                                0,
                                400, 400, 300, 300,
                                NULL, NULL, wc.hInstance, NULL);

    HDC hdc = GetDC(hwnd);


    PIXELFORMATDESCRIPTOR pfd2 = (PIXELFORMATDESCRIPTOR){ sizeof(pfd2), 1, pfd_flags, PFD_TYPE_RGBA, 32, 8, PFD_MAIN_PLANE, 24, 8, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0};
    int pixel_format2;
    UINT num_formats;
    wglChoosePixelFormatARB(hdc, attribs, 0, 1, &pixel_format2, &num_formats);
    if (!num_formats) {
        printf("Failed to create a pixel format for WGL.\n");
    }

    DescribePixelFormat(hdc, pixel_format2, sizeof(pfd2), &pfd2);
    if (!SetPixelFormat(hdc, pixel_format2, &pfd2)) {
        printf("Failed to set the WGL pixel format.\n");
    }

    #define SET_ATTRIB(a, v) { \
        assert(((size_t) index + 1) < sizeof(context_attribs) / sizeof(context_attribs[0])); \
        context_attribs[index++] = a; \
        context_attribs[index++] = v; \
    }

    /* create opengl/WGL context for the specified version */ 
    index = 0;
    i32 context_attribs[40];

    if (RGFW_profile == RGFW_GL_CORE) {
        SET_ATTRIB(WGL_CONTEXT_PROFILE_MASK_ARB, WGL_CONTEXT_CORE_PROFILE_BIT_ARB);
    }
    else {
        SET_ATTRIB(WGL_CONTEXT_PROFILE_MASK_ARB, WGL_CONTEXT_COMPATIBILITY_PROFILE_BIT_ARB);
    }

    if (RGFW_majorVersion || RGFW_minorVersion) {
        SET_ATTRIB(WGL_CONTEXT_MAJOR_VERSION_ARB, RGFW_majorVersion);
        SET_ATTRIB(WGL_CONTEXT_MINOR_VERSION_ARB, RGFW_minorVersion);
    }

    SET_ATTRIB(0, 0);

    HGLRC ctx = (HGLRC)wglCreateContextAttribsARB(hdc, NULL, context_attribs);
    wglMakeCurrent(hdc, ctx);

    ShowWindow(hwnd, SW_SHOW);
    UpdateWindow(hwnd);

    MSG msg;

    BOOL running = TRUE;
    while (running) {
        if (PeekMessageA(&msg, hwnd, 0u, 0u, PM_REMOVE)) {
            switch (msg.message) {
                case WM_CLOSE:
                case WM_QUIT:
                    running = FALSE;
                    break;
            }
            TranslateMessage(&msg);
            DispatchMessage(&msg);
        }

        running = IsWindow(hwnd);


        glClearColor(0.2f, 0.3f, 0.3f, 1.0f);
        glClear(GL_COLOR_BUFFER_BIT);

        SwapBuffers(hdc);
    }

    DeleteDC(hdc);
    DestroyWindow(hwnd);
    return 0;
}

Introducing RGFW: A lightweight Single Header Windowing framework & GLFW alternative

Colleague Riley — Thu, 25 Jul 2024 23:18:06 +0000

Intro

RGFW is a cross-platform single-header framework that abstracts creating and managing windows. RGFW is simple to use, letting you focus on programming your game or application rather than dealing with complex low-level windowing APIs, libraries with a lot of overhead, or supporting platform-specific APIs. RGFW handles the low-level APIs for you without getting in your way. It currently supports X11 (Linux), Windows (XP +), Emscripten (HTML5), and MacOS.
While creating a window, RGFW initializes a graphics context of your choosing. The options include OpenGL (including variants), DirectX, direct software rendering, or no graphics API. There is also a separate header for Vulkan support although it's recommended to make your Vulkan context yourself.

Design

RGFW is also flexible by design. For example, you can use an event loop system or an event call-back system. (See more in examples/events/main.c and examples/callbacks/main.c in the RGFW repo).

while (RGFW_window_checkEvent(win)) {
  switch (win->event.type) {
     case RGFW_quit:
       break;  
     case RGFW_keyPressed:
       break;
     case RGFW_mousePosChanged:
        break;
     ...
  }
}
void mouseposfunc(RGFW_window* win, RGFW_point point) {

} 
void keyfunc(RGFW_window* win, u32 keycode, char keyName[16], u8 lockState, u8 pressed) {

}

void windowquitfunc(RGFW_window* win) {

}

RGFW_setMousePosCallback(mouseposfunc);
RGFW_setKeyCallback(keyfunc);
RGFW_setWindowQuitCallback(windowquitfunc);

RGFW vs GLFW

RGFW is designed as an alternative to GLFW. This is because GLFW's codebase is not lightweight and is missing some flexibility.
There is a GitHub repository that takes all of GLFW's source code and puts it in one big single-header library. This GLFW.h file is 10.7 megabytes and cannot be viewed on GitHub. RGFW can be viewed on GitHub because it is 244 kilobytes and the RGFW binaries are also generally around a third of the size of GLFW's binaries. RGFW also tends to use less RAM than GLFW.
If RGFW is significantly more lightweight than GLFW does that mean that RGFW is lacking features? No, RGFW has nearly the same features as GLFW. If you're interested in knowing the differences, there is a table included in the RGFW repository that compares RGFW to GLFW.

Using/compiling RGFW

To use RGFW you need to add this line to one of your source files.
#define RGFW_IMPLEMENTATION
This allows the RGFW source defines to be included.
You can also compile RGFW like any other library.

cc -x c -c RGFW.h -D RGFW_IMPLEMENTATION -fPIC -D 

RGFW_EXPORT
(Linux): 
cc -shared RGFW.o -lX11 -lXrandr -lm -lGL

(window mingw): 
cc -shared RGFW.o -lgdi32 -lopengl32 -lwinmm -lm

(macOS)
cc -shared RGFW.o -framework Foundation -framework AppKit -framework OpenGL -framework CoreVideo -lm

RGFW example

To create a window and initialize RGFW, if it's the first window, you use RGFW_createWindow(const char* name, RGFW_rect, u16 args)
For example, to create a window in the center of the screen that cannot be resized

RGFW_window* win = RGFW_createWindow("Window", RGFW_RECT(0, 0, 200, 200) RGFW_CENTER | RGFW_NO_RESIZE);

... // do software stuff

RGFW_window_close(win); // close window now that we're done

After you finish rendering, you need to swap the window buffer.
RGFW_window_swapBuffers(RGFW_window* win);
If you're using an unsupported API, you'll need to handle the function yourself.
Now here's a full RGFW example:

#define RGFW_IMPLEMENTATION
#include "RGFW.h"

u8 icon[4 * 3 * 3] = {0xFF, 0x00, 0x00, 0xFF,    0xFF, 0x00, 0x00, 0xFF,     0xFF, 0x00, 0x00, 0xFF,   0xFF, 0x00, 0x00, 0x00, 0xFF, 0xFF, 0x00, 0xFF, 0xFF, 0xFF, 0x00, 0xFF,     0xFF, 0x00, 0x00, 0xFF, 0xFF, 0x00, 0x00, 0xFF, 0xFF, 0x00, 0x00, 0xFF};

void keyfunc(RGFW_window* win, u32 keycode, char keyName[16], u8 lockState, u8 pressed) {
    printf("this is probably early\n");
}

int main() {
    RGFW_window* win = RGFW_createWindow("name", RGFW_RECT(500, 500, 500, 500), (u64)RGFW_CENTER);

    RGFW_window_setIcon(win, icon, RGFW_AREA(3, 3), 4);

    RGFW_setKeyCallback(keyfunc); // you can use callbacks like this if you want 

    i32 running = 1;

    while (running) {
        while (RGFW_window_checkEvent(win)) { // or RGFW_window_checkEvents(); if you only want callbacks
            if (win->event.type == RGFW_quit || RGFW_isPressed(win, RGFW_Escape)) {
                running = 0;
                break;
            }

            if (win->event.type == RGFW_keyPressed) // this is the 'normal' way of handling an event
                printf("This is probably late\n");
        }

        glClearColor(0xFF, 0XFF, 0xFF, 0xFF);
        glClear(GL_COLOR_BUFFER_BIT);

        RGFW_window_swapBuffers(win);
    }

    RGFW_window_close(win);
}

Final notes

A screenshot of the RGFW examples and PureDoom-RGFWMore example codes and information about RGFW can be found in the repository. The examples can also be run with HTML5 on the RGFW examples site. If RGFW interests you, feel free to check out the RGFW repository, star it, or ask me any questions you have about RGFW. I am also open to any criticism, advice, or feature requests you may have.

Although RGFW is significantly more lightweight than GLFW, that doesn’t mean you should it over GLFW. Ultimately, the choice is up to you. RGFW is more lightweight but it's also newer and has a tiny community. So there's less support and it hasn't yet been tested in a production-ready project.

If you find RGFW interesting, please check out the repository. One way you can support RGFW is by starring it.

https://github.com/ColleagueRiley/RGFW

RSGL | Modular header-only cross-platform GUI Library for easily creating GUI software your way!

Colleague Riley — Sun, 25 Feb 2024 22:28:38 +0000

RSGL is A modular simple-to-use cross-platform GUI library for easily creating GUI apps and games. It combines the freedom of lower-level GUI libraries with modern C techniques, offering both simplicity and convenience. Its main features are its built in lightweight dependence and its flexibility, its cross platform support. It currently supports Linux, Windows and MacOS, has a zlib license, and due to its use of STB and miniaudio, supports many data formats.

Introduction to RSGL

https://github.com/ColleagueRiley/RSGL

RSGL, short for Riley's Simple GUI Library, is a tool designed to streamline the development of graphical user interfaces (GUIs) for applications and games. At its core, RSGL serves as a modular and cross-platform solution, offering developers the freedom to create GUIs easily while overcoming common challenges encountered in GUI development.

By encapsulating essential GUI functionalities within a lightweight and versatile library, RSGL empowers developers to focus on creativity rather than wrestling with technical complexities.

Background of RSGL

Much like SDL RSGL tries to not get in the users way. But unlike SDL, RSGL tries to be more modernized and do more for the user. Another library RSGL can be compared to is Raylib. I did not know about Raylib until after I had already created my initial design of RSGL. On the surface Raylib and RSGL have very similar designs. Although, RSGL has different design choices and a stronger focus on being lightweight. For example, all of RSGL's internal dependencies are very lightweight and most are designed to be so. While the dependencies Raylib uses are not designed to be lightweight, such as GLFW. RSGL uses RGFW instead of GLFW, the .o output of GLFW is ~280kb while RGFW's is ~46kb. Nevertheless Raylib and RSGL and both good choices for a GUI Library and the one you choose to use might change depending on your taste and circumstance.

Another similarity between Raylib and RSGL is that they both use OpenGL abstraction layers. RLGL and RGL respectively. I won't go into too much detail on the differences here. But it is very important to note how these both make their respective library all that stronger. The software creator can easily compile between modern and legacy OpenGL. RGL also allows the program to render using legacy functions during runtime. This allows the program to have a fail safe, just another way RSGL provides convenience to the user.

Using the code

Enough talking about how great RSGL is. Here is an example so you can decide for yourself is RSGL is really worth all the praise.

#define RSGL_NO_AUDIO /* we don't want to link with miniaudio.h */
#define RSGL_IMPLEMENTATION
#include "RSGL.h"

#include <stdbool.h>

int main() {
    /* create window and pass arg to make sure it's centered */
    RSGL_window* win = RSGL_createWindow("example", RSGL_RECT(0, 0, 500, 500), RSGL_CENTER);

    bool legacy = false;

    bool running = true;
    while(running) {
/* check events until there are no more events to check */
        while(RSGL_window_checkEvent(win)) {
            if (win->event.type == RGFW_quit || RSGL_isPressedI(win, RGFW_Escape)) {
                running = false;
                break;
            }

            /* if the space bar is pressed, toggle rendering using opengl legacy */
            if (win->event.type == RSGL_keyPressed && win->event.keyCode == RGFW_Space) {
               legacy = !legacy;
               RSGL_legacy(legacy);
            }
        }   

        /* draw a basic rectangle and clear the screen */
        RSGL_drawRect(RSGL_RECT(200, 200, 200, 200), RSGL_RGB(255, 0, 0));
        RSGL_window_clear(win, RSGL_RGB(255, 255, 255));
    }

    RSGL_window_close(win);
}

Compiling :
windows : gcc -lopengl32 -lshell32 -lgdi32
linux: gcc -lGLX -lX11 -lm
macos : gcc -framework Foundation -framework AppKit -framework OpenGL -framework CoreVideo

NOTE : This is a very basic example, there are plenty far less basic examples included in the repo.

Points of Interest

The overall features of RSGL, as bulleted list are :

No external dependencies, all the libraries required are included in RSGL and are also very lightweight\
Supports multiple platforms, windows, MacOS, linux, ect
Supports multiple versions of OpenGL (even allowing you to switch during runtime)
Uses other small lightweight dependencies
OpenGL abstraction layer : RGL (which is its own single-header library too)
Supports multiple font and image formats due to stb_truetype.h and stb_image.h
Supporst multiple audio formats due to miniaudio.h
Many examples included
Free and Open Source with a very flexible license

RSGL Modules

RSGL_NO_WIDGETS (makes it so RSGL doesn't include widget functions)

RSGL_NO_AUDIO (makes it so RSGL doesn't include audio functions)

RSGL_NO_WINDOW - no RSGL_window, RSGL_graphics is used instead [this is for using a differnt window manager other than RGFW ]

RSGL_NO_TEXT - do not include text rendering functions

RGFW_NO_WIDGETS - do not include widgets

RSGL_NO_AUDIO - do not include audio functions

RSGL_NO_MINIAUDIO_IMPLEMENTATION - do not have #define MINIAUDIO_IMPLEMENTATION in
this header (you'll have to link miniaudio some other way to use audio)

RSGL_NO_SAVE_IMAGE - do not save/load images (don't use RSGL_drawImage if you use this),

RSGL_drawImage saves the file name + texture so it can load it
when you ask for it later. This disables that

RSGL-Architecture diagram

License

RSGL uses the libpng license, this means you can use RSGL freely as long as you do not claim you wrote this software, mark altered versions as such and keep the license included with the header.

final note

The RSGL Repo can be found at :
https://github.com/ColleagueRiley/RSGL

RGFW | Singler-Header Lightweight framework for basic window and graphics context handling (like GLFW)

Colleague Riley — Thu, 22 Feb 2024 19:23:37 +0000

github repo : https://github.com/ColleagueRiley/RGFW

RGFW is a single-header lightweight a multi-platform single-header very simple-to-use framework library for creating GUI Libraries or simple GUI programs. It is written to be portable as possible and supports winapi, Xlib and cocoas for windowing apis. For graphics apis it supports, OpenGL legacy, modern OpenGL, Vulkan and DirectX. It let's you create a window with an graphics context (opengl, vulkan or directX) and manage the window and it's events only with a few function calls.

More information can be found on the RGFW repo, such as table provided in the header to show specific things RGFW supports and other information about RGFW compared to GLFW. Such as that RGFW uses far less RAM and space while having a few more features than GLFW. Documentation can be found in the header itself, RGFW.h.

Below is very basic example code

#define RGFW_IMPLEMENTATION
#include "RGFW.h"

int main() {
    RGFW_window* win = RGFW_createWindow("name", 500, 500, 500, 500, (u64)0);

    RGFW_window_setIcon(win, icon, 3, 3, 4);

    i8 running = 1;

    for (running) {
        while(RGFW_window_checkEvent(win)) {
            if (win->event.type == RGFW_quit) {
               running = 0;
               break;
            }
        }

       if (RGFW_isPressedI(win, RGFW_Escape))
            break;

        RGFW_window_swapBuffers(win);

        glClearColor(0xFF, 0XFF, 0xFF, 0xFF);
        glClear(GL_COLOR_BUFFER_BIT);
    }

    RGFW_window_close(win);
}

github repo : https://github.com/ColleagueRiley/RGFW