Merge pull request #1379 from KhronosGroup/fix-1377

Document CLI options.
This commit is contained in:
Hans-Kristian Arntzen 2020-05-28 15:51:38 +02:00 committed by GitHub
commit 999a7b5256
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 175 additions and 74 deletions

247
main.cpp
View File

@ -613,84 +613,185 @@ static void print_version()
#endif
}
static void print_help_backend()
{
fprintf(stderr, "\nSelect backend:\n"
"\tBy default, OpenGL-style GLSL is the target, with #version and GLSL/ESSL information inherited from the SPIR-V module if present.\n"
"\t[--vulkan-semantics] or [-V]:\n\t\tEmit Vulkan GLSL instead of plain GLSL. Makes use of Vulkan-only features to match SPIR-V.\n"
"\t[--msl]:\n\t\tEmit Metal Shading Language (MSL).\n"
"\t[--hlsl]:\n\t\tEmit HLSL.\n"
"\t[--reflect]:\n\t\tEmit JSON reflection.\n"
"\t[--cpp]:\n\t\tDEPRECATED. Emits C++ code.\n"
);
}
static void print_help_glsl()
{
fprintf(stderr, "\nGLSL options:\n"
"\t[--es]:\n\t\tForce ESSL.\n"
"\t[--no-es]:\n\t\tForce desktop GLSL.\n"
"\t[--version <GLSL version>]:\n\t\tE.g. --version 450 will emit '#version 450' in shader.\n"
"\t\tCode generation will depend on the version used.\n"
"\t[--flatten-ubo]:\n\t\tEmit UBOs as plain uniform arrays which are suitable for use with glUniform4*v().\n"
"\t\tThis can be an optimization on GL implementations where this is faster or works around buggy driver implementations.\n"
"\t\tE.g.: uniform MyUBO { vec4 a; float b, c, d, e; }; will be emitted as uniform vec4 MyUBO[2];\n"
"\t\tCaveat: You cannot mix and match floating-point and integer in the same UBO with this option.\n"
"\t\tLegacy GLSL/ESSL (where this flattening makes sense) does not support bit-casting, which would have been the obvious workaround.\n"
"\t[--extension ext]:\n\t\tAdd #extension string of your choosing to GLSL output.\n"
"\t\tUseful if you use variable name remapping to something that requires an extension unknown to SPIRV-Cross.\n"
"\t[--remove-unused-variables]:\n\t\tDo not emit interface variables which are not statically accessed by the shader.\n"
"\t[--separate-shader-objects]:\n\t\tRedeclare gl_PerVertex blocks to be suitable for desktop GL separate shader objects.\n"
"\t[--glsl-emit-push-constant-as-ubo]:\n\t\tInstead of a plain uniform of struct for push constants, emit a UBO block instead.\n"
"\t[--glsl-emit-ubo-as-plain-uniforms]:\n\t\tInstead of emitting UBOs, emit them as plain uniform structs.\n"
"\t[--glsl-remap-ext-framebuffer-fetch input-attachment color-location]:\n\t\tRemaps an input attachment to use GL_EXT_shader_framebuffer_fetch.\n"
"\t\tgl_LastFragData[location] is read from. The attachment to read from must be declared as an output in the shader.\n"
"\t[--vulkan-glsl-disable-ext-samplerless-texture-functions]:\n\t\tDo not allow use of GL_EXT_samperless_texture_functions, even in Vulkan GLSL.\n"
"\t\tUse of texelFetch and similar might have to create dummy samplers to work around it.\n"
"\t[--combined-samplers-inherit-bindings]:\n\t\tInherit binding information from the textures when building combined image samplers from separate textures and samplers.\n"
"\t[--no-support-nonzero-baseinstance]:\n\t\tWhen using gl_InstanceIndex with desktop GL,\n"
"\t\tassume that base instance is always 0, and do not attempt to fix up gl_InstanceID to match Vulkan semantics.\n"
"\t[--pls-in format input-name]:\n\t\tRemaps a subpass input with name into a GL_EXT_pixel_local_storage input.\n"
"\t\tEntry in PLS block is ordered where first --pls-in marks the first entry. Can be called multiple times.\n"
"\t\tFormats allowed: r11f_g11f_b10f, r32f, rg16f, rg16, rgb10_a2, rgba8, rgba8i, rgba8ui, rg16i, rgb10_a2ui, rg16ui, r32ui.\n"
"\t\tRequires ESSL.\n"
"\t[--pls-out format output-name]:\n\t\tRemaps a color output with name into a GL_EXT_pixel_local_storage output.\n"
"\t\tEntry in PLS block is ordered where first --pls-output marks the first entry. Can be called multiple times.\n"
"\t\tFormats allowed: r11f_g11f_b10f, r32f, rg16f, rg16, rgb10_a2, rgba8, rgba8i, rgba8ui, rg16i, rgb10_a2ui, rg16ui, r32ui.\n"
"\t\tRequires ESSL.\n"
"\t[--remap source_name target_name components]:\n\t\tRemaps a variable to a different name with N components.\n"
"\t\tMain use case is to remap a subpass input to gl_LastFragDepthARM.\n"
"\t\tE.g.:\n"
"\t\tuniform subpassInput uDepth;\n"
"\t\t--remap uDepth gl_LastFragDepthARM 1 --extension GL_ARM_shader_framebuffer_fetch_depth_stencil\n"
"\t[--no-420pack-extension]:\n\t\tDo not make use of GL_ARB_shading_language_420pack in older GL targets to support layout(binding).\n"
"\t[--remap-variable-type <variable_name> <new_variable_type>]:\n\t\tRemaps a variable type based on name.\n"
"\t\tPrimary use case is supporting external samplers in ESSL for video rendering on Android where you could remap a texture to a YUV one.\n"
);
}
static void print_help_hlsl()
{
fprintf(stderr, "\nHLSL options:\n"
"\t[--shader-model]:\n\t\tEnables a specific shader model, e.g. --shader-model 50 for SM 5.0.\n"
"\t[--hlsl-enable-compat]:\n\t\tAllow point size and point coord to be used, even if they won't work as expected.\n"
"\t\tPointSize is ignored, and PointCoord returns (0.5, 0.5).\n"
"\t[--hlsl-support-nonzero-basevertex-baseinstance]:\n\t\tSupport base vertex and base instance by emitting a special cbuffer declared as:\n"
"\t\tcbuffer SPIRV_Cross_VertexInfo { int SPIRV_Cross_BaseVertex; int SPIRV_Cross_BaseInstance; };\n"
"\t[--hlsl-auto-binding (push, cbv, srv, uav, sampler, all)]\n"
"\t\tDo not emit any : register(#) bindings for specific resource types, and rely on HLSL compiler to assign something.\n"
"\t[--hlsl-force-storage-buffer-as-uav]:\n\t\tAlways emit SSBOs as UAVs, even when marked as read-only.\n"
"\t\tNormally, SSBOs marked with NonWritable will be emitted as SRVs.\n"
"\t[--hlsl-nonwritable-uav-texture-as-srv]:\n\t\tEmit NonWritable storage images as SRV textures instead of UAV.\n"
"\t\tUsing this option messes with the type system. SPIRV-Cross cannot guarantee that this will work.\n"
"\t\tOne major problem area with this feature is function arguments, where we won't know if we're seeing a UAV or SRV.\n"
"\t\tShader must ensure that read/write state is consistent at all call sites.\n"
"\t[--set-hlsl-vertex-input-semantic <location> <semantic>]:\n\t\tEmits a specific vertex input semantic for a given location.\n"
"\t\tOtherwise, TEXCOORD# is used as semantics, where # is location.\n"
);
}
static void print_help_msl()
{
fprintf(stderr, "\nMSL options:\n"
"\t[--msl-version <MMmmpp>]:\n\t\tUses a specific MSL version, e.g. --msl-version 20100 for MSL 2.1.\n"
"\t[--msl-capture-output]:\n\t\tWrites geometry varyings to a buffer instead of as stage-outputs.\n"
"\t[--msl-swizzle-texture-samples]:\n\t\tWorks around lack of support for VkImageView component swizzles.\n"
"\t\tThis has a massive impact on performance and bloat. Do not use this unless you are absolutely forced to.\n"
"\t\tTo use this feature, the API side must pass down swizzle buffers.\n"
"\t\tShould only be used by translation layers as a last resort.\n"
"\t\tRecent Metal versions do not require this workaround.\n"
"\t[--msl-ios]:\n\t\tTarget iOS Metal instead of macOS Metal.\n"
"\t[--msl-pad-fragment-output]:\n\t\tAlways emit color outputs as 4-component variables.\n"
"\t\tIn Metal, the fragment shader must emit at least as many components as the render target format.\n"
"\t[--msl-domain-lower-left]:\n\t\tUse a lower-left tessellation domain.\n"
"\t[--msl-argument-buffers]:\n\t\tEmit Indirect Argument buffers instead of plain bindings.\n"
"\t\tRequires MSL 2.0 to be enabled.\n"
"\t[--msl-texture-buffer-native]:\n\t\tEnable native support for texel buffers. Otherwise, it is emulated as a normal texture.\n"
"\t[--msl-framebuffer-fetch]:\n\t\tImplement subpass inputs with frame buffer fetch.\n"
"\t\tEmits [[color(N)]] inputs in fragment stage.\n"
"\t\tRequires iOS Metal.\n"
"\t[--msl-emulate-cube-array]:\n\t\tEmulate cube arrays with 2D array and manual math.\n"
"\t[--msl-discrete-descriptor-set <index>]:\n\t\tWhen using argument buffers, forces a specific descriptor set to be implemented without argument buffers.\n"
"\t\tUseful for implementing push descriptors in emulation layers.\n"
"\t\tCan be used multiple times for each descriptor set in question.\n"
"\t[--msl-device-argument-buffer <descriptor set index>]:\n\t\tUse device address space to hold indirect argument buffers instead of constant.\n"
"\t\tComes up when trying to support argument buffers which are larger than 64 KiB.\n"
"\t[--msl-multiview]:\n\t\tEnable SPV_KHR_multiview emulation.\n"
"\t[--msl-view-index-from-device-index]:\n\t\tTreat the view index as the device index instead.\n"
"\t\tFor multi-GPU rendering.\n"
"\t[--msl-dispatch-base]:\n\t\tAdd support for vkCmdDispatchBase() or similar APIs.\n"
"\t\tOffsets the workgroup ID based on a buffer.\n"
"\t[--msl-dynamic-buffer <set index> <binding>]:\n\t\tMarks a buffer as having dynamic offset.\n"
"\t\tThe offset is applied in the shader with pointer arithmetic.\n"
"\t\tUseful for argument buffers where it is non-trivial to apply dynamic offset otherwise.\n"
"\t[--msl-inline-uniform-block <set index> <binding>]:\n\t\tIn argument buffers, mark an UBO as being an inline uniform block which is embedded into the argument buffer itself.\n"
"\t[--msl-decoration-binding]:\n\t\tUse SPIR-V bindings directly as MSL bindings.\n"
"\t\tThis does not work in the general case as there is no descriptor set support, and combined image samplers are split up.\n"
"\t\tHowever, if the shader author knows of binding limitations, this option will avoid the need for reflection on Metal side.\n"
"\t[--msl-force-active-argument-buffer-resources]:\n\t\tAlways emit resources which are part of argument buffers.\n"
"\t\tThis makes sure that similar shaders with same resource declarations can share the argument buffer as declaring an argument buffer implies an ABI.\n"
"\t[--msl-force-native-arrays]:\n\t\tRather than implementing array types as a templated value type ala std::array<T>, use plain, native arrays.\n"
"\t\tThis will lead to worse code-gen, but can work around driver bugs on certain driver revisions of certain Intel-based Macbooks where template arrays break.\n"
"\t[--msl-disable-frag-depth-builtin]:\n\t\tDisables FragDepth output. Useful if pipeline does not enable depth, as pipeline creation might otherwise fail.\n"
"\t[--msl-disable-frag-stencil-ref-builtin]:\n\t\tDisable FragStencilRef output. Useful if pipeline does not enable stencil output, as pipeline creation might otherwise fail.\n"
"\t[--msl-enable-frag-output-mask <mask>]:\n\t\tOnly selectively enable fragment outputs. Useful if pipeline does not enable fragment output for certain locations, as pipeline creation might otherwise fail.\n"
"\t[--msl-no-clip-distance-user-varying]:\n\t\tDo not emit user varyings to emulate gl_ClipDistance in fragment shaders.\n"
);
}
static void print_help_common()
{
fprintf(stderr, "\nCommon options:\n"
"\t[--entry name]:\n\t\tUse a specific entry point. By default, the first entry point in the module is used.\n"
"\t[--stage <stage (vert, frag, geom, tesc, tese comp)>]:\n\t\tForces use of a certain shader stage.\n"
"\t\tCan disambiguate the entry point if more than one entry point exists with same name, but different stage.\n"
"\t[--emit-line-directives]:\n\t\tIf SPIR-V has OpLine directives, aim to emit those accurately in output code as well.\n"
"\t[--rename-entry-point <old> <new> <stage>]:\n\t\tRenames an entry point from what is declared in SPIR-V to code output.\n"
"\t\tMostly relevant for HLSL or MSL.\n"
"\t[--rename-interface-variable <in|out> <location> <new_variable_name>]:\n\t\tRename an interface variable based on location decoration.\n"
"\t[--force-zero-initialized-variables]:\n\t\tForces temporary variables to be initialized to zero.\n"
"\t\tCan be useful in environments where compilers do not allow potentially uninitialized variables.\n"
"\t\tThis usually comes up with Phi temporaries.\n"
"\t[--fixup-clipspace]:\n\t\tFixup Z clip-space at the end of a vertex shader. The behavior is backend-dependent.\n"
"\t\tGLSL: Rewrites [0, w] Z range (D3D/Metal/Vulkan) to GL-style [-w, w].\n"
"\t\tHLSL/MSL: Rewrites [-w, w] Z range (GL) to D3D/Metal/Vulkan-style [0, w].\n"
"\t[--flip-vert-y]:\n\t\tInverts gl_Position.y (or equivalent) at the end of a vertex shader. This is equivalent to using negative viewport height.\n"
);
}
static void print_help_obscure()
{
fprintf(stderr, "\nObscure options:\n"
"\tThese options are not meant to be used on a regular basis. They have some occasional uses in the test suite.\n"
"\t[--force-temporary]:\n\t\tAggressively emit temporary expressions instead of forwarding expressions. Very rarely used and under-tested.\n"
"\t[--revision]:\n\t\tPrints build timestamp and Git commit information (updated when cmake is configured).\n"
"\t[--iterations iter]:\n\t\tRecompiles the same shader over and over, benchmarking related.\n"
"\t[--disable-storage-image-qualifier-deduction]:\n\t\tIf storage images are received without any nonwritable or nonreadable information,\n"""
"\t\tdo not attempt to analyze usage, and always emit read/write state.\n"
"\t[--flatten-multidimensional-arrays]:\n\t\tDo not support multi-dimensional arrays and flatten them to one dimension.\n"
"\t[--cpp-interface-name <name>]:\n\t\tEmit a specific class name in C++ codegen.\n"
);
}
static void print_help()
{
print_version();
fprintf(stderr, "Usage: spirv-cross\n"
"\t[--output <output path>]\n"
fprintf(stderr, "Usage: spirv-cross <...>\n"
"\nBasic:\n"
"\t[SPIR-V file]\n"
"\t[--es]\n"
"\t[--no-es]\n"
"\t[--version <GLSL version>]\n"
"\t[--dump-resources]\n"
"\t[--help]\n"
"\t[--revision]\n"
"\t[--force-temporary]\n"
"\t[--vulkan-semantics] or [-V]\n"
"\t[--flatten-ubo]\n"
"\t[--fixup-clipspace]\n"
"\t[--flip-vert-y]\n"
"\t[--iterations iter]\n"
"\t[--cpp]\n"
"\t[--cpp-interface-name <name>]\n"
"\t[--disable-storage-image-qualifier-deduction]\n"
"\t[--force-zero-initialized-variables]\n"
"\t[--glsl-emit-push-constant-as-ubo]\n"
"\t[--glsl-emit-ubo-as-plain-uniforms]\n"
"\t[--glsl-remap-ext-framebuffer-fetch input-attachment color-location]\n"
"\t[--vulkan-glsl-disable-ext-samplerless-texture-functions]\n"
"\t[--msl]\n"
"\t[--msl-version <MMmmpp>]\n"
"\t[--msl-capture-output]\n"
"\t[--msl-swizzle-texture-samples]\n"
"\t[--msl-ios]\n"
"\t[--msl-pad-fragment-output]\n"
"\t[--msl-domain-lower-left]\n"
"\t[--msl-argument-buffers]\n"
"\t[--msl-texture-buffer-native]\n"
"\t[--msl-framebuffer-fetch]\n"
"\t[--msl-emulate-cube-array]\n"
"\t[--msl-discrete-descriptor-set <index>]\n"
"\t[--msl-device-argument-buffer <index>]\n"
"\t[--msl-multiview]\n"
"\t[--msl-view-index-from-device-index]\n"
"\t[--msl-dispatch-base]\n"
"\t[--msl-dynamic-buffer <set index> <binding>]\n"
"\t[--msl-inline-uniform-block <set index> <binding>]\n"
"\t[--msl-decoration-binding]\n"
"\t[--msl-force-active-argument-buffer-resources]\n"
"\t[--msl-force-native-arrays]\n"
"\t[--msl-disable-frag-depth-builtin]\n"
"\t[--msl-disable-frag-stencil-ref-builtin]\n"
"\t[--msl-enable-frag-output-mask <mask>]\n"
"\t[--msl-no-clip-distance-user-varying]\n"
"\t[--hlsl]\n"
"\t[--reflect]\n"
"\t[--shader-model]\n"
"\t[--hlsl-enable-compat]\n"
"\t[--hlsl-support-nonzero-basevertex-baseinstance]\n"
"\t[--hlsl-auto-binding (push, cbv, srv, uav, sampler, all)]\n"
"\t[--hlsl-force-storage-buffer-as-uav]\n"
"\t[--hlsl-nonwritable-uav-texture-as-srv]\n"
"\t[--separate-shader-objects]\n"
"\t[--pls-in format input-name]\n"
"\t[--pls-out format output-name]\n"
"\t[--remap source_name target_name components]\n"
"\t[--extension ext]\n"
"\t[--entry name]\n"
"\t[--stage <stage (vert, frag, geom, tesc, tese comp)>]\n"
"\t[--remove-unused-variables]\n"
"\t[--flatten-multidimensional-arrays]\n"
"\t[--no-420pack-extension]\n"
"\t[--remap-variable-type <variable_name> <new_variable_type>]\n"
"\t[--rename-interface-variable <in|out> <location> <new_variable_name>]\n"
"\t[--set-hlsl-vertex-input-semantic <location> <semantic>]\n"
"\t[--rename-entry-point <old> <new> <stage>]\n"
"\t[--combined-samplers-inherit-bindings]\n"
"\t[--no-support-nonzero-baseinstance]\n"
"\t[--emit-line-directives]\n"
"\n");
"\t[--output <output path>]: If not provided, prints output to stdout.\n"
"\t[--dump-resources]:\n\t\tPrints a basic reflection of the SPIR-V module along with other output.\n"
"\t[--help]:\n\t\tPrints this help message.\n"
);
print_help_backend();
print_help_common();
print_help_glsl();
print_help_msl();
print_help_hlsl();
print_help_obscure();
}
static bool remap_generic(Compiler &compiler, const SmallVector<Resource> &resources, const Remap &remap)

View File

@ -8697,7 +8697,7 @@ void CompilerGLSL::emit_instruction(const Instruction &instruction)
var->static_expression = ops[1];
else if (var && var->loop_variable && !var->loop_variable_enable)
var->static_expression = ops[1];
else if (var && var->remapped_variable)
else if (var && var->remapped_variable && var->static_expression)
{
// Skip the write.
}