Skip to content

Conversation

@Exanite
Copy link
Contributor

@Exanite Exanite commented Nov 24, 2025

Summary of the PR

This PR focuses on implementing the naming-related improvements identified in #2457.
Depending on the scope of the tasks, some of these tasks may be pushed to another PR.

Important changes:

  • Handle types are now named as -HandleEXT instead of -EXTHandle.
    • Eg: AccelerationStructureHandleKHR
  • Function pointer delegate types are now named as -DelegateEXT instead of EXTDelegate.
    • Eg: pfn struct BufferCallbackSOFT and pfn delegate BufferCallbackDelegateSOFT
  • Functions with data type suffixes following a number such as alGetSourcei64vDirectSOFT are now trimmed and prettified as GetSourcei64vDirectSOFT instead of GetSourcei64VDirectSOFT. Note the capitalization of v. This is because affixes are added after prettification.
  • Vendor suffixes are now kept strictly uppercased.
  • OpenGL vendor suffix trimming is now generalized and can be configured and used for any Khronos API.
    • Notably, TrimEnumMemberImpliedVendors trims enum member vendor suffixes if it matches the enum type vendor suffix.
  • Struct properties are now prettified. They were previously ignored.
  • NativeName is a new attribute that saves the name output by ClangSharp. This for the most part isn't used by the generator, but can be useful for the end user.
  • NameAffix is a new attribute that allows prefixes/suffixes to be declared upfront and reordered. The idea is that mods add the attribute to identifiers and PrettifyNames applies the affixes during trimming and prettification.
  • A large portion of the trimming/PrettifyNames code has been rewritten.
    • NameTrimmer has been kept mostly the same.
    • INameTrimmer.Order is used to order the trimmers instead of the version.
    • PrettifyNames.Visitor's functionality is mostly the same, but also gathers name affix data.
    • MixKhronosData.Trim is almost all replaced by the name affix system. This is implemented in MixKhronosData.RewriterPhase3 (yes, there are 3 rewriters, but this keeps things simpler without adding much time cost).
    • Most usages of tuples have been replaced with record structs.
    • Most nullable collections (eg: List<string>?) have been made non-nullable. Most of these get allocated anyway and it makes the code more maintainable. If there is any performance issue (mainly concerning the Microsoft job), I will take the time to optimize it.
    • Prettification (as in calling the Prettify extension method) is now implemented as another trimmer. Prettification now happens before name conflict resolution and before name affixes are added.
  • Handle structs now have constructors since they were previously not possible to construct (field is readonly).
  • The StripAttributes mod can be used to remove attributes from the final bindings.
    • Currently the following are removed: NativeTypeName, NameAffix, Transformed

Related issues, Discord discussions, or proposals

Previous Vulkan PR (initial bindings generation): #2457
Discord thread: https://discord.com/channels/521092042781229087/1376331581198827520/1442651368207941643

Further Comments

Tasks not part of this PR

These are the tasks from my previous PR. These have been sorted and trimmed down to ensure that this PR remains focused. These may be added to this PR.

If you want to see the original, unmodified set of tasks, please see #2457.

These will also be part of a future PR.

  • Apply BoolType transformation to VkBool32 in structs. They currently are only handled for functions.
  • Add default field values to structs where it makes sense (eg: SType)
  • Ensure SupportedApiProfiles attributes are correct
    • Properly resolve API profiles for Flags/FlagBits types
    • Prefer name from NativeName for resolving API profiles

