User Guide Cancel

Lib Sparse - Shader API | Substance 3D Painter

Last updated on Jul 13, 2023

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. Export presets
    1. Export presets overview
    2. Predefined presets
    3. Creating export presets
6. Glossary
7. Performance
Interface
1. Assets
2. Substance 3D Assets
3. Color picker
4. Display settings
5. History
6. Layer stack
7. Main menu
8. Project configuration
9. Properties
10. Settings
11. Shader settings
  1. Shader settings overview
  2. Updating a shader
12. Texture Set
13. Toolbars
14. Viewport
15. Miscellaneous
Painting
1. Painting overview
2. Tool list
  1. Paint brush
  2. Eraser
  3. Projection
  4. Polygon fill
  5. Smudge tool
  6. Clone Tool
  7. Quick mask
  8. Path tool
3. Straight line
4. Lazy mouse
5. Symmetry
  1. Symmetry overview
  2. Mirror Symmetry
6. Fill projections
7. Presets
  1. Presets overview
  2. Creating and saving presets
  3. Creating particles presets
  4. Photoshop brush presets (ABR)
8. Dynamic strokes
9. Advanced channel painting
10. Vector graphic (.svg & .ai)
11. 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 UV Unwrapping
2. Physical size
3. Smart Materials and Masks
4. Subsurface Scattering
5. Dynamic Material Layering
6. UV Reprojection
7. UV Tiles
  1. UV Tiles overview
  2. Image Sequence
8. Color Management
9. Post Processing
10. Iray Renderer
11. Plugins
12. Sparse Virtual Textures
13. Custom Shaders
14. SpaceMouse® by 3Dconnexion
15. Universal Scene Description (USD)
16. 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 when loaded in layer or tool properties
    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 10.1
4. Version 10.0
5. Version 9.1
6. 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

Ask the Community

Contact Us