Tutorial: Vulkan GLSL Ray Tracing Emulator

The Vulkan GLSL Ray Tracing Emulator is an online application that aims to simulate the ray tracing shader pipeline from the Vulkan GL EXT ray tracing specification.

To this end, a pre-compiler is provided that translates the ray tracing shader code into a classic WebGL GLSL fragment shader, which generates a direct preview of the shader's output image in the browser.

Most importantly, the emulator also allows exporting the ray tracing shader code as a C++ Vulkan project that can fully exploit the dedicated ray tracing acceleration hardware available in recent graphics cards (such as Nvidia Geforce RTX GPUs or the AMD RX 6000 series).

The web-based emulator is intended for computer graphics education or rapid prototyping of GLSL ray tracing shaders. It does not require a high-end GPU with special ray tracing hardware. Only if you want to run the exported C++ Vulkan stand-alone application, a GPU with ray tracing accelerator hardware is necessary.

To keep the interface as simple and accessible as possible, the online emulator provides only a limited choice of pre-defined 3D meshes and textures. However, the ray tracing shader code from the emulator can be exported as a Vulkan C++ project or as a node graph for the GSN Composer. Both export options allow changing the loaded 3D meshes and textures.

Because this tutorial complies with the standardized GLSL ray tracing specification, it is not specific to the online ray tracing emulator. Hopefully, it provides a simple entry point to the Vulkan GLSL ray tracing pipeline in general.

The Standardized Ray Tracing Pipeline

The ray tracing pipeline consists of 5 different shaders:

Ray Generation
Closest-Hit
Miss
Intersection
Any-Hit

Roughly speaking, the pipeline works as follows.

The ray generation shader creates rays and submits them to the "acceleration structure traversal" block (see figure above) by calling the function traceRayEXT(...). The ray traversal block is the non-programmable part of the pipeline. The most important parameter of the traceRayEXT function is the payload variable that contains the collected information of the ray. The payload variable is of user-defined type and can be modified in the shaders stages that are called for a particular ray during its traversal. Once the ray traversal is complete, the traceRayEXT function returns to the caller and the payload can be evaluated in the ray generation shader to produce an output image.

If the ray traversal detects an intersection of the ray with a user-defined bounding box (or triangle of a triangle mesh), the intersection shader is called. If the intersection shader determines that a ray-primitive intersection has occurred within the bounding box, it notifies the ray traversal with the function reportIntersectionEXT(...). Furthermore, the intersection shader can fill a hitAttributeEXT variable (which can be of user-defined type). In the case of triangles, an intersection shader is already built-in. The built-in triangle intersection provides barycentric coordinates of the hit location within the triangle with the "hitAttributeEXT vec2 baryCoord" variable. For geometric primitives that are not triangles (such as cubes, cylinders, spheres, parametric surfaces, etc.) you have to provide your custom intersection shader.

If an intersection is reported and an any-hit shader is provided, the any-hit shader is called. The task of the any-hit shader is to accept or ignore a hit. A typical application for an any-hit shader is to handle a partly transparent surface. If the hit occurs in a transparent region, it should be ignored. A hit is ignored with the ignoreIntersectionEXT statement. It is also possible to terminate the ray traversal in the any-hit shader with the terminateRayEXT statement. If no any-hit shader is provided or the ignoreIntersectionEXT statement is not called in the shader, the hit is reported to the ray traversal.

Once the ray traversal has determined all possibles hits along the ray and at least one hit has occurred, the closest-hit shader is called for the closest one of these hits. Otherwise, if no hit occurred, the miss shader is called (see figure above). Both types of shaders can manipulate the ray payload. For example, the miss shader could submit the color of the environment into the payload and the closest-hit shader could compute the shading color for the hit surface. To this end, the closest-hit shader can access several built-in variables, such as the gl_PrimitiveID or the gl_InstanceID that are set accordingly for each hit. A full list of built-in variables is provided below.

The closest-hit and miss shader can also call the traceRayEXT function, which submits another ray into the ray traversal block and might create a recursion (see figure above). A typical application in the closest-hit shader is shooting a "shadow" ray in the direction of the light source to determine if the light is occluded by other objects. As this ray might trigger another call of the closest-hit shader, a recursion is created. In general, it it is recommended to keep the number of recursive function calls as low as possible for best performance. The emulator will internally unroll these recursions because a classic WebGL GLSL fragment shader does not support recursive function calls.

Built-In Variables

	Ray generation	Closest-hit	Miss	Intersection	Any-hit
