Preprocessor directives

Like GLSL, the Shadron scripting language mimics some C-style preprocessor directives. They start with a hash tag (#) followed by the directive's name and arguments, and are terminated by a newline character (unless preceeded by a backslash).

The available directives are:

  • #version – the GLSL version specification
  • #include – inclusion of another script
  • #extension, #ifextension – declaration of extension usage
  • #define (and #undef) – macro definition
  • #if, #ifdef, #ifndef, #elif, #else, #endif – conditional directives
  • #error – explicit error clause
  • #pragma – miscellaneous Shadron-specific directives

#version

Specifies the used version of the OpenGL Shading Language (GLSL). This must be placed before any GLSL code and must only be specified once. The syntax and meaning is equivalent to the GLSL #version directive. For Windows, the supported versions are 110 through 450, with 130 (OpenGL 3.0) being the default. For macOS, the minimum and default version is 150 (OpenGL 3.2).

Example: 

#version 330

#include

The include directive is very similar to the C/C++ #include directive. It loads a script from another file and places it at that position in the current file. Unlike C/C++, each file is only included once, so you don't have to use include guards.

Similarly to C/C++, to use a script from the Shadron's library, enclose the script name in angle brackets, and if you want to include your own script, enclose its relative path in quotes.

Example: 

#include <perlin>
#include "my-utilities.shadron"

#extension

The #extension directive, followed by the name of the extension, enables the selected Shadron extension for the remainder of the script. It must be installed in the extensions directory.

Example: 

#extension ffmpeg

Alternatively, the #ifextension directive can be used (with a matching #endif), to only enable the extension if it is installed. The extension-related code is then placed within that conditional block.

To invoke the GLSL extension directive instead, you can still wrap it in a GLSL block: 

glsl {
#extension GL_EXT_gpu_shader4 : enable
}

#define

The define directive also works similarly to how it works in C/C++ and it allows you to define macros, even with arguments. Shadron's preprocessor will expand these in GLSL code, and therefore OpenGL will have no knowledge of their existence.

You may also undefine them using the #undef directive.

Example: 

#define TAU 6.283185307179586476925286766559
#define SQR(x) ((x)*(x))

#if

The conditional directives #if, #ifdef, #ifndef, #elif, #else, and #endif serve to disable certain sections of the script depending on the specified conditions. Their usage is the same as in C/C++.

Example: 

#ifdef USE_LIGHTING_HIGH_QUALITY
    color = lightingHQ(material, normal);
#elif defined USE_LIGHTING
    color = lightingLQ(material, normal);
#else
    color = material.diffuseColor;
#endif

#error

The #error directive, followed by an error string, can be used to explicitly throw an error when the script is loaded. It's usage is only meaningful within a conditional directive.

Example: 

#if !defined(SHADRON_VERSION) || SHADRON_VERSION < 112
#error This script requires Shadron 1.1.2 or later
#endif

#pragma

The pragma directive can be followed by a non-standard directive, and if it isn't recognized, it is ignored. The recognized pragma directives are:

  • #pragma appendix – This directive means that the script should not be loaded by itself, but instead appended to the one loaded previously. This is used for parameter configuration files.
  • #pragma timing(mode, frequency) – Sets the global timing mode of the script, which determines when each update will be performed when viewing the animated content. This has no effect on exports. mode can be either adaptive (the default) or fixed. If the mode is set to fixed, a second argument, frequency must be provided, which is the fixed update frequency (frames per seconds). If rendering is delayed for any reason, the reported time will not match real time in fixed mode, but shadron_DeltaTime is guaranteed to be constant. May only be set once at the beginning of the script.
  • #pragma main_image(name) – Designates the main image output of the script by its name, to be displayed by the Shadron Player. If not set, the one defined last (without the hidden flag) will be used.
  • #pragma hint(hint1, hint2, ...) – Sets a hint or several hints (see below) for the entire remainder of the script.
  • #pragma push_hint(hint1, hint2, ...) – Pushes a hint or several hints (see below) on the stack. They will remain valid until the matching pop_hint directive.
  • #pragma pop_hint() – Removes hint(s) from the top of the stack. Undoes the last push_hint directive still in effect.

Hints

The following keywords can be used as arguments for the hint and push_hint directives:

  • black_background – sets the initial transparent background color to black
  • white_background – sets the initial transparent background color to white
  • background_grid – causes the checkerboard background grid to be displayed by default
  • background_no_grid – does not display the checkerboard background grid by default
  • alpha_ignored – makes the default appearance of images ignore the alpha channel
  • alpha_honored – does not make the default appearance of images ignore the alpha channel
  • persistent_var – makes state variables persistent (this is the default)
  • transient_var – causes state variables to be reset in the initial animation step