Struct Compiler

pub struct Compiler<T> { /* private fields */ }

An instance of a SPIRV-Cross compiler.

Depending on the target, different methods will be available.

Once compiled into a CompiledArtifact, reflection methods will still remain available, but the instance will be frozen, and no more mutation will be available.

Implementations

impl Compiler<Glsl>

pub fn flatten_buffer_block( &mut self, block: impl Into<Handle<VariableId>>, ) -> Result<(), SpirvCrossError>

Available on crate feature glsl only.

Legacy GLSL compatibility method.

Takes a uniform or push constant variable and flattens it into a (i|u)vec4 array[N]; array instead. For this to work, all types in the block must be the same basic type, e.g. mixing vec2 and vec4 is fine, but mixing int and float is not.

The name of the uniform array will be the same as the interface block name.

pub fn required_extensions(&self) -> GlslExtensionsIter<'_>

Available on crate feature glsl only.

Returns the list of required extensions in a GLSL shader.

If called after compilation this will contain any other extensions that the compiler used automatically, in addition to the user specified ones.

impl Compiler<Hlsl>

HLSL specific APIs.

pub fn add_resource_binding( &mut self, stage: ExecutionModel, binding: ResourceBinding, bind_target: &BindTarget, ) -> Result<(), SpirvCrossError>

Available on crate feature hlsl only.

Add a resource binding to the HLSL compilation.

Register bindings are set based on whether the HLSL resource is a CBV, UAV, SRV or Sampler.

A single binding in SPIR-V might contain multiple resource types, e.g. COMBINED_IMAGE_SAMPLER, and SRV/Sampler bindings will be used respectively.

On SM 5.0 and lower, register_space is ignored.

For deeper control of push constants, Compiler<Hlsl>::set_root_constant_layout can be used instead.

If resource bindings are provided, CompiledArtifact<Hlsl>::is_resource_used will return true if the set/binding combination was used by the HLSL code.

pub fn remap_vertex_attribute<'str>( &mut self, location: u32, semantic: impl Into<CompilerStr<'str>>, ) -> Result<(), SpirvCrossError>

Available on crate feature hlsl only.

Compiles and remap vertex attribute at specific locations to a fixed semantic.

The default is TEXCOORD# where # denotes location. Matrices are unrolled to vectors with notation ${SEMANTIC}_#, where # denotes row. $SEMANTIC is either TEXCOORD# or a semantic name specified here.

pub fn set_root_constant_layout( &mut self, constant_info: &[RootConstants], ) -> Result<(), SpirvCrossError>

Available on crate feature hlsl only.

Optionally specify a custom root constant layout.

Push constants ranges will be split up according to the layout specified.

pub fn set_resource_binding_flags( &mut self, flags: BindingFlags, ) -> Result<(), SpirvCrossError>

Available on crate feature hlsl only.

Controls how resource bindings are declared in the output HLSL.

pub fn remap_num_workgroups_builtin(&mut self) -> Option<Handle<VariableId>>

Available on crate feature hlsl only.

This is a special HLSL workaround for the NumWorkGroups builtin. This does not exist in HLSL, so the calling application must create a dummy cbuffer in which the application will store this builtin.

The cbuffer layout will be:

 cbuffer SPIRV_Cross_NumWorkgroups : register(b#, space#) {
    uint3 SPIRV_Cross_NumWorkgroups_count;
};

This must be called before Compiler::compile if the NumWorkgroups builtin is used, or compilation will fail.

The function returns None if NumWorkGroups builtin is not statically used in the shader from the current entry point.

If Some, returns the variable ID of a cbuffer which corresponds to the cbuffer declared above.

By default, no binding or descriptor set decoration is set, so the calling application should declare explicit bindings on this ID before calling Compiler::compile.

pub fn mask_stage_output_by_location( &mut self, location: u32, component: u32, ) -> Result<(), SpirvCrossError>

Available on crate feature hlsl only.

