Merge pull request #899 from Xtarsia/improve-flat-bg-mode

Improve Region Blend, gizmos, shaders

Author: TokisanGames

Terrain3D.vcxproj

@@ -224,11 +224,13 @@
     <None Include="src\shaders\debug_views.glsl" />
     <None Include="src\shaders\displacement.glsl" />
     <None Include="src\shaders\displacement_buffer.glsl" />
+    <None Include="src\shaders\macro_variation.glsl" />
     <None Include="src\shaders\main.glsl" />
     <None Include="src\shaders\overlays.glsl" />
     <None Include="src\shaders\pbr_views.glsl">
       <FileType>Document</FileType>
     </None>
+    <None Include="src\shaders\projection.glsl" />
     <None Include="src\shaders\samplers.glsl" />
     <None Include="src\shaders\backgrounds.glsl" />
     <None Include="src\shaders\editor_functions.glsl" />

Terrain3D.vcxproj.filters

@@ -283,6 +283,12 @@
     <None Include="doc\docs\displacement.md">
       <Filter>2. Docs</Filter>
     </None>
+    <None Include="src\shaders\macro_variation.glsl">
+      <Filter>4. Shaders</Filter>
+    </None>
+    <None Include="src\shaders\projection.glsl">
+      <Filter>4. Shaders</Filter>
+    </None>
   </ItemGroup>
   <ItemGroup>
     <Text Include=".readthedocs.yaml">

doc/api/class_terrain3dassets.rst

@@ -74,8 +74,6 @@ Methods
    +-----------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
    | ``PackedFloat32Array``                                    | :ref:`get_texture_uv_scales<class_Terrain3DAssets_method_get_texture_uv_scales>`\ (\ ) |const|                                                                                  |
    +-----------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-   | ``int``                                                   | :ref:`get_texture_vertical_projections<class_Terrain3DAssets_method_get_texture_vertical_projections>`\ (\ ) |const|                                                            |
-   +-----------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
    | Error                                                     | :ref:`save<class_Terrain3DAssets_method_save>`\ (\ path\: ``String`` = ""\ )                                                                                                    |
    +-----------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
    | |void|                                                    | :ref:`set_mesh_asset<class_Terrain3DAssets_method_set_mesh_asset>`\ (\ id\: ``int``, mesh\: :ref:`Terrain3DMeshAsset<class_Terrain3DMeshAsset>`\ )                              |
@@ -416,18 +414,6 @@ Returns the array of uv scale values for each texture asset, indexed by asset id
 
 ----
 
-.. _class_Terrain3DAssets_method_get_texture_vertical_projections:
-
-.. rst-class:: classref-method
-
-``int`` **get_texture_vertical_projections**\ (\ ) |const| :ref:`🔗<class_Terrain3DAssets_method_get_texture_vertical_projections>`
-
-Returns a 32-bit int that identifies which textures are to be projected vertically.
-
-.. rst-class:: classref-item-separator
-
-----
-
 .. _class_Terrain3DAssets_method_save:
 
 .. rst-class:: classref-method

doc/api/class_terrain3dmaterial.rst

@@ -23,7 +23,9 @@ This class handles options for both the built-in shader and any custom override
 
 It is a savable resource, so you can save it to disk and use the same material settings in multiple scenes that use Terrain3D. The amount of data is small, assuming you have saved your shader parameter textures to disk, so it can be saved as a git-friendly, text based .tres file or left within the scene file.
 
-While it does mimic some of the functionality of ShaderMaterial, it does not derive from any of the Godot Material classes. It will not pass any ``is Material`` checks. It is a ``Resource``.
+While it does mimic some of the functionality of ShaderMaterial, it does not derive from any of the Godot Material classes. It will fail any ``is Material`` checks. It is a ``Resource``.
+
+Inspector settings above `Custom Shader` and :ref:`shader_override<class_Terrain3DMaterial_property_shader_override>` are used to determine what code is used in the current shader. Inspector settings in `Shader Uniforms` are the public uniforms (not prefaced with `\_`) available in the current shader.
 
 .. rst-class:: classref-reftable-group
 
@@ -48,6 +50,18 @@ Properties
    +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------+-----------+
    | ``bool``                                                         | :ref:`dual_scaling_enabled<class_Terrain3DMaterial_property_dual_scaling_enabled>`                     | ``false`` |
    +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------+-----------+
