Skip to content

Home

Jump to bottom
zalan-racz-gaijin edited this page Jun 19, 2024 · 7 revisions

This is the wiki of the Dagor Shader Language Server.

About this wiki

The goal of this wiki is to make it easier to understand how this project works. When I explain something, I try to give you some context, but I won't describe the underlying technologies in detail. For this, most pages have a Useful resources section, where you can find links that give you more in-depth explanations. In these wiki pages, I'd like to focus on the project structure, ideas behind decisions, tips, and tricks.

The language server

This is a language server which can be used to add language support features for DSHL and HLSL to any IDEs that support the Language Server Protocol. If you want to know more about the language server's features, read the README.md file. The language server is published under the BSD-3 license, which you can read in the LICENSE file. Extension that use this language server are already available for VS Code, and for Visual Studio. They are published in the Visual Studio Marketplace, and the Visual Studio Code Marketplace, but you can install them directly from your IDE.

Language Server Protocol

The Language Server Protocol is basically a specification which standardizes IDE features like code completion, formatting, go to definition, etc. It splits the execution to 2 parts: the client and the server. The client is an IDE-specific extension which starts the language server and sends requests towards it as the user interacts with the source code. The language server (don't confuse it with web servers) answers those requests. This means that although the client is IDE-specific, it's very thin and the language server does the heavy lifting, like analyzing the source code. The Language Server Protocol has many advantages:

  • the language server runs in a different process, therefore it won't block the IDE if the analyzation takes a lot of time
  • the communication is standardized, so the language server doesn't have to know the IDE's API and doesn't have to be written in the same language
  • don't have to write the language features for all the IDEs, you have to write the language server only once, and all client can use it

TODO

  • Make the shader compiler work with stdio. This way diagnostics could work when you type, and you don't have to save the file to see the errors. Also, if it's possible, it'd be good to add HLSL errors.
  • Usually upgrading the dependencies are trivial, but ESLint requires a new configuration format, but there is a migrator
  • Call hierarchy, it could work with functions, function-like defines, and macros.
  • Add missing descriptions to DSHL, and HLSL language constructs.
  • Add unit tests to the project.
  • Favorites in code completion: add a ⭐, and put some items on the top of the list. Maybe add the frequently used things, like float3, or make it user configurable.
  • Signature help for function-like defines.
  • Support mountPoint in .blk files, where include directories are defined. For example this is valid now: mountPoint:t="../../../prog/"
  • Support implicit conversions. At the moment function arguments have to match perfectly to function parameters.
  • Support material properties. Material is provided in code completion, but other features, like hover or document highlights don't work with it. Example: material.texture.diffuse
  • Support multiple declarations. At the moment only macros support multiple declarations, but for example functions can have multiple prototypes as well.
  • Support function prototypes.
  • Support user created member functions.
  • Support constructors.
  • Support function and operator overloading.
  • Support templates.
  • Support swizzles, like some_variable.xyz.
  • Support namespaces and fully qualified names.
  • Support typedefs.
  • Add all language construct to semantic highlight.
  • VS Code supports markdown, while Visual Studio doesn't. So, at the moment code completion and hover uses plain text for descriptions. Make VS Code display markdown.
  • Cache DSHL includes/macros during preprocessing, because they can't change without changing the file.
  • If something, like a variable was declared inside of a macro, but used outside of the macro, go to definition sometimes leads to the wrong location. Fix it.
  • Resolve include folder only once per analysis, because they can't change.
  • Find all references and rename for macro parameters.
  • Support all the built-in defines.
  • Add the member functions of the built-in RayQuery type.
  • Rename and find all references at the moment work only inside of the file. Make it work in the whole workspace. It's a bit tricky, because you have to take into account all (more than a thousand) shader files. But there is a work done progress mechanic in the Language Server Protocol.
  • Add the workspace symbols feature. It works the same way as the document symbols, but for the whole workspace. Similar problem and solution like in rename and find all references.
  • Add code actions.
  • Add code lens: for example struct alignment and paddings or something similar.
  • Add half targets to snippets.
  • Optimization
  • Refactoring

Reporting bugs

If you find a bug, create an issue, but please give me as much information as possible. If it's not obvious, what's the cause of the problem, please include information, like the operating system, create screenshots or videos, or anything that might be helpful.

Useful resources

Clone this wiki locally