2 // Copyright (C) 2002-2005 3Dlabs Inc. Ltd.
3 // Copyright (C) 2013-2016 LunarG, Inc.
4 // Copyright (C) 2015-2018 Google, Inc.
6 // All rights reserved.
8 // Redistribution and use in source and binary forms, with or without
9 // modification, are permitted provided that the following conditions
12 // Redistributions of source code must retain the above copyright
13 // notice, this list of conditions and the following disclaimer.
15 // Redistributions in binary form must reproduce the above
16 // copyright notice, this list of conditions and the following
17 // disclaimer in the documentation and/or other materials provided
18 // with the distribution.
20 // Neither the name of 3Dlabs Inc. Ltd. nor the names of its
21 // contributors may be used to endorse or promote products derived
22 // from this software without specific prior written permission.
24 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
25 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
26 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
27 // FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
28 // COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
29 // INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
30 // BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
31 // LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
32 // CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
33 // LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
34 // ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35 // POSSIBILITY OF SUCH DAMAGE.
37 #ifndef _COMPILER_INTERFACE_INCLUDED_
38 #define _COMPILER_INTERFACE_INCLUDED_
40 #include "../Include/ResourceLimits.h"
41 #include "../MachineIndependent/Versions.h"
47 #define C_DECL __cdecl
52 #ifdef GLSLANG_IS_SHARED_LIBRARY
54 #ifdef GLSLANG_EXPORTING
55 #define GLSLANG_EXPORT __declspec(dllexport)
57 #define GLSLANG_EXPORT __declspec(dllimport)
60 #define GLSLANG_EXPORT __attribute__((visibility("default")))
62 #endif // GLSLANG_IS_SHARED_LIBRARY
64 #ifndef GLSLANG_EXPORT
65 #define GLSLANG_EXPORT
69 // This is the platform independent interface between an OGL driver
70 // and the shading language compiler/linker.
78 // Call before doing any other compiler/linker operations.
80 // (Call once per process, not once per thread.)
82 GLSLANG_EXPORT int ShInitialize();
85 // Call this at process shutdown to clean up memory.
87 GLSLANG_EXPORT int ShFinalize();
90 // Types of languages the compiler can consume.
95 EShLangTessEvaluation,
100 EShLangRayGenNV = EShLangRayGen,
102 EShLangIntersectNV = EShLangIntersect,
104 EShLangAnyHitNV = EShLangAnyHit,
106 EShLangClosestHitNV = EShLangClosestHit,
108 EShLangMissNV = EShLangMiss,
110 EShLangCallableNV = EShLangCallable,
112 EShLangTaskNV = EShLangTask,
114 EShLangMeshNV = EShLangMesh,
115 LAST_ELEMENT_MARKER(EShLangCount),
116 } EShLanguage; // would be better as stage, but this is ancient now
118 typedef enum : unsigned {
119 EShLangVertexMask = (1 << EShLangVertex),
120 EShLangTessControlMask = (1 << EShLangTessControl),
121 EShLangTessEvaluationMask = (1 << EShLangTessEvaluation),
122 EShLangGeometryMask = (1 << EShLangGeometry),
123 EShLangFragmentMask = (1 << EShLangFragment),
124 EShLangComputeMask = (1 << EShLangCompute),
125 EShLangRayGenMask = (1 << EShLangRayGen),
126 EShLangRayGenNVMask = EShLangRayGenMask,
127 EShLangIntersectMask = (1 << EShLangIntersect),
128 EShLangIntersectNVMask = EShLangIntersectMask,
129 EShLangAnyHitMask = (1 << EShLangAnyHit),
130 EShLangAnyHitNVMask = EShLangAnyHitMask,
131 EShLangClosestHitMask = (1 << EShLangClosestHit),
132 EShLangClosestHitNVMask = EShLangClosestHitMask,
133 EShLangMissMask = (1 << EShLangMiss),
134 EShLangMissNVMask = EShLangMissMask,
135 EShLangCallableMask = (1 << EShLangCallable),
136 EShLangCallableNVMask = EShLangCallableMask,
137 EShLangTaskMask = (1 << EShLangTask),
138 EShLangTaskNVMask = EShLangTaskMask,
139 EShLangMeshMask = (1 << EShLangMesh),
140 EShLangMeshNVMask = EShLangMeshMask,
141 LAST_ELEMENT_MARKER(EShLanguageMaskCount),
150 EShSourceGlsl, // GLSL, includes ESSL (OpenGL ES GLSL)
151 EShSourceHlsl, // HLSL
152 LAST_ELEMENT_MARKER(EShSourceCount),
153 } EShSource; // if EShLanguage were EShStage, this could be EShLanguage instead
156 EShClientNone, // use when there is no client, e.g. for validation
157 EShClientVulkan, // as GLSL dialect, specifies KHR_vulkan_glsl extension
158 EShClientOpenGL, // as GLSL dialect, specifies ARB_gl_spirv extension
159 LAST_ELEMENT_MARKER(EShClientCount),
164 EShTargetSpv, // SPIR-V (preferred spelling)
165 EshTargetSpv = EShTargetSpv, // legacy spelling
166 LAST_ELEMENT_MARKER(EShTargetCount),
170 EShTargetVulkan_1_0 = (1 << 22), // Vulkan 1.0
171 EShTargetVulkan_1_1 = (1 << 22) | (1 << 12), // Vulkan 1.1
172 EShTargetVulkan_1_2 = (1 << 22) | (2 << 12), // Vulkan 1.2
173 EShTargetVulkan_1_3 = (1 << 22) | (3 << 12), // Vulkan 1.3
174 EShTargetOpenGL_450 = 450, // OpenGL
175 LAST_ELEMENT_MARKER(EShTargetClientVersionCount = 5),
176 } EShTargetClientVersion;
178 typedef EShTargetClientVersion EshTargetClientVersion;
181 EShTargetSpv_1_0 = (1 << 16), // SPIR-V 1.0
182 EShTargetSpv_1_1 = (1 << 16) | (1 << 8), // SPIR-V 1.1
183 EShTargetSpv_1_2 = (1 << 16) | (2 << 8), // SPIR-V 1.2
184 EShTargetSpv_1_3 = (1 << 16) | (3 << 8), // SPIR-V 1.3
185 EShTargetSpv_1_4 = (1 << 16) | (4 << 8), // SPIR-V 1.4
186 EShTargetSpv_1_5 = (1 << 16) | (5 << 8), // SPIR-V 1.5
187 EShTargetSpv_1_6 = (1 << 16) | (6 << 8), // SPIR-V 1.6
188 LAST_ELEMENT_MARKER(EShTargetLanguageVersionCount = 7),
189 } EShTargetLanguageVersion;
191 struct TInputLanguage {
192 EShSource languageFamily; // redundant information with other input, this one overrides when not EShSourceNone
193 EShLanguage stage; // redundant information with other input, this one overrides when not EShSourceNone
195 int dialectVersion; // version of client's language definition, not the client (when not EShClientNone)
196 bool vulkanRulesRelaxed;
201 EShTargetClientVersion version; // version of client itself (not the client's input dialect)
205 EShTargetLanguage language;
206 EShTargetLanguageVersion version; // version to target, if SPIR-V, defined by "word 1" of the SPIR-V header
207 bool hlslFunctionality1; // can target hlsl_functionality1 extension(s)
210 // All source/client/target versions and settings.
211 // Can override previous methods of setting, when items are set here.
212 // Expected to grow, as more are added, rather than growing parameter lists.
213 struct TEnvironment {
214 TInputLanguage input; // definition of the input language
215 TClient client; // what client is the overall compilation being done for?
216 TTarget target; // what to generate
219 GLSLANG_EXPORT const char* StageName(EShLanguage);
221 } // end namespace glslang
224 // Types of output the linker will create.
232 // Optimization level for the compiler.
237 EShOptSimple, // Optimizations that can be done quickly
238 EShOptFull, // Optimizations that will take more time
239 LAST_ELEMENT_MARKER(EshOptLevelCount),
240 } EShOptimizationLevel;
243 // Texture and Sampler transformation mode.
246 EShTexSampTransKeep, // keep textures and samplers as is (default)
247 EShTexSampTransUpgradeTextureRemoveSampler, // change texture w/o embeded sampler into sampled texture and throw away all samplers
248 LAST_ELEMENT_MARKER(EShTexSampTransCount),
249 } EShTextureSamplerTransformMode;
252 // Message choices for what errors and warnings are given.
254 enum EShMessages : unsigned {
255 EShMsgDefault = 0, // default is to give all required errors and extra warnings
256 EShMsgRelaxedErrors = (1 << 0), // be liberal in accepting input
257 EShMsgSuppressWarnings = (1 << 1), // suppress all warnings, except those required by the specification
258 EShMsgAST = (1 << 2), // print the AST intermediate representation
259 EShMsgSpvRules = (1 << 3), // issue messages for SPIR-V generation
260 EShMsgVulkanRules = (1 << 4), // issue messages for Vulkan-requirements of GLSL for SPIR-V
261 EShMsgOnlyPreprocessor = (1 << 5), // only print out errors produced by the preprocessor
262 EShMsgReadHlsl = (1 << 6), // use HLSL parsing rules and semantics
263 EShMsgCascadingErrors = (1 << 7), // get cascading errors; risks error-recovery issues, instead of an early exit
264 EShMsgKeepUncalled = (1 << 8), // for testing, don't eliminate uncalled functions
265 EShMsgHlslOffsets = (1 << 9), // allow block offsets to follow HLSL rules instead of GLSL rules
266 EShMsgDebugInfo = (1 << 10), // save debug information
267 EShMsgHlslEnable16BitTypes = (1 << 11), // enable use of 16-bit types in SPIR-V for HLSL
268 EShMsgHlslLegalization = (1 << 12), // enable HLSL Legalization messages
269 EShMsgHlslDX9Compatible = (1 << 13), // enable HLSL DX9 compatible mode (for samplers and semantics)
270 EShMsgBuiltinSymbolTable = (1 << 14), // print the builtin symbol table
271 EShMsgEnhanced = (1 << 15), // enhanced message readability
272 LAST_ELEMENT_MARKER(EShMsgCount),
276 // Options for building reflection
279 EShReflectionDefault = 0, // default is original behaviour before options were added
280 EShReflectionStrictArraySuffix = (1 << 0), // reflection will follow stricter rules for array-of-structs suffixes
281 EShReflectionBasicArraySuffix = (1 << 1), // arrays of basic types will be appended with [0] as in GL reflection
282 EShReflectionIntermediateIO = (1 << 2), // reflect inputs and outputs to program, even with no vertex shader
283 EShReflectionSeparateBuffers = (1 << 3), // buffer variables and buffer blocks are reflected separately
284 EShReflectionAllBlockVariables = (1 << 4), // reflect all variables in blocks, even if they are inactive
285 EShReflectionUnwrapIOBlocks = (1 << 5), // unwrap input/output blocks the same as with uniform blocks
286 EShReflectionAllIOVariables = (1 << 6), // reflect all input/output variables, even if they are inactive
287 EShReflectionSharedStd140SSBO = (1 << 7), // Apply std140/shared rules for ubo to ssbo
288 EShReflectionSharedStd140UBO = (1 << 8), // Apply std140/shared rules for ubo to ssbo
289 LAST_ELEMENT_MARKER(EShReflectionCount),
290 } EShReflectionOptions;
293 // Build a table for bindings. This can be used for locating
294 // attributes, uniforms, globals, etc., as needed.
303 ShBinding* bindings; // array of bindings
307 // ShHandle held by but opaque to the driver. It is allocated,
308 // managed, and de-allocated by the compiler/linker. Its contents
309 // are defined by and used by the compiler and linker. For example,
310 // symbol table information and object code passed from the compiler
311 // to the linker can be stored where ShHandle points.
313 // If handle creation fails, 0 will be returned.
315 typedef void* ShHandle;
318 // Driver calls these to create and destroy compiler/linker
321 GLSLANG_EXPORT ShHandle ShConstructCompiler(const EShLanguage, int debugOptions); // one per shader
322 GLSLANG_EXPORT ShHandle ShConstructLinker(const EShExecutable, int debugOptions); // one per shader pair
323 GLSLANG_EXPORT ShHandle ShConstructUniformMap(); // one per uniform namespace (currently entire program object)
324 GLSLANG_EXPORT void ShDestruct(ShHandle);
327 // The return value of ShCompile is boolean, non-zero indicating
330 // The info-log should be written by ShCompile into
331 // ShHandle, so it can answer future queries.
333 GLSLANG_EXPORT int ShCompile(
335 const char* const shaderStrings[],
336 const int numStrings,
338 const EShOptimizationLevel,
339 const TBuiltInResource *resources,
341 int defaultVersion = 110, // use 100 for ES environment, overridden by #version in shader
342 bool forwardCompatible = false, // give errors for use of deprecated features
343 EShMessages messages = EShMsgDefault // warnings and errors
346 GLSLANG_EXPORT int ShLinkExt(
347 const ShHandle, // linker object
348 const ShHandle h[], // compiler objects to link together
349 const int numHandles);
352 // ShSetEncrpytionMethod is a place-holder for specifying
353 // how source code is encrypted.
355 GLSLANG_EXPORT void ShSetEncryptionMethod(ShHandle);
358 // All the following return 0 if the information is not
359 // available in the object passed down, or the object is bad.
361 GLSLANG_EXPORT const char* ShGetInfoLog(const ShHandle);
362 GLSLANG_EXPORT const void* ShGetExecutable(const ShHandle);
363 GLSLANG_EXPORT int ShSetVirtualAttributeBindings(const ShHandle, const ShBindingTable*); // to detect user aliasing
364 GLSLANG_EXPORT int ShSetFixedAttributeBindings(const ShHandle, const ShBindingTable*); // to force any physical mappings
366 // Tell the linker to never assign a vertex attribute to this list of physical attributes
368 GLSLANG_EXPORT int ShExcludeAttributes(const ShHandle, int *attributes, int count);
371 // Returns the location ID of the named uniform.
372 // Returns -1 if error.
374 GLSLANG_EXPORT int ShGetUniformLocation(const ShHandle uniformMap, const char* name);
380 ////////////////////////////////////////////////////////////////////////////////////////////
382 // Deferred-Lowering C++ Interface
383 // -----------------------------------
385 // Below is a new alternate C++ interface, which deprecates the above
386 // opaque handle-based interface.
388 // The below is further designed to handle multiple compilation units per stage, where
389 // the intermediate results, including the parse tree, are preserved until link time,
390 // rather than the above interface which is designed to have each compilation unit
391 // lowered at compile time. In the above model, linking occurs on the lowered results,
392 // whereas in this model intra-stage linking can occur at the parse tree
393 // (treeRoot in TIntermediate) level, and then a full stage can be lowered.
412 GLSLANG_EXPORT Version GetVersion();
413 GLSLANG_EXPORT const char* GetEsslVersionString();
414 GLSLANG_EXPORT const char* GetGlslVersionString();
415 GLSLANG_EXPORT int GetKhronosToolId();
419 class TPoolAllocator;
421 // Call this exactly once per process before using anything else
422 GLSLANG_EXPORT bool InitializeProcess();
424 // Call once per process to tear down everything
425 GLSLANG_EXPORT void FinalizeProcess();
427 // Resource type for IO resolver
438 enum TBlockStorageClass
443 EbsNone, // not a uniform or buffer variable
447 // Make one TShader per shader that you will link into a program. Then
448 // - provide the shader through setStrings() or setStringsWithLengths()
449 // - optionally call setEnv*(), see below for more detail
450 // - optionally use setPreamble() to set a special shader string that will be
451 // processed before all others but won't affect the validity of #version
452 // - optionally call addProcesses() for each setting/transform,
453 // see comment for class TProcesses
454 // - call parse(): source language and target environment must be selected
455 // either by correct setting of EShMessages sent to parse(), or by
456 // explicitly calling setEnv*()
457 // - query the info logs
459 // N.B.: Does not yet support having the same TShader instance being linked into
460 // multiple programs.
462 // N.B.: Destruct a linked program *before* destructing the shaders linked into it.
466 GLSLANG_EXPORT explicit TShader(EShLanguage);
467 GLSLANG_EXPORT virtual ~TShader();
468 GLSLANG_EXPORT void setStrings(const char* const* s, int n);
469 GLSLANG_EXPORT void setStringsWithLengths(
470 const char* const* s, const int* l, int n);
471 GLSLANG_EXPORT void setStringsWithLengthsAndNames(
472 const char* const* s, const int* l, const char* const* names, int n);
473 void setPreamble(const char* s) { preamble = s; }
474 GLSLANG_EXPORT void setEntryPoint(const char* entryPoint);
475 GLSLANG_EXPORT void setSourceEntryPoint(const char* sourceEntryPointName);
476 GLSLANG_EXPORT void addProcesses(const std::vector<std::string>&);
477 GLSLANG_EXPORT void setUniqueId(unsigned long long id);
478 GLSLANG_EXPORT void setOverrideVersion(int version);
479 GLSLANG_EXPORT void setDebugInfo(bool debugInfo);
481 // IO resolver binding data: see comments in ShaderLang.cpp
482 GLSLANG_EXPORT void setShiftBinding(TResourceType res, unsigned int base);
483 GLSLANG_EXPORT void setShiftSamplerBinding(unsigned int base); // DEPRECATED: use setShiftBinding
484 GLSLANG_EXPORT void setShiftTextureBinding(unsigned int base); // DEPRECATED: use setShiftBinding
485 GLSLANG_EXPORT void setShiftImageBinding(unsigned int base); // DEPRECATED: use setShiftBinding
486 GLSLANG_EXPORT void setShiftUboBinding(unsigned int base); // DEPRECATED: use setShiftBinding
487 GLSLANG_EXPORT void setShiftUavBinding(unsigned int base); // DEPRECATED: use setShiftBinding
488 GLSLANG_EXPORT void setShiftCbufferBinding(unsigned int base); // synonym for setShiftUboBinding
489 GLSLANG_EXPORT void setShiftSsboBinding(unsigned int base); // DEPRECATED: use setShiftBinding
490 GLSLANG_EXPORT void setShiftBindingForSet(TResourceType res, unsigned int base, unsigned int set);
491 GLSLANG_EXPORT void setResourceSetBinding(const std::vector<std::string>& base);
492 GLSLANG_EXPORT void setAutoMapBindings(bool map);
493 GLSLANG_EXPORT void setAutoMapLocations(bool map);
494 GLSLANG_EXPORT void addUniformLocationOverride(const char* name, int loc);
495 GLSLANG_EXPORT void setUniformLocationBase(int base);
496 GLSLANG_EXPORT void setInvertY(bool invert);
497 GLSLANG_EXPORT void setDxPositionW(bool dxPosW);
498 GLSLANG_EXPORT void setEnhancedMsgs();
500 GLSLANG_EXPORT void setHlslIoMapping(bool hlslIoMap);
501 GLSLANG_EXPORT void setFlattenUniformArrays(bool flatten);
503 GLSLANG_EXPORT void setNoStorageFormat(bool useUnknownFormat);
504 GLSLANG_EXPORT void setNanMinMaxClamp(bool nanMinMaxClamp);
505 GLSLANG_EXPORT void setTextureSamplerTransformMode(EShTextureSamplerTransformMode mode);
506 GLSLANG_EXPORT void addBlockStorageOverride(const char* nameStr, glslang::TBlockStorageClass backing);
508 GLSLANG_EXPORT void setGlobalUniformBlockName(const char* name);
509 GLSLANG_EXPORT void setAtomicCounterBlockName(const char* name);
510 GLSLANG_EXPORT void setGlobalUniformSet(unsigned int set);
511 GLSLANG_EXPORT void setGlobalUniformBinding(unsigned int binding);
512 GLSLANG_EXPORT void setAtomicCounterBlockSet(unsigned int set);
513 GLSLANG_EXPORT void setAtomicCounterBlockBinding(unsigned int binding);
515 // For setting up the environment (cleared to nothingness in the constructor).
516 // These must be called so that parsing is done for the right source language and
517 // target environment, either indirectly through TranslateEnvironment() based on
518 // EShMessages et. al., or directly by the user.
520 // setEnvInput: The input source language and stage. If generating code for a
521 // specific client, the input client semantics to use and the
522 // version of that client's input semantics to use, otherwise
523 // use EShClientNone and version of 0, e.g. for validation mode.
524 // Note 'version' does not describe the target environment,
525 // just the version of the source dialect to compile under.
526 // For example, to choose the Vulkan dialect of GLSL defined by
527 // version 100 of the KHR_vulkan_glsl extension: lang = EShSourceGlsl,
528 // dialect = EShClientVulkan, and version = 100.
530 // See the definitions of TEnvironment, EShSource, EShLanguage,
531 // and EShClient for choices and more detail.
533 // setEnvClient: The client that will be hosting the execution, and its version.
534 // Note 'version' is not the version of the languages involved, but
535 // the version of the client environment.
536 // Use EShClientNone and version of 0 if there is no client, e.g.
537 // for validation mode.
539 // See EShTargetClientVersion for choices.
541 // setEnvTarget: The language to translate to when generating code, and that
542 // language's version.
543 // Use EShTargetNone and version of 0 if there is no client, e.g.
544 // for validation mode.
546 void setEnvInput(EShSource lang, EShLanguage envStage, EShClient client, int version)
548 environment.input.languageFamily = lang;
549 environment.input.stage = envStage;
550 environment.input.dialect = client;
551 environment.input.dialectVersion = version;
553 void setEnvClient(EShClient client, EShTargetClientVersion version)
555 environment.client.client = client;
556 environment.client.version = version;
558 void setEnvTarget(EShTargetLanguage lang, EShTargetLanguageVersion version)
560 environment.target.language = lang;
561 environment.target.version = version;
564 void getStrings(const char* const* &s, int& n) { s = strings; n = numStrings; }
567 void setEnvTargetHlslFunctionality1() { environment.target.hlslFunctionality1 = true; }
568 bool getEnvTargetHlslFunctionality1() const { return environment.target.hlslFunctionality1; }
570 bool getEnvTargetHlslFunctionality1() const { return false; }
573 void setEnvInputVulkanRulesRelaxed() { environment.input.vulkanRulesRelaxed = true; }
574 bool getEnvInputVulkanRulesRelaxed() const { return environment.input.vulkanRulesRelaxed; }
576 // Interface to #include handlers.
578 // To support #include, a client of Glslang does the following:
579 // 1. Call setStringsWithNames to set the source strings and associated
580 // names. For example, the names could be the names of the files
581 // containing the shader sources.
582 // 2. Call parse with an Includer.
584 // When the Glslang parser encounters an #include directive, it calls
585 // the Includer's include method with the requested include name
586 // together with the current string name. The returned IncludeResult
587 // contains the fully resolved name of the included source, together
588 // with the source text that should replace the #include directive
589 // in the source stream. After parsing that source, Glslang will
590 // release the IncludeResult object.
593 // An IncludeResult contains the resolved name and content of a source
595 struct IncludeResult {
596 IncludeResult(const std::string& headerName, const char* const headerData, const size_t headerLength, void* userData) :
597 headerName(headerName), headerData(headerData), headerLength(headerLength), userData(userData) { }
598 // For a successful inclusion, the fully resolved name of the requested
599 // include. For example, in a file system-based includer, full resolution
600 // should convert a relative path name into an absolute path name.
601 // For a failed inclusion, this is an empty string.
602 const std::string headerName;
603 // The content and byte length of the requested inclusion. The
604 // Includer producing this IncludeResult retains ownership of the
606 // For a failed inclusion, the header
607 // field points to a string containing error details.
608 const char* const headerData;
609 const size_t headerLength;
610 // Include resolver's context.
613 IncludeResult& operator=(const IncludeResult&);
617 // For both include methods below:
619 // Resolves an inclusion request by name, current source name,
620 // and include depth.
621 // On success, returns an IncludeResult containing the resolved name
622 // and content of the include.
623 // On failure, returns a nullptr, or an IncludeResult
624 // with an empty string for the headerName and error details in the
626 // The Includer retains ownership of the contents
627 // of the returned IncludeResult value, and those contents must
628 // remain valid until the releaseInclude method is called on that
629 // IncludeResult object.
631 // Note "local" vs. "system" is not an "either/or": "local" is an
632 // extra thing to do over "system". Both might get called, as per
633 // the C++ specification.
635 // For the "system" or <>-style includes; search the "system" paths.
636 virtual IncludeResult* includeSystem(const char* /*headerName*/,
637 const char* /*includerName*/,
638 size_t /*inclusionDepth*/) { return nullptr; }
640 // For the "local"-only aspect of a "" include. Should not search in the
641 // "system" paths, because on returning a failure, the parser will
642 // call includeSystem() to look in the "system" locations.
643 virtual IncludeResult* includeLocal(const char* /*headerName*/,
644 const char* /*includerName*/,
645 size_t /*inclusionDepth*/) { return nullptr; }
647 // Signals that the parser will no longer use the contents of the
648 // specified IncludeResult.
649 virtual void releaseInclude(IncludeResult*) = 0;
650 virtual ~Includer() {}
653 // Fail all Includer searches
654 class ForbidIncluder : public Includer {
656 virtual void releaseInclude(IncludeResult*) override { }
659 GLSLANG_EXPORT bool parse(
660 const TBuiltInResource*, int defaultVersion, EProfile defaultProfile,
661 bool forceDefaultVersionAndProfile, bool forwardCompatible,
662 EShMessages, Includer&);
664 bool parse(const TBuiltInResource* res, int defaultVersion, EProfile defaultProfile, bool forceDefaultVersionAndProfile,
665 bool forwardCompatible, EShMessages messages)
667 TShader::ForbidIncluder includer;
668 return parse(res, defaultVersion, defaultProfile, forceDefaultVersionAndProfile, forwardCompatible, messages, includer);
671 // Equivalent to parse() without a default profile and without forcing defaults.
672 bool parse(const TBuiltInResource* builtInResources, int defaultVersion, bool forwardCompatible, EShMessages messages)
674 return parse(builtInResources, defaultVersion, ENoProfile, false, forwardCompatible, messages);
677 bool parse(const TBuiltInResource* builtInResources, int defaultVersion, bool forwardCompatible, EShMessages messages,
680 return parse(builtInResources, defaultVersion, ENoProfile, false, forwardCompatible, messages, includer);
683 // NOTE: Doing just preprocessing to obtain a correct preprocessed shader string
684 // is not an officially supported or fully working path.
685 GLSLANG_EXPORT bool preprocess(
686 const TBuiltInResource* builtInResources, int defaultVersion,
687 EProfile defaultProfile, bool forceDefaultVersionAndProfile,
688 bool forwardCompatible, EShMessages message, std::string* outputString,
691 GLSLANG_EXPORT const char* getInfoLog();
692 GLSLANG_EXPORT const char* getInfoDebugLog();
693 EShLanguage getStage() const { return stage; }
694 TIntermediate* getIntermediate() const { return intermediate; }
697 TPoolAllocator* pool;
700 TIntermediate* intermediate;
702 // strings and lengths follow the standard for glShaderSource:
703 // strings is an array of numStrings pointers to string data.
704 // lengths can be null, but if not it is an array of numStrings
705 // integers containing the length of the associated strings.
706 // if lengths is null or lengths[n] < 0 the associated strings[n] is
707 // assumed to be null-terminated.
708 // stringNames is the optional names for all the strings. If stringNames
709 // is null, then none of the strings has name. If a certain element in
710 // stringNames is null, then the corresponding string does not have name.
711 const char* const* strings; // explicit code to compile, see previous comment
713 const char* const* stringNames;
714 int numStrings; // size of the above arrays
715 const char* preamble; // string of implicit code to compile before the explicitly provided code
717 // a function in the source string can be renamed FROM this TO the name given in setEntryPoint.
718 std::string sourceEntryPointName;
720 // overrides #version in shader source or default version if #version isn't present
723 TEnvironment environment;
725 friend class TProgram;
728 TShader& operator=(TShader&);
731 #if !defined(GLSLANG_WEB) && !defined(GLSLANG_ANGLE)
734 // A reflection database and its interface, consistent with the OpenGL API reflection queries.
737 // Data needed for just a single object at the granularity exchanged by the reflection API
738 class TObjectReflection {
740 GLSLANG_EXPORT TObjectReflection(const std::string& pName, const TType& pType, int pOffset, int pGLDefineType, int pSize, int pIndex);
742 const TType* getType() const { return type; }
743 GLSLANG_EXPORT int getBinding() const;
744 GLSLANG_EXPORT void dump() const;
745 static TObjectReflection badReflection() { return TObjectReflection(); }
750 int size; // data size in bytes for a block, array size for a (non-block) object that's an array
754 int arrayStride; // stride of an array variable
755 int topLevelArraySize; // size of the top-level variable in a storage buffer member
756 int topLevelArrayStride; // stride of the top-level variable in a storage buffer member
757 EShLanguageMask stages;
761 : offset(-1), glDefineType(-1), size(-1), index(-1), counterIndex(-1), numMembers(-1), arrayStride(0),
762 topLevelArrayStride(0), stages(EShLanguageMask(0)), type(nullptr)
771 struct TVarEntryInfo;
773 // Allows to customize the binding layout after linking.
774 // All used uniform variables will invoke at least validateBinding.
775 // If validateBinding returned true then the other resolveBinding,
776 // resolveSet, and resolveLocation are invoked to resolve the binding
777 // and descriptor set index respectively.
779 // Invocations happen in a particular order:
780 // 1) all shader inputs
781 // 2) all shader outputs
782 // 3) all uniforms with binding and set already defined
783 // 4) all uniforms with binding but no set defined
784 // 5) all uniforms with set but no binding defined
785 // 6) all uniforms with no binding and no set defined
787 // mapIO will use this resolver in two phases. The first
788 // phase is a notification phase, calling the corresponging
789 // notifiy callbacks, this phase ends with a call to endNotifications.
790 // Phase two starts directly after the call to endNotifications
791 // and calls all other callbacks to validate and to get the
792 // bindings, sets, locations, component and color indices.
794 // NOTE: that still limit checks are applied to bindings and sets
795 // and may result in an error.
799 virtual ~TIoMapResolver() {}
801 // Should return true if the resulting/current binding would be okay.
802 // Basic idea is to do aliasing binding checks with this.
803 virtual bool validateBinding(EShLanguage stage, TVarEntryInfo& ent) = 0;
804 // Should return a value >= 0 if the current binding should be overridden.
805 // Return -1 if the current binding (including no binding) should be kept.
806 virtual int resolveBinding(EShLanguage stage, TVarEntryInfo& ent) = 0;
807 // Should return a value >= 0 if the current set should be overridden.
808 // Return -1 if the current set (including no set) should be kept.
809 virtual int resolveSet(EShLanguage stage, TVarEntryInfo& ent) = 0;
810 // Should return a value >= 0 if the current location should be overridden.
811 // Return -1 if the current location (including no location) should be kept.
812 virtual int resolveUniformLocation(EShLanguage stage, TVarEntryInfo& ent) = 0;
813 // Should return true if the resulting/current setup would be okay.
814 // Basic idea is to do aliasing checks and reject invalid semantic names.
815 virtual bool validateInOut(EShLanguage stage, TVarEntryInfo& ent) = 0;
816 // Should return a value >= 0 if the current location should be overridden.
817 // Return -1 if the current location (including no location) should be kept.
818 virtual int resolveInOutLocation(EShLanguage stage, TVarEntryInfo& ent) = 0;
819 // Should return a value >= 0 if the current component index should be overridden.
820 // Return -1 if the current component index (including no index) should be kept.
821 virtual int resolveInOutComponent(EShLanguage stage, TVarEntryInfo& ent) = 0;
822 // Should return a value >= 0 if the current color index should be overridden.
823 // Return -1 if the current color index (including no index) should be kept.
824 virtual int resolveInOutIndex(EShLanguage stage, TVarEntryInfo& ent) = 0;
825 // Notification of a uniform variable
826 virtual void notifyBinding(EShLanguage stage, TVarEntryInfo& ent) = 0;
827 // Notification of a in or out variable
828 virtual void notifyInOut(EShLanguage stage, TVarEntryInfo& ent) = 0;
829 // Called by mapIO when it starts its notify pass for the given stage
830 virtual void beginNotifications(EShLanguage stage) = 0;
831 // Called by mapIO when it has finished the notify pass
832 virtual void endNotifications(EShLanguage stage) = 0;
833 // Called by mipIO when it starts its resolve pass for the given stage
834 virtual void beginResolve(EShLanguage stage) = 0;
835 // Called by mapIO when it has finished the resolve pass
836 virtual void endResolve(EShLanguage stage) = 0;
837 // Called by mapIO when it starts its symbol collect for teh given stage
838 virtual void beginCollect(EShLanguage stage) = 0;
839 // Called by mapIO when it has finished the symbol collect
840 virtual void endCollect(EShLanguage stage) = 0;
841 // Called by TSlotCollector to resolve storage locations or bindings
842 virtual void reserverStorageSlot(TVarEntryInfo& ent, TInfoSink& infoSink) = 0;
843 // Called by TSlotCollector to resolve resource locations or bindings
844 virtual void reserverResourceSlot(TVarEntryInfo& ent, TInfoSink& infoSink) = 0;
845 // Called by mapIO.addStage to set shader stage mask to mark a stage be added to this pipeline
846 virtual void addStage(EShLanguage stage, TIntermediate& stageIntermediate) = 0;
849 #endif // !GLSLANG_WEB && !GLSLANG_ANGLE
851 // Make one TProgram per set of shaders that will get linked together. Add all
852 // the shaders that are to be linked together. After calling shader.parse()
853 // for all shaders, call link().
855 // N.B.: Destruct a linked program *before* destructing the shaders linked into it.
859 GLSLANG_EXPORT TProgram();
860 GLSLANG_EXPORT virtual ~TProgram();
861 void addShader(TShader* shader) { stages[shader->stage].push_back(shader); }
862 std::list<TShader*>& getShaders(EShLanguage stage) { return stages[stage]; }
863 // Link Validation interface
864 GLSLANG_EXPORT bool link(EShMessages);
865 GLSLANG_EXPORT const char* getInfoLog();
866 GLSLANG_EXPORT const char* getInfoDebugLog();
868 TIntermediate* getIntermediate(EShLanguage stage) const { return intermediate[stage]; }
870 #if !defined(GLSLANG_WEB) && !defined(GLSLANG_ANGLE)
872 // Reflection Interface
874 // call first, to do liveness analysis, index mapping, etc.; returns false on failure
875 GLSLANG_EXPORT bool buildReflection(int opts = EShReflectionDefault);
876 GLSLANG_EXPORT unsigned getLocalSize(int dim) const; // return dim'th local size
877 GLSLANG_EXPORT int getReflectionIndex(const char *name) const;
878 GLSLANG_EXPORT int getReflectionPipeIOIndex(const char* name, const bool inOrOut) const;
879 GLSLANG_EXPORT int getNumUniformVariables() const;
880 GLSLANG_EXPORT const TObjectReflection& getUniform(int index) const;
881 GLSLANG_EXPORT int getNumUniformBlocks() const;
882 GLSLANG_EXPORT const TObjectReflection& getUniformBlock(int index) const;
883 GLSLANG_EXPORT int getNumPipeInputs() const;
884 GLSLANG_EXPORT const TObjectReflection& getPipeInput(int index) const;
885 GLSLANG_EXPORT int getNumPipeOutputs() const;
886 GLSLANG_EXPORT const TObjectReflection& getPipeOutput(int index) const;
887 GLSLANG_EXPORT int getNumBufferVariables() const;
888 GLSLANG_EXPORT const TObjectReflection& getBufferVariable(int index) const;
889 GLSLANG_EXPORT int getNumBufferBlocks() const;
890 GLSLANG_EXPORT const TObjectReflection& getBufferBlock(int index) const;
891 GLSLANG_EXPORT int getNumAtomicCounters() const;
892 GLSLANG_EXPORT const TObjectReflection& getAtomicCounter(int index) const;
894 // Legacy Reflection Interface - expressed in terms of above interface
896 // can be used for glGetProgramiv(GL_ACTIVE_UNIFORMS)
897 int getNumLiveUniformVariables() const { return getNumUniformVariables(); }
899 // can be used for glGetProgramiv(GL_ACTIVE_UNIFORM_BLOCKS)
900 int getNumLiveUniformBlocks() const { return getNumUniformBlocks(); }
902 // can be used for glGetProgramiv(GL_ACTIVE_ATTRIBUTES)
903 int getNumLiveAttributes() const { return getNumPipeInputs(); }
905 // can be used for glGetUniformIndices()
906 int getUniformIndex(const char *name) const { return getReflectionIndex(name); }
908 int getPipeIOIndex(const char *name, const bool inOrOut) const
909 { return getReflectionPipeIOIndex(name, inOrOut); }
911 // can be used for "name" part of glGetActiveUniform()
912 const char *getUniformName(int index) const { return getUniform(index).name.c_str(); }
914 // returns the binding number
915 int getUniformBinding(int index) const { return getUniform(index).getBinding(); }
917 // returns Shaders Stages where a Uniform is present
918 EShLanguageMask getUniformStages(int index) const { return getUniform(index).stages; }
920 // can be used for glGetActiveUniformsiv(GL_UNIFORM_BLOCK_INDEX)
921 int getUniformBlockIndex(int index) const { return getUniform(index).index; }
923 // can be used for glGetActiveUniformsiv(GL_UNIFORM_TYPE)
924 int getUniformType(int index) const { return getUniform(index).glDefineType; }
926 // can be used for glGetActiveUniformsiv(GL_UNIFORM_OFFSET)
927 int getUniformBufferOffset(int index) const { return getUniform(index).offset; }
929 // can be used for glGetActiveUniformsiv(GL_UNIFORM_SIZE)
930 int getUniformArraySize(int index) const { return getUniform(index).size; }
933 const TType *getUniformTType(int index) const { return getUniform(index).getType(); }
935 // can be used for glGetActiveUniformBlockName()
936 const char *getUniformBlockName(int index) const { return getUniformBlock(index).name.c_str(); }
938 // can be used for glGetActiveUniformBlockiv(UNIFORM_BLOCK_DATA_SIZE)
939 int getUniformBlockSize(int index) const { return getUniformBlock(index).size; }
941 // returns the block binding number
942 int getUniformBlockBinding(int index) const { return getUniformBlock(index).getBinding(); }
944 // returns block index of associated counter.
945 int getUniformBlockCounterIndex(int index) const { return getUniformBlock(index).counterIndex; }
948 const TType *getUniformBlockTType(int index) const { return getUniformBlock(index).getType(); }
950 // can be used for glGetActiveAttrib()
951 const char *getAttributeName(int index) const { return getPipeInput(index).name.c_str(); }
953 // can be used for glGetActiveAttrib()
954 int getAttributeType(int index) const { return getPipeInput(index).glDefineType; }
957 const TType *getAttributeTType(int index) const { return getPipeInput(index).getType(); }
959 GLSLANG_EXPORT void dumpReflection();
960 // I/O mapping: apply base offsets and map live unbound variables
961 // If resolver is not provided it uses the previous approach
962 // and respects auto assignment and offsets.
963 GLSLANG_EXPORT bool mapIO(TIoMapResolver* pResolver = nullptr, TIoMapper* pIoMapper = nullptr);
964 #endif // !GLSLANG_WEB && !GLSLANG_ANGLE
967 GLSLANG_EXPORT bool linkStage(EShLanguage, EShMessages);
968 GLSLANG_EXPORT bool crossStageCheck(EShMessages);
970 TPoolAllocator* pool;
971 std::list<TShader*> stages[EShLangCount];
972 TIntermediate* intermediate[EShLangCount];
973 bool newedIntermediate[EShLangCount]; // track which intermediate were "new" versus reusing a singleton unit in a stage
975 #if !defined(GLSLANG_WEB) && !defined(GLSLANG_ANGLE)
976 TReflection* reflection;
982 TProgram& operator=(TProgram&);
985 } // end namespace glslang
987 #endif // _COMPILER_INTERFACE_INCLUDED_