Images declaration and usage

Table of Contents

1. Description
2. Examples
   • CombinedImage
   • SampledImage
   • StorageImage

Description

ShaderWriter follows the SPIR-V (and HLSL) model for images, and provides three image types:

• sdw::CombinedImage, declared using ShaderWriter::declCombinedImg, is the combination of an sdw::Sampler and an sdw::SampledImage, and you can sample/fetch directly from it.
• sdw::Sampler, declared using ShaderWriter::declSampler, represents just a sampler.
• sdw::SampledImage, declared using ShaderWriter::declSampledImg needs to to be combined with an sdw::Sampler, using the sdw::combine intrinsic, for you to be able to sample from them.
• sdw::StorageImage, declared using ShaderWriter::declStorageImg, is a storage image, from which you can load/store and perform atomic operations, when available.

In addition to this, you can declare array images (GLSL's samplerArray) and images arrays (GLSL's sampler[]).

• Array images are a type you pass to the template parameter of the ShaderWriter::declXxxImg functions.
• Images arrays are declared using the array variant of those functions: ShaderWriter::declXxxImgArray.

Examples

CombinedImage

Single:

auto map = writer.declCombinedImg< FImg2DRgba32 >( "map"
    , 0u    // binding
    , 0u ); // set
// ...
map.sample( uv ); // uv is a vec2
map.lod( uv, miplevel ); // uv is a vec2

Array image:

auto map = writer.declCombinedImg< FImg2DArrayRgba32 >( "map"
    , 0u    // binding
    , 0u ); // set
// ...
map.sample( uv ); // uv is a vec3
map.lod( uv, miplevel ); // uv is a vec3

Images array:

auto map = writer.declCombinedImgArray< FImg2DRgba32 >( "map"
    , 0u     // binding
    , 0u     // set
    , 10u ); // array dimensions
// ...
map[0u].sample( uv ); // uv is a vec2
map[0u].lod( uv, miplevel ); // uv is a vec2

SampledImage

Single:

auto map = writer.declSampledImg< FImg2DRgba32 >( "map"
    , 0u    // binding
    , 0u ); // set
auto sampler = writer.declSampler< false /*ComparisonMode*/ >( "samp"
    , 1u    // binding
    , 0u ); // set
auto combined = writer.declLocale( "combined"
    , combine( map, sampler ) );
// ...
combined.sample( uv ); // uv is a vec2
combine( map, sampler ).lod( uv, miplevel ); // uv is a vec2

Array image:

auto map = writer.declSampledImg< FImg2DArrayRgba32 >( "map"
    , 0u    // binding
    , 0u ); // set
auto sampler = writer.declSampler< false /*ComparisonMode*/ >( "samp"
    , 1u    // binding
    , 0u ); // set
auto combined = writer.declLocale( "combined"
    , combine( map, sampler ) );
// ...
combined.sample( uv ); // uv is a vec3
combine( map, sampler ).lod( uv, miplevel ); // uv is a vec3

Images array:

auto map = writer.declSampledImgArray< FImg2DRgba32 >( "map"
    , 0u     // binding
    , 0u     // set
    , 10u ); // array dimensions
auto sampler = writer.declSampler< false /*ComparisonMode*/ >( "samp"
    , 1u     // binding
    , 0u     // set
    , 10u ); // array dimensions
auto combined = writer.declLocale( "combined"
    , combine( map[0u], sampler[0u] ) );
// ...
combined.sample( uv ); // uv is a vec2
combine( map[0u], sampler[0u] ).lod( uv, miplevel ); // uv is a vec2

StorageImage

Single:

auto map = writer.declStorageImg< RWFImg2DRgba32 >( "map"
    , 0u    // binding
    , 0u ); // set
// ...
map.load( coord ); // coord is an ivec2
map.store( coord ); // coord is an ivec2

Array image:

auto map = writer.declStorageImg< RWFImg2DArrayRgba32 >( "map"
    , 0u    // binding
    , 0u ); // set
// ...
map.load( coord ); // coord is an ivec3
map.store( coord ); // coord is an ivec3

Images array:

auto map = writer.declStorageImgArray< RWFImg2DRgba32 >( "map"
    , 0u     // binding
    , 0u     // set
    , 10u ); // array dimensions
// ...
map[0u].load( coord ); // coord is an ivec2
map[0u].store( coord ); // coord is an ivec2