User Guide Cancel

Lib Sampler - Shader API | Substance 3D Painter

  1. Substance 3D home
  2. Home
  3. Getting Started
    1. Getting Started overview
    2. Activation and licenses
    3. System requirements
    4. Project creation
    5. Export
      1. Export overview
      2. Export window
        1. Export window overview
        2. Export settings
        3. Output templates
        4. List of exports
      3. Export presets
        1. Export presets overview
        2. Predefined presets
          1. Predefined Presets
          2. USD PBR Metal Roughness Preset
          3. Default Presets
        3. Creating export presets
    6. Glossary
    7. Performance
  4. Interface
    1. Assets
      1. Assets overview
      2. Navigation
      3. Customizing the layout
      4. Filter by path
      5. Saved searches
      6. Advanced search queries
      7. Adding a new library
      8. Sub-library tab
    2. Substance 3D Assets
    3. Color picker
    4. Display settings
      1. Display settings overview
      2. Environment settings
      3. Camera settings
      4. Viewport settings
    5. History
    6. Layer stack
      1. Layer stack overview
      2. Creating layers
      3. Managing layers
      4. Masking and effects
      5. Blending modes
      6. Layer instancing
      7. Geometry mask
    7. Main menu
      1. Main menu overview
      2. File menu
      3. Edit menu
      4. Mode menu
      5. Window menu
      6. Viewport menu
      7. Plugins menu
      8. Help menu
    8. Project configuration
    9. Properties
    10. Settings
      1. Settings overview
      2. General preferences
      3. Shortcuts
      4. Libraries configuration
    11. Shader settings
      1. Shader settings overview
      2. Updating a shader
    12. Texture Set
      1. Texture Set overview
      2. Texture Set list
      3. Texture Set settings
      4. Texture Set reassignment
    13. Toolbars
    14. Viewport
      1. Viewport overview
      2. 2D view
      3. 3D view
      4. Camera management
    15. Miscellaneous
      1. Sliders
      2. Log
      3. Update checker
  5. 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
      1. Fill projections overview
      2. Fill (match per UV Tile)
      3. UV projection
      4. Tri-planar projection
      5. Planar projection
      6. Spherical projection
      7. Cylindrical projection
      8. Warp projection
      9. UV set to UV set projection
    7. Presets
      1. Presets overview
      2. Creating and saving presets
      3. Creating particles presets
        1. Creating particles overview
        2. Installing the particle editor
        3. Overview of the particle editor
        4. Creating a new particle script
      4. Photoshop brush presets (ABR)
        1. Photoshop brush presets overview
        2. Exporting Brush Presets from Photoshop
        3. Importing Photoshop Brush Presets
        4. Photoshop Brush Parameters Compatibility
    8. Dynamic strokes
      1. Dynamic strokes overview
      2. Enabling Dynamic Stroke feature
      3. Dynamic Stroke Performances
      4. Creating custom Dynamic Strokes
    9. Advanced channel painting
      1. Channel painting overview
      2. Ambient Occlusion
      3. Flow Map
      4. Height Map
      5. Normal Map
    10. Vector graphic (.svg & .ai)
    11. Text resource
  6. Effects
    1. Effects overview
    2. Generator
    3. Paint
    4. Fill
    5. Levels
    6. Compare Mask
    7. Filter
    8. Anchor Point
  7. Baking
    1. Baking overview
    2. How to bake mesh maps
    3. Baking visualization settings
  8. Content
    1. Creating custom effects
      1. Creating custom effects overview
      2. Generic filter
      3. Channel specific filter
      4. Generators
      5. Mesh map
      6. Mesh based input
      7. User data
    2. Importing assets
      1. Adding resources via drag and drop
      2. Adding resources via the import window
      3. Adding content on the hard drive
      4. Receiving assets from other Substance 3D applications
  9. Features
    1. Automatic UV Unwrapping
    2. Physical size
    3. Smart Materials and Masks
    4. Subsurface Scattering
      1. Subsurface Scattering overview
      2. Enabling Subsurface in a Project
      3. Subsurface Parameters
      4. Subsurface Material Type
    5. Dynamic Material Layering
    6. UV Reprojection
    7. UV Tiles
      1. UV Tiles overview
      2. Image Sequence
    8. Color Management
      1. Color management overview
      2. Color management with Adobe ACE - ICC
      3. Color management with OpenColorIO
    9. Post Processing
      1. Post Processing overview
      2. Color correction
      3. Depth of Field
      4. Glare
      5. Lens Distortion
      6. Tone Mapping
      7. Vignette
      8. Color Profile
    10. Iray Renderer
      1. Iray Renderer overview
      2. Iray Settings
      3. Viewer and MDL Settings
    11. Plugins
      1. Plugins overview
      2. Autosave
      3. Resources Updater
    12. Sparse Virtual Textures
    13. Custom Shaders
    14. SpaceMouse® by 3Dconnexion
    15. Universal Scene Description (USD)
    16. Send to
  10. Technical Support
    1. Performance Guidelines
      1. Performances guidelines overview
      2. Conflicts and background applications
      3. Mesh and UV setup
      4. GPU Drivers
      5. NVIDIA Drivers Settings
      6. GPU VRAM amount and bandwidth
      7. GPU VRAM and other applications
      8. Texture Sets amount
      9. Layer management
      10. Channels management
      11. Substance filters and materials
      12. Viewport display
    2. Configuring Pens and Tablets
    3. Exporting the log file
    4. Exporting a DXDiag
    5. Technical issues
      1. GPU Issues
        1. Crash when working with overclocked GPU
        2. Forcing the external GPU on Mac OS
        3. GPU drivers compatibility
        4. GPU drivers crash with long computations (TDR crash)
        5. GPU has outdated drivers
        6. GPU is not recognized
        7. GPU is not recognized and is mentionned as GDI Generic
        8. Issues with Nvidia GPUs on recent Mac OS versions
        9. Multi/Bi-GPU
        10. Running on integrated GPU
        11. Painter doesn't start on the right GPU
      2. Startup Issues
        1. Application failed to start because of Qt
        2. Crash or freeze during startup
        3. Software conflicts
      3. Rendering Issues
        1. Artifacts and glitches on Mac OS with Custom GPUs
        2. Blocky artifacts appear on textures in the viewport
        3. Mesh appears pink in the viewport
        4. Mesh flash to white when moving camera
        5. Some HDPI scaling values are not working
      4. Stability Issues
        1. Crash during export
        2. Crash when opening or saving a file
        3. Crash while baking
        4. Crash with low virtual memory
        5. Windows Blue Screens
      5. Miscellaneous Issues
        1. Corrupted texture error message
        2. Shelf resources are gone after 7.2 update
        3. Error there is no disk in the drive
        4. Error with missing api-ms-crt dll
        5. Impossible to drag and drop files into the shelf
        6. Impossible to use the ALT keyboard shortcut on Linux
        7. Assets (or shelf) previews are empty
    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
        1. A project has been processed as a text file and is now corrupted
        2. Loading files from a network
        3. Preserve brush strokes setting stays disabled
        4. Projects are really big
      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
  11. Pipeline and integration
    1. Installation and preferences
      1. Preferences and application data location
      2. Automated installation
      3. Retrieving the installation path
    2. Configuration
      1. Command lines
      2. Environment variables
      3. Firewall Configuration
      4. Querying Current Software Version
      5. Remote Desktop
    3. Resource management
      1. Shelf and Assets location
      2. Resource paths
        1. Adding resource paths by editing preferences manually
        2. Editing resource paths manually
        3. Editing the Shelf Preferences with Python
      3. Adding saved searches manually
      4. Preferences and content migration
      5. Excluding resources in a resource path
  12. 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
        1. Lib Alpha - Shader API
        2. Lib Bayer - Shader API
        3. Lib Defines - Shader API
        4. Lib Emissive - Shader API
        5. Lib Env - Shader API
        6. Lib Normal - Shader API
        7. Lib PBR - Shader API
        8. Lib PBR Aniso - Shader API
        9. Lib Pom - Shader API
        10. Lib Random - Shader API
        11. Lib Sampler - Shader API
        12. Lib Sparse - Shader API
        13. Lib SSS - Shader API
        14. Lib Utils - Shader API
        15. Lib Vectors - Shader API
      4. Parameters - Shader API
        1. All Custom Params - Shader API
        2. All Engine Params - Shader API
        3. All Rendering States Params - Shader API
        4. Layering Bind Materials - Shader API
        5. Layering Declare Stacks - Shader API
      5. Shaders - Shader API
        1. PBR Material Layering - Shader API
        2. PBR Metal Rough - Shader API
        3. Pixelated - Shader API
        4. Surface Shader - Shader API
        5. Toon - Shader API
  13. Release notes
    1. Release notes overview
    2. All Changes
    3. Version 10.1
    4. Version 10.0
    5. Version 9.1
    6. Old versions
      1. Version 9.0
      2. Version 8.3
      3. Version 8.2
      4. Version 8.1
      5. Version 7.4
      6. Version 7.3
      7. Version 7.2
      8. Version 2021.1 (7.1.0)
      9. Version 2020.2 (6.2.0)
      10. Version 2020.1 (6.1.0)
      11. Version 2019.3
      12. Version 2019.2
      13. Version 2019.1
      14. Version 2018.3
      15. Version 2018.2
      16. Version 2018.1
      17. Version 2017.4
      18. Version 2017.3
      19. Version 2017.2
      20. Version 2017.1
      21. Version 2.6
      22. Version 2.5
      23. Version 2.4
      24. Version 2.3
      25. Version 2.2

