3.8. Preprocessor

The preprocessor is much like that in C. Support for

#define
#undef
#if
#ifdef
#ifndef
#else
#elif
#endif

as well as the defined operator are exactly as in standard C. This includes macros with arguments and macro expansion. Built-in macros are

__LINE__
__FILE__
__VERSION__

__LINE__ substitutes a decimal integer constant that is one more than the number of preceding new-lines in the current source string.

__FILE__ substitutes a decimal integer constant that says which source string number is currently being processed.

__VERSION__ substitutes a decimal integer reflecting the version number of the OpenGL Shading Language. The version of the shading language described in this document has __VERSION__ defined as the decimal integer 110.

Macro names containing two consecutive underscores (__) are reserved for future use as predefined macro names, as are all macro names prefixed with "GL_".

There is also the usual support for

#error message
#line
#pragma

#error puts message into the shader's information log. The compiler then proceeds as if a semantic error has been encountered.

#line must have, after macro substitution, one of the following two forms:

#line line
#line line source-string-number

where line and source-string-number are constant integer expressions. After processing this directive (including its new-line), the implementation behaves as if it is compiling at line number line+1 and source string number source-string-number. Subsequent source strings are numbered sequentially until another #line directive overrides that numbering.

#pragma is implementation dependent. Tokens following #pragma are not subject to preprocessor macro expansion. If an implementation does not recognize the tokens specified by the pragma, the pragma is ignored. However, the following pragmas are defined as part of the language.

#pragma STDGL

The STDGL pragma reserves pragmas for use by future revisions of the OpenGL Shading Language. No implementation may use a pragma whose first token is STDGL.

Use the optimize pragma

#pragma optimize(on)
#pragma optimize(off)

to turn optimizations on or off as an aid in developing and debugging shaders. The optimize pragma can occur only outside function definitions. By default, optimization is turned on for all shaders.

The debug pragma

#pragma debug(on)
#pragma debug(off)

enables compiling and annotating a shader with debug information so that it can be used with a debugger. The debug pragma can occur only outside function definitions. By default, debug is set to off.

Shaders should declare the version of the language to which they are written by using

#version number

If the targeted version of the language is the version that was approved in conjunction with OpenGL 2.0, then a value of 110 should be used for number. Any value less than 110 causes an error to be generated. Any value greater than the latest version of the language supported by the compiler also causes an error to be generated. Version 110 of the language does not require shaders to include this directive, and shaders without this directive are assumed to target version 110 of the OpenGL Shading Language. This directive, when present, must occur in a shader before anything else except comments and white space.

By default, compilers must issue compile-time syntactic, grammatical, and semantic errors for shaders that do not conform to the OpenGL Shading Language specification. Any extended behavior must first be enabled through a preprocessor directive. The behavior of the compiler with respect to extensions is declared with the #extension directive:

#extension extension_name : behavior
#extension all : behavior

extension_name is the name of an extension. The token all means that the specified behavior should apply to all extensions supported by the compiler. The possible values for behavior and their corresponding effects are shown in Table 3.2. A shader could check for the existence of a built-in function named foo defined by a language extension named GL_ARB_foo in the following way:

Table 3.2. Permitted values for the behavior expression in the #extension directive

Value of behavior	Effect
require	Behave as specified by the extension extension_name. The compiler reports an error on the #extension directive if the specified extension is not supported or if the token all is used instead of an extension name.
enable	Behave as specified by the extension extension_name. The compiler provides a warning on the #extension directive if the specified extension is not supported, and it reports an error if the token all is used instead of an extension name.
warn	Behave as specified by the extension extension_name, except cause the compiler to issue warnings on any detectable use of the specified extension, unless such use is supported by other enabled or required extensions. If all is specified, then the compiler warns on all detectable uses of any extension used.
disable	Behave (including errors and warnings) as if the extension specified by extension_name is not part of the language definition. If all is specified, then behavior must revert to that of the nonextended version of the language that is being targeted. The compiler warns if the specified extension is not supported.

#ifdef GL_ARB_foo
    #extension GL_ARB_foo : enable
    myFoo = foo(); // use the built-in foo()
#else
    // use some other method to compute myFoo
#endif

Directives that occur later override those that occur earlier. The all token sets the behavior for all extensions, overriding all previously issued #extension directives, but only for behaviors warn and disable.

The initial state of the compiler is as if the directive

#extension all : disable

were issued, telling the compiler that all error and warning reporting must be done according to the nonextended version of the OpenGL Shading Language that is being targeted (i.e., all extensions are ignored).

Macro expansion is not done on lines containing #extension and #version directives.

The number sign (#) on a line by itself is ignored. Any directive not described in this section causes the compiler to generate an error message. The shader is subsequently treated as ill-formed.