Add new SpirvToolsDisassemble API interface + Improve Doc on existing API interface (#2442)

BUILD.gn

@@ -246,6 +246,8 @@ template("glslang_sources_common") {
       ]
     }
 
+    include_dirs = [ "${target_gen_dir}/include" ]
+
     deps = [ ":glslang_build_info" ]
 
     if (invoker.enable_opt) {
@@ -253,10 +255,9 @@ template("glslang_sources_common") {
         "${spirv_tools_dir}:spvtools_opt",
         "${spirv_tools_dir}:spvtools_val",
       ]
+      include_dirs += [ "${spirv_tools_dir}/include" ]
     }
 
-    include_dirs = [ "${target_gen_dir}/include" ]
-
     configs -= _configs_to_remove
     configs += _configs_to_add
   }
@@ -302,7 +303,10 @@ executable("glslang_validator") {
   ]
   public_configs = [ ":glslang_hlsl" ]
 
-  include_dirs = [ "${target_gen_dir}/include" ]
+  include_dirs = [
+    "${target_gen_dir}/include",
+    "${spirv_tools_dir}/include",
+  ]
 
   configs -= _configs_to_remove
   configs += _configs_to_add
@@ -313,6 +317,8 @@ executable("spirv-remap") {
   defines = [ "ENABLE_OPT=1" ]
   deps = [ ":glslang_sources" ]
 
+  include_dirs += [ "${spirv_tools_dir}/include" ]
+
   configs -= _configs_to_remove
   configs += _configs_to_add
 }

SPIRV/SpvTools.cpp

@@ -44,7 +44,6 @@
 
 #include "SpvTools.h"
 #include "spirv-tools/optimizer.hpp"
-#include "spirv-tools/libspirv.h"
 
 namespace glslang {
 
@@ -114,11 +113,18 @@ void OptimizerMesssageConsumer(spv_message_level_t level, const char *source,
     out << std::endl;
 }
 
-// Use the SPIRV-Tools disassembler to print SPIR-V.
+// Use the SPIRV-Tools disassembler to print SPIR-V using a SPV_ENV_UNIVERSAL_1_3 environment.
 void SpirvToolsDisassemble(std::ostream& out, const std::vector<unsigned int>& spirv)
 {
+    SpirvToolsDisassemble(out, spirv, spv_target_env::SPV_ENV_UNIVERSAL_1_3);
+}
+
+// Use the SPIRV-Tools disassembler to print SPIR-V with a provided SPIR-V environment.
+void SpirvToolsDisassemble(std::ostream& out, const std::vector<unsigned int>& spirv,
+                           spv_target_env requested_context)
+{
     // disassemble
-    spv_context context = spvContextCreate(SPV_ENV_UNIVERSAL_1_3);
+    spv_context context = spvContextCreate(requested_context);
     spv_text text;
     spv_diagnostic diagnostic = nullptr;
     spvBinaryToText(context, spirv.data(), spirv.size(),

SPIRV/SpvTools.h

@@ -41,9 +41,10 @@
 #ifndef GLSLANG_SPV_TOOLS_H
 #define GLSLANG_SPV_TOOLS_H
 
-#ifdef ENABLE_OPT
+#if ENABLE_OPT
 #include <vector>
 #include <ostream>
+#include "spirv-tools/libspirv.h"
 #endif
 
 #include "glslang/MachineIndependent/localintermediate.h"
@@ -62,11 +63,15 @@ struct SpvOptions {
     bool validate;
 };
 
-#ifdef ENABLE_OPT
+#if ENABLE_OPT
 
-// Use the SPIRV-Tools disassembler to print SPIR-V.
+// Use the SPIRV-Tools disassembler to print SPIR-V using a SPV_ENV_UNIVERSAL_1_3 environment.
 void SpirvToolsDisassemble(std::ostream& out, const std::vector<unsigned int>& spirv);
 
+// Use the SPIRV-Tools disassembler to print SPIR-V with a provided SPIR-V environment.
+void SpirvToolsDisassemble(std::ostream& out, const std::vector<unsigned int>& spirv,
+                           spv_target_env requested_context);
+
 // Apply the SPIRV-Tools validator to generated SPIR-V.
 void SpirvToolsValidate(const glslang::TIntermediate& intermediate, std::vector<unsigned int>& spirv,
                         spv::SpvBuildLogger*, bool prelegalization);

StandAlone/CMakeLists.txt

@@ -41,7 +41,6 @@ target_include_directories(glslang-default-resource-limits
                            PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>
                            PUBLIC $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}>)
 
-
 set(SOURCES StandAlone.cpp DirStackFileIncluder.h)
 
 add_executable(glslangValidator ${SOURCES})
@@ -70,6 +69,12 @@ target_include_directories(glslangValidator PUBLIC
     $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/../External>
     $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}/External>)
 
+if(ENABLE_OPT)
+    target_include_directories(glslangValidator
+        PRIVATE ${spirv-tools_SOURCE_DIR}/include
+    )
+endif(ENABLE_OPT)
+
 if(ENABLE_SPVREMAPPER)
     set(REMAPPER_SOURCES spirv-remap.cpp)
     add_executable(spirv-remap ${REMAPPER_SOURCES})

gtests/CMakeLists.txt

@@ -83,6 +83,12 @@ if(BUILD_TESTING)
                                    ${gmock_SOURCE_DIR}/include
                                    ${gtest_SOURCE_DIR}/include)
 
+        if(ENABLE_OPT)
+            target_include_directories(glslangtests
+                PRIVATE ${spirv-tools_SOURCE_DIR}/include
+            )
+        endif(ENABLE_OPT)
+
         set(LIBRARIES
             glslang OSDependent OGLCompiler glslang
             SPIRV glslang-default-resource-limits)