+
+ +
+

IDL — Interface Definition Language

+

bgfx uses a custom Interface Definition Language (IDL) to define its entire public API in a single +source-of-truth file: scripts/bgfx.idl. From this file, code generators produce the C99 API, +C++ API, language bindings, and documentation — ensuring that all representations stay in sync.

+

For additional background and motivation, see the blog post: +IDL — Interface Definition Language.

+
+

Purpose

+

The IDL serves several goals:

+
    +

  • Single source of truth — The API (types, functions, flags, enums, structs, handles) is +declared once in bgfx.idl. All generated outputs derive from this file.

    • +

  • Multi-language bindings — Code generators read the IDL and produce bindings for C99, C#, D, +Zig, Beef, C3, and potentially other languages.

    • +

  • Documentation generation — The docs-rst.lua generator produces reStructuredText API +reference documentation from the IDL.

    • +

  • Consistency — Changes to the API only need to be made in one place. The code generators +ensure that all bindings and documentation are updated automatically.

    • +
+
+
+

File overview

+

All IDL-related files live under scripts/:

+
+
bgfx.idl

The IDL source file. Contains all type definitions, function declarations, flag/enum +definitions, struct layouts, handle types, documentation comments, and the section hierarchy +for the generated docs.

+
+
idl.lua

The IDL parser/runtime. Sets up the Lua environment that bgfx.idl executes in. Provides +the DSL keywords (typedef, enum, flag, struct, handle, func, +funcptr, section, version, etc.) as Lua metatable-driven constructors.

+
+
codegen.lua

Shared code generation utilities. Reads the parsed IDL, resolves types, converts between +naming conventions (CamelCase ↔ underscore_case), and provides template expansion for +function signatures.

+
+
bgfx-codegen.lua

The main code generator. Reads the IDL via codegen.lua and produces the C99 header, +C++ header, C99-to-C++ bridge implementation, and the internal function ID tables.

+
+
bindings-*.lua

Per-language binding generators (bindings-cs.lua, bindings-d.lua, bindings-zig.lua, +bindings-bf.lua, bindings-c3.lua). Each reads the IDL and outputs the API in the +target language’s syntax and conventions.

+
+
docs-rst.lua

Generates reStructuredText API reference documentation (docs/bgfx.rst) from the IDL.

+
+
+
+
+

Running the code generators

+

The code generators are invoked via the makefile at the repository root:

+
make idl
+
+
+

This runs the Lua scripts that regenerate all C/C++ headers, language bindings, and documentation +from scripts/bgfx.idl.

+
+
+

IDL syntax reference

+

The IDL file is valid Lua, executed in a special environment that provides the DSL keywords. +Comments prefixed with --- become documentation comments attached to the next declaration.

+
+

version

+

Declares the API version number:

+
version(140)
+
+
+
+
+

typedef

+

Declares a type alias. These map IDL type names to their C/C++ equivalents:

+
typedef "uint32_t"
+typedef "ViewId"
+typedef "CallbackI" { cname = "callback_interface" }
+
+
+

The optional table provides attributes. cname overrides the C binding name.

+
+
+

handle

+

Declares an opaque handle type. Handles are type-safe 16-bit integers used to reference GPU +resources:

+
handle "TextureHandle"
+handle "VertexBufferHandle"
+
+
+
+
+

enum

+

Declares an enumeration. Each member can have a --- documentation comment:

+
enum.TextureFormat { comment = "Texture formats:", section = "Textures" }
+    .BC1       --- DXT1 R5G6B5A1.
+    .BC2       --- DXT3 R5G6B5A4.
+    .Unknown   --- Compressed formats above.
+    ()
+
+
+

The () sentinel marks the end of the enum (generates a Count member). The section +attribute controls where this type appears in the generated documentation hierarchy.

+
+
+

flag

+

Declares a bitfield flag type. Similar to enum, but members represent individual bits:

+
flag.StateWrite { bits = 64, base = 1, section = "State Flags", label = "Write" }
+    .R     --- Enable R write.
+    .G     --- Enable G write.
+    .B     --- Enable B write.
+    .A     --- Enable alpha write.
+    .Z (39) --- Enable depth write.
+    .Rgb  { "R",   "G", "B" }  --- Enable RGB write.
+    .Mask { "Rgb", "A", "Z" }  --- Write all channels mask.
+
+
+