+   | ``bool``                                                         | :ref:`macro_variation_enabled<class_Terrain3DMaterial_property_macro_variation_enabled>`               | ``false`` |
+   +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------+-----------+
+   | ``bool``                                                         | :ref:`output_albedo<class_Terrain3DMaterial_property_output_albedo>`                                   | ``true``  |
+   +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------+-----------+
+   | ``bool``                                                         | :ref:`output_ambient_occlusion<class_Terrain3DMaterial_property_output_ambient_occlusion>`             | ``true``  |
+   +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------+-----------+
+   | ``bool``                                                         | :ref:`output_normal_map<class_Terrain3DMaterial_property_output_normal_map>`                           | ``true``  |
+   +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------+-----------+
+   | ``bool``                                                         | :ref:`output_roughness<class_Terrain3DMaterial_property_output_roughness>`                             | ``true``  |
+   +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------+-----------+
+   | ``bool``                                                         | :ref:`projection_enabled<class_Terrain3DMaterial_property_projection_enabled>`                         | ``false`` |
+   +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------+-----------+
    | ``Shader``                                                       | :ref:`shader_override<class_Terrain3DMaterial_property_shader_override>`                               |           |
    +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------+-----------+
    | ``bool``                                                         | :ref:`shader_override_enabled<class_Terrain3DMaterial_property_shader_override_enabled>`               | ``false`` |
@@ -124,7 +138,7 @@ Methods
    +-------------+----------------------------------------------------------------------------------------------------------------------------+
    | |void|      | :ref:`set_shader_param<class_Terrain3DMaterial_method_set_shader_param>`\ (\ name\: ``StringName``, value\: ``Variant``\ ) |
    +-------------+----------------------------------------------------------------------------------------------------------------------------+
-   | |void|      | :ref:`update<class_Terrain3DMaterial_method_update>`\ (\ full\: ``bool`` = false\ )                                        |
+   | |void|      | :ref:`update<class_Terrain3DMaterial_method_update>`\ (\ flags\: ``int`` = 0\ )                                            |
    +-------------+----------------------------------------------------------------------------------------------------------------------------+
 
 .. rst-class:: classref-section-separator
@@ -192,6 +206,56 @@ Textures are filtered using a blend of 4 adjacent pixels. Use this for most case
 
 Textures are filtered using a the nearest pixel only. It is faster than LINEAR, but the texture will look pixelated. Use this for a low-poly look, with a very low uv_scale.
 
+.. rst-class:: classref-item-separator
+
+----
+
+.. _enum_Terrain3DMaterial_UpdateFlags:
+
+.. rst-class:: classref-enumeration
+
+enum **UpdateFlags**: :ref:`🔗<enum_Terrain3DMaterial_UpdateFlags>`
+
+.. _class_Terrain3DMaterial_constant_UNIFORMS_ONLY:
+
+.. rst-class:: classref-enumeration-constant
+
+:ref:`UpdateFlags<enum_Terrain3DMaterial_UpdateFlags>` **UNIFORMS_ONLY** = ``0``
+
+Non-texture array values are assigned to the shader. This is the default and is always done.
+
+.. _class_Terrain3DMaterial_constant_TEXTURE_ARRAYS:
+
+.. rst-class:: classref-enumeration-constant
+
+:ref:`UpdateFlags<enum_Terrain3DMaterial_UpdateFlags>` **TEXTURE_ARRAYS** = ``1``
+
+The ground texture arrays are assigned to the shader, along with the values in `UNIFORMS_ONLY`.
+
+.. _class_Terrain3DMaterial_constant_REGION_ARRAYS:
+
+.. rst-class:: classref-enumeration-constant
+
+:ref:`UpdateFlags<enum_Terrain3DMaterial_UpdateFlags>` **REGION_ARRAYS** = ``2``
+
+The region data texture arrays are assigned to the shader, along with the values in `UNIFORMS_ONLY`.
+
+.. _class_Terrain3DMaterial_constant_UPDATE_ARRAYS:
+
+.. rst-class:: classref-enumeration-constant
+
+:ref:`UpdateFlags<enum_Terrain3DMaterial_UpdateFlags>` **UPDATE_ARRAYS** = ``3``
+
+Values in `TEXTURE_ARRAYS` and `REGION_ARRAYS` are assigned to the shader.
+
+.. _class_Terrain3DMaterial_constant_FULL_REBUILD:
+
+.. rst-class:: classref-enumeration-constant
+
+:ref:`UpdateFlags<enum_Terrain3DMaterial_UpdateFlags>` **FULL_REBUILD** = ``7``
+
+The shader is rebuilt, then all values in `UPDATE_ARRAYS` are assigned to the shader.
+
 .. rst-class:: classref-section-separator
 
 ----
