Built‐ins

Built-in contextual values

GPULang doesn't provide global variables for built-in values such as gl_Position, neither does it utilize HLSL style semantics to assign a built-in usage of a variable. Instead, GPULang provides a suite of functions that allows the user to read or write to the GPU state for such those built-in values.

GPULang reserves the prefix 'gpl' to be used by GPULang. User-made functions with the same prefix will trigger the compiler to emit an error.

Scalar types include:

i32, i32x2, i32x3, i32x4

f32, f32x2, f32x3, f32x4

u32, u32x2, u32x3, u32x4

literal means the value is compile time evaluated, and must therefore be a compile time resolvable value.

Name	Function	Compatible Shaders
gplSetOutputLayer(i32) void	Sets the output layer for a multilayered framebuffer output	Vertex/Geometry
gplGetOutputLayer() i32	Retrieves the output layer	Vertex/Geometry
gplSetOutputViewport(i32) void	Sets the viewport for framebuffer outputs	Vertex/ Geometry
gplExportVertexCoordinates(f32x4) void	Exports the vertex position for rasterization	Vertex/Hull/Domain/Geometry/Mesh
gplGetVertexIndex() i32	Gets the index for the vertex being invoked	Vertex
gplGetInstanceIndex() i32	Gets the instance index	Vertex
gplGetBaseVertexIndex() i32	Gets the base vertex index	Vertex
gplGetBaseInstanceIndex() i32	Gets the base instance index	Vertex
gplGetDrawIndex() i32	Gets the draw index	Vertex
gplGetPixelCoordinates() f32x4	Gets the clip space pixel coordinates. The XY coordinates describe the absolute pixel index and the Z coordinate a normalized depth value [0..1] between the near and far plane.	Pixel
gplExportColor(scalar, literal i32) void	Exports a color value to the designated output target	Pixel
gplSetPixelDepth(f32) void	Explicitly sets the pixel depth. Using this function triggers the compiler to emit an error if early_depth is being used for the entry point invoking the function	Pixel
gplGetLocalInvocationIndex() i32x3	Get the work group invocation index (xyz) of the current invocation	Compute
gplGetGlobalInvocationIndex() i32x3	Get the dispatch invocation index (xyz) of the current invocation	Compute
gplGetWorkGroupIndex() i32x3	Get the work group index (xyz) of the current invocation	Compute
gplGetWorkGroupDimensions() i32x3	Get the size of the work group (xyz)	Compute
gplGetSubgroupId() i32	Get the Subgroup id of the current invocation	Compute
gplGetSubgroupSize() i32	Get the size of the subgroup	Compute
gplGetNumSubgroups() i32	Get the number of subgroups in the current invocation	Compute
gplGetSubgroupLocalInvocationMask() u32x4	Get an execution mask (128 bit) with only this invocation set to 1	Compute
gplGetSubgroupLocalInvocationAndLowerMask() u32x4	Get an execution mask (128 bit) with this invocation and any lower invocation set to 1	Compute
gplGetSubgroupLowerMask() u32x4	Get an execution mask (128 bit) with all lower invocations set to 1	Compute
gplGetSubgroupLocalInvocationAndGreaterMask() u32x4	Get an execution mask (128 bit) with this invocation and any greater invocation set to 1	Compute
gplGetSubgroupGreaterMask() u32x4	Get an execution mask (128 bit) with all greater invocations set to 1	Compute

In addition to the functions above, there is also a globally defined constant value which is set to true based on the type of shader that is being compiled. This value is fetched using gplIsXShader where X is any value from the below list:

• Vertex
• Hull
• Domain
• Geometry
• Pixel
• Compute
• Task
• Mesh
• RayGeneration
• RayClosestHit
• RayAnyHit
• RayMiss
• RayIntersection
• RayCallable

Example:

entry_point
BasicPixel(
    in UV : f32x2
) void
{
    var color = textureSample(Albedo, Sampler, UV);
    if (gplIsPixelShader)
        gplExportColor(color, i32(Framebuffer.Color));
    else if (gplIsComputeShader)
        textureStore(OutputImage, gplGetPixelCoordinates().xy, color);
}

Normally, gplExportColor would only be allowed in a Pixel shader, so the above code would provoke a compilation issue. However, GPULang checks for shader specific functions with dead code eliminated, and employs the same dead code elimination for code gen.