Mask a stage output by location.

If a shader output is active in this stage, but inactive in a subsequent stage, this can be signalled here. This can be used to work around certain cross-stage matching problems which plagues HLSL in certain scenarios.

An output which matches one of these will not be emitted in stage output interfaces, but rather treated as a private variable.

This option is only meaningful for MSL and HLSL, since GLSL matches by location directly.

pub fn mask_stage_output_by_builtin( &mut self, builtin: BuiltIn, ) -> Result<(), SpirvCrossError>

Available on crate feature hlsl only.

Mask a stage output by builtin. Masking builtins only takes effect if the builtin in question is part of the stage output interface.

If a shader output is active in this stage, but inactive in a subsequent stage, this can be signalled here. This can be used to work around certain cross-stage matching problems which plagues HLSL in certain scenarios.

An output which matches one of these will not be emitted in stage output interfaces, but rather treated as a private variable.

This option is only meaningful for MSL and HLSL, since GLSL matches by location directly. Masking builtins only takes effect if the builtin in question is part of the stage output interface.

impl Compiler<Msl>

MSL specific APIs.

pub fn is_rasterization_disabled(&self) -> bool

Available on crate feature msl only.

Get whether the vertex shader requires rasterization to be disabled.

pub fn buffer_requirements(&self) -> BufferRequirements

Available on crate feature msl only.

Get information such as required buffers for the MSL shader

pub fn add_shader_input( &mut self, location: u32, variable: &ShaderInterfaceVariable, ) -> Result<(), SpirvCrossError>

Available on crate feature msl only.

Add a shader interface variable description used to fix up shader input variables.

If shader inputs are provided, CompiledArtifact::is_shader_input_used will return true after calling Compiler::compile if the location were used by the MSL code.

Note: this covers the functionality implemented by the SPIR-V Cross C API spvc_compiler_msl_add_vertex_attribute.

pub fn add_shader_output( &mut self, location: u32, variable: &ShaderInterfaceVariable, ) -> Result<(), SpirvCrossError>

Available on crate feature msl only.

Add a shader interface variable description used to fix up shader output variables.

If shader outputs are provided, CompiledArtifact::is_shader_input_used will return true after calling Compiler::compile if the location were used by the MSL code.

Note: this covers the functionality implemented by the SPIR-V Cross C API spvc_compiler_msl_add_vertex_attribute.

pub fn add_resource_binding( &mut self, stage: ExecutionModel, binding: ResourceBinding, bind_target: &BindTarget, ) -> Result<(), SpirvCrossError>

Available on crate feature msl only.

Add a resource binding to indicate the MSL buffer, texture or sampler index to use for a particular resource.

If resource bindings are provided, CompiledArtifact<Msl>::is_resource_used will return true after Compiler::compile if the set/binding combination was used by the MSL code.

pub fn add_discrete_descriptor_set( &mut self, desc_set: u32, ) -> Result<(), SpirvCrossError>

Available on crate feature msl only.

When using MSL argument buffers, we can force “classic” MSL 1.0 binding schemes for certain descriptor sets. This corresponds to VK_KHR_push_descriptor in Vulkan.

pub fn add_dynamic_buffer( &mut self, desc_set: u32, binding: u32, index: u32, ) -> Result<(), SpirvCrossError>

Available on crate feature msl only.

This function marks a resource as using a dynamic offset (VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC or VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC).

desc_set and binding are the SPIR-V descriptor set and binding of a buffer resource in this shader.

index is the index within the dynamic offset buffer to use.

This function only has any effect if argument buffers are enabled. If so, the buffer will have its address adjusted at the beginning of the shader with an offset taken from the dynamic offset buffer.

pub fn add_inline_uniform_block( &mut self, desc_set: u32, binding: u32, ) -> Result<(), SpirvCrossError>

Available on crate feature msl only.

This function marks a resource an inline uniform block (VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK_EXT)

