cs-binding-generator 1.0.1.dev38__tar.gz → 1.0.1.dev40__tar.gz

{cs_binding_generator-1.0.1.dev38 → cs_binding_generator-1.0.1.dev40}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cs_binding_generator
-Version: 1.0.1.dev38
+Version: 1.0.1.dev40
 Summary: Generate C# bindings from C headers using libclang with modern LibraryImport
 Author-email: Robin 'Ruadeil' Degen <mail@ruadeil.lgbt>
 License-Expression: MIT
@@ -48,7 +48,10 @@ The tool is configured primarily through XML configuration files, providing powe
 - **Automatic Type Mapping**: Intelligently maps C types to C# equivalents
 - **Renaming Support**: Simple and regex-based renaming rules to transform C names to C# conventions
 - **Removal Support**: Filter out unwanted functions, types, or patterns
-- **Macro Constants**: Extract C `#define` constants as C# enums with optional `[Flags]` attribute
+- **Compiler Defines**: Pass `-D` flags to libclang via `<define>` to enable optional API blocks and gate platform-specific code paths during parsing
+- **Flag Enum Marking**: Tag auto-discovered C enums with `[Flags]` via `<flags>`, with exact-name or regex matching
+- **UTF-8 Byte Overloads**: Opt in via `<utf8-byte-overloads/>` to emit a second `byte*`-param partial alongside every `string?`-param `[LibraryImport]`, so callers can hand pre-encoded UTF-8 buffers (u8 literals, pinned spans) to native code without re-encoding through a managed string
+- **Macro Constants**: Extract C `#define` constants as C# enums (numeric mode) or as UTF-8 `ReadOnlySpan<byte>` members (string mode). Object-like and function-like macros are recursively expanded, and C-style casts in macro values are stripped before the numeric check, so chains like `SDL_BUTTON_MASK(SDL_BUTTON_LEFT)` and values like `((SDL_AudioDeviceID) 0xFFFFFFFFu)` resolve cleanly.
 - **String Handling**: Provides both raw pointer and helper string methods for `char*` returns
 - **Struct Generation**: Creates explicit layout structs with proper field offsets
 - **Union Support**: Converts C unions to C# structs with `LayoutKind.Explicit` and field offsets
@@ -449,7 +452,10 @@ CsBindingGenerator/
 ## Limitations
 
 - Variadic functions are not supported (skipped)
-- Complex macros with expressions are not extracted
+- Macro expansion is textual, not a full C preprocessor: token-pasting (`##`),
+  stringizing (`#`), and multi-line backslash continuations are not handled.
+  Multi-token type names inside casts are recognized (`unsigned int`, `long long`),
+  but pointer casts (`(int*)`) are not stripped.
 - Bitfields in structs are not supported
 - Function pointers are mapped to `nint`
 - Requires manual handling of callbacks

{cs_binding_generator-1.0.1.dev38 → cs_binding_generator-1.0.1.dev40}/README.md

@@ -19,7 +19,10 @@ The tool is configured primarily through XML configuration files, providing powe
 - **Automatic Type Mapping**: Intelligently maps C types to C# equivalents
 - **Renaming Support**: Simple and regex-based renaming rules to transform C names to C# conventions
 - **Removal Support**: Filter out unwanted functions, types, or patterns
-- **Macro Constants**: Extract C `#define` constants as C# enums with optional `[Flags]` attribute
+- **Compiler Defines**: Pass `-D` flags to libclang via `<define>` to enable optional API blocks and gate platform-specific code paths during parsing
+- **Flag Enum Marking**: Tag auto-discovered C enums with `[Flags]` via `<flags>`, with exact-name or regex matching
+- **UTF-8 Byte Overloads**: Opt in via `<utf8-byte-overloads/>` to emit a second `byte*`-param partial alongside every `string?`-param `[LibraryImport]`, so callers can hand pre-encoded UTF-8 buffers (u8 literals, pinned spans) to native code without re-encoding through a managed string
+- **Macro Constants**: Extract C `#define` constants as C# enums (numeric mode) or as UTF-8 `ReadOnlySpan<byte>` members (string mode). Object-like and function-like macros are recursively expanded, and C-style casts in macro values are stripped before the numeric check, so chains like `SDL_BUTTON_MASK(SDL_BUTTON_LEFT)` and values like `((SDL_AudioDeviceID) 0xFFFFFFFFu)` resolve cleanly.
 - **String Handling**: Provides both raw pointer and helper string methods for `char*` returns
 - **Struct Generation**: Creates explicit layout structs with proper field offsets
 - **Union Support**: Converts C unions to C# structs with `LayoutKind.Explicit` and field offsets
