Skip to content

Commit b7ec820

Browse files
committed
Work on documenting the name affixes used by MixKhronosData
1 parent 52508ef commit b7ec820

1 file changed

Lines changed: 28 additions & 4 deletions

File tree

docs/for-contributors/Generator/generator-mods.md

Lines changed: 28 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -413,11 +413,35 @@ Be aware that these link to the latest version. Silk's repo may be using an olde
413413

414414
Name affix categories:
415415

416-
- `KhronosFunctionDataType` - TODO
417-
- `KhronosHandleType` - TODO
418-
- `KhronosImpliedVendor` - TODO
419-
- `KhronosNamespaceEnum` - TODO
416+
- `KhronosFunctionDataType` - This is a suffix relevant to OpenGL-like APIs where functions like `glColor3` have
417+
variants such as `glColor3i`, `glColor3f`, and `glColor3b`. These suffixes indicate the data type that the function
418+
expects. In this case, integer, float, and byte, respectively. Silk's bindings configure these as discriminators so
419+
that they can be removed when removing them does not lead to method overload conflicts. `IdentifyFunctionDataTypes`
420+
must be set to true in the `MixKhronosData` configuration for this affix category to be identified.
421+
422+
- `KhronosHandleType` - This is a suffix resulting from the typedefs used by Khronos in their headers. For example,
423+
Vulkan uses the following macro to define handle types:
424+
`#define VK_DEFINE_HANDLE(object) typedef struct object##_T* object;`, used as `VK_DEFINE_HANDLE(VkInstance)`.
425+
Although Vulkan uses the handle type as `VkInstance`, `ClangScraper` outputs the type as `VkInstance_T` due to the
426+
typedef. As such, `MixKhronosData` identifies this suffix so that `PrettifyNames` can be configured to remove this
427+
suffix later.
428+
429+
- `KhronosImpliedVendor` - This is a suffix added when an enum member has the same vendor suffix as the containing enum
430+
type. This suffix exists in native code because the enum member is usually defined as a standalone, global constant
431+
without any other context whether the enum member is part of an extension. In C#, this is not a problem because the
432+
enum type itself conveys that information. For example, in Vulkan, `VkPresentModeKHR` in Vulkan is a `KHR` suffixed
433+
enum type that contains `VK_PRESENT_MODE_IMMEDIATE_KHR` as a member. In C#, this `KHR` suffix on the member is
434+
redundant. As such, Silk's bindings are configured to remove this suffix. `IdentifyEnumMemberImpliedVendors` must be
435+
set to true in the `MixKhronosData` configuration for this affix category to be identified.
436+
437+
- `KhronosNamespaceEnum` - This is a prefix added to the "namespace" enum of OpenGL-like APIs such as `GLEnum`,
438+
`ALEnum`, and `ALCEnum`. In this case, the value of the prefix would be `GL`, `AL`, and `ALC`, respectively. This is
439+
so that the casing of the prefix is preserved by `PrettifyNames`. As such, Silk's bindings leaves the affix category
440+
unconfigured in the `PrettifyNames` configuration so that `PrettifyNames` uses the default behavior of preserving the
441+
affix.
442+
420443
- `KhronosNonExclusiveVendor` - TODO
444+
421445
- `KhronosVendor` - TODO
422446

423447
Usage recommendations:

0 commit comments

Comments
 (0)