.spvSPIR-V file that can be loaded into a vulkan compute shader.
gosl implements Go as a shader language for GPU compute shaders: converts Go code to HLSL, and then uses the glslc compiler (e.g., from a vulkan package) to compile into an
.spv SPIR-V file that can be loaded into a vulkan compute shader.
glslc must be installed!
gosl enables the same CPU-based Go code to also be run on the GPU. The relevant subsets of Go code to use are specifically marked using
//gosl: comment directives, and this code must only use basic expressions and concrete types that will compile correctly in a shader (see Restrictions below). Method functions and pass-by-reference pointer arguments to
struct types are supported and incur no additional compute cost due to inlining (see notes below for more detail).
examples/axon examples (simple and much more complicated, respectively), using the vgpu Vulkan-based GPU compute shader system.
You must also install
goimports which is used on the extracted subset of Go code:
$ go install golang.org/x/tools/cmd/goimports@latest
To install the
gosl command, do:
$ go install github.com/goki/gosl@latest
In your Go code, use these comment directives:
//gosl: start <filename> < Go code to be translated > //gosl: end <filename>
to bracket code to be processed. The resulting converted code is copied into a
shaders subdirectory created under the current directory where the
gosl command is run, using the filenames specified in the comment directives. Each such filename should correspond to a complete shader program (i.e., a “kernel”), or a file that can be included into other shader programs. Code is appended to the target file names in the order of the source .go files on the command line, so multiple .go files can be combined into one resulting HLSL file.
HLSL specific code, e.g., for the
main compute function or to specify
#include files, can be included either by specifying files with a
.hlsl extension as arguments to the
gosl command, or by using a
//gosl: hlsl comment directive as follows:
//gosl: hlsl <filename> // <HLSL shader code to be copied> //gosl: end <filename>
where the HLSL shader code is commented out in the .go file – it will be copied into the target filename and uncommented. The HLSL code can be surrounded by
*/ comment blocks (each on a separate line) for multi-line code (though using a separate
.hlsl file is preferable in this case).
.hlsl files, their filename is used to determine the
shaders destination file name, and they are automatically appended to the end of the corresponding
.hlsl file generated from the
Go files – this is where the
main function and associated global variables should be specified.
.spv files are removed from the
shaders directory prior to processing to ensure everything there is current – always specify a different source location for any custom
.hlsl files that are included.
gosl [flags] [path ...]
The flags are:
-exclude string comma-separated list of names of functions to exclude from exporting to HLSL (default "Update,Defaults") -out string output directory for shader code, relative to where gosl is invoked (default "shaders") -keep keep temporary converted versions of the source files, for debugging
Note: any existing
.go files in the output directory will be removed prior to processing, because the entire directory is built to establish all the types, which might be distributed across multiple files. Any existing
.hlsl files with the same filenames as those extracted from the
.go files will be overwritten. Otherwise, you can maintain other custom
.hlsl files in the
shaders directory, although it is recommended to treat the entire directory as automatically generated, to avoid any issues.
gosl path args can include filenames, directory names, or Go package paths (e.g.,
github.com/goki/mat32/fastexp.go loads just that file from the given package) – files without any
//gosl: comment directives will be skipped up front before any expensive processing, so it is not a problem to specify entire directories where only some files are relevant. Also, you can specify a particular file from a directory, then the entire directory, to ensure that a particular file from that directory appears first – otherwise alphabetical order is used.
gosl ensures that only one copy of each file is included.
struct types encountered will be checked for 16-byte alignment of sub-types and overall sizes as an even multiple of 16 bytes (4
int32 values), which is the alignment used in HLSL and glsl shader languages, and the underlying GPU hardware presumably. Look for error messages on the output from the gosl run. This ensures that direct byte-wise copies of data between CPU and GPU will be successful. The fact that
gosl operates directly on the original CPU-side Go code uniquely enables it to perform these alignment checks, which are otherwise a major source of difficult-to-diagnose bugs.
In general shader code should be simple mathematical expressions and data types, with minimal control logic via
for statements, and only using the subset of Go that is consistent with C. Here are specific restrictions:
Can only use
[u]int32, and their 64 bit versions for basic types, and
structtypes composed of these same types – no other Go types (i.e.,
string, etc) are compatible. There are strict alignment restrictions on 16 byte (e.g., 4
float32’s) intervals that are enforced via the
bool– it defines a Go-friendly interface based on a
int32basic type. Using a
structcauses an obscure
shaderc: internal error: compilation succeeded but failed to optimize: OpFunctionCall Argument <id> '73[%73]'s type does not match Function
Alignment and padding of
structfields is key – this is automatically checked by
HLSL does not support enum types, but standard go
constdeclarations will be converted. Use an
uint32data type. It will automatically deal with the simple incrementing
iotavalues, but not more complex cases. Also, for bitflags, define explicitly, not using
HLSL does not do multi-pass compiling, so all dependent types must be specified before being used in other ones, and this also precludes referencing the current type within itself. todo: can you just use a forward declaration?
HLSL does not provide the same auto-init-to-zero for declared variables – safer to initialize directly:
val := float32(0) // guaranteed 0 value var val float32 // not guaranteed to be 0! avoid!
Cannot use multiple return values, or multiple assignment of variables in a single
Can use multiple variable names with the same type (e.g.,
min, max float32) – this will be properly converted to the more redundant C form with the type repeated.
Random numbers: slrand
See slrand for a shader-optimized random number generation package, which is supported by
gosl – it will convert
slrand calls into appropriate HLSL named function calls.
gosl will also copy the
slrand.hlsl file, which contains the full source code for the RNG, into the destination
shaders directory, so it can be included with a simple local path:
//gosl: hlsl mycode // #include "slrand.hlsl" //gosl: end mycode
With sufficiently large N, and ignoring the data copying setup time, around ~80x speedup is typical on a Macbook Pro with M1 processor. The
rand example produces a 175x speedup!
Implementation / Design Notes
HLSL is very C-like and provides a much better target for Go conversion than glsl. See
examples/basic/shaders/basic_nouse.glsl vs the .hlsl version there for the difference. Only HLSL supports methods in a struct, and performance is the same as writing the expression directly – it is suitably inlined.
While there aren’t any pointers allowed in HLSL, the inlining of methods, along with the use of the
inout InputModifier, effectively supports pass-by-reference. The stackoverflow on this is a bit unclear but the basic example demonstrates that it all goes through.
Key docs for HLSL as compute shaders:
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.