image

The image object represents a static image that can be sampled as a 2D texture or serve as the output. Use animation instead for animated images.

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: 

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

Modifiers

You can specify any subset of the following image modifiers:

  • filter(<filter mode>) – specifies the texture filtering mode. 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 as an additional argument (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
  • srgb(<true / false>) – changes the image's color space to sRGB. Sampling an sRGB image will yield a color converted to the linear color space. Additionally, for generated images, the shader's output color must also be in the linear color space. Mixing sRGB and non-sRGB images will produce erroneous results unless handled carefully
  • 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. Support of additional formats may be enabled through extensions. At any point, 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(reprocessImage, 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));

base64 initializer

Initializes the image using a Base64-encoded image file. The first and only argument is a string in Base64 format. All file formats accepted by the file initializer are supported.

Example: 

image DitherMatrix = base64(
    "iVBORw0KGgoAAAANSUhEUgAAAAQAAAAECAYAAACp8Z5+AAAANElEQVQImWP48OHD/4KCgv8XLl"
    "z4HxAQ8J/JwcGBARkzHDhw4L+Dg8P/Bw8e/E9ISMBUAQBhQBw95eaC5QAAAABJRU5ErkJggg=="
);