Add iOS Support

[directedchaossoftware]

Overview

I am new to Godot and Terrain3D, but have been experimenting. I managed to mostly get iOS working without much trouble, maybe solving 2 of 3 issues/steps, after some setup from building from source instructions.

Steps

1. [Local Fix] Building iOS libraries

scons platform=ios target=template_debug
[...]
scons platform=ios target=template_release

Note: there are some deprecation warnings.

2. [Local Fix] Updating terrain.gdextension:

[...]
ios.debug = "res://addons/terrain_3d/bin/libterrain.ios.debug.universal.dylib"
ios.release = "res://addons/terrain_3d/bin/libterrain.ios.release.universal.dylib"

3. [WIP] Fixing textures

With the first two changes and the normal iOS export templates from the Godot editor, I am seeing a "chess squares" shader issue (as if it had no textures?) actually on device. I have a separate C++ GDExtension moving the character and camera slightly to confirm code is running. Also note shadows and occlusion look to be working.

Other Thoughts

Rendering: This is with Godot Project Settings->General->Renderering->Renderer->Rendering Method options: forward_plus or mobile. gl_compatibility shows an all grey plane, no height at all or squares, which is a different issue.

Exporting: I am not an artist, but one suggestion from that other issue was to investigate the texture exports themselves. I followed Texturing the Terrain, using the highly recommended DDS settings using GIMP-2.10. It renders fine in editor, export to mac and windows.

Architectures: I did this on an M1 Mac and updated to the latest XCode. But I am not sure that matters as it builds universal. arm64 seems to build fine:

scons platform=ios target=template_debug arch=arm64
[...]
scons platform=ios target=template_release arch=arm64

Though the resulting libraries are exactly the same size as the universal libraries. I haven't tried with the App Store either. The mac libraries look to not use architecture, though now I wonder if that would help arm macs.

[directedchaossoftware]

I tried removing all textures but one, painting that and white color everywhere, same result. I also tried
PNG, but I can't get Terrain3D to accept it.

When I try to set it as an Albedo Texture I get this log (error and message):

  ./core/variant/variant_utility.cpp:905 - Terrain3DTexture::_is_texture_valid: Invalid format. Expected channel packed DXT5 RGBA8. See documentation for format.
Set albedo_texture

Similarly for Normal Texture:

  ./core/variant/variant_utility.cpp:905 - Terrain3DTexture::_is_texture_valid: Invalid format. Expected channel packed DXT5 RGBA8. See documentation for format.
Set normal_texture

I see the log line here, which sure enough requires FORMAT_DXT5, but shouldn't it also support FORMAT_RGBA8? I see these values in the path godot-cpp/gen/include/godot_cpp/classes, but I can't actually find that on github now (only a couple classes). But the comment also says "RGBA8" in it.

I have tried exporting from GIMP with and without the Channel Pack approach, and all the same checkboxes marked in the PNG instructions. I selected the same Godot import options as in the instructions, but there are many other settings I may have wrong:

So, I tweaked the check to allow FORMAT_RGBA8 and error to output the format:

	if (format != Image::FORMAT_DXT5 && format != Image::FORMAT_RGBA8) {
		LOG(ERROR, "Invalid format. Expected channel packed DXT5 RGBA8 (or straight RGBA8). See documentation for format.  Actual value=", format);

This finally revealed it was FORMAT_DXT1.

./core/variant/variant_utility.cpp:905 - Terrain3DTexture::_is_texture_valid: Invalid format. Expected channel packed DXT5 RGBA8 (or straight RGBA8). See documentation for format.  Actual value=17

FORMAT_DXT1 = 17

I'm not sure if I'm exporting or importing the PNG incorrectly, or if that would help the iOS issue (and I'm probably misunderstanding a couple other things too).

[directedchaossoftware]

Oh I also tried the demo ground_037 texture. The editor sets it fine, but on export to iOS the same chess board no texture pattern appears.

[TokisanGames]

I can work with PNG just fine with the instructions in the wiki.

I see the log line here, which sure enough requires FORMAT_DXT5, but shouldn't it also support FORMAT_RGBA8?

DDSs exported as we describe are RGBA compressed with DXT5. When you import PNGs into Godot they are not sent directly to the video card typically. Godot converts them to another specified format, such as DXT1 or 5. So no it shouldn't accept plain RGB8. You should tell Godot to import the PNG as VRAM Compressed as stated in the docs. Then it will be converted to DXT5 and be usable.

Do you want us to convert up to 64 4096x4096 textures every time you open a scene in the editor, or run the game or a scene? No, we want to avoid all this extra processing on start. So you do the easy preparation once to convert the textures into the format they will be used in vram. Godot normally does that with every texture.

but I can't actually find that on github now (only a couple classes). But the comment also says "RGBA8" in it.

You are looking in the godot-cpp repository which is only a set of binding classes for the engine. You need to look at the engine code repository to see how it actually works.

So, I tweaked the check to allow FORMAT_RGBA8 and error to output the format:

This isn't the way to go. However having the code tell you the format its in is a good way to go. We need format 19 specifically, which is RGBA compressed as DXT5. 17 is RGB compressed as DXT1. The settings you showed are correct. If the computer says its 17, I believe it. That means you added an RGB image. You need height on the alpha channel.

Oh I also tried the demo ground_037 texture. The editor sets it fine, but on export to iOS the same chess board no texture pattern appears.

The checkboard texture is a 1024x1024 RGBA as DXT5 texture. As is the ground texture. So we know these textures can be read by the shader on ios. If not, then you'd see a completely white or black terrain as the shader is failing, or the texture is. I suspect that the problem lies in the exporting. Either in the settings you have chosen, your process, or a bug in the project exporting portion of the engine is causing the ground dds file to not be included in the export. When Terrain3D loads, if there is no attached texture it is supposed to generate the checkerboard images to fill in.

I can export the demo to windows just fine. Have you tried exporting the demo to mac, both debug and release builds? Make sure the libraries are in the export directory (which should be automatic) or it will crash instantly.

If you can get a console mode on ios, you can enable debug logging and get a lot more information about what is and is not happening.

[directedchaossoftware]

Update: ETC2 ASTC?

Would Project Settings->Rendering->Textures->VRAM Compression->Import ETC2 ASTC: On be an issue? While getting Terrain3D/project to export to iOS (see steps below), I remembered I had to do that (it is a blocking error on the iOS export template for any project). I also got debug logs, and both projects show some of the same logs, related to compression issues.

Terrain3D/project iOS

Import ETC2 ASTC

Logs

USER ERROR: Cannot convert to <-> from compressed formats. Use compress() and decompress() instead.
   at: convert (core/io/image.cpp:521)
USER ERROR: Terrain3DTexture::_is_texture_valid: Invalid format. Expected channel packed DXT5 RGBA8. See documentation for format.
   at: push_error (core/variant/variant_utility.cpp:905)
USER ERROR: Cannot convert to <-> from compressed formats. Use compress() and decompress() instead.
   at: convert (core/io/image.cpp:521)
USER ERROR: Terrain3DTexture::_is_texture_valid: Invalid format. Expected channel packed DXT5 RGBA8. See documentation for format.
   at: push_error (core/variant/variant_utility.cpp:905)
USER ERROR: Cannot convert to <-> from compressed formats. Use compress() and decompress() instead.
   at: convert (core/io/image.cpp:521)
USER ERROR: Terrain3DTexture::_is_texture_valid: Invalid format. Expected channel packed DXT5 RGBA8. See documentation for format.
   at: push_error (core/variant/variant_utility.cpp:905)
USER ERROR: Cannot convert to <-> from compressed formats. Use compress() and decompress() instead.
   at: convert (core/io/image.cpp:521)
USER ERROR: Terrain3DTexture::_is_texture_valid: Invalid format. Expected channel packed DXT5 RGBA8. See documentation for format.
   at: push_error (core/variant/variant_utility.cpp:905)
USER ERROR: Cannot convert to <-> from compressed formats. Use compress() and decompress() instead.
   at: convert (core/io/image.cpp:521)
USER ERROR: Terrain3DTexture::_is_texture_valid: Invalid format. Expected channel packed DXT5 RGBA8. See documentation for format.
   at: push_error (core/variant/variant_utility.cpp:905)
USER ERROR: Cannot convert to <-> from compressed formats. Use compress() and decompress() instead.
   at: convert (core/io/image.cpp:521)
USER ERROR: Terrain3DTexture::_is_texture_valid: Invalid format. Expected channel packed DXT5 RGBA8. See documentation for format.
   at: push_error (core/variant/variant_utility.cpp:905)
USER ERROR: Cannot convert to <-> from compressed formats. Use compress() and decompress() instead.
   at: convert (core/io/image.cpp:521)
USER ERROR: Terrain3DTexture::_is_texture_valid: Invalid format. Expected channel packed DXT5 RGBA8. See documentation for format.
   at: push_error (core/variant/variant_utility.cpp:905)
USER ERROR: Cannot convert to <-> from compressed formats. Use compress() and decompress() instead.
   at: convert (core/io/image.cpp:521)
USER ERROR: Terrain3DTexture::_is_texture_valid: Invalid format. Expected channel packed DXT5 RGBA8. See documentation for format.
   at: push_error (core/variant/variant_utility.cpp:905)
USER ERROR: Condition "!_image_compress_bc_func" is true. Returning: ERR_UNAVAILABLE
   at: compress_from_channels (core/io/image.cpp:2637)
USER ERROR: Condition "!_image_compress_bc_func" is true. Returning: ERR_UNAVAILABLE
   at: compress_from_channels (core/io/image.cpp:2637)
USER ERROR: Condition "!_image_compress_bc_func" is true. Returning: ERR_UNAVAILABLE
   at: compress_from_channels (core/io/image.cpp:2637)
USER ERROR: Condition "!_image_compress_bc_func" is true. Returning: ERR_UNAVAILABLE
   at: compress_from_channels (core/io/image.cpp:2,637)
USER ERROR: Condition "!_image_compress_bc_func" is true. Returning: ERR_UNAVAILABLE
   at: compress_from_channels (core/io/image.cpp:2,637)
USER ERROR: Condition "!_image_compress_bc_func" is true. Returning: ERR_UNAVAILABLE
   at: compress_from_channels (core/io/image.cpp:2637)
USER WARNING: Icon not supported by this display server.
   at: set_icon (servers/display_server.cpp:543)
USER ERROR: Condition "!_image_compress_bc_func" is true. Returning: ERR_UNAVAILABLE
   at: compress_from_channels (core/io/image.cpp:2,637)
USER ERROR: Condition "!_image_compress_bc_func" is true. Returning: ERR_UNAVAILABLE
   at: compress_from_channels (core/io/image.cpp:2,637)
USER WARNING: Icon not supported by this display server.
   at: set_icon (servers/display_server.cpp:543)

Steps:

1. Add iOS export, App Store Team ID, Bundle Identifier (2nd picture)
2. Set Project Settings->Rendering->Textures->VRAM Compression->Import ETC2 ASTC: On (third picture)
3. Add, say, Godot's icon.svg to the project base folder and set Project Settings->Application->Config->Icon: res://icon.svg
4. Follow steps 1 (Building iOS libraries) and 2 (Updating terrain.gdextension:) from the start of this thread
5. Export Project... (and open in XCode, run locally or on device, etc. -- iOS has a lot of setup with profiles, device ids, etc.)

[TokisanGames]

Would Project Settings->Rendering->Textures->VRAM Compression->Import ETC2 ASTC: On be an issue?

Is it an issue on desktop?

I don't know. So far we've only been using DXT5, which is S3TC. The demo textures and generated checkered textures are in this format, 19.

It looks like godot's etc format would be FORMAT_ETC2_RGBA8 = 31

I don't know how to make that format. If you have a png with vram compression, while etc is enabled, that might make that format.

The checkerbox is automatically generated, so it's probably using that format. But ground textures are not.

You'll need to modify our verification check to accept format 31. You should also print out the format to see if the checkers are indeed 31 instead of 19.

Cannot convert to <-> from compressed formats

This means Godot will not convert 19 to 31. We have to uncompress then recompress in the new format. However, the compression/decompression libraries do not exist in the exported versions of Godot. So the textures must be setup for ios from the beginning (probably with png).

Looking through the Godot source for this format it looks like there is a ktx texture format that can hold etc2. This tool can write that format https://developer.imaginationtech.com/pvrtextool/ and a plugin for gimp https://github.com/chriku/gimp-ktx

[directedchaossoftware]

Solved?

I re-added the change to output the texture format and continue regardless, showing the on-device format is 5 (FORMAT_RGBA8) and it runs fine (no texture issue). There may have been some extra loading time (just a feeling, I have not done any profiling - I also saw a lot of warnings). I'm a bit out of my depth with these texture options, but I'm happy to use this approach. That is:

1. Use recommended DDS texture formats from docs
2. Import ETC2 ASTC as required for iOS (Mac still seems to work fine, I'll try Windows again later)
3. The 3 steps mentioned in this thread (see change below)

PR

I went ahead and forked so I could send a PR with these little changes. After something like that (I'm happy to talk more about the better fix or let anyone else, I can just work off this for now) you still need Step 1 (Building iOS libraries -- I am not sure how to contribute those): scons platform=ios

Screenshot

Log

[...]
Terrain3D[...] USER ERROR: Terrain3DTexture::_is_texture_valid: Invalid format. Expected channel packed DXT5 RGBA8 (or straight RGBA8). See documentation for format.  Continuing anyway.  Actual value=5

Change, Solving Step 3

(PR is cleaner and more limited)
Terrain3D/src/terrain_3d_texture.cpp:

	if (format != Image::FORMAT_DXT5) {
		LOG(ERROR, "Invalid format. Expected channel packed DXT5 RGBA8 (or straight RGBA8). See documentation for format.  Continuing anyway.  Actual value=", format);
		//return false;