Future PRs

  • Update Curin's branch to use my new LocationTransformation code. The new renamer should be replaced with this. See the NameUtils.cs and Renamer.cs files on Curin's branch. Renamer.cs should be removed. NameUtils.cs should have the methods updated to use my LocationTransformation code instead (this should show up as a merge conflict).
    • PR opened and ready for review/merge
    • PR merged
    • Old renamer code removed
  • Reimplement the struct chaining API
  • Figure out why the headers are getting mixed up when running multiple jobs at the same time.
    • Seems to be related to TransformFunctions.
  • Figure out why the SDL handle structs are getting named as Silk.NET.SDL.ConditionHandle.gen.cs instead of ConditionHandle.gen.cs when running multiple jobs at the same time.
  • Work on making the generator/mod configs more consistent and user friendly. This should be done before the generator is considered a public API.
  • Consider opening a ClangSharp PR to fix issue with SDL_MAX_SINT64 generation on Linux
  • Consider splitting ExtractNestedTyping and TransformHandles into a new set of Extract- mods.
    • This this mainly for maintainability for ExtractNestedTyping, but for TransformHandles it is useful for AddApiProfiles to be executed after all types are extracted, but not yet transformed.
    • Alternatively, make AddApiProfiles strictly work off of NativeName attributes.
  • Acronym related name improvements discussed here: https://discord.com/channels/521092042781229087/587346162802229298/1446979314330501172
    • Re-read discussion and organize into tasks.
    • Change default acronym threshold to 2 for all bindings
    • Change default acronym threshold to 2 to be the default if not specified in the PrettifyNames config.
    • Handle Mat4X4 case. The "X" should be lowercased.
    • Update existing names to match framework design guidelines
      • EGL as Egl
      • Name overrides in generator config
  • Optimize/refactor overrides in PrettifyNames
  • Consider reworking data type trimming regexes.
    • This was discussed more here: [3.0] Implement name-related improvements identified in previous Vulkan PR #2503 (comment)
    • The summary is that the current set of 2 regexes doesn't elegantly handle the case where the ending of a word should not be trimmed, but the word itself can be data type suffixes.
    • For example: alSourceRewindv and alSourceRewind. The d in Rewind can be mistaken as a data type suffix, so we add it to the EndingsNotToTrim regex. However, the dv in Rewindv also has the same problem.
    • We likely need something more akin to WordsNotToTrimInto than EndingsNotToTrim.
  • Optimize NativeName attributes.
    • This should involve renaming StripAttributes to CleanupAttributes and adding an option in its config to optimize NativeName attributes.
  • Maybe rework how using statements are added. Not sure why, but using statements are randomly added/removed between Windows/Linux. This causes noisy diffs.

Current Todos

Prepare to merge.

  • Finish self code review
  • Generate bindings on Windows for consistency
  • Temporarily remove generated files from PR during code review
  • Review the generated bindings as a second code review
  • Consider updating OpenAL submodule and regenerating

Completed Todos

Newest groups at the top. Order within a group is chronological.

Note that I also wrote a summary at the top. The summary is more comprehensive, but this section can be useful getting additional context. Also see my commit descriptions if more context is needed.

INameTrimmer.Order

  • Add priority system to INameTrimmer.
    • I implemented the new name affixer system using trimmers, so this introduced 3 new trimmers in order to separate each stage properly. There is now a new INameTrimmer.Order property and internal TrimmerOrder enum.

Fix misc issues I noticed

  • VkVendorId members are not trimmed properly
  • Figure out why the members of the enum AttribMask in OpenGL are not getting rewritten.
    • Initial investigation shows that the fieldSymbol.ConstantValue is null, but why it is null is unclear. Maybe a Roslyn bug? Example member: DepthBufferBit = unchecked((uint)0x00000100). Note that similar expressions in Vulkan are fine, eg: unchecked((ulong)0x00000002UL). Maybe it is because the literal type and cast type are different.
    • Wait, are these the enums that we generate?
    • Yup, they are. MixKhronosData was outputting subtly invalid type names. I changed it to use ParseTypeName(baseType) instead of IdentifierName(baseType).

Fix issues introduced by name affix system

  • Identify and fix issues introduced by name affixation. Also just identify and fix naming issues in general.
    • Data type trimming in OpenAL seems to be broken. Probably OpenGL as well.
    • Check if I need to reimplement vendor suffix removal for OpenGL. I probably do.
      • Discuss: I decided to change the vendor suffix removal for enum members so that it removes the member suffix if it matches the type suffix. This prevents cases where a member of a different suffix is added, causing all members to have their suffixes restored.
      • Discuss: The above change made it so that the member suffix removal code is usable for Vulkan so I enabled it for Vulkan as well. See PresentModeKHR to see how it looks (the KHR suffixed members have their suffixes removed, but EXT remains the same).
    • Reapply some of my MixKhronosData code removals to the current develop/3.0 branch and see what changes would be made. This is to ensure I don't accidentally remove functionality when deleting code.
  • Ensure other APIs are configured consistently with Vulkan. Eg: Ensure affix priorities are set, etc.

Name affix system

  • Properly trim prefixed/suffixed names, such as PFNVkDebugUtilsMessengerCallbackEXT and BufferTHandle
    • PFNVkDebugUtilsMessengerCallbackEXT prefix
    • PFNVkDebugUtilsMessengerCallbackDelegateEXT suffix
    • AccelerationStructureHandleKHR suffix
    • Extract vendor extensions from names and store into NameSuffix attributes.
    • Revert "hacky" THandle fix.
  • Consider renaming handle types as HandleEXT instead of EXTHandle for readability.
    • This is fairly doable. The above todos track this.

