Blender V5.3
blender::ShaderCreateInfo Struct Reference

Describe inputs & outputs, stage interfaces, resources and sources of a shader. If all data is correctly provided, this is all that is needed to create and compile a #gpu::Shader. More...

#include <gpu_shader_create_info.hh>

Inherited by blender::gpu::shader::GPUCodegenCreateInfo.

Classes

struct  Conditions
struct  BuiltinBit
struct  VertIn
struct  GeometryStageLayout
struct  ComputeStageLayout
struct  FragOut
struct  SubpassIn
struct  SharedVariable
struct  Sampler
struct  Image
struct  UniformBuf
struct  StorageBuf
struct  AccelerationStructure
struct  Resource
struct  StageInterfaceInfoHandle
struct  PushConst
struct  AdditionalInfo

Public Types

using ConditionFn = std::function<bool(Span<CompilationConstant>)>
using Self = ShaderCreateInfo

Public Member Functions

BuiltinBits builtins_combined () const
Vector< Resource, 0 > & resources_get_ (Frequency freq)
Vector< Resource > resources_get_all_ () const
 ShaderCreateInfo (const char *name)
 ~ShaderCreateInfo ()=default
Self & noop ()
Shaders in/outs (fixed function pipeline config)
Self & vertex_in (int slot, Type type, StringRefNull name, ConditionFn cond=nullptr)
Self & vertex_out (StageInterfaceInfo &interface, ConditionFn cond=nullptr)
Self & geometry_layout (PrimitiveIn prim_in, PrimitiveOut prim_out, int max_vertices, int invocations=-1)
Self & local_group_size (int local_size_x, int local_size_y=1, int local_size_z=1)
Self & early_fragment_test (bool enable)
Self & geometry_out (StageInterfaceInfo &interface, ConditionFn cond=nullptr)
Self & fragment_out (int slot, Type type, StringRefNull name, DualBlend blend=DualBlend::NONE, int raster_order_group=-1, ConditionFn cond=nullptr)
Self & subpass_in (int slot, Type type, ImageType img_type, StringRefNull name, int raster_order_group=-1)
Self & shared_resource_descriptor (void(*fn)(ShaderCreateInfo &))
Shader compilation constants

Compilation constants are constants defined in the create info. They cannot be changed after the shader is created. It is a replacement to macros with added type safety.

Self & compilation_constant (Type type, StringRefNull name, double default_value)
Shader specialization constants
Self & specialization_constant (Type type, StringRefNull name, double default_value)
Compute shader Shared variables
Self & shared_variable (Type type, StringRefNull name)
Resources bindings points
Self & uniform_buf (int slot, StringRefNull type_name, StringRefNull name, Frequency freq=Frequency::PASS, ConditionFn cond=nullptr)
Self & storage_buf (int slot, Qualifier qualifiers, StringRefNull type_name, StringRefNull name, Frequency freq=Frequency::PASS, ConditionFn cond=nullptr)
Self & acceleration_structure (int slot, StringRefNull name, Frequency freq=Frequency::PASS, ConditionFn cond=nullptr)
Self & image (int slot, TextureFormat format, Qualifier qualifiers, ImageReadWriteType type, StringRefNull name, Frequency freq=Frequency::PASS, ConditionFn cond=nullptr)
Self & sampler (int slot, ImageType type, StringRefNull name, Frequency freq=Frequency::PASS, ConditionFn cond=nullptr)
Shader Source
Self & vertex_source (StringRefNull filename)
Self & fragment_source (StringRefNull filename)
Self & compute_source (StringRefNull filename)
Self & vertex_function (StringRefNull function_name)
Self & fragment_function (StringRefNull function_name)
Self & compute_function (StringRefNull function_name)
Push constants

Data managed by gpu::Shader. Can be set through uniform functions. Must be less than 128bytes.

Self & push_constant (Type type, StringRefNull name, int array_size=0, ConditionFn cond=nullptr)
Defines
Self & define (StringRefNull name, StringRefNull value="")
Self & do_static_compilation (bool value)
Self & builtins (BuiltinBits builtin, ConditionFn cond=nullptr)
Self & depth_write (DepthWrite value)
Self & metal_backend_only (bool flag)
Additional Create Info

Used to share parts of the infos that are common to many shaders.

Self & additional_info (StringRefNull info_name)
template<typename... Args>
Self & additional_info (StringRefNull info_name, Args... args)
Self & additional_info_with_condition (StringRefNull info_name, ConditionFn cond=nullptr)
Typedef Sources

Some resource declarations might need some special structure defined. Adding a file using typedef_source will include it before the resource and interface definitions.

Self & typedef_source (StringRefNull filename)
mtl_max_total_threads_per_threadgroup