@@ -420,7 +423,10 @@ CsBindingGenerator/
 ## Limitations
 
 - Variadic functions are not supported (skipped)
-- Complex macros with expressions are not extracted
+- Macro expansion is textual, not a full C preprocessor: token-pasting (`##`),
+  stringizing (`#`), and multi-line backslash continuations are not handled.
+  Multi-token type names inside casts are recognized (`unsigned int`, `long long`),
+  but pointer casts (`(int*)`) are not stripped.
 - Bitfields in structs are not supported
 - Function pointers are mapped to `nint`
 - Requires manual handling of callbacks

{cs_binding_generator-1.0.1.dev38 → cs_binding_generator-1.0.1.dev40}/cs_binding_generator/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.0.1.dev38'
-__version_tuple__ = version_tuple = (1, 0, 1, 'dev38')
+__version__ = version = '1.0.1.dev40'
+__version_tuple__ = version_tuple = (1, 0, 1, 'dev40')
 
-__commit_id__ = commit_id = 'g88b2816f6'
+__commit_id__ = commit_id = 'g7677f88ad'

{cs_binding_generator-1.0.1.dev38 → cs_binding_generator-1.0.1.dev40}/cs_binding_generator/code_generators.py

@@ -12,12 +12,23 @@ from .type_mapper import TypeMapper
 class CodeGenerator:
     """Generates C# code from libclang AST nodes"""
 
-    def __init__(self, type_mapper: TypeMapper, visibility: str = "public", skip_variadic: bool = False):
+    def __init__(
+        self,
+        type_mapper: TypeMapper,
+        visibility: str = "public",
+        skip_variadic: bool = False,
+        utf8_byte_overloads: bool = False,
+    ):
         self.type_mapper = type_mapper
         self.anonymous_enum_counter = 0
         self.visibility = visibility
         self.skip_variadic = skip_variadic
         self.has_variadic_functions = False
+        # When True, generate_function emits a parallel `byte*`-param overload alongside
+        # the primary `[LibraryImport]` for any function whose original signature contains
+        # a `string?` parameter. Lets callers pass pre-encoded UTF-8 buffers without the
+        # managed-string → UTF-8 re-encode round trip.
+        self.utf8_byte_overloads = utf8_byte_overloads
 
     def generate_function(self, cursor, library_name: str) -> str:
         """Generate C# LibraryImport for a function"""
@@ -100,6 +111,40 @@ class CodeGenerator:
             code = f"""    [LibraryImport("{library_name}", EntryPoint = "{original_func_name}", StringMarshalling = StringMarshalling.Utf8)]
     [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
 {return_marshal}    {self.visibility} static partial {result_type} {func_name}({params_str});
+"""
+
+        # Optional byte*-param overload. Emitted only when (a) the opt-in flag is set,
+        # (b) the function isn't variadic, and (c) at least one parameter was mapped to
+        # `string?`. The overload swaps every `string?` param for `byte*`, letting callers
+        # pass pre-encoded UTF-8 buffers (u8 literals, pinned spans) without re-encoding.
+        # The C# compiler picks between the two overloads by argument type at the call site.
+        if self.utf8_byte_overloads and not is_variadic_for_generation:
+            byte_params: list[str] = []
+            has_string_param = False
+            for i, arg in enumerate(cursor.get_arguments()):
+                arg_type = self.type_mapper.map_type(arg.type, is_return_type=False)
+                if arg_type is None:
+                    # If the primary emit accepted these params, the secondary should too.
+                    # Skip silently rather than emit a half-built overload.
+                    byte_params = []
+                    has_string_param = False
+                    break
+                arg_name = arg.spelling or f"param{i}"
+                arg_name = self._escape_keyword(arg_name)
+                if arg_type == "string?":
+                    has_string_param = True
+                    byte_params.append(f"byte* {arg_name}")
+                elif arg_type == "bool":
+                    byte_params.append(f"[MarshalAs(UnmanagedType.I1)] {arg_type} {arg_name}")
+                else:
+                    byte_params.append(f"{arg_type} {arg_name}")
+
+            if has_string_param:
+                byte_params_str = ", ".join(byte_params)
+                code += f"""
+    [LibraryImport("{library_name}", EntryPoint = "{original_func_name}", StringMarshalling = StringMarshalling.Utf8)]
+    [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+{return_marshal}    {self.visibility} static partial {result_type} {func_name}({byte_params_str});
 """
 
         # Add helper function for char* return types (skip for variadic functions)

