Add a category named function in dawn.json

Rename "callback" to "function pointer" category.

The function does not belongs to any class that has below two keys:
 - `"returns"` a string that's the name of the return type
 - `"args"` a **record**, so an array of **record members**

BUG=dawn:1201
Change-Id: I546301a19af9472501122e759c495fd761e27ed5
Reviewed-on: https://dawn-review.googlesource.com/c/dawn/+/71060
Reviewed-by: Corentin Wallez <cwallez@chromium.org>
Commit-Queue: Junwei Fu <junwei.fu@intel.com>

dawn.json

@@ -23,6 +23,27 @@
         "namespace": "wgpu"
     },
 
+    "create instance": {
+        "category": "function",
+        "returns": "instance",
+        "args": [
+            {"name": "descriptor", "type": "instance descriptor", "annotation": "const*"}
+        ]
+    },
+    "proc": {
+        "category": "function pointer",
+        "returns": "void",
+        "args": []
+    },
+    "get proc address": {
+        "category": "function",
+        "returns": "proc",
+        "args": [
+            {"name": "device", "type": "device"},
+            {"name": "proc name", "type": "char", "annotation": "const*"}
+        ]
+    },
+
     "request adapter options": {
         "category": "structure",
         "extensible": "in",
@@ -45,7 +66,7 @@
         ]
     },
     "request adapter callback": {
-        "category": "callback",
+        "category": "function pointer",
         "tags": ["upstream"],
         "args": [
             {"name": "status", "type": "request adapter status"},
@@ -85,7 +106,7 @@
                 "name": "request device",
                 "args": [
                     {"name": "descriptor", "type": "device descriptor", "annotation": "const*"},
-                    {"name": "callback", "type": "request device callback"},
+                    {"name": "function pointer", "type": "request device callback"},
                     {"name": "userdata", "type": "void", "annotation": "*"}
                 ]
             }
@@ -358,7 +379,7 @@
                     {"name": "mode", "type": "map mode"},
                     {"name": "offset", "type": "size_t"},
                     {"name": "size", "type": "size_t"},
-                    {"name": "callback", "type": "buffer map callback"},
+                    {"name": "function pointer", "type": "buffer map callback"},
                     {"name": "userdata", "type": "void", "annotation": "*"}
                 ]
             },
@@ -406,7 +427,7 @@
         ]
     },
     "buffer map callback": {
-        "category": "callback",
+        "category": "function pointer",
         "args": [
             {"name": "status", "type": "buffer map async status"},
             {"name": "userdata", "type": "void", "annotation": "*"}
@@ -660,7 +681,7 @@
         ]
     },
     "compilation info callback": {
-        "category": "callback",
+        "category": "function pointer",
         "args": [
             {"name": "status", "type": "compilation info request status"},
             {"name": "compilation info", "type": "compilation info", "annotation": "const*"},
@@ -853,7 +874,7 @@
         ]
     },
     "create compute pipeline async callback": {
-        "category": "callback",
+        "category": "function pointer",
         "args": [
             {"name": "status", "type": "create pipeline async status"},
             {"name": "pipeline", "type": "compute pipeline"},
@@ -873,7 +894,7 @@
         ]
     },
     "create render pipeline async callback": {
-        "category": "callback",
+        "category": "function pointer",
         "args": [
             {"name": "status", "type": "create pipeline async status"},
             {"name": "pipeline", "type": "render pipeline"},
@@ -937,7 +958,7 @@
                 "returns": "void",
                 "args": [
                     {"name": "descriptor", "type": "compute pipeline descriptor", "annotation": "const*"},
-                    {"name": "callback", "type": "create compute pipeline async callback"},
+                    {"name": "function pointer", "type": "create compute pipeline async callback"},
                     {"name": "userdata", "type": "void", "annotation": "*"}
                 ]
             },
@@ -968,7 +989,7 @@
                 "returns": "void",
                 "args": [
                     {"name": "descriptor", "type": "render pipeline descriptor", "annotation": "const*"},
-                    {"name": "callback", "type": "create render pipeline async callback"},
+                    {"name": "function pointer", "type": "create render pipeline async callback"},
                     {"name": "userdata", "type": "void", "annotation": "*"}
                 ]
             },
@@ -1048,7 +1069,7 @@
             {
                 "name": "set uncaptured error callback",
                 "args": [
-                    {"name": "callback", "type": "error callback"},
+                    {"name": "function pointer", "type": "error callback"},
                     {"name": "userdata", "type": "void", "annotation": "*"}
                 ]
             },
