View source for Tessellation Control Shader

{{stack|
{{infobox feature
| core = 4.0
| core_extension = {{extref|tessellation_shader}}
}}
|{{pipeline float}}
}}

The '''Tessellation Control Shader''' (TCS) is a [[Shader]] program written in [[GLSL]]. It sits between the [[Vertex Shader]] and the [[Tessellation Evaluation Shader]].

The TCS controls how much tessellation a particular patch gets; it also defines the size of a patch, thus allowing it to augment data. It can also filter vertex data taken from the vertex shader. The main purpose of the TCS is to feed the tessellation levels to the [[Tessellation#Tessellation primitive generator|Tessellation primitive generator stage]], as well as to feed patch data (as its output values) to the [[Tessellation Evaluation Shader]] stage.

== Execution model ==

The TCS execution model is different from most other shader stages; it is most similar to [[Compute Shader]]s. Unlike [[Geometry Shader]]s, where each invocation can output multiple primitives, each TCS invocation is only responsible for producing a single vertex of output to the output patch.

For each [[Patch Primitive|patch provided during rendering]], {{param|n}} TCS shader invocations will be processed, where {{param|n}} is the number of vertices in the output patch. So if a drawing command draws 20 patches, and each output patch has 4 vertices, there will be a total of 80 separate TCS invocations.

The different invocations that provide data to the same patch are interconnected. These invocations all ''share'' their output values. They can read output values that other invocations for the same patch have written to. But in order to do so, they must use a [[#Synchronization|synchronization]] mechanism to ensure that all other invocations for the patch have executed at least that far.

Because of this, it is possible for TCS invocations to share data and communicate with one another.

=== Output patch size ===

The output patch size is the number of vertices in the output patch. It also determines the number of TCS invocations used to compute this patch data. The output patch size does not have to match the input patch size.

The number of vertices in the output patch is defined with an output layout qualifier:

 layout(vertices = {{param|patch_size}}) out;

{{param|patch_size}} must be an integral constant expression greater than zero and less than the patch limit ([[#Limitations|see below]]).

== Inputs ==

All inputs from vertex shaders to the TCS are aggregated into arrays, based on the size of the input patch. The size of these arrays is the number of input patches provided by the patch primitive.

Every TCS invocation for an input patch has access to the same input data, save for {{code|gl_InvocationID}} (see below) which will be different for each invocation. So any TCS invocation can look at the input vertex data for the entire input patch.

User-defined inputs can be declared as unbounded arrays:

<source lang="glsl">
in vec2 texCoord[];
</source>

You should not attempt to index this array past the number of input patch vertices.

TCS inputs may have [[Interpolation qualifiers|interpolation qualifiers]] on them. They have no actual function however.
{{snippet|:Tessellation Control Shader/Defined Inputs}}

== Outputs ==

TCS output variables are passed directly to the [[Tessellation Evaluation Shader]], without any form of interpolation (that's the TES's main job). These can be per-vertex outputs and per-patch outputs.

Per-vertex outputs are aggregated into arrays. Therefore, a user-defined per-vertex output variable would be defined as such:

<source lang="cpp">
out vec2 vertexTexCoord[];
</source>

The length of the array ({{code|vertexTexCoord.length()}} will always be the size of the output patch. So you don't need to restate it in the definition.

A TCS can ''only ever'' write to the per-vertex output variable that corresponds to their invocation. So writes to per-vertex outputs must be of the form {{code|vertexTexCoord[gl_InvocationID]}}. Any expression that writes to a per-vertex output that doesn't index it with exactly "{{code|gl_InvocationID}}" results in a compile-time error. Silly things like {{code|vertexTexCoord[gl_InvocationID - 1 + 1]}} will also error.

=== Patch variables ===

Per-patch output variables are not aggregated into arrays (unless you want them to be, in which case you must specify a size). All TCS invocations for this patch see the same patch variables. They are declared with the {{code|patch}} keyword:

<source lang="glsl">
patch out vec4 data;
</source>

Any TCS invocation can write to a per-patch output; indeed, ''all'' TCS invocations will generally write to a per-patch output. As long as they all write the same value, everything is fine.

=== Built-in outputs ===

{{snippet|:Tessellation Control Shader/Defined Outputs}}

=== Synchronization ===

TCS invocations that operate on the same patch can read each others output variables, whether per-patch or per-vertex. To do so, they must first ensure that those invocations have actually ''written'' to those variables. The value of all output variables is undefined initially.

Ensuring that invocations have written to a variable requires synchronization between invocations. This is done via the {{code|barrier()}} function. When executed, it will not complete until all other TCS invocations for this patch have reached that barrier. This means that all writes have occurred by this point. However, ''subsequent'' writes to those variables may have occurred, so if you want to read those variables, make sure that another {{code|barrier()}} is issued before writing more to them. If there are no subsequent writes to those variables, then this should be fine.

The {{code|barrier()}} function has significant restrictions on where it can be placed. It must be placed:

* ''Directly'' in the {{code|main()}} function. It cannot be in any other functions or subroutines.
* Outside of ''any'' flow control. This includes {{code|if}}, {{code|for}}, {{code|switch}}, and the like.
* Before any use of {{code|return}}, even a conditional one.

This ensures that every TCS invocation hits the same sequence of {{code|barrier()}} calls in the same order every time. The compiler will error if any of these restrictions are violated.

{{note|This is different from the restrictions on {{code|barrier()}} in [[Compute Shader]]s. Also, writes to TCS output variables do not use the rules for [[Incoherent Memory Access]], so they do not need those memory barrier calls.}}

== Limitations ==

There is a maximum output patch size, defined by {{enum|GL_MAX_PATCH_VERTICES}}; the {{code|vertices}} output qualifier must be less than this value. The minimum required limit is 32.

There are other limitations on output size, however. The number of components for active per-vertex output variables may not exceed {{enum|GL_MAX_TESS_CONTROL_OUTPUT_COMPONENTS}}. The minimum required limit is 128.

The number of components for active per-patch output variables may not exceed {{enum|GL_MAX_TESS_PATCH_COMPONENTS}}. The minimum required limit is 120. Note that the {{code|gl_TessLevelOuter}} and {{code|gl_TessLevelInner}} outputs do not count against this limit (but other built-in outputs do if you use them.

There is a limit on the total number of components that can go into an output patch. To compute the total number of components, multiply the number of active per-vertex components by the number of output vertices, then add the number of active per-patch components. This number may not exceed {{enum|GL_MAX_TESS_CONTROL_TOTAL_OUTPUT_COMPONENTS}}. The minimum required limit is 4096, which is not quite enough to use a 32-vertex patch with 128 per-vertex components and 120 per-patch components. But it's still a lot.

== See also ==

* [[Tessellation Evaluation Shader]]
* [http://voxels.blogspot.com/2011/09/tesselation-shader-tutorial-with-source.html OpenGL 4 Tessellation Shader Tutorial]: A simple OpenGL tutorial with source code for using Tessellation Shaders. Based on VC++ 2010.

[[Category:OpenGL Shading Language]]
[[Category:Vertex Processing]]
[[Category:Shaders]]