@@ -221,8 +285,8 @@ This private dictionary stores all of the shader parameters in the resource. It
 
 .. rst-class:: classref-property-setget
 
-- |void| **set_auto_shader**\ (\ value\: ``bool``\ )
-- ``bool`` **get_auto_shader**\ (\ )
+- |void| **set_auto_shader_enabled**\ (\ value\: ``bool``\ )
+- ``bool`` **get_auto_shader_enabled**\ (\ )
 
 Enables selecting two texture IDs that will automatically be applied to the terrain based upon slope.
 
@@ -306,15 +370,117 @@ Adjusts the transition between textures. When set at `1.0`, the blending of disp
 
 .. rst-class:: classref-property-setget
 
-- |void| **set_dual_scaling**\ (\ value\: ``bool``\ )
-- ``bool`` **get_dual_scaling**\ (\ )
+- |void| **set_dual_scaling_enabled**\ (\ value\: ``bool``\ )
+- ``bool`` **get_dual_scaling_enabled**\ (\ )
 
 Enables selecting one texture ID that will have multiple scales applied based upon camera distance. Use it for something like a rock texture so up close it will be nicely detailed, and far away mountains can be covered in the same rock texture without looking tiled. The two blend together at a specified distance.
 
 .. rst-class:: classref-item-separator
 
 ----
 
+.. _class_Terrain3DMaterial_property_macro_variation_enabled:
+
+.. rst-class:: classref-property
+
+``bool`` **macro_variation_enabled** = ``false`` :ref:`🔗<class_Terrain3DMaterial_property_macro_variation_enabled>`
+
+.. rst-class:: classref-property-setget
+
+- |void| **set_macro_variation_enabled**\ (\ value\: ``bool``\ )
+- ``bool`` **get_macro_variation_enabled**\ (\ )
+
+Allows you to add a couple of noise patterns at different scales and colors to add variation to your terrain to avoid tiled textures.
+
+.. rst-class:: classref-item-separator
+
+----
+
+.. _class_Terrain3DMaterial_property_output_albedo:
+
+.. rst-class:: classref-property
+
+``bool`` **output_albedo** = ``true`` :ref:`🔗<class_Terrain3DMaterial_property_output_albedo>`
+
+.. rst-class:: classref-property-setget
+
+- |void| **set_output_albedo_enabled**\ (\ value\: ``bool``\ )
+- ``bool`` **get_output_albedo_enabled**\ (\ )
+
+Enables the Albedo, aka Base Color or Diffuse, output channel in the shader.
+
+.. rst-class:: classref-item-separator
+
+----
+
+.. _class_Terrain3DMaterial_property_output_ambient_occlusion:
+
+.. rst-class:: classref-property
+
+``bool`` **output_ambient_occlusion** = ``true`` :ref:`🔗<class_Terrain3DMaterial_property_output_ambient_occlusion>`
+
+.. rst-class:: classref-property-setget
+
+- |void| **set_output_ambient_occlusion_enabled**\ (\ value\: ``bool``\ )
+- ``bool`` **get_output_ambient_occlusion_enabled**\ (\ )
+
+Enables the Ambient Occlusion output channel in the shader.
+
+.. rst-class:: classref-item-separator
+
+----
+
+.. _class_Terrain3DMaterial_property_output_normal_map:
+
+.. rst-class:: classref-property
+
+``bool`` **output_normal_map** = ``true`` :ref:`🔗<class_Terrain3DMaterial_property_output_normal_map>`
+
+.. rst-class:: classref-property-setget
+
+- |void| **set_output_normal_map_enabled**\ (\ value\: ``bool``\ )
+- ``bool`` **get_output_normal_map_enabled**\ (\ )
+
+Enables the Normal Map output channel in the shader.
+
+.. rst-class:: classref-item-separator
+
+----
+
+.. _class_Terrain3DMaterial_property_output_roughness:
+
+.. rst-class:: classref-property
+
+``bool`` **output_roughness** = ``true`` :ref:`🔗<class_Terrain3DMaterial_property_output_roughness>`
+
+.. rst-class:: classref-property-setget
+
+- |void| **set_output_roughness_enabled**\ (\ value\: ``bool``\ )
+- ``bool`` **get_output_roughness_enabled**\ (\ )
+
+Enables the Roughness output channel in the shader.
+
+.. rst-class:: classref-item-separator
+
+----
+
+.. _class_Terrain3DMaterial_property_projection_enabled:
+
+.. rst-class:: classref-property
+
+``bool`` **projection_enabled** = ``false`` :ref:`🔗<class_Terrain3DMaterial_property_projection_enabled>`
+
+.. rst-class:: classref-property-setget
+
+- |void| **set_projection_enabled**\ (\ value\: ``bool``\ )
+- ``bool`` **get_projection_enabled**\ (\ )
+
+Enables textures to be projected vertically when placed on slopes above 45 degrees. This is useful for mapping textures on cliff faces without stretching, even though the polygons are stretched.
+
+.. rst-class:: classref-item-separator
+
+----
+
 .. _class_Terrain3DMaterial_property_shader_override:
 
 .. rst-class:: classref-property
