The Shader Debugger

The shader debugger lets you interactively edit FShade shaders in your Aardvark application.

How to use

Add a package reference to FShade.Debug and call FShade.Debug.ShaderDebugger.attach() at the start of your program. In the console you will see all projects that have been located by the debugger. Once the debugger has been attached any effects, raytracing effects, and compute shaders that are created will be registered for on-the-fly editing.

When you modify any file of a project that contains a registered shader, the project will be recompiled automatically. Once the build has completed successfully, every affected shader will be updated and reinjected into your application.

Limitations

• Only individual shaders can be modified on the fly, effect compositions are fixed. For example, if you compose an effect from shaderA, shaderB, and shaderC via Effect.compose or Sg.shader, you will not be able to change that composition afterwards. Only, the individual shaders shaderA, shaderB, and shaderC can be edited. The same holds true for raytracing effects.

• The F# compiler is painfully slow, so dependencies between projects are disregarded. Changes in files of a project will be ignored even if their values are used in shaders of another project. This avoids long rebuild chains and minimizes the time required for recompilation. If you develop a complex shader, it may be reasonable to (temporarily) move it to a small separate project to reduce compilation times even further.

• Symbol files (*.pdb) are used to determine the original location of the shaders. If you use shaders from a Nuget package, the paths in the accompanying symbol files will probably be invalid for your machine. In this case, registration will fail with a warning:

  WARNING: Cannot find shader definition for D:\a\aardvark.rendering\aardvark.rendering\src\Aardvark.Rendering\Effects\Default\Impl\SgColor.fs (10,12).

  If you are not interested in editing those shaders, the warnings can be safely ignored. Otherwise, you can build the corresponding projects locally and copy the assemblies and symbol files to your application's output folder.

• Shaders must be functions. For example, a simple miss shader for shadow rays may be defined as:

  let missShadow =
      miss { return false }

  The debugger will not be able to resolve this shader and output a warning:

  WARNING: Failed to resolve shader <StartupCode$36 - Raytracing>.$Program..cctor

  This can be avoided by defining the shader as a parameterless function:

  let missShadow() = . . .

• The parameters of the shader function must not change. For example, an intersection shader for equal-sized spheres may be defined with a parameter for the radius:

  let intersectionSphere (radius : float) (input : RayIntersectionInput) =
    intersection { . . . }

  When the shader is updated, the function will be invoked with the arguments that were passed when the corresponding effect was created. If the signature has changed, an exception will be thrown.

• Interface changes to compute shaders are generally not allowed. This is because the interface layout is used to create input bindings, which cannot be modified afterwards. If the interface of the updated shader is incompatible, a warning is printed and the updated shader is ignored. Some interface changes are permitted, for example removing the last field of a uniform buffer.

Known issues

• The shader debugger copies assemblies of project dependencies to the output folder before starting the build process. Unfortunately, dotnet build does not seem to search the output folder to resolve assemblies when targeting net6.0 or later. Instead, they are expected to be in the respective obj folders for the Debug configuration. If this is not the case, you may see an error similar to:

  FSC : error FS0078: Unable to find the file 'C:\aardvark.base\src\Aardvark.Base\obj\Debug\net6.0\ref\Aardvark.Base.dll' in any of↔ C:\Program Files\dotnet\packs\Microsoft.NETCore.App.Ref\6.0.20\ref\net6.0↔ C:\aardvark.base\src\Aardvark.Base.FSharp↔ C:\Program Files\dotnet\sdk\7.0.306\FSharp\

  As a workaround, build the affected projects manually with the Debug configuration.