bindbc-allegro5 1.1.0
Dynamic and static bindings to Allegro and its addons, compatible with -betterC, @nogc, and nothrow.
To use this package, run the following command in your project's root directory:
Manual usage
Put the following dependency into your project's dependences section:
bindbc-allegro5
Note This is not an official BindBC package.
This project provides both static and dynamic bindings to the Allegro libraries. They are compatible with @nogc
and nothrow
and can be compiled with -betterC
compatibility.
General BindBC Usage
BindBC is a cross-platform API for creating D bindings for C libraries. This entire section was adapted from bindbc-sdl’s README. You may skip to Package Declarations section if you are already familiar with BindBC conventions.
By default, bindbc-allegro5 is configured to compile as dynamic bindings that are not BetterC-compatible. The dynamic bindings have no link-time dependency on the Allegro libraries, so the Allegro shared libraries must be manually loaded at runtime. When configured as static bindings, there is a link-time dependency on the Allegro libraries—either the static libraries or the appropriate files for linking with shared libraries on your system (see below).
When using DUB to manage your project, the static bindings can be enabled via a DUB subConfiguration
statement in your project’s package file. BetterC compatibility is also enabled via subconfigurations.
To use any of the supported Allegro libraries, add bindbc-allegro5 as a dependency to your project’s package config file and include the appropriate version for any of the addons you want to use. For example, the following is configured to use Font and TTF addons, in addition to the base Allegro binding, as dynamic bindings that are not BetterC-compatible:
dub.json
dependencies {
"bindbc-allegro5": "~>1.0.0",
}
"versions": [
"Allegro_Font",
"Allegro_TTF"
],
dub.sdl
dependency "bindbc-allegro5" version="~>1.0.0"
versions "Allegro_Font" "Allegro_TTF"
The Dynamic Bindings
The dynamic bindings require no special configuration when using DUB to manage your project. There is no link-time dependency. At runtime, the Allegro shared libraries are required to be on the shared library search path of the user’s system. On Windows, this is typically handled by distributing the Allegro DLLs with your program. On other systems, it usually means installing the Allegro runtime libraries through a package manager.
To load the shared libraries, you need to call the appropriate load function. This returns a member of the AllegroSupport
enumeration:
AllegroSupport.noLibrary
indicating that the library failed to load (it couldn’t be found)AllegroSupport.badLibrary
indicating that one or more symbols in the library failed to load- a member of
AllegroSupport
indicating a version number that matches the version of Allegro that bindbc-allegro5 was configured at compile-time to load. By default, that isAllegroSupport.v5_2_0
, but can be configured via a version identifier (see below). This value will match the global manifest constant,allegroSupport
.
import bindbc.allegro5;
/*
This version attempts to load the Allegro shared library using well-known
variations of the library name for the host system.
*/
AllegroSupport ret = loadAllegro();
if (ret != allegroSupport) {
/*
Handle error. For most use cases, it’s reasonable to use the the error
handling API in bindbc-loader to retrieve error messages for logging and
then abort. If necessary, it’s possible to determine the root cause via
the return value:
*/
if (ret == AllegroSupport.noLibrary) {
// The Allegro shared library failed to load
}
else if (AllegroSupport.badLibrary) {
/*
One or more symbols failed to load. The likely cause is that the shared
library is for a lower version than bindbc-allegro5 was configured
to load (via Allegro_5_2_8, etc.)
*/
}
}
/*
This version attempts to load the Allegro library using a user-supplied file
name. Usually, the name and/or path used will be platform specific, as in this
example which attempts to load `allegro-5.2.dll` from the `libs` subdirectory,
relative to the executable, only on Windows.
*/
version (Windows) loadAllegro("libs/allegro-5.2.dll");
The error reporting API in bindbc-loader can be used to log error messages.
// Import the dependent package
import bindbc.allegro5;
/*
Import the sharedlib module for error handling. Assigning an alias ensures
the function names do not conflict with other public APIs. This isn’t strictly
necessary, but the API names are common enough that they could appear in other
packages.
*/
import loader = bindbc.loader.sharedlib;
bool loadLib() {
/*
Compare the return value of loadAllegro with the global `allegroSupport`
constant to determine if the version of Allegro configured at compile time
is the version that was loaded.
*/
auto ret = loadAllegro();
if (ret != allegroSupport) {
// Log the error info
foreach (info; loader.errors) {
/*
A hypothetical logging function. Note that `info.error` and
`info.message` are `const(char)*`, not
`string`.
*/
logError(info.error, info.message);
}
// Optionally construct a user-friendly error message for the user
string msg;
if (ret == AllegroSupport.noLibrary) {
msg = "This application requires the Allegro library.";
}
else {
msg = "The version of the Allegro library on your system is too low. Please upgrade."
}
// A hypothetical message box function
showMessageBox(msg);
return false;
}
return true;
}
By default, each bindbc-allegro5 binding is configured to compile bindings for stable APIs of the lowest supported version of the C libraries. This ensures the widest level of compatibility at runtime. This behavior can be overridden via specific version identifiers. It is recommended that you always select the minimum version you require and no higher. In this example, the Allegro dynamic binding is compiled to support Allegro 5.2.2:
dub.json
"dependencies": {
"bindbc-allegro5": "~>1.0.0"
},
"versions": ["Allegro_5_2_2"]
dub.sdl
dependency "bindbc-allegro5" version="~>1.0.0"
versions "Allegro_5_2_2"
With this example configuration, allegroSupport
is configured at compile time as AllegroSupport.v5_2_2
. If Allegro 5.2.2 or later is installed on the system, loadAllegro
will return AllegroSupport.v5_2_2
. If a lower version of Allegro is installed, loadAllegro
will return AllegroSupport.badLibrary
. In this scenario, calling loadedAllegroVersion()
will return an AllegroSupport
member indicating which version of Allegro, if any, actually loaded.
If a lower version is loaded, it’s still possible to call functions from that version of Allegro, but any calls to functions from versions between that version and the one you configured will result in a null pointer access. For example, if you configured Allegro 2.0.4
and loaded Allegro 2.0.2
, then function pointers from both 2.0.3 and 2.0.4 will be null
. For this reason, it’s recommended to always specify your required version of the Allegro library at compile time and abort when you receive an AllegroSupport.badLibrary
return value from loadAllegro
.
No matter which version was configured, the successfully loaded version can be obtained via a call to loadedAllegroVersion
. It returns one of the following:
AllegroSupport.noLibrary
ifloadAllegro
returnedAllegroSupport.noLibrary
AllegroSupport.badLibrary
ifloadAllegro
returnedAllegroSupport.badLibrary
and no version of Allegro successfully loaded- a member of
AllegroSupport
indicating the version of Allegro that successfully loaded. WhenloadAllegro
returnsAllegroSupport.badLibrary
, this will be a version number lower than the one configured at compile time. Otherwise, it will be the same as the manifest constantallegroSupport
.
The function isAllegroLoaded
returns true
if any version of the shared library has been loaded and false
if not.
AllegroSupport ret = loadAllegro();
if (ret != allegroSupport) {
if (AllegroSupport.badLibrary) {
/*
Let’s say we’ve configured support for Allegro 5.2.5 for some of the functions
added to the Allegro API in that version and don’t use them if they
aren’t available. Let’s further say that the absolute minimum version
of Allegro we require is 5.2.2, because we rely on some of the functions
that version added to the Allegro API.
In this scenario, `AllegroSupport.badLibrary` indicates that we have
loaded a version of Allegro that is less than 5.2.5. Maybe it’s 5.2.4,
or 5.2.1. We require at least 5.2.2, so we can check.
*/
if (loadedAllegroVersion < AllegroSupport.5_2_2) {
// Version too low. Handle the error.
}
}
/*
The only other possible return value is `AllegroSupport.noLibrary`,
indicating the Allegro library or one of its dependencies could not be found.
*/
else {
// No library. Handle the error.
}
}
For most use cases, it’s probably not necessary to check for AllegroSupport.badLibrary
or AllegroSupport.noLibrary
. The bindbc-loader package provides a means to fetch error information regarding load failures. This information can be written to a log file before aborting the program.
See Package Declarations section for the supported versions of each Allegro library and the corresponding version IDs to pass to the compiler.
The Static Bindings
First things first: static bindings do not require static linking. The static bindings have a link-time dependency on either the shared or static Allegro libraries and any satellite Allegro libraries the program uses. On Windows, you can link with the static libraries or, to use the DLLs, the import libraries. On other systems, you can link with either the static libraries or directly with the shared libraries.
Static bindings requires the Allegro development packages be installed on your system. Allegro releases on GitHub provide precompiled Windows binaries. On OS X, you can use Homebrew. On Unix-like systems, you can install them via your system package manager. See Allegro downloads page for details and additional options.
When linking with the shared (or import) libraries, there is a runtime dependency on the shared library just as there is when using the dynamic bindings. The difference is that the shared libraries are no longer loaded manually–loading is handled automatically by the system when the program is launched. Attempting to call loadAllegro
with the static binding enabled will result in a compilation error.
When linking with the static libraries, there is no runtime dependency on Allegro. Besides static Allegro libraries, you also need to acquire all its dependencies and link with them. This is a lot of work with questionable benefits.
Enabling the static bindings can be done in two ways.
Via the Compiler’s -version
Switch or DUB’s versions
Directive
Pass the BindAllegro_Static
version to the compiler and link with the appropriate libraries. Note that BindAllegro_Static
will also enable the static bindings for any addons used.
When using the compiler command line or a build system that doesn’t support DUB, this is the only option. The -version=BindAllegro_Static
option should be passed to the compiler when building your program. All of the required C libraries, as well as the bindbc-allegro5 static libraries, must also be passed to the compiler on the command line or via your build system’s configuration.
Note: Though bindbc5-allegro is not an official BindBC package, it supports BindBC_Static
version identifier.
For example, when using the static bindings for Allegro and Allegro_image with DUB:
dub.json
"dependencies": {
"bindbc-allegro5": "~>1.0.0"
},
"versions": ["BindAllegro_Static", "Allegro_Image"],
"libs-windows": ["liballegro", "liballegro_image"]
dub.sdl
dependency "bindbc-allegro5" version="~>1.0.0"
versions "BindAllegro_Static" "Allegro_Image"
libs "liballegro" "liballegro_image"
Via DUB Subconfigurations
Instead of using DUB’s versions
directive, a subConfiguration
can be used. Enable the static
subconfiguration for the bindbc-allegro5 dependency:
dub.json
"dependencies": {
"bindbc-allegro5": "~>1.0.0"
},
"subConfigurations": {
"bindbc-allegro5": "static"
},
"versions": [
"Allegro_Image"
],
"libs": ["liballegro", "liballegro_image"]
dub.sdl
dependency "bindbc-allegro5" version="~>1.0.0"
subConfiguration "bindbc-allegro5" "static"
versions "Allegro_Image"
libs "liballegro" "liballegro_image"
This has the benefit of completely excluding from the build any source modules related to the dynamic bindings, i.e., they will never be passed to the compiler. Using the version approach, the related modules are still passed to the compiler, but their contents are versioned out.
BetterC support
BetterC support is enabled via the dynamicBC
and staticBC
subconfigurations, for dynamic and static bindings respectively. To enable the static bindings with BetterC support:
dub.json
"dependencies": {
"bindbc-allegro5": "~>1.0.0"
},
"subConfigurations": {
"bindbc-allegro5": "staticBC"
},
"versions": [
"Allegro_Image"
],
"libs": ["liballegro", "liballegro_image"]
dub.sdl
dependency "bindbc-allegro5" version="~>1.0.0"
subConfiguration "bindbc-allegro5" "staticBC"
versions "Allegro_Image"
libs "liballegro" "liballegro_image"
Replace staticBC
with dynamicBC
to enable BetterC support with the dynamic bindings.
When not using DUB to manage your project, first use DUB to compile the BindBC libraries with the dynamicBC
or staticBC
configuration, then pass -betterC
to the compiler when building your project (and -version=BindAllegro_Static
if you used the staticBC
configuration).
Package Declarations
To bind statically, define BindAllegro_Static
version. If you use bindbc-allegro5 in conjunction with other BindBC packages, you can define BindBC_Static
version to bind them all statically (some third-party BindBC packages may not support this).
Functions:
AllegroSupport loadAllegro();
AllegroSupport loadAllegro(const(char)* libName);
void unloadAllegro();
bool isAllegroLoaded();
AllegroSupport loadedAllegroVersion();
Supported Allegro versions:
Version | Version ID | AllegroSupport |
---|---|---|
5.2.0 | default | v5_2_0 |
5.2.1 | Allegro_5_2_1 | v5_2_1 |
5.2.2 | Allegro_5_2_2 | v5_2_2 |
5.2.3 | Allegro_5_2_3 | v5_2_3 |
5.2.4 | Allegro_5_2_4 | v5_2_4 |
5.2.5 | Allegro_5_2_5 | v5_2_5 |
5.2.6 | Allegro_5_2_6 | v5_2_6 |
5.2.7 | Allegro_5_2_7 | v5_2_7 |
5.2.8 | Allegro_5_2_8 | v5_2_8 |
5.2.9 | Allegro_5_2_9 | v5_2_9 |
Note: To use Allegro debugging capabilities, define ALLEGRO_DEBUG
version and link with debug library builds.
Note: Parts of Allegro API, including most of the new functions introduced in 5.2.x releases, are marked as unstable. To use them, define ALLEGRO_UNSTABLE
version. This will make compatibility checks more strict: this particular WIP version must be found on user’s system. For example, if ALLEGRO_UNSTABLE
and Allegro_5_2_3
are defined, and the user has Allegro 5.2.4 installed, Allegro will fail to initialize.
Note: To access X-specific functions, define ALLEGRO_X11
version.
Addons
Official addons are part of Allegro, so they don’t have their own versioning.
Allegro can be build as a monolith library with all addons included. To link with such a library, define Allegro_Monolith
version. With dynamic bindings, loadAllegro
will also load all addon function. Attempts to call addon loading functions (like loadAllegroImage
) will fail at compile time.
Allegro_Image
AllegroSupport loadAllegroImage();
AllegroSupport loadAllegroImage(const(char)* libName);
void unloadAllegroImage();
bool isAllegroImageLoaded();
AllegroSupport loadedAllegroImageVersion();
Allegro_Primitives
AllegroSupport loadAllegroPrimitives();
AllegroSupport loadAllegroPrimitives(const(char)* libName);
void unloadAllegroPrimitives();
bool isAllegroPrimitivesLoaded();
AllegroSupport loadedAllegroPrimitivesVersion();
Allegro_Color
AllegroSupport loadAllegroColor();
AllegroSupport loadAllegroColor(const(char)* libName);
void unloadAllegroColor();
bool isAllegroColorLoaded();
AllegroSupport loadedAllegroColorVersion();
Allegro_Font
AllegroSupport loadAllegroFont();
AllegroSupport loadAllegroFont(const(char)* libName);
void unloadAllegroFont();
bool isAllegroFontLoaded();
AllegroSupport loadedAllegroFontVersion();
Allegro_TTF
Note: Requires Allegro_Font
AllegroSupport loadAllegroTTF();
AllegroSupport loadAllegroTTF(const(char)* libName);
void unloadAllegroTTF();
bool isAllegroTTFLoaded();
AllegroSupport loadedAllegroTTFVersion();
Allegro_Audio
AllegroSupport loadAllegroAudio();
AllegroSupport loadAllegroAudio(const(char)* libName);
void unloadAllegroAudio();
bool isAllegroAudioLoaded();
AllegroSupport loadedAllegroAudioVersion();
Allegro_ACodec
Note: Requires Allegro_Audio
AllegroSupport loadAllegroACodec();
AllegroSupport loadAllegroACodec(const(char)* libName);
void unloadAllegroACodec();
bool isAllegroACodecLoaded();
AllegroSupport loadedAllegroACodecVersion();
Allegro_Video
Note: Requires Allegro_Audio
AllegroSupport loadAllegroVideo();
AllegroSupport loadAllegroVideo(const(char)* libName);
void unloadVideoAllegro();
bool isAllegroVideoLoaded();
AllegroSupport loadedAllegroVideoVersion();
Allegro_Memfile
AllegroSupport loadAllegroMemfile();
AllegroSupport loadAllegroMemfile(const(char)* libName);
void unloadAllegroMemfile();
bool isAllegroMemfileLoaded();
AllegroSupport loadedAllegroMemfileVersion();
Allegro_PhysFS
AllegroSupport loadAllegroPhysFS();
AllegroSupport loadAllegroPhysFS(const(char)* libName);
void unloadAllegroPhysFS();
bool isAllegroPhysFSLoaded();
AllegroSupport loadedAllegroPhysFSVersion();
Allegro_Dialog
AllegroSupport loadAllegroDialog();
AllegroSupport loadAllegroDialog(const(char)* libName);
void unloadAllegroDialog();
bool isAllegroDialogLoaded();
AllegroSupport loadedAllegroDialogVersion();
- Registered by Georgy Markov
- 1.1.0 released 9 months ago
- Ogi-kun/bindbc-allegro5
- Boost
- Copyright © 2022...2024, Georgy Markov
- Authors:
- Dependencies:
- none
- Versions:
-
1.1.0 2024-Jan-20 1.0.0 2022-Dec-25 0.0.1 2022-Aug-21 ~master 2024-Jan-20 - Download Stats:
-
-
0 downloads today
-
0 downloads this week
-
0 downloads this month
-
34 downloads total
-
- Score:
- 0.6
- Short URL:
- bindbc-allegro5.dub.pm