SubC.AllegroDotNet 0.9.0

AllegroDotNet

❓ What is it?

The AllegroDotNet project aims to make the Allegro 5 game programming library available in C# and feel .NET-like. Using AllegroDotNet will allow you to create game and multimedia applications in C#.

⭐ Requirements

• Target x64 architecture (at least, for now)
• Native Allegro library available (example allegro-5.2.dll / allegro_monolith-5.2.dll, see Quick Start)

💥 Quick Start (Windows)

1. Add NuGet package references to SubC.AllegroDotNet and SubC.AllegroDotNet.Win64.

2. Add the following test code to your source code:

using SubC.AllegroDotNet;
// ...
Al.Init();
var display = Al.CreateDisplay(1280, 720) ?? throw new Exception();
Al.Rest(3);
Al.DestroyDisplay(display);
Al.UninstallSystem();

3. Compile and run.

For more example code, see the Source/Ex.<whatever> projects such as Source/Ex.Camera/.

🔥 Slow Start

AllegroDotNet is a wrapper for the native Allegro 5 library. Care was taken to make Allegro feel more like .NET and not a wrapper library generated by a tool that requires you to pass around IntPtr everywhere.

You must provide the native Allegro 5 library, but the NuGet package SubC.AllegroDotNet.Win64 can do that for you if you add it to your project (if targeting Windows).

All the existing documentation for Allegro 5 is still valid with AllegroDotNet; for example, you still have to first call al_init() (in AllegroDotNet: Al.Init()), then you can make your display with al_create_display() (in AllegroDotNet: Al.CreateDisplay()), etc.

Things like the concept of the thread that created the display is the thread that owns it is still correct (just like when using Allegro in C); there is not too much of a difference between using C# with AllegroDotNet to run Allegro or C/C++ code.

See below for more differences between Allegro and AllegroDotNet.

💾 Native Allegro 5 Library

AllegroDotNet is only an interop wrapper for the native Allegro 5 library; you still need to provide the native Allegro 5 binary library. For convience, you can use the SubC.AllegroDotNet.Win64 NuGet package if you are targeting Windows to automatically add the monolith .DLL to your project's output. The Allegro 5 library filenames should not be modified from the defaults, such as allegro_monolith-5.2.dll (Windows).

The native Allegro library may require a runtime for your target platform, such as the Visual C++ Redistributable vc_redist.x64.exe on Windows. Your development machine may already have this installed, but other machines may not. This is a requirement you can forget about when testing on other machines.

The method Al.Init() tries to initialize Allegro with any known versions in the LibraryVersion enumeration. If you want/need to specify the version, you need to call Al.InstallSystem() instead.

When specifying the version of Allegro 5 with Al.InstallSystem(), you can provide either an integer of the version as per usual from C, or use the enumeration LibraryVersion to specify some well-known versions such as 5.2.8 (LibraryVersion.V528).

📰 Differences Between Allegro and AllegroDotNet

• All Allegro functions are provided in the Al static class (example: Al.InstallKeyboard()).

• Most Allegro 5 opaque types (example: ALLEGRO_BITMAP*) are turned into classes (example: AllegroBitmap). They are located in the SubC.AllegroDotNet.Models namespace.

• The remaining Allegro 5 types (example: ALLEGRO_COLOR) are turned into structures (example: AllegroColor). You will often need to pass them with the ref keyword to facilitate marshalling them to the native C library correctly and quickly.

• Allegro 5 constant values (example: ALLEGRO_NO_PRESERVE_TEXTURE) are grouped into enumerations (example: BitmapFlags.NoPreserveTexture). These enumerations are in the SubC.AllegroDotNet.Enums namespace.

• Allegro 5 macros (example: ALLEGRO_BPS_TO_SECS(x)) are turned into static methods (example: Al.BpsToSecs(x)).

• The method Al.Init() only is aware of versions in the LibraryVersion enumeration. If you need to initialize a version of Allegro not in this enumeration, you need to call Al.InstallSystem() with the correct integer parameter (same as from C code).

• When calling Al.InitUserEventSource(), native memory is allocated for the event source. When you are done with the event source, call Al.DestroyUserEventSource(). This is different than native Allegro 5 where the ALLEGRO_EVENT_SOURCE is allocated by the user, instead of the API methods.

• If the Allegro function takes or returns a string, that involves extra marshalling from managed/unmanaged code. While this isn't "slow", it isn't as fast as passing pointers and numbers around.

📝 Custom Interop Providers

AllegroDotNet has built in interop providers for Windows, OS X, and Linux. These providers define 3 things:

• The well-known filenames of the Allegro 5 library.
• A method that will load a library and return the native pointer to it.
• A method that will return the native pointer to a function in the Allegro 5 library.

You can make your own custom interop provider if you want to have custom Allegro 5 library filenames or add support for a platform not already present. To use your own interop provider:

• Make a class that implements the SubC.AllegroDotNet.Native.IInteropProvider interface (see the existing interop providers for examples).
• Call Al.SetupInteropProvider() before you call any Allegro function.
• Call Allegro functions (ex: Al.InstallSystem()) like usual.

⚠️ Troubleshooting

• If you get "unbalanced stack" errors, ensure your application is targeting x64 architecture. AnyCPU or x86 will not work.

• If calling Al.InstallSystem() is failing, ensure the version of Allegro 5 you are trying to load is available. You cannot load Allegro 5.2.8 if you pass LibraryVersion.V529 (5.2.9) to Al.InstallSystem(). Also ensure the library files (ie, .DLL files on Windows) are available to your executable.

• If you get "missing function" errors, you may be using a native version of Allegro 5 that does not have functions available that are expected by AllegroDotNet. For example, if you did not include audio or acodec support in your Allegro 5 library, but you try to use any of those functions, you will get an error.

• You may get errors if your native library files do not have their dependencies available or are not statically linked. You can solve this by providing the needed libraries (flac.dll, zlib.dll, etc) or by using a statically-linked native Allegro library.

❌ Unimplemented Routines

• Any function marked as "Unstable API" - I will add these functions if they become non-unstable.
• Haptic functions - These are marked as unstable in Allegro 5.2.9.
• PhysFS addon - This would also require wrapping the PhysFS library.