max_total_threads_per_threadgroup - Provides compiler hint for maximum threadgroup size up front. Maximum value is 1024.

Self & mtl_max_total_threads_per_threadgroup (ushort max_total_threads_per_threadgroup)
Recursive evaluation.

Flatten all dependency so that this descriptor contains all the data from the additional descriptors. This avoids tedious traversal in shader source creation.

void finalize (const bool recursive=false)
std::string resource_guard_defines (Span< CompilationConstant > constants) const
std::string iface_guard_defines () const
void extend_predicate (Vector< Resource, 0 > &resource_vector, ShaderCreateInfo::Resource res_copy, Span< ConditionFn > additional_conditions) const
void extend_predicate (Vector< PushConst, 0 > &resource_vector, ShaderCreateInfo::PushConst res_copy, Span< ConditionFn > additional_conditions) const
void assert_no_overlap (const ShaderCreateInfo &info, const bool test, const StringRefNull error) const
void set_resource_slot (Resource &res, int &images, int &samplers, int &ubos, int &ssbos, int &acceleration_structures) const
std::string check_error () const
bool is_vulkan_compatible () const
void validate_merge (const ShaderCreateInfo &other_info)
void validate_vertex_attributes (const ShaderCreateInfo *other_info=nullptr)
Pipeline warm-up
PipelineState & pipeline_state ()
 Create a new pipeline state.

Static Public Member Functions

static int find_constant (Span< CompilationConstant > constants, StringRefNull name)

Public Attributes

std::string name_
bool do_static_compilation_ = false
bool is_generated_ = true
bool finalized_ = false
bool early_fragment_test_ = false
DepthWrite depth_write_ = DepthWrite::UNCHANGED
bool metal_backend_only_ = false
size_t interface_names_size_ = 0
Vector< BuiltinBit, 0 > builtins_
std::string vertex_source_generated
std::string fragment_source_generated
std::string compute_source_generated
std::string geometry_source_generated
std::string typedef_source_generated
Vector< StringRefNull, 0 > dependencies_generated
GeneratedSourceList generated_sources
Vector< VertIn, 0 > vertex_inputs_
GeometryStageLayout geometry_layout_
ComputeStageLayout compute_layout_
Vector< FragOut, 0 > fragment_outputs_
Vector< SubpassIn, 0 > subpass_inputs_
Vector< CompilationConstant, 0 > compilation_constants_
Vector< SpecializationConstant, 0 > specialization_constants_
Vector< SharedVariable, 0 > shared_variables_
Vector< Resource, 0 > pass_resources_
Vector< Resource, 0 > batch_resources_
Vector< Resource, 0 > geometry_resources_
Vector< StageInterfaceInfoHandle, 0 > vertex_out_interfaces_
Vector< StageInterfaceInfoHandle, 0 > geometry_out_interfaces_
Vector< PushConst, 0 > push_constants_
Vector< StringRefNull, 0 > typedef_sources_
StringRefNull vertex_source_
StringRefNull geometry_source_
StringRefNull fragment_source_
StringRefNull compute_source_
StringRefNull vertex_entry_fn_ = "main"
StringRefNull geometry_entry_fn_ = "main"
StringRefNull fragment_entry_fn_ = "main"
StringRefNull compute_entry_fn_ = "main"
Vector< std::array< StringRefNull, 2 >, 0 > defines_
Vector< AdditionalInfo, 0 > additional_infos_
Vector< PipelineState, 0 > pipelines_

Operators.

bool operator== (const ShaderCreateInfo &b) const
bool has_resource_type (Resource::BindType bind_type) const
bool has_resource_image () const
int sampler_count () const
int max_sampler_slot () const
std::ostream & operator<< (std::ostream &stream, const ShaderCreateInfo &info)

Detailed Description

Describe inputs & outputs, stage interfaces, resources and sources of a shader. If all data is correctly provided, this is all that is needed to create and compile a #gpu::Shader.

IMPORTANT: All strings are references only. Make sure all the strings used by a ShaderCreateInfo are not freed until it is consumed or deleted.

Definition at line 799 of file gpu_shader_create_info.hh.

Member Typedef Documentation

◆ ConditionFn

◆ Self

Constructor & Destructor Documentation

◆ ShaderCreateInfo()

ShaderCreateInfo::ShaderCreateInfo ( const char * name)

Definition at line 101 of file gpu_shader_create_info.cc.

Referenced by blender::pygpu_shader_info__tp_new().

◆ ~ShaderCreateInfo()

Member Function Documentation

◆ acceleration_structure()

◆ additional_info() [1/2]

◆ additional_info() [2/2]

template<typename... Args>
Self & blender::gpu::shader::ShaderCreateInfo::additional_info ( StringRefNull info_name,
Args... args )
inline

Definition at line 1605 of file gpu_shader_create_info.hh.

