From 1ed93f7ccbe7a4a6a1bd54c0be3dc90aa33fb46c Mon Sep 17 00:00:00 2001
From: Garux <garux@mail.ru>
Date: Tue, 10 Dec 2024 23:13:12 +0500
Subject: [PATCH] tweak portal, alphagen portal documentation, completion

---
 docs/shaderManual/general-directives.html | 16 ++++++++++++++-
 docs/shaderManual/stage-directives.html   | 25 +++++++++++++++++++++--
 radiant/gtkdlgs.cpp                       |  6 ++++--
 3 files changed, 42 insertions(+), 5 deletions(-)

diff --git a/docs/shaderManual/general-directives.html b/docs/shaderManual/general-directives.html
index fce5d2ea..140203de 100644
--- a/docs/shaderManual/general-directives.html
+++ b/docs/shaderManual/general-directives.html
@@ -176,7 +176,21 @@ textures/skies/xtoxicsky_dm9
 </blockquote>
 
 <h2 id="portal">portal</h2>
-<p>Specifies that this texture is the surface for a portal or mirror. In the game map, a portal entity must be placed directly in front of the texture (within 64 game units). All this does is set "sort portal", so it isn't needed if you specify that explicitly.</p>
+<p>Specifies that this shader is the surface for a portal or mirror. In the game map, a portal entity (e.g. "misc_portal_surface") must be placed directly in front of the surface (within 64 game units). All this does is set "sort portal", so it isn't needed if you specify that explicitly.</p>
+<p>Bare bones mirror shader example:</p>
+<pre>
+textures/ztest/mirror
+{
+	qer_editorimage textures/sfx/portalfog.tga
+	surfaceparm nolightmap
+	portal
+	{
+		map textures/sfx/portalfog.tga
+		blendFunc GL_ZERO GL_SRC_ALPHA
+		depthWrite
+	}
+}
+</pre>
 
 <h2 id="sort">sort value</h2>
 <p>Use this keyword to fine-tune the depth sorting of shaders as they are compared against other shaders in the game world. The basic concept is that if there is a question or a problem with shaders drawing in the wrong order against each other, this allows the designer to create a hierarchy of which shader draws in what order.</p>
diff --git a/docs/shaderManual/stage-directives.html b/docs/shaderManual/stage-directives.html
index 21c797de..28345e97 100644
--- a/docs/shaderManual/stage-directives.html
+++ b/docs/shaderManual/stage-directives.html
@@ -310,8 +310,29 @@ textures/obsidian_video/intro
 <h3>alphaGen const N.N</h3>
 <p>A constant vertex alpha is assigned to the affected surface. This modifies the transparency of the texture.</p>
 
-<h3>alphaGen portal</h3>
-<p>This rendering stage keyword is used in conjunction with the surface parameter keyword portal. The function accomplishes the "fade" that causes the scene in the portal to fade from view. Specifically, it means "Generate alpha values based on the distance from the viewer to the portal." Use alphaGen portal on the last rendering pass.</p>
+<h3>alphaGen portal <em>distance</em></h3>
+<p>This rendering stage keyword is normally used in conjunction with the surface parameter keyword portal. The function accomplishes the "fade" that causes the scene in the portal/mirror to fade from view. Specifically, it means "Generate alpha values based on the distance from the viewer to the portal". Viewer distance 0 maps to alpha 0, when distance is more than "distance" parameter value, alpha is 1. While latter is the case, portal/mirror content is not rendering at all, this optimization is original purpose of the keyword, though it may be utilized for other distance dependent effects.</p>
+<p>
+Basic fading portal/mirror shader example:
+</p>
+<pre>
+textures/ztest/portal
+{
+	qer_editorimage textures/sfx/portalfog.tga
+	surfaceparm nolightmap
+	portal
+	{
+		map textures/sfx/portalfog.tga
+		blendFunc GL_ZERO GL_SRC_ALPHA
+		depthWrite
+	}
+	{
+		map textures/sfx/portalfog.tga
+		blendfunc GL_SRC_ALPHA GL_ONE_MINUS_SRC_ALPHA
+		alphagen portal 256
+	}
+}
+</pre>
 
 <h2 id="tcGen">tcGen coordinateSource</h2>
 <p>Specifies how texture coordinates are generated and where they come from. Valid functions are base, lightmap, environment and vector.</p>
diff --git a/radiant/gtkdlgs.cpp b/radiant/gtkdlgs.cpp
index 7ae78738..bb404117 100644
--- a/radiant/gtkdlgs.cpp
+++ b/radiant/gtkdlgs.cpp
@@ -1238,7 +1238,6 @@ static const std::vector<ShaderFormat> g_shaderStageFormats{
 			"oneMinusEntity",
 			"vertex",
 			"oneMinusVertex",
-			"portal",
 		}
 	},
 	{
@@ -1252,7 +1251,10 @@ static const std::vector<ShaderFormat> g_shaderStageFormats{
 		}
 	},
 	{
-		"alphaGen const %f", c_pageStage, c_colorKeyLv2
+		"alphaGen %s %f", c_pageStage, c_colorKeyLv2, {
+			"const",
+			"portal",
+		}
 	},
 	{
 		"tcGen %s", c_pageStage, c_colorKeyLv2, {