Adjusted framebuffer size and rotation shader variables and functions.

Framebuffer size, both pre and post rotation, and framebuffer rotation are
now available through dsInstanceTransformData and dsViewFramebufferData to
allow them to change based on the bound framebuffer.
dsInstanceTransformData allows it to be accessed for the common case
without additional variables, dsViewFramebufferData maintains one copy of
the values for all instances for a group that is drawn together. Added
separate uniforms for dsShadowInstanceTransformData that omits the
framebuffer elements.

Renamed various transformation functions to be more consistent. Shared
implementations are now provided in CoordinateHelpers.mslh where parameters
may come from different uniforms.

Going from clip to view space no longer adjusts the clip. This avoids
duplicate adjustments, which can also differ based on where the coordinates
came from. (projection matrix or framebuffer position)

Adjusted the internal uniforms for OpenGL to reduce the amount of work
required to adjust the fragment coordinates and have more info available
for adjusting the clips. This now requires two vec4 uniforms, but should
be faster at runtime and provide more flexibility.

Removed DS_ADJUST_TEXTURE_CLIP() macro and removed the dsViewTransformData
variable for the texture transform. Defines are now used for the projection
texture transforms for standard situations for shadow mapping and SSAO.

Author: akb825

modules/Render/Render/README.md

@@ -27,7 +27,6 @@ DeepSea uses [Modular Shader Language](https://github.com/akb825/ModularShaderLa
 * gl_FragCoord is always in the upper-left.
 * Use the `DS_ADJUST_CLIP(x)` macro with the clip position (such as that assigned to gl_Position) to ensure the clip position x is transformed to the correct space.
 	* If using a direct clip position without a projection matrix, use `DS_ADJUST_DIRECT_CLIP(x)` instead.
-	* If used as a guaranteed texture target, such as a texture projection, use `DS_ADJUST_TEXTURE_CLIP(x)` instead.
 * When support for older hardware with OpenGL 2.x, use the `DS_RG_SWZL` macro for RG-format textures. (e.g. `color.DS_RG_SWZL`) This ensures compatibility with targets that use luminance-alpha textures instead.
 * Subpass inputs may always be used. Defines are provided to fall back to a standard texture lookup on targets that don't support them directly.
 * When declaring subpass inputs, instead of using `layout(input_attachment_index = i) uniform subpassInput input`, declare as `inputAttachment(i) input`.
@@ -75,6 +74,8 @@ Most render states are set by declaring the render state in the shader pipeline.
 The following built-in defines are available when writing shaders:
 
 * `DS_MIN_CLIP_Z`: The minimum Z value in clip space. In most cases this is 0.0, but for OpenGL it may be -1.0 or 0.0 depending on whether the `preferHalfDepthRange` renderer option is enabled and the device supports adjusting the clip range.
+* `DS_CLIP_Z_TO_DEPTH_MUL` and `DS_CLIP_Z_TO_DEPTH_ADD`: The multiplication and addition factors to convert from clip z to depth values, applied as `z*DS_CLIP_Z_TO_DEPTH_MUL + DS_CLIP_Z_TO_DEPTH_ADD`.
+* `DS_DEPTH_TO_CLIP_Z_MUL` and `DS_DEPTH_TO_CLIP_Z_ADD`: The multiplication and addition factors to convert from depth values to clip z, applied as `z*DS_DEPTH_TO_CLIP_Z_MUL + DS_DEPTH_TO_CLIP_Z_ADD`.
 * `DS_ADJUST_CLIP(v)`: Call when assigning `gl_Position` at the end of the vertex shader to adjust for the current system's clip space. It's assumed that the position was computed with the projection matrix.
 * `DS_ADJUST_DIRECT_CLIP(v)`: Same as `DS_ADJUST_CLIP`, except for creating the position directly in clip space rather than using the projection matrix.
 * `DS_RG_SWZL`: Swizzle for RG channel textures. This takes into account older versions of OpenGL that use lumanance alpha for two-channel textures, which requires `ra` rather than `rg`.

modules/Render/Render/include/DeepSea/Render/RenderSurface.h

@@ -66,6 +66,7 @@ DS_RENDER_EXPORT bool dsRenderSurface_makeRotationMatrix44(
  * @param viewport The viewport to rotate. This may be the same as result.
  * @param width The width of the physical surface.
  * @param height The height of the physical surface.
+ * @param rotation The rotation to apply.
  * @return False if the parameters are invalid.
  */
 DS_RENDER_EXPORT bool dsRenderSurface_rotateViewport(dsAlignedBox3f* result,
@@ -76,9 +77,10 @@ DS_RENDER_EXPORT bool dsRenderSurface_rotateViewport(dsAlignedBox3f* result,
  * @brief Rotates a scissor box for the render surface rotation.
  * @remark errno will be set on failure.
  * @param[out] result The rotated scissor.
+ * @param scissor The scissor to rotate. This may be the same as result.
  * @param width The width of the physical surface.
  * @param height The height of the physical surface.
- * @param scissor The scissor to rotate. This may be the same as result.
+ * @param rotation The rotation to apply.
  * @return False if the parameters are invalid.
  */
 DS_RENDER_EXPORT bool dsRenderSurface_rotateScissor(dsAlignedBox2f* result,

modules/Render/Render/include/DeepSea/Render/Shaders/CoordinateHelpers.mslh

@@ -1,5 +1,5 @@
 /*
- * Copyright 2022 Aaron Barany
+ * Copyright 2022-2026 Aaron Barany
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -21,8 +21,45 @@
  * @brief Functions to help with different coordinate transformations.
  */
 
+#if SPIRV_VERSION
+/**
+ * @brief Multiplier factor from clip coordinates to projected texture coordinates.
+ */
+#define DS_CLIP_TO_PROJ_TEX_COORDS_MUL vec3(0.5, 0.5, DS_CLIP_Z_TO_DEPTH_MUL)
+
+/**
+ * @brief Addition factor from clip coordinates to projected texture coordinates.
+ */
+#define DS_CLIP_TO_PROJ_TEX_COORDS_ADD vec3(0.5, 0.5, DS_CLIP_Z_TO_DEPTH_ADD)
+#else
+#define DS_CLIP_TO_PROJ_TEX_COORDS_MUL vec3(0.5, -0.5, DS_CLIP_Z_TO_DEPTH_MUL)
+#define DS_CLIP_TO_PROJ_TEX_COORDS_ADD vec3(0.5, 0.5, DS_CLIP_Z_TO_DEPTH_ADD)
+#endif
+
 /**
- * @brief Transforms from clip coordinates in the common [-1, -1] as lower left to texture
+ * @brief Array with the multiplier and addition afctors from clip coordinates to projected
+ * texture coordinates.
+ */
+#define DS_CLIP_TO_PROJ_TEX_COORDS \
+	vec3[2](DS_CLIP_TO_PROJ_TEX_COORDS_MUL, DS_CLIP_TO_PROJ_TEX_COORDS_ADD)
+
+/**
+ * @brief Toggles between common clip coordinates, where [-1, -1] is the lower-left, and direct
+ *     clip space where the origin depends on the current graphics environment.
+ * @param clipCoords The clip coordinates.
+ * @return The adjusted clip coordinates, toggling between common and device-specific coordinates.
+ */
+vec4 dsToggleCommonClip(vec4 clipCoords)
+{
+#if SPIRV_VERSION
+	return vec4(clipCoords.x, -clipCoords.y, clipCoords.zw);
+#else
+	return clipCoords;
+#endif
+}
+
+/**
+ * @brief Transforms from common clip coordinates, where [-1, -1] is the lower-left, to texture
  * coordinates.
  *
  * This is typically used for cases where the clip coordinates are passed directly as vertex
@@ -34,7 +71,7 @@
  */
 vec2 dsCommonClipToTexCoords(vec2 clipCoords)
 {
-	return vec2(clipCoords.x, -clipCoords.y)*vec2(0.5) + vec2(0.5);
+	return clipCoords*vec2(0.5, -0.5) + vec2(0.5);
 }
 
 /**
@@ -45,11 +82,44 @@ vec2 dsCommonClipToTexCoords(vec2 clipCoords)
 vec2 dsClipToTexCoords(vec2 clipCoords)
 {
 #if SPIRV_VERSION
-	// Avoid having to call DS_ADJUST_DIRECT_CLIP and have duplicate operations.
+	// Avoid having to call dsToggleCommonClip() and have duplicate operations.
 	return clipCoords*vec2(0.5) + vec2(0.5);
 #else
-	return vec2(clipCoords.x, -clipCoords.y)*vec2(0.5) + vec2(0.5);
+	return clipCoords*vec2(0.5, -0.5) + vec2(0.5);
+#endif
+}
+
+/**
+ * @brief Converts a depth value to a clip Z coordinate.
+ * @param depth The depth value in the range [0, 1].
+ * @return The z coordinate for a clip position.
+ */
+float dsDepthToClipZ(float depth)
+{
+#if GLSL_VERSION || GLSLES_VERSION
+	// Only OpenGL may potentially have a different clip space.
+	return depth*DS_DEPTH_TO_CLIP_Z_MUL + DS_DEPTH_TO_CLIP_Z_ADD;
+#else
+	return depth;
+#endif
+}
+
+/**
+ * @brief Transforms the current pixel's framebuffer coordinates to clip coordinates.
+ * @param framebufferSize The size of the framebuffer.
+ * @return The clip position for the current framebuffer position as would have been set on
+ *     gl_Position after multiplying by a projection matrix.
+ */
+[[fragment]]
+vec2 dsFramebufferToClip(vec2 framebufferSize)
+{
+	// gl_FragCoord origin follows native texture coordinate origin.
+	vec2 framebufferPos = gl_FragCoord.xy/framebufferSize;
+	framebufferPos = framebufferPos*vec2(2.0) - vec2(1.0);
+#if METAL_VERSION
+	framebufferPos.y = -framebufferPos.y;
 #endif
+	return framebufferPos;
 }
 
 /**

modules/Render/Render/include/DeepSea/Render/Shaders/Shadows/CascadedShadowMap.mslh

@@ -84,7 +84,7 @@ float DS_CASCADED_SHADOW_FUNCTION_NAME(sampler2DArrayShadow shadowMap, vec3 view
 	float fadeAmount = fadeFactors.x/fadeFactors.y;
 
 	mat4 projection = INSTANCE(DS_SHADOW_UNIFORM).matrices[split];
-	vec4 shadowPos = DS_ADJUST_TEXTURE_CLIP(projection*vec4(viewPos, 1.0));
+	vec4 shadowPos = projection*vec4(viewPos, 1.0);
 	shadowPos /= shadowPos.w;
 	vec3 shadowTexCoords = shadowPos.xyz*texCoordTransform[0] + texCoordTransform[1];
 	shadowTexCoords.z = clamp(shadowTexCoords.z, 0.0, 1.0);

modules/Render/Render/include/DeepSea/Render/Shaders/Shadows/PointShadowMap.mslh

@@ -90,7 +90,7 @@ float DS_POINT_SHADOW_FUNCTION_NAME(sampler2DArrayShadow shadowMap, vec3 viewPos
 		surface = lightToPos.z > 0 ? 4 : 5;
 
 	mat4 projection = INSTANCE(DS_SHADOW_UNIFORM).matrices[surface];
-	vec4 shadowPos = DS_ADJUST_TEXTURE_CLIP(projection*vec4(viewPos, 1.0));
+	vec4 shadowPos = projection*vec4(viewPos, 1.0);
 	shadowPos /= shadowPos.w;
 	vec3 shadowTexCoords = shadowPos.xyz*texCoordTransform[0] + texCoordTransform[1];
 	shadowTexCoords.z = clamp(shadowTexCoords.z, 0.0, 1.0);

modules/Render/Render/include/DeepSea/Render/Types.h

@@ -2217,11 +2217,6 @@ struct dsRenderer
 	 */
 	bool hasFragmentInputs;
 
-	/**
-	 * @brief Whether or not projected texture coordinates have an inverted T coordinate.
-	 */
-	bool projectedTexCoordTInverted;
-
 	/**
 	 * @brief Whether or not render passes require strictly all commands in separate command buffers
 	 *     when using secondary command buffers.

modules/Render/RenderMetal/msl-config/metal-ios-1.0.conf

@@ -2,7 +2,10 @@ target = metal-ios
 version = 1.0
 define = subpassInput(i)=layout(input_attachment_index = i) subpassInput
 define = DS_MIN_CLIP_Z=0.0
+define = DS_CLIP_Z_TO_DEPTH_MUL=1.0
+define = DS_CLIP_Z_TO_DEPTH_ADD=0.0
+define = DS_DEPTH_TO_CLIP_Z_MUL=1.0
+define = DS_DEPTH_TO_CLIP_Z_ADD=0.0
 define = DS_ADJUST_CLIP(v)=(v)
 define = DS_ADJUST_DIRECT_CLIP(v)=(v)
-define = DS_ADJUST_TEXTURE_CLIP(v)=(v)
 define = DS_RG_SWZL=rg

modules/Render/RenderMetal/msl-config/metal-ios-1.1.conf

@@ -2,7 +2,10 @@ target = metal-ios
 version = 1.1
 define = subpassInput(i)=layout(input_attachment_index = i) subpassInput
 define = DS_MIN_CLIP_Z=0.0
+define = DS_CLIP_Z_TO_DEPTH_MUL=1.0
+define = DS_CLIP_Z_TO_DEPTH_ADD=0.0
+define = DS_DEPTH_TO_CLIP_Z_MUL=1.0
+define = DS_DEPTH_TO_CLIP_Z_ADD=0.0
 define = DS_ADJUST_CLIP(v)=(v)
 define = DS_ADJUST_DIRECT_CLIP(v)=(v)
-define = DS_ADJUST_TEXTURE_CLIP(v)=(v)
 define = DS_RG_SWZL=rg

modules/Render/RenderMetal/msl-config/metal-ios-1.2.conf

@@ -2,7 +2,10 @@ target = metal-ios
 version = 1.2
 define = subpassInput(i)=layout(input_attachment_index = i) subpassInput
 define = DS_MIN_CLIP_Z=0.0
+define = DS_CLIP_Z_TO_DEPTH_MUL=1.0
+define = DS_CLIP_Z_TO_DEPTH_ADD=0.0
+define = DS_DEPTH_TO_CLIP_Z_MUL=1.0
+define = DS_DEPTH_TO_CLIP_Z_ADD=0.0
 define = DS_ADJUST_CLIP(v)=(v)
 define = DS_ADJUST_DIRECT_CLIP(v)=(v)
-define = DS_ADJUST_TEXTURE_CLIP(v)=(v)
 define = DS_RG_SWZL=rg

modules/Render/RenderMetal/msl-config/metal-ios-2.0.conf

@@ -2,7 +2,10 @@ target = metal-ios
 version = 2.0
 define = subpassInput(i)=layout(input_attachment_index = i) subpassInput
 define = DS_MIN_CLIP_Z=0.0
+define = DS_CLIP_Z_TO_DEPTH_MUL=1.0
+define = DS_CLIP_Z_TO_DEPTH_ADD=0.0
+define = DS_DEPTH_TO_CLIP_Z_MUL=1.0
+define = DS_DEPTH_TO_CLIP_Z_ADD=0.0
 define = DS_ADJUST_CLIP(v)=(v)
 define = DS_ADJUST_DIRECT_CLIP(v)=(v)
-define = DS_ADJUST_TEXTURE_CLIP(v)=(v)
 define = DS_RG_SWZL=rg