{cs_binding_generator-1.0.1.dev38 → cs_binding_generator-1.0.1.dev40}/cs_binding_generator/config.py

@@ -20,6 +20,7 @@ class BindingConfig:
     visibility: str = "public"
     global_constants: list[tuple[str, str, str, bool]] = field(default_factory=list)
     global_defines: list[tuple[str, str | None]] = field(default_factory=list)
+    utf8_byte_overloads: bool = False
 
 
 def parse_config_file(config_path):
@@ -84,19 +85,31 @@ def parse_config_file(config_path):
 
         # Get global constants (macros to extract)
         # These are stored as a list of (name, pattern, type, is_flags) tuples
-        # They will be applied to all libraries during processing
+        # They will be applied to all libraries during processing.
+        # The `name` attribute is required for numeric constants groups (which become a
+        # named C# enum) but optional for `type="string"` groups (which emit each macro
+        # as a member of the library's static class with no wrapper type).
         for const in root.findall("constants"):
             const_name = const.get("name")
             const_pattern = const.get("pattern")
-            const_type = const.get("type", "uint")  # Default to uint
-            const_flags = const.get("flags", "false").lower() == "true"  # Default to false
+            const_type = const.get("type", "uint").strip()
+            const_flags = const.get("flags", "false").lower() == "true"
 
-            if not const_name:
-                raise ValueError("Constants element missing 'name' attribute")
             if not const_pattern:
                 raise ValueError("Constants element missing 'pattern' attribute")
+            if const_type != "string" and not const_name:
+                raise ValueError("Constants element missing 'name' attribute")
+
+            config.global_constants.append(
+                ((const_name or "").strip(), const_pattern.strip(), const_type, const_flags)
+            )
 
-            config.global_constants.append((const_name.strip(), const_pattern.strip(), const_type.strip(), const_flags))
+        # Opt-in: for every function that has at least one `string?` parameter (mapped
+        # from a C char* arg), emit a parallel byte*-param overload alongside the primary
+        # P/Invoke. Lets callers pass pre-encoded UTF-8 buffers (u8 literals, pinned spans)
+        # without the round trip through Encoding.UTF8 → marshaller → native.
+        if root.find("utf8-byte-overloads") is not None:
+            config.utf8_byte_overloads = True
 
         for library in root.findall("library"):
             library_name = library.get("name")

{cs_binding_generator-1.0.1.dev38 → cs_binding_generator-1.0.1.dev40}/cs_binding_generator/generator.py

@@ -60,51 +60,293 @@ class CSharpBindingsGenerator:
         self.source_file = None
 
     def _extract_macros_from_file(self, file_path: str, patterns: list[str]) -> dict[str, str]:
-        """Extract #define macros from a header file that match the given patterns
+        """Numeric-only extractor (legacy signature, retained for internal tests).
 