◆ additional_info_with_condition()

◆ assert_no_overlap()

void ShaderCreateInfo::assert_no_overlap ( const ShaderCreateInfo & info,
const bool test,
const StringRefNull error ) const

Definition at line 298 of file gpu_shader_create_info.cc.

◆ builtins()

◆ builtins_combined()

◆ check_error()

std::string ShaderCreateInfo::check_error ( ) const

Definition at line 335 of file gpu_shader_create_info.cc.

◆ compilation_constant()

Definition at line 1310 of file gpu_shader_create_info.hh.

◆ compute_function()

◆ compute_source()

◆ define()

◆ depth_write()

◆ do_static_compilation()

◆ early_fragment_test()

Force fragment tests before fragment shader invocation. IMPORTANT: This is incompatible with using the gl_FragDepth output.

Definition at line 1243 of file gpu_shader_create_info.hh.

◆ extend_predicate() [1/2]

void ShaderCreateInfo::extend_predicate ( Vector< PushConst, 0 > & resource_vector,
ShaderCreateInfo::PushConst res_copy,
Span< ConditionFn > additional_conditions ) const

IMPORTANT: We keep duplicates until we evaluate the conditions.

Definition at line 289 of file gpu_shader_create_info.cc.

◆ extend_predicate() [2/2]

void ShaderCreateInfo::extend_predicate ( Vector< Resource, 0 > & resource_vector,
ShaderCreateInfo::Resource res_copy,
Span< ConditionFn > additional_conditions ) const

IMPORTANT: We keep duplicates until we evaluate the conditions.

Definition at line 280 of file gpu_shader_create_info.cc.

◆ finalize()

void ShaderCreateInfo::finalize ( const bool recursive = false)

Definition at line 141 of file gpu_shader_create_info.cc.

◆ find_constant()

◆ fragment_function()

◆ fragment_out()

Self & blender::gpu::shader::ShaderCreateInfo::fragment_out ( int slot,
Type type,
StringRefNull name,
DualBlend blend = DualBlend::NONE,
int raster_order_group = -1,
ConditionFn cond = nullptr )
inline

Definition at line 1261 of file gpu_shader_create_info.hh.

◆ fragment_source()

◆ geometry_layout()

Self & blender::gpu::shader::ShaderCreateInfo::geometry_layout ( PrimitiveIn prim_in,
PrimitiveOut prim_out,
int max_vertices,
int invocations = -1 )
inline

Definition at line 1219 of file gpu_shader_create_info.hh.

◆ geometry_out()

Only needed if geometry shader is enabled. IMPORTANT: Input and output instance name will have respectively "_in" and "_out" suffix appended in the geometry shader IF AND ONLY IF the vertex_out interface instance name matches the geometry_out interface instance name.

Definition at line 1255 of file gpu_shader_create_info.hh.

◆ has_resource_image()

◆ has_resource_type()

◆ iface_guard_defines()

std::string ShaderCreateInfo::iface_guard_defines ( ) const

Definition at line 132 of file gpu_shader_create_info.cc.

◆ image()

◆ is_vulkan_compatible()

bool ShaderCreateInfo::is_vulkan_compatible ( ) const

Definition at line 82 of file gpu_shader_create_info.cc.

◆ local_group_size()

Self & blender::gpu::shader::ShaderCreateInfo::local_group_size ( int local_size_x,
int local_size_y = 1,
int local_size_z = 1 )
inline

Definition at line 1231 of file gpu_shader_create_info.hh.

◆ max_sampler_slot()

◆ metal_backend_only()

◆ mtl_max_total_threads_per_threadgroup()

Definition at line 1649 of file gpu_shader_create_info.hh.

◆ noop()

◆ operator==()

bool blender::gpu::shader::ShaderCreateInfo::operator== ( const ShaderCreateInfo & b) const
inline

Definition at line 1707 of file gpu_shader_create_info.hh.

◆ pipeline_state()

Create a new pipeline state.

On Metal and Vulkan pipelines states will be pre-compiled when creating the shader to reduce compilation stuttering when using the shader.

Note
returned pipeline state is only guaranteed to be valid until the next call to this function.

Definition at line 1852 of file gpu_shader_create_info.hh.

◆ push_constant()

Definition at line 1533 of file gpu_shader_create_info.hh.

◆ resource_guard_defines()

std::string ShaderCreateInfo::resource_guard_defines ( Span< CompilationConstant > constants) const

Definition at line 117 of file gpu_shader_create_info.cc.

◆ resources_get_()

◆ resources_get_all_()

◆ sampler()

◆ sampler_count()

◆ set_resource_slot()

void ShaderCreateInfo::set_resource_slot ( Resource & res,
int & images,
int & samplers,
int & ubos,
int & ssbos,
int & acceleration_structures ) const

