So what's the ultimate purpose of variants? If I trace e.g. mayUseVertexOverbright/VERTEX_OVERBRIGHT, I can't find any decisions ever being made based on the variant, other than segregating it from other variants.

Once some of the pStage members are set in MaterialSystem::GenerateMaterialsBuffer(), they are then used in pStage->surfaceDataUpdater() to set the correct surface data. Essentially, for each unique surface data all of the active variants are stored consecutively, with the differences dictated by variant.

Seems wrong to store them on pStage since if there is more than one draw surf using the same shader (which is the whole point of having variant bit masks, right?) the different values would clobber each other.

The offset stored in drawSurf_t includes the offset to the specific variant used for it (

The mapping between drawSurfs, shader stages, and material buffer can be thought of like this:

shaderStage_t* pStage = drawSurf->shader->stages[stage];

uint32_t baseSurfaceDataIndex = pStage->bufferOffset;
uint32_t variant = drawSurf->shaderVariant[stage]; // Always in the range of [0; active stage variants]
uint32_t variantOffset = pStage->variantOffsets[variant];
void* material = materials + baseSurfaceDataIndex + variantOffset; // materials is mapped to the start of the range for either static or dynamic stages
uint32_t materialOffset = pStage->materialOffset // Different from bufferOffset for dynamic stages
    + variantOffset; // materialOffset is what's then used in the GLSL shaders to index the material array 

This data should be stored somewhere else. It's hacky to store drawsurf-specific data on the shader.

Perhaps, though I don't really see where else it could be stored. There could be a wrapper around shaderStage_t passed to GenerateMaterialsBuffer instead, and it could store all the variants, I suppose.

Well, it's not truly stored in the shader, the shaderStage_t is just used as a proxy, so that surfaceDataUpdater() no longer needs a drawSurf_t as input. When the materials are initially generated, these use drawSurf to set the value to avoid using up memory and doing processing for stage variants that are never used.

OK I see that they are just temporary; used during one iteration of GenerateMaterialsBuffer.

If it's too burdensome to add an argument to those "updater" functions, it would still be better to store them in a global variable, instead of misleadingly them with shader stages.

Made it work with propagating it through UpdateSurfaceData*().