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 <https://bkaradzic.github.io/posts/idl/>__.

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:

.. code-block:: bash

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:

.. code-block:: lua

    version(140)

typedef

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

.. code-block:: lua

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:

.. code-block:: lua

    handle "TextureHandle"
    handle "VertexBufferHandle"

enum
~~~~

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

.. code-block:: lua

    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:

.. code-block:: lua

    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:

.. code-block:: lua

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:

.. code-block:: lua

    --- 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:

.. code-block:: lua

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):

.. code-block:: lua

    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:

.. code-block:: lua

--- 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:

Add the function declaration in scripts/bgfx.idl with the appropriate section attribute and --- documentation comments.
Run make idl to regenerate all headers, bindings, and documentation.
Implement the function in src/bgfx.cpp (and the renderer backends if needed).
Verify the generated output in include/bgfx/bgfx.h, include/bgfx/c99/bgfx.h, and the binding files under bindings/.