image

The image section represents an image that can be sampled in GLSL functions or serve as the output. It is displayed in its own window by default.

Its syntax can be one of:

image <name> = <initializer>;
image <name> = <initializer> : <modifier1, modifier2, ...>;

The available modifiers and initializers are listed below. Additional initializers may be available via extensions.

Every image object is accessible as a 2D texture sampler with the same name in all GLSL functions that follow it. You can sample it like this:

glsl vec4 sampleMyImage(vec2 position) {
    vec4 sample = texture(MyImage, position);
    return sample;
}

Modifiers

You can specify any subset of the following image modifiers:

  • filter(<filter mode>) – specifies the texture filtering mode for GLSL. The possible values are:
    • none / nearest – nearest neighbor resampling / no filtering
    • linear – linear filtering, no mipmaps (default)
    • bilinear – linear filtering with discrete mipmap steps
    • trilinear – linear filtering with linear mipmap transitions
    • anisotropic / anisotropicN – anisotropic filtering (N×)
  • map(<X mapping>, <Y mapping>) – specifies the texture mapping / wrapping. You can also supply only one argument to be used for both dimensions. The possible values are:
    • clamp – clamps the texture coordinate to <0, 1>
    • repeat / wrap – repeats the texture outside its bounds (default)
    • mirror – repeats the texture but every other repetition is mirrored
    • clamp_to_border – uses a fixed border color out of bounds. The border color can be set in an additional parameter (as a vec4 value)
  • hidden(<true / false>) – do not create a window for the image and only use it as an intermediate output
  • resizable(<true / false>) – make the window resizable and the image dynamically adapt to its size
  • full_range(<true / false>) – if enabled, the image pixels will be stored in floating point format without clamping, allowing other shaders to sample the exact computed value at each pixel, but sacrificing some performance
  • heavy_mode(<true / false>) – this option is required for computationally intensive shaders, where rendering time may exceed 1 second. Without it, there is a risk of GPU driver crash

input initializer

Initializes the image as a blank input. An image file can then be dragged-and-dropped into its window, or a bitmap can be pasted from clipboard using Ctrl+V.

Example:

image MyInput = input() : map(clamp);

file initializer

Initializes the image as a file input. A file name can be supplied as an argument, which will be loaded. Otherwise, it is equivalent to input. The supported formats are BMP, PNG, TGA, TIFF, JPEG, and GIF. After that, another image file can be dragged-and-dropped into its window, or a bitmap pasted from clipboard using Ctrl+V.

Example:

image MyInput = file("my-input.png");

glsl initializer

Initializes the image as a GLSL shader output.

Its first argument is a GLSL function that will be evaluated at each pixel. This function must have one input vec2 parameter, where the position of the pixel between (0, 0) – lower left corner and (1, 1) – upper right corner, will be passed, or no parameters at all, if it uses some other method of determining position (such as gl_FragCoord). Its return value must be one of vec4, vec3, float, or vec2, for an RGBA, RGB, luminance, or luminance/alpha output, respectively.

The second argument specifies the dimensions of the image. You may as well pass the width and height separately as two arguments. Use sizeof(SomeImage) to make the image the same size as another.

Example:

image MyOutput = glsl(transformImage, sizeof(MyInput));

text initializer

Initializes the image with a rendered text. The arguments are the text (in UTF-8 encoding), name of font, font style (regular / bold / italic / bold_italic), text size, text align (left / center / right), and the dimensions of the image.

Example:

image MyText = text("Hello World", "Arial", regular, 64, center, ivec2(384, 64));