View source for Geometry Shader

{{stack|
{{infobox feature
| core = 3.2
| arb_extension = ARB_geometry_shader4 <!-- This is intentionally left unlinked due to the differences between it and the core feature -->
}}
|{{pipeline float}}
}}

A '''Geometry Shader''' (GS) is a [[Shader]] program written in [[GLSL]] that governs the processing of [[Primitive]]s. Geometry shaders reside between the [[Vertex Shader]]s (or the optional [[Tessellation]] stage) and the fixed-function [[Vertex Post-Processing]] stage.

A geometry shader is optional and does not have to be used.

Geometry shader invocations take a single [[Primitive]] as input and may output zero or more primitives. There are implementation-defined limits on how many primitives can be generated from a single GS invocation. GS's are written to accept a specific input primitive type and to output a specific primitive type.

While the GS can be used to amplify geometry, thus implementing a crude form of tessellation, this is generally not a good use of a GS. The main reasons to use a GS are:

* Layered rendering: taking one primitive and rendering it to multiple images without having to change bound rendertargets and so forth.
* [[Transform Feedback]]: This is often employed for doing computational tasks on the GPU (obviously pre-[[Compute Shader]]).

In OpenGL 4.0, GS's gained two new features. One was the ability to write to multiple output streams. This is used exclusively with transform feedback, such that different feedback buffer sets can get different transform feedback data.

The other feature was GS instancing, which allows multiple invocations to operate over the same input primitive. This makes layered rendering easier to implement and possibly faster performing, as each layer's primitive(s) can be computed by a separate GS instance.

{{note|While geometry shaders have had previous extensions like GL_EXT_geometry_shader4 and GL_ARB_geometry_shader4, these extensions expose the API and GLSL functionality in ''very'' different ways from the core feature. This page describes only the core feature.}}

== Primitive in/out specification ==

Each geometry shader is designed to accept a specific [[Primitive]] type as input and to output a specific primitive type. The accepted input primitive type is defined in the shader:

 layout({{param|input_primitive}}) in;

The {{param|input_primitive}} type ''must'' match the primitive type for the vertex stream provided to the GS. If [[Tessellation]] is enabled, then the primitive type is specified by the [[Tessellation Evaluation Shader]]'s output qualifiers. If Tessellation is not enabled, then the primitive type is provided by the [[Vertex Rendering|drawing command]] that renders with this shader program. The valid values for {{param|input_primitive}}, along with the valid OpenGL [[Primitive|primitive types]] or tessellation forms, are:

{| class="wikitable"
! GS input
! OpenGL primitives
! [[Tessellation_Evaluation_Shader#Tessellation_options|TES parameter]]
! vertex count
|-
| {{code|points}}
| {{enum|GL_POINTS}}
| {{code|point_mode}}
| 1
|-
| {{code|lines}}
| {{enum|GL_LINES}}, {{enum|GL_LINE_STRIP}}, {{enum|GL_LINE_LIST}}
| {{code|isolines}}
| 2
|-
| {{code|lines_adjacency}}
| {{enum|GL_LINES_ADJACENCY}}, {{enum|GL_LINE_STRIP_ADJACENCY}}
| N/A
| 4
|-
| {{code|triangles}}
| {{enum|GL_TRIANGLES}}, {{enum|GL_TRIANGLE_STRIP}}, {{enum|GL_TRIANGLE_FAN}}
| {{code|triangles}}, {{code|quads}}
| 3
|-
| {{code|triangles_adjacency}}
| {{enum|GL_TRIANGLES_ADJACENCY}}, {{enum|GL_TRIANGLE_STRIP_ADJACENCY}}
| N/A
| 6
|}

The vertex count is the number of vertices that the GS receives per-input primitive.

The output primitive type is defined as follows:

 layout({{param|output_primitive}}, max_vertices = {{param|vert_count}}) out;

The {{param|output_primitive}} must be one of the following:

* {{code|points}}
* {{code|line_strip}}
* {{code|triangle_strip}}

These work exactly the same way their counterpart OpenGL rendering modes do. To output individual triangles or lines, simply use {{code|EndPrimitive}} (see below) after emitting each set of 3 or 2 vertices.

There must be a {{code|max_vertices}} declaration for the output. The number must be a compile-time constant, and it defines the maximum number of vertices that will be written by a ''single'' invocation of the GS. It may be no larger than the implementation-defined limit of {{enum|MAX_GEOMETRY_OUTPUT_VERTICES}}. The minimum value for this limit is 256. See the limitations below.

=== Instancing ===
{{infobox feature
| name = GS Instancing
| core = 4.0
| core_extension = [http://www.opengl.org/registry/specs/ARB/gpu_shader5.txt ARB_gpu_shader5]
}}

The GS can also be instanced (this is separate from [[Instancing|instanced rendering]], as this is localized to the GS). This causes the GS to execute multiple times for the same input primitive. Each invocation of the GS for a particular input primitive will get a different {{code|gl_InvocationID}} value. This is useful for layered rendering and outputs to multiple streams (see below).

To use instancing, there must be an input [[Layout Qualifier (GLSL)|layout qualifier]]:

 layout(invocations = {{param|num_instances}}) in;

The value of {{param|num_instances}} must not be larger than {{enum|MAX_GEOMETRY_SHADER_INVOCATIONS}} (this will be at least 32). The built-in value {{code|gl_InvocationID}} specifies the particular instance of this shader; it will be on the half-open range [0, {{param|num_instances}}).

The output primitives from instances are ordered by the {{code|gl_InvocationID}}. So if the user renders two primitives, and has {{param|num_instances}} set to 3, then the GS will be effectively called in this order: (prim0, inst0), (prim0, inst1), (prim0, inst2), (prim1, inst0), ... The output primitives from the GS's will be ordered based on that input sequence. So if (prim0, inst0) outputs two triangles, they will both be rendered before rendering any triangles from (prim0, inst1).

== Inputs ==

Geometry shaders take a primitive as input; each primitive is composed of some number of vertices, as defined by the input primitive type in the shader.

The outputs of the vertex shader (or [[Tessellation]] Stage, as appropriate) are thus fed to the GS as ''arrays'' of variables. These can be organized as individual variables or as part of an [[Interface Block|interface block]]. Each individual variable will be an array of the length of the primitive's vertex count; for interface blocks, the block itself will be arrayed with this length. The order of vertices in the input arrays corresponds to the order of the vertices specified by prior shader stages.

Geometry shader inputs may have [[Interpolation qualifiers|interpolation qualifiers]] on them. If they do, then the prior stage's outputs must use the same qualifier.
{{snippet|:Geometry Shader/Defined Inputs}}

== Outputs ==

Geometry shaders can output as many vertices as they wish (up to the maximum specified by the {{code|max_vertices}} layout specification). To provide this, output values in geometry shaders are not arrays. Instead, a function-based interface is used.

GS code writes all of the output values for a vertex, then calls {{code|EmitVertex()}}. This tells the system to write those output values to where ever it is that output vertices get written. After calling this function, all output variables contain undefined values. So you will need to write to them all again before emitting the next vertex (if there is a next vertex).

{{note|You must write to ''each'' output variable before every {{code|EmitVertex()}} call (for all outputs [[#Output streams|for a stream]] for each {{code|EmitStreamVertex()}} call).}}

The GS defines what kind of primitive these vertex outputs represent. The GS can also end a primitive and start a new one, by calling the {{code|EndPrimitive()}} function. This does not emit a vertex.

In order to write two independent triangles from a GS, you must write three separate vertices with {{code|EmitVertex()}} for the first three vertices, then call {{code|EndPrimitive()}} to end the strip and start a new one. Then you write three more vertices with {{code|EmitVertex()}}.

Output variables are defined as normal for GLSL. They can be grouped into interface blocks or be single values, as appropriate. Output variables can be defined with [[Interpolation qualifiers|interpolation qualifiers]]. The [[Fragment Shader]] equivalent interface variables should define the same variables with the same qualifiers.
{{snippet|:Geometry Shader/Defined Outputs}}

=== Layered rendering ===

Layered rendering is the process of having the GS send specific primitives to different layers of a [[Layered Framebuffer|layered framebuffer]]. This can be useful for doing cube-based shadow mapping, or even for rendering cube environment maps without having to render the entire scene multiple times.
{{snippet|:Geometry Shader/Defined Outputs Layered}}

Layered rendering can be more efficient with GS instancing, as different GS invocations can process instances in parallel. However, while {{extref|viewport_array}} is often implemented in 3.3 hardware, no 3.3 hardware provides {{extref|gpu_shader5}} support.

{{warning|{{code|gl_Layer}} and {{code|gl_ViewportIndex}} are GS output variables. As such, every time you call {{code|EmitVertex}}, their values will become ''undefined''. Therefore, you must set these variables ''every time'' you loop over outputs.}}

If the geometry shader never writes to {{code|gl_ViewportIndex}}, then everything will behave as if 0 were written to it.

==== Which vertex ====

{{code|gl_Layer}} and {{code|gl_ViewportIndex}} are per-vertex parameters, but they specify a property that applies to the entire ''primitive''. Therefore, a question arises: which vertex in a particular primitive defines that primitive's layer and viewport index?

The answer is that it is implementation-dependent. However, OpenGL does have two queries to determine which one the current implementation uses: {{enum|GL_LAYER_PROVOKING_VERTEX}} and {{enum|GL_VIEWPORT_INDEX_PROVOKING_VERTEX}}.

The value returned from {{apifunc|glGet|Integerv}} will be one of the following enumerators:

* {{enum|GL_PROVOKING_VERTEX}}: The vertex used will track the current [[Provoking Vertex|provoking vertex convention]].
* {{enum|GL_LAST_VERTEX_CONVENTION}}: The vertex used will be the one defined by the last-vertex provoking vertex convention.
* {{enum|GL_FIRST_VERTEX_CONVENTION}}: The vertex used will be the one defined by the first-vertex provoking vertex convention.
* {{enum|GL_UNDEFINED_VERTEX}}: The implementation isn't saying.

For maximum portability, you will have to provide the same layer and viewport index to each primitive. So if you wanted to output a triangle strip, where different triangles had different indices, too bad. You have to split it into different primitives.

=== Output streams ===

{{infobox feature
| name = Output streams
| core = 4.0
| core_extension = [http://www.opengl.org/registry/specs/ARB/transform_feedback3.txt ARB_transform_feedback3]
}}

When using [[Transform Feedback]] to compute values, it is often useful to be able to send different sets of vertices to different buffers at different rates. For example, GS's can send vertex data to one stream, while building per-instance data in another stream. The vertex data and per-instance data will be of different lengths, written at different speeds.

Multiple stream output ''requires'' that the output primitive type be {{code|points}}. You can still take whatever input you prefer.

To provide this, output variables can be given a stream index with a layout qualifier:
{{clear float}}
<source lang="glsl">
 layout(stream = {{param|stream_index}}) out vec4 some_output;
</source>
The {{param|stream_index}} ranges from 0 to {{code|GL_MAX_VERTEX_STREAMS}} - 1.

A default value for the stream can be set with:

<source lang="glsl">
layout(stream = 2) out;
</source>

All following {{code|out}} variables will use stream 2 unless they specify a stream. The default can be changed later. The initial default is 0.

To write a vertex to a particular stream, the function {{code|EmitStreamVertex}} is used. This function takes a stream index; only those output variables are written. Similarly, {{code|EndStreamPrimitive}} ends a particular stream's primitive. However, since multiple stream output requires using {{code|points}} primitives, the latter function is not very useful.

Only primitives emitted to stream 0 will actually be pass along to [[Vertex Post-Processing]] and rendered; the rest of the streams will only matter if transform feedback is being used. Calling {{code|EmitVertex}} or {{code|EndPrimitive}} is equivalent to calling their stream counterparts with stream 0.

== Output limitations ==

There are two competing limitations on the output of a geometry shader:

# The maximum number of vertices that a single invocation of a GS can output.
# The total maximum number of output components that a single invocation of a GS can output.

The first limit, defined by {{enum|GL_MAX_GEOMETRY_OUTPUT_VERTICES}}, is the maximum number that can be provided to the {{param|max_vertices}} output layout qualifier. No single geometry shader invocation can exceed this number.

The other limit, defined by {{enum|GL_MAX_GEOMETRY_TOTAL_OUTPUT_COMPONENTS}} is, in layman's terms, the total amount of stuff that a single GS invocation can write. It is the total number of output values (a component, in GLSL terms, is a component of a vector. So a {{code|float}} is one component; a {{code|vec3}} is 3 components) that a single GS invocation can write to. This is different from {{enum|GL_MAX_GEOMETRY_OUTPUT_COMPONENTS}} (the maximum allowed number of components in {{code|out}} variables). The total output component is the total number of components + vertices that can be written.

For example, if the total output component count is 1024 (the smallest maximum value from GL 4.3), and the output stream writes to 12 components, the total number of vertices that can be written is <math>floor(\tfrac{1024}{12}) = 85</math>. This is the absolute hard limit to the number of vertices that can be written. Even if {{enum|GL_MAX_GEOMETRY_OUTPUT_VERTICES}} is larger than 85, because this vertex shader writes 12 components per vertex, the true maximum that this geometry shader can write is 85 vertices. If the geometry shader instead wrote only 8 components per vertex, then it could write 128 (subject to the output vertices limit, of course).

Note that even built-in outputs like {{code|gl_Layer}} count towards {{enum|GL_MAX_GEOMETRY_TOTAL_OUTPUT_COMPONENTS}}. For example, a geometry shader with a total output component count of 1024 which outputs {{code|vec4 gl_Position}} and {{code|int gl_Layer}} supports a maximum of <math>floor(\tfrac{1024}{4 + 1}) = 204</math> vertices.

== See also ==

* [[Fragment Shader]]
* [[Type Qualifier (GLSL)]]
* [[Geometry Shader Examples]]


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