Import: Cleanup and optimize etcpak compression method

Avoid unnecessary allocation of temporary buffers for each mip, and creates
only one Image with the compressed data.
Also renames variable and reorders code for clarity.

Clarify that squish is now only used for decompression.

Documented which formats can be decompressed in Image.

9 files changed, 107 insertions, 84 deletions

diff --git a/doc/classes/Image.xml b/doc/classes/Image.xml
index 9d87c9bf9a..91a07f66e0 100644
--- a/doc/classes/Image.xml
+++ b/doc/classes/Image.xml
@@ -186,7 +186,8 @@
 			<return type="int" enum="Error">
 			</return>
 			<description>
-				Decompresses the image if it is compressed. Returns an error if decompress function is not available.
+				Decompresses the image if it is VRAM compressed in a supported format. Returns [constant OK] if the format is supported, otherwise [constant ERR_UNAVAILABLE].
+				[b]Note:[/b] The following formats can be decompressed: DXT, RGTC, BPTC, PVRTC1. The formats ETC1 and ETC2 are not supported.
 			</description>
 		</method>
 		<method name="detect_alpha" qualifiers="const">
diff --git a/modules/etcpak/image_etcpak.cpp b/modules/etcpak/image_compress_etcpak.cpp
index 251d2cd7b0..abc3c26188 100644
--- a/modules/etcpak/image_etcpak.cpp
+++ b/modules/etcpak/image_compress_etcpak.cpp
@@ -1,5 +1,5 @@
 /*************************************************************************/
-/*  image_etcpak.cpp                                                     */
+/*  image_compress_etcpak.cpp                                            */
 /*************************************************************************/
 /*                       This file is part of:                           */
 /*                           GODOT ENGINE                                */
@@ -28,21 +28,16 @@
 /* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                */
 /*************************************************************************/
 
-#include "image_etcpak.h"
+#include "image_compress_etcpak.h"
 
-#include "core/os/copymem.h"
 #include "core/os/os.h"
 #include "core/string/print_string.h"
 
 #include "thirdparty/etcpak/ProcessDxtc.hpp"
 #include "thirdparty/etcpak/ProcessRGB.hpp"
 