desc_set and binding are the SPIR-V descriptor set and binding of a buffer resource in this shader.

This function only has any effect if argument buffers are enabled. If so, the buffer block will be directly embedded into the argument buffer, instead of being referenced indirectly via pointer.

pub fn set_argument_buffer_device_address_space( &mut self, desc_set: u32, device_address: bool, ) -> Result<(), SpirvCrossError>

Available on crate feature msl only.

If an argument buffer is large enough, it may need to be in the device storage space rather than constant. Opt-in to this behavior here on a per-set basis.

pub fn remap_constexpr_sampler( &mut self, variable: impl Into<Handle<VariableId>>, sampler: &ConstexprSampler, ycbcr: Option<&SamplerYcbcrConversion>, ) -> Result<(), SpirvCrossError>

Available on crate feature msl only.

Remap a sampler with ID to a constexpr sampler. Older iOS targets must use constexpr samplers in certain cases (PCF), so a static sampler must be used.

The sampler will not consume a binding, but be declared in the entry point as a constexpr sampler. This can be used on both combined image/samplers (sampler2D) or standalone samplers. The remapped sampler must not be an array of samplers.

Prefer Compiler<Msl>::remap_constexpr_sampler_by_binding unless you’re also doing reflection anyways.

pub fn remap_constexpr_sampler_by_binding( &mut self, desc_set: u32, binding: u32, sampler: &ConstexprSampler, ycbcr: Option<&SamplerYcbcrConversion>, ) -> Result<(), SpirvCrossError>

Available on crate feature msl only.

Remap a sampler with set/binding, to a constexpr sampler. Older iOS targets must use constexpr samplers in certain cases (PCF), so a static sampler must be used.

The sampler will not consume a binding, but be declared in the entry point as a constexpr sampler. This can be used on both combined image/samplers (sampler2D) or standalone samplers. The remapped sampler must not be an array of samplers.

Remaps based on ID take priority over set/binding remaps.

pub fn set_fragment_output_components( &mut self, location: u32, components: u32, ) -> Result<(), SpirvCrossError>

Available on crate feature msl only.

If using CompilerOptions::pad_fragment_output_components, override the number of components we expect to use for a particular location. The default is 4 if number of components is not overridden.

pub fn set_combined_sampler_suffix<'str>( &mut self, str: impl Into<CompilerStr<'str>>, ) -> Result<(), SpirvCrossError>

Available on crate feature msl only.

Set the suffix for combined image samplers.

pub fn combined_sampler_suffix(&self) -> CompilerStr<'_>

Available on crate feature msl only.

Get the suffix for combined image samplers.

pub fn mask_stage_output_by_location( &mut self, location: u32, component: u32, ) -> Result<(), SpirvCrossError>

Available on crate feature msl only.

Mask a stage output by location.

If a shader output is active in this stage, but inactive in a subsequent stage, this can be signalled here. This can be used to work around certain cross-stage matching problems which plagues MSL in certain scenarios.

An output which matches one of these will not be emitted in stage output interfaces, but rather treated as a private variable.

This option is only meaningful for MSL and HLSL, since GLSL matches by location directly.

pub fn mask_stage_output_by_builtin( &mut self, builtin: BuiltIn, ) -> Result<(), SpirvCrossError>

Available on crate feature msl only.

Mask a stage output by builtin. Masking builtins only takes effect if the builtin in question is part of the stage output interface.

If a shader output is active in this stage, but inactive in a subsequent stage, this can be signalled here. This can be used to work around certain cross-stage matching problems which plagues MSL in certain scenarios.

An output which matches one of these will not be emitted in stage output interfaces, but rather treated as a private variable.

This option is only meaningful for MSL and HLSL, since GLSL matches by location directly. Masking builtins only takes effect if the builtin in question is part of the stage output interface.

impl<T: CompilableTarget> Compiler<T>

Cross-compilation related methods.

