cubemap

The cubemap object represents a cube map – an environment map encoded by images on the six faces of a cube. This is typically used for reflection mapping or as the background of a 3D scene (skybox). The cubemap can be made animated by combining with the animation keyword. In the object's window, the environment map surrounds the point of view, which can be rotated with the mouse when holding the left button, and zoomed using the scroll wheel. Hold shift to drag-and-drop the output file instead.

The syntax can be one of: 

cubemap <name> = <initializer>;
cubemap <name> = <initializer> : <modifier1, modifier2, ...>;
cubemap animation <name> = <initializer>;
cubemap animation <name> = <initializer> : <modifier1, modifier2, ...>;

The available modifiers and initializers are listed below.

Every cubemap object is accessible as an OpenGL cubemap texture sampler with the same name in all GLSL functions that follow it. You can sample the color in a given direction in 3D space using a direction vector like this: 

glsl vec4 sampleMyCubemap(vec3 direction) {
    vec4 sample = texture(MyCubemap, direction);
    return sample;
}

Modifiers

You can specify any subset of the following 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×)
  • hidden(<true / false>) – do not create a window for the cubemap and only use it as an intermediate output
  • full_range(<true / false>) – if enabled, the 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 cubemap'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
  • repeat(<true / false>) – (cubemap animation only) specifies whether to repeat the animation or stop at the last frame

input initializer

Initializes the cubemap 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.

The input image must be a cube net, exactly 4N×3N pixels, where N is the side of the cubemap. The default configuration is a left-facing cross, same as the cubemap output, but if the empty parts of the image are perfectly uniform, a different configuration can be detected. This detection almost surely won't work with JPEG images.

Example: 

cubemap InputCubemap = input();

file initializer

Initializes the cubemap 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. After that, another image file can be dragged-and-dropped into its window, or a bitmap pasted from clipboard using Ctrl+V. The image file is restricted by the same condition as with the input initializer.

Example: 

cubemap InputCubemap = file("cubemap.png");

glsl initializer

Initializes the cubemap 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 vec3 parameter, which will receive the normalized direction vector in 3D space. The Y axis points upwards. In case of cubemap animation, it can have a second float parameter, the current time. 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 cubemap resolution – the length of its side in whole pixels.

Example: 

cubemap MyCubemap = glsl(environmentColor, 1024);

base64 initializer

Initializes the cubemap 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. The image file is restricted by the same condition as with the input initializer.

Example: 

cubemap ColorCube = base64(
    "iVBORw0KGgoAAAANSUhEUgAAAAQAAAADCAYAAAC09K7GAAAAIElEQVQImT3K"
    "sQ0AMBCEMN/+Q5PmFUoLILlGiYydpn886JcI+9t7+nkAAAAASUVORK5CYII="
);