GLSL TOP

Summary

The GLSL TOP renders a GLSL shader into a TOP image. Use the Info DAT to check for compile errors in your shaders. Refer to the Write a GLSL TOP article for more info on using this TOP.

Parameters - GLSL Page

GLSL Version /glslversion - pick what version of GLSL to compile the shader with.

Vertex Shader /vdat - points to the DAT holding the Vertex Shader. Drag & Drop a DAT here, or manually enter the path to the DAT.

Pixel Shader /pdat - points to the DAT holding the Pixel Shader. Drag & Drop a DAT here, or manually enter the path to the DAT.

Output Type /type - Specify what type of texture to create. When creating a 3D texture the TOP will render once for every slice of the output. Refer to 3D Textures and 2D Texture Arrays for more info.

• 2D Texture - creates a 2D texture.
• 2D Texture Array - creates a 2D Texture Array. Slices of the array can be access using a non-normalized integer index for the w coordinate.
• 3D Texture - creates a 3D Texture. Slices of the array can be accessed using the w coordinate in the range 0-1. Value of the texture in between slices are interpolated.

Depth /depth - Set the depth of the 3D texture from the Input or the Custom Depth parameter.

Custom Depth /customdepth - Manually set the depth of the 3D texture, otherwise it will use the depth of the input.

Input Mapping /inputmapping - Determines how the node's input(s) are passed into the shader for use when creating a 3D Texture. By default all of the inputs are passed to each slice. When using the N inputs per Slice mode, the first N inputs are passed to the first slice, the next N inputs are passed the second slice, and so on. When it runs out of inputs it loops back to the first input. N is selected by the parameter N Value.

N Value /nval - Determines how many inputs are passed to the shader per slice when using the N inputs per Slice mode for Input Mapping. If for example this is set to 2, then the first 2 inputs will be passed to the first slice, the next 2 inputs will be passed the second slice, and so on. It will loop back to the start of the inputs if it runs out before it reaches the last slice.

Input Extend Mode UV /inputextenduv - Controls what is returned from your texture sampling functions when the U and V texture coordinates (called S and T in the shader) are outside [0-1] range.