pub fn add_header_line<'str>( &mut self, line: impl Into<CompilerStr<'str>>, ) -> Result<(), SpirvCrossError>

Adds a line in valid header position.

For example, in the GLSL backend this would be right after #version.

This is useful for enabling custom extensions which are outside the scope of SPIRV-Cross. This can be combined with variable remapping.

A new-line will be added after this line.

While this function is a more generic way of adding arbitrary text to the header of an output file, Compiler::require_extension should be used when adding extensions since it will avoid creating collisions with SPIRV-Cross generated extensions.

pub fn require_extension<'str>( &mut self, ext: impl Into<CompilerStr<'str>>, ) -> Result<(), SpirvCrossError>

Adds an extension which is required to run this shader, e.g. require_extension("GL_KHR_my_extension");

pub fn compile( self, options: &T::Options, ) -> Result<CompiledArtifact<T>, SpirvCrossError>

Consume the compilation instance, and compile source code to the output target.

impl<T> Compiler<T>

APIs for comparing handles

pub unsafe fn create_handle<I>(&self, id: I) -> Handle<I>

Create a handle for the given ID tagged with this compiler instance.

Safety

When creating a handle, the ID must be valid for the compilation.

pub unsafe fn create_handle_if_not_zero<I: Id>( &self, id: I, ) -> Option<Handle<I>>

Create a handle for the given ID tagged with this compiler instance, if the provided ID is not zero.

Safety

When creating a handle, the ID must be valid for the compilation.

pub fn handle_is_valid<I>(&self, handle: &Handle<I>) -> bool

Returns whether the given handle is valid for this compiler instance.

pub fn yield_id<I: Id>(&self, handle: Handle<I>) -> Result<I, SpirvCrossError>

Yield the value of the handle, if it originated from the same compiler instance, otherwise return SpirvCrossError::InvalidHandle.

impl<T> Compiler<T>

Reflection of buffers (UBO, SSBOs, and PushConstant blocks).

pub fn active_buffer_ranges( &self, handle: impl Into<Handle<VariableId>>, ) -> Result<&[BufferRange], SpirvCrossError>

Returns a list of which members of a struct are potentially in use by a SPIR-V shader. The granularity of this analysis is per-member of a struct. This can be used for Buffer (UBO), BufferBlock/StorageBuffer (SSBO) and PushConstant blocks.

pub fn hlsl_counter_buffer( &self, variable: impl Into<Handle<VariableId>>, ) -> Result<Option<Handle<VariableId>>, SpirvCrossError>

Queries if a buffer object has a neighbor “counter” buffer. If so, the ID of that counter buffer will be returned.

If SPV_GOOGLE_hlsl_functionality is used, this can be used even with a stripped SPIR-V module. Otherwise, this query is purely based on OpName identifiers as found in the SPIR-V module, and will only return true if OpSource was reported HLSL. To rely on this functionality, ensure that the SPIR-V module is not stripped.

impl<T> Compiler<T>

pub fn create_dummy_sampler_for_combined_images( &mut self, ) -> Result<BuiltDummySamplerProof, SpirvCrossError>

Analyzes all OpImageFetch (texelFetch) opcodes and checks if there are instances where said instruction is used without a combined image sampler. GLSL targets do not support the use of texelFetch without a sampler. To work around this, we must inject a dummy sampler which can be used to form a sampler2D at the call-site of texelFetch as necessary.

This must be called to obtain a proof to call Compiler::build_combined_image_samplers.

The proof contains the ID of a sampler object, if one dummy sampler is necessary. This ID can be decorated with set/bindings as desired before compiling.

pub fn build_combined_image_samplers( &mut self, proof: BuiltDummySamplerProof, ) -> Result<(), SpirvCrossError>

Analyzes all separate image and samplers used from the currently selected entry point, and re-routes them all to a combined image sampler instead. This is required to “support” separate image samplers in targets which do not natively support this feature, like GLSL/ESSL.

This call will add new sampled images to the SPIR-V, so it will appear in reflection if Compiler::shader_resources is called after.

If any image/sampler remapping was found, no separate image/samplers will appear in the decompiled output, but will still appear in reflection.

The resulting samplers will be void of any decorations like name, descriptor sets and binding points, so this can be added before compilation if desired.

Combined image samplers originating from this set are always considered active variables. Arrays of separate samplers are not supported, but arrays of separate images are supported. Array of images + sampler -> Array of combined image samplers.

Compiler::create_dummy_sampler_for_combined_images must be called before this to obtain a proof that a dummy sampler, if necessary, was created. Passing in a smuggled proof from a different compiler instance will result in an error.

pub fn combined_image_samplers( &self, ) -> Result<CombinedImageSamplerIter<'static>, SpirvCrossError>

Gets a remapping for the combined image samplers.

impl<T> Compiler<T>

Reflection of specialization constants.

pub fn set_specialization_constant_scalar<S: ConstantScalar>( &mut self, handle: Handle<ConstantId>, column: u32, row: u32, value: S, ) -> Result<(), SpirvCrossError>

Set the value of the specialization value at the given column and row.

The type is inferred from the input, but it is not type checked against the SPIR-V.

Using this function wrong is not unsafe, but could cause the output shader to be invalid.

Compiler::set_specialization_constant_value is more efficient and easier to use in most cases, which will handle row and column for vector and matrix scalars. This function remains to deal with more esoteric matrix shapes, or for getting only a single element of a vector or matrix.

pub fn specialization_constant_scalar<S: ConstantScalar>( &self, handle: Handle<ConstantId>, column: u32, row: u32, ) -> Result<S, SpirvCrossError>

Get the value of the specialization value at the given column and row.

The type is inferred from the return value, and is not type-checked against the input SPIR-V.

If the inferred type differs from what is expected, an indeterminate but initialized value will be returned.

Compiler::specialization_constant_value is more efficient and easier to use in most cases, which will handle row and column for vector and matrix scalars. This function remains to deal with more esoteric matrix shapes, or for getting only a single element of a vector or matrix.

pub fn specialization_constants( &self, ) -> Result<SpecializationConstantIter<'static>, SpirvCrossError>

Query declared specialization constants.

pub fn specialization_sub_constants( &self, constant: Handle<ConstantId>, ) -> Result<SpecializationSubConstantIter<'_>, SpirvCrossError>

Get subconstants for composite type specialization constants.

pub fn work_group_size_specialization_constants( &self, ) -> WorkgroupSizeSpecializationConstants

In SPIR-V, the compute work group size can be represented by a constant vector, in which case the LocalSize execution mode is ignored.

This constant vector can be a constant vector, specialization constant vector, or partly specialized constant vector. To modify and query work group dimensions which are specialization constants, constant values must be modified directly via Compiler::set_specialization_constant_value rather than using LocalSize directly. This function will return which constants should be modified.

To modify dimensions which are not specialization constants, set_execution_mode should be used directly. Arguments to set_execution_mode which are specialization constants are effectively ignored during compilation. NOTE: This is somewhat different from how SPIR-V works. In SPIR-V, the constant vector will completely replace LocalSize, while in this interface, LocalSize is only ignored for specialization constants.

The specialization constant will be written to x, y and z arguments. If the component is not a specialization constant, a zeroed out struct will be written. The return value is the constant ID of the builtin WorkGroupSize, but this is not expected to be useful for most use cases.

If LocalSizeId is used, there is no uvec3 value representing the workgroup size, so the return value is 0, but x, y and z are written as normal if the components are specialization constants.

pub fn specialization_constant_type( &self, constant: Handle<ConstantId>, ) -> Result<Handle<TypeId>, SpirvCrossError>

Get the type of the specialization constant.

impl<T> Compiler<T>

pub fn specialization_constant_value<S: ConstantValue>( &self, handle: Handle<ConstantId>, ) -> Result<S, SpirvCrossError>

Get the value of the specialization value.

The type is inferred from the return value, and is not type-checked against the input SPIR-V.

If the output type dimensions are too large for the constant, SpirvCrossError::IndexOutOfBounds will be returned.

If the inferred type differs from what is expected, an indeterminate but initialized value will be returned.

pub fn set_specialization_constant_value<S: ConstantValue>( &mut self, handle: Handle<ConstantId>, value: S, ) -> Result<(), SpirvCrossError>

Set the value of the specialization value.

The type is inferred from the input, but it is not type checked against the SPIR-V.

Using this function wrong is not unsafe, but could cause the output shader to be invalid.

If the input dimensions are too large for the constant type, SpirvCrossError::IndexOutOfBounds will be returned.

impl<T> Compiler<T>

pub fn decoration<I: Id>( &self, id: Handle<I>, decoration: Decoration, ) -> Result<Option<DecorationValue<'_>>, SpirvCrossError>

Gets the value for decorations which take arguments.

pub fn member_decoration_by_handle( &self, struct_type_id: Handle<TypeId>, index: u32, decoration: Decoration, ) -> Result<Option<DecorationValue<'_>>, SpirvCrossError>

Gets the value for member decorations which take arguments.

pub fn member_decoration( &self, member: &StructMember<'_>, decoration: Decoration, ) -> Result<Option<DecorationValue<'_>>, SpirvCrossError>

Gets the value for member decorations which take arguments.

pub fn set_decoration<'value, I: Id>( &mut self, id: Handle<I>, decoration: Decoration, value: Option<impl Into<DecorationValue<'value>>>, ) -> Result<(), SpirvCrossError>

Set the value of a decoration for an ID.

pub fn set_member_decoration<'value>( &mut self, member: &StructMember<'_>, decoration: Decoration, value: Option<impl Into<DecorationValue<'value>>>, ) -> Result<(), SpirvCrossError>

Set the value of a decoration for a struct member.

pub fn set_member_decoration_by_handle<'value>( &mut self, struct_type: Handle<TypeId>, index: u32, decoration: Decoration, value: Option<impl Into<DecorationValue<'value>>>, ) -> Result<(), SpirvCrossError>

Set the value of a decoration for a struct member by the handle of its parent struct and the index.

pub fn binary_offset_for_decoration( &self, variable: impl Into<Handle<VariableId>>, decoration: Decoration, ) -> Result<Option<u32>, SpirvCrossError>

Gets the offset in SPIR-V words (uint32_t) for a decoration which was originally declared in the SPIR-V binary. The offset will point to one or more uint32_t literals which can be modified in-place before using the SPIR-V binary.

Note that adding or removing decorations using the reflection API will not change the behavior of this function. If the decoration was declared, returns an offset into the provided SPIR-V binary buffer, otherwise returns None.

If the decoration does not have any value attached to it (e.g. DecorationRelaxedPrecision), this function will also return None.

pub fn buffer_block_decorations( &self, variable: impl Into<Handle<VariableId>>, ) -> Result<Option<&[Decoration]>, SpirvCrossError>

Get the decorations for a buffer block resource.

If the variable handle is not a handle to with struct base type, returns SpirvCrossError::InvalidArgument.

impl<T> Compiler<T>

Querying declared properties of the SPIR-V module.

pub fn declared_capabilities(&self) -> Result<&[Capability], SpirvCrossError>

Gets the list of all SPIR-V Capabilities which were declared in the SPIR-V module.

pub fn declared_extensions( &self, ) -> Result<ExtensionsIter<'static>, SpirvCrossError>

Gets the list of all SPIR-V extensions which were declared in the SPIR-V module.

pub fn execution_model(&self) -> Result<ExecutionModel, SpirvCrossError>

Get the execution model of the module.

impl<T> Compiler<T>

Querying builtins in the SPIR-V module