Lib Sampler - Shader API

lib-sampler.glsl

Public Functions: getAO getShadowFactor getGlossiness getRoughness getMetallic getAnisotropyLevel getAnisotropyAngle getOpacity getHeight getDisplacement getSpecularLevel getBaseColor getDiffuse getSpecularColor getScattering generateAnisotropicRoughness generateDiffuseColor generateSpecularColor

Import from library

import lib-defines.glsl 
import lib-sparse.glsl

Default background colors when there is no data in channel (alpha is 0)

const vec3  DEFAULT_BASE_COLOR       = vec3(0.5); 
const float DEFAULT_ROUGHNESS        = 0.3; 
const float DEFAULT_METALLIC         = 0.0; 
const float DEFAULT_ANISOTROPY_LEVEL = 0.0; 
const float DEFAULT_ANISOTROPY_ANGLE = 0.0; 
const float DEFAULT_OPACITY          = 1.0; 
const float DEFAULT_AO               = 1.0; 
const float DEFAULT_SPECULAR_LEVEL   = 0.5; 
const float DEFAULT_HEIGHT           = 0.0; 
const float DEFAULT_DISPLACEMENT     = 0.0; 
const float DEFAULT_SCATTERING       = 0.0;

AO map.

//: param auto ao_blending_mode 
uniform int ao_blending_mode; 
//: param auto texture_ao 
uniform SamplerSparse base_ao_tex; 
//: param auto channel_ao 
uniform SamplerSparse ao_tex;

A value used to tweak the Ambient Occlusion intensity.

//: param custom { 
//:   "default": 0.75, 
//:   "label": "AO Intensity", 
//:   "min": 0.00, 
//:   "max": 1.0, 
//:   "group": "Common Parameters" 
//: } 
uniform float ao_intensity;

Shadowmask.

//: param auto shadow_mask_enable 
uniform bool sm_enable; 
//: param auto shadow_mask_opacity 
uniform float sm_opacity; 
//: param auto shadow_mask 
uniform sampler2D sm_tex; 
//: param auto screen_size 
uniform vec4 screen_size;

Return sampled glossiness or a default value

float getGlossiness(vec4 sampledValue) 
{ 
  return sampledValue.r + (1.0 - DEFAULT_ROUGHNESS) * (1.0 - sampledValue.g); 
} 
 
float getGlossiness(SamplerSparse sampler, SparseCoord coord) 
{ 
  return getGlossiness(textureSparse(sampler, coord)); 
}

Return sampled roughness or a default value

float getRoughness(vec4 sampledValue) 
{ 
  return sampledValue.r + DEFAULT_ROUGHNESS * (1.0 - sampledValue.g); 
} 
 
float getRoughness(SamplerSparse sampler, SparseCoord coord) 
{ 
  return getRoughness(textureSparse(sampler, coord)); 
}

Return sampled metallic or a default value

float getMetallic(vec4 sampledValue) 
{ 
  return sampledValue.r + DEFAULT_METALLIC * (1.0 - sampledValue.g); 
} 
 
float getMetallic(SamplerSparse sampler, SparseCoord coord) 
{ 
  return getMetallic(textureSparse(sampler, coord)); 
}

Return sampled anisotropy level or a default value

float getAnisotropyLevel(vec4 sampledValue) 
{ 
  return sampledValue.r + DEFAULT_ANISOTROPY_LEVEL * (1.0 - sampledValue.g); 
} 
 
float getAnisotropyLevel(SamplerSparse sampler, SparseCoord coord) 
{ 
  return getAnisotropyLevel(textureSparse(sampler, coord)); 
}

Return sampled anisotropy angle or a default value

float getAnisotropyAngle(vec4 sampledValue) 
{ 
  return M_2PI * (sampledValue.r + DEFAULT_ANISOTROPY_ANGLE * (1.0 - sampledValue.g)); 
} 
 
