Documentation for Substance 3D Painter is now available on Experience League. After March 14th, HelpX pages will automatically redirect to the equivalent Experience League page.
Refer to the FAQ for more information about which documentation is affected.

User Guide Cancel

Lib Sparse - Shader API | Substance 3D Painter

Last updated on Jul 13, 2023

Substance 3D Painter

Open app

Substance 3D home
Home
Getting Started
1. Getting Started overview
2. Activation and licenses
3. System requirements
4. Project creation
5. Export
  1. Export overview
  2. Export window
  3. Output templates
    1. Output templates overview
    2. Default Output templates
    3. Creating Output templates
6. Glossary
Interface
1. Interface overview
2. Assets
3. Substance 3D Assets
4. Color picker
5. Display settings
6. History
7. Layer stack
8. Main menu
9. Project configuration
10. Properties
11. Settings
12. Shader settings
  1. Shader settings overview
  2. Updating a shader
13. Texture Set
14. Toolbars
15. Viewport
16. Miscellaneous
Painting
1. Painting overview
2. Paint tools
3. Path tools
  1. Path tool overview
  2. Paint along path
  3. Ribbon path
  4. Filled path
  5. Erase along path
  6. Smudge along path
4. Straight line
5. Lazy mouse
6. Symmetry
7. Fill projections
8. Presets
  1. Presets overview
  2. Creating and saving presets
  3. Creating particles presets
  4. Photoshop brush presets
9. Dynamic strokes
10. Advanced channel painting
11. Vector graphic (.svg & .ai)
12. Text resource
Effects
1. Effects overview
2. Generator
3. Paint
4. Fill
5. Levels
6. Compare Mask
7. Filter
8. Anchor Point
Baking
Content
1. Creating custom effects
2. Importing assets
Features
1. Automatic resource update
2. Automatic UV Unwrapping
3. Physical size
4. Smart Materials and Masks
5. Subsurface Scattering
6. Dynamic Material Layering
7. UV Reprojection
8. UV Tiles
  1. UV Tiles overview
  2. Image Sequence
9. Color Management
10. Post Processing
11. Iray Renderer
12. Plugins
13. Sparse Virtual Textures
14. Custom Shaders
15. SpaceMouse® by 3Dconnexion
16. Universal Scene Description (USD)
17. Send to
Technical Support
1. Performance Guidelines
2. Configuring Pens and Tablets
3. Exporting the log file
4. Exporting a DXDiag
5. Technical issues
6. Workflow Issues
  1. Export Issues
    1. My exported opacity map is totally black
    2. Texture dilation or Padding
  2. Tools Issues
    1. Normal map looks incorrect
    2. Paint Tool bleeds on other UV islands
  3. Project Issues
  4. Library Issues
    1. Thumbnails in the shelf look incorrect
    2. Error when importing a Font
  5. Viewport Issues
    1. Mesh faces disappear when looking at them from behind
    2. Viewports and textures are blurry or lack sharpness
  6. Plugins Issues
    1. Substance Source plugin doesn't load
  7. License Issues
    1. Maintenance is expired dialog on startup
Pipeline and integration
1. Installation and preferences
2. Configuration
3. Resource management
Scripting and development
1. Scripts and plugins
  1. Creating a Javascript plugin
  2. Remote control with scripting
2. Shader API Reference
  1. Shader API overview
  2. Changelog - Shader API
  3. Libraries - Shader API
  4. Parameters - Shader API
  5. Shaders - Shader API
Release notes
1. Release notes overview
2. All Changes
3. Version 11.1
4. Version 11.0
5. Version 10.1
6. Known issues
7. Old versions

Lib Sparse - Shader API

lib-sparse.glsl

This file provides useful functions to ensure sparse textures sampling correctness (ARB_sparse_texture). Allows to sample only part of textures really present in video memory.

Public Functions: getSparseCoord getSparseCoordLod0 textureSparseQueryLod textureSparse

Public Structures: SamplerSparse SparseCoord

The FEATURE_SPARSE_TEXTURE macro is defined only if the sparse virtual texture extension is enabled.

If enabled, process additional texture lookup checks to climb up mipmap pyramid if texels are missing.

#ifdef FEATURE_SPARSE_TEXTURE 
//: param auto material_lod_check_needed 
uniform bool material_lod_check_needed = false; 
//: param auto material_lod_mask 
uniform usampler2D material_lod_mask; 
#endif // FEATURE_SPARSE_TEXTURE 
//: param auto uvtile_reference_sampler 
uniform sampler2D uvtile_reference_sampler; 
//: param auto uvtile_size 
uniform vec2 uvtile_size; 
//: param auto uvtile_inverse_size 
uniform vec2 uvtile_inverse_size; 
//: param auto uvtile_lod_bias 
uniform float uvtile_lod_bias;

Sampler and sparse texture information structure

Used to query all sampler related uniforms with a single auto binding

struct SamplerSparse { 
  sampler2D tex; 
  vec4 size; // width, height, 1/width, 1/height 
  bool is_set; // a boolean indicating whether the texture is in the texture set or not 
  uvec3 lod_mask_select; // masking operations description allowing to retrieve loaded mipmaps information 
};

