Vulkan struct chaining #706
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
* Created class library with 3 chainable structs * Added `IChainable` interface hierarchy * Added chaining methods `Chain`, `CreateNext`, `SetNext` and `End` * Added tests
* Added tests to check that invalid structs don't compile * Minimal additional code required per struct - just add an interface for each allowed `PNext` struct; and, - add a short static method `Chain` (technically optional), and a short instance method `SetNext`.
Retargeted project to ensure that it only targets the same includes, etc. as `Silk.Next.Core` and `Silk.Net.Vulkan`
* Added `IStructureType` for any struct that has a `StructureType SType` field. This is usually added automatically by one of the other interfaces; and allows the structure type to be automatically corrected and retrieved using the `StructureType IStructuredType.StructureType()` method. * Added `IChainStart` to indicate a type that can form the start of a chain. * `IChainable<...>` was replaced with `IExtendsChain<T>` which matches the Vulkan specification more readily. * The chaining methods now all accept, and return, a reference to an `IChainStart`, making it easier to scan a chain for existing items, and making use of the auto-generated `IExtendsChain<T>` to validate types at compile time. * `SetNext`, by default, will now replace existing chain entries if they match the supplied `SType`. This behaviour can be overriden with the optional `alwaysAdd` parameter. * `CreateNext` is now called `AddNext` to indicate it always adds to the end of a Chain.cs * `TryAddNext` added to only create a new structure if it is not already there. * `IndexOf` added to return the index of a structure in a chain. * Updated Readme.md.
Updated `Changes Required` section.
* ManagedChain holds structures in unmanaged memory, preventing their movement, and it can be safely held on the heap itself. * It allows for easy modification and manipulation of the chain.
`ManagedChain` now supports 2-16 chain items.
Can now easily append an item to an existing `ManagedChain` to efficiently create a new `ManagedChain`.
`ManagedChain` now has a constructor that will load an unmanaged chain allowing it to be safely stored on the heap.
Also improved loading to detect when the unmanaged chain is too long.
Also added the new blank proposals.
Proposal - Vulkan Struct Chaining - #1 StructureType correction.md
* Restored targets for PrototypeStructChaining.csproj to match `Silk.Net.Vulkan` targets. * Upped the generated `ManageChain<T...` to 16.
* IChainable now exposes `Chain* PNext` property. * Added `ManagedChain<TChain>` as smallest chain (just the head) * All `IntPtr`s are replaced with `nint`s. * Pointer offsets are calculated once per chain type and stored in statics, meaning that a chain contains a single `nint` field internally, making it incredibly lightweight. Getting the sizes once may also improve the performance, and has simplified the code. * Various fixes to ensure tail always has `PNext` set to `null` (0). * Added `Truncate` instance methods.
Also cleaned up some tests.
* Added the `Extensions`, `Extenders`, `ClrTypes` and `StructureTypes` dictionaries to `Chain`. * Added the `ClrType`, `StructureType`, `IsChainStart`, `IsChainable`, `CanExtend` and `CanBeExtendedBy` extension methods to `ChainExtensions`. * Finished Proposal dotnet#4 on Chaining Metadata extension.
* Sets all chain elements (optionally excluding the head) to their default value.
* Implicit conversion added to convert to `nint`, `void*` and `BaseInStructure*` to convert to a pointer to the head of the chain, for all `Chain` classes, including the abstract base `Chain`. * Implicit conversion added to convert to `TChain*` for the concrete `Chain<TChain...>` classes. * Added missing license header to interfaces
Fixed namespace for `Silk.NET.Vulkan.Test` tests.
Perksey
requested changes
Dec 1, 2021
...Lab/Experiments/PrototypeStructChaining/.idea/.idea.PrototypeStructChaining/.idea/.gitignore
Outdated
Show resolved
Hide resolved
* Also added operator overloads.
|
Also can you please do a full BuildTools run before continuing (this may pull in unrelated changes, but that's fine as I'll know not to look in the folders that aren't Vulkan or OpenXR) primarily so I can grasp the implications of this on OpenXR. Finally feel free to add a blog post in website/blog:
Thanks. |
* Removed implemented proposals * Renamed Metadata proposal (as this will remain on hold and isn't in the scope of this PR) * Added Chaining UML class diagram * Updated TOCs * Documented Managed chaining * Added correct summary comments to `Chain` equality operator overloads.
As I mentioned in the Working Group, I'm not confident doing this and I still have quite a few projects not building on my dev machine due to dependencies. I also have to have quite a lot of projects unloaded for the solution to be workable. @HurricanKai suggested he'd be happy to do a
I plan on finishing the documentation and PR today/tomorrow to give it a chance of making the next release. Once it gets merged I'll happily write a blog post. Hopefully, you will find the documentation pretty extensive. |
|
Ah no worries, I'll run BuildTools full now. |
Co-authored-by: Dylan Perks <11160611+Perksey@users.noreply.github.com>
Co-authored-by: Dylan Perks <11160611+Perksey@users.noreply.github.com>
Co-authored-by: Dylan Perks <11160611+Perksey@users.noreply.github.com>
…pproved' into feature/vulkan-struct-chaining/approved
Added finalizer and `GC.SuppressFinalize(this)` when disposing explicitly.
`BuildTools` deletes all `.gen.cs` files which can cause collisions.
* Removed the Unmanaged Chaining proposal as implemented.
* No longer allocates a `StringBuilder` when no `out string errors` is required. * Added CS0661 suppression to `Chain` base class, as `GetHashCode()` is correctly overriden in concrete descendents.
HurricanKai
approved these changes
Dec 3, 2021
There was a problem hiding this comment.
It's very difficult to review this, due to GitHub almost crashing, but I've looked at the Chaining implementation and it lgtm.
@Perksey I think the BuildTools stuff looks good as well, but that's your expertise
Perksey
approved these changes
Dec 3, 2021
This was referenced Dec 3, 2021
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary of the PR
Full implementation of Vulkan Struct chaining Proposals 1, 2 and 3.
(Note, this replaces the following PRs: #676, #680, #683, #693)
Related issues, Discord discussions, or proposals
Further Comments
Proposals 1-3 were approved in a Working Group meeting held at 19:00 UTC on 29 November 2021. Proposal 4, is on hold awaiting a more compelling use case.
TODOs(Completed)IListInsertandRemoveAtbeing unnecessarily complex additions, may add in future, but unlikely due to explosion of method overloads that would be required, or reflection to create types dynamically.IExtendsChain<out TChain>constraint onTChain, currentlyIChainable, should it beIChainStart?Fixed, the looserIChainablein only required on*Anymethods, this interface should have the tighter constraint.IChainabletype extends any other, this is useful when you are dealing with 'loosely constrained' types - as happens with the managedChain.ManagedCacheManagedChaintoChainManagedChain.AppendtoAddAdd, just updated the proposal.Marshal(e.g.Marshal.StructureToPtr)structconstraints tounmanagedto make it safe to blit the structures straight into memory - which should improve speed even further.MemoryCopyoperations.ManagedChain(Add,Duplicate,Truncate)ChaintoChain.csfor easier maintenance.AddAny,DuplicateandTruncateAnyinstance methods toChainto allow for easier manipulation of runtime chains.*Anyoverloads after agreement in Discord. This is to indicate their alignment with the 'less-constrained'*Anyextension methods they use.MaximumCountproperty toChainto indicate the currently supported maximum (16).Currently, instance methods call the static extension methods to perform the building. Previously the logic was moved into the statics to reduce the code, however, we may consider moving it back to instance methods (and have the extension methods call the instance methods again). For now, it was much quicker to implement this way.Add,DupliacateandTruncatemethods back into instance.Silk.Net.Vulkan.Testsand include chain tests.Chain.Clear(bool includeHead)method to conveniently clear out a chain.Chainclasses tonint,void*,BaseInStructure*andTChain*.IEquatable<Chain>toChain.(Probagbly to thewebsite)documentation/structure-chainingbased on Discord chat.Chain.LoadAny(TChain)method that is implemented directly and does not create aStringBuilder.Lead Reviewer: @Perksey (BuildTools), @HurricanKai (Vulkan)