How sparseTextureARB Queries Residency in GLSL

In OpenGL using the GL_ARB_sparse_texture extension, shaders can safely sample partially committed virtual textures without triggering faults on unallocated memory pages. Rather than returning sample data directly, the sparseTextureARB function writes sampled texels into an out variable and returns an integer status code. This code is passed directly to the built-in sparseTexelsResidentARB function, which queries whether every texel required by the lookup resides in physical GPU memory.

The Mechanism of sparseTextureARB

Standard GLSL texture lookup functions (such as texture()) return a vector containing the color or data at the specified coordinates. In a virtual sparse texturing scenario, evaluating coordinates that land on uncommitted or unmapped tiles would yield undefined values or cause hardware bottlenecks.

To solve this, GL_ARB_sparse_texture restructures texture sampling routines into a two-part query:

int sparseTextureARB(gsampler2D sampler, vec2 P, out gvec4 texel [, float bias]);

1. Texel Output: The sampled color is returned via the out parameter (texel).
2. Residency Code: The direct return value is an implementation-dependent integer bitfield representing the residency state of the memory accessed during sampling.

Evaluating Residency with sparseTexelsResidentARB

The raw integer returned by sparseTextureARB cannot be evaluated using standard equality checks (such as checking if it equals zero). Instead, GLSL provides the helper function:

bool sparseTexelsResidentARB(int code);

This function interprets the internal bitfield returned by sparseTextureARB. It returns true if and only if all texels required for the sampling operation are fully resident in physical memory. If even a single footprint sample falls onto an uncommitted page—for example, during bilinear or trilinear interpolation where multiple adjacent texels across mipmap levels are queried—sparseTexelsResidentARB returns false.

Implementation Example

Below is a standard pattern for querying residency and handling missing data inside a fragment shader:

#version 450 core
#extension GL_ARB_sparse_texture : enable

uniform sampler2D u_SparseTexture;
in vec2 v_TexCoords;
out vec4 FragColor;

void main()
{
    vec4 sampledColor;
    
    // Perform lookup and capture residency status code
    int residencyCode = sparseTextureARB(u_SparseTexture, v_TexCoords, sampledColor);

    // Evaluate residency
    if (sparseTexelsResidentARB(residencyCode))
    {
        // All necessary texels are present in memory
        FragColor = sampledColor;
    }
    else
    {
        // Data is missing: fallback to a lower LOD or default color
        FragColor = vec4(0.1, 0.1, 0.1, 1.0);
    }
}

Behavior During Filter Footprints

When using filtering modes such as GL_LINEAR_MIPMAP_LINEAR, a single texture lookup may read up to eight texels across two mipmap levels. For sparseTexelsResidentARB to return true, all physical backing pages containing those texels must be committed.

If any part of the filter footprint touches unmapped virtual memory, the return code marks the entire lookup as non-resident. In this case, the contents written to the texel variable are undefined, preventing partially loaded artifacts from corrupting the render pipeline. Applications typically use the non-resident result to stream missing tiles from disk to GPU memory or write coordinates to a residency feedback buffer.