-// thresholds for the early compression-mode decision scheme in QuickETC2
-// which can be changed by the option -e
-float ecmd_threshold[3] = { 0.03f, 0.09f, 0.38f };
-
-EtcpakType _determine_etc_type(Image::UsedChannels p_source) {
-	switch (p_source) {
+EtcpakType _determine_etc_type(Image::UsedChannels p_channels) {
+	switch (p_channels) {
 		case Image::USED_CHANNELS_L:
 			return EtcpakType::ETCPAK_TYPE_ETC1;
 		case Image::USED_CHANNELS_LA:
@@ -60,8 +55,8 @@ EtcpakType _determine_etc_type(Image::UsedChannels p_source) {
 	}
 }
 
-EtcpakType _determine_dxt_type(Image::UsedChannels p_source) {
-	switch (p_source) {
+EtcpakType _determine_dxt_type(Image::UsedChannels p_channels) {
+	switch (p_channels) {
 		case Image::USED_CHANNELS_L:
 			return EtcpakType::ETCPAK_TYPE_DXT1;
 		case Image::USED_CHANNELS_LA:
@@ -78,93 +73,112 @@ EtcpakType _determine_dxt_type(Image::UsedChannels p_source) {
 			return EtcpakType::ETCPAK_TYPE_DXT5;
 	}
 }
-void _compress_etc2(Image *p_img, float p_lossy_quality, Image::UsedChannels p_source) {
-	EtcpakType type = _determine_etc_type(p_source);
-	_compress_etcpak(type, p_img, p_lossy_quality, false, p_source);
+
+void _compress_etc1(Image *r_img, float p_lossy_quality) {
+	_compress_etcpak(EtcpakType::ETCPAK_TYPE_ETC1, r_img, p_lossy_quality);
 }
-void _compress_bc(Image *p_img, float p_lossy_quality, Image::UsedChannels p_source) {
-	EtcpakType type = _determine_dxt_type(p_source);
-	_compress_etcpak(type, p_img, p_lossy_quality, false, p_source);
+
+void _compress_etc2(Image *r_img, float p_lossy_quality, Image::UsedChannels p_channels) {
+	EtcpakType type = _determine_etc_type(p_channels);
+	_compress_etcpak(type, r_img, p_lossy_quality);
 }
-void _compress_etc1(Image *p_img, float p_lossy_quality) {
-	_compress_etcpak(EtcpakType::ETCPAK_TYPE_ETC1, p_img, p_lossy_quality, true, Image::USED_CHANNELS_RGB);
+
+void _compress_bc(Image *r_img, float p_lossy_quality, Image::UsedChannels p_channels) {
+	EtcpakType type = _determine_dxt_type(p_channels);
+	_compress_etcpak(type, r_img, p_lossy_quality);
 }
 
-void _compress_etcpak(EtcpakType p_compresstype, Image *p_img, float p_lossy_quality, bool force_etc1_format, Image::UsedChannels p_channels) {
-	uint64_t t = OS::get_singleton()->get_ticks_msec();
-	Image::Format img_format = p_img->get_format();
+void _compress_etcpak(EtcpakType p_compresstype, Image *r_img, float p_lossy_quality) {
+	uint64_t start_time = OS::get_singleton()->get_ticks_msec();
 
+	// TODO: See how to handle lossy quality.
+
+	Image::Format img_format = r_img->get_format();
 	if (img_format >= Image::FORMAT_DXT1) {
-		return; //do not compress, already compressed
+		return; // Do not compress, already compressed.
 	}
-
 	if (img_format > Image::FORMAT_RGBA8) {
 		// TODO: we should be able to handle FORMAT_RGBA4444 and FORMAT_RGBA5551 eventually
 		return;
 	}
 
-	Image::Format format = Image::FORMAT_RGBA8;
-	if (p_img->get_format() != Image::FORMAT_RGBA8) {
-		p_img->convert(Image::FORMAT_RGBA8);
+	// Use RGBA8 to convert.
+	if (img_format != Image::FORMAT_RGBA8) {
+		r_img->convert(Image::FORMAT_RGBA8);
 	}
-	if (p_compresstype == EtcpakType::ETCPAK_TYPE_ETC1 || force_etc1_format) {
-		format = Image::FORMAT_ETC;
+
+	// Determine output format based on Etcpak type.
+	Image::Format target_format = Image::FORMAT_RGBA8;
+	if (p_compresstype == EtcpakType::ETCPAK_TYPE_ETC1) {
+		target_format = Image::FORMAT_ETC;
 	} else if (p_compresstype == EtcpakType::ETCPAK_TYPE_ETC2) {
-		format = Image::FORMAT_ETC2_RGB8;
+		target_format = Image::FORMAT_ETC2_RGB8;
 	} else if (p_compresstype == EtcpakType::ETCPAK_TYPE_ETC2_RA_AS_RG) {
-		format = Image::FORMAT_ETC2_RA_AS_RG;
-		p_img->convert_rg_to_ra_rgba8();
+		target_format = Image::FORMAT_ETC2_RA_AS_RG;
+		r_img->convert_rg_to_ra_rgba8();
 	} else if (p_compresstype == EtcpakType::ETCPAK_TYPE_ETC2_ALPHA) {
-		format = Image::FORMAT_ETC2_RGBA8;
+		target_format = Image::FORMAT_ETC2_RGBA8;
 	} else if (p_compresstype == EtcpakType::ETCPAK_TYPE_DXT1) {
-		format = Image::FORMAT_DXT1;
+		target_format = Image::FORMAT_DXT1;
 	} else if (p_compresstype == EtcpakType::ETCPAK_TYPE_DXT5_RA_AS_RG) {
-		format = Image::FORMAT_DXT5_RA_AS_RG;
-		p_img->convert_rg_to_ra_rgba8();
+		target_format = Image::FORMAT_DXT5_RA_AS_RG;
+		r_img->convert_rg_to_ra_rgba8();
 	} else if (p_compresstype == EtcpakType::ETCPAK_TYPE_DXT5) {
-		format = Image::FORMAT_DXT5;
+		target_format = Image::FORMAT_DXT5;
 	} else {
-		ERR_FAIL();
+		ERR_FAIL_MSG("Invalid or unsupported Etcpak compression format.");
 	}
 
-	const bool mipmap = p_img->has_mipmaps();
-	print_verbose("Encoding format: " + Image::get_format_name(format));
+	// Compress image data and (if required) mipmaps.
+
+	const bool mipmaps = r_img->has_mipmaps();
+	const int width = r_img->get_width();
+	const int height = r_img->get_height();
+	const uint8_t *src_read = r_img->get_data().ptr();
 
-	Ref<Image> new_img;
-	new_img.instance();
-	new_img->create(p_img->get_width(), p_img->get_height(), mipmap, format);
-	Vector<uint8_t> data = new_img->get_data();
-	uint8_t *wr = data.ptrw();
+	print_verbose(vformat("ETCPAK: Encoding image size %dx%d to format %s.", width, height, Image::get_format_name(target_format)));
 
-	Ref<Image> image = p_img->duplicate();
-	int mmc = 1 + (mipmap ? Image::get_image_required_mipmaps(new_img->get_width(), new_img->get_height(), format) : 0);
-	for (int i = 0; i < mmc; i++) {
-		int ofs, size, mip_w, mip_h;
-		new_img->get_mipmap_offset_size_and_dimensions(i, ofs, size, mip_w, mip_h);
+	int dest_size = Image::get_image_data_size(width, height, target_format, mipmaps);
+	Vector<uint8_t> dest_data;
+	dest_data.resize(dest_size);
+	uint8_t *dest_write = dest_data.ptrw();
+
+	int mip_count = mipmaps ? Image::get_image_required_mipmaps(width, height, target_format) : 0;
+
+	for (int i = 0; i < mip_count + 1; i++) {
+		// Get write mip metrics for target image.
+		int mip_w, mip_h;
+		int mip_ofs = Image::get_image_mipmap_offset_and_dimensions(width, height, target_format, i, mip_w, mip_h);
+		// Ensure that mip offset is a multiple of 8 (etcpak expects uint64_t pointer).
+		ERR_FAIL_COND(mip_ofs % 8 != 0);
+		uint64_t *dest_mip_write = (uint64_t *)&dest_write[mip_ofs];
+
+		// Block size. Align stride to multiple of 4 (RGBA8).
 		mip_w = (mip_w + 3) & ~3;
 		mip_h = (mip_h + 3) & ~3;
-		Vector<uint8_t> dst_data;
-		dst_data.resize(size);
-		int mipmap_ofs = image->get_mipmap_offset(i);
-
-		const uint32_t *image_read = (const uint32_t *)&image->get_data().ptr()[mipmap_ofs];
-		uint64_t *dst_write = (uint64_t *)dst_data.ptrw();
-		if (p_compresstype == EtcpakType::ETCPAK_TYPE_ETC1 || force_etc1_format) {
-			CompressEtc1RgbDither(image_read, dst_write, mip_w * mip_h / 16, mip_w);
+		const uint32_t blocks = mip_w * mip_h / 16;
+
+		// Get mip data from source image for reading.
+		int src_mip_ofs = r_img->get_mipmap_offset(i);
+		const uint32_t *src_mip_read = (const uint32_t *)&src_read[src_mip_ofs];
+
+		if (p_compresstype == EtcpakType::ETCPAK_TYPE_ETC1) {
+			CompressEtc1RgbDither(src_mip_read, dest_mip_write, blocks, mip_w);
 		} else if (p_compresstype == EtcpakType::ETCPAK_TYPE_ETC2 || p_compresstype == EtcpakType::ETCPAK_TYPE_ETC2_RA_AS_RG) {
-			CompressEtc2Rgb(image_read, dst_write, mip_w * mip_h / 16, mip_w);
+			CompressEtc2Rgb(src_mip_read, dest_mip_write, blocks, mip_w);
 		} else if (p_compresstype == EtcpakType::ETCPAK_TYPE_ETC2_ALPHA) {
-			CompressEtc2Rgba(image_read, dst_write, mip_w * mip_h / 16, mip_w);
-		} else if (p_compresstype == EtcpakType::ETCPAK_TYPE_DXT5 || p_compresstype == EtcpakType::ETCPAK_TYPE_DXT5_RA_AS_RG) {
-			CompressDxt5(image_read, dst_write, mip_w * mip_h / 16, mip_w);
+			CompressEtc2Rgba(src_mip_read, dest_mip_write, blocks, mip_w);
 		} else if (p_compresstype == EtcpakType::ETCPAK_TYPE_DXT1) {
-			CompressDxt1Dither(image_read, dst_write, mip_w * mip_h / 16, mip_w);
+			CompressDxt1Dither(src_mip_read, dest_mip_write, blocks, mip_w);
+		} else if (p_compresstype == EtcpakType::ETCPAK_TYPE_DXT5 || p_compresstype == EtcpakType::ETCPAK_TYPE_DXT5_RA_AS_RG) {
+			CompressDxt5(src_mip_read, dest_mip_write, blocks, mip_w);
 		} else {
-			ERR_FAIL();
+			ERR_FAIL_MSG("Invalid or unsupported Etcpak compression format.");
 		}
-		copymem(&wr[ofs], dst_data.ptr(), size);
 	}
-	p_img->create(new_img->get_width(), new_img->get_height(), mipmap, format, data);
 
-	print_verbose(vformat("ETCPAK encode took %s ms.", rtos(OS::get_singleton()->get_ticks_msec() - t)));
+	// Replace original image with compressed one.
+	r_img->create(width, height, mipmaps, target_format, dest_data);
+
+	print_verbose(vformat("ETCPAK encode took %s ms.", rtos(OS::get_singleton()->get_ticks_msec() - start_time)));
 }
diff --git a/modules/etcpak/image_etcpak.h b/modules/etcpak/image_compress_etcpak.h
index 0137bab7cc..ccf157fada 100644
--- a/modules/etcpak/image_etcpak.h
+++ b/modules/etcpak/image_compress_etcpak.h
@@ -1,5 +1,5 @@
 /*************************************************************************/
-/*  image_etcpak.h                                                       */
+/*  image_compress_etcpak.h                                              */
 /*************************************************************************/
 /*                       This file is part of:                           */
 /*                           GODOT ENGINE                                */
@@ -28,8 +28,8 @@
 /* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                */
 /*************************************************************************/
 
-#ifndef IMAGE_ETCPAK_H
-#define IMAGE_ETCPAK_H
+#ifndef IMAGE_COMPRESS_ETCPAK_H
+#define IMAGE_COMPRESS_ETCPAK_H
 
 #include "core/io/image.h"
 
@@ -43,9 +43,10 @@ enum class EtcpakType {
 	ETCPAK_TYPE_DXT5_RA_AS_RG,
 };
 
-void _compress_etcpak(EtcpakType p_compresstype, Image *p_img, float p_lossy_quality, bool force_etc1_format, Image::UsedChannels p_channels);
-void _compress_etc1(Image *p_img, float p_lossy_quality);
-void _compress_etc2(Image *p_img, float p_lossy_quality, Image::UsedChannels p_source);
-void _compress_bc(Image *p_img, float p_lossy_quality, Image::UsedChannels p_source);
+void _compress_etc1(Image *r_img, float p_lossy_quality);
+void _compress_etc2(Image *r_img, float p_lossy_quality, Image::UsedChannels p_channels);
+void _compress_bc(Image *r_img, float p_lossy_quality, Image::UsedChannels p_channels);
 
-#endif // IMAGE_ETCPAK_H
+void _compress_etcpak(EtcpakType p_compresstype, Image *r_img, float p_lossy_quality);
+
+#endif // IMAGE_COMPRESS_ETCPAK_H
diff --git a/modules/etcpak/register_types.cpp b/modules/etcpak/register_types.cpp
index fcc0bc8b6f..d57d2f747a 100644
--- a/modules/etcpak/register_types.cpp
+++ b/modules/etcpak/register_types.cpp
@@ -30,7 +30,7 @@
 
 #include "register_types.h"
 
-#include "image_etcpak.h"
+#include "image_compress_etcpak.h"
 
 void register_etcpak_types() {
 	Image::_image_compress_etc1_func = _compress_etc1;
diff --git a/modules/etcpak/register_types.h b/modules/etcpak/register_types.h
index 9b300a3275..a9e10a4aae 100644
--- a/modules/etcpak/register_types.h
+++ b/modules/etcpak/register_types.h
@@ -28,5 +28,10 @@
 /* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                */
 /*************************************************************************/
 
+#ifndef ETCPAK_REGISTER_TYPES_H
+#define ETCPAK_REGISTER_TYPES_H
+
 void register_etcpak_types();
 void unregister_etcpak_types();
+
+#endif // ETCPAK_REGISTER_TYPES_H
diff --git a/modules/squish/image_compress_squish.cpp b/modules/squish/image_decompress_squish.cpp
index fb0c7aba1d..1450b0fe88 100644
--- a/modules/squish/image_compress_squish.cpp
+++ b/modules/squish/image_decompress_squish.cpp
@@ -1,5 +1,5 @@
 /*************************************************************************/
-/*  image_compress_squish.cpp                                            */
+/*  image_decompress_squish.cpp                                          */
 /*************************************************************************/
 /*                       This file is part of:                           */
 /*                           GODOT ENGINE                                */
@@ -28,7 +28,7 @@
 /* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                */
 /*************************************************************************/
 
-#include "image_compress_squish.h"
+#include "image_decompress_squish.h"
 
 #include <squish.h>
 
diff --git a/modules/squish/image_compress_squish.h b/modules/squish/image_decompress_squish.h
index ebc5a41887..fff5839ac4 100644
--- a/modules/squish/image_compress_squish.h
+++ b/modules/squish/image_decompress_squish.h
@@ -1,5 +1,5 @@
 /*************************************************************************/
-/*  image_compress_squish.h                                              */
+/*  image_decompress_squish.h                                            */
 /*************************************************************************/
 /*                       This file is part of:                           */
 /*                           GODOT ENGINE                                */
@@ -28,11 +28,11 @@
 /* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                */
 /*************************************************************************/
 
-#ifndef IMAGE_COMPRESS_SQUISH_H
-#define IMAGE_COMPRESS_SQUISH_H
+#ifndef IMAGE_DECOMPRESS_SQUISH_H
+#define IMAGE_DECOMPRESS_SQUISH_H
 
 #include "core/io/image.h"
 
 void image_decompress_squish(Image *p_image);
 
-#endif // IMAGE_COMPRESS_SQUISH_H
+#endif // IMAGE_DECOMPRESS_SQUISH_H
diff --git a/modules/squish/register_types.cpp b/modules/squish/register_types.cpp
index c51cdc9521..51aab040e7 100644
--- a/modules/squish/register_types.cpp
+++ b/modules/squish/register_types.cpp
@@ -29,7 +29,8 @@
 /*************************************************************************/
 
 #include "register_types.h"
-#include "image_compress_squish.h"
+
+#include "image_decompress_squish.h"
 
 void register_squish_types() {
 	Image::_image_decompress_bc = image_decompress_squish;
diff --git a/thirdparty/README.md b/thirdparty/README.md
index dbdc568d64..9ddeec11f8 100644
--- a/thirdparty/README.md
+++ b/thirdparty/README.md
@@ -101,6 +101,7 @@ Files extracted from upstream source:
   ```
 - `AUTHORS.txt` and `LICENSE.txt`
 
+
 ## fonts
 
 - `NotoSans*.ttf`, `NotoNaskhArabicUI_Regular.ttf`: