Debian Codegraph @

third_party/spirv-cross/spirv_cross.hpp

raw
1 /*
2 * Copyright 2015-2020 Arm Limited
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 #ifndef SPIRV_CROSS_HPP
18 #define SPIRV_CROSS_HPP
19
20 #include "spirv.hpp"
21 #include "spirv_cfg.hpp"
22 #include "spirv_cross_parsed_ir.hpp"
23
24 namespace SPIRV_CROSS_NAMESPACE
25 {
26 struct Resource
27 {
28 // Resources are identified with their SPIR-V ID.
29 // This is the ID of the OpVariable.
30 ID id;
31
32 // The type ID of the variable which includes arrays and all type modifications.
33 // This type ID is not suitable for parsing OpMemberDecoration of a struct and other decorations in general
34 // since these modifications typically happen on the base_type_id.
35 TypeID type_id;
36
37 // The base type of the declared resource.
38 // This type is the base type which ignores pointers and arrays of the type_id.
39 // This is mostly useful to parse decorations of the underlying type.
40 // base_type_id can also be obtained with get_type(get_type(type_id).self).
41 TypeID base_type_id;
42
43 // The declared name (OpName) of the resource.
44 // For Buffer blocks, the name actually reflects the externally
45 // visible Block name.
46 //
47 // This name can be retrieved again by using either
48 // get_name(id) or get_name(base_type_id) depending if it's a buffer block or not.
49 //
50 // This name can be an empty string in which case get_fallback_name(id) can be
51 // used which obtains a suitable fallback identifier for an ID.
52 std::string name;
53 };
54
55 struct ShaderResources
56 {
57 SmallVector<Resource> uniform_buffers;
58 SmallVector<Resource> storage_buffers;
59 SmallVector<Resource> stage_inputs;
60 SmallVector<Resource> stage_outputs;
61 SmallVector<Resource> subpass_inputs;
62 SmallVector<Resource> storage_images;
63 SmallVector<Resource> sampled_images;
64 SmallVector<Resource> atomic_counters;
65 SmallVector<Resource> acceleration_structures;
66
67 // There can only be one push constant block,
68 // but keep the vector in case this restriction is lifted in the future.
69 SmallVector<Resource> push_constant_buffers;
70
71 // For Vulkan GLSL and HLSL source,
72 // these correspond to separate texture2D and samplers respectively.
73 SmallVector<Resource> separate_images;
74 SmallVector<Resource> separate_samplers;
75 };
76
77 struct CombinedImageSampler
78 {
79 // The ID of the sampler2D variable.
80 VariableID combined_id;
81 // The ID of the texture2D variable.
82 VariableID image_id;
83 // The ID of the sampler variable.
84 VariableID sampler_id;
85 };
86
87 struct SpecializationConstant
88 {
89 // The ID of the specialization constant.
90 ConstantID id;
91 // The constant ID of the constant, used in Vulkan during pipeline creation.
92 uint32_t constant_id;
93 };
94
95 struct BufferRange
96 {
97 unsigned index;
98 size_t offset;
99 size_t range;
100 };
101
102 enum BufferPackingStandard
103 {
104 BufferPackingStd140,
105 BufferPackingStd430,
106 BufferPackingStd140EnhancedLayout,
107 BufferPackingStd430EnhancedLayout,
108 BufferPackingHLSLCbuffer,
109 BufferPackingHLSLCbufferPackOffset,
110 BufferPackingScalar,
111 BufferPackingScalarEnhancedLayout
112 };
113
114 struct EntryPoint
115 {
116 std::string name;
117 spv::ExecutionModel execution_model;
118 };
119
120 class Compiler
121 {
122 public:
123 friend class CFG;
124 friend class DominatorBuilder;
125
126 // The constructor takes a buffer of SPIR-V words and parses it.
127 // It will create its own parser, parse the SPIR-V and move the parsed IR
128 // as if you had called the constructors taking ParsedIR directly.
129 explicit Compiler(std::vector<uint32_t> ir);
130 Compiler(const uint32_t *ir, size_t word_count);
131
132 // This is more modular. We can also consume a ParsedIR structure directly, either as a move, or copy.
133 // With copy, we can reuse the same parsed IR for multiple Compiler instances.
134 explicit Compiler(const ParsedIR &ir);
135 explicit Compiler(ParsedIR &&ir);
136
137 virtual ~Compiler() = default;
138
139 // After parsing, API users can modify the SPIR-V via reflection and call this
140 // to disassemble the SPIR-V into the desired langauage.
141 // Sub-classes actually implement this.
142 virtual std::string compile();
143
144 // Gets the identifier (OpName) of an ID. If not defined, an empty string will be returned.
145 const std::string &get_name(ID id) const;
146
147 // Applies a decoration to an ID. Effectively injects OpDecorate.
148 void set_decoration(ID id, spv::Decoration decoration, uint32_t argument = 0);
149 void set_decoration_string(ID id, spv::Decoration decoration, const std::string &argument);
150
151 // Overrides the identifier OpName of an ID.
152 // Identifiers beginning with underscores or identifiers which contain double underscores
153 // are reserved by the implementation.
154 void set_name(ID id, const std::string &name);
155
156 // Gets a bitmask for the decorations which are applied to ID.
157 // I.e. (1ull << spv::DecorationFoo) | (1ull << spv::DecorationBar)
158 const Bitset &get_decoration_bitset(ID id) const;
159
160 // Returns whether the decoration has been applied to the ID.
161 bool has_decoration(ID id, spv::Decoration decoration) const;
162
163 // Gets the value for decorations which take arguments.
164 // If the decoration is a boolean (i.e. spv::DecorationNonWritable),
165 // 1 will be returned.
166 // If decoration doesn't exist or decoration is not recognized,
167 // 0 will be returned.
168 uint32_t get_decoration(ID id, spv::Decoration decoration) const;
169 const std::string &get_decoration_string(ID id, spv::Decoration decoration) const;
170
171 // Removes the decoration for an ID.
172 void unset_decoration(ID id, spv::Decoration decoration);
173
174 // Gets the SPIR-V type associated with ID.
175 // Mostly used with Resource::type_id and Resource::base_type_id to parse the underlying type of a resource.
176 const SPIRType &get_type(TypeID id) const;
177
178 // Gets the SPIR-V type of a variable.
179 const SPIRType &get_type_from_variable(VariableID id) const;
180
181 // Gets the underlying storage class for an OpVariable.
182 spv::StorageClass get_storage_class(VariableID id) const;
183
184 // If get_name() is an empty string, get the fallback name which will be used
185 // instead in the disassembled source.
186 virtual const std::string get_fallback_name(ID id) const;
187
188 // If get_name() of a Block struct is an empty string, get the fallback name.
189 // This needs to be per-variable as multiple variables can use the same block type.
190 virtual const std::string get_block_fallback_name(VariableID id) const;
191
192 // Given an OpTypeStruct in ID, obtain the identifier for member number "index".
193 // This may be an empty string.
194 const std::string &get_member_name(TypeID id, uint32_t index) const;
195
196 // Given an OpTypeStruct in ID, obtain the OpMemberDecoration for member number "index".
197 uint32_t get_member_decoration(TypeID id, uint32_t index, spv::Decoration decoration) const;
198 const std::string &get_member_decoration_string(TypeID id, uint32_t index, spv::Decoration decoration) const;
199
200 // Sets the member identifier for OpTypeStruct ID, member number "index".
201 void set_member_name(TypeID id, uint32_t index, const std::string &name);
202
203 // Returns the qualified member identifier for OpTypeStruct ID, member number "index",
204 // or an empty string if no qualified alias exists
205 const std::string &get_member_qualified_name(TypeID type_id, uint32_t index) const;
206
207 // Gets the decoration mask for a member of a struct, similar to get_decoration_mask.
208 const Bitset &get_member_decoration_bitset(TypeID id, uint32_t index) const;
209
210 // Returns whether the decoration has been applied to a member of a struct.
211 bool has_member_decoration(TypeID id, uint32_t index, spv::Decoration decoration) const;
212
213 // Similar to set_decoration, but for struct members.
214 void set_member_decoration(TypeID id, uint32_t index, spv::Decoration decoration, uint32_t argument = 0);
215 void set_member_decoration_string(TypeID id, uint32_t index, spv::Decoration decoration,
216 const std::string &argument);
217
218 // Unsets a member decoration, similar to unset_decoration.
219 void unset_member_decoration(TypeID id, uint32_t index, spv::Decoration decoration);
220
221 // Gets the fallback name for a member, similar to get_fallback_name.
222 virtual const std::string get_fallback_member_name(uint32_t index) const
223 {
224 return join("_", index);
225 }
226
227 // Returns a vector of which members of a struct are potentially in use by a
228 // SPIR-V shader. The granularity of this analysis is per-member of a struct.
229 // This can be used for Buffer (UBO), BufferBlock/StorageBuffer (SSBO) and PushConstant blocks.
230 // ID is the Resource::id obtained from get_shader_resources().
231 SmallVector<BufferRange> get_active_buffer_ranges(VariableID id) const;
232
233 // Returns the effective size of a buffer block.
234 size_t get_declared_struct_size(const SPIRType &struct_type) const;
235
236 // Returns the effective size of a buffer block, with a given array size
237 // for a runtime array.
238 // SSBOs are typically declared as runtime arrays. get_declared_struct_size() will return 0 for the size.
239 // This is not very helpful for applications which might need to know the array stride of its last member.
240 // This can be done through the API, but it is not very intuitive how to accomplish this, so here we provide a helper function
241 // to query the size of the buffer, assuming that the last member has a certain size.
242 // If the buffer does not contain a runtime array, array_size is ignored, and the function will behave as
243 // get_declared_struct_size().
244 // To get the array stride of the last member, something like:
245 // get_declared_struct_size_runtime_array(type, 1) - get_declared_struct_size_runtime_array(type, 0) will work.
246 size_t get_declared_struct_size_runtime_array(const SPIRType &struct_type, size_t array_size) const;
247
248 // Returns the effective size of a buffer block struct member.
249 size_t get_declared_struct_member_size(const SPIRType &struct_type, uint32_t index) const;
250
251 // Returns a set of all global variables which are statically accessed
252 // by the control flow graph from the current entry point.
253 // Only variables which change the interface for a shader are returned, that is,
254 // variables with storage class of Input, Output, Uniform, UniformConstant, PushConstant and AtomicCounter
255 // storage classes are returned.
256 //
257 // To use the returned set as the filter for which variables are used during compilation,
258 // this set can be moved to set_enabled_interface_variables().
259 std::unordered_set<VariableID> get_active_interface_variables() const;
260
261 // Sets the interface variables which are used during compilation.
262 // By default, all variables are used.
263 // Once set, compile() will only consider the set in active_variables.
264 void set_enabled_interface_variables(std::unordered_set<VariableID> active_variables);
265
266 // Query shader resources, use ids with reflection interface to modify or query binding points, etc.
267 ShaderResources get_shader_resources() const;
268
269 // Query shader resources, but only return the variables which are part of active_variables.
270 // E.g.: get_shader_resources(get_active_variables()) to only return the variables which are statically
271 // accessed.
272 ShaderResources get_shader_resources(const std::unordered_set<VariableID> &active_variables) const;
273
274 // Remapped variables are considered built-in variables and a backend will
275 // not emit a declaration for this variable.
276 // This is mostly useful for making use of builtins which are dependent on extensions.
277 void set_remapped_variable_state(VariableID id, bool remap_enable);
278 bool get_remapped_variable_state(VariableID id) const;
279
280 // For subpassInput variables which are remapped to plain variables,
281 // the number of components in the remapped
282 // variable must be specified as the backing type of subpass inputs are opaque.
283 void set_subpass_input_remapped_components(VariableID id, uint32_t components);
284 uint32_t get_subpass_input_remapped_components(VariableID id) const;
285
286 // All operations work on the current entry point.
287 // Entry points can be swapped out with set_entry_point().
288 // Entry points should be set right after the constructor completes as some reflection functions traverse the graph from the entry point.
289 // Resource reflection also depends on the entry point.
290 // By default, the current entry point is set to the first OpEntryPoint which appears in the SPIR-V module.
291
292 // Some shader languages restrict the names that can be given to entry points, and the
293 // corresponding backend will automatically rename an entry point name, during the call
294 // to compile() if it is illegal. For example, the common entry point name main() is
295 // illegal in MSL, and is renamed to an alternate name by the MSL backend.
296 // Given the original entry point name contained in the SPIR-V, this function returns
297 // the name, as updated by the backend during the call to compile(). If the name is not
298 // illegal, and has not been renamed, or if this function is called before compile(),
299 // this function will simply return the same name.
300
301 // New variants of entry point query and reflection.
302 // Names for entry points in the SPIR-V module may alias if they belong to different execution models.
303 // To disambiguate, we must pass along with the entry point names the execution model.
304 SmallVector<EntryPoint> get_entry_points_and_stages() const;
305 void set_entry_point(const std::string &entry, spv::ExecutionModel execution_model);
306
307 // Renames an entry point from old_name to new_name.
308 // If old_name is currently selected as the current entry point, it will continue to be the current entry point,
309 // albeit with a new name.
310 // get_entry_points() is essentially invalidated at this point.
311 void rename_entry_point(const std::string &old_name, const std::string &new_name,
312 spv::ExecutionModel execution_model);
313 const SPIREntryPoint &get_entry_point(const std::string &name, spv::ExecutionModel execution_model) const;
314 SPIREntryPoint &get_entry_point(const std::string &name, spv::ExecutionModel execution_model);
315 const std::string &get_cleansed_entry_point_name(const std::string &name,
316 spv::ExecutionModel execution_model) const;
317
318 // Traverses all reachable opcodes and sets active_builtins to a bitmask of all builtin variables which are accessed in the shader.
319 void update_active_builtins();
320 bool has_active_builtin(spv::BuiltIn builtin, spv::StorageClass storage);
321
322 // Query and modify OpExecutionMode.
323 const Bitset &get_execution_mode_bitset() const;
324
325 void unset_execution_mode(spv::ExecutionMode mode);
326 void set_execution_mode(spv::ExecutionMode mode, uint32_t arg0 = 0, uint32_t arg1 = 0, uint32_t arg2 = 0);
327
328 // Gets argument for an execution mode (LocalSize, Invocations, OutputVertices).
329 // For LocalSize, the index argument is used to select the dimension (X = 0, Y = 1, Z = 2).
330 // For execution modes which do not have arguments, 0 is returned.
331 uint32_t get_execution_mode_argument(spv::ExecutionMode mode, uint32_t index = 0) const;
332 spv::ExecutionModel get_execution_model() const;
333
334 bool is_tessellation_shader() const;
335
336 // In SPIR-V, the compute work group size can be represented by a constant vector, in which case
337 // the LocalSize execution mode is ignored.
338 //
339 // This constant vector can be a constant vector, specialization constant vector, or partly specialized constant vector.
340 // To modify and query work group dimensions which are specialization constants, SPIRConstant values must be modified
341 // directly via get_constant() rather than using LocalSize directly. This function will return which constants should be modified.
342 //
343 // To modify dimensions which are *not* specialization constants, set_execution_mode should be used directly.
344 // Arguments to set_execution_mode which are specialization constants are effectively ignored during compilation.
345 // NOTE: This is somewhat different from how SPIR-V works. In SPIR-V, the constant vector will completely replace LocalSize,
346 // while in this interface, LocalSize is only ignored for specialization constants.
347 //
348 // The specialization constant will be written to x, y and z arguments.
349 // If the component is not a specialization constant, a zeroed out struct will be written.
350 // The return value is the constant ID of the builtin WorkGroupSize, but this is not expected to be useful
351 // for most use cases.
352 uint32_t get_work_group_size_specialization_constants(SpecializationConstant &x, SpecializationConstant &y,
353 SpecializationConstant &z) const;
354
355 // Analyzes all OpImageFetch (texelFetch) opcodes and checks if there are instances where
356 // said instruction is used without a combined image sampler.
357 // GLSL targets do not support the use of texelFetch without a sampler.
358 // To workaround this, we must inject a dummy sampler which can be used to form a sampler2D at the call-site of
359 // texelFetch as necessary.
360 //
361 // This must be called before build_combined_image_samplers().
362 // build_combined_image_samplers() may refer to the ID returned by this method if the returned ID is non-zero.
363 // The return value will be the ID of a sampler object if a dummy sampler is necessary, or 0 if no sampler object
364 // is required.
365 //
366 // If the returned ID is non-zero, it can be decorated with set/bindings as desired before calling compile().
367 // Calling this function also invalidates get_active_interface_variables(), so this should be called
368 // before that function.
369 VariableID build_dummy_sampler_for_combined_images();
370
371 // Analyzes all separate image and samplers used from the currently selected entry point,
372 // and re-routes them all to a combined image sampler instead.
373 // This is required to "support" separate image samplers in targets which do not natively support
374 // this feature, like GLSL/ESSL.
375 //
376 // This must be called before compile() if such remapping is desired.
377 // This call will add new sampled images to the SPIR-V,
378 // so it will appear in reflection if get_shader_resources() is called after build_combined_image_samplers.
379 //
380 // If any image/sampler remapping was found, no separate image/samplers will appear in the decompiled output,
381 // but will still appear in reflection.
382 //
383 // The resulting samplers will be void of any decorations like name, descriptor sets and binding points,
384 // so this can be added before compile() if desired.
385 //
386 // Combined image samplers originating from this set are always considered active variables.
387 // Arrays of separate samplers are not supported, but arrays of separate images are supported.
388 // Array of images + sampler -> Array of combined image samplers.
389 void build_combined_image_samplers();
390
391 // Gets a remapping for the combined image samplers.
392 const SmallVector<CombinedImageSampler> &get_combined_image_samplers() const
393 {
394 return combined_image_samplers;
395 }
396
397 // Set a new variable type remap callback.
398 // The type remapping is designed to allow global interface variable to assume more special types.
399 // A typical example here is to remap sampler2D into samplerExternalOES, which currently isn't supported
400 // directly by SPIR-V.
401 //
402 // In compile() while emitting code,
403 // for every variable that is declared, including function parameters, the callback will be called
404 // and the API user has a chance to change the textual representation of the type used to declare the variable.
405 // The API user can detect special patterns in names to guide the remapping.
406 void set_variable_type_remap_callback(VariableTypeRemapCallback cb)
407 {
408 variable_remap_callback = std::move(cb);
409 }
410
411 // API for querying which specialization constants exist.
412 // To modify a specialization constant before compile(), use get_constant(constant.id),
413 // then update constants directly in the SPIRConstant data structure.
414 // For composite types, the subconstants can be iterated over and modified.
415 // constant_type is the SPIRType for the specialization constant,
416 // which can be queried to determine which fields in the unions should be poked at.
417 SmallVector<SpecializationConstant> get_specialization_constants() const;
418 SPIRConstant &get_constant(ConstantID id);
419 const SPIRConstant &get_constant(ConstantID id) const;
420
421 uint32_t get_current_id_bound() const
422 {
423 return uint32_t(ir.ids.size());
424 }
425
426 // API for querying buffer objects.
427 // The type passed in here should be the base type of a resource, i.e.
428 // get_type(resource.base_type_id)
429 // as decorations are set in the basic Block type.
430 // The type passed in here must have these decorations set, or an exception is raised.
431 // Only UBOs and SSBOs or sub-structs which are part of these buffer types will have these decorations set.
432 uint32_t type_struct_member_offset(const SPIRType &type, uint32_t index) const;
433 uint32_t type_struct_member_array_stride(const SPIRType &type, uint32_t index) const;
434 uint32_t type_struct_member_matrix_stride(const SPIRType &type, uint32_t index) const;
435
436 // Gets the offset in SPIR-V words (uint32_t) for a decoration which was originally declared in the SPIR-V binary.
437 // The offset will point to one or more uint32_t literals which can be modified in-place before using the SPIR-V binary.
438 // Note that adding or removing decorations using the reflection API will not change the behavior of this function.
439 // If the decoration was declared, sets the word_offset to an offset into the provided SPIR-V binary buffer and returns true,
440 // otherwise, returns false.
441 // If the decoration does not have any value attached to it (e.g. DecorationRelaxedPrecision), this function will also return false.
442 bool get_binary_offset_for_decoration(VariableID id, spv::Decoration decoration, uint32_t &word_offset) const;
443
444 // HLSL counter buffer reflection interface.
445 // Append/Consume/Increment/Decrement in HLSL is implemented as two "neighbor" buffer objects where
446 // one buffer implements the storage, and a single buffer containing just a lone "int" implements the counter.
447 // To SPIR-V these will be exposed as two separate buffers, but glslang HLSL frontend emits a special indentifier
448 // which lets us link the two buffers together.
449
450 // Queries if a variable ID is a counter buffer which "belongs" to a regular buffer object.
451
452 // If SPV_GOOGLE_hlsl_functionality1 is used, this can be used even with a stripped SPIR-V module.
453 // Otherwise, this query is purely based on OpName identifiers as found in the SPIR-V module, and will
454 // only return true if OpSource was reported HLSL.
455 // To rely on this functionality, ensure that the SPIR-V module is not stripped.
456
457 bool buffer_is_hlsl_counter_buffer(VariableID id) const;
458
459 // Queries if a buffer object has a neighbor "counter" buffer.
460 // If so, the ID of that counter buffer will be returned in counter_id.
461 // If SPV_GOOGLE_hlsl_functionality1 is used, this can be used even with a stripped SPIR-V module.
462 // Otherwise, this query is purely based on OpName identifiers as found in the SPIR-V module, and will
463 // only return true if OpSource was reported HLSL.
464 // To rely on this functionality, ensure that the SPIR-V module is not stripped.
465 bool buffer_get_hlsl_counter_buffer(VariableID id, uint32_t &counter_id) const;
466
467 // Gets the list of all SPIR-V Capabilities which were declared in the SPIR-V module.
468 const SmallVector<spv::Capability> &get_declared_capabilities() const;
469
470 // Gets the list of all SPIR-V extensions which were declared in the SPIR-V module.
471 const SmallVector<std::string> &get_declared_extensions() const;
472
473 // When declaring buffer blocks in GLSL, the name declared in the GLSL source
474 // might not be the same as the name declared in the SPIR-V module due to naming conflicts.
475 // In this case, SPIRV-Cross needs to find a fallback-name, and it might only
476 // be possible to know this name after compiling to GLSL.
477 // This is particularly important for HLSL input and UAVs which tends to reuse the same block type
478 // for multiple distinct blocks. For these cases it is not possible to modify the name of the type itself
479 // because it might be unique. Instead, you can use this interface to check after compilation which
480 // name was actually used if your input SPIR-V tends to have this problem.
481 // For other names like remapped names for variables, etc, it's generally enough to query the name of the variables
482 // after compiling, block names are an exception to this rule.
483 // ID is the name of a variable as returned by Resource::id, and must be a variable with a Block-like type.
484 //
485 // This also applies to HLSL cbuffers.
486 std::string get_remapped_declared_block_name(VariableID id) const;
487
488 // For buffer block variables, get the decorations for that variable.
489 // Sometimes, decorations for buffer blocks are found in member decorations instead
490 // of direct decorations on the variable itself.
491 // The most common use here is to check if a buffer is readonly or writeonly.
492 Bitset get_buffer_block_flags(VariableID id) const;
493
494 protected:
495 const uint32_t *stream(const Instruction &instr) const
496 {
497 // If we're not going to use any arguments, just return nullptr.
498 // We want to avoid case where we return an out of range pointer
499 // that trips debug assertions on some platforms.
500 if (!instr.length)
501 return nullptr;
502
503 if (instr.offset + instr.length > ir.spirv.size())
504 SPIRV_CROSS_THROW("Compiler::stream() out of range.");
505 return &ir.spirv[instr.offset];
506 }
507
508 ParsedIR ir;
509 // Marks variables which have global scope and variables which can alias with other variables
510 // (SSBO, image load store, etc)
511 SmallVector<uint32_t> global_variables;
512 SmallVector<uint32_t> aliased_variables;
513
514 SPIRFunction *current_function = nullptr;
515 SPIRBlock *current_block = nullptr;
516 uint32_t current_loop_level = 0;
517 std::unordered_set<VariableID> active_interface_variables;
518 bool check_active_interface_variables = false;
519
520 void add_loop_level();
521
522 void set_initializers(SPIRExpression &e)
523 {
524 e.emitted_loop_level = current_loop_level;
525 }
526
527 template <typename T>
528 void set_initializers(const T &)
529 {
530 }
531
532 // If our IDs are out of range here as part of opcodes, throw instead of
533 // undefined behavior.
534 template <typename T, typename... P>
535 T &set(uint32_t id, P &&... args)
536 {
537 ir.add_typed_id(static_cast<Types>(T::type), id);
538 auto &var = variant_set<T>(ir.ids[id], std::forward<P>(args)...);
539 var.self = id;
540 set_initializers(var);
541 return var;
542 }
543
544 template <typename T>
545 T &get(uint32_t id)
546 {
547 return variant_get<T>(ir.ids[id]);
548 }
549
550 template <typename T>
551 T *maybe_get(uint32_t id)
552 {
553 if (id >= ir.ids.size())
554 return nullptr;
555 else if (ir.ids[id].get_type() == static_cast<Types>(T::type))
556 return &get<T>(id);
557 else
558 return nullptr;
559 }
560
561 template <typename T>
562 const T &get(uint32_t id) const
563 {
564 return variant_get<T>(ir.ids[id]);
565 }
566
567 template <typename T>
568 const T *maybe_get(uint32_t id) const
569 {
570 if (id >= ir.ids.size())
571 return nullptr;
572 else if (ir.ids[id].get_type() == static_cast<Types>(T::type))
573 return &get<T>(id);
574 else
575 return nullptr;
576 }
577
578 // Gets the id of SPIR-V type underlying the given type_id, which might be a pointer.
579 uint32_t get_pointee_type_id(uint32_t type_id) const;
580
581 // Gets the SPIR-V type underlying the given type, which might be a pointer.
582 const SPIRType &get_pointee_type(const SPIRType &type) const;
583
584 // Gets the SPIR-V type underlying the given type_id, which might be a pointer.
585 const SPIRType &get_pointee_type(uint32_t type_id) const;
586
587 // Gets the ID of the SPIR-V type underlying a variable.
588 uint32_t get_variable_data_type_id(const SPIRVariable &var) const;
589
590 // Gets the SPIR-V type underlying a variable.
591 SPIRType &get_variable_data_type(const SPIRVariable &var);
592
593 // Gets the SPIR-V type underlying a variable.
594 const SPIRType &get_variable_data_type(const SPIRVariable &var) const;
595
596 // Gets the SPIR-V element type underlying an array variable.
597 SPIRType &get_variable_element_type(const SPIRVariable &var);
598
599 // Gets the SPIR-V element type underlying an array variable.
600 const SPIRType &get_variable_element_type(const SPIRVariable &var) const;
601
602 // Sets the qualified member identifier for OpTypeStruct ID, member number "index".
603 void set_member_qualified_name(uint32_t type_id, uint32_t index, const std::string &name);
604 void set_qualified_name(uint32_t id, const std::string &name);
605
606 // Returns if the given type refers to a sampled image.
607 bool is_sampled_image_type(const SPIRType &type);
608
609 const SPIREntryPoint &get_entry_point() const;
610 SPIREntryPoint &get_entry_point();
611 static bool is_tessellation_shader(spv::ExecutionModel model);
612
613 virtual std::string to_name(uint32_t id, bool allow_alias = true) const;
614 bool is_builtin_variable(const SPIRVariable &var) const;
615 bool is_builtin_type(const SPIRType &type) const;
616 bool is_hidden_variable(const SPIRVariable &var, bool include_builtins = false) const;
617 bool is_immutable(uint32_t id) const;
618 bool is_member_builtin(const SPIRType &type, uint32_t index, spv::BuiltIn *builtin) const;
619 bool is_scalar(const SPIRType &type) const;
620 bool is_vector(const SPIRType &type) const;
621 bool is_matrix(const SPIRType &type) const;
622 bool is_array(const SPIRType &type) const;
623 uint32_t expression_type_id(uint32_t id) const;
624 const SPIRType &expression_type(uint32_t id) const;
625 bool expression_is_lvalue(uint32_t id) const;
626 bool variable_storage_is_aliased(const SPIRVariable &var);
627 SPIRVariable *maybe_get_backing_variable(uint32_t chain);
628 spv::StorageClass get_expression_effective_storage_class(uint32_t ptr);
629
630 void register_read(uint32_t expr, uint32_t chain, bool forwarded);
631 void register_write(uint32_t chain);
632
633 inline bool is_continue(uint32_t next) const
634 {
635 return (ir.block_meta[next] & ParsedIR::BLOCK_META_CONTINUE_BIT) != 0;
636 }
637
638 inline bool is_single_block_loop(uint32_t next) const
639 {
640 auto &block = get<SPIRBlock>(next);
641 return block.merge == SPIRBlock::MergeLoop && block.continue_block == ID(next);
642 }
643
644 inline bool is_break(uint32_t next) const
645 {
646 return (ir.block_meta[next] &
647 (ParsedIR::BLOCK_META_LOOP_MERGE_BIT | ParsedIR::BLOCK_META_MULTISELECT_MERGE_BIT)) != 0;
648 }
649
650 inline bool is_loop_break(uint32_t next) const
651 {
652 return (ir.block_meta[next] & ParsedIR::BLOCK_META_LOOP_MERGE_BIT) != 0;
653 }
654
655 inline bool is_conditional(uint32_t next) const
656 {
657 return (ir.block_meta[next] &
658 (ParsedIR::BLOCK_META_SELECTION_MERGE_BIT | ParsedIR::BLOCK_META_MULTISELECT_MERGE_BIT)) != 0;
659 }
660
661 // Dependency tracking for temporaries read from variables.
662 void flush_dependees(SPIRVariable &var);
663 void flush_all_active_variables();
664 void flush_control_dependent_expressions(uint32_t block);
665 void flush_all_atomic_capable_variables();
666 void flush_all_aliased_variables();
667 void register_global_read_dependencies(const SPIRBlock &func, uint32_t id);
668 void register_global_read_dependencies(const SPIRFunction &func, uint32_t id);
669 std::unordered_set<uint32_t> invalid_expressions;
670
671 void update_name_cache(std::unordered_set<std::string> &cache, std::string &name);
672
673 // A variant which takes two sets of names. The secondary is only used to verify there are no collisions,
674 // but the set is not updated when we have found a new name.
675 // Used primarily when adding block interface names.
676 void update_name_cache(std::unordered_set<std::string> &cache_primary,
677 const std::unordered_set<std::string> &cache_secondary, std::string &name);
678
679 bool function_is_pure(const SPIRFunction &func);
680 bool block_is_pure(const SPIRBlock &block);
681
682 bool execution_is_branchless(const SPIRBlock &from, const SPIRBlock &to) const;
683 bool execution_is_direct_branch(const SPIRBlock &from, const SPIRBlock &to) const;
684 bool execution_is_noop(const SPIRBlock &from, const SPIRBlock &to) const;
685 SPIRBlock::ContinueBlockType continue_block_type(const SPIRBlock &continue_block) const;
686
687 void force_recompile();
688 void clear_force_recompile();
689 bool is_forcing_recompilation() const;
690 bool is_force_recompile = false;
691
692 bool block_is_loop_candidate(const SPIRBlock &block, SPIRBlock::Method method) const;
693
694 bool types_are_logically_equivalent(const SPIRType &a, const SPIRType &b) const;
695 void inherit_expression_dependencies(uint32_t dst, uint32_t source);
696 void add_implied_read_expression(SPIRExpression &e, uint32_t source);
697 void add_implied_read_expression(SPIRAccessChain &e, uint32_t source);
698
699 // For proper multiple entry point support, allow querying if an Input or Output
700 // variable is part of that entry points interface.
701 bool interface_variable_exists_in_entry_point(uint32_t id) const;
702
703 SmallVector<CombinedImageSampler> combined_image_samplers;
704
705 void remap_variable_type_name(const SPIRType &type, const std::string &var_name, std::string &type_name) const
706 {
707 if (variable_remap_callback)
708 variable_remap_callback(type, var_name, type_name);
709 }
710
711 void set_ir(const ParsedIR &parsed);
712 void set_ir(ParsedIR &&parsed);
713 void parse_fixup();
714
715 // Used internally to implement various traversals for queries.
716 struct OpcodeHandler
717 {
718 virtual ~OpcodeHandler() = default;
719
720 // Return true if traversal should continue.
721 // If false, traversal will end immediately.
722 virtual bool handle(spv::Op opcode, const uint32_t *args, uint32_t length) = 0;
723
724 virtual bool follow_function_call(const SPIRFunction &)
725 {
726 return true;
727 }
728
729 virtual void set_current_block(const SPIRBlock &)
730 {
731 }
732
733 // Called after returning from a function or when entering a block,
734 // can be called multiple times per block,
735 // while set_current_block is only called on block entry.
736 virtual void rearm_current_block(const SPIRBlock &)
737 {
738 }
739
740 virtual bool begin_function_scope(const uint32_t *, uint32_t)
741 {
742 return true;
743 }
744
745 virtual bool end_function_scope(const uint32_t *, uint32_t)
746 {
747 return true;
748 }
749 };
750
751 struct BufferAccessHandler : OpcodeHandler
752 {
753 BufferAccessHandler(const Compiler &compiler_, SmallVector<BufferRange> &ranges_, uint32_t id_)
754 : compiler(compiler_)
755 , ranges(ranges_)
756 , id(id_)
757 {
758 }
759
760 bool handle(spv::Op opcode, const uint32_t *args, uint32_t length) override;
761
762 const Compiler &compiler;
763 SmallVector<BufferRange> &ranges;
764 uint32_t id;
765
766 std::unordered_set<uint32_t> seen;
767 };
768
769 struct InterfaceVariableAccessHandler : OpcodeHandler
770 {
771 InterfaceVariableAccessHandler(const Compiler &compiler_, std::unordered_set<VariableID> &variables_)
772 : compiler(compiler_)
773 , variables(variables_)
774 {
775 }
776
777 bool handle(spv::Op opcode, const uint32_t *args, uint32_t length) override;
778
779 const Compiler &compiler;
780 std::unordered_set<VariableID> &variables;
781 };
782
783 struct CombinedImageSamplerHandler : OpcodeHandler
784 {
785 CombinedImageSamplerHandler(Compiler &compiler_)
786 : compiler(compiler_)
787 {
788 }
789 bool handle(spv::Op opcode, const uint32_t *args, uint32_t length) override;
790 bool begin_function_scope(const uint32_t *args, uint32_t length) override;
791 bool end_function_scope(const uint32_t *args, uint32_t length) override;
792
793 Compiler &compiler;
794
795 // Each function in the call stack needs its own remapping for parameters so we can deduce which global variable each texture/sampler the parameter is statically bound to.
796 std::stack<std::unordered_map<uint32_t, uint32_t>> parameter_remapping;
797 std::stack<SPIRFunction *> functions;
798
799 uint32_t remap_parameter(uint32_t id);
800 void push_remap_parameters(const SPIRFunction &func, const uint32_t *args, uint32_t length);
801 void pop_remap_parameters();
802 void register_combined_image_sampler(SPIRFunction &caller, VariableID combined_id, VariableID texture_id,
803 VariableID sampler_id, bool depth);
804 };
805
806 struct DummySamplerForCombinedImageHandler : OpcodeHandler
807 {
808 DummySamplerForCombinedImageHandler(Compiler &compiler_)
809 : compiler(compiler_)
810 {
811 }
812 bool handle(spv::Op opcode, const uint32_t *args, uint32_t length) override;
813
814 Compiler &compiler;
815 bool need_dummy_sampler = false;
816 };
817
818 struct ActiveBuiltinHandler : OpcodeHandler
819 {
820 ActiveBuiltinHandler(Compiler &compiler_)
821 : compiler(compiler_)
822 {
823 }
824
825 bool handle(spv::Op opcode, const uint32_t *args, uint32_t length) override;
826 Compiler &compiler;
827
828 void handle_builtin(const SPIRType &type, spv::BuiltIn builtin, const Bitset &decoration_flags);
829 };
830
831 bool traverse_all_reachable_opcodes(const SPIRBlock &block, OpcodeHandler &handler) const;
832 bool traverse_all_reachable_opcodes(const SPIRFunction &block, OpcodeHandler &handler) const;
833 // This must be an ordered data structure so we always pick the same type aliases.
834 SmallVector<uint32_t> global_struct_cache;
835
836 ShaderResources get_shader_resources(const std::unordered_set<VariableID> *active_variables) const;
837
838 VariableTypeRemapCallback variable_remap_callback;
839
840 bool get_common_basic_type(const SPIRType &type, SPIRType::BaseType &base_type);
841
842 std::unordered_set<uint32_t> forced_temporaries;
843 std::unordered_set<uint32_t> forwarded_temporaries;
844 std::unordered_set<uint32_t> suppressed_usage_tracking;
845 std::unordered_set<uint32_t> hoisted_temporaries;
846 std::unordered_set<uint32_t> forced_invariant_temporaries;
847
848 Bitset active_input_builtins;
849 Bitset active_output_builtins;
850 uint32_t clip_distance_count = 0;
851 uint32_t cull_distance_count = 0;
852 bool position_invariant = false;
853
854 void analyze_parameter_preservation(
855 SPIRFunction &entry, const CFG &cfg,
856 const std::unordered_map<uint32_t, std::unordered_set<uint32_t>> &variable_to_blocks,
857 const std::unordered_map<uint32_t, std::unordered_set<uint32_t>> &complete_write_blocks);
858
859 // If a variable ID or parameter ID is found in this set, a sampler is actually a shadow/comparison sampler.
860 // SPIR-V does not support this distinction, so we must keep track of this information outside the type system.
861 // There might be unrelated IDs found in this set which do not correspond to actual variables.
862 // This set should only be queried for the existence of samplers which are already known to be variables or parameter IDs.
863 // Similar is implemented for images, as well as if subpass inputs are needed.
864 std::unordered_set<uint32_t> comparison_ids;
865 bool need_subpass_input = false;
866
867 // In certain backends, we will need to use a dummy sampler to be able to emit code.
868 // GLSL does not support texelFetch on texture2D objects, but SPIR-V does,
869 // so we need to workaround by having the application inject a dummy sampler.
870 uint32_t dummy_sampler_id = 0;
871
872 void analyze_image_and_sampler_usage();
873
874 struct CombinedImageSamplerDrefHandler : OpcodeHandler
875 {
876 CombinedImageSamplerDrefHandler(Compiler &compiler_)
877 : compiler(compiler_)
878 {
879 }
880 bool handle(spv::Op opcode, const uint32_t *args, uint32_t length) override;
881
882 Compiler &compiler;
883 std::unordered_set<uint32_t> dref_combined_samplers;
884 };
885
886 struct CombinedImageSamplerUsageHandler : OpcodeHandler
887 {
888 CombinedImageSamplerUsageHandler(Compiler &compiler_,
889 const std::unordered_set<uint32_t> &dref_combined_samplers_)
890 : compiler(compiler_)
891 , dref_combined_samplers(dref_combined_samplers_)
892 {
893 }
894
895 bool begin_function_scope(const uint32_t *args, uint32_t length) override;
896 bool handle(spv::Op opcode, const uint32_t *args, uint32_t length) override;
897 Compiler &compiler;
898 const std::unordered_set<uint32_t> &dref_combined_samplers;
899
900 std::unordered_map<uint32_t, std::unordered_set<uint32_t>> dependency_hierarchy;
901 std::unordered_set<uint32_t> comparison_ids;
902
903 void add_hierarchy_to_comparison_ids(uint32_t ids);
904 bool need_subpass_input = false;
905 void add_dependency(uint32_t dst, uint32_t src);
906 };
907
908 void build_function_control_flow_graphs_and_analyze();
909 std::unordered_map<uint32_t, std::unique_ptr<CFG>> function_cfgs;
910 const CFG &get_cfg_for_current_function() const;
911 const CFG &get_cfg_for_function(uint32_t id) const;
912
913 struct CFGBuilder : OpcodeHandler
914 {
915 explicit CFGBuilder(Compiler &compiler_);
916
917 bool follow_function_call(const SPIRFunction &func) override;
918 bool handle(spv::Op op, const uint32_t *args, uint32_t length) override;
919 Compiler &compiler;
920 std::unordered_map<uint32_t, std::unique_ptr<CFG>> function_cfgs;
921 };
922
923 struct AnalyzeVariableScopeAccessHandler : OpcodeHandler
924 {
925 AnalyzeVariableScopeAccessHandler(Compiler &compiler_, SPIRFunction &entry_);
926
927 bool follow_function_call(const SPIRFunction &) override;
928 void set_current_block(const SPIRBlock &block) override;
929
930 void notify_variable_access(uint32_t id, uint32_t block);
931 bool id_is_phi_variable(uint32_t id) const;
932 bool id_is_potential_temporary(uint32_t id) const;
933 bool handle(spv::Op op, const uint32_t *args, uint32_t length) override;
934
935 Compiler &compiler;
936 SPIRFunction &entry;
937 std::unordered_map<uint32_t, std::unordered_set<uint32_t>> accessed_variables_to_block;
938 std::unordered_map<uint32_t, std::unordered_set<uint32_t>> accessed_temporaries_to_block;
939 std::unordered_map<uint32_t, uint32_t> result_id_to_type;
940 std::unordered_map<uint32_t, std::unordered_set<uint32_t>> complete_write_variables_to_block;
941 std::unordered_map<uint32_t, std::unordered_set<uint32_t>> partial_write_variables_to_block;
942 std::unordered_set<uint32_t> access_chain_expressions;
943 // Access chains used in multiple blocks mean hoisting all the variables used to construct the access chain as not all backends can use pointers.
944 std::unordered_map<uint32_t, std::unordered_set<uint32_t>> access_chain_children;
945 const SPIRBlock *current_block = nullptr;
946 };
947
948 struct StaticExpressionAccessHandler : OpcodeHandler
949 {
950 StaticExpressionAccessHandler(Compiler &compiler_, uint32_t variable_id_);
951 bool follow_function_call(const SPIRFunction &) override;
952 bool handle(spv::Op op, const uint32_t *args, uint32_t length) override;
953
954 Compiler &compiler;
955 uint32_t variable_id;
956 uint32_t static_expression = 0;
957 uint32_t write_count = 0;
958 };
959
960 struct PhysicalStorageBufferPointerHandler : OpcodeHandler
961 {
962 explicit PhysicalStorageBufferPointerHandler(Compiler &compiler_);
963 bool handle(spv::Op op, const uint32_t *args, uint32_t length) override;
964 Compiler &compiler;
965 std::unordered_set<uint32_t> types;
966 };
967 void analyze_non_block_pointer_types();
968 SmallVector<uint32_t> physical_storage_non_block_pointer_types;
969
970 void analyze_variable_scope(SPIRFunction &function, AnalyzeVariableScopeAccessHandler &handler);
971 void find_function_local_luts(SPIRFunction &function, const AnalyzeVariableScopeAccessHandler &handler,
972 bool single_function);
973 bool may_read_undefined_variable_in_block(const SPIRBlock &block, uint32_t var);
974
975 // Finds all resources that are written to from inside the critical section, if present.
976 // The critical section is delimited by OpBeginInvocationInterlockEXT and
977 // OpEndInvocationInterlockEXT instructions. In MSL and HLSL, any resources written
978 // while inside the critical section must be placed in a raster order group.
979 struct InterlockedResourceAccessHandler : OpcodeHandler
980 {
981 InterlockedResourceAccessHandler(Compiler &compiler_, uint32_t entry_point_id)
982 : compiler(compiler_)
983 {
984 call_stack.push_back(entry_point_id);
985 }
986
987 bool handle(spv::Op op, const uint32_t *args, uint32_t length) override;
988 bool begin_function_scope(const uint32_t *args, uint32_t length) override;
989 bool end_function_scope(const uint32_t *args, uint32_t length) override;
990
991 Compiler &compiler;
992 bool in_crit_sec = false;
993
994 uint32_t interlock_function_id = 0;
995 bool split_function_case = false;
996 bool control_flow_interlock = false;
997 bool use_critical_section = false;
998 bool call_stack_is_interlocked = false;
999 SmallVector<uint32_t> call_stack;
1000
1001 void access_potential_resource(uint32_t id);
1002 };
1003
1004 struct InterlockedResourceAccessPrepassHandler : OpcodeHandler
1005 {
1006 InterlockedResourceAccessPrepassHandler(Compiler &compiler_, uint32_t entry_point_id)
1007 : compiler(compiler_)
1008 {
1009 call_stack.push_back(entry_point_id);
1010 }
1011
1012 void rearm_current_block(const SPIRBlock &block) override;
1013 bool handle(spv::Op op, const uint32_t *args, uint32_t length) override;
1014 bool begin_function_scope(const uint32_t *args, uint32_t length) override;
1015 bool end_function_scope(const uint32_t *args, uint32_t length) override;
1016
1017 Compiler &compiler;
1018 uint32_t interlock_function_id = 0;
1019 uint32_t current_block_id = 0;
1020 bool split_function_case = false;
1021 bool control_flow_interlock = false;
1022 SmallVector<uint32_t> call_stack;
1023 };
1024
1025 void analyze_interlocked_resource_usage();
1026 // The set of all resources written while inside the critical section, if present.
1027 std::unordered_set<uint32_t> interlocked_resources;
1028 bool interlocked_is_complex = false;
1029
1030 void make_constant_null(uint32_t id, uint32_t type);
1031
1032 std::unordered_map<uint32_t, std::string> declared_block_names;
1033
1034 bool instruction_to_result_type(uint32_t &result_type, uint32_t &result_id, spv::Op op, const uint32_t *args,
1035 uint32_t length);
1036
1037 Bitset combined_decoration_for_member(const SPIRType &type, uint32_t index) const;
1038 static bool is_desktop_only_format(spv::ImageFormat format);
1039
1040 bool image_is_comparison(const SPIRType &type, uint32_t id) const;
1041
1042 void set_extended_decoration(uint32_t id, ExtendedDecorations decoration, uint32_t value = 0);
1043 uint32_t get_extended_decoration(uint32_t id, ExtendedDecorations decoration) const;
1044 bool has_extended_decoration(uint32_t id, ExtendedDecorations decoration) const;
1045 void unset_extended_decoration(uint32_t id, ExtendedDecorations decoration);
1046
1047 void set_extended_member_decoration(uint32_t type, uint32_t index, ExtendedDecorations decoration,
1048 uint32_t value = 0);
1049 uint32_t get_extended_member_decoration(uint32_t type, uint32_t index, ExtendedDecorations decoration) const;
1050 bool has_extended_member_decoration(uint32_t type, uint32_t index, ExtendedDecorations decoration) const;
1051 void unset_extended_member_decoration(uint32_t type, uint32_t index, ExtendedDecorations decoration);
1052
1053 bool type_is_array_of_pointers(const SPIRType &type) const;
1054 bool type_is_top_level_physical_pointer(const SPIRType &type) const;
1055 bool type_is_block_like(const SPIRType &type) const;
1056 bool type_is_opaque_value(const SPIRType &type) const;
1057
1058 bool reflection_ssbo_instance_name_is_significant() const;
1059 std::string get_remapped_declared_block_name(uint32_t id, bool fallback_prefer_instance_name) const;
1060
1061 bool flush_phi_required(BlockID from, BlockID to) const;
1062
1063 uint32_t evaluate_spec_constant_u32(const SPIRConstantOp &spec) const;
1064 uint32_t evaluate_constant_u32(uint32_t id) const;
1065
1066 bool is_vertex_like_shader() const;
1067
1068 private:
1069 // Used only to implement the old deprecated get_entry_point() interface.
1070 const SPIREntryPoint &get_first_entry_point(const std::string &name) const;
1071 SPIREntryPoint &get_first_entry_point(const std::string &name);
1072 };
1073 } // namespace SPIRV_CROSS_NAMESPACE
1074
1075 #endif