float getAnisotropyAngle(SamplerSparse sampler, SparseCoord coord) 
{ 
  // Manual trilinear filtering 
  float level = max(0.0, textureSparseQueryLod(sampler, coord) + uvtile_lod_bias); 
  int level0 = int(level); 
  int level1 = level0 + 1; 
 
  ivec2 texSize0 = ivec2(sampler.size.xy) >> level0; 
  ivec2 texSize1 = texSize0 >> 1; 
  ivec2 itex_coord0 = ivec2(coord.tex_coord * vec2(texSize0)); 
  ivec2 itex_coord1 = ivec2(coord.tex_coord * vec2(texSize1)); 
 
  // Assuming tex sizes are pow of 2, we can do the fast modulo 
  ivec2 texSizeMask0 = texSize0 - ivec2(1); 
  ivec2 texSizeMask1 = texSize1 - ivec2(1); 
 
  // Fetch the 8 samples needed 
  float a000 = getAnisotropyAngle(texelFetch(sampler.tex,  itex_coord0                & texSizeMask0, level0)); 
  float a001 = getAnisotropyAngle(texelFetch(sampler.tex, (itex_coord0 + ivec2(1, 0)) & texSizeMask0, level0)) - a000; 
  float a010 = getAnisotropyAngle(texelFetch(sampler.tex, (itex_coord0 + ivec2(0, 1)) & texSizeMask0, level0)) - a000; 
  float a011 = getAnisotropyAngle(texelFetch(sampler.tex, (itex_coord0 + ivec2(1, 1)) & texSizeMask0, level0)) - a000; 
  float a100 = getAnisotropyAngle(texelFetch(sampler.tex,  itex_coord1                & texSizeMask1, level1)) - a000; 
  float a101 = getAnisotropyAngle(texelFetch(sampler.tex, (itex_coord1 + ivec2(1, 0)) & texSizeMask1, level1)) - a000; 
  float a110 = getAnisotropyAngle(texelFetch(sampler.tex, (itex_coord1 + ivec2(0, 1)) & texSizeMask1, level1)) - a000; 
  float a111 = getAnisotropyAngle(texelFetch(sampler.tex, (itex_coord1 + ivec2(1, 1)) & texSizeMask1, level1)) - a000; 
 
  // Detect if the angle warps inside the filtering footprint, and fix it 
  a001 += abs(a001) > M_PI ? sign(a001) * -M_2PI + a000 : a000; 
  a010 += abs(a010) > M_PI ? sign(a010) * -M_2PI + a000 : a000; 
  a011 += abs(a011) > M_PI ? sign(a011) * -M_2PI + a000 : a000; 
  a100 += abs(a100) > M_PI ? sign(a100) * -M_2PI + a000 : a000; 
  a101 += abs(a101) > M_PI ? sign(a101) * -M_2PI + a000 : a000; 
  a110 += abs(a110) > M_PI ? sign(a110) * -M_2PI + a000 : a000; 
  a111 += abs(a111) > M_PI ? sign(a111) * -M_2PI + a000 : a000; 
 
  // Trilinear blending of the samples 
  vec2 t0 = coord.tex_coord * vec2(texSize0) - vec2(itex_coord0); 
  vec2 t1 = coord.tex_coord * vec2(texSize1) - vec2(itex_coord1); 
  return mix( 
    mix(mix(a000, a001, t0.x), mix(a010, a011, t0.x), t0.y), 
    mix(mix(a100, a101, t1.x), mix(a110, a111, t1.x), t1.y), 
    level - float(level0)); 
}

Return sampled opacity or a default value

float getOpacity(vec4 sampledValue) 
{ 
  return sampledValue.r + DEFAULT_OPACITY * (1.0 - sampledValue.g); 
} 
 
float getOpacity(SamplerSparse sampler, SparseCoord coord) 
{ 
  return getOpacity(textureSparse(sampler, coord)); 
}

Return sampled height or a default value

float getHeight(vec4 sampledValue) 
{ 
  return sampledValue.r + DEFAULT_HEIGHT * (1.0 - sampledValue.g); 
} 
 
float getHeight(SamplerSparse sampler, SparseCoord coord) 
{ 
  return getHeight(textureSparse(sampler, coord)); 
}

Return sampled displacement or a default value

float getDisplacement(vec4 sampledValue) 
{ 
  return sampledValue.r + DEFAULT_DISPLACEMENT * (1.0 - sampledValue.g); 
} 
 
float getDisplacement(SamplerSparse sampler, SparseCoord coord) 
{ 
  return getDisplacement(textureSparse(sampler, coord)); 
}

Return ambient occlusion