@@ -1056,14 +1077,14 @@
                 "name": "set logging callback",
                 "tags": ["dawn"],
                 "args": [
-                    {"name": "callback", "type": "logging callback"},
+                    {"name": "function pointer", "type": "logging callback"},
                     {"name": "userdata", "type": "void", "annotation": "*"}
                 ]
             },
             {
                 "name": "set device lost callback",
                 "args": [
-                    {"name": "callback", "type": "device lost callback"},
+                    {"name": "function pointer", "type": "device lost callback"},
                     {"name": "userdata", "type": "void", "annotation": "*"}
                 ]
             },
@@ -1077,14 +1098,14 @@
                 "name": "pop error scope",
                 "returns": "bool",
                 "args": [
-                    {"name": "callback", "type": "error callback"},
+                    {"name": "function pointer", "type": "error callback"},
                     {"name": "userdata", "type": "void", "annotation": "*"}
                 ]
             }
         ]
     },
     "device lost callback": {
-        "category": "callback",
+        "category": "function pointer",
         "args": [
             {"name": "reason", "type": "device lost reason"},
             {"name": "message", "type": "char", "annotation": "const*"},
@@ -1126,7 +1147,7 @@
         "category": "native"
     },
     "error callback": {
-        "category": "callback",
+        "category": "function pointer",
         "args": [
             {"name": "type", "type": "error type"},
             {"name": "message", "type": "char", "annotation": "const*"},
@@ -1179,7 +1200,7 @@
         ]
     },
     "logging callback": {
-        "category": "callback",
+        "category": "function pointer",
         "tags": ["dawn"],
         "args": [
             {"name": "type", "type": "logging type"},
@@ -1332,7 +1353,7 @@
                 "tags": ["upstream"],
                 "args": [
                     {"name": "options", "type": "request adapter options", "annotation": "const*"},
-                    {"name": "callback", "type": "request adapter callback"},
+                    {"name": "function pointer", "type": "request adapter callback"},
                     {"name": "userdata", "type": "void", "annotation": "*"}
                 ]
             }
@@ -1521,7 +1542,7 @@
                 "name": "on submitted work done",
                 "args": [
                     {"name": "signal value", "type": "uint64_t"},
-                    {"name": "callback", "type": "queue work done callback"},
+                    {"name": "function pointer", "type": "queue work done callback"},
                     {"name": "userdata", "type": "void", "annotation": "*"}
                 ]
             },
@@ -1558,7 +1579,7 @@
         ]
     },
     "queue work done callback": {
-        "category": "callback",
+        "category": "function pointer",
         "args": [
             {"name": "status", "type": "queue work done status"},
             {"name": "userdata", "type": "void", "annotation": "*"}
@@ -1950,7 +1971,7 @@
     },
 
     "request device callback": {
-        "category": "callback",
+        "category": "function pointer",
         "args": [
             {"name": "status", "type": "request device status"},
             {"name": "device", "type": "device"},
@@ -2119,7 +2140,7 @@
             {
                 "name": "get compilation info",
                 "args": [
-                    {"name": "callback", "type": "compilation info callback"},
+                    {"name": "function pointer", "type": "compilation info callback"},
                     {"name": "userdata", "type": "void", "annotation": "*"}
                 ]
             },

docs/codegen.md

@@ -57,7 +57,8 @@ A **record** is a list of **record members**, each of which is a dictionary with
 
 **`"bitmask"`** an `uint32_t`-based bitmask. It is similar to **`"enum"`** but can be output differently.
 
-**`"callback"`** defines a function pointer type that can be used by other things (usually callbacks passed to method calls)
+**`"function pointer"`** defines a function pointer type that can be used by other things.
+ - `"returns"` a string that's the name of the return type
  - `"args"` a **record**, so an array of **record members**
 
 **`"structure"`**
@@ -75,6 +76,10 @@ A **record** is a list of **record members**, each of which is a dictionary with
  - `"type"`: a string, the name of the base data type
  - `"value"`: a string, the value is defined with preprocessor macro
 
+**`"function"`** declares a function that not belongs to any class.
+ - `"returns"` a string that's the name of the return type
+ - `"args"` a **record**, so an array of **record members**
+
 ## Dawn "wire" generators
 
 The generator for the pieces of dawn_wire need additional data which is found in [`dawn_wire_json`](../dawn_wire.json). Examples of pieces that are generated are:

generator/dawn_json_generator.py

@@ -133,9 +133,10 @@ class BitmaskType(Type):
         self.is_wire_transparent = True
 
 
-class CallbackType(Type):
+class FunctionPointerType(Type):
     def __init__(self, is_enabled, name, json_data):
         Type.__init__(self, name, json_data)
+        self.return_type = None
         self.arguments = []
 
 
@@ -251,6 +252,14 @@ class ConstantDefinition():
         self.name = Name(name)
 
 
+class FunctionDeclaration():
+    def __init__(self, is_enabled, name, json_data):
+        self.return_type = None
+        self.arguments = []
+        self.json_data = json_data
+        self.name = Name(name)
+
+
 class Command(Record):
     def __init__(self, name, members=None):
         Record.__init__(self, name)
@@ -313,9 +322,8 @@ def link_structure(struct, types):
     struct.members = linked_record_members(struct.json_data['members'], types)
 
 
-def link_callback(callback, types):
-    callback.arguments = linked_record_members(callback.json_data['args'],
-                                               types)
+def link_function_pointer(function_pointer, types):
+    link_function(function_pointer, types)
 
 
 def link_typedef(typedef, types):
@@ -327,6 +335,12 @@ def link_constant(constant, types):
     assert constant.type.name.native
 
 
+def link_function(function, types):
+    function.return_type = types[function.json_data.get('returns', 'void')]
+    function.arguments = linked_record_members(function.json_data['args'],
+                                               types)
+
+
 # Sort structures so that if struct A has struct B as a member, then B is
 # listed before A.
 #
@@ -375,11 +389,12 @@ def parse_json(json, enabled_tags):
         'bitmask': BitmaskType,
         'enum': EnumType,
         'native': NativeType,
-        'callback': CallbackType,
+        'function pointer': FunctionPointerType,
         'object': ObjectType,
         'structure': StructureType,
         'typedef': TypedefType,
         'constant': ConstantDefinition,
+        'function': FunctionDeclaration
     }
 
     types = {}
@@ -402,8 +417,8 @@ def parse_json(json, enabled_tags):
     for struct in by_category['structure']:
         link_structure(struct, types)
 
-    for callback in by_category['callback']:
-        link_callback(callback, types)
+    for function_pointer in by_category['function pointer']:
+        link_function_pointer(function_pointer, types)
 
     for typedef in by_category['typedef']:
         link_typedef(typedef, types)
@@ -411,6 +426,9 @@ def parse_json(json, enabled_tags):
     for constant in by_category['constant']:
         link_constant(constant, types)
 
+    for function in by_category['function']:
+        link_function(function, types)
+
     for category in by_category.keys():
         by_category[category] = sorted(
             by_category[category], key=lambda typ: typ.name.canonical_case())
@@ -643,7 +661,7 @@ def get_c_methods_sorted_by_name(api_params):
 
 
 def has_callback_arguments(method):
-    return any(arg.type.category == 'callback' for arg in method.arguments)
+    return any(arg.type.category == 'function pointer' for arg in method.arguments)
 
 
 def make_base_render_params(metadata):
@@ -659,12 +677,22 @@ def make_base_render_params(metadata):
         return c_prefix + type_name.CamelCase() + '_' + value_name.CamelCase()
 
     def as_cMethod(type_name, method_name):
-        assert not type_name.native and not method_name.native
-        return c_prefix.lower() + type_name.CamelCase() + method_name.CamelCase()
+        c_method = c_prefix.lower()
+        if type_name != None:
+            assert not type_name.native
+            c_method += type_name.CamelCase()
+        assert not method_name.native
+        c_method += method_name.CamelCase()
+        return c_method
 
     def as_cProc(type_name, method_name):
-        assert not type_name.native and not method_name.native
-        return c_prefix + 'Proc' + type_name.CamelCase() + method_name.CamelCase()
+        c_proc = c_prefix + 'Proc'
+        if type_name != None:
+            assert not type_name.native
+            c_proc += type_name.CamelCase()
+        assert not method_name.native
+        c_proc += method_name.CamelCase()
+        return c_proc
 
     return {
             'Name': lambda name: Name(name),

generator/templates/api.h

@@ -134,20 +134,23 @@ typedef struct {{c_prefix}}ChainedStructOut {
 extern "C" {
 #endif
 
-{% for type in by_category["callback"] %}
-    typedef void (*{{as_cType(type.name)}})(
+{% for type in by_category["function pointer"] %}
+    typedef {{as_cType(type.return_type.name)}} (*{{as_cType(type.name)}})(
         {%- for arg in type.arguments -%}
             {% if not loop.first %}, {% endif %}{{as_annotated_cType(arg)}}
         {%- endfor -%}
     );
 {% endfor %}
 
-typedef void (*{{c_prefix}}Proc)(void);
-
 #if !defined({{c_prefix}}_SKIP_PROCS)
 
-typedef WGPUInstance (*WGPUProcCreateInstance)(WGPUInstanceDescriptor const * descriptor);
-typedef WGPUProc (*WGPUProcGetProcAddress)(WGPUDevice device, char const * procName);
+{% for function in by_category["function"] %}
+    typedef {{as_cType(function.return_type.name)}} (*{{as_cProc(None, function.name)}})(
+            {%- for arg in function.arguments -%}
+                {% if not loop.first %}, {% endif %}{{as_annotated_cType(arg)}}
+            {%- endfor -%}
+        );
+{% endfor %}
 
 {% for type in by_category["object"] if len(c_methods(type)) > 0 %}
     // Procs of {{type.name.CamelCase()}}
@@ -165,8 +168,13 @@ typedef WGPUProc (*WGPUProcGetProcAddress)(WGPUDevice device, char const * procN
 
 #if !defined({{c_prefix}}_SKIP_DECLARATIONS)
 
-WGPU_EXPORT WGPUInstance wgpuCreateInstance(WGPUInstanceDescriptor const * descriptor);
-WGPU_EXPORT WGPUProc wgpuGetProcAddress(WGPUDevice device, char const * procName);
+{% for function in by_category["function"] %}
+    {{c_prefix}}_EXPORT {{as_cType(function.return_type.name)}} {{as_cMethod(None, function.name)}}(
+            {%- for arg in function.arguments -%}
+                {% if not loop.first %}, {% endif %}{{as_annotated_cType(arg)}}
+            {%- endfor -%}
+        );
+{% endfor %}
 
 {% for type in by_category["object"] if len(c_methods(type)) > 0 %}
     // Methods of {{type.name.CamelCase()}}

generator/templates/mock_webgpu.cpp

@@ -61,7 +61,7 @@ void ProcTableAsClass::GetProcTableAndDevice(DawnProcTable* table, WGPUDevice* d
             {%- endfor -%}
         ) {
             ProcTableAsClass::Object* object = reinterpret_cast<ProcTableAsClass::Object*>({{as_varName(type.name)}});
-            {% for callback_arg in method.arguments if callback_arg.type.category == 'callback' %}
+            {% for callback_arg in method.arguments if callback_arg.type.category == 'function pointer' %}
                 object->m{{as_MethodSuffix(type.name, method.name)}}Callback = {{as_varName(callback_arg.name)}};
             {% endfor %}
             object->userdata = userdata;
@@ -73,7 +73,7 @@ void ProcTableAsClass::GetProcTableAndDevice(DawnProcTable* table, WGPUDevice* d
             );
         }
 
-        {% for callback_arg in method.arguments if callback_arg.type.category == 'callback' %}
+        {% for callback_arg in method.arguments if callback_arg.type.category == 'function pointer' %}
             void ProcTableAsClass::Call{{Suffix}}Callback(
                 {{-as_cType(type.name)}} {{as_varName(type.name)}}
                 {%- for arg in callback_arg.type.arguments -%}

generator/templates/mock_webgpu.h

@@ -70,7 +70,7 @@ class ProcTableAsClass {
                 ) = 0;
 
                 //* Calls the stored callback.
-                {% for callback_arg in method.arguments if callback_arg.type.category == 'callback' %}
+                {% for callback_arg in method.arguments if callback_arg.type.category == 'function pointer' %}
                     void Call{{as_MethodSuffix(type.name, method.name)}}Callback(
                         {{-as_cType(type.name)}} {{as_varName(type.name)}}
                         {%- for arg in callback_arg.type.arguments -%}
@@ -85,7 +85,7 @@ class ProcTableAsClass {
             ProcTableAsClass* procs = nullptr;
             {% for type in by_category["object"] %}
                 {% for method in type.methods if has_callback_arguments(method) %}
-                    {% for callback_arg in method.arguments if callback_arg.type.category == 'callback' %}
+                    {% for callback_arg in method.arguments if callback_arg.type.category == 'function pointer' %}
                         {{as_cType(callback_arg.type.name)}} m{{as_MethodSuffix(type.name, method.name)}}Callback = nullptr;
                     {% endfor %}
                 {% endfor %}

generator/templates/webgpu_cpp.cpp

@@ -112,7 +112,7 @@ namespace wgpu {
                             {{as_varName(arg.name)}}.Get()
                         {%- elif arg.type.category == "enum" or arg.type.category == "bitmask" -%}
                             static_cast<{{as_cType(arg.type.name)}}>({{as_varName(arg.name)}})
-                        {%- elif arg.type.category in ["callback", "native"] -%}
+                        {%- elif arg.type.category in ["function pointer", "native"] -%}
                             {{as_varName(arg.name)}}
                         {%- else -%}
                             UNHANDLED

generator/templates/webgpu_cpp.h

@@ -52,8 +52,7 @@ namespace wgpu {
 
     {% endfor %}
 
-    using Proc = WGPUProc;
-    {% for type in by_category["callback"] %}
+    {% for type in by_category["function pointer"] %}
         using {{as_cppType(type.name)}} = {{as_cType(type.name)}};
     {% endfor %}