@@ -343,7 +509,9 @@ If shader_override_enabled is true and this Shader is valid, the material will u
 - |void| **set_shader_override_enabled**\ (\ value\: ``bool``\ )
 - ``bool`` **is_shader_override_enabled**\ (\ )
 
-Enables use of the :ref:`shader_override<class_Terrain3DMaterial_property_shader_override>` shader code. Generates default code if shader_override is blank.
+Enables using the :ref:`shader_override<class_Terrain3DMaterial_property_shader_override>` shader. An editable shader is generated from the current one if shader_override is blank.
+
+The inspector settings above this group determine the code that is used in the current shader. The settings below are uniforms for the current shader.
 
 .. rst-class:: classref-item-separator
 
@@ -854,11 +1022,9 @@ Set a parameter in the active shader (built-in or override shader).
 
 .. rst-class:: classref-method
 
-|void| **update**\ (\ full\: ``bool`` = false\ ) :ref:`🔗<class_Terrain3DMaterial_method_update>`
-
-Sends all uniform values to the shader again.
+|void| **update**\ (\ flags\: ``int`` = 0\ ) :ref:`🔗<class_Terrain3DMaterial_method_update>`
 
-full - recompiles the shader first.
+Sends uniform values to the shader. See :ref:`UpdateFlags<enum_Terrain3DMaterial_UpdateFlags>` for options.
 
 .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
 .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`

doc/api/class_terrain3dregion.rst

@@ -64,6 +64,8 @@ Methods
    +-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
    | |void|                                        | :ref:`calc_height_range<class_Terrain3DRegion_method_calc_height_range>`\ (\ )                                                                         |
    +-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+   | |void|                                        | :ref:`clear<class_Terrain3DRegion_method_clear>`\ (\ )                                                                                                 |
+   +-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
    | |void|                                        | :ref:`dump<class_Terrain3DRegion_method_dump>`\ (\ verbose\: ``bool`` = false\ ) |const|                                                               |
    +-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
    | :ref:`Terrain3DRegion<class_Terrain3DRegion>` | :ref:`duplicate<class_Terrain3DRegion_method_duplicate>`\ (\ deep\: ``bool`` = false\ )                                                                |
@@ -402,6 +404,18 @@ Recalculates the height range for this region by looking at every pixel in the h
 
 ----
 
+.. _class_Terrain3DRegion_method_clear:
+
+.. rst-class:: classref-method
+
+|void| **clear**\ (\ ) :ref:`🔗<class_Terrain3DRegion_method_clear>`
+
+Unreferences the maps and resets all of the variables to default values.
+
+.. rst-class:: classref-item-separator
+
+----
+
 .. _class_Terrain3DRegion_method_dump:
 
 .. rst-class:: classref-method