-        Args:
-            file_path: Path to the header file
-            patterns: List of regex patterns to match macro names
+        Forwards to `_extract_typed_macros_from_file` treating every pattern as
+        ``numeric``, and strips the kind from each entry so the return shape stays
+        ``{name: value}``.
+        """
+        typed = [(p, "numeric") for p in patterns]
+        result = self._extract_typed_macros_from_file(file_path, typed)
+        return {name: value for name, (value, _kind) in result.items()}
+
+    def _extract_typed_macros_from_file(
+        self,
+        file_path: str,
+        typed_patterns: list[tuple[str, str]],
+    ) -> dict[str, tuple[str, str]]:
+        """Extract ``#define`` macros from a header, dispatching by pattern kind.
+
+        ``typed_patterns`` is a list of ``(regex, kind)`` pairs where ``kind`` is either
+        ``"string"`` or ``"numeric"``. Each macro is tested against the patterns for its
+        kind:
+
+        - ``"string"``: the macro body must be a single C string literal (``"..."``).
+          No expansion is done — string macros that reference other identifiers are
+          out of scope. The stored value is the literal including the bounding quotes.
+        - ``"numeric"``: the body is expanded against the file's full macro table,
+          C casts are stripped, and the result must pass `_is_numeric_macro_value`.
+
+        Returns a dict ``{name: (value, kind)}`` so callers can route emit decisions
+        (enum vs. UTF-8 property) without re-classifying.
+        """
+        macros: dict[str, tuple[str, str]] = {}
+        table = self._scan_macros(file_path)
+
+        numeric_patterns = [p for p, k in typed_patterns if k != "string"]
+        string_patterns = [p for p, k in typed_patterns if k == "string"]
+
+        for name, (params, body) in table.items():
+            if params is not None:
+                continue  # function-like macros stay in the table only as expansion targets
+
+            wants_numeric = any(re.fullmatch(p, name) for p in numeric_patterns)
+            wants_string = any(re.fullmatch(p, name) for p in string_patterns)
+
+            # Prefer the string check first when the macro body literally looks like a
+            # quoted string — that way `<constants type="string">` doesn't accidentally
+            # lose to a wider `numeric` pattern that happens to also match the name.
+            if wants_string and self._is_string_macro_value(body):
+                macros[name] = (body, "string")
+                continue
+
+            if wants_numeric:
+                value = self._expand_macros(body, table)
+                value = self._strip_c_casts(value)
+
+                # Legacy single-arg cast-macro form `WRAP(value)` (e.g. SDL_UINT64_C(0x123)).
+                # Run AFTER expansion so we only fall back when expansion didn't replace
+                # the wrapper.
+                cast_match = re.match(r'^\w+\((.*)\)$', value)
+                if cast_match:
+                    value = cast_match.group(1).strip()
 
-        Returns:
-            Dict mapping macro names to their values
+                if self._is_numeric_macro_value(value):
+                    macros[name] = (value, "numeric")
+
+        return macros
+
+    @staticmethod
+    def _is_string_macro_value(value: str) -> bool:
+        """True if `value` is a single C string literal (e.g. `"hello"`).
+
+        Backslash escapes are honored so that `"a\"b"` is recognized as one literal,
+        not a quote-balanced pair. Concatenated literals like `"a" "b"` are rejected;
+        we don't try to fuse them.
+        """
+        if len(value) < 2 or value[0] != '"' or value[-1] != '"':
+            return False
+        i = 1
+        end = len(value) - 1
+        while i < end:
+            if value[i] == '\\' and i + 1 < end:
+                i += 2
+            elif value[i] == '"':
+                return False
+            else:
+                i += 1
+        return True
+
+    def _scan_macros(self, file_path: str) -> dict[str, tuple[list[str] | None, str]]:
+        """Pass-1 scan: turn every `#define` in a file into a lookup table.
+
+        Returns a dict from macro name to `(params, body)` where:
+          - object-like macros (`#define NAME body`) have `params=None`
+          - function-like macros (`#define NAME(arg1, arg2) body`) have `params=[...]`
+
+        Bodies are stripped of trailing `/* ... */` comments and trailing commas to
+        match the legacy single-pass behavior. Multi-line continuations (backslash-
+        newline) are not handled — same limitation the previous scanner had.
         """
-        macros = {}
+        # Function-like has to be tried first because its `NAME(` opening would otherwise
+        # be consumed by the object-like `\w+` group and leave `(args) body` as the value.
+        func_re = re.compile(r'^\s*#\s*define\s+(\w+)\(([^)]*)\)\s+(.+?)(?://.*)?$')
+        obj_re = re.compile(r'^\s*#\s*define\s+(\w+)\s+(.+?)(?://.*)?$')
+        table: dict[str, tuple[list[str] | None, str]] = {}
 
         try:
             with open(file_path, 'r', encoding='utf-8') as f:
                 for line in f:
-                    # Look for #define directives with simple numeric values
-                    # Pattern: #define NAME VALUE
-                    match = re.match(r'^\s*#\s*define\s+(\w+)\s+(.+?)(?://.*)?$', line)
-                    if match:
-                        macro_name = match.group(1)
-                        macro_value = match.group(2).strip()
-
-                        # Strip C-style comments (/**< ... */ or /* ... */)
-                        macro_value = re.sub(r'/\*.*?\*/', '', macro_value).strip()
-
-                        # Strip trailing commas
-                        macro_value = macro_value.rstrip(',')
-
-                        # Strip C cast macros like SDL_UINT64_C(0x...) and extract the value
-                        cast_match = re.match(r'^\w+\((.*)\)$', macro_value)
-                        if cast_match:
-                            macro_value = cast_match.group(1).strip()
-
-                        # Only capture macros with numeric-looking values or simple expressions
-                        # Skip macros that reference other identifiers (which would need evaluation)
-                        if self._is_numeric_macro_value(macro_value):
-                            # Check if this macro matches any of the patterns
-                            for pattern in patterns:
-                                if re.fullmatch(pattern, macro_name):
-                                    macros[macro_name] = macro_value
-                                    break
-        except Exception as e:
-            # If we can't read the file, just skip it
+                    fm = func_re.match(line)
+                    if fm:
+                        name = fm.group(1)
+                        params = [p.strip() for p in fm.group(2).split(',') if p.strip()]
+                        body = self._clean_macro_body(fm.group(3))
+                        table[name] = (params, body)
+                        continue
+                    om = obj_re.match(line)
+                    if om:
+                        name = om.group(1)
+                        body = self._clean_macro_body(om.group(2))
+                        table[name] = (None, body)
+        except Exception:
             pass
 
-        return macros
+        return table
+
+    @staticmethod
+    def _clean_macro_body(body: str) -> str:
+        body = body.strip()
+        body = re.sub(r'/\*.*?\*/', '', body).strip()
+        return body.rstrip(',')
+
+    def _expand_macros(self, value: str, macros: dict, max_depth: int = 8) -> str:
+        """Iteratively substitute identifier and function-call references in `value`
+        until the value stops changing or we hit `max_depth`.
+
+        The depth cap is a hard stop against self-referential macros (`#define FOO FOO`)
+        and mutually-referential pairs; we'd rather return a partially-expanded value the
+        numeric check rejects than hang.
+        """
+        for _ in range(max_depth):
+            new_value = self._expand_once(value, macros)
+            if new_value == value:
+                return value
+            value = new_value
+        return value
+
+    def _expand_once(self, value: str, macros: dict) -> str:
+        """One substitution pass over `value`.
+
+        Walks the string left-to-right. When we hit an identifier, decide:
+        - if it's followed by `(`, treat it as a function-like macro call and substitute
+          the body with the args bound to the parameter names;
+        - otherwise treat it as an object-like macro reference and substitute its body.
+
+        Identifiers inside `"..."` string literals are skipped so that string-valued
+        macros aren't corrupted by accidental substitution.
+        """
+        ident_re = re.compile(r'[A-Za-z_]\w*')
+        out: list[str] = []
+        i = 0
+        n = len(value)
+
+        while i < n:
+            ch = value[i]
+
+            if ch == '"':
+                # Copy a string literal verbatim, honoring backslash escapes so that an
+                # escaped `\"` doesn't terminate the string prematurely.
+                j = i + 1
+                while j < n:
+                    if value[j] == '\\' and j + 1 < n:
+                        j += 2
+                    elif value[j] == '"':
+                        j += 1
+                        break
+                    else:
+                        j += 1
+                out.append(value[i:j])
+                i = j
+                continue
+
+            if ch.isalpha() or ch == '_':
+                m = ident_re.match(value, i)
+                assert m is not None  # the leading-char check above guarantees this
+                name = m.group(0)
+                end = i + len(name)
+
+                if end < n and value[end] == '(':
+                    # Possible function-like call.
+                    close = self._find_matching_paren(value, end)
+                    if close is not None and name in macros and macros[name][0] is not None:
+                        params, body = macros[name]
+                        args = self._split_macro_args(value[end + 1:close])
+                        if len(args) == len(params):
+                            out.append(self._substitute_params(body, params, args))
+                            i = close + 1
+                            continue
+                    # Not a known function-like macro (or arity mismatch): leave it alone.
+                    out.append(name)
+                    i = end
+                    continue
+
+                # Bare identifier.
+                if name in macros and macros[name][0] is None:
+                    out.append(macros[name][1])
+                else:
+                    out.append(name)
+                i = end
+            else:
+                out.append(ch)
+                i += 1
+
+        return ''.join(out)
+
+    @staticmethod
+    def _find_matching_paren(s: str, open_idx: int) -> int | None:
+        """Return the index of the `)` that closes the `(` at `open_idx`, or None
+        if the parens never balance."""
+        depth = 0
+        for i in range(open_idx, len(s)):
+            if s[i] == '(':
+                depth += 1
+            elif s[i] == ')':
+                depth -= 1
+                if depth == 0:
+                    return i
+        return None
+
+    @staticmethod
+    def _split_macro_args(args_str: str) -> list[str]:
+        """Split a comma-separated function-like macro argument list, respecting paren
+        depth so that `(a, b)` inside an argument is not split into two args."""
+        if args_str.strip() == '':
+            return []
+        args: list[str] = []
+        buf: list[str] = []
+        depth = 0
+        for ch in args_str:
+            if ch == ',' and depth == 0:
+                args.append(''.join(buf).strip())
+                buf = []
+            else:
+                if ch == '(':
+                    depth += 1
+                elif ch == ')':
+                    depth -= 1
+                buf.append(ch)
+        args.append(''.join(buf).strip())
+        return args
+
+    @staticmethod
+    def _substitute_params(body: str, params: list[str], args: list[str]) -> str:
+        """Replace every whole-word occurrence of each parameter name in `body` with the
+        corresponding argument text. Identifiers inside string literals are not skipped
+        here because function-like macro bodies that contain strings AND reference params
+        in them are vanishingly rare in C and unsupported."""
+        mapping = dict(zip(params, args))
+
+        def repl(m: re.Match) -> str:
+            name = m.group(0)
+            return mapping[name] if name in mapping else name
+
+        return re.sub(r'\b[A-Za-z_]\w*\b', repl, body)
+
+    def _strip_c_casts(self, value: str) -> str:
+        """Strip C-style casts `(IDENT)` from a macro value when they sit in front of a
+        numeric token.
+
+        The lookahead is what makes this safe: we only remove `(name)` when the next
+        non-space character is a digit, opening paren, minus, or bitwise NOT — i.e. the
+        start of a numeric expression that the cast is converting. Parens around a bare
+        identifier (e.g. `(x)+1`) are left alone, and parens around a number (e.g. `(1)`)
+        are not casts so the leading-letter requirement on the identifier skips them.
+        """
+        # Match a `(IDENT)` or `(IDENT IDENT ...)` cast where each token is whitespace-
+        # separated. Covers `(uint32_t)`, `(unsigned int)`, `(long long)`, etc. We do not
+        # try to handle pointer casts (`(int*)`) — those contain `*` and the numeric check
+        # would reject the surrounding expression anyway.
+        cast_pattern = re.compile(
+            r'\(\s*[A-Za-z_]\w*(?:\s+[A-Za-z_]\w*)*\s*\)\s*(?=[\d(\-~])'
+        )
+        # Loop until stable: nested casts like `((Foo)(Bar)0)` need a couple of passes.
+        prev = None
+        result = value
+        while prev != result:
+            prev = result
+            result = cast_pattern.sub('', result)
+        return result
 
     def _is_numeric_macro_value(self, value: str) -> bool:
         """Check if a macro value looks numeric (number, cast, or simple expression)
