diff options
| -rw-r--r-- | README.md | 96 | ||||
| -rw-r--r-- | appveyor.yml | 4 | ||||
| -rw-r--r-- | docs/api-users-guide.md | 494 | ||||
| -rw-r--r-- | docs/command-line-slangc.md | 131 | ||||
| -rw-r--r-- | docs/faq.md | 42 | ||||
| -rw-r--r-- | docs/language-guide.md | 104 |
6 files changed, 857 insertions, 14 deletions
@@ -2,39 +2,107 @@ [](https://ci.appveyor.com/project/shader-slang/slang/branch/master) -Slang is a library for compiling real-time shader code. -It can be used with either existing HLSL or GLSL code, or with code written directly in Slang. -The library provides a variety of services that application developers can use to put together the shader compilation workflow they want. +Slang is a library and a stand-alone compiler for wroking with real-time shader code. +It can be used with existing HLSL or GLSL code, but also supports a new HLSL-like shading language, also called Slang. +The library provides a variety of services that support applications in putting together their own shader compilation workflows. -Services provided by the Slang library include: +Using Slang you can: -* Slang can scan ordinary HLSL or GLSL code that neglects to include `register` or `layout` bindings and "rewrite" that code to include explicit bindings for all shader parameters. This lets you write simple and clean code, but still get deterministic binding locations. +* Take ordinary HLSL or GLSL code that neglects to include all those tedious `register` and `layout` bindings, and transform it into code that includes explicit bindings on every shader parameter. This frees you to write simple and clean code, while still getting completely deterministic binding locations. -* Slang provides a full reflection API for shader parameters, with a uniform interface across HLSL, GLSL, and Slang. The reflection system does not silently drop unused/"dead" parameters, and it can even be used on libraries of shader code without compiling any entry points. +* Get full reflection information about the parameters of your shader code, with a consistent API interface across GLSL, HLSL, and Slang code. Slang doesn't silently drop unused or "dead" shader parameters from the reflection data, so you can always see the full picture. -* *Work in progress:* Slang supports cross-compilation of either HLSL or Slang code to GLSL. +* Cross-compile shader code written in the HLSL-like Slang shading language to HLSL, GLSL, DX bytecode, or SPIR-V. You can even write ordinary HLSL or GLSL by hand that makes use of libraries of code written in Slang. -* You can directly get HLSL or GLSL source code as output from Slang, or you can let the library invoke lower-level code generation for you to get back DXBC or SPIR-V (DXIL support to come). +## Getting Started + +There are several ways that you can get started using Slang, depending on how complex your application's needs are. + +Right now Slang only supports Windows builds (32- and 64-bit). + +### Binary releases + +Pre-built binary packages for the stand-alone Slang compiler and a DLL of the Slang library are available through GitHub [releases](https://github.com/shader-slang/slang/releases). + +### Building from source + +If you would like to build Slang from source, then clone [this](https://github.com/shader-slang/slang) repository, and then run: + + git submodule update --init + +Next, open `slang.sln` and build your desired platform/configuration. + +### Integrating the source into your build + +If you want to statically link Slang into your application, instead of having to deal with a dynamic library, then the easiset option is to just integrate Slang into your build. + +First, clone the Slang repostiory (or download a source [release](https://github.com/shader-slang/slang/releases)) and add the root folder of the slang repository/release to your include path. +Then in one `.cpp` file in your project, write: + +```c++ +#define SLANG_INCLUDE_IMPLEMENTATION +#include <slang.h> +``` + +This causes the `slang.h` header to `#include` all the source files that make up the Slang compiler implementation. + +Note that this option does *not* currently include support for generating SPIR-V output, unless you build the `slang-glslang` dynamic library separately. ## Documentation -TODO +The Slang [language guide](docs/language-guide.md) provides information on extended language features that Slang provides for user code. -## Getting Started +The [API user's guide](docs/api-users-guide.md) gives information on how to drive Slang programmatically from an application. + +If you want to try out the `slangc` command-line tool, then you will want to read its [documentation](docs/command-line-slangc.md). +Be warned, however, that the command-line tool is primarily intended for experimenting, testing, and debugging; serious applications will likely want to use the API interface. + +## Limitations + +The Slang project is in a very early state, so there are many rough edges to be aware of. +Slang is *not* currently recommended for production use. +The project is intentionally on a pre-`1.0.0` version to reflect the fact that interfaces and features may change at any time (though we try not to break user code without good reason). + +Major limitations to be aware of (beyond everything files in the issue tracker): + +* Slang only supports outputting GLSL/SPIR-V for Vulkan, not OpenGL + +* Slang's current approach to automatically assigning registers is appropriate to D3D12, but not D3D11 -TODO +* Slang-to-GLSL cross-compilation only supports vertex, fragment, and compute shaders. Geometry and tessellation shader cross-compilation is not yet implemented. -## Testing +* The Slang front-end does best-effort checking of HLSL input, and only supports very minimal checking of GLSL. When using these languages, the `-no-checking` option can be used to allow Slang to work with these files even when it gets confused by constructs it doesn't support. -TODO +* Translations from Slang/HLSL constructs to GLSL equivalents has been done on as as-needed basis, so it is likely that new users will run into unimplemented cases. ## Contributing -TODO +If you'd like to contribute to the project, we are excited to have your input. +We don't currently have a formal set of guidelines for contributors, but here's the long/short of it: + +* Please follow the contributor [Code of Conduct](CODE_OF_CONDUCT.md). +* Bugs reports and feature requests should go through the GitHub issue tracker +* Changes should ideally come in as small pull requests on top of `master`, coming from your own personal fork of the project +* Large features that will involve multiple contributors or a long development time should be discussed in issues, and broken down into smaller pieces that can be implemented and checked in in stages ## Contributors +If you contribute changes to the library, please feel free to add (or remove/update/change) your name here. + * Yong He * Haomin Long * Teguh Hofstee * Tim Foley +* Kai-Hwa Yao + +## License + +The Slang code itself is under the MIT license (see [LICSENSE](LICENSE)). + +The Slang projet can be compiled to use the [`glslang`](https://github.com/KhronosGroup/glslang) project as a submodule (under `external/glslang`), and `glslang` is under a BSD licesnse. + +The Slang tests (which are not distributed with source/binary releases) include example shaders extracted from: +* A [repository](https://github.com/SaschaWillems/Vulkan) of Vulkan GLSL shaders by Sascha Willems, which are under the MIT license +* Sample HLSL shaders from the Microsoft DirectX SDK, which has its own licesnse + +Some of the Slang examples and tests use the `stb_imgae` and `stb_image_write` libraries (under `external/stb`) which have been placed in the public domain by their author(s). diff --git a/appveyor.yml b/appveyor.yml index 5b6596b8d..65d444eb8 100644 --- a/appveyor.yml +++ b/appveyor.yml @@ -87,9 +87,13 @@ after_build: 7z a "$env:SLANG_BINARY_ARCHIVE" bin\*\*\slang.lib 7z a "$env:SLANG_BINARY_ARCHIVE" bin\*\*\slang-glslang.dll 7z a "$env:SLANG_BINARY_ARCHIVE" bin\*\*\slangc.exe + 7z a "$env:SLANG_BINARY_ARCHIVE" docs\*.md 7z a "$env:SLANG_SOURCE_ARCHIVE" slang.h 7z a "$env:SLANG_SOURCE_ARCHIVE" source\*\*.h 7z a "$env:SLANG_SOURCE_ARCHIVE" source\*\*.cpp + 7z a "$env:SLANG_SOURCE_ARCHIVE" docs\*.md + 7z a "$env:SLANG_SOURCE_ARCHIVE" README.md + 7z a "$env:SLANG_SOURCE_ARCHIVE" LICENSE # Register the created .zip file as an artifact with AppVeyor diff --git a/docs/api-users-guide.md b/docs/api-users-guide.md new file mode 100644 index 000000000..6f89852e9 --- /dev/null +++ b/docs/api-users-guide.md @@ -0,0 +1,494 @@ +Slang API User's Guide +====================== + +This document is intended to guide user's who want to integrate Slang into their application programmatically. +It covers issues around building and linking Slang, as well as giving an overview of the main API functionality. + +Preliminaries +------------- + +Before using the Slang API, you'll need to link Slang into your application. +There are multiple ways you can do this: + +### Integrating the source into your build + +By far the simplest option if you just want to get up and running quickly, without fussing with dynamic libraries, is to integrate the Slang source files into your build. +The Slang project is packaged in a way that tries to make this easy: + +* Either clone the Slang repository, or download a source release +* Add the root folder of the repository/release to your include path +* In one `.cpp` file in your path, make sure to define `SLANG_INCLUDE_IMPLEMENTATION` before including `slang.h`: + +```c++ +#define SLANG_INCLUDE_IMPLEMENTATION +#include <slang.h> +``` + +This causes the `slang.h` header to `#include` all the source files that make up the Slang compiler implementation. + +Note that this option does *not* currently include support for generating SPIR-V output. +You can of course download or buld `slang-glslang` separately, if you want Slang's SPIR-V output, or you can just have Slang generate GLSL, and hten pass that on to whatever tool(s) you are using for GLSL today. + +### Binary releases + +Pre-built binary packages for the stand-alone Slang compiler and a DLL of the Slang library are available through GitHub [releases](https://github.com/shader-slang/slang/releases). + +Just add the downloaded package to your include path, and make sure to add (or copy) the `slang.dll` and `slang-glslang.dll` libraries into the path of your executable. + +When using a binary release, you'll need to define the `SLANG_DYNAMIC` macro to indicate that you want to dynamically link against the API functions: + +```c++ +#define SLANG_DYNAMIC +#include <slang.h> +``` + +### Building from source + +If you would like to build Slang from source, you will currently need Visual Studio 2015. +Clone [this](https://github.com/shader-slang/slang) repository, and then run: + + git submodule update --init + +Next, open `slang.sln` and build your desired platform/configuration. + +As with the binary distriution, you'll need to set the `SLANG_DYNAMIC` option when including the Slang header: + +```c++ +#define SLANG_DYNAMIC +#include <slang.h> +``` + +Getting Started with the API +---------------------------- + +### Include the Header + +In order to use the Slang API, you'll need to include its header: + +```c +#include <slang.h> +``` + +While the Slang implementation is C++, the header exposes a pure C interface (plus a few wrappers that only get defined for C++). + +### Create a Session + +All interactions with the Slang API are under the control of a *session*, represented by the type `SlangSession`: + +```c++ +SlangSession* session = spCreateSession(NULL); +``` + +You can think of the session as owning resources that can be re-used across multiple compiles. +Most notably this includes the shader "standard library," which will be parsed and checked when you first create a session. +By re-using a session across multiple files, you can avoid paying the cost of loading the standard library multiple times. + +When you are done with a session, you'll want to destroy it to free up these resources: + +```c++ +spDestroySession(session); +``` + +**Warning**: The Slang library currently isn't reentrant, and Bad Things will happen if you try to create more than one session at a time. + +### Create a Compile Request + +A *compile request* represents an interaction where you ask Slang to compile one or more files for you, and produce some output. +A `SlangCompileRequest` object is used both to hold the input for the request (what files and entry points you want to compile), and to communicate back output (error messages and/or code). + +You can create a request using an existing session: + +```c++ +SlangCompileRequest* request = spCreateCompileRequest(session); +``` + +When you are done with the request you will need to destroy it to free resources: + +```c++ +spDestroyCompileRequest(request); +``` + +### Specify Compilation Options + +#### Code Generation Target + +When invoking the compiler, it is important to specify what kind of code you'd like Slang to generate. +This is done using the `SlangCompileTarget` options. +For example, to request output as SPIR-V binary code: + +```c++ +spSetCodeGenTarget(request, SLANG_SPIRV); +``` + +#### Include Paths + +If you will be passing files with `#include` directives to Slang, you'll need to specify where it should look for those files: + +```c++ +spAddSearchpath(request, "some/path/"); +``` + +Note that for now Slang does not support any kind of "virtual filesystem," although that is obviously a desirable feature to add. + +#### Preprocessor Definitions + +If you want any kind of preprocessor macros to be defined when compiling your code, you can add global macro definitions to the compile request: + +```c++ +spAddPreprocessorDefine(request, "ENABLE_FOO", "1") +``` + +Note that Slang currently doesn't provide an automatic definition like `__SLANG__` to identify the compiler, so you might want to do that manually, if you need to have files that are processed by Slang and other tools. + +```c++ +spAddPreprocessorDefine(request, "__SLANG__", "1") +``` + +### Specify Input Code and Entry Points + +Once you've made your global configuration of the compile request, it is time to start adding source code. +The Slang model is that a compile request involves one or more *translation units*, each of which may comprise one or more *source files* (or strings), and which might define one or more *entry points*. + +In the case of HLSL or GLSL code, each translation unit will usually have only a single source file or string. +In the case of GLSL, a translation unit will only expose a single entry point. + +#### Translation Units + +To add a translation unit to the compile request: + +```c++ +int translationUnitIndex = spAddTranslationUnit(request, SLANG_SOURCE_LANGUAGE_HLSL, ""); +``` + +The first argument is the compile request. +The second argument is the source language for the translation unit (you may not have a single translation unit that mixes source files in different languages). +The last argument is an optional name for the translation unit; Slang currently doesn't do anything with this value. + +The `spAddTranslationUnit` function returns the zero-based index of the translation unit you added. +You don't need to use this return value, because it will be deterministic (the first translation unit gets `0`, the next gets `1`, etc.), but the API returns it in case it saves you from having to track it with your own counter. +The translation unit index is used in subsequent API calls taht modify or query the translation unit. + +#### Source Files/Strings + +Once you've created a translation unit, you can add source code to it. +Source code can either come from a file or a string: + +```c++ +spAddTranslationUnitSourceFile(request, translationUnitIndex, "some/file.hlsl"); + +// or: + +spAddTranslationUnitSourceString( + request, + translationUnitIndex, + "file.hlsl", + "/* source code */ ..."); +``` + +Note that even in the case where you provide a string, you need to provide a file name (even a made-up one) so that Slang can use it in error messages. + +#### Entry Points + +Once you've added source code to your translation unit, you can specify which entry point(s) you want to compile in the translation unit: + +```c++ +int entryPointIndex = spAddEntryPoint( + request, + translationUnitIndex, + "main", + profileID); +``` + +This adds an entry point to be compiled to the compilation `request`. +An entry point named `"main"` will be looked up in translation unit `translationUnitIndex` and code will be generated based on the given `profileID` (a value of type `SlangProfileID`). + +In order to get a profile to use, you'll typically want to look one up by name: + +```c++ +SlangProfileID profileID = spFindProfile(session, "ps_5_0"); +``` + +The names of profiles passed to this function are the same as are available for command-line [`slangc`](command-line-slangc.md). + +Like `spAddTranslationUnit`, `spAddEntryPoint` returns a zero-based index for the entry point. +Note that this index is for all entry points in the compile request (not per-translation-unit). + +### Compiling and Checking Diagnostics + +With all the setup out of the way, it is finally time to actually compile things: + +```c++ +int anyErrors = spCompile(request); +``` + +The `spCompile` function will compile all the translation units and entry points you specified. +If any errors were encountered during compilation, then `spCompile` will return a non-zero result. +To find out what went wrong, you can get a null-terminated log of error messages with: + +```c++ +char const* diagnostics = spGetDiagnosticOutput(request); +``` + +The diagnostic output will also contain any warnings produced, even if the compilation didn't have any errors. +Note that the returned pointer is guaranteed to live at least as long as the compile request, but no longer. +If you need to retain the data for later use, then you must make your own copy. + +If any errors occured, you shouldn't expect to read any useful output (other than the diagnostics) from the request; you should destroy it and move on. + +### Reading Output Code + +If you compilation was successful, then you probably want to extract the output code that was generated. +Slang provides access to the generated code for each entry point: + +```c++ +size_t dataSize = 0; +void const* data = spGetEntryPointCode(request, entryPointIndex, &dataSize); +``` + +As a shorthand, if you expect the output to be textual source-code: + +```c++ +char const* code = spGetEntryPointSource(request, entryPointIndex); +``` + +Note that the pointer returned by these functions is guaranteed to remain live as long as the compileRequest is alive, but no longer. +If you need to retain the output code for longer, you need to make a copy. + +### Reflection Information + +If a compilation is successful, Slang also produces reflection information that the application can query: + +```c++ +SlangReflection* reflection = spGetReflection(request); +``` + +Note that just as with output code, the reflection object (and all other objects queried from it) is guaranteed to live as long as the request is alive, but no longer. +Unlike the other data, there is no easy way to save the reflection data for later user (we do not currently implement serialization for reflection data). +Applications are encouraged to extract whatever information they need before destroying the compilation request. + +For convenience (since the reflection API surface area is large), the Slang API provides a C++ wrapper interface around the reflection API, and this document will show code examples using those wrappers: + +```c++ +slang::ShaderReflection* shaderReflection = slang::ShaderReflection::get(request); +``` + +#### Program Reflection + +When looking at the whole program (`slang::ShaderReflection`) we can enumerate global-scope shader parameters: + +```c++ +unsigned parameterCount = shaderReflection->getParameterCount(); +for(unsigned pp = 0; pp < parameterCount; pp++) +{ + slang::VariableLayoutReflection* parameter = + shaderReflection->getParameterByIndex(pp); + // ... +} +``` + +We can also enumerate the compile entry points, in order to inspect their parameters: + +```c++ +SlangUInt entryPointCount = shaderRefelction->getEntryPointCount(); +for(SlangUInt ee = 0; ee < entryPointCount; ee++) +{ + slang::EntryPointReflection* entryPoint = + shaderReflection->getEntryPointByIndex(ee); + // ... +} +``` + +Slang's reflection API does not currently expose by-name lookup of parameters, but this is obviously a desirable feature. + +#### Variable Layouts + +In the Slang reflection API, we draw a distinction between a *variable* (a particular declaration in the code), from a *variable layout* which has been laid out according to some API-specific rules. +It is possible for the same variable (e.g., a `struct` field) to be laid out multiple times, with different results (e.g., if the same `struct` type is used both for a `cbuffer` member and a varying shader `in` parameter). + +For most purposes, a `VariableLayoutReflection` represents what a shading language user thinks of as a "shader parameter." +We can query a parameter for its name: + +```c++ +char const* parameterName = parameter->getName(); +``` + +An application will typically want to know where a parameter got "bound." +In the simple case, we can query this information directly: + +```c++ +slang::ParameterCategory category = parameter->getCategory(); +unsigned index = parameter->getBindingIndex(); +unsigned space = parameter->getBindingSpace(); +``` + +For a simple global-scope "resource" parameter (e.g., HLSL `Texture2D t : register(t3)`) the `category` tells what kind of resource the parameter consumes (e.g., `slang::ParameterCategory::ShaderResource`), the `index` gives the register number (`3`), and `space` gives the register "space" (`0`) as added for D3D12. + +In the case of SPIR-V output a binding index corresponds to the `binding` layout qualifier, and the binding space corresponds to the `set`. +The main difference from D3D is that the `category` will usually be `slang::ParameterCategory::DescriptorTableSlot`. + +Textures, samplers, and constant buffers all follow this same basic pattern. +For uniform parameters (e.g., members of an HLSL `cbuffer`), the binding "space" is unused, the category is `slang::ParameterCategory::Uniform`, and the "index" is the byte offset of the parameter in its parent. + +The above are the simple cases, where a parameter only consumes a single kind of resource. +In HLSL, however, we can do things like combine textures, samplers, and uniform values in a `struct` type, so given a parameter of such a type, the reflection API needs to be able to report appropriate layout information for each of the different categories of resource. + +If `getCategory()` returns `slang::ParameterCategory::Mixed`, then the user can query additional information: + +```c++ +unsigned categoryCount = parameter->getCategoryCount(); +for(unsigned cc = 0; cc < categoryCount; cc++) +{ + slang::ParameterCategory category = parameter->getCategoryByIndex(cc); + + size_t offsetForCategory = parameter->getOffset(category); + size_t spaceForCategory = parameter->getBindingSpace(category); + + // ... +} +``` + +A loop like this lets you enumerate all of the reosurce types consumed by a parameter, and get a starting offset (and space) for each category. + +#### Type Layouts + +Just knowing where a shader parameter *starts* is only part of the story, of course. +We also need to know how many resources (e.g., registers, bytes of uniform data, ...) it consumes, how many elemnets it occupies (if it is an array), and what "sub-parameters" it might include. + +For these kinds of queries, we need to look at the *type layout* of a parameter: + +```c++ +slang::TypeLayoutReflection* typeLayout = parameter->getTypeLayout(); +``` + +Just as with the distinction between a variable and a variable layout, a type layout represents a particular type in the source code that has been laid out according to API-specific rules. +A single type like `float[10]` might be laid out differently in different contets (e.g., using GLSL `std140` vs. `std430` rules). + +The first thing we want to know about a type is its *kind*: + +```c++ +slang::TypeReflection::Kind kind = typeLayout->getKind(); +``` + +The available cases for `slang::TypeReflection::Kind` include `Scalar`, `Vector`, `Array`, `Struct`, etc. + +For any type layout, you can query the resources it consumes, or a particular parameter category: + +```c++ +// query the number of bytes of constant-buffer storage used by a type layout +size_t sizeInBytes = typeLayout->getSize(slang::ParameterCategory::Uniform); + +// query the number of HLSL `t` registers used by a type layout +size_t tRegCount = typeLayout->getSize(slang::ParameterCategory::ShaderResource); +``` + +##### Arrays + +If you have a type layout with kind `Array` you can query information about the number and type of elements: + +```c++ +size_t arrayElementCount = typeLayout->getElementCount(); +slang::TypeLayoutReflection* elementTypeLayout = typeLayout->getElementTypeLayout(); +sie_t arrayElementStride = typeLayout->getElementStride(category); +``` + +An array of unknoqn size will currently report zero elements. +The "stride" of an array is the amount of resources (e.g., the number of bytes of uniform data) that need to be skipped between consecutive array elements. +This need *not* be the same as `elementTypeLayout->getSize(category)`, and there are two notable cases to be aware of: + +- An array in a constant buffer may have a stride larger than the element size. E.g., a `float a[10]` in a D3D or `std140` constant buffer will have 4-byte elements, but a stride of 16. + +- An arrray of resources in Vulkan will have a stride of *zero* descriptor-table slots, because the entire array is allocated a single `binding`. + +##### Structures + +If you have a type layout with kind `Struct`, you can query information about the fields: + +```c++ +unsigned fieldCount = typeLayout->getFieldCount(); +for(unsigned ff = 0; ff < fieldCount; ff++) +{ + VariableLayoutReflection* field = typeLayout->getFieldByIndex(ff); + // ... +} +``` + +Each field is represented as a full variable layout, so application code can recursively extract full information. + +An important caveat to be aware of when recursing into structure types like this, is that the layout information on a field is relative to the start of the parent type layout, and not absolute. +This is perhaps not surprising in the case of `slang::ParameterCategory::Uniform`: if you ask a field in a `struct` type for its byte offset, it will return the offset from the start of the `struct`. + +Where this can trip up users is when a `struct` type containss fields of other categories (e.g., a structure with a `Texture2D` in it). +In these cases, the "binding index" of a structure field in a relative offset from whatever binding index is given to the parent structure. + +The basic rule is that no matter what category of binding resource (bytes, registers, etc.) you are talking about, the index/offset of `a.b.c` must be computed by adding together the offsets of `a`, `b` and `c`. + +#### Entry Points + +Given an `EntryPointReflection` we can query its name and stage: + +```c++ +char const* entryPointName = entryPoint->getName(); +SlangStage stage = entryPoint->getStage(); +``` + +You can also enumerate the parameters of the entry point (that is, those that were written as parameters of the entry-point function): + +```c++ +unsigned parameterCount = entryPoint->getParameterCount(); +for(unsigned pp = 0; pp < parameterCount; pp++) +{ + slang::VariableLayoutReflection* parameter = + entryPoint->getParameterByIndex(pp); + // ... +} +``` + +In the case of a compute shader entry point, you can also query the user-specified thread-group size (if any): + +```c++ +SlangUInt threadGroupSize[3]; +entryPoint->getComputeThreadGruopSize(3, &threadGroupSize[0]); +``` + +### Checking Dependencies + +If you are implementing some kind of "hot reload" system for shaders, then you probably need to know what files on disk a particular compilation request ended up depending on. +Slang provides a simple API for enumerating these, on a successful compile: + +```c++ +int depCount = spGetDepenencyFileCount(request); +for(int dep = 0; dep < depCount; dep++) +{ + char const* depPath = spGetDependencyFilePath(request, dep); + // ... +} +``` + +This will enumerate all file paths that were referenced by the compile, either directly through the API or via a `#include` directive. + +### Setting Other Options + +There are other compilation options that are more specialized, and less often used. + +If HLSL or GLSL input code uses constructs that Slang doesn't understand (that is, it is giving spurious error messages) it may be possible to make progress by suppressing Slang's semantic checking for these languages: + +```c++ +spSetCompileFlags(request, SLANG_COMPILE_FLAG_NO_CHECKING); +``` + +If you are trying to debug shader compilation issues in a large application, it may be helpful to have Slang dump all the intermediate code it generates to disk: + +```c++ +spSetDumpIntermediates(request, true); +``` + +If you don't like the way that Slang adds `#line` directives to generated source code, you can control this behavior: + +```c++ +spSetLineDirectiveMode(request, SLANG_LINE_DIRECTIVE_MODE_NONE); +``` + + + + + diff --git a/docs/command-line-slangc.md b/docs/command-line-slangc.md new file mode 100644 index 000000000..1762874c0 --- /dev/null +++ b/docs/command-line-slangc.md @@ -0,0 +1,131 @@ +Using the `slangc` Command-Line Compiler +======================================== + +The `slangc` command-line tool is used to compile or cross-compile shader source code. + +``` +slangc [<options>] <file1> [<file2>...] + +``` + +Simple Examples +--------------- + +### GLSL + +To compile a GLSL fragment shader and write SPIR-V assembly to the console: + + slangc my-shader.frag + +To output binary SPIR-V to disk, use: + + slangc my-shader.frag -o my-shader.spv + +### HLSL + +When compiling an HLSL shader, you must also specify the "profile" to use. +To see D3D bytecode assembly for a fragment shader entry point: + + slangc my-shader.hlsl -profile ps_5_0 + +To direct that output to a bytecode file: + + slangc my-shader.hlsl -profile ps_5_0 -o my-shader.dxbc + +If the entry-point function has a name other than the default `main`, then this is specified with `-entry`: + + slangc my-shader.hlsl -profile ps_5_0 -entry psMain + +### Slang + +Compiling an entry point from a Slang file is similar to HLSL, except that you must specify the profile, the entry-point name, *and* the code generation target. + +To get DXBC assembly written to the console: + + slangc my-shader.slang -profile ps_5_0 -entry main -target dxbc + +To get SPIR-V assembly: + + slangc my-shader.slang -profile ps_5_0 -entry main -target spriv + +The code generation target is implicit when writing to a file with an appropriate extension. +To write DXBC and SPIR-V to files, use: + + slangc my-shader.slang -profile ps_5_0 -entry main -o my-shader.dxbc + slangc my-shader.slang -profile ps_5_0 -entry main -o my-shader.spv + +Cross-Compilation +----------------- + +When the input file is written in Slang (or the subset of HLSL that Slang currently understands) it is possible to cross-compile to GLSL (and on to SPIR-V), e.g.: + + slangc my-shader.slang -profile ps_5_0 -entry main -o my-shader.glsl + slangc my-shader.slang -profile ps_5_0 -entry main -o my-shader.spv + +Multiple Entry Points +--------------------- + +If you are taking advantage of Slang's ability to automatically assign binding locations to shader parameters (textures, buffers, etc.), then you may need to specify multiple entry points or even multiple files in one compiler invocation. + +When compiling HLSL or Slang code, you might have multiple entry points in one file. +In this case, specify the entry-point-specific options after the file, and make sure that the `-profile` option and any `-o` option precedes the corresponding `-entry` option: + + slangc my-shader.hlsl -profile vs_5_0 -o my-shader.vs.dxbc -entry vsMain + -profile ps_5_0 -o my-shader.ps.dxbc -entry psMain + +If you want to compile multiple GLSL entry points in one pass, you will need multiple files. It is also required to fully specify the profile and entry-point name in this mode. + + slangc my-shader.vert -profile glsl_vertex -o my-shader.vert.spv -entry main + my-shader.frag -profile glsl_fragment -o my-shader.frag.spv -entry main + +These command lines obviously aren't pleasant, but we expect that most applications that need this level of complexity will be using the API. +The ability to specify compilation actions like this on the command line is primarily intended a testing and debugging tool. + +Options +------- + +For completeness, here are the options that `slangc` currently accepts: + +* `-D <name>[=<value>]`: Insert a preprocessor macro definition + * The space between `-D` and `<name>` is optional + * If no `<value>` is specified, Slang will define the macro with an empty value + +* `-entry <name>`: Specify the name of the entry-point function + * In single-file compiles for HLSL/GLSL, this defaults to `main` + * Multiple `-entry` options may appear on the command line. When they do, the input file path, `-profile` option, and `-o` option that apply for an entry point are each the first one found when scanning to the left from the `-entry` option. + +* `-I <path>`: Add a path to be used in resolving `#include` and `__import` operations + * The space between `-I` and `<path>` is optional + +* `-o <path>`: Specify a path where generated output should be written + +* `-pass-through <name>`: Don't actually perform Slang parsing/checking/etc. on the input and instead pass it through more or less modified to the existing compiler `<name>`" + * `fxc`: Use the `D3DCompile` API as exposed by `d3dcompiler_47.dll` + * `glslang`: Use Slang's internal version of `glslang` as exposed by `slang-glslang.dll` + * These are intended for debugging/testing purposes, when you want to be able to see what these existing compilers do with the "same" input and options + +* `-profile <profile>`: Specify the language "profile" to use. This is a combination of the pipeline stage (vertex, fragment, compute, etc.) and an abstract feature level. E.g., the `ps_5_0` profile specifies the fragment stage, with the Direc3D "Shader Model 5" feature level. To summarize the available profiles: + * The D3D profiles of the form `{cs,ds,gs,hs,ps,vs}_{4_0,4_1,5_0}` are supported + * The D3D profiles of the form `{vs,ps}_4_0_level_9_{0,1,3}` are supported + * Profiles of the form `glsl_{vertex,tess_control,tess_eval,geometry,fragment,compute}_<version>` are supported for all GLSL language versions where the corresponding stage is supported (e.g., there is a `glsl_fragment_110`, but the earliest compute profile is `glsl_compute_430`) + * As a convenience profiles of the form `glsl_{vertex,tess_control,tess_eval,geometry,fragment,compute}` are provided that are intended to map to the latest version of GLSL known to the Slang compiler (curently `450`) + +* `-no-checking`: Disable semantic checking as much as possible, or all files and entry points specified. Has no effect on Slang files, but will suppress many of Slang's error checks on HLSL/GLSL files. You may still get error messages when the code in those files is passed along to a downstream compiler like `fxc` or `glslang`. + +* `-target <target>`: Specifies the desired code-generation target. Values for `<target>` are: + * `glsl`: GLSL source code + * `hlsl`: HLSL source code + * `spirv`: SPIR-V intermediate language binary. + * `spirv-assembly`: SPIR-V intermediate language assembly + * `dxbc`: Direct3D shader bytecode binary + * `dxbc-assembly`: Direct3D shader bytecode assembly + * `reflection-json`: A dump of shader parameter information in JSON format. This is only intended for using in debugging/testing at present. + * `none`: Don't generate output code (but still perform front-end parsing/checking) + +* `--`: Stop parsing options, and treat the rest of the command line as input paths + +Limitations +----------- + +A major limitation of the `slangc` command today is that there is no provision for getting both compiled code *and* reflection data out in a single invocation. +For now, the command-line tool is best seen as a debugging/testing tool, and all serious applications should drive Slang through the API. diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 000000000..2859eebf1 --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,42 @@ +Frequently Asked Questions +========================== + +### How did this project start? + +The Slang project forked off from the ["Spire"](https://github.com/spire-lang/spire) shading language research project. +In particular, Slang aims to take the lessons learned in that research effort (about how to make more productive shader compilation languages and tools) and apply them to a stystem that is easier to adopt, and hopefully moreamenable to production use. + +### Why should I use Slang instead of glslang, hlsl2glslfork, the Microsoft open-source HLSL compiler, etc.? + +If you are mostly just shoping around for a tool to get HLSL shaders working on other graphics APIs, then [this](http://aras-p.info/blog/2014/03/28/cross-platform-shaders-in-2014/) blog post is probably a good place to start. + +If one of those tools meets your requirements, then you should probably use it. +Slang is a small project, and early in development, so you might find that you hit fewer bumps in the road with one of the more established tools out there. + +The goal of the Slang project is not to make "yet another HLSL-to-GLSL translator," but rather to create a shading language and supporting toolchain that improves developer productivity (and happiness) over the existing HLSL language and toolchain, while providing a reasonable adoption path for developers who have an existing investment in HLSL shader code. +If you think that is something interesting and worth supporting, then please get involved! + +### What would make a shading language more productive? + +This is probably best answered by pointing to the most recent publication from the Spire research project: + +[Shader Components: Modular and High Performance Shader Development](http://graphics.cs.cmu.edu/projects/shadercomp/) + +Some other papers for those who would like to read up on our inspiration: + +[A System for Rapid Exploration of Shader Optimization Choices](http://graphics.cs.cmu.edu/projects/spire/) +[Spark: Modular, Composable Shaders for Graphics Hardware](https://graphics.stanford.edu/papers/spark/) + +### Who is using Slang? + +Right now the only user of Slang is the [Falcor](https://github.com/NVIDIA/Falcor) real-time rendering framework developed and used by NVIDIA Research. +The implementation of Slang has so far focused heavily on the needs of Falcor. + +### Won't we all just be using C/C++ for shaders soon? + +The great thing about both Vulkan and D3D12 moving to publicly-documented binary intermediate langugaes (SPIR-V and DXIL, respectively) is that there is plenty of room for language innovation on top of these interfaces. + +Having support for writing GPU shaders in a reasonably-complete C/C++ language would be great. +We are supportive of efforts in the "C++ for shaders" direction. + +The Slang effort is about trying to solve the challenges that are unique to the real-time graphics domain, and that won't magically get better by switching to C++. diff --git a/docs/language-guide.md b/docs/language-guide.md new file mode 100644 index 000000000..a388e70f3 --- /dev/null +++ b/docs/language-guide.md @@ -0,0 +1,104 @@ +Slang Language Guide +==================== + +This document will try to describe the main characteristis of the Slang language that might make it different from other shading languages you have used. + +The Basics +---------- + +Slang is similar to HLSL, and it is expected that many HLSL programs can be used as Slang code with no modifications. +Big-picture stuff that is supported: + +* A C-style preprocessor +* Ordinary function, `struct`, `typedef`, etc. declarations +* The standard vector/matrix types like `float3` and `float4x4` +* The less-used explicit `vector<T,N>` and `matrix<T,R,C>` types +* `cbuffer` declarations for uniform parameters +* Global-scope declarations of texture/sampler parameters, including with `register` annotations +* Entry points with varying `in`/`out` parameters using semantics (including `SV_*` system-value semantics) +* The built-in templated resource types like `Texture2D<T>` with their object-oriented syntax for sampling operations +* Attributes like `[unroll]` are parsed, and passed along for HLSL/DXBC output, but dropped for other targets +* `struct` types that contain textures/samplers as well as ordinary uniform data, both as function parameters and in constant buffers + +New Features +------------ + +Right now the Slang language only has one major feature that is different from existing HLSL (that will change over time). + +### Import Declarations + +In order to support better software modularity, and also to deal with the issue of how to integrate shader libraries written in Slang into other langauges, Slang introduces an `__import` declaration construct. + +The basic idea is that if you write a file `foo.slang` like this: + +``` +// foo.slang + +float4 someFunc(float4 x) { return x; } +``` + +you can then import this code into another file in Slang, HLSL, or GLSL: + +``` +// bar.glsl + +__import foo; + +vec4 someOtherFunc(vec4 y) { return someFunc(y); } +``` + +The simplest way to think of it is that the `__import foo` declaration instructs the compiler to look for `foo.slang` (in the same search paths it uses for `#include` files), and give an error if it isn't found. +If `foo.slang` is found, then the compiler will go ahead and parse and type-check that file, and make any declarations there visible to the original file (`bar.glsl` in this example). + +When it comes time to generate output code, Slang will output any declarations from `__import`ed files that were actually used (it skips those that are never referenced), and it will cross-compile them as needed for the chosen target. + +A few other details worth knowing about `__import` declarations: + +* The name you use on the `__import` line gets translated into a file name with some very simple rules. An underscore (`_`) in the name turns into a dash (`-`) in the file name, and dot separators (`.`) turn into directory seprators (`/`). After these substitutions, `.slang` is added to the end of the name. + +* If there are multiple `__import` declarations naming the same file, it will only be imported once. This is also true for nested imports. + +* Currently importing does not imply any kind of namespacing; all global declarations still occupy a single namespace, and collisions between different imported files (or between a file and the code it imports) are possible. This is a bug. + +* If file `A.slang` imports `B.slang`, and then some other file does `__import A;`, then only the names from `A.slang` are brought into scope, not those from `B.slang`. This behavior can be controlled by having `A.slang` use `__exported __import B;` to also re-export the declarations it imports from `B`. + +* An import is *not* like a `#include`, and so the file that does the `__import` can't see preprocessor macros defined in the imported file (and vice versa). Think inf `__import foo;` as closer to `using namspace foo;` in C++ (perhaps without the same baggage). + +On that last point, if you really do want something that is like `__import` but interacts with the preprocessor more like `#include` then you can try using `#import`: + +``` +#import "foo.slang" +... +``` + +The `#import` directive is recognized during preprocessing, so macro definitions from the importing file will affect the imported code, and vice versa. +The rules about multiple imports still apply, though, so only the first `#import` encountered will determine the text that is parsed (be careful). +Please think of `#import` as a stopgap for when you want the cross-compilation benefits of `__import`, but need to deal with code that depends on macros in the here and now. + +Future Extensions +----------------- + +Longer term we would like to make Slang a much more advanced language, and indeed the implementation already has some of the underpinnings for more powerful things. + +The most important feature we plan to add is support for "constrained generics" as they appear in C#, Rust, and Swift. +For those of you with a C++ background you could think of this as "templates + concepts", but without many of the rought edges. + +Using constrained generics as an underlying mechanism, we then plan to introduce a feature similar in capability to Cg's "interfaces" feature, to allow shaders to express more flexible patterns of composition and dispatch. + + +Not Supported +------------- + +Some things are not supported, but probably will be given enough time/resources: + +* Local variables of texture/sampler type (or that contain these) +* Matrix swizzles +* Object-oriented extensions for putting methods inside `struct` types +* Explicit `packoffset` annotations on members of `cbuffer`s + +Some things from HLSL are *not* planned to be supported, unless there is significant outcry from users: + +* Pre-D3D10/11 syntax and operations +* The "effect" system, and the related `<>` annotation syntax +* Explicit `register` bindings on textures/samplers nested in `cbuffer`s +* Any further work towards making HLSL a subset of C++ (simply because implementing a full C++ compiler is way out of scope for the Slang project) |