Add C struct & inline methods bindings for builtins in godot/_hazmat/gdapi.pxd

Author: touilleMan

scripts/extension_api_parser/builtins.py

@@ -1,9 +1,9 @@
 import enum
-from typing import Dict, Optional, List, Tuple
+from typing import Dict, Optional, List
 from dataclasses import dataclass
 from string import ascii_uppercase
 
-from .utils import correct_name, correct_type_name, assert_api_consistency
+from .utils import correct_name, assert_api_consistency
 from .type import TypeInUse, ValueInUse
 
 
@@ -213,12 +213,12 @@ class BuiltinMethodSpec:
     def parse(cls, item: dict) -> "BuiltinMethodSpec":
         item.setdefault("original_name", item["name"])
         item.setdefault("arguments", [])
-        item.setdefault("return_type", None)
+        item.setdefault("return_type", "Nil")
         assert_api_consistency(cls, item)
         return cls(
             name=correct_name(item["name"]),
             original_name=item["original_name"],
-            return_type=TypeInUse(item["return_type"]) if item["return_type"] else None,
+            return_type=TypeInUse(item["return_type"]),
             is_vararg=item["is_vararg"],
             is_const=item["is_const"],
             is_static=item["is_static"],
@@ -249,9 +249,12 @@ def parse(cls, item: dict) -> "BuiltinEnumSpec":
 
 @dataclass
 class BuiltinSpec:
+    # Name as it is in `extension_api.json`
+    original_name: str
+    # Name used for the binding (e.g. `from godot import Vector2`)
     name: str
+    # Name used for the C structure binding (e.g. `from godot.hazmat.gdapi cimport Vector2`)
     c_struct_name: str
-    original_name: str
     is_scalar: bool
     size: int
     indexing_return_type: Optional[str]
@@ -288,7 +291,14 @@ def parse(cls, item: dict) -> "BuiltinSpec":
             snake += c
         item["variant_type_name"] = f"GDNATIVE_VARIANT_TYPE_{snake.upper()}"
         item.setdefault("original_name", item["name"])
-        item.setdefault("c_struct_name", f"C{item['original_name']}")
+        # Special case for the String type, this is because `String` is too
+        # broad of a name (it's easy to mix with Python's regular `str`)
+        # On top of that `str` and Godot `String` are two totally separated
+        # string types that require conversions to work together, so it's better
+        # to make extra clear they are not the same types !
+        if item["name"] == "String":
+            item["name"] = "GDString"
+        item.setdefault("c_struct_name", item["name"])
         item.setdefault("indexing_return_type", None)
         item.setdefault("methods", [])
         item.setdefault("members", [])
@@ -299,7 +309,8 @@ def parse(cls, item: dict) -> "BuiltinSpec":
 
         return cls(
             original_name=item["original_name"],
-            name=correct_type_name(item["name"]),
+            # name=correct_type_name(item["name"]),
+            name=item["name"],
             c_struct_name=item["c_struct_name"],
             is_scalar=item["is_scalar"],
             size=item["size"],

scripts/extension_api_parser/type.py

@@ -1,4 +1,4 @@
-from typing import TYPE_CHECKING, Dict, Iterable, Union, Optional
+from typing import TYPE_CHECKING, Dict, Iterable
 from dataclasses import dataclass, replace
 
 
@@ -8,6 +8,10 @@
     from .builtins import BuiltinSpec
 
 
+# Type alias
+TypeDBEntry = str
+
+
 # We devide types into three categories:
 # - scalars (native types already existing in C/Cython, e.g. float, int32 etc.)
 # - builtins
@@ -30,11 +34,13 @@ class TypeSpec:
     is_object: bool = False
     # Type is a Godot builtin (e.g. Vector2)
     is_builtin: bool = False
+    # Nil type (aka None, or NULL) is very special ;-)
+    is_nil: bool = False
     # Type is a scalar (e.g. int, float) or void
     is_scalar: bool = False
     # Type doesn't use the heap (hence no need for freeing it)
     is_stack_only: bool = False
-    # # Type is an enum (e.g. godot_error, Camera::KeepAspect)
+    # Type is an enum (e.g. godot_error, Camera::KeepAspect)
     is_enum: bool = False
     # e.g. `GDNATIVE_VARIANT_TYPE_BOOL`
     # Default to an invalid value so that we detect incorrect use during Cython compilation
@@ -54,11 +60,58 @@ def __post_init__(self):
             assert not self.is_scalar
 
 
-# TODO: put variant_type_name into TypeSpec
+# `Nil` is a special case, it is only needed for `BuiltinOperatorSpec.right_type`
+# and in `ValueInUse`. But it meaning can differ:
+# - `BuiltinOperatorSpec.right_type`: `Nil` represents the absence of value
+# - `ValueInUse`: `Nil` represents a singleton value (like `None` in Python)
+# So the template code is expected to use the `is_nil` attribute and do ad-hoc
+# code according to it need instead of relying on py/c/cy_type
+
+
+class NilTypeSpec(TypeSpec):
+    def __init__(self):
+        # Cannot use super().__init__() given py/cy/c_type are read-only !
+        self.__dict__ = {
+            # Default values from parent
+            **{f.name: f.default for f in super().__dataclass_fields__.values()},
+            # Our config values
+            **{
+                "size": 0,
+                "gdapi_type": "Nil",
+                "is_scalar": True,
+                "is_stack_only": True,
+                "is_nil": True,
+                "variant_type_name": "GDNATIVE_VARIANT_TYPE_NIL",
+            },
+        }
+
+    def __repr__(self):
+        return f"<NilTypeSpec {id(self)}>"
+
+    @property
+    def py_type(self):
+        raise RuntimeError(
+            "Nil type ! Should handle this by hand with a if condition on `<my_type>.is_nil`"
+        )
+
+    @property
+    def cy_type(self):
+        raise RuntimeError(
+            "Nil type ! Should handle this by hand with a if condition on `<my_type>.is_nil`"
+        )
+
+    @property
+    def c_type(self):
+        raise RuntimeError(
+            "Nil type ! Should handle this by hand with a if condition on `<my_type>.is_nil`"
+        )
+
+
 # TODO: Object type should match GDNATIVE_VARIANT_TYPE_OBJECT
 
 
-TYPES_DB: Dict[str, TypeSpec] = {
+TYPES_DB: Dict[TypeDBEntry, TypeSpec] = {
+    "Nil": NilTypeSpec(),
     # Types marked as `meta` are used in the classes method args/return types
     "meta:int8": TypeSpec(
         size=1,
@@ -179,7 +232,7 @@ def register_variant_in_types_db(variant_size: int) -> None:
     TYPES_DB["Variant"] = TypeSpec(
         size=variant_size,
         gdapi_type="Variant",
-        c_type="CVariant",
+        c_type="Variant",
         cy_type="object",
         py_type="GDAny",
         is_builtin=True,
@@ -189,9 +242,10 @@ def register_variant_in_types_db(variant_size: int) -> None:
 def register_builtins_in_types_db(builtins: Iterable["BuiltinSpec"]) -> None:
     for spec in builtins:
         if spec.name == "Nil":
-            # `Nil` is a special case, it is only needed for
-            # `BuiltinOperatorSpec.right_type` and in `ValueInUse`.
-            # So better skip it and use ad-hoc workaround instead.
+            # `Nil` is already part of `TYPES_DB`
+            nil_spec = TYPES_DB["Nil"]
+            assert nil_spec.gdapi_type == spec.original_name  # Sanity check
+            assert nil_spec.variant_type_name == spec.variant_type_name  # Sanity check
             continue
         assert spec.size is not None
         if spec.name == "bool":
@@ -224,7 +278,7 @@ def register_builtins_in_types_db(builtins: Iterable["BuiltinSpec"]) -> None:
                 size=spec.size,
                 gdapi_type=spec.original_name,
                 py_type=spec.name,
-                c_type=f"C{spec.name}",
+                c_type=spec.c_struct_name,
                 cy_type=spec.name,
                 is_stack_only=not spec.has_destructor,
                 is_builtin=True,
@@ -279,7 +333,7 @@ def register_global_enums_in_types_db(enums: Iterable["GlobalEnumSpec"]) -> None
 
 @dataclass(repr=False)
 class TypeInUse:
-    type_name: str
+    type_name: TypeDBEntry
 
     def __repr__(self) -> str:
         try:

src/godot/_builtins.pyi.j2

@@ -30,7 +30,7 @@ class {{spec.name}}:
     # Methods
 {% endif %}
 {% for m in spec.methods %}
-    def {{m.name}}(self{% for a in m.arguments %}, {{ render_arg(a) }}{% endfor %}) -> {{ m.return_type.py_type if m.return_type is not none else "None" }}: ...
+    def {{m.name}}(self{% for a in m.arguments %}, {{ render_arg(a) }}{% endfor %}) -> {{ "None" if m.return_type.is_nil else m.return_type.py_type }}: ...
 {% endfor %}
 {% if spec.constants %}
     # Constants

src/godot/_builtins_pyx/class.j2

@@ -84,37 +84,7 @@ cdef class {{ spec.name }}:
         {{ arg.name }},
 {% endfor %}
     ):
-        # TODO
-        # cdef GDNativePtrBuiltInMethod ptrmethod = pythonscript_gdapi.variant_get_ptr_builtin_method(
-        #     {{ spec.variant_type_name }},
-        #     "{{ m.original_name }}",
-        #     {{ m.hash }}
-        # )
-        # if ptrmethod == NULL:
-        #     raise RuntimeError("Cannot load method from Godot")
-
-{% if m.arguments | length == 0 %}
-# {%     if m.return_type %}
-#         # TODO
-#         # cdef {{ m.return_type.cy_type }} ret = {{ m.return_type.cy_type }}.__new__()
-# {%         set retval_as_arg = "NULL" %}
-# {%     else %}
-# {%         set retval_as_arg = "NULL" %}
-# {%     endif %}
-
-#         with nogil:
-#             ptrmethod(
-#                 self._ptr,
-#                 NULL, # args
-#                 # return
-#                 0, # args_count
-#             )
-
-        return
-{% else %}
         raise NotImplemented
-{% endif %}
-
 {% endfor %}
 
 {%- endmacro %}

src/godot/_hazmat/gdapi.pxd.j2

@@ -1,5 +1,5 @@
 from libc.stdint cimport *
-from godot._hazmat.gdnative_interface cimport GDNativeInterface
+from godot._hazmat.gdnative_interface cimport *
 
 
 cdef extern from * nogil:
@@ -20,20 +20,76 @@ cdef extern from * nogil:
     cdef const GDNativeInterface *pythonscript_gdapi
 
 
-cdef struct Variant:
-    char _gd_data[{{ api.variant_size }}]
+# Following stuff are all the Godot builtins exposed as:
+# - a C structure (with typed fields if the structure is not opaque)
+# - the function pointer of all the builtin's constructors/destructors/methods/operators
+# - Inlines functions for a nicer way to call the constructors/destructors/methods/operators
+
 
+cdef struct Variant:
+    char _gd_opaque[{{ api.variant_size }}]
 
 {% for spec in api["builtins"] if not spec.is_scalar %}
+
+##############################################################################
+#{{ "{:^76}".format(spec.name) }}#
+##############################################################################
+
+{#
+    Builtins C struct
+#}
 cdef struct {{ spec.c_struct_name }}:
 {%   set c_struct_members = spec.c_struct_members %}
 {%   if c_struct_members %}
 {%     for member in c_struct_members %}
     {{ member.type.c_type }} {{ member.name }}
 {%     endfor %}
 {%   else %}
-    char _gd_data[{{ spec.size }}]
+    char _gd_opaque[{{ spec.size }}]
 {%   endif %}
 
+{#
+    Builtins C method call
+#}
+{%   for c in spec.constructors %}
+cdef GDNativePtrConstructor __{{ spec.name }}_constructor_{{ c.index }}
+{%   endfor %}
+{%   if spec.has_destructor %}
+cdef GDNativePtrDestructor __{{ spec.name }}_destructor
+{%   endif %}
+{%   for m in spec.methods %}
+cdef GDNativePtrBuiltInMethod __{{ spec.name }}_meth_{{ m.name }}
+{%   endfor %}
+{%   for o in spec.operators %}
+cdef GDNativePtrOperatorEvaluator __{{ spec.name }}_op_{{ o.name }}
+{%   endfor %}
+{#
+    Builtins C method call
+#}
+{%   for meth in spec.methods if meth.offest is not none %}
 
+cdef inline {{ "void" if meth.return_type.is_nil else meth.return_type.c_type }} {{ spec.name | lower }}_{{ meth.name }}(
+    {{ spec.name }} *self,
+{%     for arg in meth.arguments %}
+    {{ arg.type.c_type }}* {{ arg.name }},
+{%     endfor %}
+):
+    cdef GDNativeTypePtr[{{ meth.arguments | length }}] p_args = [{% for arg in meth.arguments %}{{ arg.name }},{% endfor %}]
+{%     if not meth.return_type.is_nil %}
+    cdef {{ meth.return_type.c_type }} r_return
+{%     endif %}
+    __{{ spec.name }}_meth_{{ meth.name }}(
+        {# GDNativeTypePtr p_base #}
+        self,
+        {# const GDNativeTypePtr *p_args #}
+        p_args,
+        {# GDNativeTypePtr r_return #}
+        {{ "NULL" if meth.return_type.is_nil else "&r_return" }},
+        {# int p_argument_count #}
+        {{ meth.arguments | length }}
+    )
+{%     if not meth.return_type.is_nil %}
+    return r_return
+{%     endif %}
+{%   endfor %}
 {% endfor %}

src/godot/_hazmat/gdapi_ptrs.pxi.j2

@@ -26,7 +26,7 @@ cdef GDNativePtrDestructor __{{ spec.name }}_destructor = pythonscript_gdapi.var
 {%   endif %}
 
 {%   for m in spec.methods %}
-cdef GDNativeMethodBindPtr __{{ spec.name }}_meth_{{ m.name }} = pythonscript_gdapi.variant_get_ptr_builtin_method(
+cdef GDNativePtrBuiltInMethod __{{ spec.name }}_meth_{{ m.name }} = pythonscript_gdapi.variant_get_ptr_builtin_method(
     {{ spec.variant_type_name }}, "{{ m.original_name }}", {{ m.hash }}
 )
 {%   endfor %}