sparseTextureLodARB Return Codes in GLSL

This article explains how the sparseTextureLodARB function in OpenGL Shading Language (GLSL) signals uncommitted memory pages. It covers the mechanics of the function's return code, the role of implementation-dependent values, and the proper built-in function used to detect non-resident texels.

The Return Value of sparseTextureLodARB

In the GL_ARB_sparse_texture extension, texture sampling functions do not return the sampled color directly. Instead, they write the sampled data to an out parameter and return an int representing the residency status of the accessed memory.

The signature is structured as follows:

int sparseTextureLodARB(gsampler2D sampler, vec2 P, float lod, out vec4 texel);

Uncommitted Memory and sparseTexelsResidentARB

The exact numeric integer returned by sparseTextureLodARB to indicate uncommitted memory is implementation-dependent. The specification does not define a fixed constant (such as 0 or -1) for non-resident pages across different GPU hardware vendors.

To determine whether the lookup accessed uncommitted or committed pages, GLSL provides the built-in function sparseTexelsResidentARB:

bool sparseTexelsResidentARB(int code);

• If all memory pages required for the footprint of the lookup are committed, passing the return code to sparseTexelsResidentARB returns true.
• If any page required by the lookup is uncommitted (non-resident), passing the return code to sparseTexelsResidentARB returns false.

Handling Non-Resident Data

When sparseTexelsResidentARB returns false, the value written to the texel output variable is undefined or implementation-dependent, and the application must handle the missing data manually.

vec4 texelColor;
int code = sparseTextureLodARB(mySparseSampler, texCoords, lodLevel, texelColor);

if (sparseTexelsResidentARB(code)) {
    // Texel data resides in committed memory
    fragColor = texelColor;
} else {
    // Texel data resides in uncommitted memory
    fragColor = vec4(0.0); // Fallback color or lower-detail alternative
}

Applications should never compare the integer return code directly against numeric literals. Always pass the integer code directly to sparseTexelsResidentARB to guarantee correct residency detection across all hardware.