Attributes:

+
    +

  • bits — Total bit width (32 or 64).

    • +

  • shift — Bit offset where this flag group starts.

    • +

  • range — Number of bits in this group.

    • +

  • base — Starting value for auto-numbering.

    • +

  • section — Documentation section.

    • +

  • label — Display label for documentation grouping.

    • +
+

A member with a number in parentheses (e.g. .Z (39)) sets an explicit bit position. Members +with a table of names (e.g. .Rgb { "R", "G", "B" }) define combined masks.

+
+
+

struct

+

Declares a data structure with typed fields:

+
struct.Init { ctor, section = "Initialization and Shutdown" }
+    .type             "RendererType::Enum" --- Select rendering backend.
+    .vendorId         "uint16_t"           --- Vendor PCI ID. See: `BGFX_PCI_ID_*`.
+    .deviceId         "uint16_t"           --- Device ID.
+    .capabilities     "uint64_t"           --- Capabilities initialization mask.
+    .debug            "bool"               --- Enable device for debugging.
+    .profile          "bool"               --- Enable device for profiling.
+
+
+

Attributes:

+
    +

  • ctor — Generate a constructor with default values.

    • +

  • namespace — Nest this struct inside another (e.g. namespace = "Caps" produces +Caps::Limits).

    • +

  • section — Documentation section.

    • +
+
+
+

func

+

Declares a function. The first string is the return type, followed by named parameters:

+
--- Advance to next frame.
+func.frame { section = "Frame" }
+    "uint32_t"                      --- Current frame number.
+    .flags "uint8_t"                --- Frame flags.
+     { default = "BGFX_FRAME_NONE" }
+
+
+

Attributes:

+
    +

  • section — Documentation section.

    • +

  • const — Mark as a const method (for class member functions).

    • +

  • conly — Only emit in the C99 API, not in C++.

    • +

  • cpponly — Only emit in the C++ API, not in C99.

    • +

  • cppinline — Provide an inline C++ implementation string.

    • +
+

Parameters can have:

+
    +

  • { default = "value" } — Default argument value.

    • +

  • { out } — Output parameter.

    • +

  • { inout } — Input/output parameter.

    • +
+
+
+

funcptr

+

Declares a function pointer type:

+
funcptr.ReleaseFn
+    "void"
+    .ptr      "void*" --- Pointer to allocated data.
+    .userData "void*" --- User defined data if needed.
+
+
+
+
+

section

+

Declares a documentation section for organizing the generated API reference. Sections form a +hierarchy based on their level (0 = top-level heading, 1 = chapter, 2+ = subsections):

+
section("API Reference", 0)
+section("General", 1)
+section("Initialization and Shutdown", 2)
+
+
+

Types and functions reference their section via the section attribute. The documentation +generator (docs-rst.lua) uses the section tree to organize the output.

+
+
+

Documentation comments

+

Lines starting with --- before a declaration become documentation comments. These are emitted +as Doxygen-style comments in the C/C++ headers and as descriptions in the generated docs:

+
--- Render frame.
+---
+--- @attention `bgfx::renderFrame` is a blocking call.
+---
+--- @warning This call should only be used on platforms that don't
+---   allow creating a separate rendering thread.
+---
+func.renderFrame { section = "Platform specific" }
+    "RenderFrame::Enum"
+    .msecs "int32_t"
+    { default = -1 }
+
+
+

Supported Doxygen tags in comments: @attention, @warning, @remarks, @param, +@returns.

+
+
+
+

Adding a new API function

+

To add a new function to the bgfx API:

+
    +

  1. Add the function declaration in scripts/bgfx.idl with the appropriate section attribute +and --- documentation comments.

    2. +

  2. Run make idl to regenerate all headers, bindings, and documentation.

    3. +

  3. Implement the function in src/bgfx.cpp (and the renderer backends if needed).

    4. +

  4. Verify the generated output in include/bgfx/bgfx.h, include/bgfx/c99/bgfx.h, and the +binding files under bindings/.

    5. +
+
+
+ + +
+