pub fn update_active_builtins(&mut self) -> ActiveBuiltinsUpdatedProof

Update active built-ins in the SPIR-V module.

pub fn has_active_builtin( &self, builtin: BuiltIn, storage_class: StorageClass, proof: ActiveBuiltinsUpdatedProof, ) -> Result<bool, SpirvCrossError>

Return whether the builtin is used or not.

Requires Compiler::update_active_builtins to be called first, proof of which is required to call this function.

impl<T> Compiler<T>

Reflection of entry points.

pub fn entry_points(&self) -> Result<EntryPointIter<'static>, SpirvCrossError>

All operations work on the current entry point.

Entry points can be swapped out with Compiler::set_entry_point.

Entry points should be set right after creating the compiler as some reflection functions traverse the graph from the entry point.

Resource reflection also depends on the entry point. By default, the current entry point is set to the first OpEntryPoint which appears in the SPIR-V module. Some shader languages restrict the names that can be given to entry points, and the corresponding backend will automatically rename an entry point name when compiling, if it is illegal.

For example, the common entry point name main() is illegal in MSL, and is renamed to an alternate name by the MSL backend.

Given the original entry point name contained in the SPIR-V, this function returns the name, as updated by the backend, if called after compilation.

If the name is not illegal, and has not been renamed this function will simply return the original name.

pub fn cleansed_entry_point_name<'str>( &self, name: impl Into<CompilerStr<'str>>, model: ExecutionModel, ) -> Result<Option<CompilerStr<'static>>, SpirvCrossError>

Get the cleansed name of the entry point for the given original name.

pub fn set_entry_point<'str>( &mut self, name: impl Into<CompilerStr<'str>>, model: ExecutionModel, ) -> Result<(), SpirvCrossError>

Set the current entry point by name.

All operations work on the current entry point.

Entry points should be set right after the constructor completes as some reflection functions traverse the graph from the entry point. Resource reflection also depends on the entry point.

By default, the current entry point is set to the first OpEntryPoint which appears in the SPIR-V module.

Names for entry points in the SPIR-V module may alias if they belong to different execution models. To disambiguate, we must pass along with the entry point names the execution model.

Shader language restrictions

Some shader languages restrict the names that can be given to entry points, and the corresponding backend will automatically rename an entry point name, on compilation if it is illegal.

For example, the common entry point name main() is illegal in MSL, and is renamed to an alternate name by the MSL backend.

pub fn rename_entry_point<'str>( &mut self, from: impl Into<CompilerStr<'str>>, to: impl Into<CompilerStr<'str>>, model: ExecutionModel, ) -> Result<(), SpirvCrossError>

Renames an entry point from from to to.

If old_name is currently selected as the current entry point, it will continue to be the current entry point, albeit with a new name.

Values returned from Compiler::entry_points before this call will be outdated.

impl<T> Compiler<T>

pub fn set_execution_mode( &mut self, mode: ExecutionMode, arguments: Option<ExecutionModeArguments>, )

Set or unset execution modes and arguments.

If arguments is None, unsets the execution mode. To set an execution mode that does not take arguments, pass Some(ExecutionModeArguments::None).

pub fn execution_modes(&self) -> Result<&[ExecutionMode], SpirvCrossError>

Query OpExecutionMode.

pub fn execution_mode_arguments( &self, mode: ExecutionMode, ) -> Result<Option<ExecutionModeArguments>, SpirvCrossError>

Get arguments used by the execution mode.

If the execution mode is unused, returns None.

LocalSizeId query returns an ID. If LocalSizeId execution mode is not used, it returns None. LocalSize always returns a literal. If execution mode is LocalSizeId, the literal (spec constant or not) is still returned.

impl<T> Compiler<T>

pub fn name<I: Id>( &self, handle: Handle<I>, ) -> Result<Option<CompilerStr<'_>>, SpirvCrossError>

Gets the identifier (OpName) of an ID.

