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 – 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. The supported versions are 110 through 450, with 130 (OpenGL 3.0) being the default.

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

To invoke the GLSL extension directive instead, you can still wrap it as 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, but other related directives, such as #ifdef, are not currently available.

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, FREQ) – 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, FREQ 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.