OpenGL: documentation for the builtin GPU shaders

This is intended to help developers to know how and when to use each shader.
There are plenty of undocumented shaders, but it's a matter of filling them in.

The script I used to quickly find the related shaders for a const is: P700

Original patch: D2318

1 files changed, 148 insertions, 0 deletions

diff --git a/source/blender/gpu/GPU_shader.h b/source/blender/gpu/GPU_shader.h
index baaa23c2398..f831d495ad0 100644
--- a/source/blender/gpu/GPU_shader.h
+++ b/source/blender/gpu/GPU_shader.h
@@ -121,9 +121,28 @@ typedef enum GPUBuiltinShader {
 	GPU_SHADER_SIMPLE_LIGHTING_FLAT_COLOR,
 	GPU_SHADER_SIMPLE_LIGHTING_SMOOTH_COLOR,
 	GPU_SHADER_SIMPLE_LIGHTING_SMOOTH_COLOR_ALPHA,
+
 	/* for simple 2D drawing */
+	/**
+	 * Take a single color for all the vertices and a 2D position for each vertex.
+	 *
+	 * \param color: uniform vec4
+	 * \param pos: in vec2
+	 */
 	GPU_SHADER_2D_UNIFORM_COLOR,
+	/**
+	 * Take a 2D position and color for each vertex without color interpolation.
+	 *
+	 * \param color: in vec4
+	 * \param pos: in vec2
+	 */
 	GPU_SHADER_2D_FLAT_COLOR,
+	/**
+	 * Take a 2D position and color for each vertex with linear interpolation in window space.
+	 *
+	 * \param color: in vec4
+	 * \param pos: in vec2
+	 */
 	GPU_SHADER_2D_SMOOTH_COLOR,
 	GPU_SHADER_2D_SMOOTH_COLOR_DITHER,
 	GPU_SHADER_2D_IMAGE,
@@ -140,34 +159,163 @@ typedef enum GPUBuiltinShader {
 	GPU_SHADER_2D_CHECKER,
 	GPU_SHADER_2D_DIAG_STRIPES,
 	/* for simple 3D drawing */
+	/**
+	 * Take a single color for all the vertices and a 3D position for each vertex.
+	 *
+	 * \param color: uniform vec4
+	 * \param pos: in vec3
+	 */
 	GPU_SHADER_3D_UNIFORM_COLOR,
 	GPU_SHADER_3D_UNIFORM_COLOR_U32,
 	GPU_SHADER_3D_UNIFORM_COLOR_INSTANCE,
+	/**
+	 * Take a 3D position and color for each vertex without color interpolation.
+	 *
+	 * \param color: in vec4
+	 * \param pos: in vec3
+	 */
 	GPU_SHADER_3D_FLAT_COLOR,
 	GPU_SHADER_3D_FLAT_COLOR_U32,  /* use for select-id's */
+	/**
+	 * Take a 3D position and color for each vertex with perspective correct interpolation.
+	 *
+	 * \param color: in vec4
+	 * \param pos: in vec3
+	 */
 	GPU_SHADER_3D_SMOOTH_COLOR,
+	/**
+	 * Take a 3D position for each vertex and output only depth.
+	 *
+	 * \param pos: in vec3
+	 */
 	GPU_SHADER_3D_DEPTH_ONLY,
 	GPU_SHADER_3D_CLIPPED_UNIFORM_COLOR,
 	/* basic image drawing */
 	GPU_SHADER_2D_IMAGE_LINEAR_TO_SRGB,
 	GPU_SHADER_2D_IMAGE_SHUFFLE_COLOR,
 	GPU_SHADER_2D_IMAGE_MASK_UNIFORM_COLOR,
+	/**
+	 * Draw texture with alpha. Take a 3D positon and a 2D texture coordinate for each vertex.
+	 *
+	 * \param alpha: uniform float
+	 * \param image: uniform sampler2D
+	 * \param texCoord: in vec2
+	 * \param pos: in vec3
+	 */
 	GPU_SHADER_3D_IMAGE_MODULATE_ALPHA,
+	/**
+	 * Draw linearized depth texture relate to near and far distances.
+	 * Take a 3D positon and a 2D texture coordinate for each vertex.
+	 *
+	 * \param znear: uniform float
+	 * \param zfar: uniform float
+	 * \param image: uniform sampler2D
+	 * \param texCoord: in vec2
+	 * \param pos: in vec3
+	 */
 	GPU_SHADER_3D_IMAGE_DEPTH,
 	GPU_SHADER_3D_IMAGE_DEPTH_COPY,
 	/* stereo 3d */
 	GPU_SHADER_2D_IMAGE_INTERLACE,
 	/* points */
+	/**
+	 * Draw round points with a hardcoded size.
+	 * Take a single color for all the vertices and a 2D position for each vertex.
+	 *
+	 * \param color: uniform vec4
+	 * \param pos: in vec2
+	 */
 	GPU_SHADER_2D_POINT_FIXED_SIZE_UNIFORM_COLOR,
+	/**
+	 * Draw round points with a constant size.
+	 * Take a single color for all the vertices and a 2D position for each vertex.
+	 *
+	 * \param size: uniform float
+	 * \param color: uniform vec4
+	 * \param pos: in vec2
+	 */
 	GPU_SHADER_2D_POINT_UNIFORM_SIZE_UNIFORM_COLOR_AA,
+	/**
+	 * Draw round points with a constant size and an outline.
+	 * Take a single color for all the vertices and a 2D position for each vertex.
+	 *
+	 * \param size: uniform float
+	 * \param outlineWidth: uniform float
+	 * \param color: uniform vec4
+	 * \param outlineColor: uniform vec4
+	 * \param pos: in vec2
+	 */
 	GPU_SHADER_2D_POINT_UNIFORM_SIZE_UNIFORM_COLOR_OUTLINE_AA,
+	/**
+	 * Draw round points with a constant size and an outline. Take a 2D position and a color for each vertex.
+	 *
+	 * \param size: uniform float
+	 * \param outlineWidth: uniform float
+	 * \param outlineColor: uniform vec4
+	 * \param color: in vec4
+	 * \param pos: in vec2
+	 */
 	GPU_SHADER_2D_POINT_UNIFORM_SIZE_VARYING_COLOR_OUTLINE_AA,
+	/**
+	 * Draw round points with a constant size and an outline. Take a 2D position and a color for each vertex.
+	 *
+	 * \param size: in float
+	 * \param color: in vec4
+	 * \param pos: in vec2
+	 */
 	GPU_SHADER_2D_POINT_VARYING_SIZE_VARYING_COLOR,
+	/**
+	 * Draw round points with a hardcoded size.
+	 * Take a single color for all the vertices and a 3D position for each vertex.
+	 *
+	 * \param color: uniform vec4
+	 * \param pos: in vec3
+	 */
 	GPU_SHADER_3D_POINT_FIXED_SIZE_UNIFORM_COLOR,
+	/**
+	 * Draw round points with a hardcoded size.
+	 * Take a single color for all the vertices and a 3D position for each vertex.
+	 *
+	 * \param color: uniform vec4
+	 * \param pos: in vec3
+	 */
 	GPU_SHADER_3D_POINT_FIXED_SIZE_VARYING_COLOR,
+	/**
+	 * Draw round points with a constant size.
+	 * Take a single color for all the vertices and a 3D position for each vertex.
+	 *
+	 * \param size: uniform float
+	 * \param color: uniform vec4
+	 * \param pos: in vec3
+	 */
 	GPU_SHADER_3D_POINT_UNIFORM_SIZE_UNIFORM_COLOR_AA,
+	/**
+	 * Draw round points with a constant size and an outline.
+	 * Take a single color for all the vertices and a 3D position for each vertex.
+	 *
+	 * \param size: uniform float
+	 * \param outlineWidth: uniform float
+	 * \param color: uniform vec4
+	 * \param outlineColor: uniform vec4
+	 * \param pos: in vec3
+	 */
 	GPU_SHADER_3D_POINT_UNIFORM_SIZE_UNIFORM_COLOR_OUTLINE_AA,
+	/**
+	 * Draw round points with a constant size and an outline.
+	 * Take a single color for all the vertices and a 3D position for each vertex.
+	 *
+	 * \param color: uniform vec4
+	 * \param size: in float
+	 * \param pos: in vec3
+	 */
 	GPU_SHADER_3D_POINT_VARYING_SIZE_UNIFORM_COLOR,
+	/**
+	 * Draw round points with a constant size and an outline. Take a 3D position and a color for each vertex.
+	 *
+	 * \param size: in float
+	 * \param color: in vec4
+	 * \param pos: in vec3
+	 */
 	GPU_SHADER_3D_POINT_VARYING_SIZE_VARYING_COLOR,
 	/* lines */
 	GPU_SHADER_2D_LINE_DASHED_UNIFORM_COLOR,