@@ -537,6 +779,7 @@ class CSharpBindingsGenerator:
         visibility: str = "public",
         global_constants: Optional[list[tuple[str, str, str, bool]]] = None,
         global_defines: Optional[list[tuple[str, Optional[str]]]] = None,
+        utf8_byte_overloads: bool = False,
     ) -> dict[str, str]:
         """Generate C# bindings from C header file(s)
 
@@ -556,8 +799,10 @@ class CSharpBindingsGenerator:
         # Store visibility setting
         self.visibility = visibility
 
-        # Initialize code generator with visibility and skip_variadic flag
-        self.code_generator = CodeGenerator(self.type_mapper, visibility, skip_variadic)
+        # Initialize code generator with visibility, skip_variadic, and byte-overload flag
+        self.code_generator = CodeGenerator(
+            self.type_mapper, visibility, skip_variadic, utf8_byte_overloads
+        )
 
         # Store library class names
         self.library_class_names = library_class_names or {}
@@ -670,10 +915,13 @@ class CSharpBindingsGenerator:
                 if library_name not in self.captured_macros:
                     self.captured_macros[library_name] = {}
 
-                # Collect all patterns from global constants
-                patterns = []
+                # Tag each pattern with its emission kind so the per-file scanner can
+                # filter accordingly. Anything other than "string" routes to the numeric
+                # path (existing behavior).
+                typed_patterns: list[tuple[str, str]] = []
                 for const_name, const_pattern, const_type, const_flags in self.global_constants:
-                    patterns.append(const_pattern)
+                    kind = "string" if const_type == "string" else "numeric"
+                    typed_patterns.append((const_pattern, kind))
 
                 # Extract macros from all files in the translation unit (not just the main header)
                 # This includes all #included files, which is where macros like SDL_WINDOW_* live
@@ -685,13 +933,13 @@ class CSharpBindingsGenerator:
                             files_set.add(file_path)
                     for child in cursor.get_children():
                         collect_files(child, files_set)
-                
+
                 all_files = set()
                 collect_files(tu.cursor, all_files)
-                
+
                 # Extract macros from all non-system files
                 for file_path in all_files:
-                    file_macros = self._extract_macros_from_file(file_path, patterns)
+                    file_macros = self._extract_typed_macros_from_file(file_path, typed_patterns)
                     self.captured_macros[library_name].update(file_macros)
 
                 if self.captured_macros[library_name]:
@@ -737,36 +985,65 @@ class CSharpBindingsGenerator:
 """
                 self._add_to_library_collection(self.generated_enums, library, code)
 