Input Extend Mode W /inputextendw - Controls what is returned from your texture sampling functions when the W texture coordinate (called W in the shader) are outside [0-1] range. Only useful for [[3D Textures].

# of Color Buffers /numcolorbufs - Any shader you write can output to more than one RGBA buffer at a time. Instead of writting to gl_FragColor in your shader, you write to gl_FragData[i] where i is the color buffer index you want to write the value to. You can use a Render Select TOP to view the contents of the other outputted buffers. You need to add this line to your shader to use multiple color buffer output.

 #extension GL_ARB_draw_buffers : enable

Parameters - Vectors 1 Page

This are passed as uniforms into your shader. Depending on how the uniform is declared only some of the values of the 4 available per parameter as passes to the shader. For example, if the uniform is declared as a vec2, then only the first 2 values are passed to the shader, the other 2 are ignored.

Name /uniname0 (up to uniname9) - The uniform name, as declared in the shader.

Value val0v (up to val9v) - The value(s) to give the uniform.

Parameters - Vectors 2 Page

More uniforms, same as Vector 1 page.

Name /uniname10 (up to uniname19)

Value /val10v (up to val19v)

Parameters - Arrays 1 & Arrays 2 Page

CHOP Uniforms allow you to send CHOP channel data into a GLSL shader as an array. Depending on the array type used, the number of values you can send into the shader may be limited. If you are using Uniform Arrays, you can use the Built-In variable $SYS_GFX_GLSL_MAX_UNIFORMS to get an idea of how many values you can pass to the shader. Current GPUs are vec4 based for uniform arrays, so the maximum array size is $SYS_GFX_GLSL_MAX_UNIFORMS / 4. Other uniforms will take away from this maximum. If you are using Texture Buffers the maximum array size is far bigger, $SYS_GFX_MAX_TEXTURE_BUFFER_SIZE will tell you the max for this. The max for texture buffer is per texture buffer, and having multiple texture buffers does not take away from the max for each array.

Uniform Name /unichopname0 (up to chopuniname9) - The name of the uniform. You can send up to 4 channels into the GLSL shader in a single uniform. The number of channels is determined by the float/vec2/vec3/vec4 menu to the right of the name. For a CHOP with a single channel declare your uniform as a float, for one with two channels declare your uniform as a vec2, etc. The data is interleaved in the uniform. I.e the .x component is the 1st channel, .y is the 2nd channel, etc.

CHOP /chop0 (up to chop9) - The channels from this CHOP will be sent to the GLSL shader.

Array Type /choparraytype0 (up to chopunitype9) - The type of the uniform.

• Uniform Array - All GPUs can send array data into a GLSL shader using Uniform Arrays.
• Texture Buffer - Newer GPUs can send array data into a GLSL shader using Texture Buffers. Texture Buffers use texture memory and texture fetches to access the data, which allows them to store many more values. To use them you'll need to enable the GLSL extension that supports them.

 #extension GL_EXT_gpu_shader4 : enable

Declare them differently:

 uniform samplerBuffer <uniformname>;

And sample them like this

 vec4 val = texelFetchBuffer(<uniformname>, i);

Where i is the 0-based index (an integer) into the buffer that you want to get a value for.

Parameters - Common Page

Resolution - quickly change the resolution of the TOP's data.

• Input - uses the input's resolution.
• Eighth, Quarter, Half, 2X, 4X, 8X - multiply the input's resolution by that amount.
• Custom Resolution - enables the Custom Res parameter below, giving direct control over res in the X and Y axis.

Custom Res - enabled only when the Resolution parameter is set to Custom Resolution. Some Generators like Constant and Ramp do not use inputs and only use this field to determine their size. The drop down menu on the right provides some commonly used resolutions.

Use Global Resolution Multiplier - Uses the Global Resolution Multiplier found in Edit>Preferences>TOPs. This multiplies all the TOPs resolutions by the set amount. This is handy when working on computers with different hardware specifications. If a project is designed on a desktop workstation with lots of graphics memory, a user on a laptop with only 64MB VRAM can set the Global Resolution Multiplier to a value of half or quarter so it runs at an acceptable speed. By checking this checkbox on, this TOP is affected by the global multiplier.

Aspect Ratio - sets the image aspect ratio allowing any textures to be viewed in any size. Watch for unexpected results when compositing TOPs with different aspect ratios.

• Input - uses the input's aspect ratio.
• Resolution - uses the aspect of the image's defined resolution (ie 512x256 would be 2:1), whereby each pixel is square.
• Custom Aspect Ratio - lets you explicitly define a custom aspect ratio.

Input Smoothness - This controls pixel filtering on the input image of the TOP.

• Nearest Pixel - uses nearest pixel or accurate image representation. Images will look jaggy when viewing at any zoom level other than Native Resolution.
• Interpolate Pixels - uses linear filtering between pixels. This is how you get TOP images in viewers to look good at various zoom levels, especially useful when using any Fill Viewer setting other than Native Resolution.
• Mipmap Pixels - uses mipmap filtering when scaling images. This can be used to reduce artifacts and sparkling in moving/scaling images that have lots of detail.

Fill Viewer - determine how the TOP image is displayed in the viewer.

• Input - uses the same Fill Viewer settings as it's input.
• Fill - stretches the image to fit the edges of the viewer.
• Fit Horizontal - stretches image to fit viewer horizontally.
• Fit Vertical - stretches image to fit viewer vertically.
• Fit Best - stretches or squashes image so no part of image is cropped.
• Fit Worst - stretches or squashes image so image fills viewer while constraining it's proportions. This often leads to part of image getting cropped by viewer.
• Native Resolution - displays the native resolution of the image in the viewer.

NOTE: To get an understanding of how TOPs works with images, you will want to set this to Native Resolution as you lay down TOPs when starting out. This will let you see what is actually happening without any automatic viewer resizing.

Viewer Smoothness - This controls pixel filtering in the viewers.

• Nearest Pixel - uses nearest pixel or accurate image representation. Images will look jaggy when viewing at any zoom level other than Native Resolution.
• Interpolate Pixels - uses linear filtering between pixels. Use this to get TOP images in viewers to look good at various zoom levels, especially useful when using any Fill Viewer setting other than Native Resolution.
• Mipmap Pixels - uses mipmap filtering when scaling images. This can be used to reduce artifacts and sparkling in moving/scaling images that have lots of detail. When the input is 32-bit float format, only nearest filtering will be used (regardless of what is selected).

Passes - duplicates the operation of the TOP the specified number of times.

Channel Mask - Allows you to choose which channels (R, G, B, or A) the TOP will operate on. All channels are selected by default.

Pixel Format - format used to store data for each channel in the image (ie. R, G, B, and A). Fixed format values are limited to the range [0-1]. Refer to Pixel Formats for more information.

• Input - uses the input's pixel format.
• 8-bit fixed (RGBA) - uses 8-bit integer values for each channel.
• 16-bit float (RGBA) - uses 16-bits per color channel, 64-bits per pixel.
• 32-bit float (RGBA) - uses 32-bits per color channel, 128-bits per pixels.

• 10-bit RGB, 2-bit Alpha, fixed (RGBA) - uses 10-bits per color channel and 2-bits for alpha, 32-bits total per pixel.
• 16-bit fixed (RGBA) - uses 16-bits per color channel, 64-bits total per pixel.
• 11-bit float (RGB), Positive Values Only - A RGB floating point format that has 11 bits for the Red and Green channels, and 10-bits for the Blue Channel, 32-bits total per pixel (therefore the same memory usage as 8-bit RGBA). The Alpha channel in this format will always be 1. Values can go above one, but can't be negative. ie. the range is [0, infinite).
• 8-bit fixed (R) - has 8-bits for the red channel, 8-bits total per pixel.
• 16-bit fixed (R) - has 16-bits for the red channel, 16-bits total per pixel.
• 16-bit float (R) - has 16-bits for the red channel, 16-bits per pixel.
• 32-bit float (R) - has 32-bits for the red channel, 32-bits per pixel.
• 8-bit fixed (RG) - has 8-bits for the red and green channels, 16-bits total per pixel.
• 16-bit fixed (RG) - has 16-bits for the red and green channels, 32-bits total per pixel.
• 16-bit float (RG) - has 16-bits for the red and green channels, 32-bits per pixel.
• 32-bit float (RG) - has 32-bits for the red and green channels, 64-bits per pixel.
• 8-bit fixed (A) - An Alpha only format that has 8-bits per channel, 8-bits per pixel.
• 16-bit float (A) - An Alpha only format that has 16-bits per channel, 16-bits per pixel.
• 32-bit float (A) - An Alpha only format that has 32-bits per channel, 32-bits per pixel.

Examples

This example shows some basic of using the GLSL TOP and GLSL coding.

Media:GLSL_TOP_Basic.tox

This example shows how to use uniforms

Media:GLSL_TOP_Using_Uniforms.tox

This example shows how to use 3D, 2D array textures, as well as multiple color buffer output.

Media:GLSL_TOP_3D_Textures.tox