GLSL TOP

From TouchDesigner 099 Wiki

Summary

The GLSL TOP renders a GLSL shader into a TOP image. Use the Info DAT to check for compile errors in your shaders.

The GLSL TOP can act as a pixel shader, or the more general and complex Compute Shader. Caveat: Compute Shaders need GLSL 4.30 or later.

Refer to the Write a GLSL TOP article for more info on using this TOP.

The GLSL TOP has one docked compute shader as well as a normal GLSL shader. Change he Mode to Compute Shader. it will use the glsl1_compute DAT.

See the GLSL Category for more information, and Compute Shader.

PythonIcon.png glslTOP_Class

Parameters - GLSL Page

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

Mode mode - Choose what type of shader you are writing, vertex/pixel shader, or a compute shader.

Vertex Shader vertexdat - Points to the DAT holding the Vertex Shader. Drag & Drop a DAT here, or manually enter the path to the DAT.

Pixel Shader pixeldat - Points to the DAT holding the Pixel Shader. Drag & Drop a DAT here, or manually enter the path to the DAT.

Compute Shader computedat - Points to the DAT holding the Compute Shader. Drag & Drop a DAT here, or manually enter the path to the DAT.

Dispatch Size dispatchsize - Controls the dispatch size (the number of groups in the X, Y and Z dimensions). This is essentially the arguments to the OpenGL command glDispatchCompute().

Output Access outputaccess - Controls how the output textures will be accessed. If the textures will be read from (such as using previous frame's values), then the access should be changed to Read-Write instead of Write Only.

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. Turn up this value to have more color buffers allocated for you, and refer to Write a GLSL TOP for more information on using this feature.

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-uniname9 - The uniform name, as declared in the shader.

Value value0[xyzw]-value9[xyzw] - The value(s) to give the uniform.

Parameters - Vectors 2 Page

More uniforms, same as Vector 1 page.

Name uniname10-uniname19

Value value10[xyzw]-value19[xyzw]

Parameters - Vectors 3 Page

More uniforms, same as Vector 1 page.

Name uniname20-uniname29

Value value20[xyzw]-value29[xyzw]

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 chopuniname0-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-chop9 - The channels from this CHOP will be sent to the GLSL shader.

Array Type choparraytype0-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.

Declare them:

 uniform samplerBuffer <uniformname>;

And sample them like this

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

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

Parameters - Matrices Page

Uniform Name matuniname0-matuniname9 - The name of the matrix uniform. Should always be a mat4 currently.

Matrix matvalue0-matvalue9 - The value to assign the matrix. For valid ways to specify this, see the Matrix Parameters article.

Parameters - Atomic Counters Page

Size acsize0-acsize3 - The size allocated for the atomic counter. The size corresponds to the number of atomic counters allowed in that binding, not the size of the allowed offset. Because atomic counters are 4 bytes each it means that the offset in the shader code will be able to be 4 times as large as the number in the size parameter. So, the offset in the code for that binding cannot be larger than (4 * Size) - 4

Binding acbinding0-acbinding3 - The binding location of the counter. This value must be equal to the binding value specified in the shader for the desired atomic counter.

Initial Value Type acinitval0-acinitval3 - Specifies how the atomic counters receive their initial value, either through a single default value or a CHOP.

Initial Value acsingleval0-acsingleval3 - Specifies a single value that all atomic counters in this binding will be initialized to.

Initial Values CHOP acchopval0-acchopval3 - A reference to the CHOP that will determine the initial values of the atomic counters in this binding. The CHOP will be spanned in track order, so the values from the first track will be read in order first, then the next track (if there is one) and so on. If there are more initial values to fill than there are values in the CHOP then they will all be set to 0. Atomic counters will be initialized from low to high offsets.

Parameters - Common Page

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

  • Use Input - uses the input's resolution.
  • Eighth, Quarter, Half, 2X, 4X, 8X - multiply the input's resolution by that amount.
  • Fit Resolution - Resizes the input to the size specified in Resolution using the best possible match that does not crop any of the input. It will resize the image to be larger than the input resolution if a larger resolution is specified. It's a "fit inside", Aspect Ratio is maintained.
  • Limit Resolution - Limits the input to the size specified in Resolution using the best possible match that does not crop any of the input. It will NOT resize the image to be larger than the input resolution if a larger resolution is specified. It's a "fit inside", Aspect Ratio is maintained.
  • Custom Resolution - enables the Resolution parameter below, giving direct control over width and height.

Resolution - 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 Res 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.

Output Aspect - 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. (You can define images with non-square pixels using xres, yres, aspectx, aspecty where xres/yres != aspectx/aspecty.)

  • 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 - lets you explicitly define a custom aspect ratio in the Aspect parameter below.

Aspect - Use when Output Aspect parameter is set to Custom Aspect.

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 Outside - 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). 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.
  • sRGB 8-bit fixed (RGBA) - uses 8-bit integer values for each channel and stores color in sRGB colorspace.
  • 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 (Mono) - Single channel, where RGB will all have the same value, and Alpha will be 1.0. 8-bits per pixel.
  • 16-bit fixed (Mono) - Single channel, where RGB will all have the same value, and Alpha will be 1.0. 16-bits per pixel.
  • 16-bit float (Mono) - Single channel, where RGB will all have the same value, and Alpha will be 1.0. 16-bits per pixel.
  • 32-bit float (Mono) - Single channel, where RGB will all have the same value, and Alpha will be 1.0. 32-bits per pixel.
  • 8-bit fixed (RG) - A 2 channel format, R and G have values, while B is 0 always and Alpha is 1.0. 8-bits per channel, 16-bits total per pixel.
  • 16-bit fixed (RG) - A 2 channel format, R and G have values, while B is 0 always and Alpha is 1.0. 16-bits per channel, 32-bits total per pixel.
  • 16-bit float (RG) - A 2 channel format, R and G have values, while B is 0 always and Alpha is 1.0. 16-bits per channel, 32-bits total per pixel.
  • 32-bit float (RG) - A 2 channel format, R and G have values, while B is 0 always and Alpha is 1.0. 32-bits per channel, 64-bits total per pixel.
  • 8-bit fixed (A) - An Alpha only format that has 8-bits per channel, 8-bits per pixel.
  • 16-bit fixed (A) - An Alpha only format that has 16-bits per channel, 16-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.
  • 8-bit fixed (Mono+Alpha) - A 2 channel format, one value for RGB and one value for Alpha. 8-bits per channel, 16-bits per pixel.
  • 16-bit fixed (Mono+Alpha) - A 2 channel format, one value for RGB and one value for Alpha. 16-bits per channel, 32-bits per pixel.
  • 16-bit float (Mono+Alpha) - A 2 channel format, one value for RGB and one value for Alpha. 16-bits per channel, 32-bits per pixel.
  • 32-bit float (Mono+Alpha) - A 2 channel format, one value for RGB and one value for Alpha. 32-bits per channel, 64-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