-        # Generate enums from captured macros using global constants
+        # Generate enums or UTF-8 string members from captured macros using global constants
         for library_name in self.captured_macros:
             for const_name, const_pattern, const_type, const_flags in self.global_constants:
-                # Get all macros matching this pattern
-                matching_macros = {}
-                for macro_name, macro_value in self.captured_macros[library_name].items():
-                    if re.fullmatch(const_pattern, macro_name):
-                        matching_macros[macro_name] = macro_value
-
-                if matching_macros:
-                    # Apply rename rules to the enum name and member names
-                    enum_name = self.type_mapper.apply_rename(const_name)
-
-                    # Build enum members with renamed names
-                    members = []
-                    for macro_name, macro_value in sorted(matching_macros.items()):
+                wants_string = const_type == "string"
+
+                # Get all macros matching this pattern, filtering by kind so that
+                # a numeric constants group can't accidentally pick up a string macro
+                # (or vice-versa) when their name patterns overlap.
+                matching_macros: dict[str, str] = {}
+                for macro_name, (macro_value, kind) in self.captured_macros[library_name].items():
+                    if not re.fullmatch(const_pattern, macro_name):
+                        continue
+                    if wants_string and kind != "string":
+                        continue
+                    if not wants_string and kind != "numeric":
+                        continue
+                    matching_macros[macro_name] = macro_value
+
+                if not matching_macros:
+                    continue
+
+                if wants_string:
+                    # Each macro lands as a ReadOnlySpan<byte> member directly on the
+                    # library's static class. We use the fully-qualified type so we don't
+                    # need to add `using System;` to every generated file.
+                    for macro_name, raw_string in sorted(matching_macros.items()):
                         renamed_member = self.type_mapper.apply_rename(macro_name)
