{"id":13805655,"url":"https://github.com/BindBC/bindbc-freeimage","last_synced_at":"2025-05-13T19:31:36.030Z","repository":{"id":48395024,"uuid":"179520798","full_name":"BindBC/bindbc-freeimage","owner":"BindBC","description":"Static \u0026 dynamic D bindings to FreeImage, compatible with BetterC, @nogc, and nothrow.","archived":false,"fork":false,"pushed_at":"2023-07-07T20:52:20.000Z","size":54,"stargazers_count":7,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-18T21:48:27.808Z","etag":null,"topics":["bindbc","dlang","freeimage"],"latest_commit_sha":null,"homepage":"","language":"D","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsl-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BindBC.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE_1_0.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-04-04T15:00:12.000Z","updated_at":"2024-04-02T17:40:28.000Z","dependencies_parsed_at":"2024-01-03T01:20:16.097Z","dependency_job_id":"9e0756bb-2efc-493c-86b4-ed97200d0c43","html_url":"https://github.com/BindBC/bindbc-freeimage","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BindBC%2Fbindbc-freeimage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BindBC%2Fbindbc-freeimage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BindBC%2Fbindbc-freeimage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BindBC%2Fbindbc-freeimage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BindBC","download_url":"https://codeload.github.com/BindBC/bindbc-freeimage/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254012987,"owners_count":21999346,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bindbc","dlang","freeimage"],"created_at":"2024-08-04T01:01:03.494Z","updated_at":"2025-05-13T19:31:35.729Z","avatar_url":"https://github.com/BindBC.png","language":"D","funding_links":[],"categories":["Game Bindings"],"sub_categories":["XML"],"readme":"# bindbc-freeimage\nThis project provides both static and dynamic bindings to the [FreeImage library](http://freeimage.sourceforge.net/download.html). They are `@nogc` and `nothrow` compatible and can be compiled for compatibility with BetterC. This package is intended as a replacement of [DerelictFI](https://github.com/DerelictOrg/DerelictFI), which is not compatible with `@nogc`,  `nothrow`, or BetterC.\n\n## Usage\nBy default, `bindbc-freeimage` is configured to compile as a dynamic binding that is not BetterC compatible. The dynamic binding has no link-time dependency on the FreeImage library, so the FreeImage shared library must be manually loaded at run time. When configured as a static binding, there is a link-time dependency on the FreeImage library\u0026mdash;either the static library or the appropriate file for linking with shared libraries on your platform. (see below)\n\nWhen using DUB to manage your project, the static binding can be enabled via a DUB `subConfiguration` statement in your project's package file. BetterC compatibility is also enabled via subconfigurations.\n\nTo use FreeImage, add `bindbc-freeimage` as a dependency to your project's package config file. For example, the following is configured to compile FreeImage as a dynamic binding that is not BetterC compatible:\n\n__dub.json__\n```\ndependencies {\n    \"bindbc-freeimage\": \"~\u003e1.1.0\",\n}\n```\n\n__dub.sdl__\n```\ndependency \"bindbc-freeimage\" version=\"~\u003e1.1.0\"\n```\n\n### The dynamic binding\nThe dynamic binding requires no special configuration when using DUB to manage your project. There is no link-time dependency. At run time, the FreeImage shared library is required to be on the shared library search path of the user's system. On Windows, this is typically handled by distributing the FreeImage DLL with your program. On other systems, it usually means the user must install the FreeImage shared library through a package manager.\n\nTo load the shared library, you need to call the `loadFreeImage` function. This returns a member of the `FISupport` enumeration (see [the README for `bindbc.loader`](https://github.com/BindBC/bindbc-loader/blob/master/README.md) for the error handling API):\n\n* `FISupport.noLibrary` indicating that the library failed to load (it couldn't be found)\n* `FISupport.badLibrary` indicating that one or more symbols in the library failed to load\n* a member of `FISupport` indicating a version number that matches the version of FreeImage that `bindbc-freeimage` was configured at compile-time to load. By default, that is `FISupport.fi317`, but can be configured via a version identifier (see below). This value will match the global manifest constant, `fiSupport`.\n\n```d\nimport bindbc.freeimage;\n\n/*\nThis version attempts to load the FreeImage shared library using well-known variations\nof the library name for the host system.\n*/\nFISupport ret = loadFreeImage();\nif(ret != fiSupport) {\n\n    // Handle error. For most use cases, its reasonable to use the the error handling API in\n    // bindbc-loader to retrieve error messages for logging and then abort. If necessary, it's\n    // possible to determine the root cause via the return value:\n\n    if(ret == FISupport.noLibrary) {\n        // FreeImage shared library failed to load\n    }\n    else if(FISupport.badLibrary) {\n        // One or more symbols failed to load. The likely cause is that the\n        // shared library is for a lower version than bindbc-freeimage was configured\n        // to load.\n    }\n}\n\n/*\nThis version attempts to load the FreeImage library using a user-supplied file name.\nUsually, the name and/or path used will be platform specific, as in this example\nwhich attempts to load `freeimage.dll` from the `libs` subdirectory, relative\nto the executable, only on Windows.\n*/\n// version(Windows) loadFreeImage(\"libs/freeimage.dll\")\n```\nBy default, the `bindbc-freeimage` binding is configured to load FreeImage 3.17. This behavior can be overridden via the `-version` compiler switch or the `versions` DUB directive with the desired FreeImage version number. It is recommended that you always select the minimum version you require _and no higher_. In this next example, the FreeImage dynamic binding is compiled to support FreeImage 3.18:\n\n__dub.json__\n```\n\"dependencies\": {\n    \"bindbc-freeimage\": \"~\u003e1.1.0\"\n},\n\"versions\": [\"FI_318\"]\n```\n\n__dub.sdl__\n```\ndependency \"bindbc-freeimage\" version=\"~\u003e1.1.0\"\nversions \"FI_318\"\n```\n\nWith this example configuration, `fiSupport == FISupport.fi318` on a successful load. If FreeImage 3.18 or later is installed on the user's system, `loadFreeImage` will return `FISupport.fi318`. If FreeImage 3.17 is found instead, `loadFreeImage` will return `FISupport.badLibrary`. In this scenario, calling `loadedFreeImageVersion()` will return a `FISupport` member indicating which version of FreeImage, if any, actually loaded. If a lower version was loaded, it's still possible to call functions from that version of FreeImage, but any calls to functions from higher versions will result in a null pointer access. For this reason, it's recommended to always specify your required version of the FreeImage library at compile time and abort when you receive an `FISupport.badLibrary` return value from `loadFreeImage`.\n\nNo matter which version was configured, the successfully loaded version can be obtained via a call to `loadedFreeImageVersion`. It returns one of the following:\n\n* `FISupport.noLibrary` if `loadFreeImage` returned `FISupport.noLibrary`\n* `FISupport.badLibrary` if `loadFreeImage` returned `FISupport.badLibrary` and no version of FreeImage successfully loaded\n* a member of `FISupport` indicating the version of FreeImage that successfully loaded. When `loadFreeImage` returns `FISupport.badLibrary`, this will be a version number lower than that configured at compile time. Otherwise, it will be the same as the manifest constant `fiSupport`.\n\nThe function `isFreeImageLoaded` returns `true` if any version of FreeImage was successfully loaded and `false` otherwise.\n\nFollowing are the supported versions of FreeImage, the corresponding version IDs to pass to the compiler, and the corresponding `FISupport` members.\n\n| Library \u0026 Version  | Version ID       | `FISupport` Member |\n|--------------------|------------------|--------------------|\n|FreeImage 3.17      | FI_317 (Default) | `FISupport.fi317`  |\n|FreeImage 3.18      | FI_318           | `FISupport.fi318`  |\n\n## The static binding\nThe static binding has a link-time dependency on either the shared or the static FreeImage library. On Windows, you can link with the static library or, to use the shared library (`freeimage.dll`), with the import library. On other systems, you can link with either the static library or directly with the shared library. This requires the FreeImage development package be installed on your system at compile time, either by compiling the FreeImage source yourself, downloading the FreeImage precompiled binaries for Windows, or installing via a system package manager. [See the FreeImage download page](http://freeimage.sourceforge.net/download.html) for details.\n\nWhen linking with the static library, there is no run-time dependency on FreeImage. When linking with the shared library (or the import library on Windows), the run-time dependency is the same as the dynamic binding, the difference being that the shared library is no longer loaded manually\u0026mdash;loading is handled automatically by the system when the program is launched.\n\nEnabling the static binding can be done in two ways.\n\n### Via the compiler's `-version` switch or DUB's `versions` directive\nPass the `BindFI_Static` version to the compiler and link with the appropriate library.\n\nUsing the compiler command line or a build system that doesn't support DUB, the `-version=BindFI_Static` option should be passed to the compiler when building your program. All of the required C libraries, as well as the `bindbc-freeimage` and `bindbc-loader` static libraries, must also be passed to the compiler on the command line or via your build system's configuration.\n\nUsing DUB, set the `BindFI_Static` version via its `versions` directive and  the required libraries in the `libs` directive. For example:\n\n__dub.json__\n```\n\"dependencies\": {\n    \"bindbc-freeimage\": \"~\u003e1.1.0\"\n},\n\"versions\": [\"BindFI_Static\"],\n\"libs\": [\"freeimage\"]\n```\n\n__dub.sdl__\n```\ndependency \"bindbc-freeimage\" version=\"~\u003e1.1.0\"\nversions \"BindFI_Static\"\nlibs \"freeimage\"\n```\n\nThe above example only links to the FreeImage library, meaning it is linking with either the shared library or, on Windows, the import library for the DLL. When linking with the FreeImage static library, any dependencies it has must also be added to the `libs` directive.\n\n### Via DUB subconfigurations\nInstead of using DUB's `versions` directive, a `subConfiguration` can be used. Enable the `static` subconfiguration for the `bindbc-freeimage` dependency:\n\n__dub.json__\n```\n\"dependencies\": {\n    \"bindbc-freeimage\": \"~\u003e1.1.0\"\n},\n\"subConfigurations\": {\n    \"bindbc-freeimage\": \"static\"\n},\n\"libs\": [\"freeimage\"]\n```\n\n__dub.sdl__\n```\ndependency \"bindbc-freeimage\" version=\"~\u003e1.1.0\"\nsubConfiguration \"bindbc-freeimage\" \"static\"\nlibs \"freeimage\"\n```\n\nThis has the benefit that it completely excludes from the build any source modules related to the dynamic binding, i.e. they will never be passed to the compiler. When linking with the FreeImage static library, its dependencies must still also be added to the `libs` directive.\n\n## `betterC` support\n\n`betterC` support is enabled via the `dynamicBC` and `staticBC` subconfigurations, for dynamic and static bindings respectively. To enable the static binding with BetterC support:\n\n__dub.json__\n```\n\"dependencies\": {\n    \"bindbc-freeimage\": \"~\u003e1.1.0\"\n},\n\"subConfigurations\": {\n    \"bindbc-freeimage\": \"staticBC\"\n},\n\"libs\": [\"freeimage\"]\n```\n\n__dub.sdl__\n```\ndependency \"bindbc-freeimage\" version=\"~\u003e1.1.0\"\nsubConfiguration \"bindbc-freeimage\" \"staticBC\"\nlibs \"freeimage\"\n```\n\nWhen 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.\n\n## Support for the `JPEGTransform*` functions\n\nOn some platforms, the following functions may be disabled by default in the binaries distributed via the system package manager:\n\n* `FreeImage_JPEGTransform`\n* `FreeImage_JPEGTransformU`\n* `FreeImage_JPEGCrop`\n* `FreeImage_JPEGCropU`\n* `FreeImage_JPEGTransformFromHandle`\n* `FreeImage_JPEGTransformCombined`\n* `FreeImage_JPEGTransformCombinedU`\n* `FreeImage_JPEGTransformCombinedFromMemory`\n\n`binbc-freeimage` excludes these functions by default. If your application requires these functions, there are a few steps to take.\n\nFirst, add the version `BindFI_JPEGTransform` to your DUB package configuration or compiler command line.\n\n__dub.json__\n```\n\"versions\": [\"BindFI_JPEGTransform\"],\n```\n__dub.sdl__\n```\nversions \"BindFI_JPEGTransform\"\n```\n\nNext, either ship your application with a version of the FreeImage shared library that supports these functions or inform your users they'll need to compile or install a version that does.\n\nFinally, for robustness, you may want to use the `bindbc-loader` error handling API to filter any errors that arise when these functions are missing so that you may present an error message to your users informing them how to install a properly compiled version of the FreeImage shared library.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBindBC%2Fbindbc-freeimage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FBindBC%2Fbindbc-freeimage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBindBC%2Fbindbc-freeimage/lists"}