EEVEE & Viewport: Add a built-in shader called 3D_IMAGE, and expose to the python API

Adds an example python script to the documentation for the 3D_IMAGE shader.

The **use-case** is to draw textures with 3D vertex positions, in XR views as well as non-XR views (in a simpler manner).

**Testing**: I've tested that this compiles and works on my Macbook (with the example python script included in this change). I don't have access to a Windows or Linux machine right now, but this change doesn't look platform-specific and no new glsl shaders have been added or edited by this change. I'll try to get access to a Windows machine, but if someone does have one, I'd be really grateful if they could try this change. Thanks!

**Problem addressed**: The existing 2D_IMAGE shader (exposed in the python API) gets near-clipped when drawn in the
XR view, regardless of the near-clip settings. Additionally, the 2D_IMAGE shader only accepts 2D
positions for the image vertices, which means drawing textures in 3D requires providing
2D coordinates and then pushing a transform-rotate-scale matrix to the GPU, even for
non-XR (i.e. WINDOW) views. The 3D_IMAGE shader is simpler: it accepts 3D vertex positions, and doesn't require
any additional work by the scripter.

**Workaround**: The current workaround is to use custom shaders in the python script.

**Non-intrusive change**: No new glsl shaders were added. This change just bundles two existing shaders: the vertex shader used
by the 3D_IMAGE_MODULATE_ALPHA shader, and the fragment shader used by the 2D_IMAGE shader.

Reviewed By: #eevee_viewport, jbakker

Differential Revision: https://developer.blender.org/D14832

1 files changed, 5 insertions, 0 deletions

diff --git a/source/blender/gpu/intern/gpu_shader_builtin.c b/source/blender/gpu/intern/gpu_shader_builtin.c
index 1100272b712..b92fae4a89b 100644
--- a/source/blender/gpu/intern/gpu_shader_builtin.c
+++ b/source/blender/gpu/intern/gpu_shader_builtin.c
@@ -150,6 +150,11 @@ static const GPUShaderStages builtin_shader_stages[GPU_SHADER_BUILTIN_LEN] = {
             .name = "GPU_SHADER_SIMPLE_LIGHTING",
             .create_info = "gpu_shader_simple_lighting",
         },
+    [GPU_SHADER_3D_IMAGE] =
+        {
+            .name = "GPU_SHADER_3D_IMAGE",
+            .create_info = "gpu_shader_3D_image",
+        },
     [GPU_SHADER_3D_IMAGE_MODULATE_ALPHA] =
         {
             .name = "GPU_SHADER_3D_IMAGE_MODULATE_ALPHA",