muCOSA v2.0.1

muCOSA (COSA standing for cross operating-system API) is a public domain single-file C library for interacting with operating systems with a cross-platform API. Its header is automatically defined upon inclusion if not already included (MUCOSA_H), and the source code is defined if MUCOSA_IMPLEMENTATION is defined, following the interal structure of:

#ifndef MUCOSA_H
#define MUCOSA_H
// (Header code)
#endif

#ifdef MUCOSA_IMPLEMENTATION
// (Source code)
#endif

Therefore, a standard inclusion of the file to get all automatic functionality looks like:

#define MUCOSA_IMPLEMENTATION
#include "muCOSA.h"

More information about the general structure of a mu library is provided at the mu library information GitHub repository.

Demos

Demos are designed for muCOSA to both test its functionality and allow users to get the basic idea of the structure of the library quickly without having to read the documentation in full. These demos are available in the demos folder.

Demo dependencies

Since the demos test the functionality of OpenGL, glad is used as an OpenGL loader in the demos (with these settings if you're interested), and therefore needs to be included when compiling the demos. Include dependencies are stored in the include folder within demos, and all files within this folder should be in the user's include directory when compiling them.

Note that the inclusion of glad changes the conditions of the licensing due to Khronos's Apache 2.0 license for OpenGL specifications; more information is given in the licensing section of this documentation.

System dependencies

muCOSA is supported for Win32. This operating system requires the user to link to certain operating system files when compiling.

Win32 dependencies

To compile with Windows, you need to link the following files under the given circumstances:

user32.dll and imm32.dll in any given circumstance.

gdi32.dll and opengl32.dll if MU_SUPPORT_OPENGL is defined by the user.

Licensing

muCOSA is licensed under public domain or MIT, whichever you prefer. More information is provided in the accompanying file license.md and at the bottom of muCOSA.h.

However, note that the demos that use OpenGL use glad, which is built from the Khronos specification for OpenGL, so its Apache 2.0 license applies within that context. See further clarification in this issue comment.

Multi-threading

muCOSA does not directly support thread safety, and must be implemented by the user themselves. Thread safety in muCOSA can be generally achieved by locking each object within a muCOSA context (ie muWindow for example), making sure that only one thread is interacting with the given object. There are a few known exceptions to this to achieve total thread safety, which are detailed below, but multi-threading with muCOSA is not thoroughly tested.

Context creation

If MU_SUPPORT_OPENGL is defined, two contexts cannot be created at the same time. This is technically a limitation, as it has to do with the generation of unique class names for a dummy WGL-loading window.

Window updating

Due to limitations with the handling of messages on Win32, no more than one window can be updated safely at any given time across threads.

Window resizing/moving

Due to the way that Win32 handles messages when the window is being resized or moved, a call to muCOSA_window_update will hang for the entire duration of the window being dragged/moved. Handling implemented by users of muCOSA should expect this, and handle vital functionality that needs to be executed over this time on a separate thread.

Known bugs and limitations

This section covers all of the known bugs and limitations with muCOSA.

Limited support for most stuff

This version of muCOSA is intended to be very basic, meaning that it only supports Windows and OpenGL, and is not thoroughly tested on other devices. Additionally, many features that might be needed on certain programs are absent. This, if not abandoned, will change in the future, as more support is added, but for now, this library's reach will be fairly limited.

Minimal overhead attribute management

Currently, muCOSA gets/sets attributes using a single function that requires at least one get/set call for every attribute being modified. Theoretically, more overhead could be abolished by allowing to get/set multiple attributes in one function call, perhaps using the muWindowInfo struct and a flag system. This has not been outruled as an option, and muCOSA may stand to gain via this being implemented at some point.

Unique class name generation

Currently, a unique class name for every window is generated by using the manually-allocated pointer for each window, which, although making it highly likely that a unique name will be generated each time, doesn't make it entirely likely. More optimally, a system of generating valid unique names should be implemented, likely using an atomic counter and manual allocation per name, but this has yet to be implemented.

Inefficient window memory allocation on Win32

Due to limitations with how a window is identified via its handle in the window procedure functions, the implementation for Win32 has a memory buffer that contains pointers to each window. The logic for this uses filling in empty slots to ensure that a fair amount of memory is allocated even in the event of a large amount of windows being destroyed and created. However, the logic of it currently does not decrease the amount of memory allocated for the window pointers, meaning that a peak in the amount of windows created (across all muCOSA contexts) will peak the memory usage for the buffer, and will not decrease until all muCOSA contexts are destroyed.

This is generally okay, both because the maximum amount of memory allocated for this buffer is the size of a pointer multiplied by the closest power of 2 greater than the amount of windows. So, for example, if there were a maximum of 2718 windows reached at some point during the program's lifespan, and the device is using 64 bits per pointer, the memory usage by this buffer will peak at 64*4096, or 262144 bytes, and will not decrease until all muCOSA contexts are destroyed. However, it is not only unlikely that a program will ever use this amount of windows, but it is even more unlikely that Windows itself will be able to run properly after this amount of windows have been created.

Testing with multiple pixel formats

Uncommon pixel formats (such as no-alpha pixel formats) are not tested thoroughly in muCOSA, and in fields where pixel format information is meant to be specified, the information may not be formatted correctly by muCOSA, leading to a bad result being returned. The documentation on what makes "valid" pixel format attributes for OpenGL ranges from confusing to non-existent, so this area can definitely be improved upon later.

Other library dependencies

muCOSA has a dependency on:

• muUtility v2.0.1.

Note that mu libraries store their dependencies within their files, so you don't need to import these dependencies yourself; this section is purely to give more information about the contents that this file defines. The libraries listed may also have other dependencies that they also include that aren't explicitly listed here.

Version

The macros MUCOSA_VERSION_MAJOR, MUCOSA_VERSION_MINOR, and MUCOSA_VERSION_PATCH are defined to match its respective release version, following the formatting of MAJOR.MINOR.PATCH.

Window systems

The type muWindowSystem (typedef for uint8_m) is used to define all of the currently supported window systems. It has the following defined values:

• MU_WINDOW_NULL - Unknown/Null window system; real value 0. This value can also act as an "auto" window system, such as when creating a muCOSA context with it, automatically picking the best currently available window system.

• MU_WINDOW_WIN32 - Win32; real value 1.

Note that although on most operating systems, only one window system can exist (such as macOS or Windows), some operating systems can have more than one window system, such as Linux with X11 or Wayland. Just in case, muCOSA allows more than one window system to be defined at once in its API, tying each muCOSA context to a particular window system, theoretically allowing for multiple muCOSA contexts to exist at once with different window systems in one program.

Window system names

The name function mu_window_system_get_name returns a const char* representation of the given window sytem (for example, MU_WINDOW_NULL returns "MU_WINDOW_NULL"), defined below:

MUDEF const char* mu_window_system_get_name(muWindowSystem system);

It will return "MU_UNKNOWN" in the case that system is an invalid window system value.

The name function mu_window_system_get_nice_name does the same thing, but with a nicer and more readable const char* representation (for example, MU_WINDOW_NULL returns "Unknown/Auto"), defined below:

MUDEF const char* mu_window_system_get_nice_name(muWindowSystem system);

It will return "Unknown" in the case that system is an invalid window system value.

These functions are "name" functions, and therefore are only defined if MUCOSA_NAMES is also defined by the user.

Manual window system support

Not all window systems are supported upfront, so it is automatically guessed based on the current operating system that the code is compiling for using macros provided by muUtility.

The explicit functionality is this:

• MUCOSA_WIN32 is defined if MU_WIN32 is defined (automatically provided by muUtility), which toggles support for Win32.

All of this functionality can be overrided by defining the macro MUCOSA_MANUAL_OS_SUPPORT, in which case, none of this is performed, and it is up to the user to manually define that operating systems are supported by defining their respective muCOSA macros (ie, if you're compiling on Windows and disabled automatic operating system recognition, you would need to define MUCOSA_WIN32 yourself).

Global context

muCOSA operates in a context, encapsulated by the type muCOSAContext, which has the following members:

• void* inner - pointer to internally-used manually-allocated memory for running the current operating system context. The user should never interact with this member.

• muCOSAResult result - the result of the latest non-successful non-result-checking function call regarding the context; starting value upon context creation is MUCOSA_SUCCESS, and is set to another value if a function whose result is not set manually by the user doesn't return a success result value.

Creation and destruction

To create the context, the function muCOSA_context_create is used, defined below:

MUDEF void muCOSA_context_create(muCOSAContext* context, muWindowSystem system, muBool set_context);

The result of this function is stored within context->result. Upon success, this function automatically calls muCOSA_context_set on the created context unless set_context is equal to MU_FALSE.

For every successfully created context, it must be destroyed, which is done with the function muCOSA_context_destroy, defined below:

MUDEF void muCOSA_context_destroy(muCOSAContext* context);

This function cannot fail if given a valid pointer to an active context (otherwise, a crash is likely), so no result value is ever indicated by this funct