-                        members.append(f"    {renamed_member} = unchecked(({const_type})({macro_value})),")
+                        prop = (
+                            f"    {self.visibility} static System.ReadOnlySpan<byte> "
+                            f"{renamed_member} => {raw_string}u8;\n"
+                        )
+                        self._add_to_library_collection(
+                            self.generated_functions, library_name, prop
+                        )
+                    continue
+
+                # Numeric (enum) path — unchanged from before.
+                # Apply rename rules to the enum name and member names
+                enum_name = self.type_mapper.apply_rename(const_name)
+
+                # Build enum members with renamed names
+                members = []
+                for macro_name, macro_value in sorted(matching_macros.items()):
+                    renamed_member = self.type_mapper.apply_rename(macro_name)
+                    members.append(
+                        f"    {renamed_member} = unchecked(({const_type})({macro_value})),"
+                    )
 
-                    members_str = "\n".join(members)
+                members_str = "\n".join(members)
 
-                    # Generate enum with specified type and optional [Flags] attribute
-                    flags_attr = "[Flags]\n" if const_flags else ""
-                    type_clause = f" : {const_type}" if const_type != "int" else ""
-                    code = f"""{flags_attr}{self.visibility} enum {enum_name}{type_clause}
+                # Generate enum with specified type and optional [Flags] attribute
+                flags_attr = "[Flags]\n" if const_flags else ""
+                type_clause = f" : {const_type}" if const_type != "int" else ""
+                code = f"""{flags_attr}{self.visibility} enum {enum_name}{type_clause}
 {{
 {members_str}
 }}
 """
-                    self._add_to_library_collection(self.generated_enums, library_name, code)
+                self._add_to_library_collection(self.generated_enums, library_name, code)
 
         return self._generate_multi_file_output(output)