Native bindings¶
Raw bindings for each C library are generated by our own tool, Tools/Apogee.Build/Bindings (ClangSharp.Interop over
libclang). Output goes to Source/Apogee.Native.<Lib>/Generated/ and is committed; nothing in Generated/ is edited by
hand.
./build.sh bindings # all libraries
./build.sh bindings sdl flecs # some
Each library has a JSON config in Tools/Apogee.Build/Bindings/Configs/: headers and include directories, ownDirs
(declarations found elsewhere are foreign and not bound), prefixes and suffixes to strip, renames, macro groups that
become [Flags] enums, and regexes for functions and constants to leave out. What was skipped, and why, is written to
Bin/bindings/<lib>.skipped.txt.
A config can name a type that another binding defines (foreignTypes, a regex on C names mapped to a namespace): it is then referenced and not bound again, by the name that binding gives it (the same
stripPrefixes and renames, as rmlui.json and cimgui.json have). Enum members lose the common prefix they share with their enum (JPH_MotionType_Static is MotionType.Static), and members whose C name starts with an underscore
(_JPH_MotionType_Count, _JPH_MotionType_Force32: reserved names, not values) are left out.
Vulkan is generated from the Khronos registry ("kind": "vulkan") rather than headers, and loads commands through
vkGetInstanceProcAddr into VkGlobalCommands, VkInstanceCommands and VkDeviceCommands.
Steamworks ("kind": "steam") is generated from Valve's steam_api.json and the S_API declarations of its flat API, because the headers are C++: the config names the interfaces to bind (interfaces) and the core functions (includeFunctions).
libclang parses the headers only to measure the structs, once with Linux's 4-byte callback packing and once as Windows (8), and the structs whose size differs are emitted with Pack = SteamPack.Callback
(Native libraries).
What is generated¶
Blittable structs, unmanaged function pointers for callbacks, opaque handles as readonly structs, DllImports with
ExactSpelling (runtime marshalling is disabled in every binding assembly), a module initializer that registers the
library with NativeLibraries, and a Sizes table of every struct's C size.
Build defines¶
The headers are read with the defines the native library is built with ("defines" in the config, and the same ones in
Native/<lib>/CMakeLists.txt). Struct layouts can depend on them: Flecs has more fields in ecs_ref_t and ecs_map_t in a
debug build, so its binding is generated with FLECS_NDEBUG and the library is always compiled with it. The struct size
test cannot catch this, because it compares with what clang saw, not with the compiled library; FlecsRefsHaveTheLayoutOfTheCompiledLibrary
calls a function that returns such a struct by value.
Exported variables¶
extern variables (extern const ecs_entity_t EcsOnUpdate;) become ref properties that look the symbol up by name the
first time they are used, so the value is always the library's, filled in by its init function:
ulong phase = Ecs.OnUpdate; // ref readonly ulong: the variable is const in C
Ecs.ComponentId // ecs_id(EcsComponent), the symbol FLECS_IDEcsComponentID_
globalRenames (regex → replacement, first match wins, applied before the usual stripping) maps odd symbol names;
excludeGlobals leaves out variables the library does not export (debug-only ones, or ones declared without a definition).
Arrays are not bound. A variable whose name is a function's keeps the full C name (EcsDelete next to Delete).
Array parameters¶
A C parameter written as an array (float color[4]) is a pointer to its first element: the binding takes float*, not an inline array by value (libclang reports the
written type, and passing the bytes where an address is expected crashes). Fields of structs are different: they are fixed buffers or inline arrays.
Types from another binding¶
A library whose headers use another library's types (VMA uses Vulkan's) lists them in foreignTypes: a regex on the C
type name and the C# namespace of the binding assembly that has it under the same name.
"foreignTypes": { "^Vk": "Apogee.Native.Vulkan" },
"typeMap": { "VkBufferUsageFlags": "VkBufferUsageFlagBits", "VkBool32": "uint", "VkDeviceSize": "ulong" }
Those types are referenced (the generated files get a using for the namespace, and the project references the other
binding), never generated again. The Vulkan binding names flags typedefs differently from C (VkBufferUsageFlags is the
VkBufferUsageFlagBits enum, VkBool32 is uint), so those go in typeMap, which is looked at first. A name that the
other assembly lacks is a compile error in the generated code, not a silent void*.
Vulkan structure types¶
Every Vulkan struct that starts with sType has a parameterless constructor that sets it from the registry, so
new VkRenderingInfo { … } is correct by default:
var rendering = new VkRenderingInfo { LayerCount = 1, RenderArea = area }; // SType is VkStructureType.RenderingInfo
default(T), stackalloc and arrays of the struct do not run it: set SType yourself there (or loop over the array).
Verification¶
Tests/Apogee.Build.Tests runs the generator on fixture headers and on the Vulkan registry, and checks that the committed
Vulkan bindings are what the generator writes now (it needs clang; the tests skip without it).
Tests/Apogee.Native.Tests checks, for every binding assembly, that every entry point resolves in the native library,
that every exported variable is found, that every struct size equals the one clang computed, and calls into each library. Library assemblies are skipped, with a
message, when the native library is not installed.
Not bound¶
Variadic functions (igText, SDL_Log…): use their non-variadic forms.