`uvec3 gl_LaunchIDEXT`	✓	✓	✓	✓	✓
`uvec3 gl_LaunchSizeEXT`	✓	✓	✓	✓	✓
`int gl_PrimitiveID`		✓		✓	✓
`int gl_InstanceID`		✓		✓	✓
`int gl_InstanceCustomIndexEXT`		✓		✓	✓
`int gl_GeometryIndexEXT`		✓		✓	✓
`vec3 gl_WorldRayOriginEXT`		✓	✓	✓	✓
`vec3 gl_WorldRayDirectionEXT`		✓	✓	✓	✓
`vec3 gl_ObjectRayOriginEXT`		✓		✓	✓
`vec3 gl_ObjectRayDirectionEXT`		✓		✓	✓
`float gl_RayTminEXT`		✓	✓	✓	✓
`float gl_RayTmaxEXT`		✓	✓	✓	✓
`uint gl_IncomingRayFlagsEXT`		✓	✓	✓	✓
`float gl_HitTEXT`		✓			✓
`uint gl_HitKindEXT`		✓			✓
`mat4x3 gl_ObjectToWorldEXT`		✓		✓	✓
`mat4x3 gl_WorldToObjectEXT`		✓		✓	✓

Built-In Constants

const uint gl_RayFlagsNoneEXT = 0u;

const uint gl_RayFlagsNoOpaqueEXT = 2u;

const uint gl_RayFlagsTerminateOnFirstHitEXT = 4u;

const uint gl_RayFlagsSkipClosestHitShaderEXT = 8u;

const uint gl_RayFlagsCullBackFacingTrianglesEXT = 16u;

const uint gl_RayFlagsCullFrontFacingTrianglesEXT = 32u;

const uint gl_RayFlagsCullOpaqueEXT = 64u;

const uint gl_RayFlagsCullNoOpaqueEXT = 128u;

const uint gl_HitKindFrontFacingTriangleEXT = 0xFEu;

const uint gl_HitKindBackFacingTriangleEXT = 0xFFu;

TLAS and BLAS

The 3D scene is represented by the acceleration structure that is used in the acceleration structure traversal block. As shown in the image below, the acceleration structure consists of a top-level acceleration structure (TLAS) and multiple bottom-level acceleration structures (BLAS). Each BLAS can be either a triangle mesh or a user-defined collection of axis-aligned bounding boxes (AABBs).

A BLAS can be instantiated in the TLAS and gets a unique gl_InstanceID. Furthermore, each triangle in a triangle mesh and each AABB in the collection of intersection boxes gets a consecutive gl_PrimitiveID.

Each BLAS has its transformation from object to world space, which is initially assigned when the BLAS is added to the TLAS. This transformation is accessible in the shader via the gl_ObjectToWorldEXT and gl_WorldToObjectEXT variables.

When a hit occurs in the ray traversal and the intersection, any-hit, or closest-hit shader is called, these mentioned variables are set accordingly.

TLAS

BLAS

gl_ObjectToWorldEXT

gl_WorldToObjectEXT

gl_InstanceID = 0

gl_InstanceID = 1

gl_InstanceID = 2

Triangle Mesh

Intersection Boxes

Example 1: Ray Tracing "Hello, World!"

This first minimal example consists only of a ray generation shader that is called for each pixel of the image and writes a color value into that pixel.

In the Vulkan GLSL Ray Tracing Emulator this is achieved with the following code:

// gsnShaderOptions: precompiler="GL_EXT_ray_tracing, recursion: 2, app: 1"
// IMPORTANT: do not remove the line above

/**** ABOUT ****/
// A minimal example

/**** COMMON START ****/
// In the COMMON section, the structs "RayPayloadType" and "HitAttributeType" must be defined.
// Furthermore, your own helper functions must be defined here (can be called in all shaders).

struct RayPayloadType {
  vec3 color; // unused
}; // type of the "payload" variable

struct HitAttributeType {
  vec3 normal; // unused
}; // type of the "hit" variable

/**** COMMON END ****/

// Ray tracing shaders must be defined in the following order:
// ray generation, closest-hit, miss, intersection, any-hit

void main() { /**** RAY GENERATION SHADER ****/
  // set RGBA color
  gsnSetPixel(vec4(1.0, 1.0, 0.0, 1.0));
}

All commented lines are not necessary, except for the first line, which invokes the pre-compiler. Consequently, if you like it as short as possible, this code works as well:

// gsnShaderOptions: precompiler="GL_EXT_ray_tracing, recursion: 2, app: 1"
struct RayPayloadType {
  vec3 color;
};

struct HitAttributeType {
  vec3 normal;
};

void main() {
  gsnSetPixel(vec4(1.0, 1.0, 0.0, 1.0));
}