Using textureSize to Get Mipmap Dimensions in GLSL

In OpenGL Shading Language (GLSL), querying texture resolution directly on the GPU eliminates the need to pass manual dimension uniforms from the CPU. The built-in textureSize function retrieves the dimensions of a specified texture sampler at a designated mipmap level. This article explains the syntax, parameters, return types, and implementation details for using textureSize across different sampler types to handle level-of-detail (LOD) dimension queries effectively.

Function Signature and Parameters

The textureSize function accepts a sampler and an integer representing the mipmap level:

gvec textureSize(gsampler sampler, int lod);
  • sampler: The texture sampler being queried (e.g., sampler2D, sampler3D, samplerCube, sampler2DArray).
  • lod: An integer specifying the mipmap level. Level 0 represents the base resolution of the texture. Higher integers correspond to smaller, downsampled mipmap levels (e.g., 1, 2, etc.).

Return Values

The return type matches the dimensionality of the sampler provided:

  • int: Returned for 1D textures (sampler1D).
  • ivec2: Returned for 2D textures, cube maps, and rectangular textures (sampler2D, samplerCube). The components represent (width, height). For cube maps, width and height are identical.
  • ivec3: Returned for 3D textures and 2D texture arrays (sampler3D, sampler2DArray). For 3D textures, the components represent (width, height, depth). For array textures, the third component represents the layer count rather than a depth dimension.

GLSL Implementation Example

The following fragment shader snippet demonstrates querying dimensions at both the base level and an arbitrary mipmap level:

#version 450 core

uniform sampler2D u_Texture;
uniform int u_TargetMipLevel;

out vec4 FragColor;

void main()
{
    // Retrieve base dimensions (mip level 0)
    ivec2 baseSize = textureSize(u_Texture, 0);

    // Retrieve dimensions at a specific mipmap level
    ivec2 mipSize = textureSize(u_Texture, u_TargetMipLevel);

    // Calculate texel size for filtering or manual sampling
    vec2 texelSize = 1.0 / vec2(mipSize);

    FragColor = vec4(texelSize, 0.0, 1.0);
}

Key Considerations

  1. Mipmap Clamping and Out-of-Bounds Queries: If the lod argument exceeds the total number of defined mipmap levels for the texture, the returned values are undefined or typically evaluate to zero, depending on the hardware driver. Ensure the queried mip level is within the valid range [0, levels - 1].
  2. Multisample Textures: For multisample textures (sampler2DMS), textureSize does not take a lod parameter because multisampled textures do not support mipmapping. The call is simply textureSize(sampler2DMS).
  3. Texture Buffers: Similarly, buffer textures (samplerBuffer) have no mipmaps and accept only the sampler argument, returning an int representing total texels.
  4. Data Types: Because textureSize returns integer types (int, ivec2, ivec3), explicit casting to floating-point vectors (vec2, vec3) is required when performing coordinate calculations or texel offset normalization.