Jump to content

  • Log In with Google      Sign In   
  • Create Account

Banner advertising on our site currently available from just $5!

1. Learn about the promo. 2. Sign up for GDNet+. 3. Set up your advert!

HlslUnit released: a new unit testing library for HLSL shaders

Old topic!
Guest, the last post of this topic is over 60 days old and at this point you may not reply in this topic. If you wish to continue this conversation start a new topic.

  • You cannot reply to this topic
4 replies to this topic

#1 Tim J   Members   -  Reputation: 261


Posted 07 January 2014 - 10:59 AM

I'm pleased to announce the release of the first version of HlslUnit, a unit testing library library for HLSL shaders:




HlslUnit is an open source .NET library that allows you to test your HLSL shaders in isolation, without running your game or application. It executes shaders entirely on the CPU, using an interpreter, and doesn't touch the GPU. Here's an example unit test:

public void CanExecuteVertexShader()
  // Arrange.
  var shader = new Shader(ShaderTestUtility.CompileShader(
    "Shaders/VS/BasicHLSL.fx", "RenderSceneVS", "vs_4_0"));
  shader.SetConstantBuffer("$Globals", new VertexConstantBufferGlobals
    World = Matrix.Identity,
    WorldViewProjection =
      Matrix.LookAtRH(Vector3.UnitZ, Vector3.Zero, Vector3.UnitY) *
      Matrix.PerspectiveFovRH(MathUtil.PiOverFour, 1, 1, 10)
  var vertexInput = new VertexShaderInput
    Position = new Vector4(3, 0, 2, 1),
    Normal = new Vector3(0, 1, 0),
    TexCoords = new Vector2(0, 1)

  // Act.
  var output = shader.Execute<VertexShaderInput, VertexShaderOutput>(vertexInput);

  // Assert.
  Assert.That(output, Is.EqualTo(new VertexShaderOutput
    Position = new Vector4(7.24264f, 0, -3.222222f, 1),
    Normal = new Vector3(0, 1, 0),
    TexCoords = new Vector2(0, 1)

I know HLSL and unit tests aren't the most exciting of topics, but I like the idea of bringing automated testing to HLSL code, and hopefully I'm not alone!

Edited by Tim J, 07 January 2014 - 11:00 AM.


#2 Starnick   Members   -  Reputation: 1404


Posted 07 January 2014 - 03:33 PM

Wow. Very neat!

#3 ViperMeat   Members   -  Reputation: 111


Posted 08 January 2014 - 11:32 AM

I will definitely be checking this out

#4 MJP   Moderators   -  Reputation: 14044


Posted 08 January 2014 - 01:24 PM

That's pretty awesome, especially the bytecode interpreter!

#5 Tim J   Members   -  Reputation: 261


Posted 09 January 2014 - 10:19 AM

Thank you for the comments!


The most challenging part of implementing an HLSL interpreter was getting dynamic branching working. Because I wanted to emulate GPUs reasonably closely - in particular, running pixel shaders on a 2x2 quad so that partial derivative instructions (ddx, ddy) work correctly - I needed to support running multiple threads at the same time. But that means that when the interpreter executes a conditional branch instruction, some threads might take the branch, and some might not (as it happens, partial derivative instructions don't work inside dynamic branches, but still, I wanted to support multiple threads in general). So just like a real GPU (to the best of my limited knowledge) I execute both branches, and 'mask' the threads that aren't active for the given branch.


In order to make that work, I needed to rewrite the bytecode instructions into the form of basic blocks, where each block has a single entry point and a single exit point. Then, when taking a branch, the interpreter knows the index of the instruction where the branches will come back together. It uses that information to mask / unmask threads. It was quite 'fun' getting it figured out! In case anyone's interested, here are the papers / websites I learnt from:


SlimShader, the library that actually does most of the heavy lifting for HlslUnit, has a GUI tool that visualises how the instructions are broken down into basic blocks. You can load up the compiled binary for any shader you like (as long as it was compiled for SM4.0 or SM5.0), and see the corresponding control flow - which may (or may not! I only have a vague idea what happens at the hardware level) be similar to the shader code pre-processing that the GPU does.


By the way, the (C#) code for SlimShader, SlimShader.VirtualMachine and HlslUnit is here:



(Incidentally, in addition an HLSL interpreter, I also wrote a JITter, which compiles a new C# class on the fly, for a particular shader. But I don't use the JITter in HlslUnit, because the compilation time is too long when the shader is only getting executed once. I *do* use the JITter in my software rasterizer (https://github.com/tgjones/rasterizr), because it's a lot faster than the interpreter when rendering multiple frames.)




Old topic!
Guest, the last post of this topic is over 60 days old and at this point you may not reply in this topic. If you wish to continue this conversation start a new topic.