Sparse sampling coordinates

Store the UV coordinates & material-wise sparse LoD mask

struct SparseCoord { 
  vec2 tex_coord; 
  vec2 dfdx; 
  vec2 dfdy; 
  float lod; 
  uint material_lod_mask; 
}; 
 
 
#if defined(SHADER_FRAGMENT)

Build texture coordinates structure used by textureSparse() sampling function (must be called from fragment shader)

Example: SparseCoord uv1coord = getSparseCoord(inputs.multi_tex_coord[1]);

SparseCoord getSparseCoord(vec2 tex_coord) { 
  SparseCoord res; 
  res.tex_coord = tex_coord; 
  res.dfdx = dFdx(tex_coord); 
  res.dfdy = dFdy(tex_coord); 
#ifdef FEATURE_SPARSE_TEXTURE 
  res.material_lod_mask = material_lod_check_needed ? 
    textureLod(material_lod_mask,tex_coord,0.0).r : 
    0u; 
  res.lod = getLodFromReferenceSampler(tex_coord); 
#endif // FEATURE_SPARSE_TEXTURE 
  return res; 
} 
#endif

Build texture coordinates structure used by textureSparse() sampling function Base level sampling version (can be used if outside fragment shader)

SparseCoord getSparseCoordLod0(vec2 tex_coord) { 
  SparseCoord res; 
  res.tex_coord = tex_coord; 
  res.dfdx = vec2(0.0); 
  res.dfdy = vec2(0.0); 
#ifdef FEATURE_SPARSE_TEXTURE 
  res.material_lod_mask = material_lod_check_needed ? 
    textureLod(material_lod_mask,tex_coord,0.0).r : 
    0u; 
  res.lod = 0.0; 
#endif // FEATURE_SPARSE_TEXTURE 
  return res; 
} 
 
#if defined(SHADER_FRAGMENT)

Compute the level-of-detail that would be used to sample from a sparse texture

Climb up mipmap pyramid if texels are missing Returns LoD BEFORE LoD bias applied

float textureSparseQueryLod(SamplerSparse sampler, SparseCoord coord) { 
#ifdef FEATURE_SPARSE_TEXTURE 
  float lodfix = coord.lod; 
  if (material_lod_check_needed) { 
    lodfix = getFixedSparseLod(getTextureLodMask(sampler.lod_mask_select, coord.material_lod_mask), lodfix); 
  } 
  return lodfix-uvtile_lod_bias; 
#else // FEATURE_SPARSE_TEXTURE 
  return textureQueryLod(sampler.tex, coord.tex_coord).y-uvtile_lod_bias; 
#endif // FEATURE_SPARSE_TEXTURE 
} 
#endif // SHADER_FRAGMENT

Compute the derivatives that would be used to sample from a sparse texture

Climb up mipmap pyramid if texels are missing

void textureSparseQueryGrad(out vec2 dfdx, out vec2 dfdy, SamplerSparse sampler, SparseCoord coord) { 
#ifdef FEATURE_SPARSE_TEXTURE 
  if (material_lod_check_needed) { 
    float lodfix = getFixedSparseLod(getTextureLodMask(sampler.lod_mask_select, coord.material_lod_mask), coord.lod); 
    if (coord.lod!=lodfix) { 
      // Fix dfdx dfdy, take account offset, no more anisotropy 
      vec2 ddfix = exp2(lodfix-uvtile_lod_bias) * uvtile_inverse_size; 
      dfdx = vec2(ddfix.x,0.0); 
      dfdy = vec2(0.0,ddfix.y); 
      return; 
    } 
  } 
#endif // FEATURE_SPARSE_TEXTURE 
  dfdx = coord.dfdx; 
  dfdy = coord.dfdy; 
}

Performs a texture lookup on a sparse texture, go up the mipmap levels if necessary

This function replaces the standard texture(sampler2D, vec2) to retrieve texels from a sparse texture

vec4 textureSparse(SamplerSparse sampler, SparseCoord coord) { 
  vec2 dfdx,dfdy; 
  textureSparseQueryGrad(dfdx, dfdy, sampler, coord); 
  return textureGrad(sampler.tex, coord.tex_coord, dfdx, dfdy); 
}

Given a texture, performs an optimized multiple texture lookups with small offsets

We are providing alternatives versions of this helper for up to N=4

void textureSparseOffsets(SamplerSparse sampler, SparseCoord coord, vec2 offsets[N], out vec4 results[N]) { 
  vec2 dfdx,dfdy; 
  textureSparseQueryGrad(dfdx, dfdy, sampler, coord); 
  for(int i = 0; i < N; ++i) { 
    results[i] = textureGrad(sampler.tex, coord.tex_coord + offsets[i], dfdx, dfdy); 
  } 
}

Get help faster and easier

New user?

Lib Sparse - Shader API | Substance 3D Painter

Lib Sparse - Shader API

lib-sparse.glsl

Get help faster and easier

Share this page

Ask the Community

Contact Us