Definition at line 309 of file gpu_shader_create_info.cc.

◆ shared_resource_descriptor()

◆ shared_variable()

◆ specialization_constant()

Definition at line 1360 of file gpu_shader_create_info.hh.

◆ storage_buf()

Definition at line 1421 of file gpu_shader_create_info.hh.

◆ subpass_in()

Self & blender::gpu::shader::ShaderCreateInfo::subpass_in ( int slot,
Type type,
ImageType img_type,
StringRefNull name,
int raster_order_group = -1 )
inline

Allows to fetch frame-buffer values from previous render sub-pass.

On Apple Silicon, the additional raster_order_group is there to set the sub-pass dependencies. Any sub-pass input need to have the same raster_order_group defined in the shader writing them.

IMPORTANT: Currently emulated on all backend except Metal. This is only for debugging purpose as it is too slow to be viable.

TODO(fclem): Vulkan can implement that using subpassInput. However sub-pass boundaries might be difficult to inject implicitly and will require more high level changes. TODO(fclem): OpenGL can emulate that using GL_EXT_shader_framebuffer_fetch.

Definition at line 1287 of file gpu_shader_create_info.hh.

◆ typedef_source()

◆ uniform_buf()

◆ validate_merge()

void ShaderCreateInfo::validate_merge ( const ShaderCreateInfo & other_info)

Error detection that some backend compilers do not complain about.

Definition at line 522 of file gpu_shader_create_info.cc.

◆ validate_vertex_attributes()

void ShaderCreateInfo::validate_vertex_attributes ( const ShaderCreateInfo * other_info = nullptr)

Definition at line 598 of file gpu_shader_create_info.cc.

◆ vertex_function()

◆ vertex_in()

Definition at line 1205 of file gpu_shader_create_info.hh.

◆ vertex_out()

◆ vertex_source()

◆ operator<<

std::ostream & operator<< ( std::ostream & stream,
const ShaderCreateInfo & info )
friend

Debug print

Definition at line 1736 of file gpu_shader_create_info.hh.

Member Data Documentation

◆ additional_infos_

◆ batch_resources_

◆ builtins_

◆ compilation_constants_

◆ compute_entry_fn_

◆ compute_layout_

◆ compute_source_

◆ compute_source_generated

◆ defines_

◆ dependencies_generated

Manually set generated dependencies file names.

Definition at line 874 of file gpu_shader_create_info.hh.

◆ depth_write_

Allow optimization when fragment shader writes to gl_FragDepth.

Definition at line 834 of file gpu_shader_create_info.hh.

◆ do_static_compilation_

True if the shader is static and can be pre-compiled at compile time.

Definition at line 826 of file gpu_shader_create_info.hh.

◆ early_fragment_test_

If true, force depth and stencil tests to always happen before fragment shader invocation.

Definition at line 832 of file gpu_shader_create_info.hh.

◆ finalized_

If true, all additionally linked create info will be merged into this one.

Definition at line 830 of file gpu_shader_create_info.hh.

◆ fragment_entry_fn_

◆ fragment_outputs_

◆ fragment_source_

◆ fragment_source_generated

◆ generated_sources

◆ geometry_entry_fn_

◆ geometry_layout_

◆ geometry_out_interfaces_

◆ geometry_resources_

◆ geometry_source_

◆ geometry_source_generated

◆ interface_names_size_

Maximum length of all the resource names including each null terminator. Only for names used by #gpu::ShaderInterface.

Definition at line 844 of file gpu_shader_create_info.hh.

◆ is_generated_

True if the shader is not part of gpu_shader_create_info_list.

Definition at line 828 of file gpu_shader_create_info.hh.

◆ metal_backend_only_

GPU Backend compatibility flag. Temporary requirement until Metal enablement is fully complete.

Definition at line 839 of file gpu_shader_create_info.hh.

◆ name_

Shader name for debugging.

Definition at line 824 of file gpu_shader_create_info.hh.

◆ pass_resources_

Resources are grouped by frequency of change. Pass resources are meant to be valid for the whole pass. Batch resources can be changed in a more granular manner (per object/material). Geometry resources can be changed in a very granular manner (per draw-call). Misuse will only produce suboptimal performance.

Definition at line 1084 of file gpu_shader_create_info.hh.

◆ pipelines_

◆ push_constants_

◆ shared_variables_

◆ specialization_constants_

◆ subpass_inputs_

◆ typedef_source_generated

◆ typedef_sources_

◆ vertex_entry_fn_

◆ vertex_inputs_

◆ vertex_out_interfaces_

◆ vertex_source_

◆ vertex_source_generated

Manually set generated code.

Definition at line 868 of file gpu_shader_create_info.hh.


The documentation for this struct was generated from the following files: