Compatibility renderer support

README.md

@@ -7,7 +7,7 @@ A high performance, editable terrain system for Godot 4.
 * Written in C++ as a GDExtension addon, which works with official engine builds
 * Can be accessed by GDScript, C#, and any language Godot supports
 * Geometric Clipmap Mesh Terrain, as used in The Witcher 3. See [System Architecture](https://terrain3d.readthedocs.io/en/stable/docs/system_architecture.html) 
-* Up to 16k x 16k in 1k regions (imagine multiple islands without paying for 16k^2 vram)
+* Terrains as small as 64x64m up to 65.5x65.5km (4295km^2) in variable sized regions
 * Up to 32 textures
 * Up to 10 levels of detail
 * Foliage instancing

doc/api/class_terrain3d.rst

@@ -108,6 +108,8 @@ Methods
    +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
    | :ref:`EditorPlugin<class_EditorPlugin>`             | :ref:`get_plugin<class_Terrain3D_method_get_plugin>`\ (\ ) |const|                                                                                                                                    |
    +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+   | :ref:`bool<class_bool>`                             | :ref:`is_compatibility_mode<class_Terrain3D_method_is_compatibility_mode>`\ (\ ) |const|                                                                                                              |
+   +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
    | |void|                                              | :ref:`set_camera<class_Terrain3D_method_set_camera>`\ (\ camera\: :ref:`Camera3D<class_Camera3D>`\ )                                                                                                  |
    +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
    | |void|                                              | :ref:`set_editor<class_Terrain3D_method_set_editor>`\ (\ editor\: :ref:`Terrain3DEditor<class_Terrain3DEditor>`\ )                                                                                    |
@@ -827,6 +829,18 @@ Returns the EditorPlugin connected to Terrain3D.
 
 ----
 
+.. _class_Terrain3D_method_is_compatibility_mode:
+
+.. rst-class:: classref-method
+
+:ref:`bool<class_bool>` **is_compatibility_mode**\ (\ ) |const| :ref:`🔗<class_Terrain3D_method_is_compatibility_mode>`
+
+Returns true if Terrain3D has detected that the Compatibility renderer is in use.
+
+.. rst-class:: classref-item-separator
+
+----
+
 .. _class_Terrain3D_method_set_camera:
 
 .. rst-class:: classref-method

doc/api/class_terrain3ddata.rst

@@ -282,7 +282,7 @@ Constants
 
 .. rst-class:: classref-constant
 
-**REGION_MAP_SIZE** = ``16`` :ref:`🔗<class_Terrain3DData_constant_REGION_MAP_SIZE>`
+**REGION_MAP_SIZE** = ``32`` :ref:`🔗<class_Terrain3DData_constant_REGION_MAP_SIZE>`
 
 Hard coded number of regions on a side. The total number of regions is this squared.
 
@@ -715,7 +715,7 @@ Returns the calculated region location for the given global position. This is ju
 
 :ref:`PackedInt32Array<class_PackedInt32Array>` **get_region_map**\ (\ ) |const| :ref:`🔗<class_Terrain3DData_method_get_region_map>`
 
-Returns a fully populated 16 x 16 array. The array location contains the region id + 1, or 0, which means no region.
+Returns a fully populated 32 x 32 array. The array location contains the region id + 1, or 0, which means no region.
 
 See :ref:`get_region_map_index<class_Terrain3DData_method_get_region_map_index>`.
 
@@ -731,7 +731,7 @@ See :ref:`get_region_map_index<class_Terrain3DData_method_get_region_map_index>`
 
 Given a region location, returns the index into the region map array. See :ref:`get_region_map<class_Terrain3DData_method_get_region_map>`.
 
-You can use this function to quickly determine if a location is within the greater world bounds (-8,-8) to (7, 7). It returns -1 if not.
+You can use this function to quickly determine if a location is within the greater world bounds (-16,-16) to (15, 15). It returns -1 if not.
 
 .. rst-class:: classref-item-separator
 
@@ -859,7 +859,7 @@ Imports an Image set (Height, Control, Color) into this resource. It does NOT no
 
 \ ``images`` - MapType.TYPE_MAX sized array of Images for Height, Control, Color. Images can be blank or null.
 
-\ ``global_position`` - X,0,Z position on the region map. Valid range is :ref:`Terrain3D.vertex_spacing<class_Terrain3D_property_vertex_spacing>` \* (+/-8192, +/-8192).
+\ ``global_position`` - X,0,Z position on the region map. Valid range is :ref:`Terrain3D.vertex_spacing<class_Terrain3D_property_vertex_spacing>` \* :ref:`Terrain3D.region_size<class_Terrain3D_property_region_size>` \* (+/-16, +/-16).
 
 \ ``offset`` - Add this factor to all height values, can be negative.
 

doc/api/class_terrain3dstorage.rst

@@ -159,7 +159,7 @@ Constants
 
 .. rst-class:: classref-constant
 
-**REGION_MAP_SIZE** = ``16`` :ref:`🔗<class_Terrain3DStorage_constant_REGION_MAP_SIZE>`
+**REGION_MAP_SIZE** = ``32`` :ref:`🔗<class_Terrain3DStorage_constant_REGION_MAP_SIZE>`
 
 .. container:: contribute
 

doc/classes/Terrain3D.xml

@@ -68,6 +68,12 @@
 				Returns the EditorPlugin connected to Terrain3D.
 			</description>
 		</method>
+		<method name="is_compatibility_mode" qualifiers="const">
+			<return type="bool" />
+			<description>
+				Returns true if Terrain3D has detected that the Compatibility renderer is in use.
+			</description>
+		</method>
 		<method name="set_camera">
 			<return type="void" />
 			<param index="0" name="camera" type="Camera3D" />

doc/classes/Terrain3DData.xml

@@ -212,7 +212,7 @@
 		<method name="get_region_map" qualifiers="const">
 			<return type="PackedInt32Array" />
 			<description>
-				Returns a fully populated 16 x 16 array. The array location contains the region id + 1, or 0, which means no region.
+				Returns a fully populated 32 x 32 array. The array location contains the region id + 1, or 0, which means no region.
 				See [method get_region_map_index].
 			</description>
 		</method>
@@ -221,7 +221,7 @@
 			<param index="0" name="region_location" type="Vector2i" />
 			<description>
 				Given a region location, returns the index into the region map array. See [method get_region_map].
-				You can use this function to quickly determine if a location is within the greater world bounds (-8,-8) to (7, 7). It returns -1 if not.
+				You can use this function to quickly determine if a location is within the greater world bounds (-16,-16) to (15, 15). It returns -1 if not.
 			</description>
 		</method>
 		<method name="get_regionp" qualifiers="const">
@@ -297,7 +297,7 @@
 			<description>
 				Imports an Image set (Height, Control, Color) into this resource. It does NOT normalize values to 0-1. You must do that using get_min_max() and adjusting scale and offset.
 				[code skip-lint]images[/code] - MapType.TYPE_MAX sized array of Images for Height, Control, Color. Images can be blank or null.
-				[code skip-lint]global_position[/code] - X,0,Z position on the region map. Valid range is [member Terrain3D.vertex_spacing] * (+/-8192, +/-8192).
+				[code skip-lint]global_position[/code] - X,0,Z position on the region map. Valid range is [member Terrain3D.vertex_spacing] * [member Terrain3D.region_size] * (+/-16, +/-16).
 				[code skip-lint]offset[/code] - Add this factor to all height values, can be negative.
 				[code skip-lint]scale[/code] - Scale all height values by this factor (applied after offset).
 			</description>
@@ -500,7 +500,7 @@
 		<constant name="HEIGHT_FILTER_MINIMUM" value="1" enum="HeightFilter">
 			Samples (1 &lt;&lt; lod) * 2 heights around the given coordinates and returns the lowest.
 		</constant>
-		<constant name="REGION_MAP_SIZE" value="16">
+		<constant name="REGION_MAP_SIZE" value="32">
 			Hard coded number of regions on a side. The total number of regions is this squared.
 		</constant>
 	</constants>

doc/classes/Terrain3DStorage.xml

@@ -53,7 +53,7 @@
 		</constant>
 		<constant name="SIZE_1024" value="1024" enum="RegionSize">
 		</constant>
-		<constant name="REGION_MAP_SIZE" value="16">
+		<constant name="REGION_MAP_SIZE" value="32">
 		</constant>
 	</constants>
 </class>

doc/docs/double_precision.md

@@ -15,7 +15,7 @@ For a more detailed explanation, see [Large World Coordinates](https://docs.godo
 * This feature is experimental and has had only one user give a positive report so far.
 * There are many caveats listed in the link above. You should read them all before beginning this process.
 * You must build Godot and Terrain3D from source.
-* Terrain3D currently only supports a maximum world of 16k by 16k, or (+/-8192, +/-8192). Although with `mesh_vertex_spacing`, you can expand this up to 10x. You can also have Terrain3D located around the origin, then have your own meshes or a shader generated terrain outside of that world. See [Support more region sizes #70](https://github.com/TokisanGames/Terrain3D/issues/77) for supporting worlds up to 90k per side and more.
+* Terrain3D currently supports a maximum world of 65.5x65.5km. Although with `vertex_spacing`, you can expand this up to 10x. You can also have Terrain3D located around the origin, then have your own meshes or a shader generated terrain outside of that world. See [Support more region sizes #70](https://github.com/TokisanGames/Terrain3D/issues/77) for supporting worlds up to 90k per side and more.
 * Shaders do not support double precision. Clayjohn wrote an article demonstrating how to [Emulate Double Precision](https://godotengine.org/article/emulating-double-precision-gpu-render-large-worlds/) in shaders. He wrote that the camera and model transform matrices needed to be emulated to support double precision. This is now done automatically in the engine when building it with double precision. There may be other cases where shaders will need this emulation.
 
 

doc/docs/import_export.md

@@ -18,8 +18,8 @@ Currently importing and exporting is possible via code or our import tool. We wi
 4) Specify the `import_position` of where in the world you want to import. Values are rounded to the nearest `region_size` (defaults to 1024). So a location of (-2000, 1000) will be imported at (-2048, 1024).
 
      Notes:
-     * You can import multiple times into the greater 16k^2 world map by specifying different positions. So you could import multiple maps as separate islands or combined regions.
-     * It will slice and pad odd sized images into region sized chunks ([default is 1024x1024](https://github.com/TokisanGames/Terrain3D/issues/77)). e.g. You could import a 4k x 2k, several 1k x 1ks, and a 5123 x 3769 and position them so they are adjacent.
+     * You can import multiple times into the greater world map by specifying different positions. So you could import multiple maps as separate islands or combined regions.
+     * It will slice and pad odd sized images into region sized chunks (default is 256x256). e.g. You could import a 4k x 2k, several 1k x 1ks, and a 5123 x 3769 and position them so they are adjacent.
      * You can also reimport to the same location to overwrite anything there using individual maps or a complete set of height, control, and/or color.
 
 5) Specify any desired `height_offset` or `import_scale`. The scale gets applied first. (eg. 100, -100 would scale the terrain by 100, then lower the whole terrain by 100).
@@ -86,7 +86,7 @@ We can import any supported image format Godot can read. These include:
 
 Notes:
 
-* The exporter takes the smallest rectangle that will fit around all active regions in the 16k^2 world and export that as an image. So, if you have a 1k x 1k island in the NW corner, and a 2k x 3k island in the center, with a 1k strait between them, the resulting export image will be something like 4k x 5k. You'll need to specify the location (rounded to `region_size`) when reimporting to have a perfect round trip.
+* The exporter takes the smallest rectangle that will fit around all active regions in the world and export that as an image. So, if you have a 1k x 1k island in the NW corner, and a 2k x 3k island in the center, with a 1k strait between them, the resulting export image will be something like 4k x 5k. You'll need to specify the location (rounded to `region_size`) when reimporting to have a perfect round trip.
 
 * The exporter tool does not offer region by region export, but there is an API where you can retrieve any given region, then you can use `Image` to save it externally yourself.
 

doc/docs/installation.md

@@ -24,8 +24,7 @@ Terrain3D is listed in the Asset Library [here](https://godotengine.org/asset-li
 7. In `Project Settings / Plugins`, ensure that Terrain3D is enabled.
 8. Select `Project / Reload Current Project` to restart once more.
 9. Open `demo/Demo.tscn`. You should see a terrain. Run the scene by pressing `F6`. 
-
-**Updated for 0.9.3-dev:** When using Terrain3D in your own scene, select the Terrain3D node in the Scene panel. In the Inspector, click the folder icon to the right of `data directory`, and specify a directory to store your data. This directory can be used shared with other scenes.
+10. When using Terrain3D in your own scene, select the Terrain3D node in the Scene panel. In the Inspector, click the folder icon to the right of `data directory`, then specify a directory to store your data. This directory can be used shared with other scenes.
 
 Next, learn how to [prepare your textures](texture_prep.md).
 
@@ -48,7 +47,7 @@ If the demo isn't working for you, watch the [tutorial videos](tutorial_videos.m
 4. In `Project Settings / Plugins`, ensure that Terrain3D is enabled.
 5. Select `Project / Reload Current Project` to restart once more.
 6. Create or open a 3D scene and add a new Terrain3D node.
-7. **Updated 0.9.3-dev:** Select Terrain3D in the Scene panel. In the Inspector, click the folder icon to the right of `data directory` and specify a directory to store your data. This directory can be used shared with other scenes.
+7. Select Terrain3D in the Scene panel. In the Inspector, click the folder icon to the right of `data directory` and specify a directory to store your data. This directory can be used shared with other scenes.
 
 Next, learn how to [prepare your textures](texture_prep.md).
 
@@ -63,7 +62,7 @@ To update Terrain3D:
 
 Don't just copy the new folder over the old, as this won't remove any files that we may have intentionally removed.
 
-4. Upgrading to 0.9.3, when opening your scene and selecting your Terrain3D node, a directory selection wizard will popup. Terrain3D now stores data in a directory. Follow the popup to select your old storage file and a new storage directory, and it will upgrade your data. Save afterwards.
+4. **Upgrading to 0.9.3:** Terrain3D now stores data in a directory. When opening your scene and selecting your Terrain3D node, a directory selection wizard will popup. Follow the directions to select your old storage file and a new storage directory, and it will upgrade your data. Save afterwards.
 
 ### Upgrade Path
 

doc/docs/platforms.md

@@ -31,7 +31,7 @@ Fully supported. See [renderers](#supported-renderers).
 
 ## macOS
 
-Godot and Terrain3D work fine on macOS, however Apple security is overly aggressive when using the release binaries.
+Godot and Terrain3D work fine on macOS, however Apple security is overly aggressive when using our release binaries.
 
 Users have reported errors like this:
 
@@ -47,7 +47,8 @@ $ xattr -dr com.apple.quarantine addons/terrain_3d/bin/libterrain.macos.release.
 You can also [read comments and workarounds](https://github.com/TokisanGames/Terrain3D/issues/227)
 from other users. 
 
-If disabling Apple security is not working, or if approaching a release date, macOS users should [build from source](building_from_source.md) so you can sign the binaries with your own account.
+If bypassing Apple security is not working, or if approaching a release date, macOS users should [build from source](building_from_source.md) so you can sign the binaries with your own developer account.
+
 
 ## Android
 
@@ -63,6 +64,7 @@ There is a [texture artifact](https://github.com/TokisanGames/Terrain3D/issues/1
 Further reading:
 * [Issue 197](https://github.com/TokisanGames/Terrain3D/issues/197)
 
+
 ## IOS
 
 As of Terrain3D 0.9.1 and Godot 4.2, iOS is reported to work with the following setup:
@@ -100,14 +102,16 @@ The user got it working with the following:
 * Install `glibc` and `linux-api-headers` in addition to the standard Godot dependencies
 * [Build from source](building_from_source.md)
 
-
 Further reading:
 * [Issue 220](https://github.com/TokisanGames/Terrain3D/issues/220#issuecomment-1837552459)
 
 
 ## WebGL
 
-Terrain3D does export to WebGL, however it requires the [Compatibility Renderer (read more)](#compatibility).
+The Terrain3D library can be exported to WebGL, however the terrain will not currently render. It requires the [Compatibility Renderer (read more)](#compatibility), which is now supported, and but there are some additional shader elements that need to be sorted out before it will work. 
+
+Further reading:
+* [Issue 502](https://github.com/TokisanGames/Terrain3D/issues/502)
 
 
 Supported Renderers
@@ -137,12 +141,25 @@ The Forward Vulkan Mobile renderer is fully supported in Terrain3D 0.9.3. There
 
 ## Compatibility
 
-The OpenGLES 3.0 Compatibility renderer has recently reached "feature complete" status in Godot 4.3. Features are still lacking in 4.2.
+The OpenGLES 3.0 Compatibility renderer is supported from Terrain3D 0.9.3 with Godot 4.3. There is partial support for Godot 4.2.
+
+* If using a custom override shader, we add a special COMPATIBILITY_DEFINES block to your shader that will allow certain features to work properly (eg the fma() function). We remove this block from your shader if you switch back to Mobile or Forward. It is normal to receive a shader dump in your console during this transition, but it should not repeat every start, once saved.
+
+* `IS_COMPATIBILITY` is defined in this block should you wish to check against it with your own custom preprocessor statements.
+
+* If enabling compatibility mode on the command line, we cannot detect that currently. You can tell Terrain3D with a special parameter:
+
+    `Godot_v4.3-stable_win64_console.exe --rendering-driver opengl3 -e project.godot --terrain3d-renderer=compatibility`
 
-It is not yet fully supported by Terrain3D. The terrain mesh builds and is reported to work fine. The remaining issue is that the texturing shader and the mouse cursor do not work due to the lack of necessary features.
+**Godot 4.2**
 
-Some work has been done to partially support Compatibility in Godot 4.2 and full support coming in Terrain3D 0.9.4 with Godot 4.3+.
+In addition to the above notes, OpenGLES is incomplete in 4.2. It does work with the following caveats:
 
+* There are some startup warnings about depth textures and glow that you can ignore.
+* `VRAM Compressed` is not supported. In the `Import` panel, you must set your texture files to either `VRAM Uncompressed` or `Lossless` and reimport.
+* The command line option `--rendering-method gl_compatibility` breaks the terrain in 4.2. Don't use it. The above command works for 4.2 or 4.3.
+
 Further reading:
 
 * [Issue 217](https://github.com/TokisanGames/Terrain3D/issues/217)
+* [PR 500](https://github.com/TokisanGames/Terrain3D/pull/500)