Add in the shader authoring guide chapter. #333
Conversation
(cherry picked from commit 3eb823c)
|
I know @SaschaWillems already wrote a whole chapter around this "area" so want him approval Also @swoods-nv would also be great to review |
swoods-nv
left a comment
swoods-nv
left a comment
There was a problem hiding this comment.
My main overarching comment is that I'd recommend caution when phrasing migration from HLSL->Slang as "upgrading" or similar. Vulkan consciously chooses not to have an official shading language, and both Slang and HLSL continue to evolve and gain new features.
|
There is def. some duplication here. The chapters I did are:
The latter was written with additional shading languages in mind. So maybe it's better to
A separate chapter that kinda combines what we have + slang might be confusing. |
|
Okay, sounds good, I'll try to move things around. |
|
Btw. the official slang docs do have migration guides, so maybe something we could link to: |
|
Good call on using those links, I'll add it in. The next version will have a lot of copy pasting to place the details in the right place. Should have a new version once I finish reviewing all changes. |
… slang.adoc to match hlsl.adoc
|
Alright, significant copy/pasting and reorganizing into the existing structure. I don't think I lost any of the details I wrote in the original version. However, hopefully that's closer to where things should go. |
# Conflicts: # README.adoc
|
|
||
| With link:https://github.com/microsoft/DirectXShaderCompiler/blob/main/docs/SPIR-V.rst#unsupported-hlsl-features[a few exceptions], all Vulkan features and shader stages available with GLSL can be used with Slang too, including recent Vulkan additions like hardware accelerated ray tracing. On the other hand, Slang to SPIR-V supports Vulkan exclusive features that are not (yet) available in DirectX. | ||
|
|
||
| image::{images}what_is_spirv_dxc.png[what_is_spriv_dxc.png] |
There was a problem hiding this comment.
not sure why this is here, feels unrelated to Slang
spencer-lunarg
left a comment
spencer-lunarg
left a comment
There was a problem hiding this comment.
- Adding Slang to the
high_level_shader_language_comparison.adocpage is great (I often know a term in in GLSL and need to look up the Slang equivalent) - Will wait for @SaschaWillems approval on the HLSL additions added
- Will wait for @swoods-nv for a re-read and approval on the new Slang chapter
| * Be mindful of matrix layout differences | ||
| * Consider using a shader generation system | ||
|
|
||
| === Performance Optimization |
There was a problem hiding this comment.
Everything after (and including) this chapter (up to the conclusion) isn't specific to HLSL. Might be better to move this to a separate chapter.
| * *Consider push constants*: Use push constants for frequently changing small data | ||
| * *Be mindful of SPIR-V limitations*: Some HLSL features may not translate directly to SPIR-V | ||
|
|
||
| == Migration from GLSL to HLSL |
There was a problem hiding this comment.
A lof ot content in this chapter is a duplication of what's already present in the high level shading language chapter. Might be better to just link to that instead.
|
|
||
| [[hlsl-in-vulkan]] | ||
| = HLSL in Vulkan | ||
| :toc: |
There was a problem hiding this comment.
Any reason this was explicitly added? Antora already takes care o the toc, this might lead to a duplicated toc in the docs site build.
| float4x4 projection; | ||
| }; | ||
| [[vk::binding(0, 0)]] | ||
| ConstantBuffer<SceneUBO> ubo; |
There was a problem hiding this comment.
If this is meant to show a portable shader, register notation should be added.
| struct Input | ||
| { | ||
| float3 position : POSITION; | ||
| float3 normal : NORMAL; |
There was a problem hiding this comment.
Afaik you can skip pretty much all of those semantics all along in Slang. I don't use stuff like NORMAL, TEXCOORDn, etc. in my samples with Slang.
| }; | ||
| // Declare a parameter block with explicit binding | ||
| [[vk::binding(0, 0)]] |
There was a problem hiding this comment.
Afaik the whole idea behind parameter blocks is that you DON'T need to specify explicit bindings anymore.
|
That's a lot of text to review ^^ Added a few comments. One of the things that IMO needs more attention is Skang's ability to automatically generate binding slots. For me, that was one of the best things about Slang, and while you can somehow find that information in this PR I'd like to see that more explicitly stated. |
| [[educational-resources]] | ||
| == Educational resources | ||
|
|
||
| For Slang, the official link:https://github.com/shader-slang/slang[GitHub repository] and link:https://docs.shader-slang.org/en/latest/[documentation] are the best resources to get started. |
There was a problem hiding this comment.
Not sure if it's worth mentioning here, but the Slang Discord is an additional resource; this can be especially helpful if you are troubleshooting.
|
|
||
| == Differences Between HLSL and Slang | ||
|
|
||
| While Slang is built on HLSL and maintains backward compatibility, it adds several powerful features that make shader development more efficient, maintainable, and flexible. |
There was a problem hiding this comment.
One more "backward compatibility" here that should get softened.
|
|
||
| === Compilation Differences | ||
|
|
||
| Slang provides its own compiler (`slangc`) with different capabilities than the HLSL compiler: |
There was a problem hiding this comment.
Might be worth mentioning the runtime compilation API here as well
|
|
||
| == Migration Guide: from HLSL to Slang | ||
|
|
||
| Migrating from HLSL to Slang can be done incrementally, as Slang maintains backward compatibility with HLSL. This guide provides a step-by-step approach to migrating your shaders. |
| slangc -profile glsl_spirv -entry main -o output.spv input.slang | ||
| ---- | ||
|
|
||
| For HLSL compatibility mode: |
There was a problem hiding this comment.
I believe there's also a GLSL full-compatibility flag (but can't remember the specific cases that it's required for -- in general, Slang can handle most GLSL without the flag. The migration Slang doc page might have more info.)
4 participants
No description provided.