Name metadata

  • Add NativeName attribute
  • Ensure NativeName attribute is added by all mods that generate new types/members
    • Technically not strictly required, but nice from a API consistency standpoint.
    • MixKhronosData
      • Enum members
      • Enum declarations
        • Vulkan (uses FlagBits version of enum names since it is more helpful when googling)
        • Discuss validity in other Khronos APIs (some APIs don't have actual enums)
          • Eg: GLEnum and the other OpenGL enums
    • ExtractNestedTyping
      • Function pointers
      • Others?
    • TransformHandles

Name prettification

Fix bugs from original PR

  • Enums containing negative values should not have an unsigned backing type.

Handle struct improvements

  • Handle structs don't have an easy way of being constructed (field is readonly and no constructor).

This looks like it's from some sort of built-in renamer.
Don't think we'll ever use this since we have a custom renamer.
Not sure why these were not being coerced when the Vulkan PR was merged, but they started getting coerced in this PR.
This technically is a good thing since it means the coerce backing types code is now working as previously intended.
However, the previously intended implementation missed an edge case, which this commit fixes.
This is because the structs were impossible to reasonably construct before.
Technically this is from my update PR into Curin's branch (curin#101), but is effectively the same as backporting the changes from Curin's branch.
Exact commit that I copied the changes from: 0cc698a
VaListTagHandle is an extra handle struct that seems to generate on Linux (and not on Windows) and breaks global prefix determination.
OpenAL: ContextErrorCode seems to always be replaced with ErrorCode, even on Windows. Not sure why. This also happened during the last PR, but I didn't commit it.
Honestly, what I wrote is a complete guess, I'll likely revisit these once I understand them more.
@Exanite Exanite force-pushed the feature/vulkan-bindings-3.0-improvements branch from b06e648 to 53fbdd3 Compare December 6, 2025 23:02
@Exanite Exanite force-pushed the feature/vulkan-bindings-3.0-improvements branch from c6a07d7 to 9bbf8be Compare December 7, 2025 00:18
Copy link
Contributor Author

@Exanite Exanite left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Self code review complete. Going to mark as ready for review.

Note that I only have the non-generated changes committed.
The generated changes are here: Exanite#19

This is because the generated changes hide the non-generated changes (it goes over the 1k file limit).

Feel free to comment on the linked PR as well.
It will be merged into this PR after the non-generated changes are reviewed.

DO NOT merge this PR until the generated changes are merged, and preferably, reviewed.

@Exanite Exanite marked this pull request as ready for review December 7, 2025 00:45
return attributeLists;
}

return attributeLists.WithNativeName(identifier.Text);
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should change this to not apply NativeName if:

  • the native name is identical to the current name, and
  • it is obvious that the symbol is representing a native symbol (i.e. one of the parent syntax nodes has a NativeName)

This way NativeName is still used to signify that this a representation of a native symbol, but where that's already known, we're not adding attributes that aren't conveying any extra information (such as when the names are identical)

Copy link
Contributor Author

@Exanite Exanite Dec 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be something we do as a post-process step and not at a pre-process step.

MarkNativeNames is designed as a pre-process step. It goes early in the mod order.
MarkNativeNames goes right after ClangScraper because, at that point, we know that all names match the native names (outside some exceptions like in bitfield structs where ClangSharp introduces an extra field).

Attribute removal is currently handled by StripAttributes, which is a post-process step. It goes late (last currently) in the mod order.
This mod can be generalized as an CleanupAttributes mod where optimizing attributes is part of the configurable steps that the mod applies.

The reason why optimizing attributes should be done as a post-process is because optimization requires knowledge of the output. If we introduce the "don't add if redundant" logic during pre-processing, then no NativeName attributes would ever get added.

An alternative is for mods to only add the NativeName attribute if they change the name, but that also requires all mods to understand the rules for adding/removing the NativeName attribute, which greatly increases complexity.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmmmmm ok, I agree - I must admit I haven't checked the bindings yet so I don't know whether this is being done already.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The optimization of NativeName attributes isn't, but it's not too hard to implement.
To me, this is a lower priority task since it's not critical to the bindings working.