pub fn set_name<'str, I: Id>( &mut self, handle: Handle<I>, string: impl Into<CompilerStr<'str>>, ) -> Result<(), SpirvCrossError>

Overrides the identifier OpName of an ID.

Identifiers beginning with underscores or identifiers which contain double underscores are reserved by the implementation.

pub fn member_name( &self, struct_type: Handle<TypeId>, index: u32, ) -> Result<Option<CompilerStr<'_>>, SpirvCrossError>

Given a struct type ID, obtain the identifier for member number “index”.

pub fn set_member_name<'str>( &mut self, struct_type: Handle<TypeId>, index: u32, string: impl Into<CompilerStr<'str>>, ) -> Result<(), SpirvCrossError>

Sets the member identifier for the given struct member.

impl<T> Compiler<T>

pub fn remapped_declared_block_name( &self, handle: impl Into<Handle<VariableId>>, ) -> Result<Option<CompilerStr<'static>>, SpirvCrossError>

When declaring buffer blocks in GLSL, the name declared in the GLSL source might not be the same as the name declared in the SPIR-V module due to naming conflicts. In this case, SPIRV-Cross needs to find a fallback-name, and it might only be possible to know this name after compiling to GLSL.

This is particularly important for HLSL input and UAVs which tends to reuse the same block type for multiple distinct blocks. For these cases it is not possible to modify the name of the type itself because it might be unique. Instead, you can use this interface to check after compilation which name was actually used if your input SPIR-V tends to have this problem.

For other names like remapped names for variables, etc., it’s generally enough to query the name of the variables after compiling, block names are an exception to this rule. handle should be a handle to a variable with a Block-like type.

This also applies to HLSL cbuffers.

impl<T> Compiler<T>

pub fn shader_resources(&self) -> Result<ShaderResources, SpirvCrossError>

Query shader resources, use ids with reflection interface to modify or query binding points, etc.

pub fn shader_resources_for_active_variables( &self, set: InterfaceVariableSet, ) -> Result<ShaderResources, SpirvCrossError>

Query shader resources, but only return the variables which are part of active_variables. E.g.: get_shader_resources(get_active_variables()) to only return the variables which are statically accessed.

impl<T> Compiler<T>

pub fn active_interface_variables( &self, ) -> Result<InterfaceVariableSet, SpirvCrossError>

Returns a set of all global variables which are statically accessed by the control flow graph from the current entry point. Only variables which change the interface for a shader are returned, that is, variables with storage class of Input, Output, Uniform, UniformConstant, PushConstant and AtomicCounter storage classes are returned.

To use the returned set as the filter for which variables are used during compilation, this set can be moved to set_enabled_interface_variables().

The return object is opaque to Rust, but its contents inspected by using InterfaceVariableSet::to_handles. There is no way to modify the contents or use your own InterfaceVariableSet.

pub fn set_enabled_interface_variables( &mut self, set: InterfaceVariableSet, ) -> Result<(), SpirvCrossError>

Sets the interface variables which are used during compilation. By default, all variables are used. Once set, Compiler::compile will only consider the set in active_variables.

impl<T> Compiler<T>

Reflection of SPIR-V types.

pub fn type_description( &self, id: Handle<TypeId>, ) -> Result<Type<'_>, SpirvCrossError>

Get the type description for the given type ID.

In most cases, a base_type_id should be passed in unless pointer specifics are desired.

Atomics are represented as TypeInner::Pointer { storage: StorageClass::AtomicCounter, ... }, usually with a scalar base type.

pub fn variable_type( &self, variable: impl Into<Handle<VariableId>>, ) -> Result<Handle<TypeId>, SpirvCrossError>

Get the underlying type of the variable.

impl<T: Target> Compiler<T>

pub fn new(spirv: Module<'_>) -> Result<Compiler<T>, SpirvCrossError>

Create a compiler instance from a SPIR-V module.

Trait Implementations

impl<T: Send> Send for Compiler<T>