float getAO(SparseCoord coord, bool is_premult) 
{ 
  vec2 ao_lookup = textureSparse(base_ao_tex, coord).ra; 
  float ao = ao_lookup.x + DEFAULT_AO * (1.0 - ao_lookup.y); 
 
  if (ao_tex.is_set) { 
    ao_lookup = textureSparse(ao_tex, coord).rg; 
    if (!is_premult) ao_lookup.x *= ao_lookup.y; 
    float channel_ao = ao_lookup.x + DEFAULT_AO * (1.0 - ao_lookup.y); 
    if (ao_blending_mode == BlendingMode_Replace) { 
      ao = channel_ao; 
    } else if (ao_blending_mode == BlendingMode_Multiply) { 
      ao *= channel_ao; 
    } 
  } 
 
  // Modulate AO value by AO_intensity 
  return mix(1.0, ao, ao_intensity); 
}

Helper to get ambient occlusion for shading

float getAO(SparseCoord coord) 
{ 
  return getAO(coord, true); 
}

Return specular level

float getSpecularLevel(vec4 sampledValue) 
{ 
  return sampledValue.r + DEFAULT_SPECULAR_LEVEL * (1.0 - sampledValue.g); 
} 
 
float getSpecularLevel(SamplerSparse sampler, SparseCoord coord) 
{ 
  return getSpecularLevel(textureSparse(sampler, coord)); 
}

Fetch the shadowing factor (screen-space)

float getShadowFactor() 
{ 
  float shadowFactor = 1.0; 
 
  if (sm_enable) { 
    vec2 screenCoord = (gl_FragCoord.xy * vec2(screen_size.z, screen_size.w)); 
    vec2 shadowSample = texture(sm_tex, screenCoord).xy; 
    // shadowSample.x / shadowSample.y is the normalized shadow factor. 
    // shadowSample.x may already be normalized, shadowSample.y contains 0.0 in this case. 
    shadowFactor = shadowSample.y == 0.0 ? shadowSample.x : shadowSample.x / shadowSample.y; 
  } 
 
  return mix(1.0, shadowFactor, sm_opacity); 
}

Return sampled base color or a default value

vec3 getBaseColor(vec4 sampledValue) 
{ 
  return sampledValue.rgb + DEFAULT_BASE_COLOR * (1.0 - sampledValue.a); 
} 
 
vec3 getBaseColor(SamplerSparse sampler, SparseCoord coord) 
{ 
  return getBaseColor(textureSparse(sampler, coord)); 
}

Return sampled diffuse color or a default value

vec3 getDiffuse(vec4 sampledValue) 
{ 
  return getBaseColor(sampledValue); 
} 
 
vec3 getDiffuse(SamplerSparse sampler, SparseCoord coord) 
{ 
  return getDiffuse(textureSparse(sampler, coord)); 
}

Return sampled specular color or a default value

vec3 getSpecularColor(vec4 sampledValue) 
{ 
  vec3 specColor = sampledValue.rgb + DEFAULT_BASE_COLOR * (1.0 - sampledValue.a); 
  vec3 defaultF0 = mix(vec3(0.04), specColor, DEFAULT_METALLIC); 
  return mix(specColor, defaultF0, (1.0 - sampledValue.a)); 
} 
 
vec3 getSpecularColor(SamplerSparse sampler, SparseCoord coord) 
{ 
  return getSpecularColor(textureSparse(sampler, coord)); 
}

Generate anisotropic roughness from roughness and anisotropy level

vec2 generateAnisotropicRoughness(float roughness, float anisoLevel) 
{ 
  return vec2(roughness, roughness / sqrt(max(1e-8, 1.0 - anisoLevel))); 
}

Generate diffuse color from base color and metallic factor

vec3 generateDiffuseColor(vec3 baseColor, float metallic) 
{ 
  return baseColor * (1.0 - metallic); 
}

Generate specular color from dielectric specular level, base color and metallic factor

vec3 generateSpecularColor(float specularLevel, vec3 baseColor, float metallic) 
{ 
  return mix(vec3(0.08 * specularLevel), baseColor, metallic); 
}

Generate specular color from base color and metallic factor, using default specular level (0.04) for dielectrics

vec3 generateSpecularColor(vec3 baseColor, float metallic) 
{ 
  return mix(vec3(0.04), baseColor, metallic); 
}

Return sampled scattering value or a default value

float getScattering(vec4 sampledValue) 
{ 
  return sampledValue.r + DEFAULT_SCATTERING * (1.0 - sampledValue.g); 
} 
 
float getScattering(SamplerSparse sampler, SparseCoord coord) 
{ 
  return getScattering(textureSparse(sampler, coord)); 
} 
 

Get help faster and easier

New user?