@@ -1800,7 +1505,7 @@ public bool TryGetSymbolMetadata(
/// while the lookbehind asserts that the ending match will not overreach into the end of a word.
/// </summary>
// NOTE: LET THIS BE A LESSON! Do NOT add x (fixed) here, these will frequently conflict with integer overloads.
[GeneratedRegex("(?<!xe)([fdh]v?|u?[isb](64)?v?|v|i_v|fi|hi)$")]
[GeneratedRegex("(?<!xe)((?<!Rewin)[dhf]v?|u?[isb](64)?v?|v|i_v|fi|hi)$")]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why didn't the EndingsNotToTrim regex immediately below this not pick it up?


public override SyntaxNode VisitEnumDeclaration(EnumDeclarationSyntax node)
{
// Special case for enums since this code needs information about the enum type and its members at the same time.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why does it need to know its type?

exclusiveVendor = null;
}

// Check if the enum contains unsuffixed members
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why?

return false;
});

var isSafeToTrimMembers = !containsUnsuffixed;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why does it not containing any unsuffixed vendors make it safe? How is this different to exclusiveVendor?


if (config.TrimEnumTypeNonExclusiveVendors && typeVendor != null)
{
var shouldTrimType = typeVendor != exclusiveVendor;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I won't keep asking questions out loud, but generally I think this code could do with some more comments with some examples of what it's actually doing as it's quite hard to visualise.

I think what it's doing makes sense but it requires a lot of thought and careful reading to figure out what it's doing.

Copy link
Contributor Author

@Exanite Exanite Dec 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This code mostly matches the functionality of the code that was originally in MixKhronosData.Trim.
Well... to the best of my ability since that code wasn't really commented either.

The exceptions are that I removed/prevented some edge cases and restructured the code.

Edit: Another exception is that I changed the enum member name trimming condition to be if the member matches the enum type name vendor suffix. Previously it was if all member names match the type vendor suffix (hence the config option being called TrimEnumMemberImpliedVendors instead of TrimEnumMemberSharedVendors). This was the part I discussed with you in the discord.

I provide a better explanation of the functionality of the code in the Configuration record struct at the top of the class, but I agree that that this code is likely hard to understand without context and local examples. I'll go through the code and add these.

{
if (isSafeToTrimType)
{
// Remove the exclusive vendor from the enum name since it is wrong and it is safe to do so
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is it safe to do so? Why is it wrong? Can you give an example of where this code is used? This could result in breaking changes!

Copy link
Contributor Author

@Exanite Exanite Dec 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've updated the code to answer these questions. Same for the similar review comments in this area of the code.

This is how this section now looks:
image

I'm not exactly sure what you mean by breaking changes since this behavior exactly matches the original behavior of the code as it as in MixKhronosData.Trim. Keep in mind that this isn't new functionality. This is old functionality ported over to the new name affix system.

That being said, both the old and new implementations do have the possibility of introducing breaking changes if upstream introduces another variant of the enum that prevents the vendor suffix from getting trimmed.

For example, CombinerRegisterNV currently exists and has the NV vendor suffix trimmed due to it containing GL_TEXTURE0_ARB, similar to this example:
image

If Khronos was to add CombinerRegisterAMD, then CombinerRegisterNV's suffix would no longer be trimmed and CombinerRegister would no longer exist as an enum in the generated bindings.

That being said, this is probably a rare case.

Note that if Khronos added CombinerRegister, there likely would be no breaking change.

/// Used to define the order that the trimmers will run in.
/// Higher values indicate that the trimmer should run later.
/// </summary>
int Order { get; }
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this should be the way we determine the order of execution - this is not something individual augments should be able to influence without careful consideration of what it's trying to achieve. If the order of execution matters and has different effects, this should be user configurable. As I've said before, I want to get rid of things like Version where you arbitrarily change the number to achieve the result you want - if there is a need to control the order of execution to achieve the results the user wants, then that's what the user-facing design should reflect.

Copy link
Contributor Author

@Exanite Exanite Dec 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I fully agree. In this case, I only documented the functionality of the property, but I probably should have also documented the intended usage.

This is the intended usage:
Mods should only use the values -1 or 0 for Order and DiscriminatorPriority.
-1 corresponds to "disabling" the property and 0 corresponds to leaving it as the default value.
All other values should come from the generator config.
Mods also should not attempt to compute what values to use for Order and DiscriminatorPriority.

The above usage matches how the properties are currently used by the mods in my PR.

Arguably, even 0 and -1 should not be hardcoded, but I opted not to do that since it would expose a lot of configuration properties.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh wait, I completely misunderstood what code this comment was addressing.
I thought it was referring to the NameAffix attribute. For that case, my comment still holds and I'll still update the documentation to include the intended usage of the attribute.

As for the trimmer case though, I'm not sure.
The order property here, as it currently stands, is for ensuring correctness rather than for allowing for customizability. The affixes have to trimmed in a certain order for my NameAffix system to work, as seen here.
image

However, for trimmers not part of the required set (eg: the trimmers defined by mods), those probably should have their own configuration.

Copy link
Contributor Author

@Exanite Exanite Dec 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The only external trimmer (external as in not part of PrettifyNames) here is MixKhronosData.
This means we currently don't really have a usage pattern to analyze.

What other trimmers will there be that isn't covered by the existing functionality?
Even NameTrimmer can probably use the name affix system instead, which has a well defined and configurable execution order. From what I understand, it mainly identifies and trims global prefixes, so it can be implemented as a IdentifyGlobalPrefixes mod that has a syntax rewriter. This also lets configure whether global prefixes should be identified; if they should be identified, but kept; and if they should be kept, but reordered.

MixKhronosData does provide one case, which is to prevent/rewind trimming in the case of GLEnum.
Generally speaking, this would be more of a name replacement/transformation. This is not covered by the affix system, but is partially covered by the name override system.

@github-project-automation github-project-automation bot moved this from Todo to In Progress in Silk.NET Development Tracker Dec 7, 2025
@Exanite
Copy link
Contributor Author

Exanite commented Dec 7, 2025

Not sure why I can't reply to the following comment:

Why didn't the EndingsNotToTrim regex immediately below this not pick it up?

But the reason for this is because ...Radix|Sound|Rewind|Supported)$ matches only if Rewind is at the very end of the name.

Rewind is also a function name that has data type suffixes.
That being said, the only suffix it does have is -v and it never truly gets trimmed due to name conflict so perhaps we can just add Rewindv as part of EndingsNotToTrim. This is notably dangerous if OpenAL decides to add a different, actually trimmable suffix (I'm not familiar with OpenAL so I'm not sure that they will though).

Two other things we probably should consider:

  1. Changing it so that the regex is configurable in the generator config.
  2. Adding a comment explaining why (?<!Rewin)[dhf]v? is part of EndingsToTrim.
  3. (Same as above, but for completeness), consider adding Rewindv as part of EndingsNotToTrim.

@Perksey
Copy link
Member

Perksey commented Dec 7, 2025

This is mostly my concern, EndingsNotToTrim was intended to provide the "do the data type trimming, but prevent these special cases from being trimmed". If the new code is no longer using EndingsNotToTrim in this way, I'd rather fix that than add special cases to EndingsToTrim.

With regards to Rewindv, I would expect it to behave as it does on develop as well i.e. Rewindv is added as a secondary. I don't expect the fix to be adding Rewindv to EndingsNotToTrim.

@Exanite
Copy link
Contributor Author

Exanite commented Dec 7, 2025

I probably should have mentioned that it's also wrong on develop/3.0:
image

This was a case that I noticed and fixed; not a case that I introduced and fixed.

@Perksey
Copy link
Member

Perksey commented Dec 7, 2025

Oh... lol. Ok yeah maybe this is the appropriate fix.

@Exanite
Copy link
Contributor Author

Exanite commented Dec 7, 2025

On second thought though, I think my statement here is wrong:

This is notably dangerous if OpenAL decides to add a different, actually trimmable suffix (I'm not familiar with OpenAL so I'm not sure that they will though).

I think it's safe to add Rewindv to EndingsNotToTrim since it only prevents the -v suffix from being trimmed.

@Perksey
Copy link
Member

Perksey commented Dec 7, 2025

Yeah I agree. Maybe we should integrate the words in EndingsNotToTrim into EndingsToTrim to make sure we don't run into another spot of bother in the future.

@Exanite
Copy link
Contributor Author

Exanite commented Dec 7, 2025

As in, combine the two regexes? I think that would make it confusing to edit.

Edit: I think I see what you mean. You mean to make it so that the regex considers if trimming the suffix would trim into part of another word. Eg: Match for Rewind before matching for dv or v.

@Perksey
Copy link
Member

Perksey commented Dec 7, 2025

I'm concerned about only having Rewind in EndingsToTrim if that is indeed the valid fix. I still feel like there should be a way to use EndingsNotToTrim to get what we want but I'm not sure how. But I don't want the two regexes to not enact the correct behaviour because they have different sets of applicable words.

@Exanite
Copy link
Contributor Author

Exanite commented Dec 7, 2025

I added this to my task tracker above to be done in a separate PR.

Don't resolve the PR comment just yet though since I think it is better to add Rewindv to EndingsNotToTrim for now.

@Exanite Exanite requested a review from Perksey December 8, 2025 00:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: In Progress

Development

Successfully merging this pull request may close these issues.

2 participants